adb-ready 0.1.2 → 0.3.0

package/docs/agent-integration.md

@@ -0,0 +1,222 @@
+# AI agent integration
+
+ADB Ready exposes Android workflows to local AI agents through a typed Model
+Context Protocol (MCP) server. The agent works with the same deterministic
+target, application identity, verification rules, and structured problems as
+the CLI—without receiving a generic shell or raw ADB command.
+
+## Install and verify
+
+Pin ADB Ready in the Android project the agent will work on:
+
+```bash
+npm install --save-dev --save-exact adb-ready
+node ./node_modules/adb-ready/dist/cli.js doctor
+```
+
+The MCP server uses standard input/output and must be started from the project
+root:
+
+```bash
+node ./node_modules/adb-ready/dist/cli.js mcp
+```
+
+Do not run that command by hand for normal use; the MCP client starts and stops
+it. ADB Ready does not open an MCP network listener.
+
+## Connect an agent
+
+Preview the exact project change first, then apply it:
+
+```bash
+adb-ready agent setup codex --dry-run
+adb-ready agent setup codex
+```
+
+Replace `codex` with `claude-code`, `cursor`, or `vscode`. Existing unrelated
+configuration is preserved. An existing `adb-ready` entry with different
+settings is reported as a conflict and is never replaced automatically.
+
+### Codex
+
+Create a project-scoped `.codex/config.toml`:
+
+```toml
+[mcp_servers.adb_ready]
+command = "node"
+args = ["./node_modules/adb-ready/dist/cli.js", "mcp"]
+default_tools_approval_mode = "writes"
+```
+
+Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share Codex MCP
+configuration. See the [official Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp).
+
+### Claude Code
+
+Run this from the project root:
+
+```bash
+claude mcp add --scope project adb-ready -- node ./node_modules/adb-ready/dist/cli.js mcp
+claude mcp get adb-ready
+```
+
+Claude Code stores project-scoped servers in `.mcp.json` and asks users to
+approve them. See the [official Claude Code MCP guide](https://docs.anthropic.com/en/docs/claude-code/mcp).
+
+### Cursor
+
+Create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "adb-ready": {
+      "command": "node",
+      "args": ["./node_modules/adb-ready/dist/cli.js", "mcp"]
+    }
+  }
+}
+```
+
+See the [official Cursor MCP guide](https://docs.cursor.com/context/model-context-protocol).
+
+### VS Code and GitHub Copilot
+
+Create `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "adb-ready": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/node_modules/adb-ready/dist/cli.js", "mcp"]
+    }
+  }
+}
+```
+
+See the [official VS Code MCP guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
+
+### Windsurf
+
+Windsurf currently keeps MCP configuration in a user-scoped file. Generate a
+project-bound snippet and merge it through Windsurf MCP settings:
+
+```bash
+adb-ready agent setup windsurf
+```
+
+ADB Ready deliberately does not edit this global file. The generated entry
+uses an absolute local package path and `ADB_READY_MCP_PROJECT_ROOT` so Cascade
+still resolves the intended project. See the [official Windsurf MCP guide](https://docs.windsurf.com/windsurf/cascade/mcp).
+
+### Other MCP clients
+
+Generate a standard `mcpServers` entry:
+
+```bash
+adb-ready agent setup generic
+```
+
+Merge the result at the location required by the client and ensure the server
+starts in the Android project root.
+
+## Recommended agent workflow
+
+Ask the agent to follow this sequence:
+
+1. Call `doctor` when host or ADB health is unknown.
+2. Call `ensure_ready`; provide an exact device serial, configured alias, or
+   transport ID when more than one ready target exists.
+3. Start the configured stack with `start_dev_session` when it is not already
+   running; retain its task handle and poll `get_dev_session` without holding a
+   tool call open.
+4. Resolve the project app with `resolve_app`.
+5. Use `inspect_app` or `inspect_ui` for bounded current evidence.
+6. Perform one typed action, then inspect again instead of assuming success.
+7. Use `get_session_problems` or `compile_debug_context` for an existing
+   development session.
+
+The first successful `ensure_ready` binds one target to that MCP connection and
+returns a `targetHandle`. Pass that handle to later target-bound calls when the
+client supports workflow state. A stale or cross-connection handle is rejected,
+and later tools cannot silently switch targets. When no ready target exists,
+`ensure_ready` may reconnect an explicit network endpoint or the single
+unambiguous paired service; it never guesses among multiple devices.
+
+Tool calls within one MCP connection are executed in submission order. This
+prevents parallel agent requests from interleaving target binding, UI snapshots,
+or device mutations. Separate MCP connections remain independent.
+
+## Tool surface
+
+| Capability | MCP tools |
+| --- | --- |
+| Host and target readiness | `doctor`, `list_targets`, `ensure_ready` |
+| Durable development lifecycle | `start_dev_session`, `get_dev_session`, `stop_dev_session` |
+| App identity and lifecycle | `resolve_app`, `install_app`, `launch_app`, `restart_app`, `open_url` |
+| Current evidence | `inspect_app`, `inspect_ui`, `capture_screenshot` |
+| Safe UI queries and actions | `audit_ui`, `get_ui`, `find_ui`, `assert_ui`, `compare_ui`, `tap_ui`, `long_press_ui`, `scroll_ui`, `swipe_ui`, `fill_ui`, `clear_ui`, `type_text_ui`, `press_key_ui`, `wait_for_ui` |
+| Saved diagnostics | `list_sessions`, `get_session_problems`, `compile_debug_context` |
+
+MCP resources keep larger read-only context outside tool calls:
+
+| Resource | Content |
+| --- | --- |
+| `adb-ready://targets` | current target inventory and this connection's bound target |
+| `adb-ready://sessions` | bounded saved-session manifests |
+| `adb-ready://sessions/{sessionId}` | one session manifest |
+| `adb-ready://sessions/{sessionId}/events/{offset}/{limit}` | a page of up to 200 redacted events |
+| `adb-ready://sessions/{sessionId}/context` | a bounded redacted Markdown context document |
+
+Every tool advertises an output schema and returns the same versioned result
+envelope used by CLI JSON output. Screenshot capture additionally returns MCP
+`image` content so a vision-capable agent can inspect the pixels directly; the
+verified project-local PNG remains the evidence source of record.
+
+The npm package also ships `schema/agent-tools-v1.json`, generated from the
+server's real `tools/list` response during every build. Integrations can inspect
+version-matched input and output schemas plus safety annotations without
+starting ADB.
+
+`list_sessions` is project-scoped by default and supports status, preset,
+recency, and result-count filters. When more matches remain, pass its opaque
+`nextCursor` back as `cursor`; an expired cursor fails explicitly instead of
+silently restarting the list.
+
+## Safety boundary
+
+- There is no arbitrary command, shell, or raw ADB tool.
+- MCP tool arguments are schema-validated before execution.
+- Local APK installation accepts only a real path inside the project.
+- Screenshots require an explicit tool call and are stored as project files.
+- UI hierarchy and app inspection are marked sensitive and remain bounded.
+- UI references are checked against a fresh hierarchy digest before mutation;
+  stale references are rejected.
+- Data clearing and uninstall are intentionally absent from the agent surface.
+- Tool annotations help clients request approval, but ADB Ready enforces its
+  own target, path, and destructive-action rules.
+- Durable development handles are random, project-scoped, heartbeat-checked,
+  and can signal only the owned managed process recorded for that handle.
+- Nothing is uploaded by ADB Ready. The selected AI client controls what tool
+  results it sends to its model provider.
+
+Review the client configuration before approving it and keep write-capable
+tools behind the client's approval policy. See [Security](../SECURITY.md) for
+the complete trust model.
+
+## Runtime alternatives
+
+The published bundle is smoke-tested as an MCP stdio server under Node.js, Bun,
+and Deno against the legacy 2025-11-25 and modern 2026-07-28 protocol eras.
+Replace the command and arguments when Node.js is not your chosen runtime:
+
+```text
+Bun:  bun  ./node_modules/adb-ready/dist/cli.js mcp
+Deno: deno run -A ./node_modules/adb-ready/dist/cli.js mcp
+```
+
+Deno's `-A` grants the local server the filesystem, process, environment, and
+network access required to find project metadata and invoke ADB. Use the
+client's sandbox controls when a narrower host boundary is required.

