@shipvo/cli 0.1.4 → 0.1.5

package/dist/run.d.ts

@@ -0,0 +1,86 @@
+import { type Server } from "node:http";
+export type Platform = "android" | "ios";
+export type RunOptions = {
+    platform: Platform;
+    open: boolean;
+    port?: number;
+    native: boolean;
+};
+/** Parses `run` arguments. Throws a plain message for anything it does not know. */
+export declare function parseRunArgs(argv: string[]): RunOptions;
+/** The command `--native` runs. */
+export declare const nativeCommand: (p: Platform) => {
+    cmd: string;
+    args: string[];
+};
+export declare const FRAMES: {
+    readonly android: {
+        readonly width: 412;
+        readonly height: 915;
+        readonly radius: 36;
+        readonly label: "Android";
+        readonly sheet: {
+            readonly title: "Allow access?";
+            readonly allow: "While using the app";
+            readonly deny: "Don't allow";
+        };
+    };
+    readonly ios: {
+        readonly width: 393;
+        readonly height: 852;
+        readonly radius: 55;
+        readonly label: "iOS";
+        readonly sheet: {
+            readonly title: "Would Like to Access";
+            readonly allow: "Allow While Using App";
+            readonly deny: "Don't Allow";
+        };
+    };
+};
+export type RenderFrame = ((o: {
+    skin: "android" | "ios";
+    dark?: boolean;
+    status?: object;
+    screen?: string;
+}) => {
+    width: number;
+    height: number;
+    outerWidth: number;
+    outerHeight: number;
+    html: string;
+    css: string;
+}) & {
+    /** Script that keeps the status bar live from the app's `pn:status` events. Absent in older @shipvo/sim. */
+    statusScript?: (iframeId?: string, skin?: string) => string;
+};
+/** Loads the frame renderer from @shipvo/sim: the app's install first, then the one next to this CLI. */
+export declare function loadFrameRenderer(bases?: string[]): Promise<RenderFrame>;
+/** The page that shows the app in an Android or iOS frame at its real logical size, scaled to fit the window. The phone body comes from @shipvo/sim's renderFrame. */
+export declare function runFramePage(platform: Platform, name: string, render: RenderFrame, dark?: boolean, token?: string): string;
+/** Adds `.shipvo/` to `<dir>/.gitignore` when it is not already ignored. */
+export declare function ensureShipvoIgnored(dir: string): void;
+/**
+ * Serves the frame page at `/` and the web export at `/app/` (and its absolute asset paths at `/`).
+ * Port 0 picks a free port. Resolves once listening.
+ * The agent channel is a WebSocket at `/__shipvo/agent?role=screen|driver&token=...`, loopback only. It relays JSON
+ * messages between the `screen` and the `driver`. With `projectDir`, `.shipvo/run.json` describes the session while it runs.
+ */
+export declare function startRunServer(opts: {
+    dir: string;
+    platform: Platform;
+    name: string;
+    port?: number;
+    projectDir?: string;
+    render?: RenderFrame;
+}): Promise<{
+    server: Server;
+    port: number;
+    token: string;
+    close: () => Promise<void>;
+}>;
+/** Names the module or file a web build failed on, from the build's error output. */
+export declare function describeWebBuildFailure(output: string): string;
+/** Builds the web export with `rebuildInto` from sim.ts (the same build as `shipvo sim`) into `<root>/sim-dist`. */
+export declare function buildWeb(root: string, command?: string): Promise<void>;
+/** Returns the exit code. */
+export declare function run(argv: string[]): Promise<number>;

package/dist/run.js

