@shipvo/cli 0.1.2 → 0.1.4

package/dist/autohalt.js

@@ -0,0 +1,84 @@
+// `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"];
+export const AUTOHALT_HELP = `Usage: shipvo auto-halt [flags]
+
+Stop serving a release on its own when too many devices fail to apply it.
+With no flags, print the current setting.
+
+Flags (write a value after a space, not =):
+  --threshold 0.2     Halt when more than this share of reports failed (above 0, at most 1)
+  --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
+  --help              Show this help
+
+Needs SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).
+`;
+const describe = (s) => describeAutoHalt(s.enabled ? { threshold: s.threshold, min_reports: s.min_reports } : null);
+export async function autoHalt(argv, deps = {}) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(AUTOHALT_HELP);
+        return;
+    }
+    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(" ")}`);
+    }
+    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.");
+    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.");
+        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}").`);
+        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"]}").`);
+        }
+    }
+    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).");
+    const base = cfg.controlPlane.replace(/\/$/, "");
+    const url = `${base}/app/${encodeURIComponent(cfg.appId)}/api/halt-config`;
+    const call = async (method, body) => {
+        let r;
+        try {
+            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)}).`);
+        }
+        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.`);
+        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}` : ""}`);
+        }
+        return (await r.json());
+    };
+    if (!off && threshold === undefined) {
+        console.log(describe(await call("GET")));
+        return;
+    }
+    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;
+    }
+    console.log(describe(off ? await call("DELETE") : await call("PUT", { threshold, min_reports: minReports })));
+}

package/dist/cli.js

@@ -5,94 +5,130 @@ import { b64, keyFromSeed, sha256Hex, signBytes, signDoc, verifyDoc } from "./in
 import { seed } from "./config.js";
 import { init } from "./init.js";
 import { publish, rollback } from "./publish.js";
+import { promote } from "./promote.js";
+import { autoHalt } from "./autohalt.js";
 import { sim } from "./sim.js";
+import { preview } from "./preview.js";
 import { keys, login, mcp } from "./login.js";
+import { verifyPointer } from "./verify.js";
 import { signingKey } from "./signing.js";
 import { appCmd } from "./app.js";
+import { status } from "./status.js";
+import { doctor } from "./doctor.js";
+import { store } from "./store.js";
+import { failure, help, unknownCommand } from "./help.js";
 const [cmd, ...rest] = process.argv.slice(2);
-const help = `shipvo <command>
-
-  init <dir>                  New app wired to Shipvo: OTA runtime, device API, simulator, publish workflow
-  sim [--port 4545]           Build the app for the simulator and serve it (agents: open_app("<appId>"))
-  publish [--bands b0,b1,b2]  Build, sign and publish an over-the-air release (+ the agent-facing web artifact)
-  rollback --to <release>     Republish an earlier release's code as a new release
-  app create | list | delete  Register this app with the hosted control plane (publish token), list yours, or remove one
-  login                       Sign in with GitHub and get a key for the hosted simulator
-  keys                        Show the stored key's status and quota
-  keys export [--out f]       Print (or save) this app's release signing seed, to back it up or move machines
-  keys import [seed|--file f] Restore the signing seed on a new machine (checked against shipvo.json)
-  mcp                         Print the MCP config agents need (hosted and local)
-
-  keygen [--out seed.txt]     Create an Ed25519 release signing key; prints the public key
-  pubkey                      Print the public key for the seed in SHIPVO_SIGNING_SEED
-  hash <file>                 SHA-256 and size of a bundle
-  sign-file <file>            Ed25519 signature (base64) over a file's bytes
-  sign-json <file.json>       Sign a JSON document (canonical form); writes signature into it
-  verify-json <file.json> <public-key-b64>
-`;
-switch (cmd) {
-    case "init":
-        await init(rest);
-        break;
-    case "sim":
-        await sim(rest);
-        break;
-    case "publish":
-        await publish(rest);
-        break;
-    case "rollback":
-        await rollback(rest);
-        break;
-    case "login":
-        await login(rest);
-        break;
-    case "app":
-        await appCmd(rest);
-        break;
-    case "keys":
-        if (rest[0] === "export" || rest[0] === "import")
-            await signingKey(rest);
-        else
-            await keys();
-        break;
-    case "mcp":
-        mcp();
-        break;
-    case "keygen": {
-        const s = b64(randomBytes(32));
-        const out = rest[rest.indexOf("--out") + 1];
-        if (rest.includes("--out") && out) {
-            writeFileSync(out, s, { mode: 0o600 });
-            console.error(`Seed written to ${out}. Back it up offline; never commit it.`);
+try {
+    switch (cmd) {
+        case "init":
+            await init(rest);
+            break;
+        case "sim":
+            await sim(rest);
+            break;
+        case "preview":
+            await preview(rest);
+            break;
+        case "publish":
+            await publish(rest);
+            break;
+        case "promote":
+            await promote(rest);
+            break;
+        case "auto-halt":
+            await autoHalt(rest);
+            break;
+        case "rollback":
+            await rollback(rest);
+            break;
+        case "login":
+            await login(rest);
+            break;
+        case "doctor":
+            await doctor(rest);
+            break;
+        case "status":
+            process.exitCode = await status(rest);
+            break;
+        case "store":
+            await store(rest);
+            break;
+        case "app":
+            await appCmd(rest);
+            break;
+        case "keys":
+            if (rest[0] === "export" || rest[0] === "import")
+                await signingKey(rest);
+            else
+                await keys();
+            break;
+        case "mcp":
+            mcp();
+            break;
+        case "keygen": {
+            const s = b64(randomBytes(32));
+            const out = rest[rest.indexOf("--out") + 1];
+            if (rest.includes("--out") && out) {
+                writeFileSync(out, s, { mode: 0o600 });
+                console.error(`Seed written to ${out}. Back it up offline; never commit it.`);
+            }
+            else
+                console.log(`seed (secret): ${s}`);
+            console.log(`public key: ${b64(keyFromSeed(s).publicKey)}`);
+            break;
         }
-        else
-            console.log(`seed (secret): ${s}`);
-        console.log(`public key: ${b64(keyFromSeed(s).publicKey)}`);
-        break;
-    }
-    case "pubkey":
-        console.log(b64(keyFromSeed(seed()).publicKey));
-        break;
-    case "hash": {
-        const b = readFileSync(rest[0]);
-        console.log(JSON.stringify({ sha256: sha256Hex(b), size: b.length }));
-        break;
-    }
-    case "sign-file":
-        console.log(signBytes(new Uint8Array(readFileSync(rest[0])), seed()));
-        break;
-    case "sign-json": {
-        const d = JSON.parse(readFileSync(rest[0], "utf8"));
-        writeFileSync(rest[0], JSON.stringify(signDoc(d, seed()), null, 2));
-        console.log("signed");
-        break;
-    }
-    case "verify-json": {
-        const ok = verifyDoc(JSON.parse(readFileSync(rest[0], "utf8")), rest[1]);
-        console.log(ok ? "valid" : "INVALID");
-        process.exit(ok ? 0 : 1);
+        case "pubkey":
+            console.log(b64(keyFromSeed(seed()).publicKey));
+            break;
+        case "hash": {
+            const b = readFileSync(rest[0]);
+            console.log(JSON.stringify({ sha256: sha256Hex(b), size: b.length }));
+            break;
+        }
+        case "sign-file":
+            console.log(signBytes(new Uint8Array(readFileSync(rest[0])), seed()));
+            break;
+        case "sign-json": {
+            const d = JSON.parse(readFileSync(rest[0], "utf8"));
+            writeFileSync(rest[0], JSON.stringify(signDoc(d, seed()), null, 2));
+            console.log("signed");
+            break;
+        }
+        case "verify-json": {
+            const ok = verifyDoc(JSON.parse(readFileSync(rest[0], "utf8")), rest[1]);
+            console.log(ok ? "valid" : "INVALID");
+            process.exit(ok ? 0 : 1);
+        }
+        case "verify": {
+            if (!rest[0]) {
+                console.error("Usage: shipvo verify <pointer file> [public-key-b64]");
+                process.exit(2);
+            }
+            const key = rest[1] ?? b64(keyFromSeed(seed()).publicKey);
+            let text;
+            try {
+                text = readFileSync(rest[0], "utf8");
+            }
+            catch {
+                console.error(`Cannot read ${rest[0]}`);
+                process.exit(2);
+            }
+            const ok = verifyPointer(text, key);
+            console.log(ok ? "valid" : "INVALID");
+            process.exit(ok ? 0 : 1);
+        }
+        case undefined:
+        case "--help":
+        case "-h":
+        case "help":
+            console.log(help);
+            break;
+        default:
+            console.error(unknownCommand(cmd));
+            process.exit(1);
     }
-    default:
-        console.log(help);
-        process.exit(cmd ? 1 : 0);
+}
+catch (e) {
+    console.error(failure(e));
+    process.exit(1);
 }

package/dist/config.d.ts

@@ -7,10 +7,20 @@ export type ShipvoConfig = {
     controlPlane: string;
     /** Base64 Ed25519 public key built into the shell. */
     publicKey: string;
+    /** Hermes bytecode version(s) the app's shells run. If set, `shipvo publish` refuses bundles that differ. */
+    hermesBytecodeVersion?: number | number[];
+    /** What AI agents may do through `@shipvo/mcp` owner commands. "ask" (default): irreversible commands need confirm: true. "deny": they are refused. "allow": no confirm step (the owner must set it). */
+    agentPolicy?: "ask" | "deny" | "allow";
+    /** Owner commands agents may never run. */
+    agentDeny?: string[];
     /** Where `shipvo publish` writes: the control plane's Cloudflare KV namespace. */
     kv?: {
         namespaceId: string;
     };
+    /** Where `shipvo preview` publishes: "here.now" (default, no account) or "control-plane" (not built yet). */
+    preview?: "here.now" | "control-plane";
+    /** Release rules checked by `shipvo publish --dry-run`. Validated there, not at load, so a bad section never breaks other commands. */
+    policy?: unknown;
     /** Marketplace listing (hosted control plane): shown to agents and on shipvo.dev once reviewed. */
     listing?: {
         public?: boolean;

package/dist/config.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 export function loadConfig(dir = process.cwd()) {
     const p = join(dir, "shipvo.json");
     if (!existsSync(p))
-        throw new Error("No shipvo.json here. Run this inside an app created with `shipvo init`, or create one (see docs/getting-started.md).");
+        throw new Error("No shipvo.json in this folder. Run this inside your app's folder. To start a new app, run `shipvo init myshop`.");
     const c = JSON.parse(readFileSync(p, "utf8"));
     for (const k of ["appId", "controlPlane", "publicKey"])
         if (!c[k])
@@ -26,8 +26,8 @@ export function seed() {
     if (!s && local)
         return local;
     if (!s) {
-        console.error("Set SHIPVO_SIGNING_SEED or SHIPVO_SIGNING_SEED_FILE (the seed `shipvo keygen` printed), or keep it at .shipvo/seed.txt.");
-        process.exit(2);
+        console.error("Set SHIPVO_SIGNING_SEED or SHIPVO_SIGNING_SEED_FILE (the seed `shipvo keygen` printed), or keep it at .shipvo/seed.txt. No key yet? Run `shipvo keygen`.");
+        process.exit(1);
     }
     return s;
 }
@@ -47,13 +47,26 @@ function hostedKv(cfg, token) {
     const base = `${cfg.controlPlane.replace(/\/$/, "")}/apps/${cfg.appId}/kv`;
     const auth = { Authorization: `Bearer ${token}` };
     const path = (k) => `${base}/${k.split("/").map(encodeURIComponent).join("/")}`;
+    const host = cfg.controlPlane.replace(/\/$/, "");
+    /** One place for the two first-run failures: the server is not there, or it does not accept the token. */
+    const call = async (url, init) => {
+        let r;
+        try {
+            r = await fetch(url, init);
+        }
+        catch {
+            throw new Error(`Cannot reach the control plane at ${host}. Check "controlPlane" in shipvo.json, then run \`shipvo doctor\`.`);
+        }
+        if (r.status === 401 || r.status === 403)
+            throw new Error(`The control plane at ${host} rejected your publish token (${r.status}). Run \`shipvo login\`, then \`shipvo app create\` for a new token.`);
+        return r;
+    };
     return {
-        async get(k) { const r = await fetch(path(k), { headers: auth }); if (r.status === 401)
-            throw new Error("publish token rejected: run `shipvo app create` for a new one"); return r.ok ? r.text() : null; },
-        async getBytes(k) { const r = await fetch(path(k), { headers: auth }); return r.ok ? new Uint8Array(await r.arrayBuffer()) : null; },
-        async keys(prefix) { const r = await fetch(`${base}?prefix=${encodeURIComponent(prefix)}`, { headers: auth }); return r.ok ? (await r.json()).keys : []; },
+        async get(k) { const r = await call(path(k), { headers: auth }); return r.ok ? r.text() : null; },
+        async getBytes(k) { const r = await call(path(k), { headers: auth }); return r.ok ? new Uint8Array(await r.arrayBuffer()) : null; },
+        async keys(prefix) { const r = await call(`${base}?prefix=${encodeURIComponent(prefix)}`, { headers: auth }); return r.ok ? (await r.json()).keys : []; },
         async put(k, body, type) {
-            const r = await fetch(path(k), { method: "PUT", headers: { ...auth, "content-type": type }, body });
+            const r = await call(path(k), { method: "PUT", headers: { ...auth, "content-type": type }, body });
             if (!r.ok) {
                 let m = "";
                 try {
@@ -75,7 +88,7 @@ export function kv(cfg) {
         if (pt)
             return hostedKv(cfg, pt);
         console.error("Nothing to publish with. Hosted: run `shipvo login`, then `shipvo app create` (or set SHIPVO_PUBLISH_TOKEN). Self-hosted: set CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN and SHIPVO_KV_ID.");
-        process.exit(2);
+        process.exit(1);
     }
     const url = (k) => `https://api.cloudflare.com/client/v4/accounts/${ACC}/storage/kv/namespaces/${NS}/values/${encodeURIComponent(k)}`;
     const auth = { Authorization: `Bearer ${TOKEN}` };

package/dist/doctor.d.ts

@@ -0,0 +1,29 @@
+import { existsSync } from "node:fs";
+type CheckResult = {
+    name: string;
+    ok: boolean;
+    fix: string;
+    note?: string;
+};
+type DoctorDeps = {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    nodeVersion: string;
+    fetchFn: typeof fetch;
+    fileExists: typeof existsSync;
+    readText: (path: string) => string;
+    platform: NodeJS.Platform;
+    fileMode: (path: string) => number | null;
+    /** Port the simulator will use (default 4545). */
+    port: number;
+    /** Path of the Playwright Chromium binary, or null if Playwright is not installed. */
+    chromiumPath: (cwd: string) => string | null;
+    portFree: (port: number) => Promise<boolean>;
+    /** Skip the checks that need the network (control plane reachable and /health). */
+    offline: boolean;
+    /** Skip the simulator checks (Chromium, port) even when package.json has a `sim` script. */
+    skipSim: boolean;
+};
+export declare function runDoctorChecks(overrides?: Partial<DoctorDeps>): Promise<CheckResult[]>;
+export declare function doctor(argv: string[]): Promise<void>;
+export {};

package/dist/doctor.js

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { execSync } from "node:child_process";
+import { portFree } from "./sim.js";
+import { args as parseArgs } from "./config.js";
+import { b64, keyFromSeed } from "./index.js";
+import { parseDeclared } from "./hermes.js";
+const defaultDeps = () => ({
+    cwd: process.cwd(),
+    env: process.env,
+    nodeVersion: process.versions.node,
+    fetchFn: fetch,
+    fileExists: existsSync,
+    readText: (path) => readFileSync(path, "utf8"),
+    platform: process.platform,
+    fileMode: (path) => { try {
+        return statSync(path).mode & 0o777;
+    }
+    catch {
+        return null;
+    } },
+    port: 4545,
+    chromiumPath: playwrightChromiumPath,
+    portFree,
+    offline: false,
+    skipSim: false,
+});
+/** Finds Playwright the way packages/sim/server.mjs does (the app's install, then this package's and @shipvo/sim's, then the global npm root) and asks it where Chromium should be. */
+function playwrightChromiumPath(cwd) {
+    const tries = [
+        () => createRequire(join(cwd, "package.json"))("playwright"),
+        () => createRequire(import.meta.url)("playwright"),
+        () => createRequire(createRequire(import.meta.url).resolve("@shipvo/sim/package.json"))("playwright"),
+        () => createRequire(import.meta.url)(join(execSync("npm root -g", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(), "playwright")),
+    ];
+    for (const get of tries) {
+        try {
+            return get().chromium.executablePath();
+        }
+        catch { }
+    }
+    return null;
+}
+function hasSimScript(deps) {
+    try {
+        const pkg = JSON.parse(deps.readText(join(deps.cwd, "package.json")));
+        return typeof pkg?.scripts?.sim === "string";
+    }
+    catch {
+        return false;
+    }
+}
+const parseMajor = (v) => Number(v.split(".")[0] || 0);
+const pub = (s) => b64(keyFromSeed(s).publicKey);
+function seedFilePath(env, cwd) {
+    if (env.SHIPVO_SIGNING_SEED || env.PURENATIVE_SIGNING_SEED)
+        return null;
+    return env.SHIPVO_SIGNING_SEED_FILE || env.PURENATIVE_SIGNING_SEED_FILE || join(cwd, ".shipvo", "seed.txt");
+}
+function resolveSeed(env, cwd, readText) {
+    const direct = env.SHIPVO_SIGNING_SEED || env.PURENATIVE_SIGNING_SEED;
+    if (direct)
+        return direct;
+    const file = env.SHIPVO_SIGNING_SEED_FILE || env.PURENATIVE_SIGNING_SEED_FILE;
+    if (file) {
+        try {
+            return readText(file).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        return readText(join(cwd, ".shipvo", "seed.txt")).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function loadShipvoConfig(deps) {
+    const path = join(deps.cwd, "shipvo.json");
+    if (!deps.fileExists(path)) {
+        return { cfg: null, parseCheck: { name: "shipvo.json parses", ok: false, fix: "run this in your app root (or create shipvo.json with `shipvo init`)" } };
+    }
+    try {
+        const cfg = JSON.parse(deps.readText(path));
+        return { cfg, parseCheck: { name: "shipvo.json parses", ok: true, fix: "none" } };
+    }
+    catch {
+        return { cfg: null, parseCheck: { name: "shipvo.json parses", ok: false, fix: "fix JSON syntax in shipvo.json" } };
+    }
+}
+export async function runDoctorChecks(overrides = {}) {
+    const deps = { ...defaultDeps(), ...overrides };
+    const results = [];
+    const nodeMajor = parseMajor(deps.nodeVersion);
+    results.push({
+        name: "Node version (>=22)",
+        ok: Number.isInteger(nodeMajor) && nodeMajor >= 22,
+        fix: "use Node 22 or newer (for example: `nvm use 22`)",
+    });
+    const { cfg, parseCheck } = loadShipvoConfig(deps);
+    results.push(parseCheck);
+    const signingOk = (() => {
+        if (!cfg?.publicKey || typeof cfg.publicKey !== "string")
+            return false;
+        const s = resolveSeed(deps.env, deps.cwd, deps.readText);
+        if (!s)
+            return false;
+        try {
+            return pub(s) === cfg.publicKey;
+        }
+        catch {
+            return false;
+        }
+    })();
+    const needCfg = "fix shipvo.json first";
+    results.push({ name: "signing key matches shipvo.json publicKey", ok: signingOk, fix: !cfg ? needCfg : "restore the right seed with `shipvo keys import` (or set SHIPVO_SIGNING_SEED)" });
+    const skipped = "skipped, --offline";
+    let controlPlaneOk = false;
+    let cpFix = "check shipvo.json controlPlane and your network access (5 second timeout)";
+    if (!deps.offline && cfg?.controlPlane && typeof cfg.controlPlane === "string") {
+        try {
+            const res = await deps.fetchFn(cfg.controlPlane.replace(/\/$/, ""), { signal: AbortSignal.timeout(5000) });
+            if (res.status >= 500)
+                cpFix = `the control plane answered HTTP ${res.status}; check its deploy and logs`;
+            else
+                controlPlaneOk = true;
+        }
+        catch { }
+    }
+    if (deps.offline)
+        results.push({ name: "control plane reachable", ok: true, fix: "none", note: skipped });
+    else
+        results.push({ name: "control plane reachable", ok: controlPlaneOk, fix: !cfg ? needCfg : cpFix });
+    const keyName = "signing key file is private";
+    const keyPath = seedFilePath(deps.env, deps.cwd);
+    if (deps.platform === "win32") {
+        results.push({ name: keyName, ok: true, fix: "none", note: "skipped on Windows, file modes do not apply" });
+    }
+    else if (!keyPath) {
+        results.push({ name: keyName, ok: true, fix: "none", note: "skipped, the seed comes from an environment variable" });
+    }
+    else {
+        const mode = deps.fileMode(keyPath);
+        if (mode === null)
+            results.push({ name: keyName, ok: true, fix: "none", note: "skipped, no key file found" });
+        else
+            results.push({ name: keyName, ok: (mode & 0o077) === 0, fix: `run \`chmod 600 ${keyPath}\` (it is mode ${mode.toString(8).padStart(3, "0")})` });
+    }
+    let healthOk = false;
+    let healthFix = "check shipvo.json controlPlane and your network access (5 second timeout)";
+    if (!deps.offline && cfg?.controlPlane && typeof cfg.controlPlane === "string") {
+        try {
+            const res = await deps.fetchFn(cfg.controlPlane.replace(/\/$/, "") + "/health", { signal: AbortSignal.timeout(5000) });
+            if (res.status !== 200)
+                healthFix = `/health answered HTTP ${res.status}, expected 200; check the control plane URL and deploy`;
+            else {
+                try {
+                    await res.json();
+                    healthOk = true;
+                }
+                catch {
+                    healthFix = "/health answered 200 but not JSON; controlPlane may point at the wrong service";
+                }
+            }
+        }
+        catch (e) {
+            healthFix = e instanceof Error && e.name === "TimeoutError" ? "/health did not answer within 5 seconds; check the URL and your network" : healthFix;
+        }
+    }
+    if (deps.offline)
+        results.push({ name: "control plane /health returns JSON", ok: true, fix: "none", note: skipped });
+    else
+        results.push({ name: "control plane /health returns JSON", ok: healthOk, fix: !cfg ? needCfg : healthFix });
+    let hermesOk = true;
+    if (cfg && Object.prototype.hasOwnProperty.call(cfg, "hermesBytecodeVersion")) {
+        try {
+            parseDeclared(cfg.hermesBytecodeVersion); // undefined means "not declared", which passes
+        }
+        catch {
+            hermesOk = false;
+        }
+    }
+    results.push({ name: "hermesBytecodeVersion (if present) is set", ok: hermesOk, fix: "set hermesBytecodeVersion to a positive integer or list (for example 96 or [96, 98])" });
+    // Simulator checks only apply to projects that have a `sim` script.
+    if (!deps.skipSim && hasSimScript(deps)) {
+        const exe = deps.chromiumPath(deps.cwd);
+        results.push({ name: "Playwright Chromium installed", ok: !!exe && deps.fileExists(exe), fix: "npx playwright install chromium" });
+        results.push({ name: `sim port ${deps.port} is free`, ok: await deps.portFree(deps.port), fix: "Stop the other process or pass --port <n>" });
+    }
+    return results;
+}
+export async function doctor(argv) {
+    const a = parseArgs(argv);
+    const port = a.port === undefined ? 4545 : Number(a.port);
+    const offline = argv.includes("--offline");
+    const skipSim = argv.includes("--skip-sim");
+    const stray = argv.some((x, i) => !x.startsWith("--") && argv[i - 1] !== "--port");
+    if (stray || !Number.isInteger(port) || port < 1 || port > 65535) {
+        console.error("Usage: shipvo doctor [--port <n>] [--offline] [--skip-sim]");
+        process.exit(2);
+    }
+    const results = await runDoctorChecks({ port, offline, skipSim });
+    for (const r of results)
+        console.log(`${r.ok ? `PASS ${r.name}${r.note ? ` (${r.note})` : ""}` : `FAIL ${r.name} — fix: ${r.fix}`}`);
+    if (results.some((r) => !r.ok))
+        process.exit(1);
+}

package/dist/help.d.ts

@@ -0,0 +1,8 @@
+export declare const COMMANDS: readonly ["init", "sim", "preview", "publish", "promote", "auto-halt", "rollback", "app", "login", "doctor", "store", "status", "keys", "mcp", "keygen", "pubkey", "hash", "sign-file", "sign-json", "verify-json", "verify"];
+export declare const help = "shipvo <command>\n\nStart\n  init <dir>                  Create a new app wired to Shipvo\n  sim [--port 4545]           Build the app and run it in the simulator\n  sim --watch [--verbose]     Rebuild on file changes and keep serving; --verbose shows full build errors\n  preview [--json]            Publish a public 24-hour preview link (here.now, no account)\n\nShip\n  publish [--bands b0,b1,b2]  Build, sign and publish an over-the-air release\n  publish --dry-run [--out d] Check a release offline: build and sign, write nothing remote\n  promote [--to b1,b2]        Widen a staged release to more bands (same release, new signature)\n  promote --dry-run           Preview a promote, write nothing\n  auto-halt [--threshold 0.2 --min-reports 20 | --off]  Show, turn on or turn off auto-halt\n  rollback --to <release>     Republish an earlier release as a new release\n  rollback --to <n> --dry-run Preview a rollback, write nothing\n  app create | list | delete  Register, list or remove apps on the hosted control plane\n  login                       Sign in with GitHub and get a key for the hosted simulator\n  store details --dry-run     Draft Play Data safety answers and a privacy policy from shipvo.json\n  status [--app id] [--json]  Show how the newest releases are doing on phones\n  doctor [--port <n>]         Check setup before first publish\n  keys                        Show the stored key's status and quota\n  keys export [--out f]       Print or save this app's signing seed, to back it up\n  keys import [seed|--file f] Restore the signing seed on a new machine\n  mcp                         Print the MCP config that agents need\n\nAdvanced\n  keygen [--out seed.txt]     Create an Ed25519 signing key and print the public key\n  pubkey                      Print the public key for SHIPVO_SIGNING_SEED\n  hash <file>                 Print the SHA-256 and size of a file\n  sign-file <file>            Print the Ed25519 signature (base64) of a file\n  sign-json <file.json>       Sign a JSON document and write the signature into it\n  verify <pointer> [public-key-b64]\n                              Check a release pointer (such as one from publish --dry-run)\n  verify-json <file.json> <public-key-b64>\n                              Check the signature of a JSON document\n";
+export declare function distance(a: string, b: string): number;
+/** Closest command within edit distance 2, or undefined. */
+export declare function suggest(input: string): string | undefined;
+export declare function unknownCommand(input: string): string;
+/** What to print when a command throws: the message, not a stack trace. Set SHIPVO_DEBUG=1 for the stack. */
+export declare function failure(e: unknown, debug?: boolean): string;