package/docs/apps-and-evidence.md

@@ -0,0 +1,164 @@
+# Apps and evidence
+
+ADB Ready resolves project identity locally when possible, then binds
+target-based app operations and evidence to one deterministic Android target.
+It reports success only after the requested postcondition is observed.
+
+## App identity
+
+Inspect the project app without hard-coding its package name:
+
+```bash
+adb-ready app resolve
+adb-ready app info
+```
+
+Resolution prefers an explicit `APP_ID`, then project configuration and
+detected Android project metadata. Every resolved result includes provenance.
+If equally valid candidates remain, ADB Ready asks for an explicit choice
+instead of selecting the first package.
+
+Explicit, configured, Gradle, Expo, and manifest identity can be resolved with
+no running emulator, connected phone, or ADB binary. Only the final
+installed-package fallback requires a target.
+
+Set a stable project value when detection is not sufficient:
+
+```json
+{
+  "app": {
+    "android": {
+      "package": "com.example.app"
+    }
+  }
+}
+```
+
+List installed packages when investigating a target:
+
+```bash
+adb-ready apps list
+adb-ready apps list --system --filter google
+adb-ready apps list --all --json --non-interactive
+```
+
+User packages are the default. Enumeration and machine output are bounded.
+
+## App lifecycle
+
+```bash
+adb-ready app install ./android/app/build/outputs/apk/debug/app-debug.apk --replace
+adb-ready app install ./splits/base.apk ./splits/config.arm64_v8a.apk ./splits/config.en.apk
+adb-ready app launch
+adb-ready app restart
+adb-ready app stop
+adb-ready open 'myapp://orders/42' --package com.example.app
+```
+
+Pass all files from one split APK set together; ADB Ready uses Android's
+`install-multiple` operation and verifies the installed package afterward.
+Android App Bundles (`.aab`) and APK Set archives (`.apks`) are not directly
+installable. Generate device-specific APKs with the Android build tool that
+created them, then pass those `.apk` files explicitly.
+
+- Installation accepts one ordinary APK or an explicit complete split APK set.
+  `.apks`, `.aab`, and implicit downloads are not accepted yet.
+- Install, launch, stop, restart, and explicit deep-link handlers are checked
+  after ADB accepts the request.
+- `restart` is a verified stop followed by a verified launch.
+- Add `--activity .MainActivity` only when Android cannot resolve a launchable
+  activity.
+- Add `--grant-runtime-permissions` to an install only when that behavior is
+  intended.
+
+Preview exact target-scoped ADB operations without changing the device:
+
+```bash
+adb-ready app restart --dry-run --json
+adb-ready app clear-data --dry-run
+```
+
+`clear-data` and `uninstall` are destructive. Interactive use requires a
+confirmation; automation must pass `--allow-destructive`. A dry run never asks
+for destructive approval because it performs no mutation.
+
+## Structured inspection
+
+Build a compact snapshot of the project app, foreground state, and a small
+classified log window:
+
+```bash
+adb-ready inspect app
+adb-ready inspect app com.example.app --json --non-interactive
+```
+
+Screenshots are deliberately not captured by this read-only command. The
+result reports `adb-ready capture screenshot` as the explicit next action so
+sensitive pixels never enter evidence or AI context implicitly.
+
+Read the current Android accessibility hierarchy:
+
+```bash
+adb-ready inspect ui --interactive-only
+adb-ready inspect ui --max-depth 20 --json --non-interactive
+```
+
+The snapshot is capped at 2,000 nodes and includes a SHA-256 digest. Each node
+reference contains a prefix of that digest, so callers can distinguish stale
+references after the UI changes. `--interactive-only` keeps enabled actionable
+nodes; `--max-depth` accepts 1–100. Secure windows and missing accessibility
+data are reported as unavailable rather than as an empty successful snapshot.
+
+UI text and hierarchy data are marked `sensitive: true`. They are returned only
+by the explicit inspect command and are never included in diagnostic AI context
+automatically.
+
+## Evidence capture
+
+Capture a PNG directly from the selected target:
+
+```bash
+adb-ready capture screenshot
+adb-ready capture screenshot --out artifacts/login.png
+```
+
+Capture a bounded MP4 recording:
+
+```bash
+adb-ready capture screen-record --duration 15s
+adb-ready capture screen-record --duration 30s --out artifacts/repro.mp4
+```
+
+Evidence paths are relative to the current project. A capture never follows a
+symlink outside that root and never replaces an existing file unless `--force`
+is explicit. Files are written through a private temporary path and published
+only after validation.
+
+Some multi-display Android builds, including foldables, emit a short textual
+warning before the screenshot bytes. ADB Ready removes only a bounded text
+preamble and still requires a valid PNG signature before publishing the file.
+
+The result contains:
+
+- a project-relative path;
+- media type and byte size;
+- SHA-256 digest;
+- selected target and capture-command provenance.
+
+Binary data is stored as a file rather than embedded into JSON or AI context.
+Screenshots and recordings can contain private information; ADB Ready does not
+upload or implicitly attach them to diagnostic context.
+
+## Target selection and automation
+
+All commands accept the standard target selectors:
+
+```bash
+adb-ready app info --device SERIAL
+adb-ready capture screenshot --transport-id ID
+adb-ready app restart --last
+```
+
+Use `--json --non-interactive` for one versioned result on `stdout`, or
+`--format ndjson` for structured progress plus the final result. Human progress
+and errors remain on `stderr`.

