@shipvo/cli 0.1.3 → 0.1.5

package/dist/ensure-playwright.js

@@ -0,0 +1,64 @@
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+];
+export function detectPackageManager(cwd, exists) {
+    for (const [file, pm] of LOCKFILES)
+        if (exists(join(cwd, file)))
+            return pm;
+    return "npm";
+}
+export function installCommand(pm) {
+    switch (pm) {
+        case "pnpm": return { cmd: "pnpm", args: ["add", "-D", "playwright"] };
+        case "yarn": return { cmd: "yarn", args: ["add", "-D", "playwright"] };
+        case "bun": return { cmd: "bun", args: ["add", "-d", "playwright"] };
+        default: return { cmd: "npm", args: ["install", "--save-dev", "playwright"] };
+    }
+}
+/** Same lookup order as doctor's playwrightChromiumPath: the app, this package, @shipvo/sim, then the global npm root. */
+function playwrightResolves(cwd) {
+    const tries = [
+        () => createRequire(join(cwd, "package.json")).resolve("playwright"),
+        () => createRequire(import.meta.url).resolve("playwright"),
+        () => createRequire(createRequire(import.meta.url).resolve("@shipvo/sim/package.json")).resolve("playwright"),
+        () => createRequire(import.meta.url).resolve(join(execSync("npm root -g", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(), "playwright")),
+    ];
+    for (const t of tries) {
+        try {
+            t();
+            return true;
+        }
+        catch { }
+    }
+    return false;
+}
+/** Installs `playwright` as a dev dependency with the app's package manager when it is missing. */
+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));
+    if ((deps.resolves ?? playwrightResolves)(cwd))
+        return;
+    const { cmd, args } = installCommand(detectPackageManager(cwd, exists));
+    const line = [cmd, ...args].join(" ");
+    if (env.SHIPVO_NO_AUTO_INSTALL === "1") {
+        throw new Error(`playwright is not installed and SHIPVO_NO_AUTO_INSTALL=1 is set. Run \`${line}\` in ${cwd}.`);
+    }
+    log(`playwright is not installed. Running: ${line}`);
+    try {
+        run(cmd, args, cwd);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`\`${line}\` failed: ${msg}`);
+    }
+}

package/dist/explore.d.ts

@@ -0,0 +1,84 @@
+export type Step = {
+    action: "open";
+} | {
+    action: "open_url";
+    url: string;
+} | {
+    action: "tap";
+    role: string;
+    name: string;
+    nth: number;
+} | {
+    action: "back";
+};
+export type Reply = {
+    ok: boolean;
+    screen?: string | null;
+    error?: string;
+    code?: string;
+    delivery?: string;
+    reason?: string;
+};
+/** What the walker needs from a simulator session. */
+export type Driver = {
+    /** Start a fresh phone on the app. */
+    open(): Promise<Reply>;
+    openUrl(url: string): Promise<Reply>;
+    tap(ref: string): Promise<Reply>;
+    back(): Promise<Reply>;
+    /** Uncaught page errors since the last call. */
+    errors(): Promise<string[]>;
+};
+export type Kind = "error" | "not_delivered" | "action_failed" | "dead_end" | "unnamed";
+export type Finding = {
+    kind: Kind;
+    message: string;
+    screen: string;
+    steps: Step[];
+};
+export type Report = {
+    app: string;
+    generatedAt: string;
+    steps: number;
+    screens: number;
+    maxSteps: number;
+    maxDepth: number;
+    stoppedEarly: string | null;
+    error: string | null;
+    findings: Finding[];
+    parityLimits: string[];
+};
+export declare const PARITY_LIMITS: string[];
+type El = {
+    role: string;
+    name: string;
+    ref: string;
+    nth: number;
+};
+/** Actionable elements in a tree, in order. `nth` counts earlier elements with the same role and name. Disabled ones are left out. */
+export declare function elements(tree: string): El[];
+/** The tree without refs, to tell whether two screens are the same. */
+export declare const signature: (tree: string) => string;
+/** Steps in plain lines, for the report. */
+export declare const describeStep: (s: Step) => string;
+export declare function walk(driver: Driver, o?: {
+    routes?: string[];
+    maxDepth?: number;
+    maxSteps?: number;
+    app?: string;
+}): Promise<Report>;
+export declare function renderMarkdown(r: Report): string;
+/** Driver for a running simulator. */
+export declare function simDriver(base: string, app: string, session?: string): Driver;
+/** Use the simulator at `--sim <url>`, or build the app and start one on `--port` (default 4546). `stop` kills the one we started. */
+export declare function startSim(a: Record<string, string | undefined>, cfg: {
+    name: string;
+    appId: string;
+    controlPlane: string;
+}): Promise<{
+    base: string;
+    stop: () => void;
+}>;
+/** Returns the exit code. */
+export declare function explore(argv: string[]): Promise<number>;
+export {};

