mirror of
https://github.com/software-mansion/argent.git
synced 2026-09-14 19:27:14 +08:00
feat/flow-script-drop-logs
44 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Ignacy Łątka
|
8dd2621968 |
docs: cut the README to the essentials (#1082)
The README duplicated the docs site - install prerequisites, a Linux emulator tuning essay, the full CLI and editor tables - burying what Argent actually is. 17.4 KB -> 3.5 KB (5.0x), no information lost: everything cut already lives in the docs, now linked. | | Before | After | | --- | --- | --- | | Size | 217 lines / 17404 chars | 43 lines / 3477 chars | | Sections | 9 (incl. a ~4500-char Linux emulator section, CLI table, editors table) | 6 | | Media | header, 3 ads, showcase gif, SWM logo | unchanged | | Legal | Privacy + License | unchanged (License verbatim) | <details> <summary>Where the removed content lives</summary> | Removed | Docs page | | --- | --- | | Prerequisites, Linux emulator tuning, `--local` team install, manual install | [fundamentals/installation](https://docs.swmansion.com/argent/docs/fundamentals/installation) | | Supported platforms table | [fundamentals/supported-platforms](https://docs.swmansion.com/argent/docs/fundamentals/supported-platforms) | | CLI reference table | [reference/cli](https://docs.swmansion.com/argent/docs/reference/cli) | | Supported editors table | [reference/editors](https://docs.swmansion.com/argent/docs/reference/editors) | Verified: `prettier --check` passes; all five outbound links return 200; `LICENSE.txt`, `Telemetry.md` and `assets/showcase.gif` exist at the referenced paths. No docs changes needed - the docs site already covered every removed section. </details> 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01YNGjiLLCf4cg3LXx4SCeUC Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
Mateusz Aliyev
|
6e9e45c9f0 |
feat: attach to devices offered by external providers (#735)
This pull request lets Argent drive a simulator or emulator another process is already running, attaching to its simulator-server rather than spawning a second one. A provider writes a JSON descriptor to `~/.argent/providers/` listing the devices it offers and the mechanisms Argent may use on each. They appear in `list-devices` with an `ext:` id and work with the existing tools. The file is re-read on every call, so a withdrawal or a narrowed grant applies immediately. `ios.additionalDeviceSets` (#600) already makes such a simulator reachable by UDID. What changes is ownership. `boot-device` and `stop-simulator-server` refuse these devices, anything the provider did not grant is refused with a message naming it and Argent uses only the endpoints its own simulator-server build serves. A grant binds to the device rather than to one of its names, so the real udid or serial is gated exactly like the `ext:` id. Android emulators are covered too and a device visible to both a provider and `adb`/`simctl` is listed once. The contract ships as `schemas/device-provider-v1.json`, validated by `argent providers check`, and is documented in `docs/reference/device-providers.mdx`. Includes unit tests and an e2e phase where the harness acts as its own provider. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added support for discovering and connecting to externally managed devices. * Added `argent providers` commands for listing, validating, publishing, withdrawing, and pruning providers. * Added provider-aware simulator, debugger, profiler, native tools, and device listings. * Added capability controls, endpoint validation, revocation handling, and provider-specific diagnostics. * Added automatic CLI discovery for provider integrations. * **Bug Fixes** * Improved service recovery and paused-runtime error reporting. * Improved simulator keyboard and paste command reliability. * **Documentation** * Documented provider descriptors, capabilities, lifecycle rules, and CLI usage. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Sebastian Flajszer
|
1068430b91 |
feat(ios-device): small fixes related with ios-device support (#1031)
Follow-up to #944: the fixes made after the review that did not make the squash. ## What changes - **Signing note**: delivered only to a call whose device argument resolves to a physical iPhone, including `flow-execute`'s `device`, and held (not dropped) across other calls. The label is now `Apple Development (KEYID)`; the certificate CN's Apple ID no longer reaches agent context or logs. - **Flow device resolution**: the no-device-matched refusal names the cabled phone and the exact `device <udid>` / `--device` spelling. A physical iPhone is never picked automatically. - **`gesture-swipe`**: the description states the hardware semantics (edge gesture needs `fromX` 0, `durationMs` sets drag speed, `momentum:false` does not damp). - **Skills**: `argent-ios-simulator-setup` skips `kind: "device"` entries; `argent-ios-device-setup` and `-interact` state the runner build timing, the full list of tools that do not exist on hardware, the backgrounded-target behaviour of each read tool, `actionButton` only on models that have one, and the swipe and `open-url` rules; the flow, Metro and profiler skills each carry one line on physical-iPhone limits. - **Docs**: `physical-ios-devices`, `flows`, `flow-yaml` and `tools` corrected to match the behaviour above; README platform row; runner `PROTOCOL.md`. ## Verification - tool-server suite 400 files / 5173 tests, `tsc`, lint, prettier and the docs build clean. - Live re-check against 0.23.0 on three simulators and a physical iPhone 15: no regression; the note lands once on the first phone call with no e-mail address, and flow auto-detection is byte-identical to 0.23.0 with 0, 1 and 3 simulators booted. |
||
|
Sebastian Flajszer
|
1e69c90981 |
feat(ios-device): add physical iOS support (#944)
# Physical iOS device support Try it now (cabled iPhone, unlocked, Developer Mode on): ```bash argent run list-devices # copy the 25-char UDID argent run launch-app --udid <UDID> --bundleId com.apple.Preferences ``` First launch builds and signs the on-device runner: 3 to 5 minutes, keep the phone unlocked. Every later start: seconds, from cache. No signing setup needed if an Apple ID is signed into Xcode; the team is detected from the keychain. ## What this adds - Physical iPhone support, on by default: a cabled iPhone simply appears in `list-devices`. iPhone-only: physical iPads are skipped at discovery. - 15 tools ported to hardware. Flows replay on device. - Zero-config signing from the keychain; `ARGENT_IOS_TEAM_ID` is an override, nothing is persisted. - Self-contained npm install: the runner's Swift sources ship in the package. New package `@argent/ios-device-runner` (an XCUITest bundle hosting an HTTP command server on the device), new tool-server backend under `src/utils/ios-device/`. - The one always-on cost: `list-devices` on macOS now runs physical discovery in parallel with the other platform probes, under the existing 8s devicectl timeout; off-macOS it early-returns. ## Suggested review order Rough estimate: half a day for the full pass. 1. `packages/ios-device-runner/PROTOCOL.md`, then `README.md` (wire contract and reliability model, ~15 min) 2. `packages/tool-server/src/utils/ios-device/` (devicectl, usbmux, team-detect, runner-build, runner-commands: the core) 3. `packages/tool-server/src/blueprints/ios-device-runner.ts` (service lifecycle, crash recovery) 4. Per-tool device arms and the capability gates (`ios-physical-device-classification.test.ts` is the ratchet) 5. Docs page, the two new skills, the Swift runner sources ## Requirements 1. macOS host with full Xcode (iOS platform installed); uses `xcrun devicectl` and `xcodebuild`. 2. An Apple ID signed into Xcode; automatic signing mints the runner's provisioning profile. 3. USB cable only. Wi-Fi is deliberately unsupported: the transport is usbmux, and a Wi-Fi-only device lists as `paired`, not `connected`. 4. iPhone paired with and trusting the Mac, Developer Mode on, A12/2018 or newer (modern 8+16-hex UDID, the CoreDevice floor). Legacy 40-hex UDIDs are not classified as iOS. 5. Signing resolves as: `ARGENT_IOS_TEAM_ID` in the tool-server's environment (explicit override, CI) -> keychain detection (newest identity first, memoized per server run, never persisted). One certificate: nothing to do. Several teams: newest wins; the first tool result names the pick, the runner-ups, and the override. No certificate: the error walks through Xcode > Settings > Accounts and Manage Certificates > + > Apple Development, then retry; it never names the env var, since a team id alone cannot sign. Bundle ids derive per team (`com.argent.runner.t<teamid>`). `ARGENT_IOS_RUNNER_PROJECT` overrides the project path for unusual layouts. Build artifacts cache under `~/.argent/ios-device-runner`, keyed by runner sources, Xcode/SDK version, and signing. A team with no registered devices self-heals: the failed generic build retries against the connected phone, which registers it. ## How it works 1. `xcrun devicectl` (CoreDevice) is the control plane: discovery, readiness, app lifecycle. Readiness gates on the wired transport, so an unplugged phone is refused before any build starts. 2. A signed XCUITest runner is built lazily with the resolved team, started via `xcodebuild test-without-building`, and parks as an HTTP command server for 24h. On an npm install the Xcode project is the copy shipped inside the package. 3. The listener binds to the device's loopback interface; the host reaches it over usbmuxd with a dependency-free `node:net` client. 4. Mutating commands are journaled by `commandId`; a lost reply is resolved by asking `status` for the journaled fate, never by replay (at-most-once delivery). 5. Routing hangs off `resolveDevice` UDID-shape classification plus a per-tool capability allowlist. CLI and MCP layers are untouched; outside tool-server, docs, and the runner package the diff is failure-code constants (registry), two agent skills plus rule updates (skills), the pack step (packages/argent), and the e2e smoke script. ## Supported tools | Tool | Status | Notes | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | launch-app | Supported | Plain `devicectl` launch. System UI (SpringBoard/Spotlight) registers a session only; no launch attempt. Carries a note when signing is not resolvable yet. | | restart-app | Supported | System UI bundle ids rejected before any device contact. | | reinstall-app | Supported | Same system UI pre-flight. | | screenshot | Supported | Served through the runner; device-wide, needs no registered app. (No host-side devicectl screenshot exists on any toolchain; that dead route was removed.) | | describe | Supported | AX tree snapshot via the runner. Snapshots the session app's process, so another process's dialogs are not in the tree. A backgrounded session app fails with an actionable error instead of being silently re-fronted. Focus polling is off for this source; typing uses a fixed settle. | | keyboard | Supported | Types into the focused element; typing with nothing focused is refused with "tap the text field first". `enter` and `backspace` are the named keys (both exist as software-keyboard characters; there is no per-keycode HID surface on hardware). Whitespace-only keys rejected, not silently "typed". | | gesture-tap | Supported | `clickCount > 1` dispatches as one native multi-tap gesture, not separate taps. | | gesture-swipe | Supported | Single-finger drag between two points. | | gesture-custom | Supported | Two shapes only: press-hold and straight single-finger drag. Second finger or `Move` waypoints rejected with authoring guidance, before any runner starts. | | button | Supported | `home`, `volumeUp`, `volumeDown`, `actionButton` (volume buttons are simulator-unavailable in the SDK, not device-unavailable). `power`/`appSwitch` have no public XCUIDevice API and reject before device contact; a button the model lacks gets a typed refusal via `hasHardwareButton`. | | await-ui-element | Supported | Polls the same runner snapshot describe returns; waits and taps see identical frames. Degrades to `cause: "unreadable"` with a note on a backgrounded app, never a raw throw. | | await-screen-idle | Supported | Same describe path; resolves not-settled instead of throwing, so a follow-up screenshot still runs. | | run-sequence | Supported | Outer gate only; each step pre-flights its own capability. | | open-url | Supported | devicectl launches the receiving app with the URL as its launch payload. http(s) defaults to Safari; any other scheme needs the new optional `bundleId` param (hardware cannot resolve a scheme's handler system-wide). | | screenshot-diff | Supported | Live captures through the runner (full-resolution, device-wide, no registered app needed); the diff itself runs on the host. Baselines are per device model/resolution; `rotation` is ignored on hardware. | Flows run through these tools; the device flow tree gets the same `subtreeText` hoisting as every other platform, so container-scoped `text` asserts work. ## Not supported (400 at the capability gate) 1. gesture-pinch, gesture-rotate: no two-finger coordinate API on hardware. Pinch/rotate flow directives also fail upfront with a clear error. 2. screen-recording-start/stop (video): simulator-only capture pipeline. 3. rotate, paste, shake, settings-permissions: simulator-only backends, not ported (paste also hits the iOS 16+ cross-app paste permission prompt). 4. native-devtools, debugger, profiler families: simulator-side instrumentation (DYLD injection does not exist on hardware). 5. Physical iPads: filtered at discovery for now. A test ratchet (`ios-physical-device-classification.test.ts`) keeps `apple.device` declarations in sync with the ported list. ## Core contracts 1. Observation never mutates the screen: a backgrounded session app makes `describe`/`await-*` fail with an error naming the three ways out (screenshot, launch-app, or launch-app com.apple.springboard). Mutating commands do re-front, and their result carries `reactivated: true`. 2. The runner listener is unauthenticated; mitigation is the loopback-only bind. 3. `list-devices` states: `connected` (cabled now, usable) vs `paired` (unreachable, never auto-bound). Wired transport alone decides; a Wi-Fi-migrated CoreDevice tunnel does not count. 4. The multi-team signing pick rides the first affected tool result as a one-shot note (the pre-existing notes channel). The `list-devices` result shape is unchanged from main: devices and avds, nothing else. 5. Rejections are typed 400 validation errors end to end, so a batch flow run skips one failing flow instead of aborting. Also: the runner is a first-class device-owned service (`stop-simulator-server` and `stop-all-simulator-servers` reap it, detached xcodebuild child included; a crashed runner respawns on the next call). A passcode-locked phone refuses launches; the devicectl 10002 hint also covers a pending system prompt on an unlocked phone. Build failures surface xcodebuild's own `error:` lines with signing hints (no registered devices, free-team app-id cap, missing provisioning, the `errSecInternalComponent` partition-list fix). An app XCTest reports as `.unknown` (a swipe-killed foreign app) is refused with launch-app guidance. Status-bar pinning is skipped on hardware; pixel-settle masks the top band. ## Testing - Unit coverage, hardware-independent: UDID classification and capability routing; usbmux framing and transport; devicectl list/hints parsing incl. the silent iPhone-only filter; keychain detection against real certificate fixtures; runner build/cache self-heals (poisoned cache, concurrent checkout, fresh-team retry); crash/journal recovery; the backgrounded-observation and reactivated contracts; keyboard guards incl. the not-focused refusal; system-UI pre-flight; per-tool device arms. - Manual smoke on a real device: `scripts/e2e-ios-physical-device.mjs`. ## Docs and skills 1. `features/physical-ios-devices.mdx`: the user-facing walkthrough (zero-config signing with the sign-in fallback, prerequisites, app-scoped model, troubleshooting). 2. `fundamentals/supported-platforms.mdx`: physical iPhones in the platform matrix (iPads not supported yet). 3. `reference/tools.mdx` and `reference/configuration.mdx`: list-devices states and the `ARGENT_IOS_TEAM_ID` override. 4. Two skills ship with the package via `argent init`: `argent-ios-device-setup` (setup ladder plus a troubleshooting table keyed to real error texts) and `argent-ios-device-interact` (the app-scoped hardware contract, supported subset with alternatives, gesture recipes, pitfalls). The agent rule and sibling skills route to them. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added experimental USB-connected physical iPhone support. * Physical iPhones now support discovery, app lifecycle actions, URL opening, accessibility snapshots, screenshots, taps, swipes, custom gestures, keyboard input, waits, flows, and screenshot comparisons. * Added automatic signing-team detection with optional `ARGENT_IOS_TEAM_ID` configuration. * Added clear handling for paired or unavailable devices and unsupported hardware actions. * **Documentation** * Added setup, troubleshooting, capability, and physical-device usage guidance. * Clarified that physical iPads and several simulator-only tools and gestures remain unsupported. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
filip131311
|
9489a220b0 |
chore(argent): declare the Node version the package actually needs (#653)
Fixes #640. ```json "engines": { "node": ">=20.12.0" } ``` ## Why 20.12.0 and not 20 My first answer was `>=20` — CI's lowest tested line, satisfied by every runtime dependency, and the version the issue reporter (and I) installed successfully. **It is wrong**, and shipping it would have told npm it is safe to install onto runtimes where the CLI cannot execute a single line. The mistake was looking at first-party `src/`. The published artifacts are four esbuild bundles with their dependencies **inlined**, and that is where the real floor lives. Confirmed in `packages/argent/dist/`: | blocker | added in | consequence below it | |---|---|---| | `import { styleText } from "node:util"` (via inlined `@clack/*`, in `installer.mjs` and `cli-cmds.mjs`) | **20.12.0** | a **link-time** `SyntaxError` — `argent init` and every CLI subcommand fail to load | | `import.meta.dirname` at module scope (`bundled-paths.js`, `cli.js`) | 20.11.0 | `TypeError` during module init | So 20.12.0 is the lowest version on which the package actually loads. It is also the lowest line CI exercises (7 workflows pin Node 20), and it satisfies every runtime dependency's own constraint (`@fails-components/webtransport` `>=20`, `@modelcontextprotocol/sdk` `>=18`). `electron`'s `>=22.12.0` does **not** apply — it is an `optionalDependency`, and npm does not engine-check those. Verified: installing `0.18.0` on Node 20.19.5 produces no `EBADENGINE` at all and electron is never materialized. I did not go to `>=22` on EOL grounds: it would refuse a runtime seven CI workflows still test and that users demonstrably run. ## Docs corrected alongside - `README.md` said **20.11** — one minor below where the package can load. - `CONTRIBUTING.md` said **Node.js 18+** — predates what the repo's own lint toolchain needs (`eslint@10` requires `^20.19.0 || ^22.13.0 || >=24`). `packages/argent/README.md` is generated by `scripts/sync-readme.cjs` on `prepack`, so it follows automatically and is deliberately untouched. ## What a reviewer should know **Enforcement is package-manager-dependent**, which matters because `argent init` installs with whichever PM the project uses: | | behaviour on too-old Node | |---|---| | npm (default) | `npm warn EBADENGINE` — installs anyway | | npm + `engine-strict=true` | hard error, install aborts | | **yarn 1.x** | **hard error by default** | | **pnpm** | **silently ignores it** | So this achieves the issue's "warn" but only conditionally its "refuse". There is no `.npmrc` in the repo, so contributors are unaffected either way. **Nothing in the repo validates `engines`** — `repo-hygiene`, `check-workspace-versions.mjs` and `pack-mcp.cjs` all ignore unknown manifest keys, and `next-canary-version.mjs` round-trips the manifest through `JSON.parse`/`stringify`, which preserves the new field and stays prettier-clean. **One inconsistency I did not resolve:** `packages/argent/scripts/bundle-tools.cjs:383` builds with `target: "node22"`, which now sits above the declared floor. In practice the node20→node22 syntax gap is negligible (tsc targets ES2022 and I found no post-20 *syntax*), so I left the shipped artifact alone rather than change build output in a manifest-only PR — but it should either be lowered to match or consciously kept. Your call. ## Separate bug found while verifying this `ios-remote` is broken on the **entire Node 20 line**, independent of this change: the inlined `@moq/*` client uses `Promise.withResolvers` (Node 22+) ungated — 6 occurrences in `dist/tool-server.cjs`, reached from `utils/moq-client.ts` via the simulator-server blueprint. Reproduced on Node 20.19.5: `TypeError: Promise.withResolvers is not a function`. I deliberately did **not** raise the floor to `>=22` to paper over it — that would refuse Node 20 for every user to hide one broken path. `moq-client.ts` already has an `ensurePolyfill()` that polyfills `WebSocket`/`WebTransport`; this belongs there. Filed separately. 🤖 Generated with [Claude Code](https://claude.com/claude-code) |
||
|
filip131311
|
f1331cf80d |
fix(installer): unbreak pnpm local installs + stop self-fulfilling editor detection (#501)
## Problem Field report (pnpm setup): `npx @swmansion/argent init --local` - ✅ "updated argent 14→15", ✅ created `.mcp.json` + `skills-lock.json` - 🔴 did **not** add argent to `package.json` - 🔴 re-running the same command → `Local install failed.` + advice to run `pnpm add -D ...` manually - 🔴 init "persistently detects" Cursor and Codex on a fresh machine that never had them ## Root causes (each reproduced; confirmed against installer telemetry) 1. **Stale-binary hijack** — bare `npx @swmansion/argent` prefers an existing **global install** over the registry. A global 0.14 predates `--local` and `parseInitArgs` silently ignored unknown flags, so run 1 was a plain global-mode 0.14 init: it offered the 14→15 update, wrote mcp/skills files, and never touched package.json. That's symptoms 1–3 in one. 2. **pm detection missed pnpm's modern markers** — `pnpm init` (pnpm 10/11) writes only `devEngines.packageManager`, and no lockfile exists before the first install. Detection fell back to npm, whose own devEngines gate instantly rejects the install (`EBADDEVENGINES`, ~250 ms). This is the 221–537 ms `INSTALL_LOCAL_PACKAGE_FAILED` cluster in PostHog (8 events / 7 users last week). 3. **Missing pm binary** (cloned pnpm repo, machine has only npm) surfaced as raw `spawn pnpm ENOENT` plus manual advice that fails identically in the user's shell. 4. **Self-fulfilling detection** — Cursor/Codex `detect()` keyed on bare `~/.cursor` / `~/.codex` dirs, which argent itself creates (an `init -y` with nothing detected configures *all* editors; allowlist/skills writes too). Telemetry also shows a ~19 s failure shape where an identical manual retry succeeds (transient registry / pnpm first-run state errors). ## Fixes - **Init flag parsing stays lenient**: unknown flags remain silently ignored — aborting on them could break existing scripts/setups that pass flags an installed version doesn't know. The parser now also accepts the `--from=path` spelling, ignores a dangling `--from`, and keeps first-`--from`-wins semantics. The stale-binary hijack is addressed on the docs side (`@latest` in the README) rather than by a hard abort. - **`detectProjectPackageManager`** honors `devEngines.packageManager` (object + array forms) and `pnpm-workspace.yaml` — the latter ranked *below* real lockfiles so a stray file left by a pnpm→yarn migration can't outrank `yarn.lock`. - **Missing-binary failures** name the real problem ("This project uses pnpm, but the pnpm command was not found on PATH" + corepack hint). Windows detected via cmd.exe's "is not recognized" text, since `shell: true` never ENOENTs there. Other pm failures **retry once**. - **Editor detection requires real evidence**: a `.cursor`/`.codex` dir counts only if it holds something beyond argent's own artifacts (argent mcp.json entry, `permissions.json` allowlist, managed `developer_instructions`, bundled rules/agents/skills). Corrupt, unparseable, or empty content conservatively counts as user evidence. The stale-config sweep now scans **all** adapters so dead entries in no-longer-detected dirs still get pruned. - **README**: recommend `npx @swmansion/argent@latest init` and a `pnpm dlx` alternative (npm's devEngines gate blocks the *outer* npx in fresh pnpm-init projects). ## Testing - Live-tested a packed tgz under the exact repro conditions: fresh pnpm-init project A/B (published 0.15.0 fails EBADDEVENGINES in ~250 ms; this branch installs the devDependency correctly), missing-pnpm message, flag-parsing edges (`--from=` spelling, dangling `--from`), retry-on-transient-failure (flaky pm shim), detection flips (argent-only dirs incl. permissions.json → not detected; `argv.json`/`sessions/`/corrupt configs → detected), plus regressions: npm project local init, global-mode `init -y`, recovery of the broken post-0.14 state. - High-effort multi-agent code review of the diff surfaced 10 confirmed defects in the first iteration (permissions.json not whitelisted, corrupt configs misclassified as argent-only, pnpm-workspace.yaml outranking yarn.lock, `--from=` rejected, Windows ENOENT never firing, stale-sweep interaction, …) — all fixed and re-verified. - 493 argent-installer + 87 registry unit tests green (new suites for flag parsing, devEngines/workspace detection, detection evidence). 🤖 Generated with [Claude Code](https://claude.com/claude-code) |
||
|
Ignacy Łątka
|
3f2680788d |
fix(cli): print help for init/update/uninstall instead of running them (#460)
## The bug `argent <cmd> --help` for the installer subcommands `init` / `install` / `update` / `uninstall` / `remove` did not print help — it ran the real, side-effecting command. `argent uninstall --help` even opened the destructive "Remove argent configuration from this workspace?" prompt (with Yes pre-selected). Root cause: `main()` in `packages/argent/src/cli.ts` dispatched these subcommands and forwarded `rest` (including `--help`) to the installer functions, which have no help handling. Only the top-level `--help` case called `printHelp()`. ## The fix Intercept `--help`/`-h` for exactly the installer command set before dispatching, and print a short per-subcommand usage block without loading or invoking any installer code (no network, no wizard, no prompt). - New side-effect-free module `packages/argent/src/installer-help.ts` exports the pure decision function `installerHelpRequested(command, rest)` plus `printInstallerHelp(command)`. - `cli.ts` calls the guard at the top of `main()` and returns early when help is requested. - The other subcommands (`run`, `tools`, `server`, `link`, `flags`, `enable`, `disable`, `telemetry`) already handle `--help` themselves, so they are deliberately excluded — `argent run <tool> --help` still prints that tool's flags. ## Verification - `npm run build` (root tsc) + `npm run build -w @swmansion/argent` — green. - Ran the built CLI end-to-end (stdin from /dev/null): `init --help`, `update --help`, `uninstall --help`, `install --help`, `remove --help`, `uninstall -h` all print usage and exit 0 with no wizard/network/prompt. - Regression: `argent --help` still prints top-level help; `argent run --help` still prints the `run` usage (not intercepted). - Added unit tests in `packages/argent/test/installer-help.test.ts` for `installerHelpRequested` / `isInstallerCommand` (8 tests, all pass). - `prettier` and `eslint` clean on the touched files; test typecheck passes. Fixes #451 |
||
|
filip131311
|
7bd017a796 |
feat(installer): committable repo-local (--local) install mode (#428)
## Summary Adds an opt-in **committable / repo-local** install mode so a team can version Argent _with the repo_. `argent init --local` installs `@swmansion/argent` as a project **devDependency** and writes MCP configs that launch the project-local copy — so after `git clone && npm install`, every teammate has the same Argent version and MCP wiring with **no global install and no per-developer `argent init`**. **Global mode stays the default** and is unchanged; everything here is additive and backward-compatible. Motivation: the workflow some users already do by hand (#207). Supersedes the earlier, since-closed #232 — this version is Windows-safe (`node`, not the `.bin` shim), handles Yarn PnP, and closes the cross-install tool-server hazards rather than leaving them. ## What changed **`init`** - `--local` / `--global` flags + an interactive "How should argent be installed?" prompt. Mutually exclusive; non-interactive (`--yes`) defaults to **global**. - Local mode installs the devDependency with the package manager detected from the project's **lockfile** (run with `cwd = projectRoot`). - MCP entry points at the local copy: `node node_modules/@swmansion/argent/dist/cli.js mcp` (the bin path is derived from the installed `package.json` `bin` and existence-checked — forward slashes, committable, Windows-safe). Yarn PnP → `yarn argent mcp`; an `npx --no-install argent mcp` fallback is used only when the bin can't be resolved. - Records the mode in a committed `<root>/.argent/install.json`. - Drops global-only adapters (Windsurf/Hermes) in local mode; prints team-setup / commit guidance. **`update`** — detects the project's mode; in local mode reads the installed version from `node_modules` (not the global binary / npx cache) and bumps the **devDependency + lockfile**, then re-emits the local MCP command. **`uninstall`** — scoped to the project's mode: a local-mode uninstall removes the **local devDependency only and never the shared global install**, and prunes `.argent/install.json`. Global-mode behavior is unchanged. **Cross-install hardening (the gate that makes per-project pinning safe)** - `launcher`: a tool-server is reused only when its `bundlePath` matches the caller's — a repo-local pin never silently runs against (or kills) a different version's server. - `postinstall`: only stops a tool-server spawned from *this package's own* bundle, so a devDependency install can't tear down an unrelated editor session. **Telemetry** — adds an `install_mode` dimension to init/update/uninstall events. ## Testing - New unit tests: install-mode helpers + record (`utils`), mode-aware `getMcpEntry`/`resolveLocalCommandMode` incl. the opencode array form (`mcp-configs`), local-only uninstall guard (`uninstall`), and bundlePath-gated tool-server reuse (`launcher`). - All existing suites green (installer 346, tools-client 115, telemetry 191, registry 83, argent 13, tool-server 1621). Build + lint clean. - **Live end-to-end** in an isolated sandbox: `init --local` → real MCP stdio handshake serves **69 tools from `node_modules`**; `update --local` reads the local version; `uninstall --local` removes the local install and **leaves the global install intact**; `init --global` unchanged; flag conflict rejected. ## Notes / known limitations - Recommended on mainstream platforms (macOS, Linux x64, Windows x64) with prebuilt native binaries; Linux arm64 / Windows arm need a C/C++ toolchain to build `tree-sitter` on `npm install` (documented in the README). - Concurrent sessions of two *different* Argent versions on one machine each spawn their own tool-server; an orphaned one idle-times-out (no session is ever broken). 🤖 Generated with [Claude Code](https://claude.com/claude-code) |
||
|
Hubert Gancarczyk
|
3393d22edd |
feat(telemetry): derive distinct_id from a stable host fingerprint (#444)
## Summary Replaces the random-UUID telemetry `distinct_id` with a stable per-machine id derived from the host fingerprint, so PostHog's native "Unique users" counts machines (funnels / retention / breakdowns work with no HogQL). Every Argent entry point - installer, CLI, tool-server, MCP - derives the id from one shared code path, so a given machine reports a single identity across every event and across install / uninstall / reinstall. ## What changed - `distinct_id = uuidv5(hostFingerprint, NAMESPACE)`, where the fingerprint comes from `simulator-server fingerprint`. Deterministic, keeps the UUID shape, and never stores the raw hardware value in PostHog (only the SHA-1-derived UUID leaves the process). - The fingerprint is resolved in `buildPayload` - the single `capture()` path shared by every entry point - so installer / CLI / tool-server / MCP all produce the same id. Resolved lazily, once per process, memoized. - One-time, local-only migration: the first time a fingerprint resolves, `~/.argent/telemetry-id` is rewritten from the legacy random UUID to the derived id. No PostHog `alias` / `$identify` event is emitted. - Fallback: if the fingerprint can't be resolved (unsupported platform, binary absent), the stored or a fresh random UUID is used - identically for every entry point on that machine, self-healing to the derived id on the next successful resolve. - Hardening: never throws; the fingerprint is validated (exactly 64 hex, case-insensitive) before hashing; corrupt / empty / unreadable id files self-heal; the binary is spawned at most once per process. ## Why the id is stable across install -> uninstall -> reinstall Uninstall deletes `~/.argent/telemetry-id`. Because the id is `uuidv5(fingerprint)` and the fingerprint is deterministic per machine, a fresh install recomputes the identical id. Previously only the tool-server resolved the fingerprint while the installer emitted under a random UUID, so this cycle produced a different random id each time. ## Bundling note for reviewers `@argent/telemetry` now depends on `@argent/native-devtools-ios` to locate the binary. That package computes its bin dir from `__dirname` at module load, which is undefined in an ES module. The installer / CLI / MCP ship as ESM bundles, so `bundle-tools.cjs`'s ESM banner is extended to shim `__dirname` / `__filename` (the CJS tool-server bundle already has them natively). Without this shim those bundles would crash on load, so the banner change is load-bearing. ## Testing - Unit: 219 telemetry tests - RFC 4122 v5 vectors, migration, idempotency, case/length validation, corrupt-file self-heal, spawn-at-most-once, and all fallbacks. - E2E on a real machine + booted iPhone 16 Pro: installer, CLI, and tool-server runtimes all emit the same derived id; the id is stable across a delete/recreate (uninstall/reinstall) cycle; a legacy v4 id migrates locally with no alias/identify emitted; verified from an ESM bundle placed in the real install's `dist/` so the binary resolves via the bundled `__dirname` with no env override; tool calls against the device carry the same id. |
||
|
Ignacy Łątka
|
cbced9aa4b |
docs(readme): cover TV, Fire TV, Electron/web platforms and new CLI commands (#461)
The README still described Argent as an iOS-Simulator / Android-Emulator tool, missing the platforms and commands we've shipped since. Cross-referenced the copy against the actual code (device classifier, capability matrix, MCP tool registry, CLI dispatch, and editor adapters) and brought it up to date. ## What changed **Tagline & new "Supported platforms" table** — Argent now advertises what it actually drives: - iOS Simulators (touch) - Android emulators **and physical devices** over adb (touch) - **TV**: Apple TV (tvOS), Android TV / Google TV, Amazon Fire TV / Vega (D-pad remote) - **Desktop & web**: Electron and Chromium apps incl. React Native Web / Expo web, over CDP (mouse) **Capabilities** — expanded to reflect shipped features that weren't mentioned: - Record & replay flows - Visual regression (screenshot diff with OCR/font-aware comparison) - Richer profiling story (React DevTools / Hermes fibers, native Instruments + Perfetto, cross-correlated commit-vs-hang reports) - Network capture (JS `fetch` + native), JS evaluation, native UIKit / React component tree inspection - Desktop & web control (tabs, cookies, storage, DOM, network over CDP) **Prerequisites** — added tvOS (Xcode), Android TV (SDK), Fire TV (Vega SDK) and Electron/Chromium (`--remote-debugging-port`) notes. **CLI Reference** — added the six commands present in code but missing from the table: `tools`, `run`, `server`, `lens`, `link`, `unlink`. **Supported Editors** — corrected Zed to note its global config path (`~/.config/zed/settings.json`) alongside the project path. ## Notes - Physical iOS devices and physical Fire TV hardware are declared in the capability types but aren't drivable today, so they're intentionally left out. (A physically-connected Fire TV can be surfaced by `list-devices` discovery via `classifyKind()`, but it isn't bootable and the shape-based resolver in `device-info.ts` routes every `amazon-` serial through the VVD gate.) - Remote iOS simulators (`ios-remote` via `sim-remote`) are omitted from the platform table to keep it focused on the common targets. |
||
|
Ignacy Łątka
|
b4ecfde05b |
feat(installer): add Kiro CLI MCP support (#410)
Fixes #408 ## Summary Adds first-class support for the [Kiro CLI](https://kiro.dev/cli/) to `argent init` / `update` / `uninstall`, so the Argent MCP server is registered for Kiro alongside the other supported editors. The new `kiroAdapter` follows the same `McpConfigAdapter` contract as every other editor, so it automatically flows through the existing init wizard, the `update` re-sync (only for users who opted Kiro in), and the uninstall sweep. ## What it does Per Kiro's [MCP configuration docs](https://kiro.dev/docs/mcp/configuration/): - **Config paths** — `.kiro/settings/mcp.json` (workspace) and `~/.kiro/settings/mcp.json` (user/global). - **Format** — writes the documented `mcpServers` shape: ```json { "mcpServers": { "argent": { "command": "argent", "args": ["mcp"] } } } ``` - **Auto-approve** — opting into the allowlist sets `"autoApprove": ["*"]` on the `argent` entry (Kiro's documented "approve all tools" syntax), scope-aware for project vs. global. - **Detection** — `detect()` is true when a `.kiro` dir exists in the project or home dir; `.kiro` is also added to the project-root markers so `resolveProjectRoot` treats a Kiro workspace as a project root. ## Scope MCP-only, matching editors like Windsurf/Zed/Hermes that don't get rules/agents copied. Kiro's steering files are a separate mechanism and out of scope for this MCP-config request. ## Testing - `vitest run` for `@argent/installer` — **299 passed** (12 new Kiro adapter tests: write/remove/detect/allowlist round-trips, scope handling, server preservation). The generic `ALL_ADAPTERS` portability/env/uninstall sweeps now also cover Kiro. - Typecheck (`tsc --noEmit`) on src + tests, ESLint (`--max-warnings 0`), and Prettier all clean. - End-to-end against the **compiled** `dist` artifact: drove `init.ts`'s exact `getMcpEntry → write → addAllowlist` sequence into a temp project and confirmed `.kiro/settings/mcp.json` is produced with the format above (including `autoApprove: ["*"]`), and that `remove()` prunes it. --- ## End-to-end verification against the real Kiro CLI The docs were not taken on faith — the actual `kiro-cli` was installed and the integration validated against the real binary and the open-source upstream. **Reconciled a real risk first:** the **Kiro CLI** (kiro.dev/cli/) is the rebranded **Amazon Q Developer CLI**, documented separately from the Kiro IDE. Confirmed both read the **same** config paths this adapter targets — `<root>/.kiro/settings/mcp.json` (workspace) and `~/.kiro/settings/mcp.json` (global) — via the CLI-specific docs, multiple web sources, the CLI's own `mcp --scope {workspace,global}` flags, and the pre-existing `~/.kiro/settings/mcp.json` on the test machine. **Verified, autonomously:** - **`argent mcp` is a working MCP stdio server** — completed an `initialize` + `tools/list` handshake: `serverInfo {name: "argent", version: "0.12.1"}`, **69 tools** (incl. `screenshot`, `list-devices`). This is exactly the `command`/`args` the adapter writes. - **Installed the real Kiro CLI** (`kiro-cli 2.9.0`) via the official installer and wrote the workspace config through the **compiled adapter** (`dist/`), producing the expected `{ mcpServers: { argent: { command, args, autoApprove } } }`. - **Config-schema compatibility, proven authoritatively.** The CLI's server-config struct (`CustomToolConfig`, upstream + confirmed in the 2.9.0 binary) recognizes `command/args/env/timeout/disabled` — our `command`/`args`/`env` map exactly. It has **no `deny_unknown_fields`** (that serde attribute lives only on the *agent* config), so the extra **`autoApprove` is silently ignored by the CLI** — it cannot break loading. Since the file is shared with the Kiro IDE, `autoApprove: ["*"]` is honored there and harmless here. **Could not exercise (no credentials):** every `kiro-cli mcp` subcommand and `chat` is gated behind `kiro-cli login` (Kiro/AWS auth). So the final authenticated leg — `kiro-cli chat` spawning `argent mcp` and listing/invoking a tool live — was **not** run. Every link up to that boundary is verified; the remaining step is mechanical given a logged-in session. |
||
|
Hubert Gancarczyk
|
8483fe23f9 |
feat: add telemetry (#274)
## Summary Adds anonymous, opt-out telemetry for Argent installer, update/uninstall flows, CLI telemetry controls, tool-server lifecycle, and tool invocation health signals. ## What Changed - Added a new private `@argent/telemetry` package - Introduced typed telemetry events with runtime property allowlisting/sanitization. - Added lazy anonymous identity creation in `~/.argent/telemetry-id`. - Added consent handling via: `argent telemetry enable`, `argent telemetry disable`, `argent telemetry status` - Added local debug logging with `ARGENT_TELEMETRY_DEBUG=1`. - Tracks installer funnel events for init, global install/update decisions, editor selection, allowlist decisions, skill installation, rules/agents copy, update, and uninstall. - Tracks tool-server start/stop and tool invocation/complete/fail events. - Adds per-tool invocation IDs so request metadata can be correlated without relying on ordering. - Records only coarse platform metadata (`ios` / `android`) for device tools - Ensures short-lived commands drain telemetry with bounded shutdown before exit. - Wires telemetry package into bundling and injects full Argent CLI version metadata at build time. - Added central `FAILURE_CODES` and `FailureSignal` helpers in `@argent/registry`. - Attached structured, sanitized failure metadata across registry errors, tool-server tools/services, HTTP validation/dependency gates, installer flows, and `argent run`. - Added telemetry allowlisting for safe failure fields only: static error codes/stages, coarse area/kind/command, bounded exit codes, allowlisted signals/spawn codes, and coarse network failure classes. - Split CLI-local `argent run` failures into `cli:run_fail` so they are not double-counted as tool failures. - Added installer telemetry for failed package actions, update/uninstall failures, rules/agents copy results, and skill refresh results. - Made telemetry consent writes atomic and kept telemetry status side-effect free via `peekAnonId()`. - Adds a coarse, anonymous signal to tool telemetry: which AI coding tool is driving the MCP server (Claude Code, Codex, Cursor, Gemini, VS Code, Windsurf, Zed, opencode, Copilot, or other). ## Tests Added / Updated - Telemetry unit coverage for consent precedence, identity creation, base props, sanitization, PostHog config, debug logging, shutdown, opt-out, and forget behavior. - Registry/tool-server tests for invocation IDs, platform metadata boundaries, startup failure flushing, and tool lifecycle telemetry. - Installer tests for final telemetry drain, update action classification, and uninstall identity cleanup ordering. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
Ignacy Łątka
|
8634b6042a |
docs(readme): correct Node version floor and editor config paths (#376)
While verifying the README's setup instructions against the actual code, I found a few factual inaccuracies. All changes are README-only. ### Fixes - **Node version floor: 18 → 20.11.** The README's prerequisites claim "Node.js 18 or later", but the CLI relies on `import.meta.dirname` (added in Node 20.11) in its very entry path — `packages/argent/src/cli.ts`, `packages/argent/src/bundled-paths.ts`, `packages/argent-installer/src/utils.ts`. On Node 18 that property is `undefined`, so `argent` throws at startup before any command runs. CI only exercises Node 20 and 24, and there is no `engines` field. - **Windsurf config path.** Was `.windsurf/mcp.json`; the adapter actually writes `~/.codeium/windsurf/mcp_config.json` (global only) — `packages/argent-installer/src/mcp-configs.ts:342-355`. - **Codex config path.** Was `.codex/config.yaml`; it is `.codex/config.toml` (project) or `~/.codex/config.toml` (global) — `packages/argent-installer/src/mcp-configs.ts:577-592`. - **Hermes adapter was missing** from the Supported Editors table. It writes `~/.hermes/config.yaml` (global only) and is part of `ALL_ADAPTERS` — `packages/argent-installer/src/mcp-configs.ts:682-695`. ### Scope notes - Left the "auto-detects your editor" wording as-is — detection is real; the user only confirms the detected set. - Did not expand the iOS-Simulator/Android-Emulator positioning to mention physical devices / Chromium support — that's a scoping choice, not an inaccuracy. Opened as draft. |
||
|
Paweł Małecki
|
07335efa87 |
docs: add dynamic banner serving to readme (#318)
Adds dynamic banner serving to the readme, server-side content swaps update banner without repo changes. Banners are currently hidden. |
||
|
Ignacy Łątka
|
80661fad8f |
feat: Linux support (#249)
This PR makes Linux work.
# AI Summary
<details>
Brings Argent up on Linux as a host: per-platform npm bundle, renderer
selection that actually works on hybrid-GPU / Wayland / containerized
Linux, hot-boot guarding that survives the SwiftShader composite gap, a
real Linux preflight, and a Wayland-headless E2E job in CI. macOS stays
on
the path it was on before (no `-gpu` flag was passed; AVD config
decided);
nothing about the iOS Simulator behavior changes.
The diff is broader than "ship the Linux artifact" — calling it out
below
because several pieces affect macOS too and reviewers should be primed
for
that rather than skim past expecting "just packaging."
### What's actually in here
**npm packaging (the original framing — still load-bearing)**
| File | Change |
|---|---|
| `packages/argent/scripts/argent-simulator-server.cjs` (new) | Node
dispatcher exposed as the `argent-simulator-server` bin entry. Joins
`process.platform` into the bin path and execs. Forwards
SIGTERM/SIGINT/SIGHUP parent→child so non-TTY supervisors can't orphan
the binary. |
| `packages/argent/scripts/bundle-tools.cjs` | Copies per-platform
binaries from `packages/native-devtools-ios/bin/<platform>/` into
`packages/argent/bin/<platform>/`. darwin required, linux best-effort. |
| `packages/argent/package.json` | `bin.argent-simulator-server` points
at the dispatcher. |
| `packages/native-devtools-ios/src/index.ts` | Resolver joins
`process.platform` into the simulator-server bin path. iOS-only dylibs
and `ax-service` throw `"requires a macOS host"` on Linux callers so
they get the root cause, not "file not found". |
| `scripts/download-simulator-server.sh` | Downloads
`simulator-server-argent-{macos,linux}` into platform-keyed subdirs.
**Purges each platform dir before its download attempt** so a failed
download can't leave stale binaries in place from a prior run. |
| `scripts/dev.cjs` | Local dev copies the current host's binary into
`bin/<process.platform>/` to match the resolver layout. |
| `.github/workflows/publish{,-next}.yml` | Replaces single `test -x
darwin/...` with a per-platform inventory loop. darwin always required;
Linux gated by `ARGENT_REQUIRE_LINUX_BINARY=1` (flip once radon#118
lands). |
**Linux runtime — emulator boot path**
| File | Change |
|---|---|
| `packages/tool-server/src/tools/devices/boot-device.ts` |
`selectGpuMode()`: Linux defaults to `-gpu swiftshader` (`auto` lands on
lavapipe with ~10× cold-boot slowdown; `-gpu host` produces silent
black-window failures on Optimus / NVIDIA+libglvnd / Wayland-on-hybrid /
containers). macOS keeps `auto` (ANGLE→Metal).
`ARGENT_EMULATOR_GPU_MODE` overrides, **validated against `emulator
-help-gpu`'s whitelist** so a typoed value fails fast instead of burning
the whole boot budget. `ARGENT_EMULATOR_NO_WINDOW=1` appends
`-no-window` for headless contexts (CI / containers / Wayland sessions
with no Qt wayland plugin). |
| `packages/tool-server/src/tools/devices/boot-device.ts` (cont.) |
**Cold-boot:** `awaitFirstRealFrame` polls SwiftShader's lockscreen
composite (PNG byte-count via `screencap -p`); blocks `booted:true`
until a real frame shows up. Without this, callers chaining `boot-device
→ screenshot` get an all-black PNG because `sys.boot_completed=1` fires
5–60 s before the first composite. |
| `packages/tool-server/src/tools/devices/boot-device.ts` (cont.) |
**Hot-boot:** `assertScreencapAlive` polls within an 8 s budget instead
of single-probing. The earlier single-probe caught the sticky-blank
state but also killed the emulator on every transient snapshot-restore
blank, forcing "every boot is cold" cycles. Sticky vs transient is
discriminated by whether the budget exhausts. |
| `packages/tool-server/src/utils/linux-preflight.ts` (new) |
`linuxBootDiagnostics()` checks `/dev/kvm` access. `diagnoseAvdSizing()`
warns when a target AVD's `hw.ramSize`/`vm.heapSize` is below the floor
an aggressive RN/Expo app needs (2G/228M avdmanager defaults wedge under
load). |
| `packages/tool-server/src/utils/android-binary.ts` |
`defaultAndroidRoots()` probes typical SDK install locations when
`ANDROID_HOME`/`ANDROID_SDK_ROOT` are unset — **cross-platform**,
benefits macOS launches from GUI-launched MCP hosts (Claude Code Desktop
etc.) where shell rc env doesn't propagate. |
**Cross-platform fixes that landed alongside**
| File | Change |
|---|---|
| `packages/argent-installer/src/utils.ts` | `getLatestVersion()` now
redirects `npm view`'s stderr to `ignore` so `EBADDEVENGINES` warnings
from a consumer project's `package.json` (e.g. Bluesky's pnpm pin) don't
leak to the user's terminal. **Cross-platform fix**, not Linux-specific.
|
**CI**
| File | Change |
|---|---|
| `.github/workflows/wayland-e2e.yml` (new) | Boots an AVD through the
tool-server under headless Weston; asserts `hw.gpu.mode = swiftshader`
and that screenshots + gesture-tap work without a display. Currently
runs on `pull_request` for the affected paths + `workflow_dispatch`.
Pinned to `radon-daily` for the simulator-server until radon#118 ships a
Linux asset to `radon-main`. |
### Tests added in this PR
- `packages/argent/test/dispatcher.test.ts` — e2e against tmpdir-staged
dispatcher + fake `<platform>/simulator-server`: missing-binary error
path, exit-code passthrough, argv passthrough, SIGTERM forwarding.
- `packages/tool-server/test/native-devtools-ios-resolver.test.ts` —
`requireDarwin` gates for dylibs and `ax-service` on Linux, per-platform
`simulator-server` path resolution, missing-binary error,
`ARGENT_NATIVE_DEVTOOLS_DIR` override.
- `packages/tool-server/test/linux-preflight.test.ts` — KVM diagnostic
shape + `diagnoseAvdSizing` (ram low, heap low, both, neither, missing
keys).
- `packages/tool-server/test/boot-device-hotboot.test.ts` — extended
with `it.each([linux→swiftshader, darwin→auto])` so a single CI runner
exercises both GPU branches (was runner-platform-dependent, regressions
could pass on both runners individually). New cases for the wedged-frame
fallback (under fake timers because the polling budget is short but
real-time enough to exceed vitest's 5 s default), the GPU-mode whitelist
rejection, and the cold-boot composite-wait timeout.
- `packages/tool-server/test/android-binary.test.ts` — extended for
`defaultAndroidRoots` probe ordering and HOME pinning.
### Verification
- `tsc --build`: clean apart from pre-existing
`@argent/native-devtools-android` import errors unrelated to this
branch.
- `vitest run` in `packages/tool-server` and `packages/argent`: 689 + 11
= 700 tests passing; the 4 pre-existing test-file load failures
(native-devtools-android missing) reproduce on `main` and are out of
scope.
- `npm pack -w @swmansion/argent`: produces `swmansion-argent-0.8.0.tgz`
with the per-platform layout.
- Wayland-e2e: triggered on this branch — link will be in a PR comment
once the run completes.
- Manually verified end-to-end on a Wayland-on-hybrid-GPU developer
laptop: AVD boots through the tool-server with `-gpu swiftshader`,
screencap returns real frames, gesture tools work.
### Dependencies / what still gates this
- **radon#118** must land before the Linux artifact ships through the
default channel. The download script tolerates the asset being absent
today (best-effort), so this PR is technically safe to merge before —
Linux installs just won't get a working `simulator-server` until the
upstream artifact is published. Once it lands:
- Drop the `radon-daily` arg in `.github/workflows/wayland-e2e.yml`.
- Flip `ARGENT_REQUIRE_LINUX_BINARY` to `1` in both publish workflows.
- **wayland-e2e is not a required status check** today (no branch
protection on `main` requires it). Worth turning on before merging
anything else that touches the Linux boot path.
### Related
- radon#118 — produces the `simulator-server-argent-linux` artifact this
PR consumes.
- argent-private#11 — cross-builds the iOS Simulator dylibs on Linux.
Strictly orthogonal: those dylibs are macOS-runtime-only regardless of
where they're built, and this PR keeps them under `dylibs/` with a clean
error path on Linux callers.
</details>
Fixes #246
|
||
|
Ignacy Łątka
|
c5c3f7af11 |
feat: feature flags (#260)
## Summary
- New top-level CLI commands `argent enable <flag>` / `argent disable
<flag>` / `argent flags`.
- Storage is a small JSON file at `~/.argent/flags.json` by default;
`--scope project` writes to `<project-root>/.argent/flags.json` instead.
- `enable` writes `true`. `disable` removes the entry at the chosen
scope (and deletes the file + empty `.argent/` when it becomes the last
flag).
- `isFlagEnabled` walks project → global, so a project entry shadows the
same key in the global file. To opt a single project out of a
globally-enabled flag, hand-edit `<project>/.argent/flags.json` to
`{"flags":{"name":false}}` — there is no CLI for an explicit override.
- The dispatcher routes the new commands to `@argent/cli` exports;
bundling needs no config changes (only `node:fs|path|os`).
## Behaviour
- `argent enable foo` → writes `{ "flags": { "foo": true } }` to global
file.
- `argent disable foo` → removes `foo` from the global file (clean round
trip with `enable`).
- `argent enable foo --scope project` → writes to
`<project-root>/.argent/flags.json`.
- `argent flags` → lists effective state with the winning scope;
`--json` for scripting.
- Project root is the nearest ancestor with `.argent`, `.git`, or
`package.json` — falls back to cwd when none found.
- POSIX `--` separator: `argent enable -- weird-name` is supported.
- Help (`--help` / `-h`), invalid `--scope`, invalid flag names, missing
arg, unknown flags all produce a clear stderr error and `exit 2`.
- Flag-name validation: `/^[a-zA-Z][a-zA-Z0-9._-]*$/`.
- Writes are atomic (tmp file + rename) so concurrent invocations cannot
tear the JSON.
## Reader API
`isFlagEnabled(name)` is exported from `@argent/cli` for future
consumers; it walks project → global and returns `false` when unset.
## Files
- `packages/argent-cli/src/flags.ts` (new) — storage + CLI handlers
- `packages/argent-cli/src/index.ts` — re-exports `enable` / `disable` /
`flags` / `isFlagEnabled` / `FlagScope`
- `packages/argent-cli/test/flags.test.ts` (new) — 41 tests
- `packages/argent-cli/vitest.config.ts` (new)
- `packages/argent-cli/package.json` — description bump
- `packages/argent/src/cli.ts` — dispatcher routes + help text
- `README.md`, `CONTRIBUTING.md` — command tables
## Test plan
- [x] `npm test --workspaces --if-present` → 1085 tests pass (41 in
`@argent/cli`).
- [x] `npm run typecheck:tests --workspaces --if-present` → clean.
- [x] `npm run build` (root `tsc --build`) → clean.
- [x] `npm run build -w @swmansion/argent` (dispatcher + esbuild
bundles) → clean.
- [x] `npx prettier --check .` → clean.
- [x] End-to-end against the built dispatcher in a tmpdir:
- `argent enable my-feature-flag` (global) writes to
`~/.argent/flags.json`.
- `argent enable proj-only --scope project` writes to
`<proj>/.argent/flags.json`.
- `argent disable my-feature-flag` removes the entry; round trip leaves
a clean tree (file + empty `.argent/` removed when no other state lives
there).
- `argent disable foo` preserves sibling flags in the same file.
- `argent flags` lists each flag with the winning scope.
- `argent enable --` errors cleanly; `argent enable -- name-after`
accepts the literal.
- `argent enable foo --scope project` walks up to `.git` /
`package.json` / `.argent`; stray editor configs (`.claude`, `.cursor`,
…) do NOT count as project roots.
- Error paths (`--scope bogus`, no name, `1bad-name`) exit `2` with a
clear message.
|
||
|
Ignacy Łątka
|
95d2ffa0e4 |
fix(skills): remove iOS bias from skill/tool docs (#212)
We've had multiple instances of iOS-biased references in our skills. This PR makes these references platform-agnostic. <details> ## Summary After Android emulator support landed (#148), several skill docs and tool descriptions still treated iOS as the only/default platform. A QA reported that asking the agent to "test … using argent" makes it spin up an iOS simulator even when an Android emulator is already running. These are **minimal de-biasing edits** — mostly one-word `simulator` → `device` swaps. Android is **not** promoted above iOS; the incidental iOS bias is just removed where it was unnecessary. Genuinely iOS-only tools (`paste`, `native-*`, `native-profiler-*`) are left untouched since the capability gate already rejects them on Android. ## Changes (14 files, +43/-29) - **`argent.md` rule**: one-line `PLATFORM DETECTION` note (call `list-devices` first, don't default to iOS); `simulator actions` → `device actions`; mention `adb` next to `xcrun` in the escape-hatch bullet. Routing order unchanged (iOS still listed first). - **Skill docs**: `native iOS app navigation` → `app navigation`; `simulator` → `device` where the action is platform-neutral; added the missing `argent-android-emulator-setup` row to the RN-workflow Related Skills table; `argent-ios-simulator-setup` description scoped to iOS. - **`flow-run` / `flow-start-recording`**: `simulator interactions` → `device interactions`. - **`network-logs` / `network-request`**: `device_id` description `iOS Simulator UDID` → `Device UDID`. - **`list-devices`**: merged result now sorts by readiness so a booted Android emulator is not buried beneath idle iOS simulators (the only logic change). ## Test plan - [x] `npx tsc --build` clean - [x] `@argent/tool-server` 478 tests pass; `@argent/mcp` 51; `@argent/installer` 231; `@argent/registry` 57 - [x] `prettier --check` clean - [ ] Sanity-check that an agent with only an Android emulator booted no longer reaches for an iOS simulator </details> |
||
|
Ignacy Łątka
|
d017ba340c |
feat: Android emulator support (#148)
### For reviewers - what to focus on: The diff is ~6k LoC; this breakdown should help triage where to spend attention: | Bucket | Lines | Effort | | --- | --- | --- | | **Net-new Android logic**: `boot-device.ts` (660) + `adb.ts` (399) + `uiautomator-parser.ts` (292) | 1351 | **Read carefully** | | Blueprint `DeviceInfo` refactor: `simulator-server`, `ax-service`, `native-devtools` | 365 | Read | | Tool `index.ts` / `types.ts` sprawl across ~20 tools (capability gates, `services()`, descriptions) | ~965 | Skim — watch for cross-file consistency | | `platforms/android.ts` impls (stub → real implementation) | ~426 | Skim | | Skill/docs prose, profiler rename ripple | ~1000 | Skim | | **`platforms/ios.ts` deletions** — 12 files, 0 additions; logic moved into unified handlers | 684 | **Skip — mechanical** | ## What works, what doesn't: ### Just works thanks to either sim server or metro: - `gesture-*` - `button`, `keyboard` - `screenshot` - `run-sequence`, `flow-*` - `debugger-*` - `react-profiler-*` ### Adjusted to work on android too: | tool | android | ios | | --- | --- | --- | | `describe` | `uiautomator dump` → `DescribeNode` | `AXServiceApi` | | `launch-app` | `cmd package resolve-activity` + `am start -W` | `simctl launch` | | `restart-app` | `cmd package resolve-activity` + `am force-stop` + `am start -W` | `simctl terminate` + `simctl launch` | | `reinstall-app` | `adb install -r` (+`-g`/`-d`) | `simctl uninstall` + `simctl install` | | `open-url` | `am start -a VIEW -d <url>` | `simctl openurl` | | `list-devices` | `adb devices` + `emulator -list-avds` | `xcrun simctl list --json` | | `boot-device` | snapshot probe → `-force-snapshot-load` hot boot with screencap-alive guard, falls back to cold boot on any failure | `simctl boot` + `bootstatus -b` | ### Will not work on android for now: - `native-devtools-*` (7 total) - `native-profiler-*` (3 total — was `ios-profiler-*`) - `profiler-stack-query`, `profiler-combined-report` (depend on `native-profiler-*`) - `paste` — unregistered on both platforms for now. --------- Co-authored-by: Paweł Fornagiel <pawel.fornagiel2@gmail.com> |
||
|
Kacper Kapuściak
|
4d826ca01c |
chore: update header image in README.md (#176)
Due to popular vote here's an Argent branded banner in the readme <img width="993" height="597" alt="image" src="https://github.com/user-attachments/assets/30b62430-3888-4e50-a3c7-eb84fef6cad8" /> |
||
|
Kacper Kapuściak
|
72e0d4d6fd |
chore: update banner image in README (#169)
Updated the README banner to be Software Mansion branded <img width="955" height="594" alt="image" src="https://github.com/user-attachments/assets/eb57abd2-2870-483a-9719-447ebbdea30b" /> |
||
|
Ignacy Łątka
|
26da07d371 |
feat: add MCP config adapter for opencode (#152)
This PR adds MCP config adapter for OpenCode At one point OpenCode worked presumably because it read `.claude` or some other config (i've had like 13 of them on my machine). That doesn't seem to be the case anymore. before|after ---|--- <img width="508" alt="image" src="https://github.com/user-attachments/assets/615d07f6-aa92-49a4-b159-92d6b292d2c7" />|<img width="510" alt="image" src="https://github.com/user-attachments/assets/4dabcd1a-d920-4979-9e9e-31e45b12d1c2" /> <img width="400" alt="image" src="https://github.com/user-attachments/assets/8853ddf4-0001-4874-81b7-d2a88d3b6956" />|<img width="400" alt="image" src="https://github.com/user-attachments/assets/048928bf-7c59-4ac0-8483-04cc3b3edcda" /> --------- Co-authored-by: Filip131311 <contact@filipkaminski.com> |
||
|
Ignacy Łątka
|
c060348d8f | Update README.md (#147) | ||
|
Ignacy Łątka
|
47801ddaec |
docs: add privacy footer to README (#146)
* docs: add privacy footer to README * Apply suggestion from @latekvo * style: prettier |
||
|
Paweł Fornagiel
|
a048a4b930 |
docs: make README images link to argent website on click (#140)
Made-with: Cursor |
||
|
Paweł Fornagiel
|
82418eeb92 |
feat: AXService daemon, describe tool native-devtools path, and submodule bump (#98)
* feat: first implementation integration of ax-service for enhanced accessibility support * feat: enhance ax-service with automation enablement and daemon management * feat: export ensureAutomationEnabled function for improved accessibility automation in simulator server * feat: add new build scripts for native development and update binary files * feat: enhance describe tool to support native-devtools fallback and introduce DescribeResult interface * chore: bump version to 0.4.1 * chore: bump argent-private to main; list ax-service in LICENSE - Point packages/argent-private at current main and set submodule branch. - Declare packages/native-devtools-ios/bin/ax-service as proprietary alongside simulator-server and dylibs. Made-with: Cursor * docs: document ax-service as proprietary across LICENSE and README - Extend root README and CONTRIBUTING requirements (mcp README syncs from root at build). - List bin/ax-service in @swmansion/argent and native-devtools-ios LICENSE. - Assert ax-service is present and executable in publish workflow. Made-with: Cursor --------- Co-authored-by: Filip131311 <Filip.kaminski@swmansion.com> |
||
|
Paweł Fornagiel
|
eb2d9222b9 | fix: update LICENSE link in README.md | ||
|
Paweł Fornagiel
|
04819fd4fc |
chore: update README banner with dark/light mode support and new assets (#97)
* chore: update README to improve branding and layout * chore: update README to include responsive banner images and fix minor text typo * chore: update README to enhance banner image responsiveness and adjust layout * feat: adjust banner image display * feat: merge changes * fix: update README with absolute image URLs and correct text typo; add new banner images |
||
|
pFornagiel
|
869786bdfe | chore: fix readme img links | ||
|
Paweł Fornagiel
|
cacf0d3f1b |
chore: update README files for production release (#85)
* feat: update README and MCP documentation with new capabilities and installation instructions; add banner and placeholder images. * chore: remove outdated badge section from README files in root and MCP packages * chore: add horizontal rule to README files in root and MCP packages for improved visual separation * chore: update README files in root and MCP packages to include detailed information about Software Mansion and its services * chore: update logo links in README files for root and MCP packages to reflect new branding * chore: update banner image to align with new branding * chore: update installation command in README to reflect correct usage * chore: replace placeholder image in README files with a GIF for improved visual appeal * chore: update placeholder GIF to enhance visual consistency across assets * chore: adjust image width in README files for consistent presentation * chore: reposition placeholder GIF in README files for improved layout consistency * chore: update installation command in README files to ensure consistency across documentation * chore: update README files to use absolute image URLs and synchronize content between root and MCP README * chore: remove MCP README.md file and update .gitignore to track README.md * chore: update README.md for clarity and consistency in naming conventions |
||
|
Paweł Fornagiel
|
167ccf409d |
fix: move simulator-server binary to native-devtools-ios and fix esbuild bundling (#82)
* chore: update simulator-server path references across documentation and scripts * feat: add native-devtools-ios entry to bundle-tools script |
||
|
Filip131311
|
4e514c1435 | chore: rename package from @software-mansion/argent to @swmansion/argent | ||
|
Filip131311
|
0253a2e641 | chore: add Apache 2.0 license files and mixed-license notices for proprietary binaries | ||
|
pFornagiel
|
d1b6a7cfb4 | chore: remove Pro license requirements from README and argent rules documentation | ||
|
Paweł Fornagiel
|
60eaf83979 |
chore: clean up repository docs and deprecated files (#64)
* docs: update installation guide to streamline setup process and add local tarball installation instructions * docs: remove INSTALL.md and RELEASING.md, update CONTRIBUTING.md to streamline release process, and adjust README.md to reflect changes * chore: remove unused agentic files * chore: remove deprecated configuration and script files, add new setup-in-workspace script for argent installation |
||
|
Paweł Fornagiel
|
da707875b1 |
feat: deprecate UI package (#45)
* feat: delete ui package * feat: delete left tsconfig.buildinfo |
||
|
Paweł Fornagiel
|
77dd289d78 |
feat: replace auto-postinstall with npx @software-mansion/argent install (#41)
* feat: add first implememntation of environment subagent * chore: remove the irrelavnt skill from main project config * feat: add rules support and enhance postinstall script for Argent tools (#23) * feat: add first implememntation of environment subagent * feat: enhance argent.md with environment inspection subagent details and workspace information retrieval guidelines * feat: introduce argent.md with comprehensive guidelines for iOS simulator interactions and React Native workflows * fix: fix postinstall script * fix: fix Install Argent launch.json job * feat: add environment inspector design document and research notes on MCP error signaling * chore: update .gitignore to include MCP agents and rules directories * fix: update `argent.md` rule with alwaysApply: true for cursor compatibility * chore: remove mcp/rules from index * feat: add basic npx flow * feat: cicd for releasing the package as nmp through github * fix: update package name references from @software-mansion-labs to @software-mansion in documentation and configuration files * refactor: simplify postinstall script for @software-mansion/argent and update configuration instructions |
||
|
pFornagiel
|
ac8c75bb9b | feat: update readme | ||
|
Ignacy Łątka
|
6b19331208 | complete rewrite, test every change | ||
|
Ignacy Łątka
|
d6535936bd | add initial better flow | ||
|
pFornagiel
|
c86378e6c4 | feat: change radon-lite references to argent | ||
|
pFornagiel
|
2578e9def8 | feat: update docs, package.json, etc. | ||
|
pFornagiel
|
dc3d4ec000 | feat: rename tools package to tool-server, minor functionalities renamings | ||
|
pFornagiel
|
f4f882bad1 | feat: registry integration | ||
|
Filip131311
|
64cbb43569 |
Add README with setup, options, token, and quick-start guide
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |