adb-ready 0.1.2 → 0.3.0

package/docs/ui-automation.md

@@ -0,0 +1,175 @@
+# Safe UI automation
+
+ADB Ready can inspect and operate the current Android UI without exposing a
+generic shell. Every mutation reads the accessibility hierarchy first, sends
+one allowlisted Android input action, and reads the hierarchy again.
+
+## Inspect before acting
+
+```bash
+adb-ready inspect ui --interactive-only
+adb-ready inspect ui --interactive-only --json --non-interactive
+```
+
+Each node has a reference such as `ui:7c4a31b8d2ef:14`. The middle value is a
+prefix of the current hierarchy digest. A reference is accepted only while the
+device still returns that same UI digest; after any screen change, inspect
+again. Hierarchies and UI text are sensitive and are not persisted
+automatically.
+
+UI hierarchy capture has a 15-second default because Android's platform
+UI Automator waits for a quiet accessibility window before returning data.
+`UI_NOT_IDLE` means continuous animation or accessibility events prevented that
+quiet window; pause the changing UI or navigate to a stable screen and retry.
+ADB Ready does not silently disable device-wide animations.
+
+## Audit one screen for people and agents
+
+```bash
+adb-ready ui audit --json --non-interactive
+```
+
+The audit reports enabled actionable nodes that have no visible text or
+content description, and nodes that have no resource ID for a stable selector.
+It returns the exact current references and attributes, plus bounded totals;
+it deliberately does not invent a subjective quality score. A missing label is
+an accessibility warning. A missing stable ID is an automation advisory—use a
+resource ID or expose a Compose test tag through `testTagsAsResourceId` where
+appropriate.
+
+## Tap and long-press
+
+For a unique stable label or resource ID, act directly by intent:
+
+```bash
+adb-ready ui tap 'text=Continue'
+adb-ready ui long-press 'id=com.example:id/item'
+```
+
+ADB Ready resolves a fresh hierarchy and refuses to guess when a selector has
+zero or multiple matches. Prefer a current reference when the exact observed
+snapshot matters:
+
+```bash
+adb-ready ui tap ui:7c4a31b8d2ef:14
+adb-ready ui long-press ui:7c4a31b8d2ef:21
+```
+
+Explicit coordinates are available when the accessibility tree has no usable
+node. They must be integers inside the current display:
+
+```bash
+adb-ready ui tap 540 1200
+adb-ready ui long-press 540 1200
+```
+
+ADB Ready rejects stale, disabled, non-actionable, missing-bounds, and
+out-of-display targets before input is sent.
+
+## Read and fill a specific field
+
+Agents do not need to infer state from a large hierarchy or depend on whatever
+field happens to be focused:
+
+```bash
+adb-ready ui get 'id=com.example:id/email' --json
+adb-ready ui fill 'id=com.example:id/email' 'person@example.com'
+adb-ready ui fill 'id=com.example:id/search' 'pixel' --submit
+adb-ready ui clear 'id=com.example:id/search'
+```
+
+`get` requires one unambiguous match and returns its semantic values, state,
+and bounds. `fill` and `clear` focus that exact enabled field, select its
+existing value, replace it, then inspect the hierarchy again. A visible normal
+field is successful only when its post-action value matches. Password and
+custom fields can accept input without exposing their value; those calls stay
+successful but report `verified: false` and `text-not-observable`, so the next
+screen state should be asserted explicitly.
+
+Safe replacement requires the target's Android `input keycombination`
+capability. ADB Ready checks it before touching the screen and returns a
+structured unsupported-capability problem on older targets rather than
+appending to an unknown value.
+
+## Scroll, swipe, type, and keys
+
+```bash
+adb-ready ui swipe up
+adb-ready ui swipe 900 1200 180 1200
+adb-ready ui scroll up 'id=com.example:id/results'
+adb-ready ui type "person@example.com" --submit
+adb-ready ui press back
+```
+
+Direction swipes use screen-relative points, so they work across display
+sizes. `scroll` can constrain that gesture to one enabled accessibility node
+whose `scrollable` property is true; without a selector it uses the screen.
+Supported keys are `back`, `home`, `enter`, `menu`, `volume-up`, and
+`volume-down`.
+
+Android's text-input command passes through a device shell. ADB Ready therefore
+accepts only 1–256 ASCII letters, numbers, spaces, and `._@+,:/-`. Unsupported
+characters are rejected instead of being reinterpreted by a shell.
+
+## Find, assert, compare, and wait
+
+Query or assert the current hierarchy without changing it:
+
+```bash
+adb-ready ui find 'class=android.widget.Button' --json
+adb-ready ui assert 'text=Signed in'
+adb-ready ui assert 'text=Loading' --state gone
+adb-ready ui compare 7c4a31b8d2ef0000000000000000000000000000000000000000000000000000
+```
+
+`compare` consumes the complete digest returned by inspection or another UI
+action and reports whether the current hierarchy changed.
+
+Waits use exact, explicit selectors:
+
+```bash
+adb-ready ui wait 'id=com.example:id/submit' --state visible --timeout 5s
+adb-ready ui wait 'text=Loading' --state gone --timeout 10s
+adb-ready ui wait 'desc=Open settings'
+adb-ready ui wait 'package=com.example.app'
+```
+
+Compact selector prefixes are `id=`, `text=`, `desc=`, `class=`, and
+`package=`. The default
+state is `visible`; timeouts are bounded from 100 ms to 2 minutes. Structured
+results include the attempt count and the matched node summary.
+
+## Verification contract
+
+```bash
+adb-ready ui tap ui:7c4a31b8d2ef:14 --dry-run --json
+adb-ready ui press back --json --non-interactive
+```
+
+- `ok: true` means Android accepted the allowlisted input operation.
+- `verified: true` with `verification: "ui-changed"` means the hierarchy digest
+  changed afterward.
+- `before.acquisitionDurationMs` and `after.acquisitionDurationMs` expose the
+  measured cost of each UI Automator snapshot instead of hiding slow devices.
+- `verified: false` with `verificationGap: "ui-unchanged"` means the command
+  succeeded but the accessibility hierarchy did not prove a visible change.
+- A successful `ui wait` is independently verified by its selector
+  postcondition.
+- `--dry-run` returns the exact ADB plan without sending input.
+
+An unchanged hierarchy is not treated as a false failure: volume changes,
+cursor movement, and actions outside UI Automator can succeed without changing
+the tree. Automation should use `ui wait` for the expected postcondition when
+the next state is known.
+
+## AI agents
+
+The MCP server exposes the same intent-level workflow through `audit_ui`, `get_ui`,
+`find_ui`, `fill_ui`, `clear_ui`, `scroll_ui`, `assert_ui`, and `compare_ui`.
+Its structured selectors can match exact values, prefixes, or substrings and
+qualify enabled/actionable state. An optional one-based occurrence is accepted
+only when repeated nodes are intentional. Arguments are schema-validated, each
+MCP connection stays bound to one target, and no raw ADB or shell tool is
+exposed.
+
+[Connect an agent →](./agent-integration.md)