@@ -0,0 +1,301 @@
+// `shipvo run android|ios`: build the web export with the simulated device, serve it on a local port and
+// open a phone frame page in the default browser. No browser automation. `--native` runs `npx expo run:<platform>`.
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { join, extname, normalize, resolve, sep } from "node:path";
+import { loadConfig } from "./config.js";
+import { AGENT_PATH, hostAllowed, isAgentRole, isLoopback, originAllowed, tokenMatches } from "./run-protocol.js";
+import { bridgeScript } from "./run-bridge.js";
+import { acceptWebSocket } from "./run-ws.js";
+import { portFree, rebuildInto } from "./sim.js";
+/** Parses `run` arguments. Throws a plain message for anything it does not know. */
+export function parseRunArgs(argv) {
+    let platform;
+    let open = true;
+    let port;
+    let native = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "android" || a === "ios")
+            platform = a;
+        else if (a === "--no-open")
+            open = false;
+        else if (a === "--native")
+            native = true;
+        else if (a === "--port") {
+            const v = argv[++i];
+            if (!v || !/^\d+$/.test(v) || Number(v) > 65535)
+                throw new Error(`--port needs a number from 0 to 65535, got "${v ?? ""}".`);
+            port = Number(v);
+        }
+        else
+            throw new Error(`Unknown argument "${a}". Usage: shipvo run android|ios [--no-open] [--port <n>] [--native]`);
+    }
+    if (!platform)
+        throw new Error("Say which phone: shipvo run android or shipvo run ios.");
+    return { platform, open, port, native };
+}
+/** The command `--native` runs. */
+export const nativeCommand = (p) => ({ cmd: "npx", args: ["expo", `run:${p}`] });
+export const FRAMES = {
+    android: { width: 412, height: 915, radius: 36, label: "Android", sheet: { title: "Allow access?", allow: "While using the app", deny: "Don't allow" } },
+    ios: { width: 393, height: 852, radius: 55, label: "iOS", sheet: { title: "Would Like to Access", allow: "Allow While Using App", deny: "Don't Allow" } },
+};
+/** Loads the frame renderer from @shipvo/sim: the app's install first, then the one next to this CLI. */
+export async function loadFrameRenderer(bases = [process.cwd() + "/package.json", import.meta.url]) {
+    let file;
+    for (const base of bases) {
+        try {
+            file = createRequire(base).resolve("@shipvo/sim/frame.mjs");
+            break;
+        }
+        catch { }
+    }
+    if (!file)
+        throw new Error("@shipvo/sim is not installed in this app. Run `npm i -D @shipvo/sim` (or use your package manager).");
+    const mod = await import(pathToFileURL(file).href);
+    const render = (o) => mod.renderFrame(o);
+    if (typeof mod.statusClientScript === "function")
+        render.statusScript = mod.statusClientScript;
+    return render;
+}
+/** The page that shows the app in an Android or iOS frame at its real logical size, scaled to fit the window. The phone body comes from @shipvo/sim's renderFrame. */
+export function runFramePage(platform, name, render, dark = false, token) {
+    const f = FRAMES[platform];
+    const title = name.replace(/[<>&"']/g, "");
+    const sheet = `<div class="sheet" id="sheet" role="dialog" aria-label="${f.label} system sheet" data-part="system-sheet"><div class="box"><p>${f.sheet.title}</p><button type="button" data-act="allow">${f.sheet.allow}</button><button type="button" data-act="deny">${f.sheet.deny}</button></div></div>`;
+    const frame = render({ skin: platform, dark, screen: `<iframe id="app" src="/app/" title="${title}"></iframe>${sheet}` });
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${title} on ${f.label} (simulated)</title>
+<style>
+html,body{margin:0;height:100%;overflow:hidden;background:${dark ? "#15171a" : "#e8eaed"};font:14px system-ui,sans-serif}
+#fit{position:absolute;left:50%;top:50%;transform-origin:center;touch-action:manipulation}
+${frame.css}
+.sheet{position:absolute;inset:0;background:#0007;display:none;align-items:${platform === "ios" ? "center" : "flex-end"};justify-content:center;z-index:5}
+.sheet.open{display:flex}
+.sheet .box{background:#fff;color:#111;width:${platform === "ios" ? "270px" : "100%"};box-sizing:border-box;padding:20px;border-radius:${platform === "ios" ? "14px" : "28px 28px 0 0"};text-align:center}
+.sheet button{display:block;width:100%;margin-top:8px;padding:10px;border:0;border-radius:${platform === "ios" ? "8px" : "20px"};background:#eee;font:inherit;cursor:pointer}
+.sheetbtn{position:fixed;right:12px;top:10px;padding:3px 10px;border-radius:12px;border:0;background:#111;color:#fff;font-size:12px;cursor:pointer}
+.tag{position:fixed;left:12px;top:10px;padding:3px 10px;border-radius:12px;background:#111;color:#fff;font-size:12px}
+</style></head><body>
+<div class="tag" role="status">Simulated ${f.label} (${f.width}x${f.height}). The app's web build on the simulated device.</div>
+<button class="sheetbtn" id="sheetbtn" type="button">Show ${f.label} system sheet</button>
+<div id="fit"><div id="phone" data-platform="${platform}">${frame.html}</div></div>
+<script>
+var sh=document.getElementById("sheet");
+function sheet(on){sh.classList.toggle("open",on)}
+document.getElementById("sheetbtn").onclick=function(){sheet(!sh.classList.contains("open"))};
+sh.onclick=function(e){if(e.target===sh||e.target.getAttribute("data-act"))sheet(false)};
+addEventListener("message",function(e){var d=e.data;if(d&&d.type==="shipvo:system-sheet")sheet(d.open!==false)});
+function fit(){var s=Math.min(1,(innerWidth-24)/${frame.outerWidth},(innerHeight-60)/${frame.outerHeight});var e=document.getElementById("fit");e.style.transform="translate(-50%,-50%) scale("+s+")";e.style.width="${frame.outerWidth}px";e.style.height="${frame.outerHeight}px"}
+addEventListener("resize",fit);fit();
+</script>${render.statusScript ? `<script>${render.statusScript("app", platform).replace(/<\/script/gi, "<\\/script")}</script>` : ""}${token ? `<script src="/__shipvo/bridge.js" data-token="${token}"></script>` : ""}</body></html>`;
+}
+const TYPES = {
+    ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json",
+    ".png": "image/png", ".jpg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml", ".webp": "image/webp", ".ico": "image/x-icon",
+    ".ttf": "font/ttf", ".otf": "font/otf", ".woff": "font/woff", ".woff2": "font/woff2", ".txt": "text/plain; charset=utf-8", ".wasm": "application/wasm",
+};
+/** Adds `.shipvo/` to `<dir>/.gitignore` when it is not already ignored. */
+export function ensureShipvoIgnored(dir) {
+    const path = join(dir, ".gitignore");
+    const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (/^\/?\.shipvo\/?\s*$/m.test(text))
+        return;
+    appendFileSync(path, (text && !text.endsWith("\n") ? "\n" : "") + ".shipvo/\n");
+}
+/**
+ * Serves the frame page at `/` and the web export at `/app/` (and its absolute asset paths at `/`).
+ * Port 0 picks a free port. Resolves once listening.
+ * The agent channel is a WebSocket at `/__shipvo/agent?role=screen|driver&token=...`, loopback only. It relays JSON
+ * messages between the `screen` and the `driver`. With `projectDir`, `.shipvo/run.json` describes the session while it runs.
+ */
+export async function startRunServer(opts) {
+    const root = resolve(opts.dir);
+    const token = randomBytes(24).toString("hex");
+    // The page gets its own credential: random, in memory only, never written to run.json, and valid for `screen` only.
+    const pageToken = randomBytes(24).toString("hex");
+    const render = opts.render ?? await loadFrameRenderer();
+    const pages = { light: runFramePage(opts.platform, opts.name, render, false, pageToken), dark: runFramePage(opts.platform, opts.name, render, true, pageToken) };
+    const bridge = bridgeScript();
+    let boundPort = -1; // set once the server listens; Host and Origin must match it
+    const server = createServer((req, res) => {
+        if (!hostAllowed(req.headers.host, boundPort)) {
+            res.writeHead(403);
+            return void res.end("Forbidden");
+        }
+        let path;
+        try {
+            path = decodeURIComponent((req.url ?? "/").split("?")[0]);
+        }
+        catch {
+            res.writeHead(400);
+            return void res.end("Bad request");
+        }
+        if (path === "/app") {
+            res.writeHead(302, { location: "/app/" });
+            return void res.end();
+        }
+        if (path === "/" || path === "/index.html") {
+            const dark = new URL(req.url ?? "/", "http://x").searchParams.get("dark") === "1";
+            res.writeHead(200, { "content-type": TYPES[".html"] });
+            return void res.end(dark ? pages.dark : pages.light);
+        }
+        if (path === "/__shipvo/bridge.js") {
+            res.writeHead(200, { "content-type": TYPES[".js"], "cache-control": "no-store" });
+            return void res.end(bridge);
+        }
+        let rel = path.startsWith("/app/") ? path.slice(4) : path;
+        if (rel.endsWith("/"))
+            rel += "index.html";
+        const file = normalize(join(root, rel));
+        if (file !== root && !file.startsWith(root + sep)) {
+            res.writeHead(403);
+            return void res.end("Forbidden");
+        }
+        let target = file;
+        if (!existsSync(target) || !statSync(target).isFile()) {
+            // A client-side route inside the frame (for example a reload on /app/settings): serve the app shell.
+            const spa = path.startsWith("/app/") && !extname(path) ? join(root, "index.html") : "";
+            if (!spa || !existsSync(spa)) {
+                res.writeHead(404);
+                return void res.end("Not found");
+            }
+            target = spa;
+        }
+        res.writeHead(200, { "content-type": TYPES[extname(target).toLowerCase()] ?? "application/octet-stream" });
+        res.end(readFileSync(target));
+    });
+    const peers = {};
+    server.on("upgrade", (req, socket) => {
+        const refuse = (line) => socket.end(`HTTP/1.1 ${line}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (url.pathname !== AGENT_PATH)
+            return refuse("404 Not Found");
+        if (!isLoopback(req.socket.remoteAddress))
+            return refuse("403 Forbidden");
+        if (!hostAllowed(req.headers.host, boundPort) || !originAllowed(req.headers.origin, boundPort))
+            return refuse("403 Forbidden");
+        const given = url.searchParams.get("token");
+        const role = url.searchParams.get("role");
+        const ok = tokenMatches(given, token) || (role === "screen" && tokenMatches(given, pageToken));
+        if (!ok)
+            return refuse("401 Unauthorized");
+        if (!isAgentRole(role))
+            return refuse("400 Bad Request");
+        const other = role === "screen" ? "driver" : "screen";
+        const peer = acceptWebSocket(req, socket, (text) => {
+            try {
+                JSON.parse(text);
+            }
+            catch {
+                return;
+            }
+            peers[other]?.send(text);
+        }, () => { if (peers[role] === peer)
+            delete peers[role]; });
+        if (!peer)
+            return;
+        const old = peers[role]; // a reloaded tab or a restarted agent replaces the old connection
+        peers[role] = peer;
+        old?.close();
+    });
+    const infoPath = opts.projectDir ? join(resolve(opts.projectDir), ".shipvo", "run.json") : undefined;
+    const cleanup = () => { if (infoPath)
+        rmSync(infoPath, { force: true }); };
+    return new Promise((ok, fail) => {
+        server.once("error", fail);
+        server.listen(opts.port ?? 0, "127.0.0.1", () => {
+            const port = server.address().port;
+            boundPort = port;
+            if (infoPath) {
+                const info = { port, platform: opts.platform, app: opts.name, token, pid: process.pid };
+                mkdirSync(join(infoPath, ".."), { recursive: true });
+                writeFileSync(infoPath, JSON.stringify(info, null, 2) + "\n", { mode: 0o600 });
+            }
+            ok({ server, port, token, close: () => new Promise((r) => { cleanup(); for (const p of Object.values(peers))
+                    p?.close(); server.close(() => r()); server.closeAllConnections?.(); }) });
+        });
+    });
+}
+/** Names the module or file a web build failed on, from the build's error output. */
+export function describeWebBuildFailure(output) {
+    const m = /Unable to resolve module ['"]?([^'"\s]+)['"]?(?: from ['"]?([^'":\s]+))?/.exec(output)
+        ?? /Module not found: (?:Error: )?Can't resolve '([^']+)'(?: in '([^']+)')?/.exec(output)
+        ?? /Cannot find module ['"]([^'"]+)['"]/.exec(output);
+    if (m)
+        return `The app cannot build for web: ${m[1]} fails to resolve${m[2] ? ` (from ${m[2]})` : ""}. Fix or stub that module for web, or use \`shipvo run <platform> --native\`.`;
+    const f = /(?:SyntaxError|Error)[^\n]*\n?[^\n]*?(\S+\.(?:tsx?|jsx?|json))/.exec(output) ?? /(\S+\.(?:tsx?|jsx?|json))/.exec(output);
+    const last = output.trim().split("\n").slice(-1)[0] ?? "";
+    return `The app cannot build for web${f ? ` (in ${f[1]})` : ""}: ${last || "see the build output above"}. Use \`shipvo run <platform> --native\` to run it natively.`;
+}
+/** Builds the web export with `rebuildInto` from sim.ts (the same build as `shipvo sim`) into `<root>/sim-dist`. */
+export async function buildWeb(root, command) {
+    try {
+        await rebuildInto({ root, command, echo: true });
+    }
+    catch (e) {
+        throw new Error(describeWebBuildFailure(e.output ?? e.message));
+    }
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    const p = spawn(cmd, args, { stdio: "ignore", detached: true });
+    p.on("error", () => console.error(`Could not open a browser. Open ${url} yourself.`));
+    p.unref();
+}
+/** Returns the exit code. */
+export async function run(argv) {
+    let o;
+    try {
+        o = parseRunArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    if (o.native) {
+        const { cmd, args } = nativeCommand(o.platform);
+        console.error(`Running natively: ${cmd} ${args.join(" ")} (not the simulated device)`);
+        return spawnSync(cmd, args, { stdio: "inherit" }).status ?? 1;
+    }
+    let name;
+    try {
+        name = loadConfig().name;
+    }
+    catch (e) {
+        console.error(e.message);
+        return 1;
+    }
+    if (o.port !== undefined && o.port !== 0 && !(await portFree(o.port))) {
+        console.error(`Port ${o.port} is in use. Pass another --port <n>.`);
+        return 1;
+    }
+    const out = join(process.cwd(), "sim-dist");
+    console.error(`Building ${name} for web with the simulated device…`);
+    try {
+        await buildWeb(process.cwd());
+    }
+    catch (e) {
+        console.error(e.message);
+        return 1;
+    }
+    try {
+        ensureShipvoIgnored(process.cwd());
+    }
+    catch { /* read-only project: the session still works */ }
+    const s = await startRunServer({ dir: out, platform: o.platform, name, port: o.port, projectDir: process.cwd() });
+    const url = `http://127.0.0.1:${s.port}/`;
+    console.error(`Simulated ${FRAMES[o.platform].label} phone at ${url}  (Ctrl+C to stop)`);
+    if (o.open)
+        openBrowser(url);
+    await new Promise((done) => { for (const sig of ["SIGINT", "SIGTERM"])
+        process.once(sig, done); });
+    await s.close();
+    return 0;
+}

package/dist/sim.d.ts

@@ -1,5 +1,7 @@
 /** True if nothing is listening on the port (checks by binding, then closing). */
 export declare function portFree(port: number): Promise<boolean>;
+/** Resolves true once something accepts connections on the port, false if `stop` says to give up. */
+export declare function waitListening(port: number, stop: () => boolean): Promise<boolean>;
 /** True if a path (relative to the project) is inside a folder that never triggers a rebuild. */
 export declare const ignoredPath: (rel: string) => boolean;
 /** Turns a build error into a short plain message. Unknown errors keep their first line only. */
@@ -20,9 +22,11 @@ export declare function watchAndRebuild(opts: {
  * Builds into `<root>/.shipvo/sim-next` and swaps it into `<root>/sim-dist` only if the build succeeds.
  * The old build is moved aside first and moved back if the swap fails.
  * `command` is the shell command; it gets the output dir as its last argument.
+ * A failed build rejects with an Error whose `output` property holds the last 4000 characters of stdout and stderr.
  */
 export declare function rebuildInto(opts?: {
     root?: string;
     command?: string;
+    echo?: boolean;
 }): Promise<void>;
 export declare function sim(argv: string[]): Promise<void>;

package/dist/sim.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, renameSync, rmSync, watch } from "node:fs";
 import { join } from "node:path";
 import { createRequire } from "node:module";
 import { createServer, connect } from "node:net";
+import { ensurePlaywright } from "./ensure-playwright.js";
 import { args as parse, loadConfig } from "./config.js";
 /** True if nothing is listening on the port (checks by binding, then closing). */
 export function portFree(port) {
@@ -14,7 +15,7 @@ export function portFree(port) {
     });
 }
 /** Resolves true once something accepts connections on the port, false if `stop` says to give up. */
-function waitListening(port, stop) {
+export function waitListening(port, stop) {
     return new Promise((resolve) => {
         const tryOnce = () => {
             if (stop())
@@ -86,6 +87,7 @@ export function watchAndRebuild(opts) {
  * Builds into `<root>/.shipvo/sim-next` and swaps it into `<root>/sim-dist` only if the build succeeds.
  * The old build is moved aside first and moved back if the swap fails.
  * `command` is the shell command; it gets the output dir as its last argument.
+ * A failed build rejects with an Error whose `output` property holds the last 4000 characters of stdout and stderr.
  */
 export function rebuildInto(opts = {}) {
     const root = opts.root ?? process.cwd();
@@ -94,14 +96,19 @@ export function rebuildInto(opts = {}) {
     return new Promise((resolve, reject) => {
         mkdirSync(join(root, ".shipvo"), { recursive: true });
         rmSync(next, { recursive: true, force: true });
-        const p = spawn(`${command} "${next}"`, { cwd: root, shell: true, env: { ...process.env, PN_SIM: "1" }, stdio: ["ignore", "ignore", "pipe"] });
+        const p = spawn(`${command} "${next}"`, { cwd: root, shell: true, env: { ...process.env, PN_SIM: "1" }, stdio: ["ignore", "pipe", "pipe"] });
         let tail = "";
-        p.stderr.on("data", (d) => { tail = (tail + d).slice(-4000); });
+        // Metro and Expo print resolve errors to either stream, so keep both. `echo` also shows them.
+        for (const [stream, out] of [[p.stdout, process.stdout], [p.stderr, process.stderr]]) {
+            stream.on("data", (d) => { if (opts.echo)
+                out.write(d); tail = (tail + d).slice(-4000); });
+        }
         p.on("error", (e) => { rmSync(next, { recursive: true, force: true }); reject(e); });
         p.on("close", (code) => {
             if (code !== 0) {
                 rmSync(next, { recursive: true, force: true });
-                return reject(new Error(tail.trim().split("\n").slice(-5).join("\n") || `build exited with code ${code}`));
+                const err = new Error(tail.trim().split("\n").slice(-5).join("\n") || `build exited with code ${code}`);
+                return reject(Object.assign(err, { output: tail }));
             }
             let moved = false;
             try {
@@ -138,12 +145,19 @@ export async function sim(argv) {
         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" } });
     }
+    try {
+        ensurePlaywright({ cwd: process.cwd() });
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(2);
+    }
     let server;
     try {
         server = createRequire(process.cwd() + "/package.json").resolve("@shipvo/sim/server.mjs");
     }
     catch {
-        console.error("Install @shipvo/sim (and playwright) in this app: npm i -D @shipvo/sim playwright && npx playwright install chromium");
+        console.error("@shipvo/sim is not installed in this app. Run `npm i -D @shipvo/sim` (or use your package manager).");
         process.exit(2);
     }
     const p = spawn(process.execPath, [server, "--port", port, "--app", cfg.appId, ...(a.dir ? ["--dir", a.dir] : [])], { stdio: "inherit", env: { ...process.env, PN_CONTROL: cfg.controlPlane } });

package/dist/status.d.ts

@@ -8,9 +8,57 @@ type AutoHalt = {
     threshold: number;
     min_reports: number;
 } | null;
+type Halted = {
+    release: number;
+    reports: number;
+    failed: number;
+    threshold: number;
+};
 /** Plain-text table: one row per release, one column per event name, then the two medians. */
 export declare function formatStatus(releases: Row[]): string;
 /** "auto-halt: off" or "auto-halt: on at 20% after 20 reports". */
 export declare function describeAutoHalt(c: AutoHalt | undefined): string;
+export type Next = {
+    command: string;
+    why: string;
+};
+export type StatusJson = {
+    ok: boolean;
+    code: "ok" | "no_project" | "no_signing_key" | "release_halted" | "no_release" | "error";
+    summary: string;
+    data: {
+        project: {
+            kind: string;
+            app_id: string | null;
+        };
+        sim: {
+            running: boolean;
+            port: number;
+        };
+        run_server: {
+            running: boolean;
+            port: number | null;
+        };
+        signing_key: {
+            present: boolean;
+        };
+        pending_release: {
+            newest: number | null;
+            halted: Halted | null;
+            auto_halt: AutoHalt | null;
+        } | null;
+        store_step: {
+            id: string;
+            title: string;
+            state: string;
+        } | null;
+    };
+    next: Next[];
+};
+/** `shipvo status --json`: exit 0 ok, 1 action needed, 2 error. */
+export declare function statusJson(appArg: string | undefined, fetchFn: typeof fetch, dir?: string): Promise<{
+    doc: StatusJson;
+    exit: number;
+}>;
 export declare function status(argv: string[], fetchFn?: typeof fetch): Promise<number>;
 export {};

package/dist/status.js

@@ -1,4 +1,9 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { routeStore } from "@shipvo/store";
 import { args, loadConfig } from "./config.js";
+import { detectProject } from "./agents.js";
+import { portFree } from "./sim.js";
 const ms = (v) => (typeof v === "number" ? String(Math.round(v)) : "-");
 /** Plain-text table: one row per release, one column per event name, then the two medians. */
 export function formatStatus(releases) {
@@ -15,8 +20,100 @@ export function describeAutoHalt(c) {
     const n = c.min_reports ?? 20;
     return `auto-halt: on at ${Math.round(c.threshold * 1000) / 10}% after ${n} report${n === 1 ? "" : "s"}`;
 }
+const alive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} };
+/** Local facts for `status --json`: no network. */
+async function localFacts(dir, simPort = 4545) {
+    const hasKey = !!(process.env.SHIPVO_SIGNING_SEED || process.env.PURENATIVE_SIGNING_SEED || (process.env.SHIPVO_SIGNING_SEED_FILE && existsSync(process.env.SHIPVO_SIGNING_SEED_FILE)) || (process.env.PURENATIVE_SIGNING_SEED_FILE && existsSync(process.env.PURENATIVE_SIGNING_SEED_FILE)) || existsSync(join(dir, ".shipvo", "seed.txt")));
+    let run = { running: false, port: null };
+    try {
+        const r = JSON.parse(readFileSync(join(dir, ".shipvo", "run.json"), "utf8"));
+        if (typeof r.pid === "number" && alive(r.pid))
+            run = { running: true, port: typeof r.port === "number" ? r.port : null };
+    }
+    catch { /* not running */ }
+    let storeStep = null;
+    try {
+        const plan = JSON.parse(readFileSync(join(dir, "store-plan.json"), "utf8"));
+        const r = routeStore(plan.answers);
+        const step = [...r.play.steps, ...r.apple.steps].find((x) => (plan.marks?.[x.id] ?? "todo") !== "done");
+        if (step)
+            storeStep = { id: step.id, title: step.title, state: plan.marks?.[step.id] ?? "todo" };
+    }
+    catch { /* no plan */ }
+    return { hasKey, run, storeStep, sim: { running: !(await portFree(simPort)), port: simPort } };
+}
+/** `shipvo status --json`: exit 0 ok, 1 action needed, 2 error. */
+export async function statusJson(appArg, fetchFn, dir = process.cwd()) {
+    const kind = detectProject(dir);
+    const f = await localFacts(dir);
+    const shared = { sim: f.sim, run_server: f.run, signing_key: { present: f.hasKey }, store_step: f.storeStep };
+    const mk = (code, summary, next, appId, pending, exit) => ({
+        doc: { ok: exit === 0, code, summary, data: { project: { kind, app_id: appId }, ...shared, pending_release: pending }, next }, exit,
+    });
+    if (!existsSync(join(dir, "shipvo.json"))) {
+        return mk("no_project", "No shipvo.json here.", [{ command: kind === "unknown" ? "shipvo init myapp" : "shipvo init .", why: "This folder is not set up for Shipvo yet." }], null, null, 1);
+    }
+    let cfg;
+    try {
+        cfg = loadConfig(dir);
+    }
+    catch (e) {
+        return mk("error", e instanceof Error ? e.message : String(e), [{ command: "shipvo doctor", why: "shipvo.json is missing a field." }], null, null, 2);
+    }
+    const appId = appArg ?? cfg.appId;
+    let data;
+    const baseUrl = cfg.controlPlane.replace(/\/$/, "");
+    try {
+        const r = await fetchFn(`${baseUrl}/t/${encodeURIComponent(appId)}/summary`);
+        if (!r.ok)
+            throw new Error(`HTTP ${r.status}`);
+        data = (await r.json());
+    }
+    catch (e) {
+        return mk("error", `Could not reach the control plane at ${baseUrl} (${e instanceof Error ? e.message : String(e)}).`, [{ command: "shipvo doctor", why: "Check the control plane URL and network." }], appId, null, 2);
+    }
+    const releases = data.releases ?? [];
+    const pending = { newest: releases.length ? Math.max(...releases.map((r) => r.release)) : null, halted: data.halted ?? null, auto_halt: data.auto_halt ?? null };
+    const next = [];
+    let code = "ok", exit = 0;
+    let summary = pending.newest === null ? `No releases with telemetry yet for "${appId}".` : `Newest release ${pending.newest} is reporting for "${appId}".`;
+    if (!f.hasKey) {
+        code = "no_signing_key";
+        exit = 1;
+        summary = "No signing key found.";
+        next.push({ command: "shipvo keygen --out .shipvo/seed.txt", why: "You cannot publish without a signing key." });
+    }
+    if (pending.halted) {
+        code = "release_halted";
+        exit = 1;
+        summary = `Release ${pending.halted.release} is halted: ${pending.halted.failed} of ${pending.halted.reports} devices failed.`;
+        const prev = releases.map((r) => r.release).filter((n) => n < pending.halted.release);
+        const to = prev.length ? String(Math.max(...prev)) : "<release>";
+        next.unshift({ command: `shipvo rollback --to ${to}`, why: "Send devices back to a release that works, or publish a fixed one." });
+    }
+    else if (code === "ok" && pending.newest === null) {
+        code = "no_release";
+        next.push({ command: "shipvo publish --dry-run", why: "Check a first release before you publish it." });
+    }
+    if (!f.sim.running && !f.run.running)
+        next.push({ command: "shipvo sim", why: "Start the simulator to try the app." });
+    if (f.storeStep)
+        next.push({ command: f.storeStep.state === "waiting" ? "shipvo store status" : `shipvo store status --mark ${f.storeStep.id}`, why: `Store step "${f.storeStep.title}" is ${f.storeStep.state === "todo" ? "next" : f.storeStep.state}.` });
+    return mk(code, summary, next, appId, pending, exit);
+}
 export async function status(argv, fetchFn = fetch) {
     const a = args(argv);
+    if (argv.includes("--json")) {
+        const { doc, exit } = await statusJson(a.app && a.app !== "true" ? a.app : undefined, fetchFn);
+        console.log(JSON.stringify(doc));
+        return exit;
+    }
     const cfg = loadConfig();
     const appId = a.app && a.app !== "true" ? a.app : cfg.appId;
     const base = cfg.controlPlane.replace(/\/$/, "");
@@ -32,10 +129,6 @@ export async function status(argv, fetchFn = fetch) {
         console.error(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
         return 1;
     }
-    if (argv.includes("--json")) {
-        console.log(JSON.stringify(data));
-        return 0;
-    }
     const releases = data.releases ?? [];
     // An older control plane has no auto_halt field: say nothing rather than a wrong "off".
     if ("auto_halt" in data)