@shipvo/cli 0.1.5 → 0.1.6

package/README.md

@@ -18,6 +18,7 @@ npx -y @shipvo/cli sim                  # serve the app in the simulator for age
 | `sim [--port 4545]` | Build for the simulator and serve it |
 | `publish [--bands b0,b1,b2]` | Build, sign and publish a release plus the agent-facing web artifact |
 | `rollback --to <release>` | Republish an earlier release's code as a new release |
+| `test [files] --report <file> --release <n> [--platform android\|ios] --upload` | Run plain-language tests and send the results to the control plane; `status` then shows "tests: N failing" per release |
 | `login` | Sign in with GitHub; issues a 30-day key |
 | `app create` / `list` / `delete <id> --yes` | Register the app (publish token), list yours, or remove one |
 | `keys` | Status and quota of the stored sign-in key |
@@ -28,6 +29,8 @@ npx -y @shipvo/cli sim                  # serve the app in the simulator for age
 | `pubkey` | Print the public key for the current seed |
 | `hash <file>`, `sign-file <file>`, `sign-json <file>`, `verify-json <file> <key>`, `verify <pointer> [key]` (release pointers) | Low-level signing helpers |
 
+`init`, `login`, `audit` and `keys` take `--json`: one `{ ok, code, summary, data, next }` document on stdout, progress on stderr. Exit codes: 0 ok, 1 failed, 2 usage error. The codes and `data` shapes are in [docs/cli.md](../../docs/cli.md#--json-for-init-login-audit-and-keys). `keys export --json` needs `--out`, and no envelope holds a seed or token.
+
 Changing computers? See [Moving to a new machine](new-machine.md).
 
 Also usable as a library: `signDoc`, `verifyDoc`, `signBytes`, `sha256Hex`, `keyFromSeed`.

package/dist/adopt.js

@@ -86,7 +86,7 @@ export async function adopt(argv, dir = process.cwd(), overrides = {}) {
     }
     if (p.expoUpdates || p.codePush) {
         const what = p.expoUpdates ? "expo-updates" : "react-native-code-push";
-        return fail(`shipvo: this app uses ${what}. Two over-the-air systems would fight over the bundle, so I stopped and changed nothing.\nRemove ${what} first. Steps: docs/migrate-from-codepush.md`);
+        return fail(`shipvo: this app uses ${what}. Two over-the-air systems would fight over the bundle, so I stopped and changed nothing.\n${p.expoUpdates ? "Run `shipvo migrate --plan` to see the steps. Guide: docs/migrate-from-eas-update.md" : "Remove react-native-code-push first. Steps: docs/migrate-from-codepush.md"}`);
     }
     let manifest = null, infoPlist;
     if (bare) {
@@ -248,7 +248,6 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - run: ${pm === "npm" ? "npm ci" : pm === "pnpm" ? "corepack enable && pnpm install --frozen-lockfile" : pm === "yarn" ? "corepack enable && yarn install --immutable" : "npm i -g bun && bun install --frozen-lockfile"}
-      - run: pip install --break-system-packages bsdiff4
       - name: Build, sign and publish over the air
         env:
           SHIPVO_PUBLISH_TOKEN: \${{ secrets.SHIPVO_PUBLISH_TOKEN }}

package/dist/agents.d.ts

@@ -10,5 +10,20 @@ export declare function agentsSection(kind: ProjectKind): string;
 export declare function upsertSection(text: string, section: string): string | null;
 /** Add the `shipvo` server and keep every other server and key. Returns null if the file is not valid JSON. */
 export declare function mergeMcp(text: string | null): string | null;
+/** Where synced skills are copied to, relative to the project. */
+export declare const SKILL_DIRS: string[];
+export type SkillEntry = {
+    package: string;
+    name: string;
+    source: string;
+};
+/** Skills shipped by the `@shipvo/*` packages this project depends on and has installed. */
+export declare function projectSkills(dir: string): SkillEntry[];
+/** For `status --json`: each package skill and whether every target holds the current copy. */
+export declare function skillStatus(dir: string): {
+    package: string;
+    name: string;
+    synced: boolean;
+}[];
 /** `shipvo agents setup [--dry-run] [--json]`. Exit 0 done, 2 error. */
 export declare function agentsCmd(argv: string[], dir?: string): Promise<number>;

package/dist/agents.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { args } from "./config.js";
 export const BEGIN = "<!-- shipvo:begin -->";
@@ -68,13 +68,63 @@ export function mergeMcp(text) {
     servers.shipvo = SERVER;
     return JSON.stringify({ ...doc, mcpServers: servers }, null, 2) + "\n";
 }
+/** Where synced skills are copied to, relative to the project. */
+export const SKILL_DIRS = [".agents/skills", ".claude/skills"];
+/** Skills shipped by the `@shipvo/*` packages this project depends on and has installed. */
+export function projectSkills(dir) {
+    let deps = {};
+    try {
+        const p = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        deps = { ...p.peerDependencies, ...p.devDependencies, ...p.dependencies };
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const pkg of Object.keys(deps).filter((d) => d.startsWith("@shipvo/")).sort()) {
+        let root = dir, found = null;
+        for (;;) {
+            const c = join(root, "node_modules", pkg, "skills");
+            if (existsSync(c)) {
+                found = c;
+                break;
+            }
+            const up = dirname(root);
+            if (up === root)
+                break;
+            root = up;
+        }
+        if (!found)
+            continue;
+        for (const n of readdirSync(found).sort()) {
+            const source = join(found, n, "SKILL.md");
+            if (existsSync(source))
+                out.push({ package: pkg, name: n, source });
+        }
+    }
+    return out;
+}
+/** Which skill files (project-relative) are missing or out of date. */
+function skillTargets(dir, e) {
+    const text = readFileSync(e.source, "utf8");
+    return SKILL_DIRS.map((d) => {
+        const file = `${d}/${e.name}/SKILL.md`;
+        const path = join(dir, file);
+        return { file, text, synced: existsSync(path) && readFileSync(path, "utf8") === text };
+    });
+}
+/** For `status --json`: each package skill and whether every target holds the current copy. */
+export function skillStatus(dir) {
+    return projectSkills(dir).map((e) => ({ package: e.package, name: e.name, synced: skillTargets(dir, e).every((t) => t.synced) }));
+}
 /** `shipvo agents setup [--dry-run] [--json]`. Exit 0 done, 2 error. */
 export async function agentsCmd(argv, dir = process.cwd()) {
     const [sub, ...rest] = argv;
-    if (sub !== "setup") {
+    if (sub !== "setup" && sub !== "skills-sync") {
         console.error("Usage: shipvo agents setup [--dry-run] [--json]");
         return 2;
     }
+    const only = sub === "skills-sync";
     const a = args(rest);
     const dry = a["dry-run"] !== undefined, json = a.json !== undefined;
     const kind = detectProject(dir);
@@ -95,12 +145,18 @@ export async function agentsCmd(argv, dir = process.cwd()) {
         writes.push({ path, text: next });
     };
     const read = (f) => existsSync(join(dir, f)) ? readFileSync(join(dir, f), "utf8") : null;
-    plan("AGENTS.md", upsertSection(read("AGENTS.md") ?? "", agentsSection(kind)), "AGENTS.md has a broken shipvo marker; fix it and run again.");
-    const targets = [".mcp.json", ...(existsSync(join(dir, ".cursor")) ? [".cursor/mcp.json"] : [])];
-    for (const f of targets) {
-        const merged = mergeMcp(read(f));
-        plan(f, merged, `${f} is not valid JSON; I left it alone. Fix it and run again.`);
+    if (!only) {
+        plan("AGENTS.md", upsertSection(read("AGENTS.md") ?? "", agentsSection(kind)), "AGENTS.md has a broken shipvo marker; fix it and run again.");
+        const targets = [".mcp.json", ...(existsSync(join(dir, ".cursor")) ? [".cursor/mcp.json"] : [])];
+        for (const f of targets) {
+            const merged = mergeMcp(read(f));
+            plan(f, merged, `${f} is not valid JSON; I left it alone. Fix it and run again.`);
+        }
     }
+    const skills = projectSkills(dir);
+    for (const e of skills)
+        for (const t of skillTargets(dir, e))
+            plan(t.file, t.text);
     const bad = changes.some((c) => c.action === "skip");
     if (!dry && !bad)
         for (const w of writes) {
@@ -109,7 +165,7 @@ export async function agentsCmd(argv, dir = process.cwd()) {
         }
     const wrote = !dry && !bad;
     if (json)
-        console.log(JSON.stringify({ ok: !bad, project: kind, dry_run: dry, changes, skill_install: SKILL_LINE }));
+        console.log(JSON.stringify({ ok: !bad, project: kind, dry_run: dry, changes, skill_install: SKILL_LINE, skills: skills.map((e) => ({ package: e.package, name: e.name })) }));
     else {
         console.log(`Project: ${LABEL[kind]}.`);
         for (const c of changes)
@@ -118,7 +174,10 @@ export async function agentsCmd(argv, dir = process.cwd()) {
             console.log("Dry run: nothing was written.");
         else if (wrote && !changes.some((c) => c.action !== "unchanged"))
             console.log("Nothing to change.");
-        console.log(`Install the skill: ${SKILL_LINE}`);
+        if (only && !skills.length)
+            console.log("No installed @shipvo/* dependency ships a skill.");
+        if (!only)
+            console.log(`Install the skill: ${SKILL_LINE}`);
     }
     return bad ? 2 : 0;
 }

package/dist/approvals.d.ts

@@ -0,0 +1,9 @@
+export declare const APPROVALS_HELP = "Usage: shipvo approvals list [--app id] [--json]\n       shipvo approvals approve <id> [--app id] [--json]\n\nList promotes held above policy.requireApprovalAbove, or approve one.\nA second owner must approve: the proposer cannot, and an agent cannot approve an agent's proposal.\n\nExit codes: 0 done, 1 refused by a rule (the rule is named), 2 error.\nWith --json, one line: { ok, code, summary, data, next }, the same envelope as status and doctor.\ncode is ok, a rule name such as self_approval, or usage, config, no_credentials, unreachable, http_<status>.\nThe list is in data.approvals.\n\nApproving a hold that an agent proposed (through the publish token) needs a signed-in person (run shipvo login).\nSHIPVO_OWNER_TOKEN counts as an agent, so it can approve only holds that a person proposed.\nlist also works with the publish token.\n";
+/** "3m", "2h", "5d". */
+export declare function age(from: string, now?: number): string;
+/** Whole seconds since `from`, or null when the date does not parse. */
+export declare function ageSeconds(from: string, now?: number): number | null;
+export declare function approvals(argv: string[], deps?: {
+    fetchFn?: typeof fetch;
+    now?: number;
+}): Promise<number>;

package/dist/approvals.js

@@ -0,0 +1,106 @@
+// `shipvo approvals list` and `shipvo approvals approve <id>`: see and release promotes held above the policy band.
+import { loadConfig, publishToken } from "./config.js";
+import { savedCreds } from "./login.js";
+import { envelope } from "./json-out.js";
+export const APPROVALS_HELP = `Usage: shipvo approvals list [--app id] [--json]
+       shipvo approvals approve <id> [--app id] [--json]
+
+List promotes held above policy.requireApprovalAbove, or approve one.
+A second owner must approve: the proposer cannot, and an agent cannot approve an agent's proposal.
+
+Exit codes: 0 done, 1 refused by a rule (the rule is named), 2 error.
+With --json, one line: { ok, code, summary, data, next }, the same envelope as status and doctor.
+code is ok, a rule name such as self_approval, or usage, config, no_credentials, unreachable, http_<status>.
+The list is in data.approvals.
+
+Approving a hold that an agent proposed (through the publish token) needs a signed-in person (run shipvo login).
+SHIPVO_OWNER_TOKEN counts as an agent, so it can approve only holds that a person proposed.
+list also works with the publish token.
+`;
+/** "3m", "2h", "5d". */
+export function age(from, now = Date.now()) {
+    const s = ageSeconds(from, now);
+    if (s === null)
+        return "?";
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m`;
+    if (s < 86400)
+        return `${Math.floor(s / 3600)}h`;
+    return `${Math.floor(s / 86400)}d`;
+}
+/** Whole seconds since `from`, or null when the date does not parse. */
+export function ageSeconds(from, now = Date.now()) {
+    const n = Math.round((now - Date.parse(from)) / 1000);
+    return Number.isFinite(n) ? Math.max(0, n) : null;
+}
+export async function approvals(argv, deps = {}) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(APPROVALS_HELP);
+        return 0;
+    }
+    const json = argv.includes("--json");
+    const out = (code, summary, data, next, exit, human = summary) => {
+        console.log(json ? JSON.stringify(envelope(code, summary, data, next, exit)) : human);
+        return exit;
+    };
+    const fail = (code, message, data = {}, exit = 2, next = []) => out(code, message, data, next, exit);
+    const pos = [];
+    let app;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--app")
+            app = argv[++i];
+        else if (!argv[i].startsWith("--"))
+            pos.push(argv[i]);
+    }
+    const [sub, id] = pos;
+    if (sub !== "list" && sub !== "approve")
+        return fail("usage", "Usage: shipvo approvals list | approve <id> [--app id] [--json]");
+    if (sub === "approve" && !id)
+        return fail("usage", "Usage: shipvo approvals approve <id> [--app id] [--json]");
+    let cfg;
+    try {
+        cfg = loadConfig();
+    }
+    catch (e) {
+        return fail("config", e instanceof Error ? e.message : String(e));
+    }
+    const appId = app ?? cfg.appId;
+    const token = process.env.SHIPVO_OWNER_TOKEN?.trim() || savedCreds()?.key || publishToken();
+    if (!token)
+        return fail("no_credentials", "No credentials. Set SHIPVO_OWNER_TOKEN, run `shipvo login`, or use the publish token.");
+    const base = cfg.controlPlane.replace(/\/$/, "");
+    const f = deps.fetchFn ?? fetch;
+    const url = `${base}/apps/${encodeURIComponent(appId)}/approvals` + (sub === "approve" ? `/${encodeURIComponent(id)}/approve` : "");
+    let r;
+    try {
+        r = await f(url, { method: sub === "approve" ? "POST" : "GET", headers: { authorization: `Bearer ${token}` } });
+    }
+    catch (e) {
+        return fail("unreachable", `Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
+    }
+    const body = (await r.json().catch(() => ({})));
+    if (!r.ok) {
+        const rule = body.rule;
+        const msg = body.message ?? body.reason ?? body.error ?? `HTTP ${r.status}`;
+        const exit = r.status === 403 || r.status === 409 ? 1 : 2;
+        const data = { status: r.status, ...(rule ? { rule } : {}) };
+        if (rule) {
+            const hint = rule === "self_approval" && sub === "approve" ? " If an agent proposed this hold, sign in as a person with shipvo login (SHIPVO_OWNER_TOKEN counts as an agent)." : "";
+            const next = rule === "self_approval" && sub === "approve" ? [{ command: "shipvo login", why: "A person's login can approve a hold that an agent proposed." }] : [];
+            return fail(rule, `Refused by rule ${rule}: ${msg}${hint}`, data, exit, next);
+        }
+        return fail(body.error ?? `http_${r.status}`, `Request failed: ${msg}${r.status === 401 ? " (the token was not accepted for this app)" : ""}`, data, exit);
+    }
+    if (sub === "approve") {
+        return out("ok", `Approved ${id}. The promote is live.`, { command: "approve", app: appId, approval_id: body.approval_id ?? id, status: body.status }, [{ command: "shipvo status", why: "Check the release is reporting." }], 0);
+    }
+    const rows = body.approvals ?? [];
+    const data = { command: "list", app: appId, approvals: rows.map((h) => ({ id: h.id, release: h.release, band: h.band, proposer: h.proposer, proposed_at: h.proposed_at, age_seconds: ageSeconds(h.proposed_at, deps.now) })) };
+    if (!rows.length)
+        return out("ok", "No promotes are waiting for approval.", data, [], 0);
+    const cols = rows.map((h) => [h.id, String(h.release), h.band, h.proposer, age(h.proposed_at, deps.now)]);
+    const head = ["ID", "RELEASE", "BAND", "PROPOSER", "AGE"];
+    const w = head.map((t, i) => Math.max(t.length, ...cols.map((c) => c[i].length)));
+    const line = (c) => c.map((v, i) => v.padEnd(w[i])).join("  ").trimEnd();
+    return out("ok", `${rows.length} promote${rows.length === 1 ? " is" : "s are"} waiting for approval.`, data, [{ command: `shipvo approvals approve ${rows[0].id}`, why: "Release the oldest hold if you are a second owner." }], 0, [line(head), ...cols.map(line)].join("\n"));
+}

package/dist/audit.d.ts

@@ -1,6 +1,6 @@
 export declare const AUDIT_FLAGS: string[];
 export declare const AUDIT_COLUMNS: readonly ["id", "app_id", "at", "actor", "actor_kind", "action", "release", "release_id", "before", "after"];
-export declare const AUDIT_HELP = "Usage: shipvo audit <app> [--format json|csv] [--limit n]\n\nPrint the app's audit log, newest first, to stdout. Pages through the control plane.\n\nFlags (write a value after a space, not =):\n  --format json|csv   Output format (default json)\n  --limit n           Stop after n entries (default: all)\n  --help              Show this help\n\nNeeds SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).\n";
+export declare const AUDIT_HELP = "Usage: shipvo audit <app> [--format json|csv] [--limit n] [--json]\n\nPrint the app's audit log, newest first, to stdout. Pages through the control plane.\n\nFlags (write a value after a space, not =):\n  --format json|csv   Output format (default json)\n  --limit n           Stop after n entries (default: all)\n  --json              Print one JSON envelope on stdout: { ok, code, summary, data, next }\n  --help              Show this help\n\nNeeds SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).\n";
 type Row = Record<string, unknown> & {
     id: number;
 };

package/dist/audit.js

@@ -1,15 +1,17 @@
 // `shipvo audit <app>`: export an app's audit log as JSON or CSV on stdout.
 import { args as parse, loadConfig, publishToken } from "./config.js";
-export const AUDIT_FLAGS = ["format", "limit"];
+import { CliFailure, UsageError, runJson } from "./json-out.js";
+export const AUDIT_FLAGS = ["format", "limit", "json"];
 export const AUDIT_COLUMNS = ["id", "app_id", "at", "actor", "actor_kind", "action", "release", "release_id", "before", "after"];
 const PAGE = 200;
-export const AUDIT_HELP = `Usage: shipvo audit <app> [--format json|csv] [--limit n]
+export const AUDIT_HELP = `Usage: shipvo audit <app> [--format json|csv] [--limit n] [--json]
 
 Print the app's audit log, newest first, to stdout. Pages through the control plane.
 
 Flags (write a value after a space, not =):
   --format json|csv   Output format (default json)
   --limit n           Stop after n entries (default: all)
+  --json              Print one JSON envelope on stdout: { ok, code, summary, data, next }
   --help              Show this help
 
 Needs SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).
@@ -29,26 +31,41 @@ export async function audit(argv, deps = {}) {
         console.log(AUDIT_HELP);
         return;
     }
+    if (argv.includes("--json")) {
+        return runJson(async () => {
+            const { appId, rows, format, limit } = await auditRows(argv, deps);
+            if (format === "csv")
+                throw new UsageError("--json always returns rows in data. Drop --format csv, or drop --json.");
+            const next = [{ command: "shipvo status --json", why: "See how the latest release does on phones." }];
+            if (limit !== undefined && rows.length === limit)
+                next.unshift({ command: `shipvo audit ${appId} --json`, why: "Read the whole log, not just the newest entries." });
+            return { code: "ok", summary: `${rows.length} audit ${rows.length === 1 ? "entry" : "entries"} for "${appId}", newest first.`, data: { app: appId, count: rows.length, rows }, next };
+        }, [{ command: "shipvo doctor --json", why: "Check your setup." }]);
+    }
+    const { rows, format } = await auditRows(argv, deps);
+    console.log(format === "csv" ? toCsv(rows) : JSON.stringify(rows, null, 2));
+}
+async function auditRows(argv, deps) {
     const bad = argv.filter((x) => x.startsWith("--") && !AUDIT_FLAGS.includes(x.slice(2)));
     if (bad.length)
-        throw new Error(`Unknown flag ${bad.join(", ")}. Known flags: ${AUDIT_FLAGS.map((k) => "--" + k).join(" ")}`);
+        throw new UsageError(`Unknown flag ${bad.join(", ")}. Known flags: ${AUDIT_FLAGS.map((k) => "--" + k).join(" ")}`);
     const a = parse(argv);
     // Positional app id: the first argument that is not a flag or a flag's value.
-    const appId = argv.find((x, i) => !x.startsWith("--") && !(i > 0 && AUDIT_FLAGS.includes(argv[i - 1].slice(2)) && argv[i - 1].startsWith("--")));
+    const appId = argv.find((x, i) => !x.startsWith("--") && !(i > 0 && argv[i - 1].startsWith("--") && argv[i - 1] !== "--json" && AUDIT_FLAGS.includes(argv[i - 1].slice(2))));
     if (!appId)
-        throw new Error("Usage: shipvo audit <app> [--format json|csv] [--limit n]");
+        throw new UsageError("Usage: shipvo audit <app> [--format json|csv] [--limit n] [--json]");
     const format = a.format ?? "json";
     if (format !== "json" && format !== "csv")
-        throw new Error(`--format must be json or csv (got "${a.format}").`);
+        throw new UsageError(`--format must be json or csv (got "${a.format}").`);
     let max = Infinity;
     if (argv.includes("--limit")) {
         max = Number(a.limit);
         if (!Number.isInteger(max) || max < 1)
-            throw new Error(`--limit must be a positive whole number (got "${a.limit}").`);
+            throw new UsageError(`--limit must be a positive whole number (got "${a.limit}").`);
     }
     const token = process.env.SHIPVO_OWNER_TOKEN?.trim() || publishToken();
     if (!token)
-        throw new Error("No credentials. Set SHIPVO_OWNER_TOKEN, or run `shipvo app create` to get a publish token (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).");
+        throw new CliFailure("No credentials. Set SHIPVO_OWNER_TOKEN, or run `shipvo app create` to get a publish token (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).", "no_credentials", 1, [{ command: "shipvo app create", why: "Get a publish token for this app." }]);
     const base = loadConfig().controlPlane.replace(/\/$/, "");
     const f = deps.fetchFn ?? fetch;
     const rows = [];
@@ -61,15 +78,15 @@ export async function audit(argv, deps = {}) {
             r = await f(url, { headers: { authorization: `Bearer ${token}` } });
         }
         catch (e) {
-            throw new Error(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
+            throw new CliFailure(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`, "remote_failed", 1, [{ command: "shipvo doctor --json", why: "Check the control plane address." }]);
         }
         if (!r.ok)
-            throw new Error(`Audit request failed: HTTP ${r.status}${r.status === 401 ? " (the token was not accepted for this app)" : ""}.`);
+            throw new CliFailure(`Audit request failed: HTTP ${r.status}${r.status === 401 ? " (the token was not accepted for this app)" : ""}.`, r.status === 401 ? "auth_failed" : "remote_failed", 1, [{ command: r.status === 401 ? "shipvo app create" : "shipvo doctor --json", why: r.status === 401 ? "Get a publish token for this app." : "Check the control plane." }]);
         const page = (await r.json()).rows ?? [];
         rows.push(...page);
         if (page.length < want)
             break;
         before = page[page.length - 1].id;
     }
-    console.log(format === "csv" ? toCsv(rows) : JSON.stringify(rows, null, 2));
+    return { appId, rows, format, limit: Number.isFinite(max) ? max : undefined };
 }

package/dist/autohalt.d.ts

@@ -1,5 +1,5 @@
 export declare const AUTOHALT_FLAGS: string[];
-export declare const AUTOHALT_HELP = "Usage: shipvo auto-halt [flags]\n\nStop serving a release on its own when too many devices fail to apply it.\nWith no flags, print the current setting.\n\nFlags (write a value after a space, not =):\n  --threshold 0.2     Halt when more than this share of reports failed (above 0, at most 1)\n  --min-reports 20    Wait for this many reports first (1 to 10000, default 20)\n  --off               Turn auto-halt off\n  --dry-run           Print what would change, write nothing\n  --help              Show this help\n\nNeeds SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).\n";
+export declare const AUTOHALT_HELP = "Usage: shipvo auto-halt [flags]\n\nStop serving a release on its own when too many devices fail to apply it.\nWith no flags, print the current setting.\n\nFlags (write a value after a space, not =):\n  --threshold 0.2     Halt when more than this share of reports failed (above 0, at most 1)\n  --min-reports 20    Wait for this many reports first (1 to 10000, default 20)\n  --off               Turn auto-halt off\n  --dry-run           Print what would change, write nothing\n  --json              Print one JSON envelope on stdout; text goes to stderr\n  --help              Show this help\n\nNeeds SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).\n";
 export declare function autoHalt(argv: string[], deps?: {
     fetchFn?: typeof fetch;
 }): Promise<void>;

package/dist/autohalt.js

@@ -1,7 +1,8 @@
 // `shipvo auto-halt`: show, turn on or turn off auto-halt for this app, through the control plane.
 import { args as parse, loadConfig, publishToken } from "./config.js";
 import { describeAutoHalt } from "./status.js";
-export const AUTOHALT_FLAGS = ["threshold", "min-reports", "off", "dry-run"];
+import { CliFailure, UsageError, runJson } from "./json-out.js";
+export const AUTOHALT_FLAGS = ["threshold", "min-reports", "off", "dry-run", "json"];
 export const AUTOHALT_HELP = `Usage: shipvo auto-halt [flags]
 
 Stop serving a release on its own when too many devices fail to apply it.
@@ -12,6 +13,7 @@ Flags (write a value after a space, not =):
   --min-reports 20    Wait for this many reports first (1 to 10000, default 20)
   --off               Turn auto-halt off
   --dry-run           Print what would change, write nothing
+  --json              Print one JSON envelope on stdout; text goes to stderr
   --help              Show this help
 
 Needs SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).
@@ -22,32 +24,37 @@ export async function autoHalt(argv, deps = {}) {
         console.log(AUTOHALT_HELP);
         return;
     }
+    if (argv.includes("--json"))
+        return runJson(() => autoHaltRun(argv, deps), [{ command: "shipvo doctor --json", why: "Check your setup." }]);
+    await autoHaltRun(argv, deps);
+}
+async function autoHaltRun(argv, deps) {
     const bad = argv.filter((x) => x.startsWith("--") && !AUTOHALT_FLAGS.includes(x.slice(2)));
     if (bad.length) {
         const eq = bad.find((x) => x.includes("="));
-        throw new Error(`Unknown flag ${bad.join(", ")}.${eq ? ` Write "${eq.replace("=", " ")}" (a space, not =).` : ""} Known flags: ${AUTOHALT_FLAGS.map((k) => "--" + k).join(" ")}`);
+        throw new UsageError(`Unknown flag ${bad.join(", ")}.${eq ? ` Write "${eq.replace("=", " ")}" (a space, not =).` : ""} Known flags: ${AUTOHALT_FLAGS.map((k) => "--" + k).join(" ")}`);
     }
     const a = parse(argv), cfg = loadConfig();
     const dry = argv.includes("--dry-run"), off = argv.includes("--off");
     const hasT = argv.includes("--threshold"), hasM = argv.includes("--min-reports");
     if (off && (hasT || hasM))
-        throw new Error("--off cannot be combined with --threshold or --min-reports.");
+        throw new UsageError("--off cannot be combined with --threshold or --min-reports.");
     let threshold, minReports = 20;
     if (hasT || hasM) {
         if (!hasT)
-            throw new Error("--min-reports needs --threshold too, for example --threshold 0.2 --min-reports 20.");
+            throw new UsageError("--min-reports needs --threshold too, for example --threshold 0.2 --min-reports 20.");
         threshold = a.threshold === "true" || a.threshold === undefined ? NaN : Number(a.threshold);
         if (!(threshold > 0 && threshold <= 1))
-            throw new Error(`--threshold must be a number above 0 and at most 1, for example 0.2 (got "${a.threshold}").`);
+            throw new UsageError(`--threshold must be a number above 0 and at most 1, for example 0.2 (got "${a.threshold}").`);
         if (hasM) {
             minReports = a["min-reports"] === "true" || a["min-reports"] === undefined ? NaN : Number(a["min-reports"]);
             if (!Number.isInteger(minReports) || minReports < 1 || minReports > 10000)
-                throw new Error(`--min-reports must be a whole number from 1 to 10000 (got "${a["min-reports"]}").`);
+                throw new UsageError(`--min-reports must be a whole number from 1 to 10000 (got "${a["min-reports"]}").`);
         }
     }
     const token = process.env.SHIPVO_OWNER_TOKEN?.trim() || publishToken();
     if (!token)
-        throw new Error("No credentials. Set SHIPVO_OWNER_TOKEN, or run `shipvo app create` to get a publish token (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).");
+        throw new CliFailure("No credentials. Set SHIPVO_OWNER_TOKEN, or run `shipvo app create` to get a publish token (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).", "no_credentials", 1, [{ command: "shipvo app create", why: "Get a publish token." }]);
     const base = cfg.controlPlane.replace(/\/$/, "");
     const url = `${base}/app/${encodeURIComponent(cfg.appId)}/api/halt-config`;
     const call = async (method, body) => {
@@ -56,29 +63,34 @@ export async function autoHalt(argv, deps = {}) {
             r = await (deps.fetchFn ?? fetch)(url, { method, headers: { authorization: `Bearer ${token}`, ...(body ? { "content-type": "application/json" } : {}) }, body: body ? JSON.stringify(body) : undefined });
         }
         catch (e) {
-            throw new Error(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
+            throw new CliFailure(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`, "remote_failed", 1, [{ command: "shipvo doctor --json", why: "Check the control plane." }]);
         }
         if (r.status === 401 || r.status === 403)
-            throw new Error(`The control plane at ${base} rejected your token (${r.status}). Check SHIPVO_OWNER_TOKEN or your publish token.`);
+            throw new CliFailure(`The control plane at ${base} rejected your token (${r.status}). Check SHIPVO_OWNER_TOKEN or your publish token.`, "auth_failed", 1, [{ command: "shipvo app create", why: "Get a publish token, or set SHIPVO_OWNER_TOKEN." }]);
         if (!r.ok) {
             let m = "";
             try {
                 m = (await r.json()).message ?? "";
             }
             catch { /* no body */ }
-            throw new Error(`Auto-halt request failed: HTTP ${r.status}${m ? ` ${m}` : ""}`);
+            throw new CliFailure(`Auto-halt request failed: HTTP ${r.status}${m ? ` ${m}` : ""}`, "remote_failed", 1, [{ command: "shipvo doctor --json", why: "Check the control plane." }]);
         }
         return (await r.json());
     };
-    if (!off && threshold === undefined) {
-        console.log(describe(await call("GET")));
-        return;
-    }
+    const status = [{ command: "shipvo status --json", why: "See how the newest releases do." }];
+    const done = (code, st, extra = {}) => {
+        console.log(describe(st));
+        return { code, summary: describe(st), data: { enabled: st.enabled, threshold: st.enabled ? st.threshold ?? null : null, min_reports: st.enabled ? st.min_reports ?? null : null, dry_run: false, changed: false, ...extra }, next: status };
+    };
+    if (!off && threshold === undefined)
+        return done("auto_halt_show", await call("GET"));
     const want = off ? { enabled: false } : { enabled: true, threshold, min_reports: minReports };
     if (dry) {
         console.log(`Would set ${describe(want)}`);
         console.log("Dry run: nothing was written.");
-        return;
+        const real = argv.filter((x) => x !== "--dry-run");
+        return { code: "dry_run", summary: `Would set ${describe(want)}`, data: { enabled: want.enabled, threshold: want.threshold ?? null, min_reports: want.min_reports ?? null, dry_run: true, changed: false }, next: [{ command: `shipvo auto-halt ${real.join(" ")}`.trim(), why: "Apply this setting." }] };
     }
-    console.log(describe(off ? await call("DELETE") : await call("PUT", { threshold, min_reports: minReports })));
+    const st = off ? await call("DELETE") : await call("PUT", { threshold, min_reports: minReports });
+    return done(off ? "auto_halt_off" : "auto_halt_on", st, { changed: true });
 }

package/dist/bsdiff.d.ts

@@ -0,0 +1,4 @@
+/** Compress to a standard .bz2 stream. */
+export declare function bzip2(data: Uint8Array): Uint8Array;
+/** A BSDIFF40 patch that turns `oldData` into `newData`. */
+export declare function bsdiff(oldData: Uint8Array, newData: Uint8Array): Uint8Array<ArrayBuffer>;