adb-ready 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -9,6 +9,14 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-29
+
+### Added
+
+- Add deterministic, offline shell completion generation for Bash, zsh, fish,
+  PowerShell, and Nushell, covering both `adb-ready` and `adbr` without loading
+  project configuration or contacting ADB.
+
 ## [0.7.0] - 2026-09-27
 
 ### Added
@@ -499,7 +507,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.7.0...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/Adam014/adb-ready/compare/v0.7.0...v0.8.0
 [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

package/README.md

@@ -284,6 +284,7 @@ Android transport backend.
 | Guide | Start here when you want to… |
 | --- | --- |
 | [Getting started](./docs/getting-started.md) | Reach the first ready development session. |
+| [Shell completion](./docs/completions.md) | Enable command discovery in Bash, zsh, fish, PowerShell, or Nushell. |
 | [Development sessions](./docs/dev-sessions.md) | Configure frameworks, commands, ports, readiness, and cleanup. |
 | [Targets and Wireless debugging](./docs/targets-and-wireless.md) | Pair, connect, recover, or explicitly select a target. |
 | [Apps and evidence](./docs/apps-and-evidence.md) | Control the app and capture screenshots or recordings. |

package/dist/cli.js

@@ -3304,7 +3304,7 @@ import process15 from "node:process";
 // package.json
 var package_default = {
   name: "adb-ready",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   private: false,
   type: "module",
@@ -3403,7 +3403,7 @@ var package_default = {
     "@yarnpkg/cli-dist": "4.18.0",
     npm: "12.0.2",
     publint: "0.3.24",
-    runpalette: "0.3.0",
+    runpalette: "0.5.0",
     tinyexec: "1.3.1",
     typescript: "7.0.2",
     yarn: "1.22.22"
@@ -57732,12 +57732,259 @@ function resolveTerminalCapabilities(preferences) {
   };
 }
 
+// src/cli/completion.ts
+var COMPLETION_SHELLS = ["bash", "zsh", "fish", "powershell", "nushell"];
+var COMMANDS = [
+  { name: "agent", description: "Configure a project-local AI agent bridge", values: ["setup"] },
+  {
+    name: "app",
+    description: "Resolve, inspect, install, or control one app",
+    values: ["resolve", "info", "install", "launch", "stop", "restart", "clear-data", "uninstall"]
+  },
+  { name: "apps", description: "List packages on one Android target", values: ["list"] },
+  {
+    name: "capture",
+    description: "Capture verified device evidence",
+    values: ["screenshot", "screen-record"]
+  },
+  { name: "completion", description: "Generate shell completion", values: COMPLETION_SHELLS },
+  {
+    name: "config",
+    description: "Validate or explain configuration",
+    values: ["validate", "explain"]
+  },
+  { name: "connect", description: "Connect a wireless Android target" },
+  { name: "context", description: "Export bounded AI-ready context" },
+  { name: "dev", description: "Start a target-bound development session" },
+  { name: "devices", description: "List visible Android targets" },
+  { name: "doctor", description: "Inspect the local ADB environment" },
+  { name: "help", description: "Show command help" },
+  { name: "init", description: "Create detected project configuration" },
+  {
+    name: "inspect",
+    description: "Build bounded device evidence",
+    values: ["app", "failures", "ui"]
+  },
+  { name: "logs", description: "Stream focused target logs" },
+  { name: "mcp", description: "Serve typed tools over local stdio" },
+  { name: "open", description: "Open a deep link or web URL" },
+  { name: "pair", description: "Pair through Wireless debugging" },
+  { name: "ports", description: "Manage verified TCP mappings", values: ["forward", "reverse"] },
+  { name: "problems", description: "Show saved session problems" },
+  { name: "run", description: "Run one bounded verification job" },
+  { name: "sessions", description: "Inspect saved sessions", values: ["list", "show", "events"] },
+  { name: "test", description: "Run managed Android tests", values: ["gradle", "firebase"] },
+  {
+    name: "ui",
+    description: "Perform a bounded verified UI action",
+    values: [
+      "audit",
+      "find",
+      "get",
+      "assert",
+      "compare",
+      "tap",
+      "long-press",
+      "scroll",
+      "swipe",
+      "fill",
+      "clear",
+      "type",
+      "press",
+      "keyboard",
+      "permission",
+      "wait"
+    ]
+  },
+  { name: "version", description: "Show version" }
+];
+var GLOBAL_OPTIONS = [
+  "--help",
+  "-h",
+  "--version",
+  "-V",
+  "--format",
+  "--json",
+  "--quiet",
+  "--verbose",
+  "--color",
+  "--no-color",
+  "--unicode",
+  "--no-unicode",
+  "--animation",
+  "--no-animation",
+  "--non-interactive",
+  "--timeout",
+  "--adb",
+  "--adb-host",
+  "--adb-port",
+  "--config",
+  "--profile",
+  "--select",
+  "--device",
+  "--serial",
+  "-s",
+  "--transport-id",
+  "--last",
+  "--dry-run"
+];
+var commandNames = () => COMMANDS.map(({ name }) => name).join(" ");
+var optionNames = () => GLOBAL_OPTIONS.join(" ");
+function bash() {
+  const cases = COMMANDS.filter(({ values: values2 }) => values2 !== undefined).map(({ name, values: values2 }) => `      ${name}) candidates="${values2?.join(" ")}" ;;`).join(`
+`);
+  return `# Generated by adb-ready. Source this file from ~/.bashrc.
+_adb_ready_complete() {
+  local current command candidates
+  COMPREPLY=()
+  current="\${COMP_WORDS[COMP_CWORD]}"
+  command="\${COMP_WORDS[1]}"
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    candidates="${commandNames()} ${optionNames()}"
+  elif [[ \${COMP_CWORD} -eq 2 ]]; then
+    case "\${command}" in
+${cases}
+      help) candidates="${commandNames()}" ;;
+      *) candidates="${optionNames()}" ;;
+    esac
+  else
+    candidates="${optionNames()}"
+  fi
+  COMPREPLY=( $(compgen -W "\${candidates}" -- "\${current}") )
+}
+complete -F _adb_ready_complete adb-ready adbr
+`;
+}
+function zsh() {
+  const commands = COMMANDS.map(({ name, description }) => `    '${name}:${description.replaceAll("'", "'\\''")}'`).join(`
+`);
+  const cases = COMMANDS.filter(({ values: values2 }) => values2 !== undefined).map(({ name, values: values2 }) => `      ${name}) _values 'action' ${values2?.join(" ")} ;;`).join(`
+`);
+  return `#compdef adb-ready adbr
+# Generated by adb-ready. Add its directory to fpath, then run compinit.
+_adb_ready() {
+  local -a commands
+  commands=(
+${commands}
+  )
+  _arguments -C \\
+    '(-h --help)'{-h,--help}'[show help]' \\
+    '(-V --version)'{-V,--version}'[show version]' \\
+    '--format[select output format]:format:(human plain json ndjson)' \\
+    '--json[emit JSON]' \\
+    '--non-interactive[never prompt]' \\
+    '1:command:->command' \\
+    '*::argument:->argument'
+  case $state in
+    command) _describe 'command' commands ;;
+    argument)
+      case $words[2] in
+${cases}
+        help) _describe 'command' commands ;;
+      esac
+      ;;
+  esac
+}
+_adb_ready "$@"
+`;
+}
+function fish() {
+  const lines = [
+    "# Generated by adb-ready. Save as ~/.config/fish/completions/adb-ready.fish."
+  ];
+  for (const binary of ["adb-ready", "adbr"]) {
+    for (const { name, description } of COMMANDS) {
+      const safeDescription = description.replaceAll("'", "\\'");
+      lines.push(`complete -c ${binary} -f -n '__fish_use_subcommand' -a '${name}' -d '${safeDescription}'`);
+    }
+    for (const { name, values: values2 } of COMMANDS) {
+      if (values2 === undefined)
+        continue;
+      lines.push(`complete -c ${binary} -f -n '__fish_seen_subcommand_from ${name}' -a '${values2.join(" ")}'`);
+    }
+    lines.push(`complete -c ${binary} -s h -l help -d 'Show help'`, `complete -c ${binary} -s V -l version -d 'Show version'`, `complete -c ${binary} -l json -d 'Emit JSON'`, `complete -c ${binary} -l non-interactive -d 'Never prompt'`, `complete -c ${binary} -l dry-run -d 'Plan without mutation'`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function powershell() {
+  const map = COMMANDS.filter(({ values: values2 }) => values2 !== undefined).map(({ name, values: values2 }) => `  '${name}' = @('${values2?.join("','")}')`).join(`
+`);
+  return `# Generated by adb-ready. Add this script to your PowerShell profile.
+$AdbReadyCommands = @('${commandNames().replaceAll(" ", "','")}')
+$AdbReadyOptions = @('${optionNames().replaceAll(" ", "','")}')
+$AdbReadyActions = @{
+${map}
+}
+Register-ArgumentCompleter -Native -CommandName adb-ready,adbr -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $words = $commandAst.CommandElements | ForEach-Object { $_.Extent.Text }
+  $candidates = if ($words.Count -le 1) {
+    $AdbReadyCommands + $AdbReadyOptions
+  } elseif ($words.Count -eq 2 -and $AdbReadyActions.ContainsKey($words[1])) {
+    $AdbReadyActions[$words[1]] + $AdbReadyOptions
+  } elseif ($words[1] -eq 'help') {
+    $AdbReadyCommands
+  } else {
+    $AdbReadyOptions
+  }
+  $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}
+`;
+}
+function nushellExtern(binary) {
+  return `export extern "${binary}" [
+  command?: string@"nu-complete adb-ready commands"
+  ...args: string
+  --help(-h)
+  --version(-V)
+  --json
+  --quiet
+  --verbose
+  --non-interactive
+  --dry-run
+]`;
+}
+function nushell() {
+  const records = COMMANDS.map(({ name, description }) => `  { value: "${name}", description: "${description}" }`).join(`
+`);
+  return `# Generated by adb-ready. Source this file from config.nu.
+def "nu-complete adb-ready commands" [] {
+[
+${records}
+]
+}
+
+${nushellExtern("adb-ready")}
+
+${nushellExtern("adbr")}
+`;
+}
+function generateCompletion(shell) {
+  switch (shell) {
+    case "bash":
+      return bash();
+    case "zsh":
+      return zsh();
+    case "fish":
+      return fish();
+    case "powershell":
+      return powershell();
+    case "nushell":
+      return nushell();
+  }
+}
+
 // src/cli/arguments.ts
-var COMMANDS = new Set([
+var COMMANDS2 = new Set([
   "agent",
   "app",
   "apps",
   "capture",
+  "completion",
   "config",
   "connect",
   "context",
@@ -57887,6 +58134,7 @@ function splitLongOption(argument) {
 function parseArguments(argv) {
   let command;
   let helpTarget;
+  let completionShell;
   let format = "human";
   let quiet = false;
   let verbose = false;
@@ -58024,17 +58272,17 @@ function parseArguments(argv) {
     }
     if (!argument.startsWith("-")) {
       if (command === undefined) {
-        if (!COMMANDS.has(argument)) {
-          const hint = suggestion(argument, COMMANDS);
+        if (!COMMANDS2.has(argument)) {
+          const hint = suggestion(argument, COMMANDS2);
           return failure4("CLI_USAGE", `Unknown command: ${argument}${hint === "" ? "" : `. ${hint}`}`);
         }
         const candidate = argument;
         command = candidate;
         continue;
       }
-      if (command === "help" && COMMANDS.has(argument)) {
+      if (command === "help" && COMMANDS2.has(argument)) {
         const candidate = argument;
-        if (candidate === "agent" || candidate === "app" || candidate === "apps" || candidate === "capture" || candidate === "connect" || candidate === "config" || candidate === "context" || candidate === "dev" || candidate === "devices" || candidate === "doctor" || candidate === "logs" || candidate === "mcp" || candidate === "open" || candidate === "init" || candidate === "inspect" || candidate === "pair" || candidate === "ports" || candidate === "problems" || candidate === "run" || candidate === "sessions" || candidate === "test" || candidate === "ui" || candidate === "version") {
+        if (candidate === "agent" || candidate === "app" || candidate === "apps" || candidate === "capture" || candidate === "completion" || candidate === "connect" || candidate === "config" || candidate === "context" || candidate === "dev" || candidate === "devices" || candidate === "doctor" || candidate === "logs" || candidate === "mcp" || candidate === "open" || candidate === "init" || candidate === "inspect" || candidate === "pair" || candidate === "ports" || candidate === "problems" || candidate === "run" || candidate === "sessions" || candidate === "test" || candidate === "ui" || candidate === "version") {
           helpTarget = candidate;
           continue;
         }
@@ -58043,6 +58291,13 @@ function parseArguments(argv) {
         endpoint = argument;
         continue;
       }
+      if (command === "completion" && completionShell === undefined) {
+        if (!COMPLETION_SHELLS.includes(argument)) {
+          return failure4("CLI_INVALID_VALUE", `Invalid completion shell: ${argument}. Expected bash, zsh, fish, powershell, or nushell.`);
+        }
+        completionShell = argument;
+        continue;
+      }
       if (command === "agent" && argument === "setup" && !agentSetupSeen) {
         agentSetupSeen = true;
         continue;
@@ -58927,6 +59182,12 @@ function parseArguments(argv) {
   if (command === "capture" && captureKind === undefined) {
     return failure4("CLI_USAGE", "capture requires screenshot or screen-record.");
   }
+  if (command === "completion" && completionShell === undefined) {
+    return failure4("CLI_USAGE", "completion requires bash, zsh, fish, powershell, or nushell.");
+  }
+  if (command === "completion" && argv.some((argument) => argument !== "completion" && argument !== completionShell)) {
+    return failure4("CLI_USAGE", "completion accepts only one shell name; redirect its exact script output to a file.");
+  }
   if (command === "inspect" && inspectKind === undefined) {
     return failure4("CLI_USAGE", "inspect requires app, failures, or ui.");
   }
@@ -59232,6 +59493,7 @@ function parseArguments(argv) {
     options: {
       command,
       ...helpTarget === undefined ? {} : { helpTarget },
+      ...completionShell === undefined ? {} : { completionShell },
       format,
       quiet,
       verbose,
@@ -59360,6 +59622,7 @@ Commands:
   app ACTION [APP_ID]   Resolve, inspect, install, or control one app
   apps list             List packages on one Android target
   capture ACTION         Save a verified screenshot or bounded screen recording
+  completion SHELL       Generate completion for bash, zsh, fish, PowerShell, or Nushell
   config ACTION          Validate or explain resolved configuration
   connect [HOST:PORT]    Connect and verify a wireless Android target
   context [SESSION]      Export bounded AI-ready diagnostic context
@@ -59466,6 +59729,12 @@ Writes verified binary evidence inside the current project. Existing files are
 never replaced unless --force is explicit. Recordings are bounded to 180s.
 Screenshot crops use source pixels. Dimension limits preserve aspect ratio and
 never upscale the image. The CLI keeps full resolution unless limits are set.
+`,
+  completion: `Usage: adb-ready completion bash|zsh|fish|powershell|nushell
+
+Prints a static completion script for both adb-ready and adbr. Generation is
+offline, deterministic, and never loads project configuration or contacts ADB.
+See docs/completions.md for one-time installation instructions.
 `,
   config: `Usage:
   adb-ready config validate [options]
@@ -60225,6 +60494,10 @@ async function runCliInternal(argv, io, dependencies = {}, signal) {
     });
     return 0 /* Success */;
   }
+  if (options.command === "completion") {
+    io.output.write(generateCompletion(options.completionShell ?? "bash"));
+    return 0 /* Success */;
+  }
   if (options.command === "mcp") {
     const explicitRoot = io.env.ADB_READY_MCP_PROJECT_ROOT?.trim();
     await runMcpStdio({
@@ -61355,4 +61628,4 @@ try {
   process16.removeListener("SIGTERM", abort);
 }
 
-//# debugId=8986C9014073E12364756E2164756E21
+//# debugId=2AD0AEC355B9989464756E2164756E21

package/docs/completions.md

@@ -0,0 +1,61 @@
+# Shell completion
+
+ADB Ready generates static tab-completion scripts for both `adb-ready` and its
+short alias, `adbr`. Generation is instant and offline: it does not load project
+configuration, start ADB, or inspect a device.
+
+## Bash
+
+```bash
+mkdir -p ~/.local/share/bash-completion/completions
+adb-ready completion bash > ~/.local/share/bash-completion/completions/adb-ready
+```
+
+Start a new shell. If the user completion directory is not loaded by your Bash
+installation, source the generated file from `~/.bashrc`.
+
+## zsh
+
+```zsh
+mkdir -p ~/.zfunc
+adb-ready completion zsh > ~/.zfunc/_adb-ready
+```
+
+Add the directory before `compinit` in `~/.zshrc`:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit && compinit
+```
+
+## fish
+
+```fish
+mkdir -p ~/.config/fish/completions
+adb-ready completion fish > ~/.config/fish/completions/adb-ready.fish
+```
+
+fish loads the file automatically in new shell sessions.
+
+## PowerShell
+
+```powershell
+New-Item -ItemType Directory -Force (Split-Path $PROFILE) | Out-Null
+adb-ready completion powershell | Out-File -Append -Encoding utf8 $PROFILE
+```
+
+Reload the profile with `. $PROFILE` or open a new PowerShell session.
+
+## Nushell
+
+```nu
+mkdir ($nu.data-dir | path join "vendor" "autoload")
+adb-ready completion nushell | save --force ($nu.data-dir | path join "vendor" "autoload" "adb-ready.nu")
+```
+
+Nushell loads vendor autoload files in new sessions. The generated declarations
+complete public commands while preserving ordinary file completion for command
+arguments.
+
+Regenerate the script after upgrading ADB Ready so newly added commands become
+available to the shell.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",
@@ -99,7 +99,7 @@
     "@yarnpkg/cli-dist": "4.18.0",
     "npm": "12.0.2",
     "publint": "0.3.24",
-    "runpalette": "0.3.0",
+    "runpalette": "0.5.0",
     "tinyexec": "1.3.1",
     "typescript": "7.0.2",
     "yarn": "1.22.22"

package/schema/agent-tools-v1.json

@@ -1,7 +1,7 @@
 {
   "title": "ADB Ready agent tool contract",
   "schemaVersion": 1,
-  "packageVersion": "0.7.0",
+  "packageVersion": "0.8.0",
   "protocolVersion": "2025-11-25",
   "transport": "stdio",
   "tools": [

package/skills/adb-ready/SKILL.md

@@ -3,7 +3,7 @@ name: adb-ready
 description: Prepare, automate, debug, and verify one Android target through the ADB Ready MCP server. Use for Android development sessions, app lifecycle work, UI automation, failure evidence, screenshots, and agent-driven device checks.
 ---
 
-<!-- Generated by adb-ready 0.7.0; do not edit. -->
+<!-- Generated by adb-ready 0.8.0; do not edit. -->
 
 # ADB Ready
 
@@ -51,4 +51,4 @@ Use the typed `adb-ready` MCP tools. Do not replace them with generic shell or r
 - `session`: 12 tools
 - `ui`: 29 tools
 
-Contract: ADB Ready 0.7.0, agent schema v1.
+Contract: ADB Ready 0.8.0, agent schema v1.