From 14ed610728ff8eec51bfdb950c605d49d6dd76d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Fri, 3 Apr 2026 16:36:31 +0200 Subject: [PATCH] feat: add generated repo knowledge layer --- AGENTS.md | 2 + knowledge/agent-routes.md | 41 + knowledge/commands/alert.md | 53 + knowledge/commands/app-switcher.md | 52 + knowledge/commands/apps.md | 53 + knowledge/commands/appstate.md | 44 + knowledge/commands/back.md | 53 + knowledge/commands/batch.md | 48 + knowledge/commands/boot.md | 52 + knowledge/commands/click.md | 60 + knowledge/commands/clipboard.md | 53 + knowledge/commands/close.md | 53 + knowledge/commands/devices.md | 44 + knowledge/commands/diff.md | 60 + knowledge/commands/ensure-simulator.md | 46 + knowledge/commands/fill.md | 55 + knowledge/commands/find.md | 54 + knowledge/commands/focus.md | 52 + knowledge/commands/get.md | 54 + knowledge/commands/home.md | 52 + knowledge/commands/install-from-source.md | 54 + knowledge/commands/install.md | 52 + knowledge/commands/is.md | 54 + knowledge/commands/keyboard.md | 53 + knowledge/commands/logs.md | 52 + knowledge/commands/longpress.md | 52 + knowledge/commands/metro.md | 56 + knowledge/commands/network.md | 52 + knowledge/commands/open.md | 55 + knowledge/commands/perf.md | 52 + knowledge/commands/pinch.md | 52 + knowledge/commands/press.md | 59 + knowledge/commands/push.md | 52 + knowledge/commands/record.md | 51 + knowledge/commands/reinstall.md | 52 + knowledge/commands/replay.md | 44 + knowledge/commands/rotate.md | 53 + knowledge/commands/screenshot.md | 55 + knowledge/commands/scroll.md | 52 + knowledge/commands/scrollintoview.md | 52 + knowledge/commands/session.md | 44 + knowledge/commands/settings.md | 53 + knowledge/commands/snapshot.md | 58 + knowledge/commands/swipe.md | 54 + knowledge/commands/test.md | 49 + knowledge/commands/trace.md | 42 + knowledge/commands/trigger-app-event.md | 53 + knowledge/commands/type.md | 52 + knowledge/commands/wait.md | 55 + knowledge/index.json | 2564 +++++++++++++++++++++ knowledge/index.md | 71 + knowledge/platform-matrix.md | 55 + package.json | 4 +- scripts/build-knowledge.mjs | 5 + scripts/check-knowledge.mjs | 22 + scripts/knowledge-lib.mjs | 674 ++++++ 56 files changed, 5889 insertions(+), 1 deletion(-) create mode 100644 knowledge/agent-routes.md create mode 100644 knowledge/commands/alert.md create mode 100644 knowledge/commands/app-switcher.md create mode 100644 knowledge/commands/apps.md create mode 100644 knowledge/commands/appstate.md create mode 100644 knowledge/commands/back.md create mode 100644 knowledge/commands/batch.md create mode 100644 knowledge/commands/boot.md create mode 100644 knowledge/commands/click.md create mode 100644 knowledge/commands/clipboard.md create mode 100644 knowledge/commands/close.md create mode 100644 knowledge/commands/devices.md create mode 100644 knowledge/commands/diff.md create mode 100644 knowledge/commands/ensure-simulator.md create mode 100644 knowledge/commands/fill.md create mode 100644 knowledge/commands/find.md create mode 100644 knowledge/commands/focus.md create mode 100644 knowledge/commands/get.md create mode 100644 knowledge/commands/home.md create mode 100644 knowledge/commands/install-from-source.md create mode 100644 knowledge/commands/install.md create mode 100644 knowledge/commands/is.md create mode 100644 knowledge/commands/keyboard.md create mode 100644 knowledge/commands/logs.md create mode 100644 knowledge/commands/longpress.md create mode 100644 knowledge/commands/metro.md create mode 100644 knowledge/commands/network.md create mode 100644 knowledge/commands/open.md create mode 100644 knowledge/commands/perf.md create mode 100644 knowledge/commands/pinch.md create mode 100644 knowledge/commands/press.md create mode 100644 knowledge/commands/push.md create mode 100644 knowledge/commands/record.md create mode 100644 knowledge/commands/reinstall.md create mode 100644 knowledge/commands/replay.md create mode 100644 knowledge/commands/rotate.md create mode 100644 knowledge/commands/screenshot.md create mode 100644 knowledge/commands/scroll.md create mode 100644 knowledge/commands/scrollintoview.md create mode 100644 knowledge/commands/session.md create mode 100644 knowledge/commands/settings.md create mode 100644 knowledge/commands/snapshot.md create mode 100644 knowledge/commands/swipe.md create mode 100644 knowledge/commands/test.md create mode 100644 knowledge/commands/trace.md create mode 100644 knowledge/commands/trigger-app-event.md create mode 100644 knowledge/commands/type.md create mode 100644 knowledge/commands/wait.md create mode 100644 knowledge/index.json create mode 100644 knowledge/index.md create mode 100644 knowledge/platform-matrix.md create mode 100644 scripts/build-knowledge.mjs create mode 100644 scripts/check-knowledge.mjs create mode 100644 scripts/knowledge-lib.mjs diff --git a/AGENTS.md b/AGENTS.md index d6a92fa7..cbe28648 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,6 +60,8 @@ Minimal operating guide for AI coding agents in this repo. ## Cheap Exploration - Prefer these first-pass commands over broader reads: + - `pnpm kb:build`: regenerate the agent-facing `knowledge/` index after command/doc/skill changes + - `pnpm kb:check`: detect stale generated knowledge files - `rg -n "" src test` - `rg --files src/daemon/handlers src/platforms/ios src/platforms/android` - `git diff -- ` for active-branch context diff --git a/knowledge/agent-routes.md b/knowledge/agent-routes.md new file mode 100644 index 00000000..cec72b32 --- /dev/null +++ b/knowledge/agent-routes.md @@ -0,0 +1,41 @@ + + +# Agent Routes + +Use this page when deciding where to read first. The goal is to keep the first hop narrow and close to the owning module. + +## Learn the CLI surface or flag schema + +- [src/utils/command-schema.ts](../src/utils/command-schema.ts) +- [src/utils/args.ts](../src/utils/args.ts) +- [knowledge/index.md](index.md) + +## Trace session lifecycle and session-owned commands + +- [src/daemon/handlers/session.ts](../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../src/daemon/session-store.ts) +- [skills/agent-device/references/bootstrap-install.md](../skills/agent-device/references/bootstrap-install.md) + +## Trace selectors and element interactions + +- [src/daemon/handlers/interaction.ts](../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../src/daemon/selectors.ts) +- [skills/agent-device/references/exploration.md](../skills/agent-device/references/exploration.md) + +## Trace snapshot, wait, alerts, settings, or screenshot behavior + +- [src/daemon/handlers/snapshot.ts](../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../src/daemon/snapshot-processing.ts) +- [website/docs/docs/snapshots.md](../website/docs/docs/snapshots.md) + +## Trace replay, test, record, and trace flows + +- [src/daemon/handlers/record-trace.ts](../src/daemon/handlers/record-trace.ts) +- [src/daemon/handlers/session-replay.ts](../src/daemon/handlers/session-replay.ts) +- [website/docs/docs/replay-e2e.md](../website/docs/docs/replay-e2e.md) + +## Trace Apple runner behavior + +- [src/platforms/ios/runner-contract.ts](../src/platforms/ios/runner-contract.ts) +- [src/platforms/ios/runner-client.ts](../src/platforms/ios/runner-client.ts) +- [src/platforms/ios/runner-transport.ts](../src/platforms/ios/runner-transport.ts) diff --git a/knowledge/commands/alert.md b/knowledge/commands/alert.md new file mode 100644 index 00000000..e164fb7e --- /dev/null +++ b/knowledge/commands/alert.md @@ -0,0 +1,53 @@ + + +# alert + +Inspect or handle iOS/macOS alerts + +## Usage + +```bash +agent-device alert [get|accept|dismiss|wait] [timeout] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | No | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | No | +| Android device | No | +| Android TV | No | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/app-switcher.md b/knowledge/commands/app-switcher.md new file mode 100644 index 00000000..333c445c --- /dev/null +++ b/knowledge/commands/app-switcher.md @@ -0,0 +1,52 @@ + + +# app-switcher + +Open app switcher + +## Usage + +```bash +agent-device app-switcher +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/apps.md b/knowledge/commands/apps.md new file mode 100644 index 00000000..b3e645cf --- /dev/null +++ b/knowledge/commands/apps.md @@ -0,0 +1,53 @@ + + +# apps + +List installed apps + +## Usage + +```bash +agent-device apps [--user-installed] [--all] +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--user-installed`: Apps: list user-installed apps +- `--all`: Apps: list all apps (include system/default apps) + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/appstate.md b/knowledge/commands/appstate.md new file mode 100644 index 00000000..d73ca8bb --- /dev/null +++ b/knowledge/commands/appstate.md @@ -0,0 +1,44 @@ + + +# appstate + +Show foreground app/activity + +## Usage + +```bash +agent-device appstate +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/back.md b/knowledge/commands/back.md new file mode 100644 index 00000000..3142cca4 --- /dev/null +++ b/knowledge/commands/back.md @@ -0,0 +1,53 @@ + + +# back + +Go back + +## Usage + +```bash +agent-device back [--in-app|--system] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- `back --in-app` is the explicit alias for the default app-owned behavior. + +## Allowed Flags + +- `--in-app`: Back: use app-provided back UI when available +- `--system`: Back: use system back input or gesture when available + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/batch.md b/knowledge/commands/batch.md new file mode 100644 index 00000000..02ea1986 --- /dev/null +++ b/knowledge/commands/batch.md @@ -0,0 +1,48 @@ + + +# batch + +Run multiple commands + +## Usage + +```bash +agent-device batch [--steps | --steps-file ] +``` + +## Session Requirement + +Creates or manages sessions internally. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--steps `: Batch: JSON array of steps +- `--steps-file `: Batch: read steps JSON from file +- `--on-error stop`: Batch: stop when a step fails +- `--max-steps `: Batch: maximum number of allowed steps +- `--out `: Output path + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/boot.md b/knowledge/commands/boot.md new file mode 100644 index 00000000..9766036c --- /dev/null +++ b/knowledge/commands/boot.md @@ -0,0 +1,52 @@ + + +# boot + +Boot target device/simulator + +## Usage + +```bash +agent-device boot [--headless] +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--headless`: Boot: launch Android emulator without a GUI window + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/click.md b/knowledge/commands/click.md new file mode 100644 index 00000000..4a952b1d --- /dev/null +++ b/knowledge/commands/click.md @@ -0,0 +1,60 @@ + + +# click + +Tap by coordinates, ref, or selector + +## Usage + +```bash +agent-device click +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--count `: Repeat count for press/swipe series +- `--interval-ms `: Delay between press iterations +- `--hold-ms `: Press hold duration for each iteration +- `--jitter-px `: Deterministic coordinate jitter radius for press +- `--double-tap`: Use double-tap gesture per press iteration +- `--button primary|secondary|middle`: Click: choose mouse button (middle reserved for future macOS support) +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/clipboard.md b/knowledge/commands/clipboard.md new file mode 100644 index 00000000..811657da --- /dev/null +++ b/knowledge/commands/clipboard.md @@ -0,0 +1,53 @@ + + +# clipboard + +Read or write device clipboard text + +## Usage + +```bash +agent-device clipboard read | clipboard write +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | No | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/close.md b/knowledge/commands/close.md new file mode 100644 index 00000000..21fd564f --- /dev/null +++ b/knowledge/commands/close.md @@ -0,0 +1,53 @@ + + +# close + +Close app or end session + +## Usage + +```bash +agent-device close [app] [--save-script [path]] [--shutdown] +``` + +## Session Requirement + +Requires an active session to close it. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--save-script [path]`: Save session script (.ad) on close; optional custom output path +- `--shutdown`: close: shutdown associated iOS simulator after ending session + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/devices.md b/knowledge/commands/devices.md new file mode 100644 index 00000000..ad53bc86 --- /dev/null +++ b/knowledge/commands/devices.md @@ -0,0 +1,44 @@ + + +# devices + +List available devices + +## Usage + +```bash +agent-device devices +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/diff.md b/knowledge/commands/diff.md new file mode 100644 index 00000000..2aa8f82d --- /dev/null +++ b/knowledge/commands/diff.md @@ -0,0 +1,60 @@ + + +# diff + +Diff snapshot or screenshot + +## Usage + +```bash +agent-device diff snapshot | diff screenshot --baseline [--out ] [--threshold <0-1>] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- `snapshot --diff` routes to `diff snapshot`. + +## Allowed Flags + +- `-i`: Snapshot: interactive elements only +- `-c`: Snapshot: compact output (drop empty structure) +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output +- `--baseline, -b `: Diff screenshot: path to baseline image file +- `--threshold <0-1>`: Diff screenshot: color distance threshold (default 0.1) +- `--out `: Output path + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/ensure-simulator.md b/knowledge/commands/ensure-simulator.md new file mode 100644 index 00000000..daae1f52 --- /dev/null +++ b/knowledge/commands/ensure-simulator.md @@ -0,0 +1,46 @@ + + +# ensure-simulator + +Ensure iOS simulator exists + +## Usage + +```bash +agent-device ensure-simulator [--runtime ] [--boot] [--reuse-existing] +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--runtime `: ensure-simulator: CoreSimulator runtime identifier (e.g. com.apple.CoreSimulator.SimRuntime.iOS-18-0) +- `--boot`: ensure-simulator: boot the simulator after ensuring it exists +- `--reuse-existing`: ensure-simulator: reuse an existing simulator (default: true) + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/fill.md b/knowledge/commands/fill.md new file mode 100644 index 00000000..c1af5203 --- /dev/null +++ b/knowledge/commands/fill.md @@ -0,0 +1,55 @@ + + +# fill + +Tap then type + +## Usage + +```bash +agent-device fill | fill <@ref|selector> +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output +- `--delay-ms `: Delay between typed characters + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/find.md b/knowledge/commands/find.md new file mode 100644 index 00000000..2ea6bd31 --- /dev/null +++ b/knowledge/commands/find.md @@ -0,0 +1,54 @@ + + +# find + +Find an element and act + +## Usage + +```bash +agent-device find [value] [--first|--last] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--depth, -d `: Snapshot: limit snapshot depth +- `--raw`: Snapshot: raw node output +- `--first`: Find: pick the first match when ambiguous +- `--last`: Find: pick the last match when ambiguous + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/find.ts](../../src/daemon/handlers/find.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/find.test.ts](../../src/daemon/handlers/__tests__/find.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/focus.md b/knowledge/commands/focus.md new file mode 100644 index 00000000..da12737e --- /dev/null +++ b/knowledge/commands/focus.md @@ -0,0 +1,52 @@ + + +# focus + +Focus input at coordinates + +## Usage + +```bash +agent-device focus +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/get.md b/knowledge/commands/get.md new file mode 100644 index 00000000..52d74ac3 --- /dev/null +++ b/knowledge/commands/get.md @@ -0,0 +1,54 @@ + + +# get + +Get text or attrs by ref or selector + +## Usage + +```bash +agent-device get text|attrs <@ref|selector> +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/home.md b/knowledge/commands/home.md new file mode 100644 index 00000000..c17e0a37 --- /dev/null +++ b/knowledge/commands/home.md @@ -0,0 +1,52 @@ + + +# home + +Go home + +## Usage + +```bash +agent-device home +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/install-from-source.md b/knowledge/commands/install-from-source.md new file mode 100644 index 00000000..e1a4d03b --- /dev/null +++ b/knowledge/commands/install-from-source.md @@ -0,0 +1,54 @@ + + +# install-from-source + +Install app from a URL source + +## Usage + +```bash +agent-device install-from-source [--header ] [--retain-paths] [--retention-ms ] +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--header `: install-from-source: repeatable HTTP header for URL downloads +- `--retain-paths`: install-from-source: keep materialized artifact paths after install +- `--retention-ms `: install-from-source: retention TTL for materialized artifact paths + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/install.md b/knowledge/commands/install.md new file mode 100644 index 00000000..24588791 --- /dev/null +++ b/knowledge/commands/install.md @@ -0,0 +1,52 @@ + + +# install + +Install app from binary path + +## Usage + +```bash +agent-device install +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/is.md b/knowledge/commands/is.md new file mode 100644 index 00000000..e8488cbc --- /dev/null +++ b/knowledge/commands/is.md @@ -0,0 +1,54 @@ + + +# is + +Assert UI state + +## Usage + +```bash +agent-device is [value] [--depth, -d ] [--scope, -s ] [--raw] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/keyboard.md b/knowledge/commands/keyboard.md new file mode 100644 index 00000000..93f5f98f --- /dev/null +++ b/knowledge/commands/keyboard.md @@ -0,0 +1,53 @@ + + +# keyboard + +Inspect or dismiss the device keyboard + +## Usage + +```bash +agent-device keyboard [status|get|dismiss] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | No | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/logs.md b/knowledge/commands/logs.md new file mode 100644 index 00000000..72050407 --- /dev/null +++ b/knowledge/commands/logs.md @@ -0,0 +1,52 @@ + + +# logs + +Manage session app logs + +## Usage + +```bash +agent-device logs path | logs start | logs stop | logs clear [--restart] | logs doctor | logs mark [message...] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--restart`: logs clear: stop active stream, clear logs, then start streaming again + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/longpress.md b/knowledge/commands/longpress.md new file mode 100644 index 00000000..3c1d0cb6 --- /dev/null +++ b/knowledge/commands/longpress.md @@ -0,0 +1,52 @@ + + +# longpress + +Long press by coordinates + +## Usage + +```bash +agent-device longpress [durationMs] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- `long-press` + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/metro.md b/knowledge/commands/metro.md new file mode 100644 index 00000000..4bae3e25 --- /dev/null +++ b/knowledge/commands/metro.md @@ -0,0 +1,56 @@ + + +# metro + +Prepare local Metro runtime + +## Usage + +```bash +agent-device metro prepare --public-base-url [--project-root ] [--port ] [--kind auto|react-native|expo] +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--project-root `: metro prepare: React Native project root (default: cwd) +- `--kind auto|react-native|expo`: metro prepare: detect or force the Metro launcher kind +- `--public-base-url `: metro prepare: public base URL used to build bundle hints +- `--proxy-base-url `: metro prepare: optional remote host bridge base URL for Metro access +- `--bearer-token `: metro prepare: host bridge bearer token (prefer AGENT_DEVICE_PROXY_TOKEN or AGENT_DEVICE_METRO_BEARER_TOKEN) +- `--port `: metro prepare: local Metro port (default: 8081) +- `--listen-host `: metro prepare: host Metro listens on (default: 0.0.0.0) +- `--status-host `: metro prepare: host used for local /status polling (default: 127.0.0.1) +- `--startup-timeout-ms `: metro prepare: timeout while waiting for Metro to become ready +- `--probe-timeout-ms `: metro prepare: timeout for /status and proxy bridge calls +- `--runtime-file `: metro prepare: optional file path to persist the JSON result +- `--no-reuse-existing`: metro prepare: always start a fresh Metro process +- `--no-install-deps`: metro prepare: skip package-manager install when node_modules is missing + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/network.md b/knowledge/commands/network.md new file mode 100644 index 00000000..536e5c80 --- /dev/null +++ b/knowledge/commands/network.md @@ -0,0 +1,52 @@ + + +# network + +Show recent HTTP traffic + +## Usage + +```bash +agent-device network dump [limit] [summary|headers|body|all] [--include summary|headers|body|all] | network log [limit] [summary|headers|body|all] [--include summary|headers|body|all] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- `network log` is an alias for `network dump`. + +## Allowed Flags + +- `--include summary|headers|body|all`: Network: include headers, bodies, or both in output + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/open.md b/knowledge/commands/open.md new file mode 100644 index 00000000..a52194cf --- /dev/null +++ b/knowledge/commands/open.md @@ -0,0 +1,55 @@ + + +# open + +Open an app, deep link or URL, save replays + +## Usage + +```bash +agent-device open [appOrUrl] [url] [--activity ] [--save-script [path]] [--relaunch] [--surface app|frontmost-app|desktop|menubar] +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--activity `: Android app launch activity (package/Activity); not for URL opens +- `--save-script [path]`: Save session script (.ad) on close; optional custom output path +- `--relaunch`: open: terminate app process before launching it +- `--surface app|frontmost-app|desktop|menubar`: macOS session surface for open (defaults to app) + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/perf.md b/knowledge/commands/perf.md new file mode 100644 index 00000000..87532b84 --- /dev/null +++ b/knowledge/commands/perf.md @@ -0,0 +1,52 @@ + + +# perf + +Show performance metrics + +## Usage + +```bash +agent-device perf +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- `metrics` + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/pinch.md b/knowledge/commands/pinch.md new file mode 100644 index 00000000..8d4bd025 --- /dev/null +++ b/knowledge/commands/pinch.md @@ -0,0 +1,52 @@ + + +# pinch + +Pinch/zoom gesture (Apple simulator or macOS app session) + +## Usage + +```bash +agent-device pinch [x] [y] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | No | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | No | +| Android device | No | +| Android TV | No | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/press.md b/knowledge/commands/press.md new file mode 100644 index 00000000..36fb9154 --- /dev/null +++ b/knowledge/commands/press.md @@ -0,0 +1,59 @@ + + +# press + +Press by coordinates, ref, or selector + +## Usage + +```bash +agent-device press +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--count `: Repeat count for press/swipe series +- `--interval-ms `: Delay between press iterations +- `--hold-ms `: Press hold duration for each iteration +- `--jitter-px `: Deterministic coordinate jitter radius for press +- `--double-tap`: Use double-tap gesture per press iteration +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/push.md b/knowledge/commands/push.md new file mode 100644 index 00000000..c0446429 --- /dev/null +++ b/knowledge/commands/push.md @@ -0,0 +1,52 @@ + + +# push + +Deliver push payload + +## Usage + +```bash +agent-device push +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | No | +| tvOS sim | Yes | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/record.md b/knowledge/commands/record.md new file mode 100644 index 00000000..7410df26 --- /dev/null +++ b/knowledge/commands/record.md @@ -0,0 +1,51 @@ + + +# record + +Start or stop screen recording + +## Usage + +```bash +agent-device record start [path] [--fps ] [--hide-touches] | record stop +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--fps `: Record: target frames per second (iOS physical device runner) +- `--hide-touches`: Record: disable touch overlays in the final video + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/record-trace.ts](../../src/daemon/handlers/record-trace.ts) +- [src/platforms/ios/runner-client.ts](../../src/platforms/ios/runner-client.ts) +- [src/daemon/handlers/__tests__/record-trace.test.ts](../../src/daemon/handlers/__tests__/record-trace.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [skills/agent-device/references/verification.md](../../skills/agent-device/references/verification.md) diff --git a/knowledge/commands/reinstall.md b/knowledge/commands/reinstall.md new file mode 100644 index 00000000..90922c7c --- /dev/null +++ b/knowledge/commands/reinstall.md @@ -0,0 +1,52 @@ + + +# reinstall + +Reinstall app from binary path + +## Usage + +```bash +agent-device reinstall +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/replay.md b/knowledge/commands/replay.md new file mode 100644 index 00000000..66a88a23 --- /dev/null +++ b/knowledge/commands/replay.md @@ -0,0 +1,44 @@ + + +# replay + +Replay a recorded session + +## Usage + +```bash +agent-device replay [--update, -u] +``` + +## Session Requirement + +Creates or manages sessions internally. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--update, -u`: Replay: update selectors and rewrite replay file in place + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/rotate.md b/knowledge/commands/rotate.md new file mode 100644 index 00000000..7d25be50 --- /dev/null +++ b/knowledge/commands/rotate.md @@ -0,0 +1,53 @@ + + +# rotate + +Rotate device orientation + +## Usage + +```bash +agent-device rotate +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | No | +| macOS | No | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/screenshot.md b/knowledge/commands/screenshot.md new file mode 100644 index 00000000..54107ad0 --- /dev/null +++ b/knowledge/commands/screenshot.md @@ -0,0 +1,55 @@ + + +# screenshot + +Capture screenshot (macOS app sessions default to the app window; use --fullscreen for full desktop, or --overlay-refs to annotate the image with current refs) + +## Usage + +```bash +agent-device screenshot [path] [--out ] [--overlay-refs] [--fullscreen] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--out `: Output path +- `--overlay-refs`: Screenshot: draw current snapshot refs and target rectangles onto the saved PNG +- `--fullscreen`: Screenshot: capture the full screen instead of the app window + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/scroll.md b/knowledge/commands/scroll.md new file mode 100644 index 00000000..a727123e --- /dev/null +++ b/knowledge/commands/scroll.md @@ -0,0 +1,52 @@ + + +# scroll + +Scroll in a direction + +## Usage + +```bash +agent-device scroll [amount] [--pixels ] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--pixels `: Scroll: explicit gesture distance in pixels + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/scrollintoview.md b/knowledge/commands/scrollintoview.md new file mode 100644 index 00000000..421151c0 --- /dev/null +++ b/knowledge/commands/scrollintoview.md @@ -0,0 +1,52 @@ + + +# scrollintoview + +Scroll until text or ref is visible + +## Usage + +```bash +agent-device scrollintoview +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--max-scrolls `: scrollintoview: cap the number of scroll gestures before failing + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/session.md b/knowledge/commands/session.md new file mode 100644 index 00000000..e87e9ea9 --- /dev/null +++ b/knowledge/commands/session.md @@ -0,0 +1,44 @@ + + +# session + +List active sessions + +## Usage + +```bash +agent-device session list +``` + +## Session Requirement + +Does not require an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/settings.md b/knowledge/commands/settings.md new file mode 100644 index 00000000..54f6b692 --- /dev/null +++ b/knowledge/commands/settings.md @@ -0,0 +1,53 @@ + + +# settings + +Change OS settings and app permissions + +## Usage + +```bash +agent-device settings | settings appearance | settings faceid | settings touchid | settings fingerprint | settings permission [full|limited] | settings permission +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | No | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/snapshot.md b/knowledge/commands/snapshot.md new file mode 100644 index 00000000..c55bc07a --- /dev/null +++ b/knowledge/commands/snapshot.md @@ -0,0 +1,58 @@ + + +# snapshot + +Capture accessibility tree or diff against the previous session baseline + +## Usage + +```bash +agent-device snapshot [--diff] [-i] [-c] [-d ] [-s ] [--raw] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--diff`: Snapshot: show structural diff against the previous session baseline +- `-i`: Snapshot: interactive elements only +- `-c`: Snapshot: compact output (drop empty structure) +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/swipe.md b/knowledge/commands/swipe.md new file mode 100644 index 00000000..ed5220f6 --- /dev/null +++ b/knowledge/commands/swipe.md @@ -0,0 +1,54 @@ + + +# swipe + +Swipe coordinates + +## Usage + +```bash +agent-device swipe [durationMs] [--count ] [--pause-ms ] [--pattern one-way|ping-pong] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--count `: Repeat count for press/swipe series +- `--pause-ms `: Delay between swipe iterations +- `--pattern one-way|ping-pong`: Swipe repeat pattern + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/test.md b/knowledge/commands/test.md new file mode 100644 index 00000000..01d49d4d --- /dev/null +++ b/knowledge/commands/test.md @@ -0,0 +1,49 @@ + + +# test + +Run .ad test suites + +## Usage + +```bash +agent-device test ... +``` + +## Session Requirement + +Creates or manages sessions internally. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--update, -u`: Replay: update selectors and rewrite replay file in place +- `--fail-fast`: Test: stop the suite after the first failing script +- `--timeout `: Test: maximum wall-clock time per script attempt +- `--retries `: Test: retry each failed script up to n additional times +- `--artifacts-dir `: Test: root directory for suite artifacts +- `--report-junit `: Test: write a JUnit XML report for the replay suite + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/session.ts](../../src/daemon/handlers/session.ts) +- [src/daemon/session-store.ts](../../src/daemon/session-store.ts) +- [src/daemon/handlers/__tests__/session.test.ts](../../src/daemon/handlers/__tests__/session.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/replay-e2e.md](../../website/docs/docs/replay-e2e.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/bootstrap-install.md](../../skills/agent-device/references/bootstrap-install.md) diff --git a/knowledge/commands/trace.md b/knowledge/commands/trace.md new file mode 100644 index 00000000..55a35559 --- /dev/null +++ b/knowledge/commands/trace.md @@ -0,0 +1,42 @@ + + +# trace + +Start or stop trace capture + +## Usage + +```bash +agent-device trace start [path] | trace stop [path] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +_Capability checks are not defined for this command in `command-schema.ts`._ + +## Primary Source Paths + +- [src/daemon/handlers/record-trace.ts](../../src/daemon/handlers/record-trace.ts) +- [src/platforms/ios/runner-client.ts](../../src/platforms/ios/runner-client.ts) +- [src/daemon/handlers/__tests__/record-trace.test.ts](../../src/daemon/handlers/__tests__/record-trace.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [skills/agent-device/references/verification.md](../../skills/agent-device/references/verification.md) diff --git a/knowledge/commands/trigger-app-event.md b/knowledge/commands/trigger-app-event.md new file mode 100644 index 00000000..9a94cfb4 --- /dev/null +++ b/knowledge/commands/trigger-app-event.md @@ -0,0 +1,53 @@ + + +# trigger-app-event + +Trigger app event hook + +## Usage + +```bash +agent-device trigger-app-event [payloadJson] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- None + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/commands/type.md b/knowledge/commands/type.md new file mode 100644 index 00000000..4142e2f0 --- /dev/null +++ b/knowledge/commands/type.md @@ -0,0 +1,52 @@ + + +# type + +Type text in focused field + +## Usage + +```bash +agent-device type [--delay-ms ] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--delay-ms `: Delay between typed characters + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/interaction.ts](../../src/daemon/handlers/interaction.ts) +- [src/daemon/selectors.ts](../../src/daemon/selectors.ts) +- [src/daemon/handlers/__tests__/interaction.test.ts](../../src/daemon/handlers/__tests__/interaction.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/selectors.md](../../website/docs/docs/selectors.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) diff --git a/knowledge/commands/wait.md b/knowledge/commands/wait.md new file mode 100644 index 00000000..214d7cc7 --- /dev/null +++ b/knowledge/commands/wait.md @@ -0,0 +1,55 @@ + + +# wait + +Wait for time, text, ref, or selector + +## Usage + +```bash +agent-device wait |text |@ref| [timeoutMs] +``` + +## Session Requirement + +Usually expects an active session. + +## Aliases + +- None + +## Notes + +- None + +## Allowed Flags + +- `--depth, -d `: Snapshot: limit snapshot depth +- `--scope, -s `: Snapshot: scope snapshot to label/identifier +- `--raw`: Snapshot: raw node output + +## Platform Coverage + +| Target | Supported | +| --- | --- | +| iOS sim | Yes | +| iOS device | Yes | +| tvOS sim | Yes | +| macOS | Yes | +| Android emu | Yes | +| Android device | Yes | +| Android TV | Yes | + +## Primary Source Paths + +- [src/daemon/handlers/snapshot.ts](../../src/daemon/handlers/snapshot.ts) +- [src/daemon/snapshot-processing.ts](../../src/daemon/snapshot-processing.ts) +- [src/daemon/handlers/__tests__/snapshot-handler.test.ts](../../src/daemon/handlers/__tests__/snapshot-handler.test.ts) + +## Docs And Skills + +- [website/docs/docs/commands.md](../../website/docs/docs/commands.md) +- [website/docs/docs/snapshots.md](../../website/docs/docs/snapshots.md) +- [skills/agent-device/SKILL.md](../../skills/agent-device/SKILL.md) +- [skills/agent-device/references/exploration.md](../../skills/agent-device/references/exploration.md) +- [skills/agent-device/references/debugging.md](../../skills/agent-device/references/debugging.md) diff --git a/knowledge/index.json b/knowledge/index.json new file mode 100644 index 00000000..47eb1f61 --- /dev/null +++ b/knowledge/index.json @@ -0,0 +1,2564 @@ +{ + "generatedBy": "pnpm kb:build", + "routes": [ + { + "task": "Learn the CLI surface or flag schema", + "paths": [ + "src/utils/command-schema.ts", + "src/utils/args.ts", + "knowledge/index.md" + ] + }, + { + "task": "Trace session lifecycle and session-owned commands", + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "skills/agent-device/references/bootstrap-install.md" + ] + }, + { + "task": "Trace selectors and element interactions", + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "skills/agent-device/references/exploration.md" + ] + }, + { + "task": "Trace snapshot, wait, alerts, settings, or screenshot behavior", + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "website/docs/docs/snapshots.md" + ] + }, + { + "task": "Trace replay, test, record, and trace flows", + "paths": [ + "src/daemon/handlers/record-trace.ts", + "src/daemon/handlers/session-replay.ts", + "website/docs/docs/replay-e2e.md" + ] + }, + { + "task": "Trace Apple runner behavior", + "paths": [ + "src/platforms/ios/runner-contract.ts", + "src/platforms/ios/runner-client.ts", + "src/platforms/ios/runner-transport.ts" + ] + } + ], + "sampleTargets": [ + { + "key": "iosSimulator", + "label": "iOS sim" + }, + { + "key": "iosDevice", + "label": "iOS device" + }, + { + "key": "tvSimulator", + "label": "tvOS sim" + }, + { + "key": "macosDesktop", + "label": "macOS" + }, + { + "key": "androidEmulator", + "label": "Android emu" + }, + { + "key": "androidDevice", + "label": "Android device" + }, + { + "key": "androidTv", + "label": "Android TV" + } + ], + "sourceFiles": [ + "AGENTS.md", + "src/utils/command-schema.ts", + "src/core/capabilities.ts", + "skills/agent-device/SKILL.md", + "website/docs/docs/commands.md" + ], + "commands": [ + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Inspect or handle alert (iOS simulator and macOS desktop)", + "name": "alert", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": false, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": false, + "androidDevice": false, + "androidTv": false + }, + "positionals": [ + "action?", + "timeout?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Inspect or handle iOS/macOS alerts", + "usage": "alert [get|accept|dismiss|wait] [timeout]" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Open app switcher (where supported)", + "name": "app-switcher", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [], + "sessionRequirement": "Usually expects an active session.", + "summary": "Open app switcher", + "usage": "app-switcher" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "appsFilter", + "names": [ + "--user-installed" + ], + "usageDescription": "Apps: list user-installed apps", + "usageLabel": "--user-installed" + }, + { + "key": "appsFilter", + "names": [ + "--all" + ], + "usageDescription": "Apps: list all apps (include system/default apps)", + "usageLabel": "--all" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "List installed apps (includes default/system apps by default)", + "name": "apps", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [], + "sessionRequirement": "Does not require an active session.", + "summary": "List installed apps", + "usage": "apps [--user-installed] [--all]" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Show foreground app/activity", + "name": "appstate", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [], + "sessionRequirement": "Usually expects an active session.", + "summary": "Show foreground app/activity", + "usage": "appstate" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "backMode", + "names": [ + "--in-app" + ], + "usageDescription": "Back: use app-provided back UI when available", + "usageLabel": "--in-app" + }, + { + "key": "backMode", + "names": [ + "--system" + ], + "usageDescription": "Back: use system back input or gesture when available", + "usageLabel": "--system" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Navigate back with explicit app or system semantics", + "name": "back", + "notes": [ + "`back --in-app` is the explicit alias for the default app-owned behavior." + ], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [], + "sessionRequirement": "Usually expects an active session.", + "summary": "Go back", + "usage": "back [--in-app|--system]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "steps", + "names": [ + "--steps" + ], + "usageDescription": "Batch: JSON array of steps", + "usageLabel": "--steps " + }, + { + "key": "stepsFile", + "names": [ + "--steps-file" + ], + "usageDescription": "Batch: read steps JSON from file", + "usageLabel": "--steps-file " + }, + { + "key": "batchOnError", + "names": [ + "--on-error" + ], + "usageDescription": "Batch: stop when a step fails", + "usageLabel": "--on-error stop" + }, + { + "key": "batchMaxSteps", + "names": [ + "--max-steps" + ], + "usageDescription": "Batch: maximum number of allowed steps", + "usageLabel": "--max-steps " + }, + { + "key": "out", + "names": [ + "--out" + ], + "usageDescription": "Output path", + "usageLabel": "--out " + } + ], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Execute multiple commands in one daemon request", + "name": "batch", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [], + "sessionRequirement": "Creates or manages sessions internally.", + "summary": "Run multiple commands", + "usage": "batch [--steps | --steps-file ]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "headless", + "names": [ + "--headless" + ], + "usageDescription": "Boot: launch Android emulator without a GUI window", + "usageLabel": "--headless" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Ensure target device/simulator is booted and ready", + "name": "boot", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [], + "sessionRequirement": "Does not require an active session.", + "summary": "Boot target device/simulator", + "usage": "boot [--headless]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "count", + "names": [ + "--count" + ], + "usageDescription": "Repeat count for press/swipe series", + "usageLabel": "--count " + }, + { + "key": "intervalMs", + "names": [ + "--interval-ms" + ], + "usageDescription": "Delay between press iterations", + "usageLabel": "--interval-ms " + }, + { + "key": "holdMs", + "names": [ + "--hold-ms" + ], + "usageDescription": "Press hold duration for each iteration", + "usageLabel": "--hold-ms " + }, + { + "key": "jitterPx", + "names": [ + "--jitter-px" + ], + "usageDescription": "Deterministic coordinate jitter radius for press", + "usageLabel": "--jitter-px " + }, + { + "key": "doubleTap", + "names": [ + "--double-tap" + ], + "usageDescription": "Use double-tap gesture per press iteration", + "usageLabel": "--double-tap" + }, + { + "key": "clickButton", + "names": [ + "--button" + ], + "usageDescription": "Click: choose mouse button (middle reserved for future macOS support)", + "usageLabel": "--button primary|secondary|middle" + }, + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Tap/click by coordinates, snapshot ref, or selector", + "name": "click", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "target" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Tap by coordinates, ref, or selector", + "usage": "click " + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Read or write device clipboard text", + "name": "clipboard", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": false, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "read|write", + "text?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Read or write device clipboard text", + "usage": "clipboard read | clipboard write " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "saveScript", + "names": [ + "--save-script" + ], + "usageDescription": "Save session script (.ad) on close; optional custom output path", + "usageLabel": "--save-script [path]" + }, + { + "key": "shutdown", + "names": [ + "--shutdown" + ], + "usageDescription": "close: shutdown associated iOS simulator after ending session", + "usageLabel": "--shutdown" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Close app or just end session", + "name": "close", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "app?" + ], + "sessionRequirement": "Requires an active session to close it.", + "summary": "Close app or end session", + "usage": "close [app] [--save-script [path]] [--shutdown]" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "List available devices", + "name": "devices", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [], + "sessionRequirement": "Does not require an active session.", + "summary": "List available devices", + "usage": "devices" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "snapshotInteractiveOnly", + "names": [ + "-i" + ], + "usageDescription": "Snapshot: interactive elements only", + "usageLabel": "-i" + }, + { + "key": "snapshotCompact", + "names": [ + "-c" + ], + "usageDescription": "Snapshot: compact output (drop empty structure)", + "usageLabel": "-c" + }, + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + }, + { + "key": "baseline", + "names": [ + "--baseline", + "-b" + ], + "usageDescription": "Diff screenshot: path to baseline image file", + "usageLabel": "--baseline, -b " + }, + { + "key": "threshold", + "names": [ + "--threshold" + ], + "usageDescription": "Diff screenshot: color distance threshold (default 0.1)", + "usageLabel": "--threshold <0-1>" + }, + { + "key": "out", + "names": [ + "--out" + ], + "usageDescription": "Output path", + "usageLabel": "--out " + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Diff accessibility snapshot or compare screenshots pixel-by-pixel", + "name": "diff", + "notes": [ + "`snapshot --diff` routes to `diff snapshot`." + ], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "kind" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Diff snapshot or screenshot", + "usage": "diff snapshot | diff screenshot --baseline [--out ] [--threshold <0-1>]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "runtime", + "names": [ + "--runtime" + ], + "usageDescription": "ensure-simulator: CoreSimulator runtime identifier (e.g. com.apple.CoreSimulator.SimRuntime.iOS-18-0)", + "usageLabel": "--runtime " + }, + { + "key": "boot", + "names": [ + "--boot" + ], + "usageDescription": "ensure-simulator: boot the simulator after ensuring it exists", + "usageLabel": "--boot" + }, + { + "key": "reuseExisting", + "names": [ + "--reuse-existing" + ], + "usageDescription": "ensure-simulator: reuse an existing simulator (default: true)", + "usageLabel": "--reuse-existing" + } + ], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Ensure an iOS simulator exists in a device set (create if missing)", + "name": "ensure-simulator", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [], + "sessionRequirement": "Does not require an active session.", + "summary": "Ensure iOS simulator exists", + "usage": "ensure-simulator [--runtime ] [--boot] [--reuse-existing]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + }, + { + "key": "delayMs", + "names": [ + "--delay-ms" + ], + "usageDescription": "Delay between typed characters", + "usageLabel": "--delay-ms " + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Tap then type", + "name": "fill", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "targetOrX", + "yOrText", + "text?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Tap then type", + "usage": "fill | fill <@ref|selector> " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + }, + { + "key": "findFirst", + "names": [ + "--first" + ], + "usageDescription": "Find: pick the first match when ambiguous", + "usageLabel": "--first" + }, + { + "key": "findLast", + "names": [ + "--last" + ], + "usageDescription": "Find: pick the last match when ambiguous", + "usageLabel": "--last" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/references/exploration.md" + ], + "family": "find", + "helpDescription": "Find by text/label/value/role/id and run action", + "name": "find", + "notes": [], + "paths": [ + "src/daemon/handlers/find.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/find.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "query", + "action", + "value?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Find an element and act", + "usage": "find [value] [--first|--last]" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Focus input at coordinates", + "name": "focus", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "x", + "y" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Focus input at coordinates", + "usage": "focus " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Return element text/attributes by ref or selector", + "name": "get", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "subcommand", + "target" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Get text or attrs by ref or selector", + "usage": "get text|attrs <@ref|selector>" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Go to home screen (where supported)", + "name": "home", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [], + "sessionRequirement": "Usually expects an active session.", + "summary": "Go home", + "usage": "home" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Install app from binary path without uninstalling first", + "name": "install", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "app", + "path" + ], + "sessionRequirement": "Does not require an active session.", + "summary": "Install app from binary path", + "usage": "install " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "header", + "names": [ + "--header" + ], + "usageDescription": "install-from-source: repeatable HTTP header for URL downloads", + "usageLabel": "--header " + }, + { + "key": "retainPaths", + "names": [ + "--retain-paths" + ], + "usageDescription": "install-from-source: keep materialized artifact paths after install", + "usageLabel": "--retain-paths" + }, + { + "key": "retentionMs", + "names": [ + "--retention-ms" + ], + "usageDescription": "install-from-source: retention TTL for materialized artifact paths", + "usageLabel": "--retention-ms " + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Install app from a URL source through the normal daemon artifact flow", + "name": "install-from-source", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "url" + ], + "sessionRequirement": "Does not require an active session.", + "summary": "Install app from a URL source", + "usage": "install-from-source [--header ] [--retain-paths] [--retention-ms ]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Assert UI state (visible|hidden|exists|editable|selected|text)", + "name": "is", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "predicate", + "selector", + "value?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Assert UI state", + "usage": "is [value] [--depth, -d ] [--scope, -s ] [--raw]" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Inspect Android keyboard visibility/type or dismiss the device keyboard", + "name": "keyboard", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": false, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "action?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Inspect or dismiss the device keyboard", + "usage": "keyboard [status|get|dismiss]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "restart", + "names": [ + "--restart" + ], + "usageDescription": "logs clear: stop active stream, clear logs, then start streaming again", + "usageLabel": "--restart" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Session app log info, start/stop streaming, diagnostics, and markers", + "name": "logs", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "path|start|stop|clear|doctor|mark", + "message?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Manage session app logs", + "usage": "logs path | logs start | logs stop | logs clear [--restart] | logs doctor | logs mark [message...]" + }, + { + "aliases": [ + "long-press" + ], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Long press by coordinates (iOS and Android)", + "name": "longpress", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "x", + "y", + "durationMs?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Long press by coordinates", + "usage": "longpress [durationMs]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "metroProjectRoot", + "names": [ + "--project-root" + ], + "usageDescription": "metro prepare: React Native project root (default: cwd)", + "usageLabel": "--project-root " + }, + { + "key": "metroKind", + "names": [ + "--kind" + ], + "usageDescription": "metro prepare: detect or force the Metro launcher kind", + "usageLabel": "--kind auto|react-native|expo" + }, + { + "key": "metroPublicBaseUrl", + "names": [ + "--public-base-url" + ], + "usageDescription": "metro prepare: public base URL used to build bundle hints", + "usageLabel": "--public-base-url " + }, + { + "key": "metroProxyBaseUrl", + "names": [ + "--proxy-base-url" + ], + "usageDescription": "metro prepare: optional remote host bridge base URL for Metro access", + "usageLabel": "--proxy-base-url " + }, + { + "key": "metroBearerToken", + "names": [ + "--bearer-token" + ], + "usageDescription": "metro prepare: host bridge bearer token (prefer AGENT_DEVICE_PROXY_TOKEN or AGENT_DEVICE_METRO_BEARER_TOKEN)", + "usageLabel": "--bearer-token " + }, + { + "key": "metroPreparePort", + "names": [ + "--port" + ], + "usageDescription": "metro prepare: local Metro port (default: 8081)", + "usageLabel": "--port " + }, + { + "key": "metroListenHost", + "names": [ + "--listen-host" + ], + "usageDescription": "metro prepare: host Metro listens on (default: 0.0.0.0)", + "usageLabel": "--listen-host " + }, + { + "key": "metroStatusHost", + "names": [ + "--status-host" + ], + "usageDescription": "metro prepare: host used for local /status polling (default: 127.0.0.1)", + "usageLabel": "--status-host " + }, + { + "key": "metroStartupTimeoutMs", + "names": [ + "--startup-timeout-ms" + ], + "usageDescription": "metro prepare: timeout while waiting for Metro to become ready", + "usageLabel": "--startup-timeout-ms " + }, + { + "key": "metroProbeTimeoutMs", + "names": [ + "--probe-timeout-ms" + ], + "usageDescription": "metro prepare: timeout for /status and proxy bridge calls", + "usageLabel": "--probe-timeout-ms " + }, + { + "key": "metroRuntimeFile", + "names": [ + "--runtime-file" + ], + "usageDescription": "metro prepare: optional file path to persist the JSON result", + "usageLabel": "--runtime-file " + }, + { + "key": "metroNoReuseExisting", + "names": [ + "--no-reuse-existing" + ], + "usageDescription": "metro prepare: always start a fresh Metro process", + "usageLabel": "--no-reuse-existing" + }, + { + "key": "metroNoInstallDeps", + "names": [ + "--no-install-deps" + ], + "usageDescription": "metro prepare: skip package-manager install when node_modules is missing", + "usageLabel": "--no-install-deps" + } + ], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Prepare a local Metro runtime and optionally bridge it through a remote host", + "name": "metro", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [ + "prepare" + ], + "sessionRequirement": "Does not require an active session.", + "summary": "Prepare local Metro runtime", + "usage": "metro prepare --public-base-url [--project-root ] [--port ] [--kind auto|react-native|expo]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "networkInclude", + "names": [ + "--include" + ], + "usageDescription": "Network: include headers, bodies, or both in output", + "usageLabel": "--include summary|headers|body|all" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Dump recent HTTP(s) traffic parsed from the session app log", + "name": "network", + "notes": [ + "`network log` is an alias for `network dump`." + ], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "dump|log", + "limit?", + "include?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Show recent HTTP traffic", + "usage": "network dump [limit] [summary|headers|body|all] [--include summary|headers|body|all] | network log [limit] [summary|headers|body|all] [--include summary|headers|body|all]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "activity", + "names": [ + "--activity" + ], + "usageDescription": "Android app launch activity (package/Activity); not for URL opens", + "usageLabel": "--activity " + }, + { + "key": "saveScript", + "names": [ + "--save-script" + ], + "usageDescription": "Save session script (.ad) on close; optional custom output path", + "usageLabel": "--save-script [path]" + }, + { + "key": "relaunch", + "names": [ + "--relaunch" + ], + "usageDescription": "open: terminate app process before launching it", + "usageLabel": "--relaunch" + }, + { + "key": "surface", + "names": [ + "--surface" + ], + "usageDescription": "macOS session surface for open (defaults to app)", + "usageLabel": "--surface app|frontmost-app|desktop|menubar" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Boot device/simulator; optionally launch app or deep link URL (macOS also supports --surface app|frontmost-app|desktop|menubar)", + "name": "open", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "appOrUrl?", + "url?" + ], + "sessionRequirement": "Does not require an active session.", + "summary": "Open an app, deep link or URL, save replays", + "usage": "open [appOrUrl] [url] [--activity ] [--save-script [path]] [--relaunch] [--surface app|frontmost-app|desktop|menubar]" + }, + { + "aliases": [ + "metrics" + ], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Show session performance metrics", + "name": "perf", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [], + "sessionRequirement": "Usually expects an active session.", + "summary": "Show performance metrics", + "usage": "perf" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Pinch/zoom gesture (Apple simulator or macOS app session)", + "name": "pinch", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": false, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": false, + "androidDevice": false, + "androidTv": false + }, + "positionals": [ + "scale", + "x?", + "y?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Pinch/zoom gesture (Apple simulator or macOS app session)", + "usage": "pinch [x] [y]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "count", + "names": [ + "--count" + ], + "usageDescription": "Repeat count for press/swipe series", + "usageLabel": "--count " + }, + { + "key": "intervalMs", + "names": [ + "--interval-ms" + ], + "usageDescription": "Delay between press iterations", + "usageLabel": "--interval-ms " + }, + { + "key": "holdMs", + "names": [ + "--hold-ms" + ], + "usageDescription": "Press hold duration for each iteration", + "usageLabel": "--hold-ms " + }, + { + "key": "jitterPx", + "names": [ + "--jitter-px" + ], + "usageDescription": "Deterministic coordinate jitter radius for press", + "usageLabel": "--jitter-px " + }, + { + "key": "doubleTap", + "names": [ + "--double-tap" + ], + "usageDescription": "Use double-tap gesture per press iteration", + "usageLabel": "--double-tap" + }, + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Tap/press by coordinates, snapshot ref, or selector (supports repeated series)", + "name": "press", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "targetOrX", + "y?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Press by coordinates, ref, or selector", + "usage": "press " + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Simulate push notification payload delivery", + "name": "push", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": false, + "tvSimulator": true, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "bundleOrPackage", + "payloadOrJson" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Deliver push payload", + "usage": "push " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "fps", + "names": [ + "--fps" + ], + "usageDescription": "Record: target frames per second (iOS physical device runner)", + "usageLabel": "--fps " + }, + { + "key": "hideTouches", + "names": [ + "--hide-touches" + ], + "usageDescription": "Record: disable touch overlays in the final video", + "usageLabel": "--hide-touches" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "skills/agent-device/references/verification.md" + ], + "family": "recordTrace", + "helpDescription": "Start/stop screen recording", + "name": "record", + "notes": [], + "paths": [ + "src/daemon/handlers/record-trace.ts", + "src/platforms/ios/runner-client.ts", + "src/daemon/handlers/__tests__/record-trace.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "start|stop", + "path?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Start or stop screen recording", + "usage": "record start [path] [--fps ] [--hide-touches] | record stop" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Uninstall + install app from binary path", + "name": "reinstall", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "app", + "path" + ], + "sessionRequirement": "Does not require an active session.", + "summary": "Reinstall app from binary path", + "usage": "reinstall " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "replayUpdate", + "names": [ + "--update", + "-u" + ], + "usageDescription": "Replay: update selectors and rewrite replay file in place", + "usageLabel": "--update, -u" + } + ], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Replay a recorded session", + "name": "replay", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [ + "path" + ], + "sessionRequirement": "Creates or manages sessions internally.", + "summary": "Replay a recorded session", + "usage": "replay [--update, -u]" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Rotate device orientation on iOS and Android", + "name": "rotate", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": false, + "macosDesktop": false, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "orientation" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Rotate device orientation", + "usage": "rotate " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "out", + "names": [ + "--out" + ], + "usageDescription": "Output path", + "usageLabel": "--out " + }, + { + "key": "overlayRefs", + "names": [ + "--overlay-refs" + ], + "usageDescription": "Screenshot: draw current snapshot refs and target rectangles onto the saved PNG", + "usageLabel": "--overlay-refs" + }, + { + "key": "screenshotFullscreen", + "names": [ + "--fullscreen" + ], + "usageDescription": "Screenshot: capture the full screen instead of the app window", + "usageLabel": "--fullscreen" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Capture screenshot (macOS app sessions default to the app window; use --fullscreen for full desktop, or --overlay-refs to annotate the image with current refs)", + "name": "screenshot", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "path?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Capture screenshot (macOS app sessions default to the app window; use --fullscreen for full desktop, or --overlay-refs to annotate the image with current refs)", + "usage": "screenshot [path] [--out ] [--overlay-refs] [--fullscreen]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "pixels", + "names": [ + "--pixels" + ], + "usageDescription": "Scroll: explicit gesture distance in pixels", + "usageLabel": "--pixels " + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Scroll in direction (relative amount or explicit pixels)", + "name": "scroll", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "direction", + "amount?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Scroll in a direction", + "usage": "scroll [amount] [--pixels ]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "maxScrolls", + "names": [ + "--max-scrolls" + ], + "usageDescription": "scrollintoview: cap the number of scroll gestures before failing", + "usageLabel": "--max-scrolls " + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Scroll until text appears or a snapshot ref is brought into view", + "name": "scrollintoview", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "target" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Scroll until text or ref is visible", + "usage": "scrollintoview " + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "List active sessions", + "name": "session", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [ + "list?" + ], + "sessionRequirement": "Does not require an active session.", + "summary": "List active sessions", + "usage": "session list" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Toggle OS settings, appearance, and app permissions (macOS supports only settings appearance and settings permission ; wifi|airplane|location remain unsupported on macOS; mobile permission actions use the active session app)", + "name": "settings", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": false, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "setting", + "state", + "target?", + "mode?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Change OS settings and app permissions", + "usage": "settings | settings appearance | settings faceid | settings touchid | settings fingerprint | settings permission [full|limited] | settings permission " + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "snapshotDiff", + "names": [ + "--diff" + ], + "usageDescription": "Snapshot: show structural diff against the previous session baseline", + "usageLabel": "--diff" + }, + { + "key": "snapshotInteractiveOnly", + "names": [ + "-i" + ], + "usageDescription": "Snapshot: interactive elements only", + "usageLabel": "-i" + }, + { + "key": "snapshotCompact", + "names": [ + "-c" + ], + "usageDescription": "Snapshot: compact output (drop empty structure)", + "usageLabel": "-c" + }, + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Capture accessibility tree or diff against the previous session baseline", + "name": "snapshot", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [], + "sessionRequirement": "Usually expects an active session.", + "summary": "Capture accessibility tree or diff against the previous session baseline", + "usage": "snapshot [--diff] [-i] [-c] [-d ] [-s ] [--raw]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "count", + "names": [ + "--count" + ], + "usageDescription": "Repeat count for press/swipe series", + "usageLabel": "--count " + }, + { + "key": "pauseMs", + "names": [ + "--pause-ms" + ], + "usageDescription": "Delay between swipe iterations", + "usageLabel": "--pause-ms " + }, + { + "key": "pattern", + "names": [ + "--pattern" + ], + "usageDescription": "Swipe repeat pattern", + "usageLabel": "--pattern one-way|ping-pong" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Swipe coordinates with optional repeat pattern", + "name": "swipe", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "x1", + "y1", + "x2", + "y2", + "durationMs?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Swipe coordinates", + "usage": "swipe [durationMs] [--count ] [--pause-ms ] [--pattern one-way|ping-pong]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "replayUpdate", + "names": [ + "--update", + "-u" + ], + "usageDescription": "Replay: update selectors and rewrite replay file in place", + "usageLabel": "--update, -u" + }, + { + "key": "failFast", + "names": [ + "--fail-fast" + ], + "usageDescription": "Test: stop the suite after the first failing script", + "usageLabel": "--fail-fast" + }, + { + "key": "timeoutMs", + "names": [ + "--timeout" + ], + "usageDescription": "Test: maximum wall-clock time per script attempt", + "usageLabel": "--timeout " + }, + { + "key": "retries", + "names": [ + "--retries" + ], + "usageDescription": "Test: retry each failed script up to n additional times", + "usageLabel": "--retries " + }, + { + "key": "artifactsDir", + "names": [ + "--artifacts-dir" + ], + "usageDescription": "Test: root directory for suite artifacts", + "usageLabel": "--artifacts-dir " + }, + { + "key": "reportJunit", + "names": [ + "--report-junit" + ], + "usageDescription": "Test: write a JUnit XML report for the replay suite", + "usageLabel": "--report-junit " + } + ], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/replay-e2e.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/bootstrap-install.md" + ], + "family": "session", + "helpDescription": "Run one or more .ad scripts as a serial test suite", + "name": "test", + "notes": [], + "paths": [ + "src/daemon/handlers/session.ts", + "src/daemon/session-store.ts", + "src/daemon/handlers/__tests__/session.test.ts" + ], + "platformSupport": null, + "positionals": [ + "pathOrGlob" + ], + "sessionRequirement": "Creates or manages sessions internally.", + "summary": "Run .ad test suites", + "usage": "test ..." + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": false, + "docs": [ + "website/docs/docs/commands.md", + "skills/agent-device/references/verification.md" + ], + "family": "recordTrace", + "helpDescription": "Start/stop trace log capture", + "name": "trace", + "notes": [], + "paths": [ + "src/daemon/handlers/record-trace.ts", + "src/platforms/ios/runner-client.ts", + "src/daemon/handlers/__tests__/record-trace.test.ts" + ], + "platformSupport": null, + "positionals": [ + "start|stop", + "path?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Start or stop trace capture", + "usage": "trace start [path] | trace stop [path]" + }, + { + "aliases": [], + "allowedFlags": [], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Trigger app-defined event hook via deep link template", + "name": "trigger-app-event", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "event", + "payloadJson?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Trigger app event hook", + "usage": "trigger-app-event [payloadJson]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "delayMs", + "names": [ + "--delay-ms" + ], + "usageDescription": "Delay between typed characters", + "usageLabel": "--delay-ms " + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/selectors.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md" + ], + "family": "interaction", + "helpDescription": "Type text in focused field", + "name": "type", + "notes": [], + "paths": [ + "src/daemon/handlers/interaction.ts", + "src/daemon/selectors.ts", + "src/daemon/handlers/__tests__/interaction.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "text" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Type text in focused field", + "usage": "type [--delay-ms ]" + }, + { + "aliases": [], + "allowedFlags": [ + { + "key": "snapshotDepth", + "names": [ + "--depth", + "-d" + ], + "usageDescription": "Snapshot: limit snapshot depth", + "usageLabel": "--depth, -d " + }, + { + "key": "snapshotScope", + "names": [ + "--scope", + "-s" + ], + "usageDescription": "Snapshot: scope snapshot to label/identifier", + "usageLabel": "--scope, -s " + }, + { + "key": "snapshotRaw", + "names": [ + "--raw" + ], + "usageDescription": "Snapshot: raw node output", + "usageLabel": "--raw" + } + ], + "capabilityChecked": true, + "docs": [ + "website/docs/docs/commands.md", + "website/docs/docs/snapshots.md", + "skills/agent-device/SKILL.md", + "skills/agent-device/references/exploration.md", + "skills/agent-device/references/debugging.md" + ], + "family": "snapshot", + "helpDescription": "Wait for duration, text, ref, or selector to appear", + "name": "wait", + "notes": [], + "paths": [ + "src/daemon/handlers/snapshot.ts", + "src/daemon/snapshot-processing.ts", + "src/daemon/handlers/__tests__/snapshot-handler.test.ts" + ], + "platformSupport": { + "iosSimulator": true, + "iosDevice": true, + "tvSimulator": true, + "macosDesktop": true, + "androidEmulator": true, + "androidDevice": true, + "androidTv": true + }, + "positionals": [ + "durationOrSelector", + "timeoutMs?" + ], + "sessionRequirement": "Usually expects an active session.", + "summary": "Wait for time, text, ref, or selector", + "usage": "wait |text |@ref| [timeoutMs]" + } + ] +} diff --git a/knowledge/index.md b/knowledge/index.md new file mode 100644 index 00000000..e39b2545 --- /dev/null +++ b/knowledge/index.md @@ -0,0 +1,71 @@ + + +# Knowledge Index + +This directory is the generated agent-facing map of the repo. The source of truth stays in code, docs, and skills; `pnpm kb:build` compiles that material into a cheaper starting point for exploration and drift checks. + +## Primary Sources + +- [AGENTS.md](../AGENTS.md) +- [src/utils/command-schema.ts](../src/utils/command-schema.ts) +- [src/core/capabilities.ts](../src/core/capabilities.ts) +- [skills/agent-device/SKILL.md](../skills/agent-device/SKILL.md) +- [website/docs/docs/commands.md](../website/docs/docs/commands.md) + +## Refresh Workflow + +1. Run `pnpm kb:build` after changing command schema, capabilities, docs, or skills. +2. Run `pnpm kb:check` in CI or before merging to catch stale generated files. +3. Start investigation here, then jump to the linked source files for the owning command family. + +## Command Index + +| Command | Summary | Page | +| --- | --- | --- | +| `alert` | Inspect or handle iOS/macOS alerts | [page](./commands/alert.md) | +| `app-switcher` | Open app switcher | [page](./commands/app-switcher.md) | +| `apps` | List installed apps | [page](./commands/apps.md) | +| `appstate` | Show foreground app/activity | [page](./commands/appstate.md) | +| `back` | Go back | [page](./commands/back.md) | +| `batch` | Run multiple commands | [page](./commands/batch.md) | +| `boot` | Boot target device/simulator | [page](./commands/boot.md) | +| `click` | Tap by coordinates, ref, or selector | [page](./commands/click.md) | +| `clipboard` | Read or write device clipboard text | [page](./commands/clipboard.md) | +| `close` | Close app or end session | [page](./commands/close.md) | +| `devices` | List available devices | [page](./commands/devices.md) | +| `diff` | Diff snapshot or screenshot | [page](./commands/diff.md) | +| `ensure-simulator` | Ensure iOS simulator exists | [page](./commands/ensure-simulator.md) | +| `fill` | Tap then type | [page](./commands/fill.md) | +| `find` | Find an element and act | [page](./commands/find.md) | +| `focus` | Focus input at coordinates | [page](./commands/focus.md) | +| `get` | Get text or attrs by ref or selector | [page](./commands/get.md) | +| `home` | Go home | [page](./commands/home.md) | +| `install` | Install app from binary path | [page](./commands/install.md) | +| `install-from-source` | Install app from a URL source | [page](./commands/install-from-source.md) | +| `is` | Assert UI state | [page](./commands/is.md) | +| `keyboard` | Inspect or dismiss the device keyboard | [page](./commands/keyboard.md) | +| `logs` | Manage session app logs | [page](./commands/logs.md) | +| `longpress` | Long press by coordinates | [page](./commands/longpress.md) | +| `metro` | Prepare local Metro runtime | [page](./commands/metro.md) | +| `network` | Show recent HTTP traffic | [page](./commands/network.md) | +| `open` | Open an app, deep link or URL, save replays | [page](./commands/open.md) | +| `perf` | Show performance metrics | [page](./commands/perf.md) | +| `pinch` | Pinch/zoom gesture (Apple simulator or macOS app session) | [page](./commands/pinch.md) | +| `press` | Press by coordinates, ref, or selector | [page](./commands/press.md) | +| `push` | Deliver push payload | [page](./commands/push.md) | +| `record` | Start or stop screen recording | [page](./commands/record.md) | +| `reinstall` | Reinstall app from binary path | [page](./commands/reinstall.md) | +| `replay` | Replay a recorded session | [page](./commands/replay.md) | +| `rotate` | Rotate device orientation | [page](./commands/rotate.md) | +| `screenshot` | Capture screenshot (macOS app sessions default to the app window; use --fullscreen for full desktop, or --overlay-refs to annotate the image with current refs) | [page](./commands/screenshot.md) | +| `scroll` | Scroll in a direction | [page](./commands/scroll.md) | +| `scrollintoview` | Scroll until text or ref is visible | [page](./commands/scrollintoview.md) | +| `session` | List active sessions | [page](./commands/session.md) | +| `settings` | Change OS settings and app permissions | [page](./commands/settings.md) | +| `snapshot` | Capture accessibility tree or diff against the previous session baseline | [page](./commands/snapshot.md) | +| `swipe` | Swipe coordinates | [page](./commands/swipe.md) | +| `test` | Run .ad test suites | [page](./commands/test.md) | +| `trace` | Start or stop trace capture | [page](./commands/trace.md) | +| `trigger-app-event` | Trigger app event hook | [page](./commands/trigger-app-event.md) | +| `type` | Type text in focused field | [page](./commands/type.md) | +| `wait` | Wait for time, text, ref, or selector | [page](./commands/wait.md) | diff --git a/knowledge/platform-matrix.md b/knowledge/platform-matrix.md new file mode 100644 index 00000000..f434fd8e --- /dev/null +++ b/knowledge/platform-matrix.md @@ -0,0 +1,55 @@ + + +# Platform Matrix + +Generated from `src/core/capabilities.ts` by evaluating each command against a small set of representative device targets. + +| Command | iOS sim | iOS device | tvOS sim | macOS | Android emu | Android device | Android TV | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `alert` | Yes | No | Yes | Yes | No | No | No | +| `app-switcher` | Yes | Yes | Yes | No | Yes | Yes | Yes | +| `apps` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `appstate` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `back` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `batch` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `boot` | Yes | Yes | Yes | No | Yes | Yes | Yes | +| `click` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `clipboard` | Yes | No | Yes | Yes | Yes | Yes | Yes | +| `close` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `devices` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `diff` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `ensure-simulator` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `fill` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `find` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `focus` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `get` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `home` | Yes | Yes | Yes | No | Yes | Yes | Yes | +| `install` | Yes | Yes | Yes | No | Yes | Yes | Yes | +| `install-from-source` | Yes | Yes | Yes | No | Yes | Yes | Yes | +| `is` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `keyboard` | Yes | Yes | No | No | Yes | Yes | Yes | +| `logs` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `longpress` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `metro` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `network` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `open` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `perf` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `pinch` | Yes | No | Yes | Yes | No | No | No | +| `press` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `push` | Yes | No | Yes | No | Yes | Yes | Yes | +| `record` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `reinstall` | Yes | Yes | Yes | No | Yes | Yes | Yes | +| `replay` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `rotate` | Yes | Yes | No | No | Yes | Yes | Yes | +| `screenshot` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `scroll` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `scrollintoview` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `session` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `settings` | Yes | No | Yes | Yes | Yes | Yes | Yes | +| `snapshot` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `swipe` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `test` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `trace` | n/a | n/a | n/a | n/a | n/a | n/a | n/a | +| `trigger-app-event` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `type` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | +| `wait` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | diff --git a/package.json b/package.json index fddfa92d..5439b9b8 100644 --- a/package.json +++ b/package.json @@ -30,10 +30,12 @@ "build:macos-helper": "swift build -c release --package-path macos-helper", "build:all": "pnpm build:node && pnpm build:xcuitest", "ad": "node bin/agent-device.mjs", + "kb:build": "node --experimental-strip-types scripts/build-knowledge.mjs", + "kb:check": "node --experimental-strip-types scripts/check-knowledge.mjs", "lint": "oxlint . --deny-warnings", "format": "oxfmt --write src test skills package.json tsconfig.json .oxlintrc.json .oxfmtrc.json", "check:quick": "pnpm lint && pnpm typecheck", - "check:tooling": "pnpm lint && pnpm typecheck && pnpm build", + "check:tooling": "pnpm lint && pnpm typecheck && pnpm build && pnpm kb:check", "check:unit": "pnpm test:unit && pnpm test:smoke", "check": "pnpm check:tooling && pnpm check:unit", "prepack": "pnpm build:all", diff --git a/scripts/build-knowledge.mjs b/scripts/build-knowledge.mjs new file mode 100644 index 00000000..d4ec40e6 --- /dev/null +++ b/scripts/build-knowledge.mjs @@ -0,0 +1,5 @@ +import { buildKnowledgeFiles, writeKnowledgeFiles } from './knowledge-lib.mjs'; + +const files = await buildKnowledgeFiles(); +await writeKnowledgeFiles(files); +console.log(`Generated ${files.size} knowledge files.`); diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjs new file mode 100644 index 00000000..7233215d --- /dev/null +++ b/scripts/check-knowledge.mjs @@ -0,0 +1,22 @@ +import { buildKnowledgeFiles, checkKnowledgeFiles } from './knowledge-lib.mjs'; + +const files = await buildKnowledgeFiles(); +const result = await checkKnowledgeFiles(files); + +if (result.ok) { + console.log(`knowledge/ is up to date (${files.size} files checked).`); + process.exit(0); +} + +if (result.missing.length > 0) { + console.error(`Missing files:\n${result.missing.map((entry) => `- ${entry}`).join('\n')}`); +} +if (result.extra.length > 0) { + console.error(`Unexpected files:\n${result.extra.map((entry) => `- ${entry}`).join('\n')}`); +} +if (result.changed.length > 0) { + console.error(`Stale files:\n${result.changed.map((entry) => `- ${entry}`).join('\n')}`); +} + +console.error('Run `pnpm kb:build` to refresh the generated knowledge layer.'); +process.exit(1); diff --git a/scripts/knowledge-lib.mjs b/scripts/knowledge-lib.mjs new file mode 100644 index 00000000..dd7fc69e --- /dev/null +++ b/scripts/knowledge-lib.mjs @@ -0,0 +1,674 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +import { + buildCommandUsageText, + getCliCommandNames, + getCommandSchema, + getFlagDefinitions, + getSchemaCapabilityKeys, +} from '../src/utils/command-schema.ts'; +import { isCommandSupportedOnDevice } from '../src/core/capabilities.ts'; + +const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url)); +const ROOT_DIR = path.resolve(SCRIPT_DIR, '..'); +const KNOWLEDGE_DIR = path.join(ROOT_DIR, 'knowledge'); +const GENERATED_HEADER = ''; + +const COMMAND_ALIASES = { + longpress: ['long-press'], + perf: ['metrics'], +}; + +const COMMAND_NOTES = { + back: ['`back --in-app` is the explicit alias for the default app-owned behavior.'], + diff: ['`snapshot --diff` routes to `diff snapshot`.'], + network: ['`network log` is an alias for `network dump`.'], +}; + +const SAMPLE_DEVICES = [ + { + key: 'iosSimulator', + label: 'iOS sim', + device: { + id: 'ios-sim-mobile', + kind: 'simulator', + name: 'iPhone Simulator', + platform: 'ios', + target: 'mobile', + }, + }, + { + key: 'iosDevice', + label: 'iOS device', + device: { + id: 'ios-device-mobile', + kind: 'device', + name: 'iPhone', + platform: 'ios', + target: 'mobile', + }, + }, + { + key: 'tvSimulator', + label: 'tvOS sim', + device: { + id: 'tvos-sim', + kind: 'simulator', + name: 'Apple TV Simulator', + platform: 'ios', + target: 'tv', + }, + }, + { + key: 'macosDesktop', + label: 'macOS', + device: { + id: 'macos-desktop', + kind: 'device', + name: 'Mac', + platform: 'macos', + target: 'desktop', + }, + }, + { + key: 'androidEmulator', + label: 'Android emu', + device: { + id: 'android-emu-mobile', + kind: 'emulator', + name: 'Android Emulator', + platform: 'android', + target: 'mobile', + }, + }, + { + key: 'androidDevice', + label: 'Android device', + device: { + id: 'android-device-mobile', + kind: 'device', + name: 'Android Phone', + platform: 'android', + target: 'mobile', + }, + }, + { + key: 'androidTv', + label: 'Android TV', + device: { + id: 'android-emu-tv', + kind: 'emulator', + name: 'Android TV Emulator', + platform: 'android', + target: 'tv', + }, + }, +]; + +const FAMILY_DEFINITIONS = [ + { + name: 'session', + commands: [ + 'app-switcher', + 'appstate', + 'apps', + 'batch', + 'boot', + 'close', + 'devices', + 'ensure-simulator', + 'home', + 'install', + 'install-from-source', + 'logs', + 'metro', + 'network', + 'open', + 'perf', + 'push', + 'reinstall', + 'replay', + 'session', + 'test', + ], + primarySources: [ + 'src/daemon/handlers/session.ts', + 'src/daemon/session-store.ts', + 'src/daemon/handlers/__tests__/session.test.ts', + ], + docs: [ + 'website/docs/docs/commands.md', + 'website/docs/docs/replay-e2e.md', + 'skills/agent-device/SKILL.md', + 'skills/agent-device/references/bootstrap-install.md', + ], + }, + { + name: 'interaction', + commands: [ + 'back', + 'click', + 'fill', + 'focus', + 'get', + 'is', + 'longpress', + 'pinch', + 'press', + 'scroll', + 'scrollintoview', + 'swipe', + 'type', + ], + primarySources: [ + 'src/daemon/handlers/interaction.ts', + 'src/daemon/selectors.ts', + 'src/daemon/handlers/__tests__/interaction.test.ts', + ], + docs: [ + 'website/docs/docs/commands.md', + 'website/docs/docs/selectors.md', + 'skills/agent-device/SKILL.md', + 'skills/agent-device/references/exploration.md', + ], + }, + { + name: 'snapshot', + commands: [ + 'alert', + 'clipboard', + 'diff', + 'keyboard', + 'rotate', + 'screenshot', + 'settings', + 'snapshot', + 'trigger-app-event', + 'wait', + ], + primarySources: [ + 'src/daemon/handlers/snapshot.ts', + 'src/daemon/snapshot-processing.ts', + 'src/daemon/handlers/__tests__/snapshot-handler.test.ts', + ], + docs: [ + 'website/docs/docs/commands.md', + 'website/docs/docs/snapshots.md', + 'skills/agent-device/SKILL.md', + 'skills/agent-device/references/exploration.md', + 'skills/agent-device/references/debugging.md', + ], + }, + { + name: 'find', + commands: ['find'], + primarySources: [ + 'src/daemon/handlers/find.ts', + 'src/daemon/selectors.ts', + 'src/daemon/handlers/__tests__/find.test.ts', + ], + docs: [ + 'website/docs/docs/commands.md', + 'website/docs/docs/selectors.md', + 'skills/agent-device/references/exploration.md', + ], + }, + { + name: 'recordTrace', + commands: ['record', 'trace'], + primarySources: [ + 'src/daemon/handlers/record-trace.ts', + 'src/platforms/ios/runner-client.ts', + 'src/daemon/handlers/__tests__/record-trace.test.ts', + ], + docs: ['website/docs/docs/commands.md', 'skills/agent-device/references/verification.md'], + }, +]; + +const ROUTES = [ + { + task: 'Learn the CLI surface or flag schema', + paths: ['src/utils/command-schema.ts', 'src/utils/args.ts', 'knowledge/index.md'], + }, + { + task: 'Trace session lifecycle and session-owned commands', + paths: [ + 'src/daemon/handlers/session.ts', + 'src/daemon/session-store.ts', + 'skills/agent-device/references/bootstrap-install.md', + ], + }, + { + task: 'Trace selectors and element interactions', + paths: [ + 'src/daemon/handlers/interaction.ts', + 'src/daemon/selectors.ts', + 'skills/agent-device/references/exploration.md', + ], + }, + { + task: 'Trace snapshot, wait, alerts, settings, or screenshot behavior', + paths: [ + 'src/daemon/handlers/snapshot.ts', + 'src/daemon/snapshot-processing.ts', + 'website/docs/docs/snapshots.md', + ], + }, + { + task: 'Trace replay, test, record, and trace flows', + paths: [ + 'src/daemon/handlers/record-trace.ts', + 'src/daemon/handlers/session-replay.ts', + 'website/docs/docs/replay-e2e.md', + ], + }, + { + task: 'Trace Apple runner behavior', + paths: [ + 'src/platforms/ios/runner-contract.ts', + 'src/platforms/ios/runner-client.ts', + 'src/platforms/ios/runner-transport.ts', + ], + }, +]; + +const SESSION_REQUIREMENTS = { + noSessionRequired: new Set([ + 'apps', + 'boot', + 'devices', + 'ensure-simulator', + 'install', + 'install-from-source', + 'metro', + 'open', + 'reinstall', + 'session', + ]), + managesOwnSessions: new Set(['batch', 'replay', 'test']), +}; + +function normalizeText(value) { + return value.replace(/\r\n/g, '\n'); +} + +function compareStrings(a, b) { + return a.localeCompare(b, 'en'); +} + +function getFlagMetadataByKey() { + const byKey = new Map(); + for (const definition of getFlagDefinitions()) { + const list = byKey.get(definition.key); + if (list) list.push(definition); + else byKey.set(definition.key, [definition]); + } + return byKey; +} + +function buildFamilyDefinitionMap() { + const commandToFamily = new Map(); + for (const family of FAMILY_DEFINITIONS) { + for (const command of family.commands) { + const existing = commandToFamily.get(command); + if (existing) { + throw new Error(`Command ${command} is assigned to multiple knowledge families.`); + } + commandToFamily.set(command, family); + } + } + return commandToFamily; +} + +function getSessionRequirement(command) { + if (SESSION_REQUIREMENTS.noSessionRequired.has(command)) { + return 'Does not require an active session.'; + } + if (SESSION_REQUIREMENTS.managesOwnSessions.has(command)) { + return 'Creates or manages sessions internally.'; + } + if (command === 'close') { + return 'Requires an active session to close it.'; + } + return 'Usually expects an active session.'; +} + +function buildPlatformSupport(command, capabilityCommands) { + if (!capabilityCommands.has(command)) return null; + return Object.fromEntries( + SAMPLE_DEVICES.map((sample) => [ + sample.key, + isCommandSupportedOnDevice(command, sample.device), + ]), + ); +} + +function formatBool(value) { + return value ? 'Yes' : 'No'; +} + +function formatLink(fromPath, targetPath) { + const relative = path.relative(path.dirname(fromPath), path.join(ROOT_DIR, targetPath)); + return `[${targetPath}](${relative.split(path.sep).join('/')})`; +} + +function formatListSection(fromPath, title, entries) { + if (entries.length === 0) return `## ${title}\n\n- None`; + return `## ${title}\n\n${entries.map((entry) => `- ${formatLink(fromPath, entry)}`).join('\n')}`; +} + +function buildCommandManifest() { + const flagMetadataByKey = getFlagMetadataByKey(); + const capabilityCommands = new Set(getSchemaCapabilityKeys()); + const familyDefinitionByCommand = buildFamilyDefinitionMap(); + return getCliCommandNames() + .sort(compareStrings) + .map((command) => { + const schema = getCommandSchema(command); + if (!schema) throw new Error(`Missing schema for command ${command}`); + const family = familyDefinitionByCommand.get(command) ?? null; + const allowedFlags = schema.allowedFlags.flatMap((key) => { + return (flagMetadataByKey.get(key) ?? []).map((definition) => ({ + key: definition.key, + names: [...definition.names], + usageDescription: definition.usageDescription ?? '', + usageLabel: definition.usageLabel ?? definition.names[0], + })); + }); + return { + aliases: COMMAND_ALIASES[command] ?? [], + allowedFlags, + capabilityChecked: capabilityCommands.has(command), + docs: family?.docs ?? ['website/docs/docs/commands.md'], + family: family?.name ?? 'unclassified', + helpDescription: schema.helpDescription, + name: command, + notes: COMMAND_NOTES[command] ?? [], + paths: family?.primarySources ?? [], + platformSupport: buildPlatformSupport(command, capabilityCommands), + positionals: [...schema.positionalArgs], + sessionRequirement: getSessionRequirement(command), + summary: schema.summary ?? schema.helpDescription, + usage: + buildCommandUsageText(command) + ?.split('\n', 1)[0] + .replace(/^agent-device\s+/, '') ?? command, + }; + }); +} + +function renderCommandPage(command) { + const filePath = path.join(KNOWLEDGE_DIR, 'commands', `${command.name}.md`); + const aliasBlock = + command.aliases.length > 0 + ? command.aliases.map((alias) => `- \`${alias}\``).join('\n') + : '- None'; + const notesBlock = + command.notes.length > 0 ? command.notes.map((note) => `- ${note}`).join('\n') : '- None'; + const flagsBlock = + command.allowedFlags.length > 0 + ? command.allowedFlags + .map((flag) => `- \`${flag.usageLabel}\`: ${flag.usageDescription}`) + .join('\n') + : '- None'; + + const platformBlock = + command.platformSupport === null + ? '_Capability checks are not defined for this command in `command-schema.ts`._' + : [ + '| Target | Supported |', + '| --- | --- |', + ...SAMPLE_DEVICES.map( + (sample) => `| ${sample.label} | ${formatBool(command.platformSupport[sample.key])} |`, + ), + ].join('\n'); + + const sections = [ + GENERATED_HEADER, + '', + `# ${command.name}`, + '', + command.summary, + '', + '## Usage', + '', + '```bash', + `agent-device ${command.usage}`, + '```', + '', + '## Session Requirement', + '', + command.sessionRequirement, + '', + '## Aliases', + '', + aliasBlock, + '', + '## Notes', + '', + notesBlock, + '', + '## Allowed Flags', + '', + flagsBlock, + '', + '## Platform Coverage', + '', + platformBlock, + '', + formatListSection(filePath, 'Primary Source Paths', command.paths), + '', + formatListSection(filePath, 'Docs And Skills', command.docs), + ]; + return `${sections.join('\n')}\n`; +} + +function renderIndex(commands) { + const filePath = path.join(KNOWLEDGE_DIR, 'index.md'); + const commandLines = commands + .map( + (command) => + `| \`${command.name}\` | ${command.summary} | [page](./commands/${command.name}.md) |`, + ) + .join('\n'); + const sourceLinks = [ + 'AGENTS.md', + 'src/utils/command-schema.ts', + 'src/core/capabilities.ts', + 'skills/agent-device/SKILL.md', + 'website/docs/docs/commands.md', + ] + .map((entry) => `- ${formatLink(filePath, entry)}`) + .join('\n'); + + return `${GENERATED_HEADER} + +# Knowledge Index + +This directory is the generated agent-facing map of the repo. The source of truth stays in code, docs, and skills; \`pnpm kb:build\` compiles that material into a cheaper starting point for exploration and drift checks. + +## Primary Sources + +${sourceLinks} + +## Refresh Workflow + +1. Run \`pnpm kb:build\` after changing command schema, capabilities, docs, or skills. +2. Run \`pnpm kb:check\` in CI or before merging to catch stale generated files. +3. Start investigation here, then jump to the linked source files for the owning command family. + +## Command Index + +| Command | Summary | Page | +| --- | --- | --- | +${commandLines} +`; +} + +function renderPlatformMatrix(commands) { + const rows = commands + .map((command) => { + if (command.platformSupport === null) { + return `| \`${command.name}\` | n/a | n/a | n/a | n/a | n/a | n/a | n/a |`; + } + return ( + [ + `| \`${command.name}\``, + formatBool(command.platformSupport.iosSimulator), + formatBool(command.platformSupport.iosDevice), + formatBool(command.platformSupport.tvSimulator), + formatBool(command.platformSupport.macosDesktop), + formatBool(command.platformSupport.androidEmulator), + formatBool(command.platformSupport.androidDevice), + formatBool(command.platformSupport.androidTv), + ].join(' | ') + ' |' + ); + }) + .join('\n'); + + return `${GENERATED_HEADER} + +# Platform Matrix + +Generated from \`src/core/capabilities.ts\` by evaluating each command against a small set of representative device targets. + +| Command | iOS sim | iOS device | tvOS sim | macOS | Android emu | Android device | Android TV | +| --- | --- | --- | --- | --- | --- | --- | --- | +${rows} +`; +} + +function renderAgentRoutes() { + const filePath = path.join(KNOWLEDGE_DIR, 'agent-routes.md'); + const sections = ROUTES.map((route) => { + const paths = route.paths.map((entry) => `- ${formatLink(filePath, entry)}`).join('\n'); + return `## ${route.task}\n\n${paths}`; + }).join('\n\n'); + + return `${GENERATED_HEADER} + +# Agent Routes + +Use this page when deciding where to read first. The goal is to keep the first hop narrow and close to the owning module. + +${sections} +`; +} + +function renderIndexJson(commands) { + return `${JSON.stringify( + { + generatedBy: 'pnpm kb:build', + routes: ROUTES, + sampleTargets: SAMPLE_DEVICES.map((sample) => ({ + key: sample.key, + label: sample.label, + })), + sourceFiles: [ + 'AGENTS.md', + 'src/utils/command-schema.ts', + 'src/core/capabilities.ts', + 'skills/agent-device/SKILL.md', + 'website/docs/docs/commands.md', + ], + commands, + }, + null, + 2, + )}\n`; +} + +export async function buildKnowledgeFiles() { + const commands = buildCommandManifest(); + const files = new Map(); + files.set('knowledge/index.md', renderIndex(commands)); + files.set('knowledge/platform-matrix.md', renderPlatformMatrix(commands)); + files.set('knowledge/agent-routes.md', renderAgentRoutes()); + files.set('knowledge/index.json', renderIndexJson(commands)); + for (const command of commands) { + files.set(`knowledge/commands/${command.name}.md`, renderCommandPage(command)); + } + + const expectedPaths = new Set( + [...files.keys()].map((relativePath) => path.join(ROOT_DIR, relativePath)), + ); + for (const [relativePath] of files) { + if (relativePath.endsWith('.md')) { + const fullPath = path.join(ROOT_DIR, relativePath); + const links = [...normalizeText(files.get(relativePath)).matchAll(/\]\(([^)]+)\)/g)].map( + (match) => match[1], + ); + for (const link of links) { + if (link.startsWith('./') || link.startsWith('../')) { + const resolved = path.resolve(path.dirname(fullPath), link); + if (expectedPaths.has(resolved)) continue; + await fs.access(resolved); + } + } + } + } + return files; +} + +export async function writeKnowledgeFiles(files) { + await fs.rm(KNOWLEDGE_DIR, { force: true, recursive: true }); + for (const [relativePath, content] of files) { + const outputPath = path.join(ROOT_DIR, relativePath); + await fs.mkdir(path.dirname(outputPath), { recursive: true }); + await fs.writeFile(outputPath, normalizeText(content), 'utf8'); + } +} + +async function listKnowledgeFiles() { + const files = []; + async function walk(currentDir) { + const entries = await fs.readdir(currentDir, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = path.join(currentDir, entry.name); + if (entry.isDirectory()) { + await walk(fullPath); + continue; + } + files.push(path.relative(ROOT_DIR, fullPath).split(path.sep).join('/')); + } + } + + try { + await walk(KNOWLEDGE_DIR); + } catch (error) { + if (error && error.code === 'ENOENT') return []; + throw error; + } + return files.sort(compareStrings); +} + +export async function checkKnowledgeFiles(files) { + const expectedPaths = [...files.keys()].sort(compareStrings); + const actualPaths = await listKnowledgeFiles(); + const missing = expectedPaths.filter((entry) => !actualPaths.includes(entry)); + const extra = actualPaths.filter((entry) => !expectedPaths.includes(entry)); + const changed = []; + + for (const relativePath of expectedPaths) { + const fullPath = path.join(ROOT_DIR, relativePath); + let current = null; + try { + current = await fs.readFile(fullPath, 'utf8'); + } catch (error) { + if (error && error.code === 'ENOENT') continue; + throw error; + } + if (current !== null && normalizeText(current) !== normalizeText(files.get(relativePath))) { + changed.push(relativePath); + } + } + + return { + changed, + extra, + missing, + ok: changed.length === 0 && extra.length === 0 && missing.length === 0, + }; +}