package/docs/automation.md

@@ -19,6 +19,14 @@ adb-ready logs --format ndjson --non-interactive
 | `ndjson` | one versioned event per line, followed by the command result where applicable; saved timelines end with an event-count summary instead of duplicating the full event array |
 | `markdown` | bounded diagnostic context; only valid for `context` |
 
+Calling the root with `--json` returns a small product/capability overview. It
+does not probe ADB or load project configuration, which makes it safe for an
+agent or integration to identify the installed CLI first:
+
+```bash
+adb-ready --json
+```
+
 Machine data is written to `stdout`. Human progress and diagnostics are written
 to `stderr`. `--quiet` hides successful human output without hiding failures.
 
@@ -43,6 +51,12 @@ JSON commands return this top-level shape:
 Consumers must ignore unknown additive fields and event types within the same
 schema version.
 
+The npm package includes two versioned public artifacts:
+
+- `schema/config-v1.schema.json` validates project configuration; and
+- `schema/agent-tools-v1.json` catalogs every MCP tool's generated input and
+  output schemas plus safety annotations for the matching package version.
+
 ## Event envelope
 
 NDJSON events include:
@@ -111,6 +125,39 @@ adb-ready dev --port 8081 --dry-run --json
 Plan steps declare their risk. A dry run performs no pairing, connection,
 mapping, hook, or child-process mutation.
 
