@shipvo/cli 0.1.2 → 0.1.4

package/dist/publish.js

@@ -1,10 +1,13 @@
 // `shipvo publish`: build the Hermes bundle, sign a release pointer, publish bundle + patches + the agent-facing web
 // artifact to the control plane. `shipvo rollback --to N`: republish an earlier bundle as a new release.
 import { execSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { sha256Hex, signBytes } from "./index.js";
+import { checkBundle, parseDeclared } from "./hermes.js";
+import { requiredNativeModules } from "./native.js";
+import { checkPublishPolicy } from "./policy.js";
 import { args as parse, kv as kvFor, loadConfig, seed } from "./config.js";
 const MIME = { ".html": "text/html", ".js": "text/javascript", ".json": "application/json", ".css": "text/css", ".ico": "image/x-icon", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".ttf": "font/ttf", ".svg": "image/svg+xml" };
 const walk = (d) => readdirSync(d).flatMap((f) => (statSync(join(d, f)).isDirectory() ? walk(join(d, f)) : [join(d, f)]));
@@ -33,33 +36,123 @@ const platformsOf = (a) => {
         return [p];
     throw new Error(`--platform must be android, ios or all (got "${a.platform}")`);
 };
+/** Unknown flags are errors: a typo like --dryrun must not fall through to a real publish. */
+function checkFlags(argv, known) {
+    const bad = argv.filter((x) => x.startsWith("--") && !known.includes(x.slice(2)));
+    if (bad.length) {
+        const eq = bad.find((x) => x.includes("="));
+        const hint = eq ? ` Write "${eq.replace("=", " ")}" (a space, not =).` : "";
+        throw new Error(`Unknown flag ${bad.join(", ")}.${hint} Known flags: ${known.map((k) => "--" + k).join(" ")}`);
+    }
+}
+/** An on/off flag: bare or "true" is on, "false" is off. Anything else is an error, so a typo never flips it silently. */
+function switchFlag(a, name) {
+    const v = a[name];
+    if (v === undefined || v === "false")
+        return false;
+    if (v === "true")
+        return true;
+    throw new Error(`--${name} is an on/off flag: use --${name}, --${name} true or --${name} false (got "${v}")`);
+}
+/** A store that only writes files under `dir` (key `p/app/1/b0` becomes `dir/p/app/1/b0`). It reads back only what this run wrote (kept in memory), never old files, so the iOS pass can find the web artifact and a dry run never needs a control plane. */
+function localKv(dir) {
+    const root = resolve(dir);
+    const mem = new Map();
+    const enc = new TextEncoder();
+    return {
+        async get(k) { const v = mem.get(k); return v ? new TextDecoder().decode(v) : null; },
+        async getBytes(k) { return mem.get(k) ?? null; },
+        async keys(prefix) { return [...mem.keys()].filter((k) => k.startsWith(prefix)); },
+        async put(k, body, _type) {
+            const f = resolve(root, k);
+            if (!f.startsWith(root + "/"))
+                throw new Error(`refusing to write outside ${dir}: ${k}`);
+            const bytes = typeof body === "string" ? enc.encode(body) : new Uint8Array(body);
+            mkdirSync(dirname(f), { recursive: true });
+            writeFileSync(f, bytes);
+            mem.set(k, bytes);
+        },
+    };
+}
+const PUBLISH_FLAGS = ["bands", "platform", "release", "min-shell", "hermes-bytecode-version", "max-bases", "skip-export", "skip-web", "dry-run", "out"];
+export const PUBLISH_HELP = `Usage: shipvo publish [flags]
+
+Build, sign and publish an over-the-air release.
+
+Flags (write a value after a space, not =; on/off flags can be bare, or true/false):
+  --bands b0,b1,b2             Cohorts to publish to (default b0,b1,b2)
+  --platform android|ios|all   Platform to publish (default android)
+  --release N                  Release number (default: the next one)
+  --min-shell X.Y.Z            Oldest app shell that can run this release (default: version in app.json)
+  --hermes-bytecode-version V  Refuse bundles built for another Hermes version, for example 96 or 96,98
+  --max-bases N                How many older releases to build patches from (default 6)
+  --skip-export               Reuse the last build in dist-ota/
+  --skip-web                  Do not publish the web copy for the simulator
+  --dry-run                    Build and sign, write files locally, send nothing
+  --out <dir>                  Where --dry-run writes files (default .shipvo/dry-run)
+  --help                       Show this help
+`;
 export async function publish(argv) {
-    const a = parse(argv), cfg = loadConfig(), SEED = seed(), kv = kvFor(cfg);
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(PUBLISH_HELP);
+        return;
+    }
+    checkFlags(argv, PUBLISH_FLAGS);
+    const a = parse(argv), cfg = loadConfig(), SEED = seed();
+    const dry = switchFlag(a, "dry-run"), skipExport = switchFlag(a, "skip-export"), skipWeb = switchFlag(a, "skip-web");
+    if (a.out !== undefined && !dry)
+        throw new Error("--out only works with --dry-run");
+    if (a.out === "true")
+        throw new Error("--out needs a directory: pass --out <dir>");
+    const outDir = a.out || ".shipvo/dry-run";
+    const kv = dry ? localKv(outDir) : kvFor(cfg);
     const APP = cfg.appId, MAJOR = cfg.shellMajor;
     const MIN_SHELL = a["min-shell"] || JSON.parse(readFileSync("app.json", "utf8")).expo.version; // a bundle needs the shell it was built against
+    if (a["hermes-bytecode-version"] === "true")
+        throw new Error("--hermes-bytecode-version needs a value: pass a value like 96 (or 96,98)");
+    const declaredHermes = parseDeclared(a["hermes-bytecode-version"] ?? cfg.hermesBytecodeVersion);
+    const skippedNative = [];
+    const nativeModules = requiredNativeModules(".", skippedNative);
+    if (skippedNative.length)
+        console.error(`native modules not recorded (the range is not a plain numeric semver range, so the control plane cannot check it): ${skippedNative.join(", ")}`);
+    if (dry)
+        console.error(`native modules this release requires: ${nativeModules ? Object.entries(nativeModules).map(([n, r]) => `${n}@${r}`).join(", ") : "none found"}`);
     const bands = (a.bands || "b0,b1,b2").split(",");
+    if (dry) {
+        const verdict = checkPublishPolicy(cfg.policy, bands);
+        if (!verdict.ok) {
+            console.error(`Refused by policy rule ${verdict.rule}: ${verdict.reason}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
     const platforms = platformsOf(a);
     const release = Number(a.release || 0) || (await currentRelease(kv, APP, MAJOR)) + 1;
-    const summary = { app: APP, release, bands, min_shell_version: MIN_SHELL };
+    const summary = { app: APP, release, bands, min_shell_version: MIN_SHELL, ...(nativeModules ? { required_native_modules: nativeModules } : {}), ...(dry ? { dry_run: true, out: outDir } : {}) };
+    if (dry)
+        console.error(`dry run: nothing is sent anywhere; files go to ${outDir}. No patches are built offline. Release is ${release}${a.release ? "" : " (pass --release N to match the control plane)"}.`);
+    let totalBytes = 0;
+    const patchInfo = { bases: 0, bsdiff: false, patches: 0 };
     for (const pf of platforms) {
         // Android published alone keeps the original dist-ota/ layout, so existing CI keeps working.
         const root = platforms.length === 1 && pf === "android" ? "dist-ota" : `dist-ota/${pf}`;
-        if (a["skip-export"] !== "true")
+        if (!skipExport)
             execSync(`npx expo export --platform ${pf} --output-dir ${root} --clear`, { stdio: "inherit" });
         const jsDir = `${root}/_expo/static/js/${pf}`;
         const file = readdirSync(jsDir).find((f) => f.endsWith(".hbc")) || readdirSync(jsDir).find((f) => f.endsWith(".js"));
         if (!file)
             throw new Error("no bundle in " + jsDir);
         const bytes = new Uint8Array(readFileSync(join(jsDir, file)));
+        const hermesVersion = checkBundle(file, bytes, declaredHermes); // fails before anything is uploaded
         const name = bundleName(release, pf), newSha = sha256Hex(bytes);
         await kv.put(`b/${APP}/${name}`, bytes, "application/octet-stream");
-        // Patches (Android): from recent releases and each shell's embedded bundle; devices verify the patched result against the signed sha256.
-        // iOS ships full bundles for now: the iOS runtime does not apply patches yet.
+        // Patches: from recent releases and each shell's embedded bundle; devices verify the patched result against the signed sha256.
+        // Releases are per platform. Embedded-bundle records are shared under base/<app>/ and tagged with a platform (no tag means Android).
         const patches = [];
-        if (pf === "android") {
+        {
             const MAX_BASES = Number(a["max-bases"] || 6);
             const bases = new Map();
-            const hist = (await Promise.all((await kv.keys(`h/${APP}/r`)).map(async (k) => { try {
+            const hist = (await Promise.all((await kv.keys(pf === "ios" ? `h/${APP}/ios-r` : `h/${APP}/r`)).map(async (k) => { try {
                 return JSON.parse((await kv.get(k)));
             }
             catch {
@@ -67,21 +160,25 @@ export async function publish(argv) {
             } })))
                 .filter((h) => h && h.release < release).sort((x, y) => y.release - x.release).slice(0, MAX_BASES - 2);
             for (const h of hist)
-                bases.set(h.sha256, `b/${APP}/r${h.release}.hbc`);
+                bases.set(h.sha256, `b/${APP}/${bundleName(h.release, pf)}`);
             for (const k of await kv.keys(`base/${APP}/`)) {
                 try {
                     const b = JSON.parse((await kv.get(k)));
-                    bases.set(b.sha256, b.key);
+                    if ((b.platform ?? "android") === pf)
+                        bases.set(b.sha256, b.key);
                 }
                 catch { }
             }
-            let bsdiff = true;
-            try {
-                execSync("python3 -c 'import bsdiff4'", { stdio: "ignore" });
-            }
-            catch {
-                bsdiff = false;
-                console.error("bsdiff4 not installed (pip install bsdiff4): publishing full bundles only");
+            // Only look for bsdiff4 when there is an older bundle to patch from; a first release needs no patches.
+            let bsdiff = false;
+            if (bases.size > 0) {
+                try {
+                    execSync("python3 -c 'import bsdiff4'", { stdio: "ignore" });
+                    bsdiff = true;
+                }
+                catch {
+                    console.error("Small patches are off because the Python tool bsdiff4 is not installed (pip install bsdiff4). Full bundles are published instead. Updates still work, they are just bigger.");
+                }
             }
             if (bsdiff) {
                 const work = mkdtempSync(join(tmpdir(), "shipvo-"));
@@ -97,19 +194,22 @@ export async function publish(argv) {
                     const patch = new Uint8Array(readFileSync(join(work, "p.bsdiff")));
                     if (patch.length >= bytes.length * 0.6)
                         continue;
-                    const pkey = `b/${APP}/d-${fromSha.slice(0, 16)}-r${release}.bsdiff`;
+                    const pkey = `b/${APP}/${pf === "ios" ? "ios-" : ""}d-${fromSha.slice(0, 16)}-r${release}.bsdiff`;
                     await kv.put(pkey, patch, "application/octet-stream");
                     patches.push({ from_sha256: fromSha, url: pkey, size: patch.length, sha256: sha256Hex(patch) });
                 }
             }
+            patchInfo.bases = bases.size;
+            patchInfo.bsdiff = bsdiff;
+            patchInfo.patches = patches.length;
             console.error(`patches: ${patches.map((p) => `${p.from_sha256.slice(0, 8)}=${(p.size / 1024).toFixed(1)}KB`).join(", ") || "none"}`);
         }
         // The agent-facing web artifact of the same commit, served at /w/<app>/r<N>/ for the simulator (built once, with the first platform).
         let web = null;
-        if (a["skip-web"] !== "true" && pf === platforms[0]) {
-            web = await publishWeb(kv, cfg, APP, release);
+        if (!skipWeb && pf === platforms[0]) {
+            web = await publishWeb(kv, cfg, APP, release, dry ? outDir : undefined);
         }
-        else if (a["skip-web"] !== "true") {
+        else if (!skipWeb) {
             try {
                 web = JSON.parse((await kv.get(`h/${APP}/r${release}`)))?.web ?? null;
             }
@@ -119,11 +219,12 @@ export async function publish(argv) {
         for (const band of bands) {
             const body = JSON.stringify({ schema_version: "1.0", app_id: APP, shell_major: MAJOR, band, ...(pf === "ios" ? { platform: "ios" } : {}), release, issued_at,
                 core: { version: `1.0.${release}`, sha256: newSha, size: bytes.length, url: `b/${APP}/${name}`, patches },
-                addons: [], screens: [], min_shell_version: MIN_SHELL, ...(web ? { web } : {}) });
+                addons: [], screens: [], min_shell_version: MIN_SHELL, ...(hermesVersion ? { hermes_bytecode_version: hermesVersion } : {}), ...(nativeModules ? { required_native_modules: nativeModules } : {}), ...(web ? { web } : {}) });
             await kv.put(pointerKey(APP, MAJOR, band, pf), JSON.stringify({ body, signature: signBytes(new TextEncoder().encode(body), SEED) }), "application/json");
         }
-        await kv.put(pf === "ios" ? `h/${APP}/ios-r${release}` : `h/${APP}/r${release}`, JSON.stringify({ release, issued_at, sha256: newSha, size: bytes.length, min_shell_version: MIN_SHELL, web }), "application/json");
-        summary[pf] = { bytes: bytes.length, ...(pf === "android" ? { patches: patches.map((p) => ({ from: p.from_sha256.slice(0, 12), kb: +(p.size / 1024).toFixed(1) })) } : {}) };
+        await kv.put(pf === "ios" ? `h/${APP}/ios-r${release}` : `h/${APP}/r${release}`, JSON.stringify({ release, issued_at, sha256: newSha, size: bytes.length, min_shell_version: MIN_SHELL, ...(hermesVersion ? { hermes_bytecode_version: hermesVersion } : {}), ...(nativeModules ? { required_native_modules: nativeModules } : {}), web }), "application/json");
+        totalBytes += bytes.length;
+        summary[pf] = { bytes: bytes.length, patches: patches.map((p) => ({ from: p.from_sha256.slice(0, 12), kb: +(p.size / 1024).toFixed(1) })) };
         if (web)
             summary.web = web;
     }
@@ -132,9 +233,34 @@ export async function publish(argv) {
         Object.assign(summary, { bytes: an.bytes, patches: an.patches });
         delete summary.android;
     }
-    console.log(JSON.stringify(summary));
+    if (dry)
+        console.log(dryRunSummary(release, totalBytes, outDir, patchInfo));
+    else
+        console.log(JSON.stringify(summary));
+}
+/** Bytes in plain units: KB below 1 MB, so a small bundle never reads as 0.00 MB. */
+export function formatSize(bytes) {
+    return bytes < 1048576 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1048576).toFixed(2)} MB`;
+}
+/** The dry-run result in plain words. `info` says what happened with patches on Android. */
+export function dryRunSummary(release, bytes, outDir, info = { bases: 0, bsdiff: false, patches: 0 }) {
+    const lines = [
+        `Dry run complete. Nothing was sent.`,
+        `  Release:  ${release}`,
+        `  Size:     ${formatSize(bytes)}`,
+        `  Files:    ${outDir}`,
+    ];
+    if (info.bases === 0 && release > 1)
+        lines.push(`Patches are not built in a dry run, because older releases are not read. Publish for real to build them.`);
+    else if (info.bases === 0)
+        lines.push(`Full bundles are fine for a first release. Small patches matter once you have older releases to compare against.`);
+    else if (!info.bsdiff)
+        lines.push(`Patches were skipped because bsdiff4 is not installed (pip install bsdiff4). Full bundles still work.`);
+    else
+        lines.push(`Patches built: ${info.patches}.`);
+    return lines.join("\n");
 }
-async function publishWeb(kv, cfg, APP, release) {
+async function publishWeb(kv, cfg, APP, release, outDir) {
     execSync("PN_SIM=1 npx expo export --platform web --output-dir dist-web --clear", { stdio: "inherit" });
     const base = `w/${APP}/r${release}`;
     const files = [];
@@ -161,7 +287,9 @@ async function publishWeb(kv, cfg, APP, release) {
     idx.releases = [...new Set([...idx.releases, release])].sort((x, y) => x - y);
     idx.latest = Math.max(...idx.releases);
     await kv.put(idxKey, JSON.stringify(idx), "application/json");
-    console.error(`web artifact: ${files.length} files at /${base}/`);
+    // Show where the files are on disk, relative to this folder: the URL path (/w/...) is not a folder.
+    const where = outDir ? (relative(process.cwd(), resolve(outDir, base)) || ".") + "/" : `/${base}/`;
+    console.error(`web artifact: ${files.length} files at ${where}`);
     // Store listing assets (icon, screenshots) and the release note, read by shipvo.dev/apps and list_apps.
     const L = cfg.listing ?? {};
     const store = `w/${APP}/store`;
@@ -186,15 +314,17 @@ async function publishWeb(kv, cfg, APP, release) {
     return web;
 }
 export async function rollback(argv) {
-    const a = parse(argv), cfg = loadConfig(), SEED = seed(), kv = kvFor(cfg);
+    checkFlags(argv, ["to", "bands", "platform", "dry-run"]);
+    const a = parse(argv), dry = a["dry-run"] !== undefined, cfg = loadConfig(), SEED = seed(), kv = kvFor(cfg);
     const APP = cfg.appId, MAJOR = cfg.shellMajor, to = Number(a.to);
     if (!to) {
-        console.error("Usage: shipvo rollback --to <release> [--bands b0,b1,b2] [--platform android|ios|all]");
+        console.error("Usage: shipvo rollback --to <release> [--bands b0,b1,b2] [--platform android|ios|all] [--dry-run]");
         process.exit(2);
     }
     const release = (await currentRelease(kv, APP, MAJOR)) + 1, issued_at = new Date().toISOString();
     let minShell = "1.0.0";
-    for (const pf of platformsOf(a)) {
+    const platforms = platformsOf(a), bands = (a.bands || "b0,b1,b2").split(",");
+    for (const pf of platforms) {
         const bytes = await kv.getBytes(`b/${APP}/${bundleName(to, pf)}`);
         if (!bytes) {
             console.error(`Release ${to} ${pf} bundle not found`);
@@ -207,11 +337,16 @@ export async function rollback(argv) {
             web = h.web ?? undefined;
         }
         catch { }
-        for (const band of (a.bands || "b0,b1,b2").split(",")) {
+        for (const band of bands) {
             const body = JSON.stringify({ schema_version: "1.0", app_id: APP, shell_major: MAJOR, band, ...(pf === "ios" ? { platform: "ios" } : {}), release, issued_at,
                 core: { version: `1.0.${release}`, sha256: sha256Hex(bytes), size: bytes.length, url: `b/${APP}/${bundleName(to, pf)}` }, addons: [], screens: [], min_shell_version: minShell, ...(web ? { web } : {}) });
-            await kv.put(pointerKey(APP, MAJOR, band, pf), JSON.stringify({ body, signature: signBytes(new TextEncoder().encode(body), SEED) }), "application/json");
+            if (!dry)
+                await kv.put(pointerKey(APP, MAJOR, band, pf), JSON.stringify({ body, signature: signBytes(new TextEncoder().encode(body), SEED) }), "application/json");
         }
     }
+    if (dry) {
+        console.log([`Rollback preview for ${APP}:`, `  Rolling back to the code of release ${to}`, `  New release number: ${release}`, `  Platforms: ${platforms.join(", ")}`, `  Bands: ${bands.join(", ")}`, `  Min shell version: ${minShell}`, `Dry run: nothing was written.`].join("\n"));
+        return;
+    }
     console.log(JSON.stringify({ app: APP, rolled_back_to_code_of: to, new_release: release, min_shell_version: minShell, issued_at }));
 }

package/dist/sim.d.ts

@@ -1 +1,28 @@
+/** True if nothing is listening on the port (checks by binding, then closing). */
+export declare function portFree(port: number): 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. */
+export declare function friendlyBuildError(message: string, verbose?: boolean): string;
+/**
+ * Calls `build` once after changes settle for `debounceMs`. A change during a build queues one more build.
+ * `build` rejects with the build error; it is printed and the caller keeps serving the last good build.
+ * Returns a function that stops watching.
+ */
+export declare function watchAndRebuild(opts: {
+    dir: string;
+    build: () => Promise<void>;
+    debounceMs?: number;
+    log?: (line: string) => void;
+    verbose?: boolean;
+}): () => void;
+/**
+ * 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.
+ */
+export declare function rebuildInto(opts?: {
+    root?: string;
+    command?: string;
+}): Promise<void>;
 export declare function sim(argv: string[]): Promise<void>;

package/dist/sim.js

@@ -1,11 +1,139 @@
 // `shipvo sim`: build the app's web bundle with the simulated device and serve it in the simulator.
 import { execSync, spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+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 { args as parse, loadConfig } from "./config.js";
+/** True if nothing is listening on the port (checks by binding, then closing). */
+export function portFree(port) {
+    return new Promise((resolve) => {
+        const s = createServer();
+        s.once("error", () => resolve(false));
+        s.listen(port, () => s.close(() => resolve(true)));
+    });
+}
+/** Resolves true once something accepts connections on the port, false if `stop` says to give up. */
+function waitListening(port, stop) {
+    return new Promise((resolve) => {
+        const tryOnce = () => {
+            if (stop())
+                return resolve(false);
+            const c = connect(port, "127.0.0.1");
+            c.once("connect", () => { c.destroy(); resolve(true); });
+            c.once("error", () => { c.destroy(); setTimeout(tryOnce, 100); });
+        };
+        tryOnce();
+    });
+}
+const IGNORED = new Set(["node_modules", "sim-dist", ".shipvo", ".git", ".expo", "dist", "dist-ota", "web-build", "ios", "android"]);
+/** True if a path (relative to the project) is inside a folder that never triggers a rebuild. */
+export const ignoredPath = (rel) => rel.split(/[\\/]/).some((seg) => IGNORED.has(seg));
+/** Turns a build error into a short plain message. Unknown errors keep their first line only. */
+export function friendlyBuildError(message, verbose = false) {
+    if (verbose)
+        return `build failed, still serving the last good build: ${message}`;
+    const m = /in file (\S+\.json) at (\d+):(\d+)/.exec(message);
+    if (m && /Unexpected token|SyntaxError/.test(message)) {
+        const comma = /expected punc [«"']?,/.test(message) || /Unexpected token string/.test(message);
+        const what = comma ? "check for a missing or extra comma" : "a character is missing, extra or in the wrong place";
+        return `Your file ${m[1]} has a mistake at line ${m[2]}, column ${m[3]}: ${what}. The page still shows your last good version.`;
+    }
+    return `build failed, still serving the last good build: ${message.split("\n")[0]} (run with --verbose for details)`;
+}
+/**
+ * Calls `build` once after changes settle for `debounceMs`. A change during a build queues one more build.
+ * `build` rejects with the build error; it is printed and the caller keeps serving the last good build.
+ * Returns a function that stops watching.
+ */
+export function watchAndRebuild(opts) {
+    const { dir, build, debounceMs = 300, log = (l) => console.error(l), verbose = false } = opts;
+    let timer;
+    let running = false;
+    let again = false;
+    let closed = false;
+    const run = async () => {
+        if (running) {
+            again = true;
+            return;
+        }
+        running = true;
+        const t0 = Date.now();
+        try {
+            await build();
+            log(`rebuilt in ${((Date.now() - t0) / 1000).toFixed(1)} s`);
+        }
+        catch (e) {
+            log(friendlyBuildError(e.message, verbose));
+        }
+        running = false;
+        if (again && !closed) {
+            again = false;
+            void run();
+        }
+    };
+    const w = watch(dir, { recursive: true }, (_ev, file) => {
+        if (closed || (file && ignoredPath(String(file))))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => void run(), debounceMs);
+    });
+    const stop = () => { closed = true; clearTimeout(timer); w.close(); };
+    w.on("error", (e) => { log(`file watcher failed, no longer watching: ${e.message}`); stop(); });
+    return stop;
+}
+/**
+ * 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.
+ */
+export function rebuildInto(opts = {}) {
+    const root = opts.root ?? process.cwd();
+    const command = opts.command ?? "npx expo export --platform web --clear --output-dir";
+    const next = join(root, ".shipvo", "sim-next"), live = join(root, "sim-dist"), prev = join(root, ".shipvo", "sim-prev");
+    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"] });
+        let tail = "";
+        p.stderr.on("data", (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}`));
+            }
+            let moved = false;
+            try {
+                rmSync(prev, { recursive: true, force: true });
+                if (existsSync(live)) {
+                    renameSync(live, prev);
+                    moved = true;
+                }
+                renameSync(next, live);
+            }
+            catch (e) {
+                try {
+                    if (moved && !existsSync(live))
+                        renameSync(prev, live);
+                }
+                catch { /* keep the original error */ }
+                rmSync(next, { recursive: true, force: true });
+                return reject(e);
+            }
+            rmSync(prev, { recursive: true, force: true });
+            resolve();
+        });
+    });
+}
 export async function sim(argv) {
     const a = parse(argv);
     const cfg = loadConfig();
+    const port = a.port || "4545";
+    if (!(await portFree(Number(port)))) {
+        console.error(`Port ${port} is in use. Stop the other \`shipvo sim\` or pass --port <n>.`);
+        process.exit(1);
+    }
     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" } });
@@ -18,8 +146,14 @@ export async function sim(argv) {
         console.error("Install @shipvo/sim (and playwright) in this app: npm i -D @shipvo/sim playwright && npx playwright install chromium");
         process.exit(2);
     }
-    const port = a.port || "4545";
-    console.error(`Simulator on http://localhost:${port}  (open_app("${cfg.appId}") from @shipvo/mcp; Ctrl-C to stop)`);
     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 } });
-    p.on("exit", (c) => process.exit(c ?? 0));
+    let exited = false;
+    p.on("exit", (c) => { exited = true; process.exit(c ?? 0); });
+    if (await waitListening(Number(port), () => exited)) {
+        console.error(`Simulator on http://localhost:${port}/app/  (open_app("${cfg.appId}") from @shipvo/mcp; Ctrl-C to stop)`);
+        if (a.watch === "true") {
+            watchAndRebuild({ dir: process.cwd(), build: () => rebuildInto(), verbose: a.verbose === "true" });
+            console.error("Watching for changes (ignoring node_modules, sim-dist, .shipvo, .expo, dist, dist-ota, web-build, ios, android)");
+        }
+    }
 }

package/dist/status.d.ts

@@ -0,0 +1,16 @@
+type Row = {
+    release: number;
+    events: Record<string, number>;
+    apply_ms_median: number | null;
+    cold_start_ms_median: number | null;
+};
+type AutoHalt = {
+    threshold: number;
+    min_reports: number;
+} | null;
+/** 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 declare function status(argv: string[], fetchFn?: typeof fetch): Promise<number>;
+export {};

package/dist/status.js

@@ -0,0 +1,54 @@
+import { args, loadConfig } from "./config.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) {
+    const names = [...new Set(releases.flatMap((r) => Object.keys(r.events ?? {})))].sort();
+    const rows = [["release", ...names, "apply ms", "cold start ms"],
+        ...releases.map((r) => [String(r.release), ...names.map((n) => String(r.events?.[n] ?? 0)), ms(r.apply_ms_median), ms(r.cold_start_ms_median)])];
+    const w = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
+    return rows.map((r) => r.map((c, i) => (i === 0 ? c.padEnd(w[i]) : c.padStart(w[i]))).join("  ")).join("\n");
+}
+/** "auto-halt: off" or "auto-halt: on at 20% after 20 reports". */
+export function describeAutoHalt(c) {
+    if (!c || typeof c.threshold !== "number")
+        return "auto-halt: off";
+    const n = c.min_reports ?? 20;
+    return `auto-halt: on at ${Math.round(c.threshold * 1000) / 10}% after ${n} report${n === 1 ? "" : "s"}`;
+}
+export async function status(argv, fetchFn = fetch) {
+    const a = args(argv);
+    const cfg = loadConfig();
+    const appId = a.app && a.app !== "true" ? a.app : cfg.appId;
+    const base = cfg.controlPlane.replace(/\/$/, "");
+    const url = `${base}/t/${encodeURIComponent(appId)}/summary`;
+    let data;
+    try {
+        const r = await fetchFn(url);
+        if (!r.ok)
+            throw new Error(`HTTP ${r.status}`);
+        data = (await r.json());
+    }
+    catch (e) {
+        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)
+        console.log(describeAutoHalt(data.auto_halt));
+    if (!releases.length) {
+        console.log(`No telemetry yet for "${appId}".`);
+        return 0;
+    }
+    const h = data.halted;
+    if (h && typeof h === "object") {
+        const pct = Math.round(h.threshold * 1000) / 10;
+        console.log(`Release ${h.release} is halted: ${h.failed} of ${h.reports} devices failed (limit ${pct}%). Publish a new release or run shipvo rollback to clear.`);
+    }
+    console.log(formatStatus(releases));
+    return 0;
+}

package/dist/store.d.ts

@@ -0,0 +1,2 @@
+/** `shipvo store details --dry-run [--out dir]`: print the answers, write two files. Nothing is uploaded; no credentials are read. */
+export declare function store(argv: string[]): Promise<void>;

package/dist/store.js

@@ -0,0 +1,34 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { deriveStoreDetails, renderDataSafetyCsv, renderPrivacyPolicy } from "@shipvo/store";
+import { args, loadConfig } from "./config.js";
+/** `shipvo store details --dry-run [--out dir]`: print the answers, write two files. Nothing is uploaded; no credentials are read. */
+export async function store(argv) {
+    const [sub, ...rest] = argv;
+    if (sub !== "details") {
+        console.error("Usage: shipvo store details --dry-run [--out dir]");
+        process.exit(2);
+    }
+    const a = args(rest);
+    if (a["dry-run"] === undefined || a["dry-run"] === "false") {
+        console.error("shipvo store details: upload is not available yet; use --dry-run");
+        process.exit(2);
+    }
+    const cfg = loadConfig();
+    const d = deriveStoreDetails(cfg);
+    const out = a.out && a.out !== "true" ? a.out : ".shipvo/store";
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "data-safety.csv"), renderDataSafetyCsv(d));
+    writeFileSync(join(out, "privacy-policy.md"), renderPrivacyPolicy(d));
+    console.log(`Data safety answers for ${d.appName} (derived from shipvo.json):`);
+    if (d.rows.length === 0)
+        console.log("  No declared capability touches user data.");
+    for (const r of d.rows)
+        console.log(`  ${r.dataType}: collected ${r.collected}, shared ${r.shared}, purpose ${r.purpose}`);
+    if (d.fill.total > 0)
+        console.log(`Filled without you: ${d.fill.filled} of ${d.fill.total} fields.`);
+    console.log(`\nYou still need to answer (${d.unknown.length}):`);
+    for (const u of d.unknown)
+        console.log(`  - ${u.question}`);
+    console.log(`\nWrote ${join(out, "data-safety.csv")} and ${join(out, "privacy-policy.md")}. Nothing was uploaded.`);
+}

package/dist/verify.d.ts

@@ -0,0 +1 @@
+export declare function verifyPointer(file: string, publicKeyB64: string): boolean;

package/dist/verify.js

@@ -0,0 +1,15 @@
+// `shipvo verify <pointer file> [public-key]`: check a release pointer, which is { body, signature }
+// with the signature taken over the body string (see publish.ts). Read-only helper; phones use their own path.
+import * as ed from "@noble/ed25519";
+import { unb64 } from "./index.js";
+export function verifyPointer(file, publicKeyB64) {
+    try {
+        const p = JSON.parse(file);
+        if (typeof p?.body !== "string" || typeof p?.signature !== "string")
+            return false;
+        return ed.verify(unb64(p.signature), new TextEncoder().encode(p.body), unb64(publicKeyB64));
+    }
+    catch {
+        return false;
+    }
+}