adb-ready 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -9,6 +9,89 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-25
+
+### Added
+
+- Add a first-device guide under Start that walks new users through USB,
+  Android 11+ Wireless debugging, or an existing emulator before handing off
+  to the normal verified devices, pairing, or connection workflow.
+
+### Fixed
+
+- Make interactive selection unmistakable with one directional cursor and a
+  high-contrast active row, while retaining explicit no-color and ASCII
+  fallbacks and removing distracting markers from inactive choices.
+- Group session launch, planning, bounded verification, wireless connection,
+  and pairing under one focused Start workflow instead of scattering entry
+  actions across unrelated top-level categories.
+
+## [0.5.0] - 2026-09-21
+
+### Fixed
+
+- Adapt the interactive home to terminal height with full, compact, and minimal
+  layouts so every action remains visible in short panes.
+- Derive interactive-home numeric shortcut hints from the visible choices so
+  every numbered action is accurately discoverable.
+- Honor plain, JSON, and NDJSON output for both the `version` command and
+  `--version` shortcut while preserving conventional bare human output.
+- Compile every `dev` and `run` dry run offline, including explicit device,
+  transport, remembered-target, interactive-selection, artifact, and AVD
+  inputs, so planning cannot inspect or mutate an Android target.
+- Show autonomous target inspection, artifact selection, and verified app
+  deployment as live run steps, then preserve their compact result in human and
+  plain summaries without exposing local artifact paths.
+- Restrict stable-identity probes to an explicitly selected serial, alias, or
+  transport ID so target-aware commands do not query unrelated visible Android
+  devices before operating on the requested target.
+- Label port mappings by explicit host and device roles and show their actual
+  direction, including listener-specific removal plans, instead of presenting
+  distinct endpoints as an ambiguous bidirectional pair.
+- Reconcile running session summaries from their complete persisted events so
+  session lists, details, and AI context show current counts, timestamps, and
+  the resolved preset before finalization without per-log manifest rewrites.
+- Scope development-session crash diagnostics to a verified Android package
+  UID or PID, retarget Expo logs after its resolved launch, and keep unrelated
+  target-process crashes out of application problems and below attributed
+  evidence in prioritized AI context.
+- Serialize Android UI hierarchy capture per target across CLI and MCP
+  processes, preventing concurrent read-only automation from racing the
+  platform's single active UI Automation service, without taking a mutation
+  lease for read-only UI queries.
+- Replace non-functional framework shortcut claims with ADB Ready-owned Expo
+  reload and developer-menu controls over a verified local Expo channel, and
+  advertise them only after the interactive control input is active.
+- Verify Expo's canonical project identity before attaching to an existing
+  Metro server, preventing a development session from silently reusing another
+  project's server on the same port.
+- Support Expo and other localhost services that listen only on IPv6 by
+  creating a session-owned IPv4 loopback bridge for `adb reverse`, then close
+  that bridge during ownership-safe cleanup.
+
+### Added
+
+- Model optional Android tooling as typed `supported`, `unavailable`,
+  `incompatible`, or `unverified` capabilities and build deterministic,
+  non-mutating plans for autonomous target, deployment, verifier, evidence,
+  and owned-resource cleanup workflows.
+- Reuse or start one exact existing Android virtual device, prove ADB, boot,
+  package-manager, and unlock readiness, and stop only emulator processes that
+  the active workflow owns.
+- Resolve explicit or framework build artifacts from bounded Android output
+  metadata, keep ABI variants separate, select only proven target-compatible
+  APKs, and reject stale, ambiguous, incomplete, or unsafe candidates.
+- Deploy APK and split APK artifacts through one target-scoped ADB transport,
+  build and install AAB or APK Set inputs with explicit bundletool, verify the
+  installed package, version, and launch activity, and clean only owned
+  temporary output.
+- Compose existing-AVD startup, deterministic artifact deployment, project
+  readiness, one bounded external verifier, normalized evidence, and
+  ownership-safe cleanup in the existing `run` command with a mutation-free
+  dry-run plan.
+- Preserve bounded, redacted native verifier stdout and stderr in every run
+  evidence bundle, including structured preparation failures after cleanup.
+
 ## [0.4.1] - 2026-09-16
 
 ### Fixed
