adb-ready 0.3.4 → 0.4.0

package/docs/RELEASING.md

@@ -24,7 +24,8 @@ The workflow does not use a long-lived npm write token.
 Release evidence has three tiers:
 
 - **Every release:** the complete fixture, unit, integration, runtime, package,
-  documentation, privacy, and release-artifact verification gate must pass.
+  documentation, privacy, coverage, and release-artifact verification gate must
+  pass. Pull requests must also satisfy the 95% changed-line coverage gate.
 - **Device-behavior changes:** rerun every affected workflow on a real target
   and record the exact host, target, Android version, and transport. A
   documentation, metadata, or machine-output-only patch does not manufacture

package/docs/apps-and-evidence.md

@@ -15,6 +15,9 @@ adb-ready app info
 
 Resolution prefers an explicit `APP_ID`, then project configuration and
 detected Android project metadata. Every resolved result includes provenance.
+Unavailable optional package metadata, such as an application without an
+Android `versionName`, is omitted from structured output instead of being
+reported as a literal sentinel value.
 If equally valid candidates remain, ADB Ready asks for an explicit choice
 instead of selecting the first package.
 
@@ -134,6 +137,13 @@ symlink outside that root and never replaces an existing file unless `--force`
 is explicit. Files are written through a private temporary path and published
 only after validation.
 
+For a recording, validation means more than finding an MP4 filename or header:
+the container must be structurally readable and its video track must contain a
+non-zero timeline with multiple frames. The result reports the measured media
+duration and frame count. If Android emits a one-frame, zero-duration recording
+while the display is static, ADB Ready rejects it with `SCREEN_RECORD_EMPTY`
+instead of publishing unusable evidence; create visible activity and retry.
+
 Some multi-display Android builds, including foldables, emit a short textual
 warning before the screenshot bytes. ADB Ready removes only a bounded text
 preamble and still requires a valid PNG signature before publishing the file.
@@ -142,6 +152,7 @@ The result contains:
 
 - a project-relative path;
 - media type and byte size;
+- measured duration and video frame count for recordings;
 - SHA-256 digest;
 - selected target and capture-command provenance.
 

package/docs/configuration.md

@@ -69,6 +69,7 @@ existing file unless `--force` is explicit. Use `--dry-run` first.
 | `packageManager` | `npm`, `pnpm`, `yarn`, or `bun` |
 | `command` | `{ "executable": string, "args": string[], "cwd"?: string }` |
 | `reversePorts` | integers or `{ "device": number, "host"?: number }` objects |
+| `autoReverseLocalhost` | detect explicit localhost URLs in Expo `EXPO_PUBLIC_*` variables; defaults to `true` |
 | `logs` | enable the session's targeted log stream |
 | `cleanupPorts` | remove only mappings created by this session |
 | `watch` | monitor and recover target, port, and log health |
@@ -80,6 +81,12 @@ existing file unless `--force` is explicit. Use `--dry-run` first.
 Unknown keys and invalid nested values fail validation rather than being
 silently ignored.
 
+`init` detects and writes `packageManager` only for Expo, React Native, and
+Capacitor presets, where it selects the project CLI. Flutter and native Gradle
+use their own launchers, so an unrelated package-manager executable available
+on the host is not recorded as project configuration. An explicit
+`--package-manager` override is still preserved.
+
 ## Profiles
 
 Profiles can inherit from one named parent. Cycles and missing references are
@@ -134,6 +141,7 @@ Supported environment variables include:
 | `ADB_READY_PRESET` | development preset |
 | `ADB_READY_PACKAGE_MANAGER` | package manager |
 | `ADB_READY_REVERSE_PORTS` | comma-separated device ports |
+| `ADB_READY_AUTO_REVERSE_LOCALHOST` | boolean Expo localhost-service discovery override |
 | `ADB_READY_DEV_LOGS` | boolean |
 | `ADB_READY_CLEANUP_PORTS` | boolean |
 | `ADB_READY_DEV_WATCH` | boolean |

package/docs/dev-sessions.md

@@ -8,13 +8,18 @@ local diagnostic record.
 
 | Preset | Detection | Default command | Default reverse port |
 | --- | --- | --- | --- |
