adb-ready 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -9,6 +9,130 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-11
+
+### Added
+
+- Scope saved sessions, latest-problem lookup, AI context, and MCP session
+  resources to the canonical current project by default, with an explicit
+  `--all-projects` escape hatch for cross-project audits.
+- Add privacy-safe cross-process Android target leases with heartbeats, bounded
+  expiry, stale-owner recovery, and ownership-checked cleanup for app, UI,
+  port, recording, and development-session mutations.
+- Let `dev --dry-run` resolve and validate the project, command, ports, and
+  lifecycle hooks without requiring ADB or allocating an Android target. An
+  explicit target selector still produces the target-resolved plan.
+- Add composable readiness contracts for boot, unlock, process, foreground
+  activity, exact UI selectors, host ports, HTTP responses, and bounded log
+  presence or absence. Expo and React Native sessions now verify Android boot
+  and Metro reachability before reporting ready.
+- Add `adb-ready run -- COMMAND` as a finite automation entrypoint: start the
+  configured development service, satisfy readiness, execute one timeout-bound
+  verification command, preserve its exit code, and clean owned resources.
+- Produce an atomic, redacted evidence bundle for every executed `run` with a
+  versioned manifest, structured result, NDJSON timeline, problems, logcat,
+  bounded AI context, JUnit XML, and GitHub step-summary Markdown.
+- Advertise and validate a versioned result-envelope output schema for every
+  MCP tool, return screenshot pixels as MCP image content, and issue stable
+  connection-scoped target handles that reject stale or cross-connection use.
+- Let MCP `ensure_ready` reconnect an explicitly addressed endpoint or the only
+  unambiguous paired wireless service before binding it.
+- Exercise the complete MCP contract on Node.js, Bun, and Deno across both the
+  legacy 2025-11-25 and modern 2026-07-28 protocol eras.
+- Add semantic UI find, assert, digest comparison, and selector-driven tap or
+  long-press workflows. Structured selectors support exact, prefix, and
+  contains matching plus enabled/actionable qualifiers; ambiguous mutations
+  fail instead of guessing.
+- Add project-scoped `start_dev_session`, `get_dev_session`, and
+  `stop_dev_session` MCP tools backed by opaque durable handles. Managed
+  sessions continue outside one tool call, survive client reconnects, report
+  heartbeats and terminal exit state, and stop only their verified owned
+  process group.
+- Add status, recency, preset, and count filters to project-scoped session
+  history.
+- Install a single APK or a complete split APK set through verified `install`
+  and `install-multiple` workflows in both CLI and MCP.
+- Detect and run Flutter and Capacitor Android projects on the exact selected
+  target, with boot readiness and no invented default port mappings.
+- Add intent-level UI read, field fill/clear, and container-scoped scroll
+  workflows for CLI and MCP. Field replacement is capability-gated before
+  mutation and verifies observable values instead of inferring success from
+  input exit codes.
+- Add a project-scoped MCP session index with status, preset, recency, limit,
+  and stable cursor pagination so agents can locate relevant saved evidence
+  without scanning unrelated history.
+- Add a bounded CLI/MCP screen audit that identifies enabled actionable nodes
+  without human-readable labels and controls without stable resource IDs,
+  returning concrete nodes instead of a subjective score.
+- Bind finite verification commands to the leased target through
+  `ANDROID_SERIAL`, `ADB_READY_TARGET_SERIAL`, and an explicit
+  `{target.serial}` argument placeholder for tools such as Maestro that require
+  their own device flag.
+- Report measured acquisition time alongside every before/after UI snapshot so
+  agents and CI can identify slow accessibility inspection without guessing.
+
+### Changed
+
+- Compact repeated successful health checks in bounded AI context while
+  preserving the complete redacted NDJSON timeline as source evidence.
+- Reorganize the interactive home around development, test automation, device,
+  debugging, and project tasks; preserve root presentation flags and use copy
+  that remains meaningful in narrow terminals.
+- Add the screen agent-readiness audit to the task-oriented Debug & evidence
+  menu without expanding the root menu.
+- Lead the public README with the agent outcome, immediate setup, and a concrete
+  first task before the implementation details.
+
+### Fixed
+
+- Return a structured capability overview for bare machine-mode invocation and
+  suggest high-confidence corrections for mistyped commands or options.
+- Apply retention limits per project before the global safety cap so one noisy
+  project cannot evict another project's recent diagnostic history.
+- Keep packaged command-matrix development sessions inside an isolated
+  temporary state directory instead of polluting the user's session store.
+- Correct the public installation guide so its compatibility note no longer
+  contradicts the documented split APK support.
+- Give accessibility hierarchy acquisition its own 15-second default deadline
+  in inspect and UI workflows while preserving an explicit global timeout.
+  This prevents ordinary slower OEM UI Automator dumps from failing at the
+  generic five-second ADB boundary.
+- Classify Android's successful-exit `could not get idle state` response as a
+  distinct `UI_NOT_IDLE` problem with a safe recovery instruction instead of
+  misreporting an inaccessible hierarchy.
+- Finalize an explicitly stopped managed development task as interrupted even
+  when Windows terminates the owned child before its signal handler can write
+  the terminal record.
+
+## [0.2.0] - 2026-09-10
+
+### Added
+
+- Resolve Android application IDs with provenance, enumerate installed
+  packages, and inspect one project app on a deterministic target.
+- Resolve known project application IDs without requiring ADB or a connected
+  target; use installed packages only as the final fallback.
+- Install, launch, stop, restart, clear, uninstall, and deep-link apps with
+  explicit destructive policy, mutation-free dry runs, and postcondition
+  verification.
+- Capture verified PNG screenshots and bounded MP4 screen recordings into
+  atomically published project-local evidence files with SHA-256 metadata,
+  including OEM multi-display screenshot output with a bounded text preamble.
+- Inspect one app and the current accessibility hierarchy as bounded,
+  explicitly sensitive snapshots with digest-scoped UI references.
+- Give local AI agents 19 typed Android tools and saved-session context over a
+  tested Node.js, Bun, and Deno MCP stdio server without exposing raw shell/ADB
+  or destructive app removal. Calls within one connection are serialized to
+  preserve deterministic target and UI state.
+- Generate or safely merge project MCP setup for Codex, Claude Code, Cursor,
+  and VS Code, with non-mutating snippets for Windsurf and generic clients.
+- Expose current targets, saved manifests, paginated redacted events, and
+  bounded Markdown context as local MCP resources.
+- Safely tap, long-press, swipe, type, press allowlisted keys, and wait for exact
+  UI postconditions with stale-reference protection and before/after evidence.
+- Replace the command-heavy interactive home with focused workflow categories
+  and progressive disclosure.
+
 ## [0.1.2] - 2026-09-10
 
 ### Changed
