adb-ready 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -9,6 +9,82 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-27
+
+### Added
+
+- Add a maintained, commit-pinned GitHub Actions emulator workflow and public
+  fixture that exercise one target-locked finite run and retain normalized
+  results, JUnit, screenshot, and diagnostic evidence on success or failure.
+- Add a manual, commit-pinned self-hosted physical-device recipe with explicit
+  runner routing, serial selection, local target leasing, read-only preflight,
+  portable execution, and retained failure evidence.
+- Add a Gradle Managed Devices handoff that discovers declared virtual-device
+  and group tasks, previews exact execution, preserves Gradle lifecycle
+  ownership, supports explicit sharding and server rendering, and normalizes
+  current JUnit, report, timeout, cancellation, assertion, and infrastructure
+  evidence.
+- Add an explicit Firebase Test Lab adapter for live catalog validation,
+  instrumentation and Robo matrices, stable provider outcome categories,
+  bounded native artifact retention, local-observer timeouts that leave remote
+  work running, and separately confirmed matrix cancellation.
+- Add explicit local, existing-AVD, remote-ADB, and Firebase target pools with
+  bounded fan-out, required/optional members, fail-fast submission policy,
+  owner-recorded lease queueing, deterministic cancellation and stale-owner
+  recovery, and aggregate results that preserve every isolated member run.
+- Add a bounded read-only protocol preflight for every explicit ADB server
+  command, with distinct route, invalid-endpoint, timeout, cancellation, and
+  version-mismatch failures that stop before upstream ADB can terminate a
+  mismatched shared server.
+
+## [0.6.0] - 2026-09-27
+
+### Added
+
+- Add the project-local `bun what` command browser for contributors who want
+  to discover and launch repository tasks without scanning `package.json`.
+- Add balanced, fast, and strict semantic UI acquisition profiles with
+  observation timing, freshness, stability, filtering, truncation, and
+  framework-limitation metadata; reject empty and continuously unstable UI
+  hierarchies instead of returning a silent false success.
+- Add bounded `compare_ui` hierarchy diffs for agents, reporting semantic nodes
+  that were added, removed, updated, or moved while refusing stale,
+  cross-target, partial, differently filtered, or display-incompatible bases.
+- Add capability-detected Unicode, emoji, RTL, CJK, and multiline UI input
+  through an already enabled ADBKeyBoard IME, configurable per-code-point
+  pacing, exact prior-IME restoration, and explicit pre-mutation failures when
+  the target cannot meet the requested input contract.
+- Add protected CLI stdin and MCP environment-variable input so secrets stay
+  out of host process arguments, operation plans, terminal output, retained
+  results, journals, screenshots, and AI context, with documented Android-side
+  trust boundaries.
+- Add guarded keyboard status and dismissal using agreeing InputMethodManager
+  and WindowInsets signals, plus exact PermissionController runtime-permission
+  inspection and responses with fresh post-action verification across CLI and
+  MCP. Unknown or ambiguous system UI now fails closed instead of pressing or
+  tapping speculatively.
+- Add decoded and checksum-verified PNG evidence with source-pixel crops,
+  proportional dimension limits, capture provenance, and truncation metadata;
+  MCP image results now default to a context-safe 1024×1024 and 4 MiB base64 budget
+  with an explicit full-resolution opt-in.
+- Add `inspect failures` and `inspect_failures` to correlate bounded,
+  package-scoped ApplicationExitInfo, crash-buffer, ANR, React Native, native,
+  and permitted DropBox evidence while reporting unavailable Android sources
+  and excluding unrelated process failures.
+- Add discoverable `debug`, `session`, `ui`, and backward-compatible `full` MCP
+  profiles, a config-independent capabilities tool/resource, and namespaced
+  safety, sensitivity, target-binding, and profile metadata generated into the
+  public agent contract.
+- Generate and package a version-matched task-first Agent Skill from the real
+  MCP tool contract, then install it atomically with project-scoped Codex,
+  Claude Code, Cursor, or VS Code setup without overwriting custom content.
+- Document durable start/get/stop development handles as the cross-client
+  compatibility path while keeping the MCP Tasks extension unadvertised until
+  negotiated interoperability is proven in two supported clients.
+- Add target-locked Maestro and Android CLI verifier adapters, bounded native
+  report/screenshot/video/log retention, and structured verifier outcome
+  categories without translating either tool's test or Journey format.
+
 ## [0.5.1] - 2026-09-25
 
 ### Added