-| Expo | `expo` dependency | project `start` script with `--android`, otherwise Expo CLI | `8081` |
+| Expo | `expo` dependency | project `start` script without framework device selection, otherwise `expo start` | `8081` |
 | React Native | `react-native` dependency | project `android` script, otherwise React Native CLI | `8081` |
 | Flutter | `pubspec.yaml` | `flutter run -d <selected-target>` | none |
 | Capacitor | `@capacitor/android` or `@capacitor/core` dependency | Capacitor CLI for the selected target | none |
 | Gradle | wrapper or Gradle build file | wrapper `installDebug` | none |
 | Custom | explicit config or `--` | exact executable and argument array | none |
 
+Flutter requires the Flutter SDK's `flutter` executable on `PATH`. Native
+Gradle projects use their checked-in `gradlew` or `gradlew.bat` Wrapper; ADB
+Ready reports either missing prerequisite directly instead of suggesting an
+unrelated custom command.
+
 Select a preset when detection is intentionally unavailable or ambiguous:
 
 ```bash
@@ -28,7 +33,7 @@ adb-ready dev --preset gradle --device emulator-5554
 An exact command after `--` wins over preset command resolution:
 
 ```bash
-adb-ready dev -- bun x expo start --host lan --port 8081 --android
+adb-ready dev -- bun x expo start --host lan --port 8081
 ```
 
 No shell is inserted. Quoting, wildcard, pipe, and substitution syntax are
@@ -39,6 +44,8 @@ therefore passed as literal arguments instead of being executed unexpectedly.
 One selected transport is used for the entire session:
 
 - every direct ADB command uses its exact serial or transport ID;
+- Expo's default workflow resolves its deep link from Metro and opens it through
+  that exact transport instead of delegating target selection to Expo;
 - the child command receives `ANDROID_SERIAL`;
 - hooks receive `ANDROID_SERIAL`, `ADB_READY_SESSION_ID`,
   `ADB_READY_PRESET`, and `ADB_READY_TARGET_ID`; and
@@ -62,6 +69,84 @@ Disable cleanup only when the mapping should intentionally outlive the process:
 adb-ready dev --no-cleanup-ports
 ```
 
+## Expo localhost services
+
+Android's `localhost` belongs to the selected target, not the development host.
+For Expo projects, ADB Ready therefore resolves the same development `.env`
+files as Expo and inspects public variables whose values are explicit
+`http://`, `https://`, `ws://`, or `wss://` loopback URLs. For example,
+`EXPO_PUBLIC_API_URL=http://localhost:8000` adds `tcp:8000 → tcp:8000` to the
+session and verifies host port `8000` before reporting ready.
+
+Detection is deliberately bounded:
+
+- only `EXPO_PUBLIC_*` variables are inspected;
+- only `localhost`, `127.0.0.1`, and `[::1]` URLs with explicit ports qualify;
+- the URL value is never retained or printed—results expose only the variable
+  name, port, and loaded `.env` basenames;
+- an explicit mapping for the same device port always wins; and
+- cleanup still removes only mappings created by the current session.
+
+Preview the resolved mappings without touching ADB:
+
+```bash
+adb-ready dev --dry-run --json
+```
+
+Disable this behavior for an intentionally different network topology:
+
+```bash
+adb-ready dev --no-auto-reverse-localhost
+```
+
+The same switch is available to `adb-ready init`. It can also be persisted as
+`dev.autoReverseLocalhost: false` or set with
+`ADB_READY_AUTO_REVERSE_LOCALHOST=false`.
+
+## Existing Metro servers
+
+For Expo and React Native, ADB Ready checks the local host behind the default
+device port `8081` before launching the project command. It attaches only when
+`/status` returns Metro's exact running-status response. An open port alone is
+not sufficient evidence.
+
+An attached Metro server remains externally owned:
+
+- ADB Ready does not start, restart, send terminal controls to, or stop it.
+- `Ctrl+C` ends only the ADB Ready session and cleans only mappings created by
+  that session.
+- Human, plain, JSON, and NDJSON results identify the external attachment.
+- Session health checks detect when the external server disappears, but recovery
+  never restarts a process ADB Ready does not own.
+- A non-Metro service on the configured host port fails with
+  `DEVELOPMENT_SERVICE_CONFLICT` and an actionable explanation.
+
+Run Metro in its original terminal when you need its native reload or developer
+controls. A newly started Metro process continues to receive its controls
+directly through ADB Ready.
+
+## Expo target isolation
+
+Expo's `--android` startup path can enumerate and mutate every attached Android
+transport, even when `ANDROID_SERIAL` names one device. ADB Ready therefore
+does not add `--android` to detected Expo commands. After Metro passes
+readiness, ADB Ready:
+
+1. asks Expo's public `/_expo/open` endpoint for the Android deep link, with a
+   bounded `/_expo/link` fallback for Expo 55;
+2. routes local-network Metro URLs through the verified reverse mapping while
+   preserving public tunnel URLs;
+3. resolves the installed URL handler on the selected transport; and
+4. opens that exact component with target-scoped ADB before reporting ready.
+
+Missing Expo Go/development builds, malformed server responses, and rejected
+launches fail as `EXPO_LAUNCH_FAILED`; ADB Ready does not silently try another
+device. A command supplied after `--` remains an explicit open-world override,
+so omit `--android` when ADB Ready should retain launch ownership. Expo's native
+`a`/`shift+a` shortcuts likewise belong to Expo and can invoke its own device
+selection; the ADB Ready control bar intentionally advertises only target-safe
+runtime controls.
+
 ## Health and recovery
 
 Once ready, the session watches:
