adb-ready 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/CHANGELOG.md +31 -1
  2. package/COMPATIBILITY.md +6 -0
  3. package/README.md +84 -39
  4. package/dist/cli.js +43066 -5950
  5. package/dist/cli.js.map +95 -17
  6. package/docs/agent-integration.md +204 -0
  7. package/docs/apps-and-evidence.md +157 -0
  8. package/docs/automation.md +6 -0
  9. package/docs/threat-model.md +85 -0
  10. package/docs/ui-automation.md +99 -0
  11. package/llms.txt +37 -0
  12. package/package.json +10 -1
  13. package/schema/agent-tools-v1.json +522 -0
  14. package/schema/config-v1.schema.json +22 -0
package/CHANGELOG.md CHANGED
@@ -9,6 +9,35 @@ breaking changes.
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ ## [0.2.0] - 2026-09-10
13
+
14
+ ### Added
15
+
16
+ - Resolve Android application IDs with provenance, enumerate installed
17
+ packages, and inspect one project app on a deterministic target.
18
+ - Resolve known project application IDs without requiring ADB or a connected
19
+ target; use installed packages only as the final fallback.
20
+ - Install, launch, stop, restart, clear, uninstall, and deep-link apps with
21
+ explicit destructive policy, mutation-free dry runs, and postcondition
22
+ verification.
23
+ - Capture verified PNG screenshots and bounded MP4 screen recordings into
24
+ atomically published project-local evidence files with SHA-256 metadata,
25
+ including OEM multi-display screenshot output with a bounded text preamble.
26
+ - Inspect one app and the current accessibility hierarchy as bounded,
27
+ explicitly sensitive snapshots with digest-scoped UI references.
28
+ - Give local AI agents 19 typed Android tools and saved-session context over a
29
+ tested Node.js, Bun, and Deno MCP stdio server without exposing raw shell/ADB
30
+ or destructive app removal. Calls within one connection are serialized to
31
+ preserve deterministic target and UI state.
32
+ - Generate or safely merge project MCP setup for Codex, Claude Code, Cursor,
33
+ and VS Code, with non-mutating snippets for Windsurf and generic clients.
34
+ - Expose current targets, saved manifests, paginated redacted events, and
35
+ bounded Markdown context as local MCP resources.
36
+ - Safely tap, long-press, swipe, type, press allowlisted keys, and wait for exact
37
+ UI postconditions with stale-reference protection and before/after evidence.
38
+ - Replace the command-heavy interactive home with focused workflow categories
39
+ and progressive disclosure.
40
+
12
41
  ## [0.1.2] - 2026-09-10
13
42
 
14
43
  ### Changed
@@ -52,7 +81,8 @@ breaking changes.
52
81
  explainable configuration precedence.
53
82
  - Human, plain, JSON, and NDJSON output across Node, Bun, and Deno entrypoints.
54
83
 
