adb-ready 0.0.1-alpha.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to ADB Ready are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and releases follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the project is below `1.0.0`, minor releases may include documented
+breaking changes.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-10
+
+### Added
+
+- Interactive and non-interactive Android workflow entrypoints.
+- Deterministic USB, emulator, and Wireless debugging target selection.
+- Secure pairing, wireless connection, and ADB capability diagnostics.
+- Verified TCP reverse and forward port management.
+- Expo, React Native, native Gradle, and direct custom development sessions.
+- Bounded target and port health recovery with independently verified repairs.
+- Targeted structured logcat, private session history, problem inspection, and
+  redacted AI-ready context export.
+- JSON Schema-backed project configuration, profiles, lifecycle hooks, and
+  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.0...HEAD
+[0.1.0]: https://github.com/Adam014/adb-ready/compare/v0.0.1-alpha.0...v0.1.0

package/COMPATIBILITY.md

@@ -0,0 +1,39 @@
+# Compatibility
+
+ADB Ready is distributed as portable JavaScript and delegates Android transport
+work to the user's real `adb` executable. It does not contain native addons and
+does not block installation by operating system or CPU architecture.
+
+## Support policy
+
+| Tier | Environments | Contract |
+| --- | --- | --- |
+| CI target | macOS arm64, Linux x64, Windows x64 | The complete verification gate is configured to run on every push and pull request. |
+| Runtime target | Node.js 22, 24, and 26; current Bun; Deno 2 npm compatibility | The packed CLI entrypoint and deterministic command contract must launch successfully. |
+| Upstream-capable | macOS x64, Linux arm64, Windows arm64, musl Linux, WSL 2, containers, ChromeOS Linux, and BSD | Supported when a compatible JavaScript runtime and a working `adb` executable are available. Reports are accepted and no package metadata intentionally blocks these hosts. |
+
+“Upstream-capable” is not a lower-priority user class. It records that the
+availability of Platform-Tools, USB passthrough, mDNS, or host networking can be
+controlled by the operating environment rather than ADB Ready. Compatibility
+claims move to the CI tier only after they have a reproducible test environment.
+
+## Architecture and dependencies
+
+- The npm artifact is architecture-neutral JavaScript.
+- 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`.
+- USB and wireless visibility depend on what the selected ADB server can access.
+  Remote servers are supported through `--adb-host` and `--adb-port`.
+- npm, pnpm, Yarn, and Bun consumers use the same package and the same
+  `adb-ready`/`adbr` entrypoint.
+
+## Honest verification boundary
+
+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`.
+
+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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ADB Ready contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,65 +1,201 @@
+<div align="center">
+
 # ADB Ready
 
