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)
## 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)
## 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
## 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)
## 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.
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.
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.
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.
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
## 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.
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>
* 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>
* 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
* 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
* 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
* 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
filip131311