adb-ready 0.6.0 → 0.8.0

package/examples/ci-emulator/dev-service.mjs

@@ -0,0 +1,14 @@
+let stopping = false;
+
+const keepAlive = setInterval(() => undefined, 60_000);
+
+function stop() {
+  if (stopping) return;
+  stopping = true;
+  process.stderr.write("CI development service stopped.\n");
+  clearInterval(keepAlive);
+}
+
+process.once("SIGINT", stop);
+process.once("SIGTERM", stop);
+process.stderr.write("CI development service ready.\n");

package/examples/ci-emulator/verify-emulator.mjs

@@ -0,0 +1,108 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} name
+ */
+function requiredEnvironment(env, name) {
+  const value = env[name];
+  if (typeof value !== "string" || value.trim() === "" || /[\r\n\0]/u.test(value)) {
+    throw new Error(`${name} must be a non-empty single-line value.`);
+  }
+  return value;
+}
+
+/**
+ * @param {string} executable
+ * @param {string} serial
+ * @param {string[]} args
+ */
+async function defaultAdb(executable, serial, args) {
+  const result = await execFile(executable, ["-s", serial, ...args], {
+    encoding: "buffer",
+    maxBuffer: 12 * 1024 * 1024,
+    timeout: 30_000,
+    windowsHide: true,
+  });
+  return Buffer.from(result.stdout);
+}
+
+/**
+ * @param {{
+ *   env?: NodeJS.ProcessEnv;
+ *   runAdb?: (args: string[]) => Promise<Buffer>;
+ * }} [options]
+ */
+export async function verifyEmulator(options = {}) {
+  const env = options.env ?? process.env;
+  const serial = requiredEnvironment(env, "ADB_READY_TARGET_SERIAL");
+  const androidSerial = requiredEnvironment(env, "ANDROID_SERIAL");
+  const outputDirectory = requiredEnvironment(env, "ADB_READY_VERIFIER_OUTPUT_DIR");
+  if (serial !== androidSerial) {
+    throw new Error("ADB Ready did not bind the verifier to one target.");
+  }
+
+  const executable = env.ADB_READY_ADB_PATH?.trim() || "adb";
+  /** @param {string[]} args */
+  const runDefaultAdb = (args) => defaultAdb(executable, serial, args);
+  const runAdb = options.runAdb ?? runDefaultAdb;
+  /** @param {string[]} args */
+  const text = async (args) => (await runAdb(args)).toString("utf8").trim();
+
+  if ((await text(["get-state"])) !== "device") {
+    throw new Error("The selected emulator is not in the device state.");
+  }
+  if ((await text(["shell", "getprop", "sys.boot_completed"])) !== "1") {
+    throw new Error("The selected emulator did not complete Android boot.");
+  }
+
+  const apiLevel = await text(["shell", "getprop", "ro.build.version.sdk"]);
+  const abi = await text(["shell", "getprop", "ro.product.cpu.abi"]);
+  if (!/^\d+$/u.test(apiLevel) || abi === "") {
+    throw new Error("The selected emulator did not expose a valid Android identity.");
+  }
+
+  await runAdb(["shell", "am", "start", "-W", "-a", "android.settings.SETTINGS"]);
+  const windowState = await runAdb(["shell", "dumpsys", "window", "displays"]);
+  const screenshot = await runAdb(["exec-out", "screencap", "-p"]);
+  if (
+    screenshot.length <= PNG_SIGNATURE.length ||
+    !screenshot.subarray(0, 8).equals(PNG_SIGNATURE)
+  ) {
+    throw new Error("The selected emulator did not return a valid PNG screenshot.");
+  }
+
+  const destination = path.resolve(outputDirectory);
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  await Promise.all([
+    writeFile(path.join(destination, "screen.png"), screenshot, { mode: 0o600 }),
+    writeFile(path.join(destination, "window.txt"), windowState, { mode: 0o600 }),
+    writeFile(
+      path.join(destination, "verification.json"),
+      `${JSON.stringify({ schemaVersion: 1, targetBound: true, state: "device", bootCompleted: true, apiLevel, abi, screenshot: "screen.png" }, null, 2)}\n`,
+      { mode: 0o600 },
+    ),
+  ]);
+
+  return { apiLevel, abi, screenshotBytes: screenshot.length };
+}
+
+const direct = process.argv[1] === fileURLToPath(import.meta.url);
+if (direct) {
+  try {
+    const result = await verifyEmulator();
+    process.stdout.write(
+      `Verified the selected Android emulator (API ${result.apiLevel}, ${result.abi}) with a ${String(result.screenshotBytes)} byte screenshot.\n`,
+    );
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/examples/ci-physical/README.md

@@ -0,0 +1,51 @@
+# Self-hosted physical Android target
+
+This recipe runs one finite ADB Ready verification against one physical Android
+target attached to a self-hosted GitHub Actions runner. It is intentionally a
+manual workflow: never let untrusted pull-request code execute on a machine
+that can control a real device.
+
+## Runner contract
+
+1. Register a dedicated self-hosted runner and add the custom
+   `android-device` label.
+2. Install a current Android SDK Platform-Tools release and make `adb`
+   available to the runner account.
+3. Enable USB debugging, connect the target, unlock it, and approve that
+   runner's RSA key before unattended work begins.
+4. Set the repository variable `ADB_READY_DEVICE_SERIAL` to the exact serial
+   shown by `adb devices -l`.
+5. Copy [`github-actions.yml`](./github-actions.yml) into your repository's
+   `.github/workflows/` directory and adapt the project command, readiness, and
+   verifier to your application.
+
+The example uses a static GitHub concurrency group with cancellation disabled,
+so jobs queue instead of interrupting a device already in use. ADB Ready then
+acquires its host-local target lease before any mutation. Another ADB Ready
+process on the same runner receives `TARGET_BUSY`; it cannot share the phone.
+The operator-provided runner label and serial are the physical-device contract;
+the verifier does not guess form factor from undocumented Android properties.
+
+## Failure and recovery
+
+- A missing serial or detached phone fails before a verifier starts.
+- `unauthorized` asks the operator to unlock the device and approve the RSA
+  prompt; ADB Ready does not bypass Android authorization.
+- `offline` remains distinct from an absent device and is reported with an
+  actionable target diagnostic.
+- A normal exit, verifier failure, timeout, or cancellation releases only the
+  current ADB Ready lease and resources created by that run.
+- If the runner process disappears, a later process on the same host can
+  recover its dead-owner lease. After a host crash, the bounded lease TTL makes
+  stale ownership recoverable.
+
+The recipe never calls `adb kill-server`, reconnects unrelated transports,
+unlocks the phone, clears app data, or resets the device. Its verifier is
+read-only and deliberately avoids screenshots because a personal device screen
+can contain sensitive information. Project-specific test artifacts remain
+local sensitive evidence and are uploaded for seven days by the example.
+
+GitHub concurrency protects this one workflow. The ADB Ready lease protects
+processes sharing one host. Neither is a distributed lock across multiple
+runner machines; use one physical target per runner label until an explicit
+shared coordination backend is configured.

package/examples/ci-physical/adb-ready.config.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "custom",
+    "command": {
+      "executable": "node",
+      "args": ["examples/ci-physical/dev-service.mjs"]
+    },
+    "reversePorts": [],
+    "logs": false,
+    "cleanupPorts": true,
+    "watch": true,
+    "ready": {
+      "timeoutMs": 60000,
+      "pollIntervalMs": 1000,
+      "all": [{ "kind": "boot" }]
+    }
+  }
+}