package/dist/explore.js

@@ -0,0 +1,247 @@
+// `shipvo explore`: a deterministic walker over the simulator's accessibility tree. No LLM call.
+// The walker (`walk`) only needs a `Driver`, so tests run it against a fake app. `explore` wires it to the simulator.
+import { execSync, spawn } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { args as parse, loadConfig } from "./config.js";
+import { portFree, waitListening } from "./sim.js";
+import { ensurePlaywright } from "./ensure-playwright.js";
+export const PARITY_LIMITS = [
+    "The simulator runs the app's web build in headless Chromium. It is not a phone and not the native app.",
+    "Camera, location, biometrics, payments and notifications are simulated. Native crashes and native-only bugs cannot show up here.",
+    "The walker only taps. It does not type, scroll or swipe, so content below the fold and rails are only seen if on screen.",
+    "Layout, speed and memory are not measured.",
+    "See docs/parity-results.md for what was measured against Android emulators and the iOS Simulator.",
+];
+const ACTIONABLE = new Set(["button", "link", "tab", "checkbox", "switch", "radio", "menuitem"]);
+const unquote = (raw) => { const q = /^(\s*- )'(.*)'(:.*)?$/.exec(raw); return q ? q[1] + q[2].replace(/''/g, "'") + (q[3] ?? "") : raw; };
+/** Actionable elements in a tree, in order. `nth` counts earlier elements with the same role and name. Disabled ones are left out. */
+export function elements(tree) {
+    const out = [];
+    const seen = new Map();
+    for (const raw of tree.split("\n")) {
+        const l = unquote(raw);
+        const m = /^\s*- ([\w-]+)(?: ("(?:[^"\\]|\\.)*"))?[^\n]*?\[ref=(\w+)\]/.exec(l);
+        if (!m || !ACTIONABLE.has(m[1]) || /\[disabled\]/.test(l))
+            continue;
+        let name = "";
+        try {
+            name = m[2] ? JSON.parse(m[2]).trim() : "";
+        }
+        catch {
+            name = m[2].slice(1, -1).trim();
+        }
+        const key = `${m[1]}|${name}`;
+        const nth = seen.get(key) ?? 0;
+        seen.set(key, nth + 1);
+        out.push({ role: m[1], name, ref: m[3], nth });
+    }
+    return out;
+}
+/** The tree without refs, to tell whether two screens are the same. */
+export const signature = (tree) => tree.replace(/\s*\[ref=\w+\]/g, "");
+const redScreen = (tree) => /Uncaught (\w*Error)|Unhandled Runtime Error|Application error|Something went wrong/i.exec(tree)?.[0];
+// Accepts "close" too, but the sim `back` action only clicks a button named exactly "Back"; the replay fallback covers the rest.
+const hasBack = (els) => els.some((e) => /^(back|go back|close)$/i.test(e.name));
+const label = (e) => `${e.role} "${e.name}"`;
+/** Steps in plain lines, for the report. */
+export const describeStep = (s) => s.action === "open" ? "open the app" : s.action === "open_url" ? `open_url ${s.url}` : s.action === "tap" ? `tap ${label(s)}${s.nth ? ` (number ${s.nth + 1} with that name)` : ""}` : "back";
+export async function walk(driver, o = {}) {
+    const maxDepth = o.maxDepth ?? 3, maxSteps = o.maxSteps ?? 100;
+    const findings = [];
+    const seenFinding = new Set();
+    const seenScreens = new Set();
+    let steps = 0;
+    let stopped = null;
+    let cut = 0;
+    const add = (f) => { const k = `${f.kind}|${f.message}|${signature(f.screen)}`; if (!seenFinding.has(k)) {
+        seenFinding.add(k);
+        findings.push(f);
+    } };
+    const need = (r, what) => { if (!r.ok || r.screen == null)
+        throw new Error(`explore: ${what} failed: ${r.error ?? "no screen"}`); return r.screen; };
+    /** Put the phone back on the screen reached by `path`. Replays are not counted as steps. */
+    async function replay(path) {
+        let screen = "";
+        for (const s of path) {
+            const r = s.action === "open" ? await driver.open() : s.action === "open_url" ? await driver.openUrl(s.url) : s.action === "back" ? await driver.back()
+                : await driver.tap(find(screen, s)?.ref ?? "missing");
+            screen = need(r, `replaying "${describeStep(s)}"`);
+        }
+        // Errors raised while replaying are drained here. On a later replay they would repeat an earlier finding.
+        // The caller of the first replay of a start path keeps them.
+        return { screen, errors: await driver.errors() };
+    }
+    const find = (tree, s) => elements(tree).find((e) => e.role === s.role && e.name === s.name && e.nth === s.nth);
+    async function checkErrors(screen, path) {
+        for (const e of await driver.errors())
+            add({ kind: "error", message: `Uncaught error: ${e}`, screen, steps: path });
+        const red = redScreen(screen);
+        if (red)
+            add({ kind: "error", message: `Red screen: the screen shows "${red}"`, screen, steps: path });
+    }
+    async function visit(screen, path, depth) {
+        const sig = signature(screen);
+        if (seenScreens.has(sig))
+            return;
+        seenScreens.add(sig);
+        await checkErrors(screen, path);
+        const els = elements(screen);
+        if (!els.length)
+            add({ kind: "dead_end", message: "Dead end: the screen has no actionable element", screen, steps: path });
+        for (const e of els)
+            if (!e.name)
+                add({ kind: "unnamed", message: `Unnamed ${e.role}: it has no accessible name`, screen, steps: path });
+        let current = screen;
+        for (const e of els) {
+            if (!e.name || /^(back|go back)$/i.test(e.name))
+                continue;
+            if (steps >= maxSteps) {
+                stopped ??= `max-steps (${maxSteps}) reached`;
+                return;
+            }
+            const target = find(current, e);
+            if (!target) {
+                current = (await replay(path)).screen;
+                if (!find(current, e))
+                    continue;
+            }
+            const step = { action: "tap", role: e.role, name: e.name, nth: e.nth };
+            const here = [...path, step];
+            steps++;
+            const r = await driver.tap(find(current, e).ref);
+            if (r.delivery === "not_delivered")
+                add({ kind: "not_delivered", message: `Not delivered (${r.reason ?? "unknown reason"}): ${r.error ?? "the app did not receive the tap"}`, screen: current, steps: here });
+            else if (!r.ok)
+                add({ kind: "action_failed", message: `Action failed${r.code ? ` [${r.code}]` : ""}: ${r.error ?? "unknown"}`, screen: current, steps: here });
+            const after = r.screen ?? current;
+            await checkErrors(after, here);
+            const crashed = !r.ok || r.screen == null || !!redScreen(after);
+            const next = signature(after);
+            if (!crashed && next !== signature(current) && !seenScreens.has(next)) {
+                if (depth >= maxDepth) {
+                    cut++;
+                    seenScreens.add(next);
+                }
+                else {
+                    await visit(after, here, depth + 1);
+                    if (steps >= maxSteps && stopped)
+                        return;
+                }
+            }
+            // Back to this screen: Back button first, a full replay if that does not land here.
+            if (next !== signature(current) || crashed) {
+                let b;
+                if (!crashed && hasBack(elements(after)))
+                    b = await driver.back();
+                current = b?.ok && b.screen != null && signature(b.screen) === sig ? b.screen : (await replay(path)).screen;
+            }
+            else
+                current = after;
+        }
+    }
+    const starts = [[{ action: "open" }], ...(o.routes ?? []).map((url) => [{ action: "open" }, { action: "open_url", url }])];
+    let error = null;
+    try {
+        for (const path of starts) {
+            if (stopped)
+                break;
+            const { screen, errors } = await replay(path);
+            // The first replay of a start path is the only time load-time errors are seen.
+            for (const e of errors)
+                add({ kind: "error", message: `Uncaught error: ${e}`, screen, steps: path });
+            await visit(screen, path, 1);
+        }
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+        stopped = `the walk failed: ${error}`;
+    }
+    if (!stopped && cut)
+        stopped = `max-depth (${maxDepth}) reached: ${cut} screen${cut === 1 ? "" : "s"} were not walked`;
+    return { app: o.app ?? "", generatedAt: new Date().toISOString(), steps, screens: seenScreens.size, maxSteps, maxDepth, stoppedEarly: stopped, error, findings, parityLimits: PARITY_LIMITS };
+}
+export function renderMarkdown(r) {
+    const L = [`# Explore report: ${r.app}`, "", "## Simulator limits", "", ...r.parityLimits.map((p) => `- ${p}`), "", "## Run", "",
+        `- Steps taken: ${r.steps} (limit ${r.maxSteps}). Screens seen: ${r.screens}. Depth limit: ${r.maxDepth}.`,
+        `- ${r.stoppedEarly ? `Stopped early: ${r.stoppedEarly}.` : "Stopped early: no. The walk ended because every reachable screen within the limits was visited."}`, ""];
+    L.push("## Findings", "");
+    if (!r.findings.length)
+        L.push(`No findings in ${r.steps} steps.`, "");
+    r.findings.forEach((f, i) => {
+        L.push(`### ${i + 1}. ${f.message}`, "", "Steps to reproduce:", "", ...f.steps.map((s, j) => `${j + 1}. ${describeStep(s)}`), "", "Typed steps:", "", "```json", JSON.stringify(f.steps), "```", "");
+    });
+    return L.join("\n");
+}
+/** Driver for a running simulator. */
+export function simDriver(base, app, session = `explore-${Date.now().toString(36)}`) {
+    const post = async (path, body) => {
+        const r = await fetch(base.replace(/\/$/, "") + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(30000) });
+        if (!r.ok)
+            throw new Error(`simulator ${path} -> ${r.status}`);
+        return (await r.json());
+    };
+    const act = (body) => post("/act", { session, ...body });
+    return {
+        open: () => post("/session", { session, app }),
+        openUrl: (url) => act({ action: "open_url", url }),
+        tap: (ref) => act({ action: "tap", ref }),
+        back: () => act({ action: "back" }),
+        errors: async () => (await act({ action: "errors" })).errors ?? [],
+    };
+}
+/** Use the simulator at `--sim <url>`, or build the app and start one on `--port` (default 4546). `stop` kills the one we started. */
+export async function startSim(a, cfg) {
+    let base = a.sim;
+    let child;
+    if (!base) {
+        const port = a.port || "4546";
+        if (!(await portFree(Number(port))))
+            throw new Error(`Port ${port} is in use. Stop the other simulator, pass --port <n>, or pass --sim <url> to use one that is running.`);
+        if (a["skip-build"] !== "true" || !existsSync("sim-dist/index.html")) {
+            console.error(`Building ${cfg.name} for the simulator…`);
+            execSync("PN_SIM=1 npx expo export --platform web --output-dir sim-dist --clear", { stdio: "inherit", env: { ...process.env, PN_SIM: "1" } });
+        }
+        ensurePlaywright({ cwd: process.cwd() });
+        let server;
+        try {
+            server = createRequire(process.cwd() + "/package.json").resolve("@shipvo/sim/server.mjs");
+        }
+        catch {
+            throw new Error("@shipvo/sim is not installed in this app. Run `npm i -D @shipvo/sim` (or use your package manager).");
+        }
+        let exited = false;
+        child = spawn(process.execPath, [server, "--port", port, "--app", cfg.appId], { stdio: ["ignore", "ignore", "inherit"], env: { ...process.env, PN_CONTROL: cfg.controlPlane } });
+        child.on("exit", () => { exited = true; });
+        if (!(await waitListening(Number(port), () => exited)))
+            throw new Error("the simulator exited before it was ready");
+        base = `http://localhost:${port}`;
+    }
+    return { base, stop: () => { child?.kill(); } };
+}
+/** Returns the exit code. */
+export async function explore(argv) {
+    const a = parse(argv);
+    const cfg = loadConfig();
+    const num = (k, d) => { if (a[k] === undefined)
+        return d; const n = Number(a[k]); if (!Number.isInteger(n) || n < 1)
+        throw new Error(`--${k} must be a whole number of 1 or more`); return n; };
+    const maxDepth = num("max-depth", 3), maxSteps = num("max-steps", 100);
+    const sim = await startSim(a, cfg);
+    const base = sim.base;
+    try {
+        const report = await walk(simDriver(base, cfg.appId), { routes: cfg.routes, maxDepth, maxSteps, app: cfg.appId });
+        const out = a.out ?? "explore-report";
+        writeFileSync(`${out}.md`, renderMarkdown(report));
+        writeFileSync(`${out}.json`, JSON.stringify(report, null, 2) + "\n");
+        console.log(`${report.findings.length ? `${report.findings.length} finding${report.findings.length === 1 ? "" : "s"}` : `No findings in ${report.steps} steps`}${report.stoppedEarly ? `. Stopped early: ${report.stoppedEarly}` : ""}. Wrote ${out}.md and ${out}.json`);
+        if (report.error) {
+            console.error(report.error);
+            return 1;
+        }
+        return report.findings.length && a["fail-on-findings"] === "true" ? 1 : 0;
+    }
+    finally {
+        sim.stop();
+    }
+}