@@ -340,7 +423,10 @@ 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.4.0...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.5.1...HEAD
+[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
 [0.4.0]: https://github.com/Adam014/adb-ready/compare/v0.3.5...v0.4.0
 [0.3.5]: https://github.com/Adam014/adb-ready/compare/v0.3.4...v0.3.5
 [0.3.4]: https://github.com/Adam014/adb-ready/compare/v0.3.3...v0.3.4

package/README.md

@@ -71,8 +71,11 @@ them or require an ADB Ready account, hosted service, or model API key.
 
 Running `adb-ready` without a command opens the interactive workflow home.
 `adbr` is the shorter alias for the same CLI.
-The home and its focused menus adapt to the detected terminal width, including
-narrow split panes, without relying on horizontal scrolling.
+New to Android device setup? Open **Start → Set up first device** for a guided
+USB, Wireless debugging, or emulator path.
+The home and its focused menus adapt to the detected terminal width and height,
+including narrow split panes and short terminals, without relying on scrolling
+to reveal an action.
 
 ## What ADB Ready does
 
@@ -145,16 +148,20 @@ variables are discovered with Expo's own development environment resolution.
 ADB Ready safely adds their ports to the selected target and verifies the host
 services before calling the session ready. Explicit port configuration always
 wins, and `--no-auto-reverse-localhost` disables discovery when required.
+IPv4 and IPv6 loopback listeners are supported; when ADB cannot reach an
+IPv6-only service directly, ADB Ready creates and cleans a local session bridge.
 
-In an interactive Expo or Flutter session, ADB Ready shows the framework's
-active reload, developer-menu, debugger, and help shortcuts as soon as the
-session is ready. Input continues directly to the framework; automation and
-redirected output stay prompt-free.
+In an interactive Expo session that ADB Ready owns, the ready state activates
+verified `r` reload, `m` developer-menu, `?` help, and `Ctrl+C` cleanup controls.
+ADB Ready advertises only actions it can execute; attached Metro servers keep
+their controls in the original terminal, while automation and redirected output
+stay prompt-free. [See live-session behavior →](./docs/dev-sessions.md#live-terminal-controls)
 
 If Expo or React Native Metro is already running, ADB Ready verifies its
-standard status endpoint and attaches the Android session without restarting or
-owning that server. An unrelated process on the same port is reported as a
-clear conflict instead of being mistaken for Metro.
+standard status endpoint and project identity before attaching the Android
+session without restarting or owning that server. A Metro server from another
+project—or an unrelated process on the same port—is reported as a clear
+conflict instead of being reused.
 
 [Reach your first ready session →](./docs/getting-started.md)
 
@@ -167,9 +174,18 @@ its exit code, and clean only resources created by the run:
 npx adb-ready run -- npm run test:e2e
 ```
 
+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
+```
+
 Each executed run retains a redacted evidence bundle with its result,
-timeline, problems, focused logcat, AI context, JUnit XML, and GitHub step
-summary. Scripts also get deterministic JSON and NDJSON contracts:
+timeline, problems, focused logcat, native verifier output, AI context, JUnit
+XML, and GitHub step summary. Existing matching emulators are reused; only an
+emulator started by that run is stopped. Scripts also get deterministic JSON
+and NDJSON contracts:
 
 ```bash
 adb-ready devices --json --non-interactive
@@ -230,7 +246,12 @@ Android transport backend.
 - Pairing codes never enter command-line arguments.
 - Session data is bounded, redacted, private to the local user, and never
   uploaded by ADB Ready.
+- Crash diagnostics are promoted only after ADB Ready verifies the application
+  package on the selected target; unrelated device-process failures remain
+  explicitly unattributed evidence.
 - Stale UI references are rejected before input is sent.
+- UI hierarchy capture is serialized per target across CLI and MCP processes,
+  while independent targets remain parallel.
 - Field replacement verifies values without confusing a declared Android hint
   for user-entered text.
 - Screen recordings require a readable MP4 and a real multi-frame timeline;