@@ -70,6 +155,23 @@ Once ready, the session watches:
 - required reverse mappings; and
 - the owned logcat stream when logs are enabled.
 
+Successful readiness and health polls are background work: they do not compete
+with framework logs and are not retained in the durable session journal.
+Failures, state changes, and recovery actions remain visible and recorded.
+
+Readiness checks and the complete session gate are separate. A host port or
+custom assertion may pass without proving that the framework launch succeeded.
+ADB Ready emits `ready` only after every configured check and target-specific
+launch succeeds while the owned development command is not already failing. If
+that command fails first, its actionable redacted error is promoted into the
+final problem instead of briefly presenting the session as ready.
+
+Foreground, activity, and unlocked checks parse the complete target-scoped
+Android state returned by `dumpsys`, including current Android 16 fields. When a
+contract does not pass, human output identifies every failed or unsupported
+assertion with its observed detail; JSON and NDJSON retain every assertion
+result for CI and agents.
+
 Recovery waits for a bounded stabilization period, attempts to reacquire the
 same target, restores only missing session mappings, restarts the targeted log
 stream when necessary, and verifies the complete state independently.
@@ -98,13 +200,32 @@ Configure the budget explicitly:
 
 Set `dev.watch` to `false` only for a deliberately one-shot child process.
 
+## Live terminal controls
+
+An interactive `adb-ready dev` session shows a compact control bar after it
+becomes ready. ADB Ready preserves the framework's native terminal input rather
+than intercepting or redefining it:
+
+- Expo shows `r` reload, `m` developer menu, `j` debugger, and `?` commands.
+- Flutter shows `r` hot reload, `R` hot restart, and `h` commands.
+- Other presets state that framework input is active without promising
+  unsupported shortcuts.
+- `Ctrl+C` stops the owned child and performs the normal verified cleanup.
+- Health monitoring is stopped and awaited before intentional child or port
+  teardown, so cancellation cannot be recorded as a device degradation or a
+  recovery attempt.
+
+The control bar is never rendered by `run`, JSON/NDJSON output, redirected
+streams, CI, `--non-interactive`, or `--quiet`. This keeps scripts deterministic
+and leaves arbitrary child input untouched.
+
 ## Lifecycle hooks
 
 Supported phases are:
 
 ```text
 beforeDev → onTargetReady → onPortsReady → onReady
-          → onChildExit → finally
+          → onChildExit (owned child only) → finally
 ```
 
 Hooks are executable/argument arrays, not shell strings. Each hook may set a

package/docs/getting-started.md

@@ -27,6 +27,9 @@ version:
 npx adb-ready doctor
 ```
 
+Run `npx adb-ready` without a command for the interactive workflow home. Its
+layout automatically switches to a compact form in narrow terminal panes.
+
 The full source build can be tested from a repository checkout:
 
 ```bash