package/dist/help.d.ts

@@ -1,6 +1,8 @@
-export declare const COMMANDS: readonly ["init", "sim", "publish", "rollback", "app", "login", "doctor", "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\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  rollback --to <release>     Republish an earlier release as a new release\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  doctor                      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 const COMMANDS: readonly ["init", "sim", "run", "explore", "preview", "publish", "promote", "auto-halt", "rollback", "app", "eas", "login", "doctor", "store", "ci", "status", "agents", "audit", "test", "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                              First run installs playwright and, if no Chrome or Edge is found, downloads Chromium once.\n                              Set SHIPVO_NO_AUTO_INSTALL=1 to turn the automatic installs off.\n  run android|ios [--no-open] [--port n]  Open the app in a phone frame in your browser (no Playwright)\n  run android|ios --native    Run on an emulator or simulator with npx expo run:android / run:ios\n  explore [--max-depth 3] [--max-steps 100] [--fail-on-findings]  Walk the app in the simulator, write explore-report.md and .json\n  preview [--json]            Publish a public 24-hour preview link (here.now, no account)\n\nShip\n  publish [--bands b0,b1,b2] [--release N]  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  promote --report <file>     Refuse to widen when the test report has a failing flow for this release\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  eas setup [--dry-run] [--run]  Make a Capacitor repo ready for eas build and submit (your own Expo account)\n  eas build [args]            Link the iOS scheme, then run eas build\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  store setup [--company yes|no] [--android-now] [--play-account-before-2023-11-13]\n                              Pick the store accounts to open and write store-plan.json\n  store screenshots [--out dir] [--sim url]\n                              Render each route at store sizes (fast mode: simulator, not the native UI)\n  store testers [--package id] [--track alpha] [--play-key file] [--json]\n                              Steps to get your 12 testers; add the Shipvo Testers group to the closed track\n  store status [--mark <step> [--as waiting|done]]\n                              Show each store's steps and what to do next\n  ci init --framework capacitor [--dry-run] [--force]\n                              Write .github/workflows/shipvo-build.yml (signed Android and iOS builds)\n  status [--app id] [--json]  Show how releases do; --json lists what to do next (exit 0 ok, 1 action needed, 2 error)\n  agents setup [--dry-run] [--json]  Write AGENTS.md section and .mcp.json for AI agents\n  audit <app> [--format json|csv] [--limit n]  Export the audit log to stdout\n  test [files] [--repair [--write]] [--report <file> [--release <id>]]  Run tests/*.steps; --repair shows a diff for broken steps, --write saves it; --report writes JSON results keyed by commit and release\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;

package/dist/help.js

@@ -1,5 +1,5 @@
 export const COMMANDS = [
-    "init", "sim", "publish", "rollback", "app", "login", "doctor", "keys", "mcp",
+    "init", "sim", "run", "explore", "preview", "publish", "promote", "auto-halt", "rollback", "app", "eas", "login", "doctor", "store", "ci", "status", "agents", "audit", "test", "keys", "mcp",
     "keygen", "pubkey", "hash", "sign-file", "sign-json", "verify-json", "verify",
 ];
 export const help = `shipvo <command>
@@ -7,14 +7,43 @@ export const help = `shipvo <command>
 Start
   init <dir>                  Create a new app wired to Shipvo
   sim [--port 4545]           Build the app and run it in the simulator
+  sim --watch [--verbose]     Rebuild on file changes and keep serving; --verbose shows full build errors
+                              First run installs playwright and, if no Chrome or Edge is found, downloads Chromium once.
+                              Set SHIPVO_NO_AUTO_INSTALL=1 to turn the automatic installs off.
+  run android|ios [--no-open] [--port n]  Open the app in a phone frame in your browser (no Playwright)
+  run android|ios --native    Run on an emulator or simulator with npx expo run:android / run:ios
+  explore [--max-depth 3] [--max-steps 100] [--fail-on-findings]  Walk the app in the simulator, write explore-report.md and .json
+  preview [--json]            Publish a public 24-hour preview link (here.now, no account)
 
 Ship
-  publish [--bands b0,b1,b2]  Build, sign and publish an over-the-air release
+  publish [--bands b0,b1,b2] [--release N]  Build, sign and publish an over-the-air release
   publish --dry-run [--out d] Check a release offline: build and sign, write nothing remote
+  promote [--to b1,b2]        Widen a staged release to more bands (same release, new signature)
+  promote --dry-run           Preview a promote, write nothing
+  promote --report <file>     Refuse to widen when the test report has a failing flow for this release
+  auto-halt [--threshold 0.2 --min-reports 20 | --off]  Show, turn on or turn off auto-halt
   rollback --to <release>     Republish an earlier release as a new release
+  rollback --to <n> --dry-run Preview a rollback, write nothing
   app create | list | delete  Register, list or remove apps on the hosted control plane
+  eas setup [--dry-run] [--run]  Make a Capacitor repo ready for eas build and submit (your own Expo account)
+  eas build [args]            Link the iOS scheme, then run eas build
   login                       Sign in with GitHub and get a key for the hosted simulator
-  doctor                      Check setup before first publish
+  store details --dry-run     Draft Play Data safety answers and a privacy policy from shipvo.json
+  store setup [--company yes|no] [--android-now] [--play-account-before-2023-11-13]
+                              Pick the store accounts to open and write store-plan.json
+  store screenshots [--out dir] [--sim url]
+                              Render each route at store sizes (fast mode: simulator, not the native UI)
+  store testers [--package id] [--track alpha] [--play-key file] [--json]
+                              Steps to get your 12 testers; add the Shipvo Testers group to the closed track
+  store status [--mark <step> [--as waiting|done]]
+                              Show each store's steps and what to do next
+  ci init --framework capacitor [--dry-run] [--force]
+                              Write .github/workflows/shipvo-build.yml (signed Android and iOS builds)
+  status [--app id] [--json]  Show how releases do; --json lists what to do next (exit 0 ok, 1 action needed, 2 error)
+  agents setup [--dry-run] [--json]  Write AGENTS.md section and .mcp.json for AI agents
+  audit <app> [--format json|csv] [--limit n]  Export the audit log to stdout
+  test [files] [--repair [--write]] [--report <file> [--release <id>]]  Run tests/*.steps; --repair shows a diff for broken steps, --write saves it; --report writes JSON results keyed by commit and release
+  doctor [--port <n>]         Check setup before first publish
   keys                        Show the stored key's status and quota
   keys export [--out f]       Print or save this app's signing seed, to back it up
   keys import [seed|--file f] Restore the signing seed on a new machine
@@ -59,3 +88,10 @@ export function unknownCommand(input) {
     const s = suggest(input);
     return `shipvo: '${input}' is not a command.${s ? ` Did you mean '${s}'?` : ""}\nRun 'shipvo --help' to see all commands.\n`;
 }
+/** What to print when a command throws: the message, not a stack trace. Set SHIPVO_DEBUG=1 for the stack. */
+export function failure(e, debug = !!process.env.SHIPVO_DEBUG) {
+    if (debug && e instanceof Error && e.stack)
+        return e.stack;
+    const m = e instanceof Error ? e.message : String(e);
+    return `shipvo: ${m}\nRun 'shipvo doctor' to check your setup, or set SHIPVO_DEBUG=1 to see the full error.\n`;
+}