+## Run one bounded verification
+
+Use `run` when CI or an agent must prove a workflow and then exit instead of
+leaving a development server open:
+
+```bash
+adb-ready run --preset expo --run-timeout 10m -- \
+  maestro '--device={target.serial}' test .maestro/smoke.yaml
+```
+
+ADB Ready selects and exclusively leases one target, prepares the configured
+ports and development command, waits for every readiness assertion, runs the
+exact command after `--`, and cleans only the resources it created. It never
+retries a failed product assertion as if it were an infrastructure failure.
+
+The literal `{target.serial}` inside a verification argument is replaced only
+after ADB Ready selects and leases the target. The child also receives the
+same value as `ANDROID_SERIAL` and `ADB_READY_TARGET_SERIAL`. This keeps tools
+such as Maestro pinned explicitly without invoking a shell; tools that already
+honor `ANDROID_SERIAL`, including common Gradle/ADB workflows, need no placeholder.
+
+Every executed run prints the path to a project-local evidence directory under
+`.adb-ready/artifacts/`. Its manifest references the structured result,
+timeline, problems, focused logcat, bounded AI context, JUnit XML, and a concise
+GitHub Actions summary. The evidence remains available when readiness or the
+verification command fails.
+
+Preview the complete project plan before a device is allocated:
+
+```bash
+adb-ready run --preset expo --dry-run --json -- npm run test:e2e
+```
+
 ## CI example
 
 ```yaml

package/docs/configuration.md

@@ -65,7 +65,7 @@ existing file unless `--force` is explicit. Use `--dry-run` first.
 
 | Field | Values or shape |
 | --- | --- |
-| `preset` | `expo`, `react-native`, `gradle`, or `custom` |
+| `preset` | `expo`, `react-native`, `flutter`, `capacitor`, `gradle`, or `custom` |
 | `packageManager` | `npm`, `pnpm`, `yarn`, or `bun` |
 | `command` | `{ "executable": string, "args": string[], "cwd"?: string }` |
 | `reversePorts` | integers or `{ "device": number, "host"?: number }` objects |

package/docs/dev-sessions.md

@@ -10,6 +10,8 @@ local diagnostic record.
 | --- | --- | --- | --- |
 | Expo | `expo` dependency | project `start` script with `--android`, otherwise Expo CLI | `8081` |
 | React Native | `react-native` dependency | project `android` script, otherwise React Native CLI | `8081` |
+| Flutter | `pubspec.yaml` | `flutter run -d <selected-target>` | none |
+| Capacitor | `@capacitor/android` or `@capacitor/core` dependency | Capacitor CLI for the selected target | none |
 | Gradle | wrapper or Gradle build file | wrapper `installDebug` | none |
 | Custom | explicit config or `--` | exact executable and argument array | none |
 
@@ -18,6 +20,8 @@ Select a preset when detection is intentionally unavailable or ambiguous:
 ```bash
 adb-ready dev --preset expo
 adb-ready dev --preset react-native --package-manager pnpm