package/docs/logs-and-context.md

@@ -36,10 +36,18 @@ Available filters:
 | `--exclude-tag TAG` | Suppress a tag; repeat to exclude more |
 | `--level PRIORITY` | Minimum `V`, `D`, `I`, `W`, `E`, `F`, `A`, or silent `S` priority |
 | `--buffer NAME` | Read `main`, `system`, or `crash`; repeat for more |
-| `--tail COUNT` | Begin with the most recent record count |
+| `--tail COUNT` | Begin with the most recent matching record count |
 | `--since TIMESTAMP` | Pass an Android logcat timestamp boundary |
 | `--max-records COUNT` | Bound records retained in the final result |
 
+The same tag cannot be passed to both `--tag` and `--exclude-tag`. ADB Ready
+rejects that contradictory request before accessing ADB so an exclusion can
+never appear to succeed while logcat returns the tag.
+
+`--tail` is applied after package, process, tag, priority, and buffer filters.
+With a live stream, ADB Ready snapshots the matching history and overlaps the
+follow boundary so records written during setup are neither lost nor repeated.
+
 Unparsed lines are preserved. Output arriving on `stderr` is not automatically
 classified as an error; severity comes from source semantics. Fatal Android
 exceptions, native crashes, ANRs, and React Native fatal errors become
@@ -117,6 +125,9 @@ Before persistence or export, ADB Ready:
 - redacts known token, credential, pairing-code, URL, and path patterns;
 - replaces observed device and project identities with short SHA-256
   fingerprints;
+- preserves operational transport IDs and bounds short literal matches to
+  complete identifier tokens, preventing unrelated timestamps, ports, hashes,
+  and correlation IDs from being altered;
 - honors additional environment names configured in
   `dev.journal.redactEnvironment`;
 - bounds both the in-memory journal and saved session history; and

package/docs/troubleshooting.md

@@ -34,7 +34,10 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `UI_NOT_IDLE` | Android UI Automator could not observe a quiet accessibility window | Pause continuous UI changes or navigate to a stable screen, then retry |
 | `SESSION_RECOVERY_FAILED` | The bounded target/port recovery budget was exhausted | Inspect `problems`, network state, and saved recovery events |
 | `SESSION_PERSISTENCE_FAILED` | The private session record could not be written | Check user-state directory permissions and capacity |
+| `FRAMEWORK_LAUNCHER_NOT_FOUND` | The detected Flutter or Gradle project has no runnable launcher | Install Flutter and expose `flutter` on PATH, or restore the project's checked-in Gradle Wrapper |
 | `CHILD_PROCESS_FAILED` | The project command exited unsuccessfully | Inspect child output, targeted logs, and preserved exit code |
+| `DEVELOPMENT_SERVICE_CONFLICT` | Metro's configured host port belongs to another service | Stop that service or map device port `8081` to the actual Metro host port |
+| `EXPO_LAUNCH_FAILED` | Expo could not provide a valid link or the selected target has no matching runtime | Install the project development build or Expo Go on that target, then retry |
 
 ## ADB is installed but not found
 
@@ -92,6 +95,28 @@ ADB Ready will reuse an exact mapping, but it will not overwrite a different
 host destination. Remove the old mapping only when you know which tool owns it,
 or choose a different device port.
 
+## An Expo app cannot reach its localhost API
+
+Run an offline preview and check whether the API port appears in the requested
+reverse mappings:
+
+```bash
+adb-ready dev --dry-run --json
+```
+
+ADB Ready automatically detects explicit loopback URLs in `EXPO_PUBLIC_*`
+variables using Expo's development `.env` resolution. If the application builds
+its URL dynamically, uses a non-public variable, or omits the URL port, declare
+the mapping explicitly:
+
+```bash
+adb-ready dev --port 8000
+```
+
+The host service must already be listening on that port. ADB Ready verifies it
+before reporting the session ready; it does not start an unknown backend on the
+user's behalf.
+
 ## A session will not recover
 
 Recovery is intentionally bounded and identity-safe. It will not connect an

package/docs/ui-automation.md

@@ -29,13 +29,20 @@ ADB Ready does not silently disable device-wide animations.
 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.