@@ -423,7 +499,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.5.1...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/Adam014/adb-ready/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/Adam014/adb-ready/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/Adam014/adb-ready/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/Adam014/adb-ready/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/Adam014/adb-ready/compare/v0.4.0...v0.4.1

package/COMPATIBILITY.md

@@ -23,8 +23,19 @@ claims move to the CI tier only after they have a reproducible test environment.
 - Node.js 22 or newer is the installation baseline.
 - `adb` remains an external dependency and can be supplied through `PATH`, an
   Android SDK location, or `--adb PATH`.
+- Firebase Test Lab workflows delegate to the current Google Cloud CLI supplied
+  through `PATH` or `--gcloud PATH`. Provider access, billing, quotas, catalog
+  availability, and Cloud Storage permissions remain Google Cloud project
+  capabilities rather than host-runtime guarantees.
 - USB and wireless visibility depend on what the selected ADB server can access.
   Remote servers are supported through `--adb-host` and `--adb-port`.
+- Explicit ADB server endpoints receive a bounded read-only `host:version`
+  safety preflight before every upstream ADB command. Route loss, endpoint
+  replacement, invalid protocol responses, and client/server protocol mismatch
+  fail without asking upstream ADB to kill or restart the shared server.
+- Target-pool leases coordinate processes sharing one host-local per-user state
+  directory. They are not a cross-runner distributed lock; multi-host labs need
+  explicit runner routing or an external coordination backend.
 - npm, pnpm, Yarn, and Bun consumers use the same package and the same
   `adb-ready`/`adbr` entrypoint.
 
@@ -43,3 +54,23 @@ Recorded physical acceptance:
 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.
+
+Firebase Test Lab command construction, catalog parsing, official exit-code
+normalization, bounded evidence collection, cancellation, and failure paths are
+covered by deterministic fixtures. The current Google Cloud CLI has also been
+used to verify the real unauthenticated failure boundary. A paid remote matrix
+has not yet been recorded for this release, so successful provider execution is
+not presented as observed acceptance evidence.
+
+Target-pool scheduling, bounded concurrency, fail-fast submission, queue
+cancellation, stale-owner recovery, and aggregate semantics are covered by
+deterministic fixtures. Cross-host contention and paid provider fan-out remain
+outside the observed acceptance boundary until suitable infrastructure is
+available.
+
+Remote-server safety is exercised against real loopback TCP fixtures carrying
+the ADB framing protocol, including connection refusal, timeout, cancellation,
+malformed/rejected responses, matching versions, and server replacement. This
+does not claim that every WSL, container, VPN, or remote lab route has been
+observed; those environments remain upstream-capable until recorded on the real
+host network.

package/README.md

@@ -82,18 +82,26 @@ to reveal an action.
 - [**Run the project**](./docs/dev-sessions.md) — select one target, prepare
   ports, launch the framework, and keep the session healthy.
 - [**Connect the device**](./docs/targets-and-wireless.md) — discover, pair,