+adb-ready dev --preset flutter
+adb-ready dev --preset capacitor
 adb-ready dev --preset gradle --device emulator-5554
 ```
 

package/docs/logs-and-context.md

@@ -57,6 +57,18 @@ adb-ready sessions events SESSION_ID --format ndjson
 adb-ready problems SESSION_ID
 ```
 
+Find the useful run without scanning a long global list:
+
+```bash
+adb-ready sessions list --status failed --since 24h --limit 5
+adb-ready sessions list --preset expo
+adb-ready sessions list --all-projects
+```
+
+History is scoped to the current project by default. Status, time, preset, and
+count filters apply before output; `--all-projects` is an explicit escape hatch
+for a machine-wide audit.
+
 When the ID is omitted, the latest saved session is selected. Default retention
 keeps at most 30 finalized sessions, 14 days, and 20 MiB. Active sessions are
 not pruned as finalized history.
@@ -88,6 +100,9 @@ Available filters are `problems`, `recovery`, `logs`, `child`, `state`, `target`
 and `ports`. The compiler prioritizes structured problems, failures, warnings,
 recovery, and nearby diagnostic output within the requested character budget.
 It reports how many events were filtered or omitted.
+Repeated successful health checks are represented once with their count and
+final timestamp. The stored NDJSON remains complete, so compact AI context does
+not discard diagnostic evidence.
 
 Use JSON when another local tool should consume the result envelope:
 

package/docs/threat-model.md