+The audit reports enabled controls that have no effective human-readable label,
+and controls that have no resource ID for a stable selector. Effective labels
+include text, hints, and content descriptions on the control, its descendants,
+or an actionable ancestor. Structural focus and scrolling containers are not
+misreported as controls merely because they are focusable or scrollable.
+
+Every finding includes its rule rationale and confidence. A partial hierarchy
+reduces the confidence of missing-label findings instead of presenting
+incomplete evidence as definitive. The audit returns exact current references,
+attributes, and 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; effective text and content-description labels remain
+usable, while a resource ID or Compose test tag exposed through
+`testTagsAsResourceId` is more resilient to copy changes.
 
 ## Tap and long-press
 
@@ -47,8 +54,11 @@ 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:
+zero or multiple matches. When unique text or a content description belongs to
+a non-clickable label inside an enabled clickable row, ADB Ready taps the
+nearest actionable ancestor. Structured results report both the label that
+matched and the action node that received the tap. Prefer a current reference
+when the exact observed snapshot matters:
 
 ```bash
 adb-ready ui tap ui:7c4a31b8d2ef:14
@@ -81,10 +91,12 @@ 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.
+field is successful only when its post-action value matches. Android may expose
+an empty field's hint as accessibility text; ADB Ready reads the separate
+platform `hint` attribute so a declared placeholder is not mistaken for a
+remaining value. 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
@@ -96,14 +108,16 @@ appending to an unknown value.
 ```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 scroll down '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.
+Direction swipes describe the physical finger gesture and use screen-relative
+points, so they work across display sizes. `scroll` describes content/viewport
+navigation instead: `scroll down` reveals content below by sending an upward
+finger gesture. It can constrain that navigation 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`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",
@@ -11,7 +11,7 @@
   "files": [
     "CHANGELOG.md",
     "COMPATIBILITY.md",
-    "dist",
+    "dist/cli.js",
     "docs",
     "examples",
     "LICENSE",
@@ -34,6 +34,7 @@
     "ui:check": "bun run scripts/ui-playground.ts --all --non-interactive",
     "test": "bun test",
     "test:coverage": "bun test --coverage && bun run scripts/coverage-check.mjs",
+    "test:coverage:diff": "bun run scripts/coverage-diff-check.mjs",
     "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",
@@ -101,6 +102,7 @@
     "yarn": "1.22.22"
   },
   "dependencies": {
+    "@expo/env": "2.4.3",
     "@modelcontextprotocol/server": "2.0.0",
     "zod": "4.5.4"
   }

package/schema/agent-tools-v1.json

@@ -1,7 +1,7 @@
 {
   "title": "ADB Ready agent tool contract",
   "schemaVersion": 1,
-  "packageVersion": "0.3.4",
+  "packageVersion": "0.4.0",
   "protocolVersion": "2025-11-25",
   "transport": "stdio",
   "tools": [
@@ -128,7 +128,7 @@
     },
     {
       "name": "audit_ui",
-      "description": "Audit the current screen for enabled actionable nodes without human-readable labels or stable automation IDs.",
+      "description": "Audit real Android controls for effective labels and stable automation IDs, with bounded findings, confidence, and rule rationale.",
       "inputSchema": {
         "type": "object",
         "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -298,7 +298,7 @@
     },
     {
       "name": "clear_ui",
-      "description": "Focus one semantic editable field, clear its value, and verify the observable value.",
+      "description": "Focus one semantic editable field, clear its value, and verify the observable value or declared hint-only state.",
       "inputSchema": {
         "type": "object",
         "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -2375,7 +2375,7 @@
     },
     {
       "name": "scroll_ui",
-      "description": "Scroll the screen or one unique semantic scroll container in a display-relative direction, then compare UI state.",
+      "description": "Navigate content in a display-relative direction within the screen or one unique semantic scroll container, then compare UI state.",
       "inputSchema": {
         "type": "object",
         "$schema": "https://json-schema.org/draft/2020-12/schema",

package/schema/config-v1.schema.json

@@ -203,6 +203,7 @@
             ]
           }
         },
+        "autoReverseLocalhost": { "type": "boolean" },
         "logs": { "type": "boolean" },
         "cleanupPorts": { "type": "boolean" },
         "watch": { "type": "boolean" },