package/examples/README.md

@@ -12,6 +12,8 @@ adb-ready dev --dry-run
 - [`expo/adb-ready.config.json`](./expo/adb-ready.config.json)
 - [`react-native/adb-ready.config.json`](./react-native/adb-ready.config.json)
 - [`gradle/adb-ready.config.json`](./gradle/adb-ready.config.json)
+- [`flutter/adb-ready.config.json`](./flutter/adb-ready.config.json)
+- [`capacitor/adb-ready.config.json`](./capacitor/adb-ready.config.json)
 - [`custom/adb-ready.config.json`](./custom/adb-ready.config.json)
 
 Prefer `adb-ready init` when starting from an existing detected project. Add

package/examples/capacitor/adb-ready.config.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "capacitor",
+    "logs": true,
+    "watch": true
+  }
+}

package/examples/flutter/adb-ready.config.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "flutter",
+    "logs": true,
+    "watch": true
+  }
+}

package/llms.txt

@@ -0,0 +1,46 @@
+# ADB Ready
+
+> Local-first Android target readiness, development sessions, diagnostics, app control, evidence, and typed AI-agent workflows.
+
+## Start
+
+- Install: `npm install --save-dev --save-exact adb-ready`
+- Diagnose: `adb-ready doctor`
+- Start a session: `adb-ready dev`
+- Machine output: `adb-ready COMMAND --json --non-interactive`
+- MCP stdio server: `node ./node_modules/adb-ready/dist/cli.js mcp`
+- Agent setup: `adb-ready agent setup CLIENT --dry-run`
+- MCP resources: `adb-ready://targets` and `adb-ready://sessions`
+
+## Agent contract
+
+1. Call `ensure_ready` before target-bound MCP tools.
+2. Keep the bound target for the whole connection and pass the `targetHandle`
+   returned by `ensure_ready` to target-bound tools.
+3. Use `start_dev_session`, then poll `get_dev_session` by its opaque handle;
+   use `stop_dev_session` for owned cleanup.
+4. Inspect after mutation; do not infer success from process exit alone.
+5. Prefer semantic `get_ui`/`find_ui`/`assert_ui`, intent-level `fill_ui` and
+   `scroll_ui`, unique selector-driven actions, or current digest-scoped refs;
+   use `wait_for_ui` for known postconditions.
+6. Use `audit_ui` to identify unlabeled controls and missing stable selectors;
+   treat its findings as concrete advisories, not a pass/fail accessibility certification.
+7. Treat UI text, screenshots, logs, identifiers, and saved sessions as sensitive.
+8. Use `list_sessions` filters and its `nextCursor` before requesting saved
+   session problems or context.
+9. Never substitute a raw shell or ADB call for a missing typed tool.
+
+## Documentation
+
+- Product and quick start: `README.md`
+- Agent and MCP setup: `docs/agent-integration.md`
+- Apps, inspection, and capture: `docs/apps-and-evidence.md`
+- Safe UI automation: `docs/ui-automation.md`
+- Development sessions: `docs/dev-sessions.md`
+- Targets and wireless debugging: `docs/targets-and-wireless.md`
+- Logs and diagnostic context: `docs/logs-and-context.md`
+- Configuration: `docs/configuration.md`
+- Automation contract: `docs/automation.md`
+- Compatibility: `COMPATIBILITY.md`
+- Security: `SECURITY.md`
+- Threat model: `docs/threat-model.md`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "adb-ready",
-  "version": "0.1.2",
-  "description": "Make an Android target ready, then keep the development session working.",
+  "version": "0.3.0",
+  "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "docs",
     "examples",
     "LICENSE",