@@ -0,0 +1,85 @@
+# Threat model
+
+ADB Ready runs locally with the same Android access as the selected ADB server.
+Its security goal is to make that authority explicit, narrow, target-bound, and
+observable; it cannot sandbox ADB, the Android device, a project command, or an
+AI client that already has broader host access.
+
+## Trust boundaries
+
+| Boundary | ADB Ready assumes | ADB Ready enforces |
+| --- | --- | --- |
+| CLI caller | arguments may be malformed or automated | strict parsing, no implicit shell, bounded values, explicit destructive approval |
+| ADB server and device | may be remote, stale, unavailable, or return hostile text | exact target selection, postcondition checks, output bounds, terminal sanitization |
+| Project filesystem | may contain symlinks, existing files, or untrusted config | root containment, schema validation, atomic writes, no overwrite by default |
+| Session storage | contains sensitive diagnostics | per-user location, bounded retention, redaction, restrictive file modes |
+| MCP client | chooses what reaches a model provider | local stdio only, typed tools, one bound target, no generic shell/raw ADB |
+| npm and CI | dependencies and release credentials can be attacked | pinned lockfile, package allowlist, short-lived OIDC publishing, provenance |
+
+## Protected assets
+
+- pairing codes, environment secrets, logs, screenshots, and UI text;
+- the identity and state of the intended Android target and app;
+- project files and existing ADB port mappings;
+- the integrity of the published npm package and its command/tool contracts.
+
+## Main threats and controls
+
+### Command and input injection
+
+Child commands use an executable plus argument array without an implicit shell.
+MCP exposes allowlisted workflows rather than command execution. Android text
+input accepts only a conservative character set; key actions map to numeric
+allowlisted keycodes.
+
+### Wrong-target mutation
+
+Every target-aware operation uses an exact ADB serial or transport ID. Ambiguous
+selection fails. An MCP connection binds one target and refuses a silent
+switch. UI references include the current hierarchy digest and are revalidated
+immediately before mutation.
+
+### Unsafe file mutation
+
+Capture and setup paths are constrained to the project, checked for unsafe
+symlinks, written atomically, and not replaced without an explicit policy. MCP
+APK installation accepts only an existing project-local file.
+
+### Secret or terminal escape disclosure
+
+Human output is terminal-sanitized. Stored diagnostic events are bounded and
+redacted. Pairing codes use protected input or stdin and never enter process
+arguments. Screenshots and UI hierarchies require explicit calls and never join
+AI context automatically.
+
+### Unbounded or misleading automation
+
+Process output, recordings, UI trees, session storage, context, retries, and
+waits are bounded. Results distinguish process acceptance (`ok`) from observed
+postconditions (`verified`). An unchanged UI is reported as a verification gap,
+not silently upgraded to verified success.
+
+### Network exposure
+
+The 0.2 MCP server uses stdio and opens no listener. ADB itself may connect to a
+local or remote server selected by the user; that existing authority is outside
+ADB Ready's isolation boundary.
+
+## Intentionally absent
+
+- arbitrary shell or raw ADB MCP tools;
+- automatic downloads, mutable `latest` execution, or implicit tool installs;
+- MCP data clearing and uninstall operations;
+- autonomous destructive recovery;
+- automatic screenshot or UI-text upload.
+
+## Residual risk
+
+A trusted ADB server can control connected Android targets, and an approved AI
+client may transmit tool results under its own provider policy. Accessibility
+hierarchies can expose on-screen personal data. Project commands and installed
+APKs execute with their normal platform authority. Users must review targets,
+MCP approvals, artifacts, and captured evidence accordingly.
+
+Report a vulnerability through the private channel in the
+[Security Policy](../SECURITY.md).

package/docs/troubleshooting.md

@@ -31,6 +31,7 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `MULTIPLE_WIRELESS_ENDPOINTS` | Discovery returned ambiguous services | Pass one exact `HOST:PORT` |
 | `PORT_MAPPING_CONFLICT` | Another mapping owns the requested listen port | Inspect `ports ... list`; remove or change it explicitly |
 | `LOG_PACKAGE_NOT_RUNNING` | Package filtering could not resolve a live process | Launch the app or use another package/PID |
+| `UI_NOT_IDLE` | Android UI Automator could not observe a quiet accessibility window | Pause continuous UI changes or navigate to a stable screen, then retry |
 | `SESSION_RECOVERY_FAILED` | The bounded target/port recovery budget was exhausted | Inspect `problems`, network state, and saved recovery events |
 | `SESSION_PERSISTENCE_FAILED` | The private session record could not be written | Check user-state directory permissions and capacity |
 | `CHILD_PROCESS_FAILED` | The project command exited unsuccessfully | Inspect child output, targeted logs, and preserved exit code |