@shipvo/cli 0.1.4 → 0.1.6

package/dist/ci-compare.js

@@ -0,0 +1,25 @@
+/** Returns null when either report is missing: there is nothing to compare. */
+export function diffReports(base, pr) {
+    if (!base || !pr)
+        return null;
+    const before = new Map();
+    for (const f of base.flows ?? [])
+        before.set(f.name ?? "unnamed flow", f);
+    const out = { regressions: [], fixed: [], stillFailing: [], newFlows: [] };
+    for (const f of pr.flows ?? []) {
+        const old = before.get(f.name ?? "unnamed flow");
+        const failed = f.status === "failed";
+        if (!old) {
+            out.newFlows.push(f);
+            continue;
+        }
+        const wasFailed = old.status === "failed";
+        if (failed && !wasFailed)
+            out.regressions.push(f);
+        else if (!failed && wasFailed)
+            out.fixed.push(f);
+        else if (failed && wasFailed)
+            out.stillFailing.push(f);
+    }
+    return out;
+}

package/dist/ci-shots.d.ts

@@ -0,0 +1,9 @@
+/** Route for a screen name from `changedScreens`. Dynamic screens (`[id]`) and layouts are skipped. */
+export declare function screenRoute(name: string): string | null;
+/** The screens to capture or walk: routable ones only, first four. Shared by `ci shots` and `explore --changed-from`. */
+export declare function routableScreens(screens: string[]): (readonly [string, string])[];
+export type Shoot = (route: string) => Promise<Uint8Array>;
+/** Capture up to four screens. A screen that fails is reported and skipped. Returns the files written. */
+export declare function captureScreens(screens: string[], shoot: Shoot, outDir: string, log?: (s: string) => void): Promise<string[]>;
+/** `shipvo ci shots --changed-from <sha> [--sim url] [--out dir]`. Never fails the check. */
+export declare function shotsCmd(argv: string[]): Promise<number>;

package/dist/ci-shots.js