-> Make an Android target ready, then keep the development session working.
+**One Android target. One reliable development session.**
+
+Select a device, prepare localhost ports, start your project, and keep the
+connection healthy—without stitching together fragile ADB scripts.
+
+[![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/)
+[![Platforms](https://img.shields.io/badge/hosts-macOS_%C2%B7_Linux_%C2%B7_Windows-64748b)](./COMPATIBILITY.md)
 
-ADB Ready is an early-alpha, Android-only developer CLI built around the real
-`adb` executable. This release establishes the portable and scriptable
-foundation for the broader development-session workflow.
+[Quick start](#quick-start) · [Why ADB Ready](#why-adb-ready) ·
+[Workflows](#find-your-workflow) · [Documentation](#documentation) ·
+[Compatibility](#compatibility)
 
-## Try the alpha
+</div>
 
-ADB Ready currently requires Node.js 22 or newer and an installed Android SDK
-Platform-Tools `adb` executable.
+```text
+$ adb-ready dev
+
+✓ Android target selected       Pixel 9 · wireless
+✓ Localhost ports ready         8081 → 8081
+✓ Development command started   pnpm run start --android
+● 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.
 
 ```bash
-npx adb-ready@alpha
-npx adb-ready@alpha doctor
-npx adb-ready@alpha devices
+npx adb-ready dev
 ```
 
-The package also exposes the shorter `adbr` command. Both names invoke the same
-CLI entrypoint.
+## Why ADB Ready?
+
+### Start once. Stay ready.
+
+ADB Ready finds one usable Android target, prepares its ports, launches your
+project with the correct `ANDROID_SERIAL`, and watches the session while you
+work.
+
+### Recover without the ritual.
+
+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.
+
+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.
+
+### 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 |
+
+## Quick start
+
+You need Android SDK Platform-Tools and Node.js 22 or newer for the standard npm
+entrypoint.
 
-## Available now
+```bash
+# Check ADB and the host
+npx adb-ready doctor
 
-- Interactive keyboard-driven home screen.
-- Read-only environment and ADB diagnostics with `doctor`.
-- Read-only Android target discovery with `devices`.
-- Deterministic target selection through `--select`.
-- Human, plain, JSON, and NDJSON output.
-- Explicit ADB executable, server host, server port, timeout, and presentation
-  controls.
-- Portable execution through Node, Bun, and Deno.
+# See connected and wireless targets
+npx adb-ready devices
 
-Run `npx adb-ready@alpha --help` for the complete command reference.
+# Start the complete development session
+npx adb-ready dev
+```
 
-## Runtime and package-manager entrypoints
+Add it to a project when the team should share one version:
 
-The same npm package can be launched through the common JavaScript package
-managers:
+```bash
+npm install --save-dev adb-ready
+npx adb-ready init
+npx adb-ready dev
+```
+
+Running `adb-ready` without a command opens the interactive workflow home.
+`adbr` is the shorter alias for the same CLI.
+
+[Read the five-minute setup →](./docs/getting-started.md)
+
+## 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) |
+
+## What happens in `adb-ready dev`?
+
+```text
+find or recover one target
+        ↓
+verify only the ports your project needs
+        ↓
+start the project on that same target
+        ↓
+watch target · ports · logs · child process
+        ↓
+recover safely or explain exactly what needs you
+```
+
+- Expo and React Native receive reverse port `8081` by default.
+- Add any local service with repeated `--port` flags.
+- Pass any command after `--`; it runs directly without an implicit shell.
+- Existing matching mappings are reused. Conflicts are never overwritten.
+- On exit, only resources created by that session are cleaned up.
+- The final exit code and a bounded, redacted session record are preserved.
 
 ```bash
-npx adb-ready@alpha doctor
-pnpm dlx adb-ready@alpha doctor
-yarn dlx adb-ready@alpha doctor
-bunx adb-ready@alpha doctor
+adb-ready dev --port 8081 --port 8000
+adb-ready dev -- pnpm run android:local
+adb-ready dev --dry-run --json
 ```
 
-Explicit alternative runtimes are also supported:
+## Built for humans and automation
+
+The interactive CLI provides keyboard navigation, live state, reduced-motion
+support, narrow-terminal fallbacks, and clear recovery feedback. Scripts get a
+separate deterministic contract:
 
 ```bash
-bunx --bun adb-ready@alpha doctor
-deno run -A npm:adb-ready@alpha doctor
+adb-ready devices --json --non-interactive
+adb-ready logs --package com.example.app --format ndjson
+adb-ready context --since 5m --only problems,recovery,logs
 ```
 
-## Alpha scope
+- machine data on `stdout`, human diagnostics on `stderr`;
+- versioned JSON results and NDJSON events;
+- no prompt, animation, or terminal takeover in redirected/CI execution;
+- stable problem categories, meaningful exit codes, timeouts, and dry runs; and
+- explicit target, ADB path, and remote ADB server overrides.
+
+## 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? |
+
+Run `adb-ready --help` for the full command list or
+`adb-ready help COMMAND` for focused options.
+
+## Compatibility
+
+ADB Ready targets macOS, Linux, and Windows, with Node.js, Bun, and Deno runtime
+smoke coverage. The package is architecture-neutral JavaScript with no native
+addon or artificial OS/CPU block. A working ADB executable remains the only
+Android transport backend.
+
+[See tested and upstream-capable support tiers →](./COMPATIBILITY.md)
+
+## Trust by default
+
+- The shared ADB server is never restarted implicitly.
+- Destructive or global actions are never hidden inside recovery.
+- Pairing codes never enter command-line arguments.
+- 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.
+
+## Project
 
-Wireless pairing and recovery, reverse and forward ports, Expo and React Native
-presets, and the flagship `adb-ready dev` session are not included yet. The
-current commands are intentionally read-only and never restart the ADB server
-or mutate a connected device.
+[Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) ·
+[Security](./SECURITY.md) · [MIT License](./LICENSE)
 
-This preview is published to validate the CLI foundation and reserve the
-canonical package name during active development. The source repository remains
-private during the early implementation phase, and this alpha is currently
-distributed as `UNLICENSED` software.
+ADB Ready is Android-only. The `0.1.0` release focuses 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.