Mateusz Aliyev
6e9e45c9f0
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 -->
Full Argent E2E harness
A release-gating end-to-end test that starts from nothing but a
swmansion-argent-*.tgz bundle and exercises the whole product: the install
flow, every CLI command, every tool's argument validation, and a happy-path run
of every tool that applies against real devices.
Run it on the real Linux box and the real Mac before a release.
Quick start
# from the repo root, with a swmansion-argent-*.tgz present there:
bash scripts/e2e-full/run-e2e.sh
# a subset of phases:
bash scripts/e2e-full/run-e2e.sh --phase install,introspection,validation
# offline core only, driving the unpacked bundle (no npm install, fast):
bash scripts/e2e-full/run-e2e.sh --skip-install --phase introspection,validation
A markdown report is written to scripts/e2e-full/results/report-<ts>.md and the
raw per-case log to results/e2e-<ts>.jsonl. The process exits non-zero if any
hard assertion failed (skips do not fail the run).
What it does (phases)
| phase | needs | covers |
|---|---|---|
install |
npm + network | npm i -g <tgz>, bundled binaries, init (global + --local), update, uninstall, telemetry, MCP-config generation |
introspection |
— | --version/--help, tools, tools describe for every published tool, feature flags, server start/status/logs/stop, link/unlink |
validation |
— | for every tool: missing-required / bad-enum / bad-type rejection (deterministic, no hardware) |
android |
Android emulator | happy-path of every touch/gesture/screenshot/app-lifecycle tool |
chromium |
Electron (bundled optional dep) + a display | boots a generated Electron app; drives CDP tools (scroll/drag/tabs/cookies/storage) |
rn |
~/dev/bluesky + Android device |
debugger + react/native profiler + network chain against the real Bluesky app |
device-provider |
an Android device (or E2E_PROVIDER_IOS_UDID) |
the external device provider contract: the harness spawns argent's own argent-simulator-server, publishes a descriptor naming it, and drives the resulting ext: device — then asserts argent never killed it, refused boot-device, honoured capability denial, and reacted to revocation |
Tiers auto-skip (with a recorded reason) when their prerequisites are missing, so a partial run still produces a meaningful report. iOS / tvOS / Vega tiers are intentionally out of scope.
Isolation
Everything runs under a throwaway HOME and npm prefix ($(mktemp -d)), so the
real machine's ~/.argent, editor MCP configs, and global packages are never
touched — safe to run on a shared box. Add --keep to inspect the sandbox after.
Providing a device
The device tiers need a booted device. Two ways:
- Inject an already-booted one (recommended on shared/CI machines):
--android-serial emulator-5554(the harness attaches, doesn't boot/teardown it). - Let the harness boot it:
--android-avd Pixel_9a(usesboot-device). The booted serial is published to the RN tier, so it runs against the same device, and the emulator is shut down in the cleanup phase — after every tier that uses it, and on an aborted run too.
The Chromium tier needs no device — it generates and boots its own Electron app.
It requires DISPLAY; on a headless Linux box run the whole harness under
xvfb-run, which supplies one. Having xvfb-run merely installed is not enough,
because nothing wraps the Electron spawn in it.
RN (Bluesky) tier
E2E_RN_DIR=~/dev/bluesky E2E_RN_PKG=xyz.blueskyweb.app \
bash scripts/e2e-full/run-e2e.sh --phase rn --android-serial <serial>
Assumes the Bluesky dev-client is already built and installed on the device; the
tier skips itself if the package is absent. Pass E2E_RN_BUILD=1 to let it run
expo run:android first (slow). It starts Metro if nothing is serving the port
and tears down only a Metro it started — one you were already running is left
alone.
Flags
--tgz PATH tarball to test (default: newest swmansion-argent-*.tgz at repo root)
--phase a,b,c subset of: install introspection validation android chromium rn device-provider
--skip-install drive the unpacked bundle directly (offline phases only; skips `install`)
--system install to the REAL global prefix (dedicated release machine only)
--android-serial S use an already-booted Android device
--android-avd NAME boot this AVD via boot-device
--keep leave the sandbox dir for inspection
Layout
run-e2e.sh orchestrator: env setup, phase dispatch, report, exit code
lib/common.sh logging, argent_cli/run_tool, assert_* helpers, server + screenshot helpers
lib/discover-tools.sh parses `argent tools describe` into per-tool arg models
lib/report.py JSONL -> markdown (per-phase + per-tool coverage matrix + failures)
phases/*.sh one run_phase() per phase
results/ generated JSONL + report (gitignored)