adb-ready 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -9,6 +9,101 @@ 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
@@ -81,7 +176,8 @@ 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.2.0...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

package/README.md

@@ -2,10 +2,10 @@
 
 # ADB Ready
 
-**Make Android development accessible to coding agents.**
+**The local Android runtime for coding agents.**
 
-An MCP-native, local-first CLI that gives agents and developers safe, typed
-control of Android targets, apps, UI, logs, evidence, and development sessions.
+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)
@@ -13,14 +13,26 @@ control of Android targets, apps, UI, logs, evidence, and development sessions.
 [![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) · [AI agents](#android-tools-built-for-ai-agents) · [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
 
@@ -30,37 +42,41 @@ $ 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 scattered ADB operations into
-one deterministic workflow that developers, scripts, and AI agents can share.
+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.
 
-```bash
-npx adb-ready dev
-```
+| 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. |
 
-## Android tools built for AI agents
+## Built for agentic Android development
 
-ADB Ready turns coding agents from passive log readers into safe Android
-operators. Its local MCP server exposes **19 schema-validated tools** for target
-readiness, app lifecycle, UI inspection, evidence capture, and verified UI
-actions—without giving the model a generic shell or unrestricted ADB access.
+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
 # Connect the current project to your coding agent
 npx adb-ready agent setup codex
 ```
 
-Codex, Claude Code, Cursor, VS Code/Copilot, Windsurf, and other MCP clients can:
+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;
-- inspect current UI, tap, type, swipe, press keys, and wait for state changes;
+- 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.
 
-Everything stays local unless your chosen AI client sends tool results to its
-model provider. Stale UI references are rejected, destructive app removal is
-not exposed to agents, and every tool returns structured evidence.
+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)
 
@@ -91,7 +107,7 @@ 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 |
+| Expo · React Native · Flutter · Capacitor · Gradle · custom | npm · pnpm · Yarn · Bun | Node.js · Bun · Deno |
 
 ## Quick start
 
@@ -126,20 +142,21 @@ Running `adb-ready` without a command opens the interactive workflow home.
 
 | I want to…                                                  | Start here                                                                          |
 | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| launch Expo, React Native, Gradle, or my own command        | [`adb-ready dev`](./docs/dev-sessions.md)                                           |
+| 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)          |
-| safely tap, type, swipe, press keys, or wait for Android UI | [Safe UI automation](./docs/ui-automation.md)                                       |
+| 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`?
@@ -179,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`;
@@ -208,7 +226,7 @@ Ready itself. [Explore the agent contract →](./docs/agent-integration.md)
 | [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, Gradle, or custom projects?   |
+| [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.