@@ -52,7 +176,9 @@ breaking changes.
   explainable configuration precedence.
 - Human, plain, JSON, and NDJSON output across Node, Bun, and Deno entrypoints.
 
-[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Adam014/adb-ready/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/Adam014/adb-ready/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/Adam014/adb-ready/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Adam014/adb-ready/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Adam014/adb-ready/compare/v0.0.1-alpha.0...v0.1.0

package/COMPATIBILITY.md

@@ -34,6 +34,12 @@ Deterministic fixtures cover platform paths, ADB output variants, target states,
 IPv4/IPv6 discovery, selection, cancellation, timeouts, and packaging. A local
 read-only smoke test is available as `bun run verify:real-adb`.
 
+Recorded physical acceptance:
+
+| Host and target | Transport | Verified workflows |
+| --- | --- | --- |
+| 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 |
+
 Physical USB, emulator, wireless, VPN, container, WSL, and remote-server claims
 must be recorded as tested only after they pass on that real environment. ADB
 Ready never treats a fixture as proof of hardware compatibility.

package/README.md

@@ -2,24 +2,37 @@
 
 # ADB Ready
 
-**One Android target. One reliable development session.**
+**The local Android runtime for coding agents.**
 
-Select a device, prepare localhost ports, start your project, and keep the
-connection healthy—without stitching together fragile ADB scripts.
+Give any MCP-capable agent a safe way to start your Android project, operate a
+real app, verify what happened, and bring back evidence—not guesses.
 
+[![MCP](https://img.shields.io/badge/MCP-native-7c3aed)](./docs/agent-integration.md)
 [![CI](https://github.com/Adam014/adb-ready/actions/workflows/ci.yml/badge.svg)](https://github.com/Adam014/adb-ready/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/adb-ready?label=npm&color=1f9db5)](https://www.npmjs.com/package/adb-ready)
 [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![Bun](https://img.shields.io/badge/Bun-tested-14151a?logo=bun&logoColor=white)](https://bun.sh/)
 [![Deno](https://img.shields.io/badge/Deno_2-tested-111827?logo=deno&logoColor=white)](https://deno.com/)
+[![Flutter](https://img.shields.io/badge/Flutter-supported-02569B?logo=flutter&logoColor=white)](./docs/dev-sessions.md)
+[![Capacitor](https://img.shields.io/badge/Capacitor-supported-119EFF?logo=capacitor&logoColor=white)](./docs/dev-sessions.md)
 [![Platforms](https://img.shields.io/badge/hosts-macOS_%C2%B7_Linux_%C2%B7_Windows-64748b)](./COMPATIBILITY.md)
 
-[Quick start](#quick-start) · [Why ADB Ready](#why-adb-ready) ·
+[Quick start](#quick-start) · [AI agents](#built-for-agentic-android-development) · [Why ADB Ready](#why-adb-ready) ·
 [Workflows](#find-your-workflow) · [Documentation](#documentation) ·
 [Compatibility](#compatibility)
 
 </div>
 
+```bash
+npm install --save-dev adb-ready
+npx adb-ready agent setup codex
+```
+
+Then ask your agent:
+
+> Start this Expo app on my Android phone, wait until the login screen is
+> actually ready, verify the change I made, and keep the failure evidence.
+
 ```text
 $ adb-ready dev
 
@@ -29,14 +42,44 @@ $ adb-ready dev
 ● Session healthy               watching target, ports, and logs
 ```
 
-Stop rebuilding your Android setup every time a cable moves, Wi-Fi reconnects,
-or ADB picks the wrong device. ADB Ready turns the target, ports, project
-command, recovery, and useful logs into one development session.
+ADB Ready handles the state around ADB that agents cannot safely guess: which
+device belongs to the run, whether the app is truly ready, which ports and
+processes it owns, and what evidence survives after a failure. It works locally
+with Codex, Claude Code, Cursor, VS Code/Copilot, and any MCP client—without an
+ADB Ready account, hosted service, or model API key.
+
+| Prepare | Operate | Prove |
+| --- | --- | --- |
+| Select one target, connect it, start the project, and keep ports healthy. | Inspect semantic UI, launch apps, act on elements, and capture the screen. | Gate tests on real readiness and return structured logs, context, and artifacts. |
+
+## Built for agentic Android development
+
+Most coding agents can edit an Android project but cannot verify the running
+app. ADB Ready closes that loop with a built-in local MCP server and typed tools
+for target readiness, development sessions, app lifecycle, semantic UI, logs,
+and visual evidence—without handing the model an unrestricted shell or raw ADB.
 
 ```bash
-npx adb-ready dev
+# Connect the current project to your coding agent
+npx adb-ready agent setup codex
 ```
 
+Your agent can:
+
+- find and bind one deterministic Android target;
+- start, check, and stop a durable development session across agent reconnects;
+- resolve, install, launch, restart, and inspect the project app;
+- find or assert semantic UI, tap by intent, type, swipe, and compare state;
+- capture screenshots and read bounded, redacted session evidence; and
+- verify actions against fresh device state instead of assuming they worked.
+
+Every action is bound to one verified target and checked against fresh device
+state. Stale UI references are rejected, destructive app removal is not exposed
+to agents, and every tool returns a schema-validated result. Everything stays
+local unless your chosen AI client sends tool results to its model provider.
+
+[Connect an AI agent in minutes →](./docs/agent-integration.md)
+
 ## Why ADB Ready?
 
 ### Start once. Stay ready.
@@ -51,20 +94,20 @@ When a wireless target or reverse mapping disappears, recovery is bounded,
 target-safe, and independently verified. It never silently restarts the shared
 ADB server or rewrites another tool's mapping.
 
-### Get signal instead of noise.
+### Give agents evidence, not terminal noise.
 
 Focused logcat, structured problems, and a saved redacted timeline keep the
-important failure evidence together. One command turns it into compact context
-for any AI assistant—without uploading anything.
+important failure evidence together. Agents receive bounded, machine-readable
+context and typed actions instead of guessing from an unstructured terminal.
 
 ### Keep your existing stack.
 
 ADB Ready orchestrates the real ADB, framework, and package manager you already
 use. It does not replace Android Studio or force your project onto Bun.
 
-| Projects | Package managers | CLI runtimes |
-| --- | --- | --- |
-| Expo · React Native · Gradle · custom | npm · pnpm · Yarn · Bun | Node.js · Bun · Deno |
+| Projects                              | Package managers        | CLI runtimes         |
+| ------------------------------------- | ----------------------- | -------------------- |
+| Expo · React Native · Flutter · Capacitor · Gradle · custom | npm · pnpm · Yarn · Bun | Node.js · Bun · Deno |
 
 ## Quick start
 
@@ -97,18 +140,24 @@ Running `adb-ready` without a command opens the interactive workflow home.
 
 ## Find your workflow
 
-| I want to… | Start here |
-| --- | --- |
-| launch Expo, React Native, Gradle, or my own command | [`adb-ready dev`](./docs/dev-sessions.md) |
-| pair or reconnect an Android device over Wi-Fi | [Targets and Wireless debugging](./docs/targets-and-wireless.md) |
-| choose the right device when several are connected | [Deterministic target selection](./docs/targets-and-wireless.md#explicit-selection) |
-| expose Metro, a local API, or a debugger to Android | [Port workflows](./docs/dev-sessions.md#port-ownership) |
-| see only the Android logs that matter | [Focused logcat](./docs/logs-and-context.md#focused-logcat) |
-| understand why the last session failed | [Session problems](./docs/logs-and-context.md#session-history) |
-| prepare safe evidence for an AI assistant | [Diagnostic context](./docs/logs-and-context.md#diagnostic-context) |
-| share project settings without a custom shell script | [Configuration](./docs/configuration.md) |
-| use ADB Ready from CI or another tool | [Automation contract](./docs/automation.md) |
-| fix a known setup or target problem | [Troubleshooting](./docs/troubleshooting.md) |
+| I want to…                                                  | Start here                                                                          |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| launch Expo, React Native, Flutter, Capacitor, Gradle, or my own command | [`adb-ready dev`](./docs/dev-sessions.md)                               |
+| pair or reconnect an Android device over Wi-Fi              | [Targets and Wireless debugging](./docs/targets-and-wireless.md)                    |
+| choose the right device when several are connected          | [Deterministic target selection](./docs/targets-and-wireless.md#explicit-selection) |
+| expose Metro, a local API, or a debugger to Android         | [Port workflows](./docs/dev-sessions.md#port-ownership)                             |
+| install, inspect, launch, restart, or deep-link my app      | [App lifecycle](./docs/apps-and-evidence.md#app-lifecycle)                          |
+| save a verified screenshot or bounded screen recording      | [Evidence capture](./docs/apps-and-evidence.md#evidence-capture)                    |
+| give a developer or agent one bounded app/UI snapshot       | [Structured inspection](./docs/apps-and-evidence.md#structured-inspection)          |
+| find, read, fill, scroll, and verify the Android UI        | [Safe UI automation](./docs/ui-automation.md)                                       |
+| see only the Android logs that matter                       | [Focused logcat](./docs/logs-and-context.md#focused-logcat)                         |
+| understand why the last session failed                      | [Session problems](./docs/logs-and-context.md#session-history)                      |
+| prepare safe evidence for an AI assistant                   | [Diagnostic context](./docs/logs-and-context.md#diagnostic-context)                 |
+| connect Codex, Claude Code, Cursor, Copilot, or Windsurf    | [`adb-ready agent setup`](./docs/agent-integration.md#connect-an-agent)             |
+| share project settings without a custom shell script        | [Configuration](./docs/configuration.md)                                            |
+| use ADB Ready from CI or another tool                       | [Automation contract](./docs/automation.md)                                         |
+| run one smoke test and keep its logs, result, and report    | [`adb-ready run`](./docs/automation.md#run-one-bounded-verification)                 |
+| fix a known setup or target problem                         | [Troubleshooting](./docs/troubleshooting.md)                                        |
 
 ## What happens in `adb-ready dev`?
 
@@ -137,7 +186,7 @@ adb-ready dev -- pnpm run android:local
 adb-ready dev --dry-run --json
 ```
 
-## Built for humans and automation
+## Built for humans, agents, and automation
 
 The interactive CLI provides keyboard navigation, live state, reduced-motion
 support, narrow-terminal fallbacks, and clear recovery feedback. Scripts get a
@@ -147,6 +196,7 @@ separate deterministic contract:
 adb-ready devices --json --non-interactive
 adb-ready logs --package com.example.app --format ndjson
 adb-ready context --since 5m --only problems,recovery,logs
+adb-ready sessions list --status failed --since 24h --limit 5
 ```
 
 - machine data on `stdout`, human diagnostics on `stderr`;
@@ -155,19 +205,28 @@ adb-ready context --since 5m --only problems,recovery,logs
 - stable problem categories, meaningful exit codes, timeouts, and dry runs; and
 - explicit target, ADB path, and remote ADB server overrides.
 
+Local AI agents use the same contracts through a schema-validated MCP stdio
+server. The package includes a version-matched public tool schema, while target
+binding, fresh-state checks, redaction, and verification remain enforced by ADB
+Ready itself. [Explore the agent contract →](./docs/agent-integration.md)
+
 ## Documentation
 
-| Guide | What it answers |
-| --- | --- |
-| [Getting started](./docs/getting-started.md) | How do I reach my first ready session? |
-| [Development sessions](./docs/dev-sessions.md) | What does ADB Ready own, watch, recover, and clean up? |
-| [Targets and Wireless debugging](./docs/targets-and-wireless.md) | How are devices paired, connected, and selected safely? |
-| [Logs and AI context](./docs/logs-and-context.md) | What is captured, redacted, saved, and exported? |
-| [Configuration](./docs/configuration.md) | How do projects, profiles, hooks, and precedence work? |
-| [Automation](./docs/automation.md) | What are the JSON, NDJSON, stdout, and exit-code contracts? |
-| [Troubleshooting](./docs/troubleshooting.md) | What should I do for each common failure? |
-| [Compatibility](./COMPATIBILITY.md) | Which hosts, runtimes, and environments are covered? |
-| [Example configs](./examples/README.md) | What can I copy for Expo, React Native, Gradle, or custom projects? |
+| Guide                                                            | What it answers                                                       |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [Getting started](./docs/getting-started.md)                     | How do I reach my first ready session?                                |
+| [Development sessions](./docs/dev-sessions.md)                   | What does ADB Ready own, watch, recover, and clean up?                |
+| [Targets and Wireless debugging](./docs/targets-and-wireless.md) | How are devices paired, connected, and selected safely?               |
+| [Apps and evidence](./docs/apps-and-evidence.md)                 | How do I control one app and capture verified device evidence?        |
+| [AI agent integration](./docs/agent-integration.md)              | How do Codex, Claude Code, Cursor, or Copilot use safe Android tools? |
+| [Safe UI automation](./docs/ui-automation.md)                    | How do humans and agents act on current UI with verifiable evidence?  |
+| [Logs and AI context](./docs/logs-and-context.md)                | What is captured, redacted, saved, and exported?                      |
+| [Configuration](./docs/configuration.md)                         | How do projects, profiles, hooks, and precedence work?                |
+| [Automation](./docs/automation.md)                               | What are the JSON, NDJSON, stdout, and exit-code contracts?           |
+| [Threat model](./docs/threat-model.md)                           | Which trust boundaries, controls, and residual risks apply?           |
+| [Troubleshooting](./docs/troubleshooting.md)                     | What should I do for each common failure?                             |
+| [Compatibility](./COMPATIBILITY.md)                              | Which hosts, runtimes, and environments are covered?                  |
+| [Example configs](./examples/README.md)                          | What can I copy for Expo, React Native, Flutter, Capacitor, Gradle, or custom projects? |
 
 Run `adb-ready --help` for the full command list or
 `adb-ready help COMMAND` for focused options.
@@ -189,13 +248,17 @@ Android transport backend.
 - Session data is bounded, redacted, private to the user, and never uploaded.
 - Package contents are allowlisted and checked before release.
 - npm publication is prepared for short-lived OIDC credentials and provenance.
+- AI clients receive typed bounded tools; raw shell/ADB and destructive app
+  removal are not exposed through MCP.
+- UI references are bound to the current hierarchy digest, so stale targets are
+  rejected before input is sent.
 
 ## Project
 
 [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) ·
 [Security](./SECURITY.md) · [MIT License](./LICENSE)
 
-ADB Ready is Android-only. The `0.1.x` releases focus on target acquisition,
-ports, development-session recovery, logs, diagnostics, and automation. App
-lifecycle, files, screenshots, screen recording, and shell workflows come
-after this core is proven on real projects.
+ADB Ready is Android-only. The current development line combines target
+readiness, ports, session recovery, logs, verified app lifecycle, and local
+evidence capture. It intentionally exposes typed workflows instead of a generic
+remote shell.