@@ -0,0 +1,81 @@
+// `shipvo ci shots`: one simulator screenshot per changed screen, written to shipvo-shots/ for the check comment.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { changedFiles, changedScreens } from "./ci-comment.js";
+const MAX = 4;
+/** Route for a screen name from `changedScreens`. Dynamic screens (`[id]`) and layouts are skipped. */
+export function screenRoute(name) {
+    if (/\[|\(|(?:^|\/)_/.test(name) || name === "+not-found")
+        return null;
+    return name === "home" ? "/" : `/${name}`;
+}
+/** The screens to capture or walk: routable ones only, first four. Shared by `ci shots` and `explore --changed-from`. */
+export function routableScreens(screens) {
+    return screens.map((s) => [s, screenRoute(s)]).filter((r) => r[1] !== null).slice(0, MAX);
+}
+/** Capture up to four screens. A screen that fails is reported and skipped. Returns the files written. */
+export async function captureScreens(screens, shoot, outDir, log = console.log) {
+    const written = [];
+    const routes = routableScreens(screens);
+    if (!routes.length)
+        return written;
+    mkdirSync(outDir, { recursive: true });
+    for (const [name, route] of routes) {
+        try {
+            const file = join(outDir, `${name.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "") || "screen"}.png`);
+            writeFileSync(file, await shoot(route));
+            written.push(file);
+        }
+        catch (e) {
+            log(`screenshot of ${name} skipped: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    return written;
+}
+/** `shipvo ci shots --changed-from <sha> [--sim url] [--out dir]`. Never fails the check. */
+export async function shotsCmd(argv) {
+    const val = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : undefined; };
+    const base = val("--changed-from"), sim = (val("--sim") ?? "http://localhost:4545").replace(/\/$/, ""), out = val("--out") ?? "shipvo-shots";
+    if (!base) {
+        console.error("shipvo ci shots: --changed-from <sha> is required");
+        return 2;
+    }
+    let screens = [];
+    try {
+        screens = changedScreens(changedFiles(base));
+    }
+    catch (e) {
+        console.error(`could not read the diff: ${e instanceof Error ? e.message : e}`);
+        return 0;
+    }
+    const post = async (path, body) => {
+        const r = await fetch(sim + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(60000) });
+        if (!r.ok)
+            throw new Error(`simulator ${path} -> ${r.status}`);
+        return (await r.json());
+    };
+    const { loadConfig } = await import("./config.js");
+    let appId;
+    try {
+        appId = loadConfig().appId;
+    }
+    catch (e) {
+        console.error(`could not read shipvo.json: ${e instanceof Error ? e.message : e}`);
+        return 0;
+    }
+    const session = `ci-shots-${Date.now().toString(36)}`;
+    const files = await captureScreens(screens, async (route) => {
+        const open = await post("/session", { session, app: appId, width: 390, height: 844 });
+        if (open.ok === false)
+            throw new Error(`could not open the app: ${open.error ?? "unknown error"}`);
+        const nav = await post("/act", { session, action: "open_url", url: route });
+        if (!nav.ok)
+            throw new Error(`could not open ${route}: ${nav.error ?? "unknown error"}`);
+        const shot = await post("/act", { session, action: "screenshot", format: "png", inline: true });
+        if (!shot.ok || !shot.data)
+            throw new Error(`screenshot failed: ${shot.error ?? "no data"}`);
+        return new Uint8Array(Buffer.from(shot.data, "base64"));
+    }, out, (s) => console.error(s));
+    console.log(`Captured ${files.length} screenshot${files.length === 1 ? "" : "s"} in ${out}/.`);
+    return 0;
+}

package/dist/ci.d.ts

@@ -0,0 +1,11 @@
+export declare const WORKFLOW_PATH: string;
+export declare const CHECK_WORKFLOW_PATH: string;
+/** The Shipvo check workflow. A test asserts this equals `templates/github-action/shipvo-check.yml`. */
+export declare const CHECK_WORKFLOW = "name: Shipvo check\n\non:\n  pull_request:\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  check:\n    runs-on: ubuntu-latest\n    timeout-minutes: 30\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n      - uses: shipvo/shipvo/actions/check@main\n";
+type Run = (argv: string[]) => Promise<number>;
+/** `shipvo ci check`: run `shipvo test`, then `shipvo explore` (so the report exists even when a flow fails).
+ * Fails on a test regression or a crash. Exploration findings alone do not fail it. */
+export declare function check(runTest?: Run, runExplore?: Run, changedFrom?: string): Promise<number>;
+/** `shipvo ci init --framework capacitor [--dry-run] [--force]`. Returns the exit code. */
+export declare function ci(argv: string[], cwd?: string): Promise<number>;
+export {};

package/dist/ci.js

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { args } from "./config.js";
+import { explore } from "./explore.js";
+import { testCmd } from "./test.js";
+import { commentCmd } from "./ci-comment.js";
+import { shotsCmd } from "./ci-shots.js";
+export const WORKFLOW_PATH = join(".github", "workflows", "shipvo-build.yml");
+export const CHECK_WORKFLOW_PATH = join(".github", "workflows", "shipvo-check.yml");
+/** The Shipvo check workflow. A test asserts this equals `templates/github-action/shipvo-check.yml`. */
+export const CHECK_WORKFLOW = `name: Shipvo check
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: shipvo/shipvo/actions/check@main
+`;
+/** `shipvo ci check`: run `shipvo test`, then `shipvo explore` (so the report exists even when a flow fails).
+ * Fails on a test regression or a crash. Exploration findings alone do not fail it. */
+export async function check(runTest = testCmd, runExplore = explore, changedFrom) {
+    const t = await runTest(["--report", "shipvo-report.json"]);
+    let e;
+    try {
+        e = await runExplore(["--sim", "http://localhost:4545", ...(changedFrom ? ["--changed-from", changedFrom] : [])]);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        e = 1;
+    }
+    return t !== 0 ? t : e;
+}
+/** Find the template: next to the built CLI (npm), or in the repo's `templates/` (development). */
+function templatePath(framework) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const rel = join("templates", framework, "github-actions", "build.yml");
+    for (const c of [join(here, rel), join(here, "..", "..", "..", rel)])
+        if (existsSync(c))
+            return c;
+    throw new Error(`template for ${framework} not found`);
+}
+/** `shipvo ci init --framework capacitor [--dry-run] [--force]`. Returns the exit code. */
+export async function ci(argv, cwd = process.cwd()) {
+    const [sub, ...rest] = argv;
+    if (sub === "check") {
+        const i = rest.indexOf("--changed-from");
+        const v = i >= 0 ? rest[i + 1] : undefined;
+        if (i >= 0 && (v === undefined || v.startsWith("-"))) {
+            console.error("shipvo ci check: --changed-from needs a commit sha");
+            return 2;
+        }
+        return check(testCmd, explore, v);
+    }
+    if (sub === "shots")
+        return shotsCmd(rest);
+    if (sub === "comment")
+        return commentCmd(rest);
+    if (sub !== "init") {
+        console.error("Usage: shipvo ci init --check | --framework capacitor [--dry-run] [--force]\n       shipvo ci check");
+        return 2;
+    }
+    const a = args(rest);
+    const isCheck = a.check !== undefined && a.check !== "false";
+    if (!isCheck && a.framework !== "capacitor") {
+        console.error("shipvo ci init: --framework capacitor is the only framework with a template so far");
+        return 2;
+    }
+    const body = isCheck ? CHECK_WORKFLOW : readFileSync(templatePath("capacitor"), "utf8");
+    const path = isCheck ? CHECK_WORKFLOW_PATH : WORKFLOW_PATH;
+    const target = resolve(cwd, path);
+    if (a["dry-run"] !== undefined && a["dry-run"] !== "false") {
+        console.log(`Would write ${path}${existsSync(target) ? " (file exists; --force needed)" : ""}. Nothing was written.\n`);
+        console.log(body);
+        return 0;
+    }
+    if (existsSync(target) && (a.force === undefined || a.force === "false")) {
+        console.error(`${path} already exists. Use --force to overwrite it.`);
+        return 1;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, body);
+    if (isCheck) {
+        console.log(`Wrote ${path}. Commit it and open a pull request.`);
+        return 0;
+    }
+    console.log(`Wrote ${WORKFLOW_PATH}. Add the secrets listed in docs/capacitor.md, then run the "Shipvo build" workflow.`);
+    return 0;
+}

package/dist/cli.js

@@ -7,15 +7,27 @@ import { init } from "./init.js";
 import { publish, rollback } from "./publish.js";
 import { promote } from "./promote.js";
 import { autoHalt } from "./autohalt.js";
+import { explore } from "./explore.js";
+import { lumi } from "./lumi.js";
+import { smoke } from "./smoke.js";
 import { sim } from "./sim.js";
 import { preview } from "./preview.js";
+import { run } from "./run.js";
 import { keys, login, mcp } from "./login.js";
 import { verifyPointer } from "./verify.js";
 import { signingKey } from "./signing.js";
+import { keysJson } from "./keys-json.js";
 import { appCmd } from "./app.js";
 import { status } from "./status.js";
+import { agentsCmd } from "./agents.js";
 import { doctor } from "./doctor.js";
+import { audit } from "./audit.js";
+import { migrate } from "./migrate.js";
+import { approvals } from "./approvals.js";
 import { store } from "./store.js";
+import { ci } from "./ci.js";
+import { easCmd } from "./eas.js";
+import { testCmd } from "./test.js";
 import { failure, help, unknownCommand } from "./help.js";
 const [cmd, ...rest] = process.argv.slice(2);
 try {
@@ -26,6 +38,18 @@ try {
         case "sim":
             await sim(rest);
             break;
+        case "explore":
+            process.exitCode = await explore(rest);
+            break;
+        case "lumi":
+            process.exitCode = await lumi(rest);
+            break;
+        case "smoke":
+            process.exitCode = await smoke(rest);
+            break;
+        case "run":
+            process.exitCode = await run(rest);
+            break;
         case "preview":
             await preview(rest);
             break;
@@ -50,14 +74,40 @@ try {
         case "status":
             process.exitCode = await status(rest);
             break;
+        case "agents":
+            process.exitCode = await agentsCmd(rest);
+            break;
+        case "skills":
+            process.exitCode = rest[0] === "sync" ? await agentsCmd(["skills-sync", ...rest.slice(1)]) : (console.error("Usage: shipvo skills sync [--dry-run] [--json]"), 2);
+            break;
+        case "audit":
+            await audit(rest);
+            break;
+        case "migrate":
+            process.exitCode = await migrate(rest);
+            break;
+        case "approvals":
+            process.exitCode = await approvals(rest);
+            break;
+        case "test":
+            process.exitCode = await testCmd(rest);
+            break;
         case "store":
             await store(rest);
             break;
+        case "ci":
+            process.exitCode = await ci(rest);
+            break;
+        case "eas":
+            process.exitCode = await easCmd(rest);
+            break;
         case "app":
             await appCmd(rest);
             break;
         case "keys":
-            if (rest[0] === "export" || rest[0] === "import")
+            if (rest.includes("--json"))
+                await keysJson(rest);
+            else if (rest[0] === "export" || rest[0] === "import" || rest[0] === "rotate")
                 await signingKey(rest);
             else
                 await keys();

package/dist/config.d.ts

@@ -9,6 +9,8 @@ export type ShipvoConfig = {
     publicKey: string;
     /** Hermes bytecode version(s) the app's shells run. If set, `shipvo publish` refuses bundles that differ. */
     hermesBytecodeVersion?: number | number[];
+    /** Hermes engine build the app's shells run, such as "250829098.0.10". If set, `shipvo publish` refuses to run with another hermes-compiler. */
+    hermesEngine?: string;
     /** 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. */
@@ -21,6 +23,8 @@ export type ShipvoConfig = {
     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;
+    /** Deep links `shipvo explore` opens after the start screen (for example "tide://cart"). Needs an onUrl listener in the app. */
+    routes?: string[];
     /** Marketplace listing (hosted control plane): shown to agents and on shipvo.dev once reviewed. */
     listing?: {
         public?: boolean;
@@ -34,11 +38,22 @@ export type ShipvoConfig = {
     };
 };
 export declare function loadConfig(dir?: string): ShipvoConfig;
+/** Flags that never take a value, so the word after one stays a positional. Add new boolean flags here. */
+export declare const BOOLEAN_FLAGS: ReadonlySet<string>;
 export declare const args: (argv: string[]) => Record<string, string | undefined>;
 /** Signing seed: SHIPVO_SIGNING_SEED (PURENATIVE_SIGNING_SEED still accepted) or a *_FILE path. */
 export declare function seed(): string;
 /** The publish token `shipvo app create` issued: SHIPVO_PUBLISH_TOKEN (CI) or .shipvo/publish-token. */
 export declare function publishToken(): string | null;
+/** True when publish/rollback/promote have somewhere real to read and write: Cloudflare KV or a publish token. */
+export declare function hasStore(): boolean;
+/** A read-only store over the files `shipvo publish --dry-run` wrote. Lets `promote --dry-run` and `rollback --dry-run` run with no login. Writes throw. */
+export declare function offlineKv(dir?: string): {
+    get(k: string): Promise<string | null>;
+    getBytes(k: string): Promise<Uint8Array<ArrayBuffer> | null>;
+    keys(prefix: string): Promise<string[]>;
+    put(k: string, _body: BodyInit, _type: string): Promise<void>;
+};
 /** Where publish/rollback write: your own Cloudflare KV (self-hosted control plane) or the hosted control plane with a publish token. */
 export declare function kv(cfg: ShipvoConfig): {
     get(k: string): Promise<string | null>;

package/dist/config.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
 export function loadConfig(dir = process.cwd()) {
     const p = join(dir, "shipvo.json");
     if (!existsSync(p))
@@ -10,7 +10,9 @@ export function loadConfig(dir = process.cwd()) {
             throw new Error(`shipvo.json: "${k}" is required`);
     return { shellMajor: 1, name: c.appId, ...c };
 }
-const argPairs = (argv) => Object.fromEntries(argv.reduce((a, x, i, all) => (x.startsWith("--") ? [...a, [x.slice(2), all[i + 1] === undefined || all[i + 1].startsWith("--") ? "true" : all[i + 1]]] : a), []));
+/** Flags that never take a value, so the word after one stays a positional. Add new boolean flags here. */
+export const BOOLEAN_FLAGS = new Set(["json", "skip-build", "fail-on-findings", "no-open"]);
+const argPairs = (argv) => Object.fromEntries(argv.reduce((a, x, i, all) => (x.startsWith("--") ? [...a, [x.slice(2), BOOLEAN_FLAGS.has(x.slice(2)) || all[i + 1] === undefined || all[i + 1].startsWith("--") ? "true" : all[i + 1]]] : a), []));
 export const args = (argv) => argPairs(argv);
 /** Signing seed: SHIPVO_SIGNING_SEED (PURENATIVE_SIGNING_SEED still accepted) or a *_FILE path. */
 export function seed() {
@@ -42,31 +44,46 @@ export function publishToken() {
         return null;
     }
 }
+const RETRIES = 2;
 /** Publishing through the hosted control plane: the same get/put/keys, scoped to this app and signed-pointer checked server side. */
 function hostedKv(cfg, token) {
     const base = `${cfg.controlPlane.replace(/\/$/, "")}/apps/${cfg.appId}/kv`;
-    const auth = { Authorization: `Bearer ${token}` };
+    const auth = { Authorization: `Bearer ${token}`, ...(process.env.SHIPVO_ACTOR === "agent" ? { "x-shipvo-actor": "agent" } : {}) };
     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) => {
+    const call = async (url, init, what) => {
         let r;
-        try {
-            r = await fetch(url, init);
+        for (let attempt = 0;; attempt++) {
+            try {
+                r = await fetch(url, init);
+                break;
+            }
+            catch (err) {
+                // Network errors only, never HTTP statuses. Every call here is a GET or a PUT of the same bytes to the same key, so repeating it is safe.
+                if (attempt < RETRIES) {
+                    await new Promise((ok) => setTimeout(ok, 150 * 2 ** attempt));
+                    continue;
+                }
+                const cause = err?.cause?.code ?? err?.code ?? err?.cause?.message ?? err?.message ?? "unknown error";
+                throw new Error(`Cannot reach the control plane at ${host} (${cause}) while ${init.method ?? "GET"} ${what}. Check "controlPlane" in shipvo.json, then run \`shipvo doctor\`.`);
+            }
         }
-        catch {
-            throw new Error(`Cannot reach the control plane at ${host}. Check "controlPlane" in shipvo.json, then run \`shipvo doctor\`.`);
+        if (r.status === 403) { // a typed policy refusal is not a bad token
+            const j = await r.clone().json().catch(() => null);
+            if (j?.code === "policy_refused")
+                throw new Error(`Refused by policy rule ${j.rule}: ${j.reason}`);
         }
         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 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 get(k) { const r = await call(path(k), { headers: auth }, k); return r.ok ? r.text() : null; },
+        async getBytes(k) { const r = await call(path(k), { headers: auth }, k); return r.ok ? new Uint8Array(await r.arrayBuffer()) : null; },
+        async keys(prefix) { const r = await call(`${base}?prefix=${encodeURIComponent(prefix)}`, { headers: auth }, `keys ${prefix}`); return r.ok ? (await r.json()).keys : []; },
         async put(k, body, type) {
-            const r = await call(path(k), { method: "PUT", headers: { ...auth, "content-type": type }, body });
+            const r = await call(path(k), { method: "PUT", headers: { ...auth, "content-type": type }, body }, k);
             if (!r.ok) {
                 let m = "";
                 try {
@@ -79,6 +96,44 @@ function hostedKv(cfg, token) {
         },
     };
 }
+/** True when publish/rollback/promote have somewhere real to read and write: Cloudflare KV or a publish token. */
+export function hasStore() {
+    const NS = process.env.SHIPVO_KV_ID || process.env.PURENATIVE_KV_ID || readConfigKvId();
+    return !!(process.env.CLOUDFLARE_ACCOUNT_ID && process.env.CLOUDFLARE_API_TOKEN && NS) || !!publishToken();
+}
+function readConfigKvId() { try {
+    return loadConfig().kv?.namespaceId;
+}
+catch {
+    return undefined;
+} }
+/** A read-only store over the files `shipvo publish --dry-run` wrote. Lets `promote --dry-run` and `rollback --dry-run` run with no login. Writes throw. */
+export function offlineKv(dir = ".shipvo/dry-run") {
+    const root = resolve(dir);
+    const file = (k) => { const f = resolve(root, k); return f.startsWith(root + sep) ? f : null; };
+    const walk = (d) => readdirSync(d).flatMap((n) => (statSync(join(d, n)).isDirectory() ? walk(join(d, n)) : [join(d, n)]));
+    return {
+        async get(k) { const f = file(k); try {
+            return f ? readFileSync(f, "utf8") : null;
+        }
+        catch {
+            return null;
+        } },
+        async getBytes(k) { const f = file(k); try {
+            return f ? new Uint8Array(readFileSync(f)) : null;
+        }
+        catch {
+            return null;
+        } },
+        async keys(prefix) { try {
+            return walk(root).map((f) => relative(root, f).split(sep).join("/")).filter((k) => k.startsWith(prefix));
+        }
+        catch {
+            return [];
+        } },
+        async put(k, _body, _type) { throw new Error(`offline dry run cannot write ${k}`); },
+    };
+}
 /** Where publish/rollback write: your own Cloudflare KV (self-hosted control plane) or the hosted control plane with a publish token. */
 export function kv(cfg) {
     const ACC = process.env.CLOUDFLARE_ACCOUNT_ID, TOKEN = process.env.CLOUDFLARE_API_TOKEN;

package/dist/doctor.d.ts

@@ -18,6 +18,8 @@ type DoctorDeps = {
     port: number;
     /** Path of the Playwright Chromium binary, or null if Playwright is not installed. */
     chromiumPath: (cwd: string) => string | null;
+    /** Version of the playwright that chromiumPath resolved, or null if unknown. */
+    playwrightVersion: (cwd: string) => string | null;
     portFree: (port: number) => Promise<boolean>;
     /** Skip the checks that need the network (control plane reachable and /health). */
     offline: boolean;

package/dist/doctor.js

@@ -5,7 +5,8 @@ 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";
+import { installedHermesEngine, parseDeclared, parseEngine } from "./hermes.js";
+import { emit, envelope } from "./json-out.js";
 const defaultDeps = () => ({
     cwd: process.cwd(),
     env: process.env,
@@ -22,6 +23,12 @@ const defaultDeps = () => ({
     } },
     port: 4545,
     chromiumPath: playwrightChromiumPath,
+    playwrightVersion: (cwd) => { try {
+        return createRequire(join(cwd, "package.json"))("playwright/package.json").version;
+    }
+    catch {
+        return null;
+    } },
     portFree,
     offline: false,
     skipSim: false,
@@ -42,6 +49,19 @@ function playwrightChromiumPath(cwd) {
     }
     return null;
 }
+/** Where system Chrome or Edge lives. Same places as the simulator's browser resolver (packages/sim/browser-resolver.mjs). */
+function systemBrowserPaths(platform, env) {
+    if (platform === "win32") {
+        const roots = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA].filter(Boolean);
+        return roots.flatMap((r) => [["Chrome", r + "\\Google\\Chrome\\Application\\chrome.exe"], ["Edge", r + "\\Microsoft\\Edge\\Application\\msedge.exe"]]);
+    }
+    if (platform === "darwin")
+        return [["Chrome", "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"], ["Edge", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"]];
+    return [
+        ["Chrome", "/usr/bin/google-chrome"], ["Chrome", "/usr/bin/google-chrome-stable"], ["Chrome", "/opt/google/chrome/chrome"],
+        ["Edge", "/usr/bin/microsoft-edge"], ["Edge", "/usr/bin/microsoft-edge-stable"], ["Edge", "/opt/microsoft/msedge/msedge"],
+    ];
+}
 function hasSimScript(deps) {
     try {
         const pkg = JSON.parse(deps.readText(join(deps.cwd, "package.json")));
@@ -150,6 +170,7 @@ export async function runDoctorChecks(overrides = {}) {
             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 healthNote;
     let healthFix = "check shipvo.json controlPlane and your network access (5 second timeout)";
     if (!deps.offline && cfg?.controlPlane && typeof cfg.controlPlane === "string") {
         try {
@@ -158,8 +179,10 @@ export async function runDoctorChecks(overrides = {}) {
                 healthFix = `/health answered HTTP ${res.status}, expected 200; check the control plane URL and deploy`;
             else {
                 try {
-                    await res.json();
+                    const j = await res.json();
                     healthOk = true;
+                    if (typeof j?.telemetry_dropped_today === "number")
+                        healthNote = `telemetry_dropped_today: ${j.telemetry_dropped_today}${j.telemetry_dropped_today > 0 ? " (D1 refused telemetry writes; see docs/self-hosting.md)" : ""}`;
                 }
                 catch {
                     healthFix = "/health answered 200 but not JSON; controlPlane may point at the wrong service";
@@ -173,7 +196,7 @@ export async function runDoctorChecks(overrides = {}) {
     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 });
+        results.push({ name: "control plane /health returns JSON", ok: healthOk, fix: !cfg ? needCfg : healthFix, ...(healthOk && healthNote ? { note: healthNote } : {}) });
     let hermesOk = true;
     if (cfg && Object.prototype.hasOwnProperty.call(cfg, "hermesBytecodeVersion")) {
         try {
@@ -184,27 +207,84 @@ export async function runDoctorChecks(overrides = {}) {
         }
     }
     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])" });
+    // Engine build: only shown when the project declares one or has a hermes-compiler, so older setups see no new row.
+    const installedEngine = installedHermesEngine(deps.cwd);
+    let declaredEngine, engineBad = false;
+    try {
+        declaredEngine = cfg ? parseEngine(cfg.hermesEngine) : undefined;
+    }
+    catch {
+        engineBad = true;
+    }
+    if (engineBad)
+        results.push({ name: "Hermes engine build", ok: false, fix: "set hermesEngine in shipvo.json to an id like 250829098.0.10" });
+    else if (declaredEngine || installedEngine) {
+        const mismatch = !!declaredEngine && declaredEngine !== installedEngine;
+        results.push({
+            name: "Hermes engine build", ok: !mismatch,
+            fix: installedEngine ? `shipvo.json declares ${declaredEngine} but hermes-compiler is ${installedEngine}; install the declared build or update hermesEngine if the shell changed` : `shipvo.json declares ${declaredEngine} but hermes-compiler was not found; install it or remove hermesEngine`,
+            note: mismatch ? undefined : declaredEngine ? `${installedEngine}, matches hermesEngine` : `${installedEngine}, hermesEngine not declared in shipvo.json`,
+        });
+    }
     // Simulator checks only apply to projects that have a `sim` script.
     if (!deps.skipSim && hasSimScript(deps)) {
+        const system = systemBrowserPaths(deps.platform, deps.env).find(([, p]) => deps.fileExists(p));
         const exe = deps.chromiumPath(deps.cwd);
-        results.push({ name: "Playwright Chromium installed", ok: !!exe && deps.fileExists(exe), fix: "npx playwright install chromium" });
+        const cached = !!exe && deps.fileExists(exe);
+        const noAuto = deps.env.SHIPVO_NO_AUTO_INSTALL === "1";
+        const ok = !!system || cached || !noAuto;
+        const note = system ? `system ${system[0]}` : cached ? "Playwright Chromium" : "none found yet; the first run downloads Chromium once";
+        results.push({ name: "Browser for the simulator", ok, fix: `SHIPVO_NO_AUTO_INSTALL=1 is set and no Chrome, Edge or Playwright Chromium was found; install Chrome or Edge, or run \`npx playwright install chromium\` in the app folder${deps.playwrightVersion(deps.cwd) ? ` (playwright ${deps.playwrightVersion(deps.cwd)})` : ""}. On Linux, if it then fails to start, run \`npx playwright install-deps chromium\``, note });
         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;
 }
+/** The command that fixes a failed check, with the fix text as the reason. */
+function nextFor(r) {
+    const why = `${r.name}: ${r.fix}`;
+    if (r.name === "shipvo.json parses")
+        return { command: r.fix.startsWith("run this") ? "shipvo init ." : "shipvo doctor", why };
+    if (r.name.startsWith("signing key matches"))
+        return { command: "shipvo keys import", why };
+    if (r.name === "signing key file is private")
+        return { command: r.fix.match(/`(chmod [^`]+)`/)?.[1] ?? "shipvo doctor", why };
+    if (r.name.startsWith("sim port")) {
+        const n = Number(r.name.match(/\d+/)?.[0]);
+        return { command: `shipvo doctor --json --port ${n < 65535 ? n + 1 : 4546}`, why: `${why}. Try another port.` };
+    }
+    if (r.name === "Browser for the simulator")
+        return { command: "npx playwright install chromium", why };
+    if (r.name.startsWith("control plane"))
+        return { command: "shipvo doctor --json --offline", why: `${why}. Check everything except the network.` };
+    return { command: "shipvo help", why };
+}
 export async function doctor(argv) {
+    const json = argv.includes("--json");
     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]");
+        const usage = "Usage: shipvo doctor [--port <n>] [--offline] [--skip-sim] [--json]";
+        if (json)
+            emit(envelope("usage", usage, { checks: [] }, [{ command: "shipvo help", why: "See the options for doctor." }], 2));
+        else
+            console.error(usage);
         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))
+    const failed = results.filter((r) => !r.ok);
+    if (json) {
+        const checks = results.map((r) => ({ name: r.name, ok: r.ok, fix: r.ok ? null : r.fix, note: r.note ?? null }));
+        emit(failed.length
+            ? envelope("checks_failed", `${failed.length} of ${results.length} checks failed.`, { checks }, failed.map(nextFor), 1)
+            : envelope("ok", `All ${results.length} checks passed.`, { checks }, [{ command: "shipvo status --json", why: "See what to do next." }], 0));
+    }
+    else {
+        for (const r of results)
+            console.log(`${r.ok ? `PASS ${r.name}${r.note ? ` (${r.note})` : ""}` : `FAIL ${r.name} — fix: ${r.fix}`}`);
+    }
+    if (failed.length)
         process.exit(1);
 }