@shipvo/cli 0.1.5 → 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

@@ -1,3 +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

@@ -2,7 +2,46 @@ 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));
@@ -15,28 +54,47 @@ function templatePath(framework) {
 /** `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 --framework capacitor [--dry-run] [--force]");
+        console.error("Usage: shipvo ci init --check | --framework capacitor [--dry-run] [--force]\n       shipvo ci check");
         return 2;
     }
     const a = args(rest);
-    if (a.framework !== "capacitor") {
+    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 = readFileSync(templatePath("capacitor"), "utf8");
-    const target = resolve(cwd, WORKFLOW_PATH);
+    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 ${WORKFLOW_PATH}${existsSync(target) ? " (file exists; --force needed)" : ""}. Nothing was written.\n`);
+        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(`${WORKFLOW_PATH} already exists. Use --force to overwrite it.`);
+        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

@@ -8,17 +8,22 @@ 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";
@@ -36,6 +41,12 @@ try {
         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;
@@ -66,9 +77,18 @@ try {
         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;
@@ -85,7 +105,9 @@ try {
             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. */
@@ -36,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() {
@@ -94,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.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,
@@ -169,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 {
@@ -177,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";
@@ -192,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 {
@@ -203,6 +207,25 @@ 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));
@@ -216,19 +239,52 @@ export async function runDoctorChecks(overrides = {}) {
     }
     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);
 }

package/dist/ensure-playwright.d.ts

@@ -9,7 +9,11 @@ export interface EnsurePlaywrightDeps {
     log: (line: string) => void;
     /** True when `playwright` resolves from the app. Defaults to the same lookup order as `doctor`. */
     resolves?: (cwd: string) => boolean;
+    /** Keep stdout clean (for `--json`): the notice and the installer's output go to stderr. */
+    quiet?: boolean;
 }
+/** stdio for the installer: stderr for both streams when quiet, so stdout stays clean. */
+export declare function installerStdio(quiet: boolean): "inherit" | ["ignore", 2, 2];
 export declare function detectPackageManager(cwd: string, exists: (path: string) => boolean): PackageManager;
 export declare function installCommand(pm: PackageManager): {
     cmd: string;

package/dist/ensure-playwright.js

@@ -2,6 +2,10 @@ import { execFileSync, execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
+/** stdio for the installer: stderr for both streams when quiet, so stdout stays clean. */
+export function installerStdio(quiet) {
+    return quiet ? ["ignore", 2, 2] : "inherit";
+}
 const LOCKFILES = [
     ["pnpm-lock.yaml", "pnpm"],
     ["yarn.lock", "yarn"],
@@ -44,8 +48,9 @@ export function ensurePlaywright(deps) {
     const { cwd } = deps;
     const env = deps.env ?? process.env;
     const exists = deps.exists ?? existsSync;
-    const run = deps.run ?? ((cmd, args, dir) => { execFileSync(cmd, args, { cwd: dir, stdio: "inherit" }); });
-    const log = deps.log ?? ((line) => console.log(line));
+    const quiet = deps.quiet ?? false;
+    const run = deps.run ?? ((cmd, args, dir) => { execFileSync(cmd, args, { cwd: dir, stdio: installerStdio(quiet) }); });
+    const log = deps.log ?? ((line) => (quiet ? console.error(line) : console.log(line)));
     if ((deps.resolves ?? playwrightResolves)(cwd))
         return;
     const { cmd, args } = installCommand(detectPackageManager(cwd, exists));

package/dist/explore-issues.d.ts

@@ -0,0 +1,12 @@
+import { type Finding, type Skin } from "./explore.js";
+/** A short name for the screen: its first heading, else its first named line, else "unnamed screen". */
+export declare function screenName(tree: string): string;
+export declare function findingToIssue(f: Finding, skin: Skin): {
+    title: string;
+    body: string;
+};
+/** Writes `<n>-<kind>.md` per distinct finding. Returns the files and the `gh issue create` lines. */
+export declare function writeIssues(findings: Finding[], skin: Skin, dir: string): {
+    files: string[];
+    commands: string[];
+};

package/dist/explore-issues.js

@@ -0,0 +1,50 @@
+// `shipvo explore --issues-dir`: one ready-to-file Markdown issue per finding. Pure, so tests need no simulator.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describeStep, PARITY_LIMITS, signature } from "./explore.js";
+/** A short name for the screen: its first heading, else its first named line, else "unnamed screen". */
+export function screenName(tree) {
+    const h = /^\s*- heading "((?:[^"\\]|\\.)*)"/m.exec(tree);
+    if (h) {
+        try {
+            return JSON.parse(`"${h[1]}"`).trim() || "unnamed screen";
+        }
+        catch {
+            return h[1];
+        }
+    }
+    const any = /^\s*- [\w-]+ "((?:[^"\\]|\\.)*)"/m.exec(tree);
+    return any ? any[1] : "unnamed screen";
+}
+export function findingToIssue(f, skin) {
+    const title = `explore: ${f.kind} on ${screenName(f.screen)}`;
+    const body = [
+        f.message, "",
+        "Steps to reproduce:", "",
+        ...f.steps.map((s, i) => `${i + 1}. ${describeStep(s)}`), "",
+        `Platform skin: ${skin}`, "",
+        "Simulator limits:", "",
+        ...PARITY_LIMITS.map((p) => `- ${p}`), "",
+    ].join("\n");
+    return { title, body };
+}
+const quote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** Writes `<n>-<kind>.md` per distinct finding. Returns the files and the `gh issue create` lines. */
+export function writeIssues(findings, skin, dir) {
+    const seen = new Set();
+    const files = [];
+    const commands = [];
+    const unique = findings.filter((f) => { const k = `${f.kind}|${f.message}|${signature(f.screen)}`; if (seen.has(k))
+        return false; seen.add(k); return true; });
+    if (!unique.length)
+        return { files, commands };
+    mkdirSync(dir, { recursive: true });
+    unique.forEach((f, i) => {
+        const { title, body } = findingToIssue(f, skin);
+        const file = join(dir, `${i + 1}-${f.kind}.md`);
+        writeFileSync(file, `${title}\n\n${body}`);
+        files.push(file);
+        commands.push(`gh issue create --title ${quote(title)} --body-file ${quote(file)}`);
+    });
+    return { files, commands };
+}