55
- [Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.1.2...HEAD
84
+ [Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.2.0...HEAD
85
+ [0.2.0]: https://github.com/Adam014/adb-ready/compare/v0.1.2...v0.2.0
56
86
  [0.1.2]: https://github.com/Adam014/adb-ready/compare/v0.1.1...v0.1.2
57
87
  [0.1.1]: https://github.com/Adam014/adb-ready/compare/v0.1.0...v0.1.1
58
88
  [0.1.0]: https://github.com/Adam014/adb-ready/compare/v0.0.1-alpha.0...v0.1.0
package/COMPATIBILITY.md CHANGED
@@ -34,6 +34,12 @@ Deterministic fixtures cover platform paths, ADB output variants, target states,
34
34
  IPv4/IPv6 discovery, selection, cancellation, timeouts, and packaging. A local
35
35
  read-only smoke test is available as `bun run verify:real-adb`.
36
36
 
37
+ Recorded physical acceptance:
38
+
39
+ | Host and target | Transport | Verified workflows |
40
+ | --- | --- | --- |
41
+ | macOS arm64 · Samsung Galaxy Z Fold4 (SM-F936B) · API 36 | Wireless debugging (TLS) | discovery and stable identity; app resolve/info/launch/restart; UI inspect/tap/stale-ref rejection/wait; multi-display screenshot; screen recording; Expo dev/reverse/Ctrl-C cleanup; concurrent MCP request ordering |
42
+
37
43
  Physical USB, emulator, wireless, VPN, container, WSL, and remote-server claims
38
44
  must be recorded as tested only after they pass on that real environment. ADB
39
45
  Ready never treats a fixture as proof of hardware compatibility.
package/README.md CHANGED
@@ -2,11 +2,12 @@
2
2
 
3
3
  # ADB Ready
4
4
 
5
- **One Android target. One reliable development session.**
5
+ **Make Android development accessible to coding agents.**
6
6
 
7
- Select a device, prepare localhost ports, start your project, and keep the
8
- connection healthy—without stitching together fragile ADB scripts.
7
+ An MCP-native, local-first CLI that gives agents and developers safe, typed
8
+ control of Android targets, apps, UI, logs, evidence, and development sessions.
9
9
 
10
+ [![MCP](https://img.shields.io/badge/MCP-native-7c3aed)](./docs/agent-integration.md)
10
11
  [![CI](https://github.com/Adam014/adb-ready/actions/workflows/ci.yml/badge.svg)](https://github.com/Adam014/adb-ready/actions/workflows/ci.yml)
11
12
  [![npm](https://img.shields.io/npm/v/adb-ready?label=npm&color=1f9db5)](https://www.npmjs.com/package/adb-ready)
12
13
  [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
@@ -14,7 +15,7 @@ connection healthy—without stitching together fragile ADB scripts.
14
15
  [![Deno](https://img.shields.io/badge/Deno_2-tested-111827?logo=deno&logoColor=white)](https://deno.com/)
15
16
  [![Platforms](https://img.shields.io/badge/hosts-macOS_%C2%B7_Linux_%C2%B7_Windows-64748b)](./COMPATIBILITY.md)
16
17
 
17
- [Quick start](#quick-start) · [Why ADB Ready](#why-adb-ready) ·
18
+ [Quick start](#quick-start) · [AI agents](#android-tools-built-for-ai-agents) · [Why ADB Ready](#why-adb-ready) ·
18
19
  [Workflows](#find-your-workflow) · [Documentation](#documentation) ·
19
20
  [Compatibility](#compatibility)
20
21
 
@@ -30,13 +31,39 @@ $ adb-ready dev
30
31
  ```
31
32
 
32
33
  Stop rebuilding your Android setup every time a cable moves, Wi-Fi reconnects,
33
- or ADB picks the wrong device. ADB Ready turns the target, ports, project
34
- command, recovery, and useful logs into one development session.
34
+ or ADB picks the wrong device. ADB Ready turns scattered ADB operations into
35
+ one deterministic workflow that developers, scripts, and AI agents can share.
35
36
 
36
37
  ```bash
37
38
  npx adb-ready dev
38
39
  ```
39
40
 
41
+ ## Android tools built for AI agents
42
+
43
+ ADB Ready turns coding agents from passive log readers into safe Android
44
+ operators. Its local MCP server exposes **19 schema-validated tools** for target
45
+ readiness, app lifecycle, UI inspection, evidence capture, and verified UI
46
+ actions—without giving the model a generic shell or unrestricted ADB access.
47
+
48
+ ```bash
49
+ # Connect the current project to your coding agent
50
+ npx adb-ready agent setup codex
51
+ ```
52
+
53
+ Codex, Claude Code, Cursor, VS Code/Copilot, Windsurf, and other MCP clients can:
54
+
55
+ - find and bind one deterministic Android target;
56
+ - resolve, install, launch, restart, and inspect the project app;
57
+ - inspect current UI, tap, type, swipe, press keys, and wait for state changes;
58
+ - capture screenshots and read bounded, redacted session evidence; and
59
+ - verify actions against fresh device state instead of assuming they worked.
60
+
61
+ Everything stays local unless your chosen AI client sends tool results to its
62
+ model provider. Stale UI references are rejected, destructive app removal is
63
+ not exposed to agents, and every tool returns structured evidence.
64
+
65
+ [Connect an AI agent in minutes →](./docs/agent-integration.md)
66
+
40
67
  ## Why ADB Ready?
41
68
 
42
69
  ### Start once. Stay ready.
@@ -51,19 +78,19 @@ When a wireless target or reverse mapping disappears, recovery is bounded,
51
78
  target-safe, and independently verified. It never silently restarts the shared
52
79
  ADB server or rewrites another tool's mapping.
53
80
 
54
- ### Get signal instead of noise.
81
+ ### Give agents evidence, not terminal noise.
55
82
 
56
83
  Focused logcat, structured problems, and a saved redacted timeline keep the
57
- important failure evidence together. One command turns it into compact context
58
- for any AI assistant—without uploading anything.
84
+ important failure evidence together. Agents receive bounded, machine-readable
85
+ context and typed actions instead of guessing from an unstructured terminal.
59
86
 
60
87
  ### Keep your existing stack.
61
88
 
62
89
  ADB Ready orchestrates the real ADB, framework, and package manager you already
63
90
  use. It does not replace Android Studio or force your project onto Bun.
64
91
 
65
- | Projects | Package managers | CLI runtimes |
66
- | --- | --- | --- |
92
+ | Projects | Package managers | CLI runtimes |
93
+ | ------------------------------------- | ----------------------- | -------------------- |
67
94
  | Expo · React Native · Gradle · custom | npm · pnpm · Yarn · Bun | Node.js · Bun · Deno |
68
95
 
69
96
  ## Quick start
@@ -97,18 +124,23 @@ Running `adb-ready` without a command opens the interactive workflow home.
97
124
 
98
125
  ## Find your workflow
99
126
 
100
- | I want to… | Start here |
101
- | --- | --- |
102
- | launch Expo, React Native, Gradle, or my own command | [`adb-ready dev`](./docs/dev-sessions.md) |
103
- | pair or reconnect an Android device over Wi-Fi | [Targets and Wireless debugging](./docs/targets-and-wireless.md) |
104
- | choose the right device when several are connected | [Deterministic target selection](./docs/targets-and-wireless.md#explicit-selection) |
105
- | expose Metro, a local API, or a debugger to Android | [Port workflows](./docs/dev-sessions.md#port-ownership) |
106
- | see only the Android logs that matter | [Focused logcat](./docs/logs-and-context.md#focused-logcat) |
107
- | understand why the last session failed | [Session problems](./docs/logs-and-context.md#session-history) |
108
- | prepare safe evidence for an AI assistant | [Diagnostic context](./docs/logs-and-context.md#diagnostic-context) |
109
- | share project settings without a custom shell script | [Configuration](./docs/configuration.md) |
110
- | use ADB Ready from CI or another tool | [Automation contract](./docs/automation.md) |
111
- | fix a known setup or target problem | [Troubleshooting](./docs/troubleshooting.md) |
127
+ | I want to… | Start here |
128
+ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
129
+ | launch Expo, React Native, Gradle, or my own command | [`adb-ready dev`](./docs/dev-sessions.md) |
130
+ | pair or reconnect an Android device over Wi-Fi | [Targets and Wireless debugging](./docs/targets-and-wireless.md) |
131
+ | choose the right device when several are connected | [Deterministic target selection](./docs/targets-and-wireless.md#explicit-selection) |
132
+ | expose Metro, a local API, or a debugger to Android | [Port workflows](./docs/dev-sessions.md#port-ownership) |
133
+ | install, inspect, launch, restart, or deep-link my app | [App lifecycle](./docs/apps-and-evidence.md#app-lifecycle) |
134
+ | save a verified screenshot or bounded screen recording | [Evidence capture](./docs/apps-and-evidence.md#evidence-capture) |
135
+ | give a developer or agent one bounded app/UI snapshot | [Structured inspection](./docs/apps-and-evidence.md#structured-inspection) |
136
+ | safely tap, type, swipe, press keys, or wait for Android UI | [Safe UI automation](./docs/ui-automation.md) |
137
+ | see only the Android logs that matter | [Focused logcat](./docs/logs-and-context.md#focused-logcat) |
138
+ | understand why the last session failed | [Session problems](./docs/logs-and-context.md#session-history) |
139
+ | prepare safe evidence for an AI assistant | [Diagnostic context](./docs/logs-and-context.md#diagnostic-context) |
140
+ | connect Codex, Claude Code, Cursor, Copilot, or Windsurf | [`adb-ready agent setup`](./docs/agent-integration.md#connect-an-agent) |
141
+ | share project settings without a custom shell script | [Configuration](./docs/configuration.md) |
142
+ | use ADB Ready from CI or another tool | [Automation contract](./docs/automation.md) |
143
+ | fix a known setup or target problem | [Troubleshooting](./docs/troubleshooting.md) |
112
144
 
113
145
  ## What happens in `adb-ready dev`?
114
146
 
@@ -137,7 +169,7 @@ adb-ready dev -- pnpm run android:local
137
169
  adb-ready dev --dry-run --json
138
170
  ```
139
171
 
140
- ## Built for humans and automation
172
+ ## Built for humans, agents, and automation
141
173
 
142
174
  The interactive CLI provides keyboard navigation, live state, reduced-motion
143
175
  support, narrow-terminal fallbacks, and clear recovery feedback. Scripts get a
@@ -155,19 +187,28 @@ adb-ready context --since 5m --only problems,recovery,logs
155
187
  - stable problem categories, meaningful exit codes, timeouts, and dry runs; and
156
188
  - explicit target, ADB path, and remote ADB server overrides.
157
189
 
190
+ Local AI agents use the same contracts through a schema-validated MCP stdio
191
+ server. The package includes a version-matched public tool schema, while target
192
+ binding, fresh-state checks, redaction, and verification remain enforced by ADB
193
+ Ready itself. [Explore the agent contract →](./docs/agent-integration.md)
194
+
158
195
  ## Documentation
159
196
 
160
- | Guide | What it answers |
161
- | --- | --- |
162
- | [Getting started](./docs/getting-started.md) | How do I reach my first ready session? |
163
- | [Development sessions](./docs/dev-sessions.md) | What does ADB Ready own, watch, recover, and clean up? |
164
- | [Targets and Wireless debugging](./docs/targets-and-wireless.md) | How are devices paired, connected, and selected safely? |
165
- | [Logs and AI context](./docs/logs-and-context.md) | What is captured, redacted, saved, and exported? |
166
- | [Configuration](./docs/configuration.md) | How do projects, profiles, hooks, and precedence work? |
167
- | [Automation](./docs/automation.md) | What are the JSON, NDJSON, stdout, and exit-code contracts? |
168
- | [Troubleshooting](./docs/troubleshooting.md) | What should I do for each common failure? |
169
- | [Compatibility](./COMPATIBILITY.md) | Which hosts, runtimes, and environments are covered? |
170
- | [Example configs](./examples/README.md) | What can I copy for Expo, React Native, Gradle, or custom projects? |
197
+ | Guide | What it answers |
198
+ | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
199
+ | [Getting started](./docs/getting-started.md) | How do I reach my first ready session? |
200
+ | [Development sessions](./docs/dev-sessions.md) | What does ADB Ready own, watch, recover, and clean up? |
201
+ | [Targets and Wireless debugging](./docs/targets-and-wireless.md) | How are devices paired, connected, and selected safely? |
202
+ | [Apps and evidence](./docs/apps-and-evidence.md) | How do I control one app and capture verified device evidence? |
203
+ | [AI agent integration](./docs/agent-integration.md) | How do Codex, Claude Code, Cursor, or Copilot use safe Android tools? |
204
+ | [Safe UI automation](./docs/ui-automation.md) | How do humans and agents act on current UI with verifiable evidence? |
205
+ | [Logs and AI context](./docs/logs-and-context.md) | What is captured, redacted, saved, and exported? |
206
+ | [Configuration](./docs/configuration.md) | How do projects, profiles, hooks, and precedence work? |
207
+ | [Automation](./docs/automation.md) | What are the JSON, NDJSON, stdout, and exit-code contracts? |
208
+ | [Threat model](./docs/threat-model.md) | Which trust boundaries, controls, and residual risks apply? |
209
+ | [Troubleshooting](./docs/troubleshooting.md) | What should I do for each common failure? |
210
+ | [Compatibility](./COMPATIBILITY.md) | Which hosts, runtimes, and environments are covered? |
211
+ | [Example configs](./examples/README.md) | What can I copy for Expo, React Native, Gradle, or custom projects? |
171
212
 
172
213
  Run `adb-ready --help` for the full command list or
173
214
  `adb-ready help COMMAND` for focused options.
@@ -189,13 +230,17 @@ Android transport backend.
189
230
  - Session data is bounded, redacted, private to the user, and never uploaded.
190
231
  - Package contents are allowlisted and checked before release.
191
232
  - npm publication is prepared for short-lived OIDC credentials and provenance.
233
+ - AI clients receive typed bounded tools; raw shell/ADB and destructive app
234
+ removal are not exposed through MCP.
235
+ - UI references are bound to the current hierarchy digest, so stale targets are
236
+ rejected before input is sent.
192
237
 
193
238
  ## Project
194
239
 
195
240
  [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) ·
196
241
  [Security](./SECURITY.md) · [MIT License](./LICENSE)
197
242
 
198
- ADB Ready is Android-only. The `0.1.x` releases focus on target acquisition,
199
- ports, development-session recovery, logs, diagnostics, and automation. App
200
- lifecycle, files, screenshots, screen recording, and shell workflows come
201
- after this core is proven on real projects.
243
+ ADB Ready is Android-only. The current development line combines target
244
+ readiness, ports, session recovery, logs, verified app lifecycle, and local
245
+ evidence capture. It intentionally exposes typed workflows instead of a generic
246
+ remote shell.