package/examples/ci-physical/dev-service.mjs

@@ -0,0 +1,14 @@
+let stopping = false;
+
+const keepAlive = setInterval(() => undefined, 60_000);
+
+function stop() {
+  if (stopping) return;
+  stopping = true;
+  process.stderr.write("Physical-device CI service stopped.\n");
+  clearInterval(keepAlive);
+}
+
+process.once("SIGINT", stop);
+process.once("SIGTERM", stop);
+process.stderr.write("Physical-device CI service ready.\n");

package/examples/ci-physical/github-actions.yml

@@ -0,0 +1,56 @@
+name: Physical Android acceptance
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Queue jobs at GitHub's runner boundary. ADB Ready's host-local lease remains
+# the final authority when another local process uses the same target.
+concurrency:
+  group: physical-android-device
+  cancel-in-progress: false
+
+jobs:
+  finite-run:
+    name: Target-bound physical run
+    runs-on: [self-hosted, android-device]
+    timeout-minutes: 20
+    env:
+      ADB_READY_DEVICE_SERIAL: ${{ vars.ADB_READY_DEVICE_SERIAL }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js 22
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          package-manager-cache: false
+
+      - name: Set up Bun from packageManager
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+
+      - name: Install and build ADB Ready
+        run: |
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Run one bounded physical-device verification
+        run: node examples/ci-physical/run-job.mjs
+
+      - name: Preserve normalized result and evidence
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: adb-ready-physical-evidence
+          path: |
+            .adb-ready/ci-result.ndjson
+            .adb-ready/artifacts/**
+          include-hidden-files: true
+          if-no-files-found: warn
+          retention-days: 7

package/examples/ci-physical/run-job.mjs

@@ -0,0 +1,77 @@
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const RESULT_PATH = path.join(".adb-ready", "ci-result.ndjson");
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function physicalRunArguments(env = process.env) {
+  const serial = env.ADB_READY_DEVICE_SERIAL;
+  if (typeof serial !== "string" || serial.trim() === "" || /[\r\n\0]/u.test(serial)) {
+    throw new Error(
+      "ADB_READY_DEVICE_SERIAL must name one pre-authorized Android target on this runner.",
+    );
+  }
+  return [
+    "dist/cli.js",
+    "run",
+    "--config",
+    "examples/ci-physical/adb-ready.config.json",
+    "--device",
+    serial,
+    "--run-timeout",
+    "10m",
+    "--format",
+    "ndjson",
+    "--non-interactive",
+    "--",
+    process.execPath,
+    "examples/ci-physical/verify-device.mjs",
+  ];
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+export async function runPhysicalJob(env = process.env) {
+  const args = physicalRunArguments(env);
+  mkdirSync(path.dirname(RESULT_PATH), { recursive: true, mode: 0o700 });
+  const output = openSync(RESULT_PATH, "w", 0o600);
+  const child = spawn(process.execPath, args, {
+    cwd: process.cwd(),
+    env,
+    stdio: ["ignore", output, "inherit"],
+    windowsHide: true,
+  });
+
+  /** @param {NodeJS.Signals} signal */
+  const forward = (signal) => {
+    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  };
+  const forwardInterrupt = () => forward("SIGINT");
+  const forwardTermination = () => forward("SIGTERM");
+  process.once("SIGINT", forwardInterrupt);
+  process.once("SIGTERM", forwardTermination);
+  try {
+    return await new Promise((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+    });
+  } finally {
+    process.removeListener("SIGINT", forwardInterrupt);
+    process.removeListener("SIGTERM", forwardTermination);
+    closeSync(output);
+  }
+}
+
+const direct = process.argv[1] === fileURLToPath(import.meta.url);
+if (direct) {
+  try {
+    const result = await runPhysicalJob();
+    process.exitCode = result.code ?? (result.signal === "SIGINT" ? 130 : 1);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 2;
+  }
+}