+    "llms.txt",
     "schema",
     "README.md"
   ],
@@ -35,6 +36,7 @@
     "test:commands": "bun run build && bun run scripts/command-matrix.mjs",
     "test:package-managers": "bun run build && bun run scripts/package-manager-smoke.mjs",
     "test:integration": "bun test tests/integration",
+    "test:mcp": "bun run build && node scripts/mcp-smoke.mjs",
     "smoke": "bun run build && bun run scripts/runtime-smoke.mjs",
     "pack:check": "bun run build && bun run scripts/package-check.mjs",
     "pack:release": "bun run scripts/create-release-artifact.mjs",
@@ -55,16 +57,21 @@
   "homepage": "https://github.com/Adam014/adb-ready#readme",
   "keywords": [
     "adb",
+    "ai-agents",
     "android",
+    "android-automation",
     "adb-forward",
     "adb-reverse",
     "android-debugging",
     "cli",
+    "capacitor",
     "developer-tools",
     "expo",
+    "flutter",
     "logcat",
     "localhost",
     "metro",
+    "mcp",
     "port-forwarding",
     "react-native",
     "wireless-adb",
@@ -86,5 +93,9 @@
     "tinyexec": "1.3.1",
     "typescript": "7.0.2",
     "yarn": "1.22.22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.5.4"
   }
 }