-  reconnect, and deterministically bind a physical device or emulator.
+  reconnect, and deterministically bind a physical device, emulator, or
+  protected remote ADB server without silently restarting shared infrastructure.
 - [**Operate the app**](./docs/apps-and-evidence.md#app-lifecycle) — resolve,
   install, launch, restart, deep-link, and inspect the project app.
 - [**Verify the UI**](./docs/ui-automation.md) — find semantic elements, act
-  by intent—including labels inside clickable containers and content-directed
-  scrolling—assert state, audit effective accessibility labels, and capture the
+  by intent—including international text, protected input, keyboard state, and
+  runtime-permission dialogs—assert state, audit accessibility, and capture the
   screen.
 - [**Debug with evidence**](./docs/logs-and-context.md) — keep focused logs,
-  session history, screenshots, recordings, and redacted context together.
+  correlated crash/ANR/native findings, session history, screenshots,
+  recordings, and redacted context together.
 - [**Automate a real device**](./docs/automation.md#run-one-bounded-verification)
   — gate a finite command on readiness and return stable results, reports, and
   artifacts.
+- [**Run cloud device matrices**](./docs/firebase-test-lab.md) — validate live
+  Firebase dimensions, run instrumentation or Robo tests, and retain normalized
+  provider evidence without storing cloud credentials.
+- [**Fan out across explicit targets**](./docs/target-pools.md) — run the same
+  bounded check on named local, AVD, remote-ADB, or Firebase pools while each
+  target keeps an isolated lease, session, result, and cleanup boundary.
 
 ## Choose how you work
 
@@ -106,16 +114,20 @@ Windsurf, or another MCP client:
 npx adb-ready agent setup codex
 ```
 
+Setup writes the project MCP bridge and a version-matched Agent Skill. Use
+`--mcp-profile debug`, `session`, or `ui` to expose only the tools needed for
+that job; `full` remains the default.
+
 Then ask for the outcome you want:
 
 > Start this Expo app on my Android phone, wait until the login screen is
 > actually ready, verify my change, and keep the failure evidence.
 
 The local MCP server gives agents typed tools for target readiness, durable
-development sessions, app lifecycle, semantic UI, logs, screenshots, and saved
-evidence. Every result is schema-validated and checked against fresh device
-state. Agents do not receive a generic shell, unrestricted raw ADB, or app
-removal.
+development sessions, app lifecycle, semantic UI, correlated failure evidence,
+screenshots, and saved diagnostics. Every result is schema-validated, annotated
+for safety, and checked against fresh device state. Agents do not receive a
+generic shell, unrestricted raw ADB, or app removal.
 
 [Connect an AI agent in minutes →](./docs/agent-integration.md)
 
@@ -178,12 +190,13 @@ Or make the target and deployment part of the same bounded job:
 
 ```bash
 npx adb-ready run --avd Pixel_9_API_36 --deploy --variant debug -- \
-  maestro '--device={target.serial}' test .maestro/smoke.yaml
+  maestro test .maestro/smoke.yaml
 ```
 
 Each executed run retains a redacted evidence bundle with its result,
-timeline, problems, focused logcat, native verifier output, AI context, JUnit
-XML, and GitHub step summary. Existing matching emulators are reused; only an
+timeline, problems, focused logcat, native verifier output and artifacts, AI
+context, JUnit XML, and GitHub step summary. Maestro and Android CLI primitives
+are pinned to the leased target automatically. Existing matching emulators are reused; only an
 emulator started by that run is stopped. Scripts also get deterministic JSON
 and NDJSON contracts:
 
@@ -195,6 +208,12 @@ adb-ready sessions list --status failed --since 24h --limit 5
 
 [Build a readiness-gated device job →](./docs/automation.md)
 
+Need a hosted target first? Start from the maintained
+[GitHub Actions emulator workflow](./examples/ci-emulator/), which runs one
+bounded target-locked job and preserves evidence even when verification fails.
+For a dedicated real device, use the manual-only
+[self-hosted physical-device recipe](./examples/ci-physical/).
+
 ## One target. One verified loop.
 
 ```text
@@ -272,6 +291,9 @@ Android transport backend.
 | [Logs and AI context](./docs/logs-and-context.md) | Diagnose a failure with bounded, redacted evidence. |
 | [AI agent integration](./docs/agent-integration.md) | Connect an MCP-capable coding agent. |
 | [Automation](./docs/automation.md) | Use readiness, exit codes, JSON, NDJSON, JUnit, and CI artifacts. |
+| [Gradle Managed Devices](./docs/gradle-managed-devices.md) | Run build-owned virtual-device and group tests with normalized evidence. |
+| [Firebase Test Lab](./docs/firebase-test-lab.md) | Run explicit remote instrumentation or Robo matrices with bounded evidence. |
+| [Target pools and fan-out](./docs/target-pools.md) | Bound parallel verification across an explicit target set. |
 | [Configuration](./docs/configuration.md) | Share project presets, hooks, aliases, and policies. |
 | [Troubleshooting](./docs/troubleshooting.md) | Resolve a known setup, target, UI, or session problem. |
 | [Compatibility](./COMPATIBILITY.md) | Check hosts, runtimes, package managers, and support tiers. |