package/examples/ci-physical/verify-device.mjs

@@ -0,0 +1,90 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} name
+ */
+function requiredEnvironment(env, name) {
+  const value = env[name];
+  if (typeof value !== "string" || value.trim() === "" || /[\r\n\0]/u.test(value)) {
+    throw new Error(`${name} must be a non-empty single-line value.`);
+  }
+  return value;
+}
+
+/**
+ * @param {string} executable
+ * @param {string} serial
+ * @param {string[]} args
+ */
+async function defaultAdb(executable, serial, args) {
+  const result = await execFile(executable, ["-s", serial, ...args], {
+    encoding: "buffer",
+    maxBuffer: 1024 * 1024,
+    timeout: 30_000,
+    windowsHide: true,
+  });
+  return Buffer.from(result.stdout);
+}
+
+/**
+ * @param {{
+ *   env?: NodeJS.ProcessEnv;
+ *   runAdb?: (args: string[]) => Promise<Buffer>;
+ * }} [options]
+ */
+export async function verifyPhysicalDevice(options = {}) {
+  const env = options.env ?? process.env;
+  const serial = requiredEnvironment(env, "ADB_READY_TARGET_SERIAL");
+  const androidSerial = requiredEnvironment(env, "ANDROID_SERIAL");
+  const outputDirectory = requiredEnvironment(env, "ADB_READY_VERIFIER_OUTPUT_DIR");
+  if (serial !== androidSerial) {
+    throw new Error("ADB Ready did not bind the verifier to one target.");
+  }
+
+  const executable = env.ADB_READY_ADB_PATH?.trim() || "adb";
+  /** @param {string[]} args */
+  const runDefaultAdb = (args) => defaultAdb(executable, serial, args);
+  const runAdb = options.runAdb ?? runDefaultAdb;
+  /** @param {string[]} args */
+  const text = async (args) => (await runAdb(args)).toString("utf8").trim();
+
+  if ((await text(["get-state"])) !== "device") {
+    throw new Error("The selected physical target is not in the device state.");
+  }
+  if ((await text(["shell", "getprop", "sys.boot_completed"])) !== "1") {
+    throw new Error("The selected physical target did not complete Android boot.");
+  }
+  const apiLevel = await text(["shell", "getprop", "ro.build.version.sdk"]);
+  if (!/^\d+$/u.test(apiLevel)) {
+    throw new Error("The selected physical target did not expose a valid Android API level.");
+  }
+
+  const destination = path.resolve(outputDirectory);
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  await writeFile(
+    path.join(destination, "verification.json"),
+    `${JSON.stringify({ schemaVersion: 1, targetBound: true, state: "device", bootCompleted: true, apiLevel }, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+  return { apiLevel };
+}
+
+const direct = process.argv[1] === fileURLToPath(import.meta.url);
+if (direct) {
+  try {
+    const result = await verifyPhysicalDevice();
+    process.stdout.write(
+      `Verified the selected physical Android target (API ${result.apiLevel}).\n`,
+    );
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/examples/target-pools/README.md

@@ -0,0 +1,22 @@
+# Explicit target-pool example
+
+Replace the serial and AVD name with resources owned by this host, then copy
+the configuration to the project root.
+
+Validate and preview before allocating either target:
+
+```bash
+adb-ready config validate
+adb-ready run --pool smoke --dry-run --json -- npm run test:e2e
+```
+
+Run the bounded verifier on both members:
+
+```bash
+adb-ready run --pool smoke -- npm run test:e2e
+```
+
+The AVD must already exist. The built-in lease backend coordinates only
+processes sharing this host and user state directory. See
+[Target pools and fan-out](../../docs/target-pools.md) before adapting this for
+multiple CI runners or a remote ADB server.

package/examples/target-pools/adb-ready.config.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "expo",
+    "reversePorts": [8081]
+  },
+  "targets": {
+    "pools": {
+      "smoke": {
+        "maxConcurrency": 2,
+        "failFast": false,
+        "leaseWaitMs": 30000,
+        "members": [
+          {
+            "id": "usb-phone",
+            "kind": "adb",
+            "serial": "REPLACE_WITH_EXACT_SERIAL"
+          },
+          {
+            "id": "api36-emulator",
+            "kind": "avd",
+            "name": "REPLACE_WITH_EXISTING_AVD"
+          }
+        ]
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.6.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.6.0",
+  "packageVersion": "0.8.0",
   "protocolVersion": "2025-11-25",
   "transport": "stdio",
   "tools": [

package/schema/config-v1.schema.json

@@ -107,6 +107,9 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "pools": {
+          "$ref": "#/$defs/targetPools"
         }
       }
     },
@@ -147,9 +150,92 @@
             "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$"
           },
           "additionalProperties": { "type": "string", "minLength": 1 }
+        },
+        "pools": {
+          "$ref": "#/$defs/targetPools"
+        }
+      }
+    },
+    "targetPools": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["members", "maxConcurrency"],
+        "properties": {
+          "members": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 64,
+            "items": { "$ref": "#/$defs/targetPoolMember" }
+          },
+          "maxConcurrency": { "type": "integer", "minimum": 1, "maximum": 32 },
+          "failFast": { "type": "boolean", "default": false },
+          "leaseWaitMs": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 3600000,
+            "default": 30000
+          }
         }
       }
     },
+    "targetPoolMember": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "serial"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$" },
+            "kind": { "const": "adb" },
+            "serial": { "type": "string", "minLength": 1 },
+            "required": { "type": "boolean", "default": true }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "name"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$" },
+            "kind": { "const": "avd" },
+            "name": { "type": "string", "minLength": 1 },
+            "required": { "type": "boolean", "default": true }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "host", "serial"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$" },
+            "kind": { "const": "remote-adb" },
+            "host": { "type": "string", "minLength": 1 },
+            "port": { "type": "integer", "minimum": 1, "maximum": 65535, "default": 5037 },
+            "serial": { "type": "string", "minLength": 1 },
+            "required": { "type": "boolean", "default": true }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "kind", "model", "version"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$" },
+            "kind": { "const": "firebase" },
+            "model": { "type": "string", "minLength": 1 },
+            "version": { "type": "string", "minLength": 1 },
+            "locale": { "type": "string", "minLength": 1, "default": "en" },
+            "orientation": { "enum": ["landscape", "portrait"], "default": "portrait" },
+            "required": { "type": "boolean", "default": true }
+          }
+        }
+      ]
+    },
     "app": {
       "type": "object",
       "additionalProperties": false,

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.6.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.6.0, agent schema v1.
+Contract: ADB Ready 0.8.0, agent schema v1.