@botiverse/testbed-cli 0.2.0 → 0.4.0

package/lib/main.mjs

@@ -1,7 +1,9 @@
 // testbed command set. Output is human tables by default; `--json` prints the
 // raw API response (what an agent wants). Secrets: `acquire` returns a one-time ADB
 // private key; it is printed only in --json output or written to --key-out (0600).
-import { openSync, writeSync, closeSync } from "node:fs";
+import { openSync, writeSync, closeSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import { resolveAuth } from "./auth.mjs";
 import { makeClient, ApiError } from "./client.mjs";
 import { runAgentLogin } from "./agent-login.mjs";
@@ -30,8 +32,14 @@ export const USAGE = `testbed — cloud phones + the acceptance testbed in the R
   testbed verify login <session-id> --account <account-id>
   testbed verify reinstall <session-id> --apk-key fast/<id> --apk-sha256 HEX
 
+  testbed skill                          print the agent skill (SKILL.md)
+  testbed skill --install [-a AGENT...] [--global]
+                                         install for any runtime via "npx skills add" (Claude Code, Codex, Cursor, Gemini, OpenCode, ...)
+  testbed skill --copy-to DIR            plain copy of SKILL.md (offline / unsupported runtime)
+
   testbed cases                          acceptance case library
   testbed run <case-id...> [--app --ref --apk --apk-run --release --by]
+  testbed run --all [...]                the whole case table in one run (release smoke)
   testbed runs
   testbed show <run-id>
 
@@ -254,6 +262,36 @@ export async function main(argv, opts) {
             throw new Error("usage: testbed verify <start|show|renew|end|accounts|login|reinstall> …");
         }
       }
+      case "skill": {
+        const install = takeSwitch(args, "install");
+        const global = takeSwitch(args, "global") || takeSwitch(args, "g");
+        const copyTo = takeFlag(args, "copy-to");
+        const agents = [];
+        for (let i = 0; i < args.length;) {
+          if ((args[i] === "-a" || args[i] === "--agent") && args[i + 1]) { agents.push(args[i + 1]); args.splice(i, 2); } else i += 1;
+        }
+        const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+        const src = join(pkgDir, "skills", "testbed", "SKILL.md");
+        const text = readFileSync(src, "utf8");
+        if (copyTo) {
+          mkdirSync(copyTo, { recursive: true });
+          writeFileSync(join(copyTo, "SKILL.md"), text);
+          out(`copied skill 'testbed' -> ${join(copyTo, "SKILL.md")}`);
+          return exit(0);
+        }
+        if (!install) { out(text); return exit(0); }
+        // The open Agent Skills installer (npm `skills`, vercel-labs/skills) knows
+        // every runtime's skills directory (77 agents on 2026-09-04) and keeps one
+        // canonical copy under .agents/skills with per-agent links. We hand it our
+        // package directory; it discovers skills/testbed/SKILL.md itself.
+        const argv = ["-y", "skills", "add", pkgDir, "--skill", "testbed", "-y", ...(global ? ["-g"] : []), ...agents.flatMap((a) => ["-a", a])];
+        const spawn = opts.spawnImpl ?? (await import("node:child_process")).spawnSync;
+        const r = spawn("npx", argv, { stdio: "inherit", env: { ...process.env, ...env } });
+        if (r.error) { err(`testbed: could not run npx skills (${r.error.message}); fall back to: testbed skill --copy-to <dir>`); return exit(1); }
+        if (r.status !== 0) { err(`testbed: npx skills add exited ${r.status}; fall back to: testbed skill --copy-to <dir>`); return exit(r.status ?? 1); }
+        out(`installed skill 'testbed' via npx skills${agents.length ? ` for ${agents.join(", ")}` : ""}${global ? " (global)" : ""}`);
+        return exit(0);
+      }
       case "cases": {
         const d = await api("GET", "/cases");
         emit(d, () => table(d.cases.map((c) => ({ id: c.id, tier: c.tier, rev: c.revision, title: c.title })), ["id", "tier", "rev", "title"], out));
@@ -266,8 +304,15 @@ export async function main(argv, opts) {
         const apkRun = takeFlag(args, "apk-run");
         const release = takeFlag(args, "release");
         const by = takeFlag(args, "by", env.USER || "testbed-cli");
-        const caseIds = args.filter((a) => !a.startsWith("--"));
-        if (!caseIds.length) throw new Error("usage: testbed run <case-id...> [--app slug] [--ref branch] [--apk url] [--apk-run ci-run-id] [--release id]");
+        const all = takeSwitch(args, "all");
+        let caseIds = args.filter((a) => !a.startsWith("--"));
+        if (all) {
+          if (caseIds.length) throw new Error("usage: --all takes no case ids");
+          const cat = await api("GET", "/cases");
+          caseIds = cat.cases.map((c) => c.id);
+          if (!caseIds.length) throw new Error("the case table is empty");
+        }
+        if (!caseIds.length) throw new Error("usage: testbed run <case-id...> | --all  [--app slug] [--ref branch] [--apk url] [--apk-run ci-run-id] [--release id] [--by name]");
         const d = await api("POST", "/runs", { app_slug: app, case_ids: caseIds, apk_ref: apk, ref, apk_run_id: apkRun, hands_release_id: release, requested_by: by });
         emit(d, () => { out(`run ${d.run_id} — ${d.cases} case(s), ${d.dispatched} dispatched`); out(`${auth.apiBase}/runs/${d.run_id}`); });
         return exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/testbed-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "CLI for testbed \u2014 cloud phones and the acceptance testbed in the Raft release loop",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,8 @@
   },
   "files": [
     "bin",
-    "lib"
+    "lib",
+    "skills"
   ],
   "engines": {
     "node": ">=20"

package/skills/testbed/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: testbed
+description: "Use the testbed CLI to lease cloud Android phones, open human verification sessions, and run the acceptance case table for Raft app releases. Use when asked to smoke-test an APK, verify a build on a real device, hand a phone to a human verifier, or run release acceptance. Login is `testbed login` (managed Raft agents: PKCE through raft, no browser)."
+---
+
+# testbed — cloud phones and release acceptance
+
+The testbed is the acceptance gate for Raft app releases: a warm pool of cloud Android
+phones, human verification sessions on those phones, and an acceptance case table that
+runs against an APK. Everything is driven by the `testbed` CLI; the Raft manifest only
+publishes `agent-login`.
+
+## Setup (once per seat)
+
+```sh
+npm i -g @botiverse/testbed-cli        # or: npx @botiverse/testbed-cli …
+# non-root: npm config set prefix ~/.npm-global && export PATH="$HOME/.npm-global/bin:$PATH"
+testbed login                          # managed Raft agent: no browser; human/CI: set TESTBED_TOKEN
+testbed whoami                         # who the API thinks you are
+```
+
+`TESTBED_URL` selects the instance (default https://testbed.botiverse.build). Add `--json`
+to any command to get the raw API body for parsing.
+
+## Workflow 1 — run the acceptance table against a build
+
+```sh
+testbed cases                                           # the case table (id, tier, revision, title)
+testbed run --all --apk <download-url> --release <id>   # whole table in one run (release smoke)
+testbed run <case-id...> --apk <download-url>           # a subset
+testbed runs                                            # recent runs
+testbed show <run-id>                                   # per-case verdicts, turns, evidence
+```
+
+Release SOP rules (artin, 2026-09-04): the default 3-step smoke (login, channel list,
+open a channel) is NOT a full smoke. A release smoke is `run --all`. A cell that was not
+run is recorded as `NOT RUN` with the reason (hotfix exemption: `NOT RUN·hotfix 豁免`),
+never left blank. Receipts bind `versionCode + SHA-256`, not just the version name.
+
+## Workflow 2 — hand a phone to a human verifier
+
+```sh
+testbed verify start --ttl 30 --app-ref "1.11.0 (1110001)" \
+  [--apk-key fast/<id> --apk-sha256 <hex>]   # pre-install an APK; key and sha go together
+# prints the verify page URL — give it to the human
+testbed verify accounts <session-id>          # QA accounts they may log in with
+testbed verify login <session-id> --account <account-id>
+testbed verify renew <session-id> --minutes 30
+testbed verify reinstall <session-id> --apk-key fast/<id> --apk-sha256 <hex>
+testbed verify end <session-id>               # always end; the device is reclaimed
+```
+
+One verification session is live at a time; `start` answers 409 when another is live.
+`show` on an ended session answers 410.
+
+## Workflow 3 — drive a phone yourself over ADB
+
+```sh
+testbed pool                                  # free / leased
+testbed acquire --ttl 20 --key-out ./adb.key  # lease; private key written 0600, never printed
+adb connect <adb_endpoint>                    # from the acquire output
+testbed renew <lease-id> --ttl 20
+testbed diagnose-adb <lease-id> [--pubkey-sha256 <hex>]
+testbed release <lease-id>                    # always release
+```
+
+Device safety (non-negotiable):
+- Never paste `adb_private_key` into Raft messages, tasks, logs, or artifacts.
+- Before connecting, derive the saved key's android_pubkey SHA-256 and require it to equal
+  `adb_public_key_sha256` from the acquire response; on mismatch, release and do not connect.
+- Release every lease. Devices in `reclaiming` / `reclaim_failed` are never yours.
+- Cloud-phone screenshots can return a stale frame: to prove "nothing changed", the
+  capture must include something that would have changed if it were live.
+
+## Errors
+
+- `401` → `testbed login` (agent) or check `TESTBED_TOKEN` (human/CI).
+- `409 POOL_EXHAUSTED` / `ANOTHER_SESSION_LIVE` → wait or end/release what you hold.
+- `410` on a verification session → it is over; start a new one.
+
+## Reference
+
+`GET /api/help` on the instance lists every command and the raw routes behind them.
+Manifest action for Raft Agent Login: `agent-login` (the CLI performs it for you).