@shipvo/cli 0.1.5 → 0.1.6

package/dist/promote.js

@@ -2,11 +2,12 @@
 // and writes the same release (same bundle, hashes and patches) to the other bands with a fresh issued_at and signature.
 import { existsSync, readFileSync } from "node:fs";
 import { signBytes } from "./index.js";
-import { args as parse, kv as kvFor, loadConfig, seed } from "./config.js";
+import { CliFailure, UsageError, runJson } from "./json-out.js";
+import { args as parse, hasStore, kv as kvFor, loadConfig, offlineKv, seed } from "./config.js";
 const BANDS = ["b0", "b1", "b2"];
 const REVERT_EVENTS = ["rolled_back", "crash_loop_revert"];
 const pointerKey = (app, major, band, pf) => (pf === "ios" ? `p/${app}/${major}/ios/${band}` : `p/${app}/${major}/${band}`);
-export const PROMOTE_FLAGS = ["to", "platform", "dry-run", "force", "report"];
+export const PROMOTE_FLAGS = ["to", "platform", "dry-run", "force", "report", "json"];
 export const PROMOTE_HELP = `Usage: shipvo promote [flags]
 
 Widen a staged release to more bands. The release number, bundle and patches stay the same; the pointer is signed again.
@@ -18,6 +19,7 @@ Flags (write a value after a space, not =):
   --dry-run                    Print the plan, write nothing
   --report <file>              Test report from shipvo test --report (default shipvo-test-report.json if it exists)
                                A report for this release with failing flows blocks promote
+  --json                       Print one JSON envelope on stdout; text goes to stderr
   --force                      Promote even if the release is halted, has reverts or has a failing test report
   --help                       Show this help
 `;
@@ -26,34 +28,44 @@ function checkFlags(argv, known) {
     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(" ")}`);
+        throw new UsageError(`Unknown flag ${bad.join(", ")}.${hint} Known flags: ${known.map((k) => "--" + k).join(" ")}`);
     }
 }
+const STATUS = [{ command: "shipvo status --json", why: "See how the release does on phones." }];
 export async function promote(argv, deps = {}) {
     if (argv.includes("--help") || argv.includes("-h")) {
         console.log(PROMOTE_HELP);
         return;
     }
+    if (argv.includes("--json"))
+        return runJson(() => promoteRun(argv, deps), [{ command: "shipvo doctor --json", why: "Check your setup." }, ...STATUS]);
+    await promoteRun(argv, deps);
+}
+async function promoteRun(argv, deps) {
     checkFlags(argv, PROMOTE_FLAGS);
     const a = parse(argv), cfg = loadConfig();
     const dry = a["dry-run"] !== undefined, force = a.force !== undefined;
     const p = (a.platform || "android").toLowerCase();
     if (p !== "android" && p !== "ios" && p !== "all")
-        throw new Error(`--platform must be android, ios or all (got "${a.platform}")`);
+        throw new UsageError(`--platform must be android, ios or all (got "${a.platform}")`);
     const platforms = p === "all" ? ["android", "ios"] : [p];
     if (a.to === "true")
-        throw new Error("--to needs bands: pass --to b1,b2");
+        throw new UsageError("--to needs bands: pass --to b1,b2");
     const explicit = a.to ? a.to.split(",").map((s) => s.trim()).filter(Boolean) : null;
     if (explicit) {
         const bad = explicit.filter((b) => !BANDS.includes(b));
         if (bad.length)
-            throw new Error(`Unknown band ${bad.join(", ")}. Bands are ${BANDS.join(", ")}.`);
+            throw new UsageError(`Unknown band ${bad.join(", ")}. Bands are ${BANDS.join(", ")}.`);
     }
     if (a.report === "true")
-        throw new Error("--report needs a file name: pass --report <file>");
+        throw new UsageError("--report needs a file name: pass --report <file>");
     const reportFile = a.report ?? (existsSync("shipvo-test-report.json") ? "shipvo-test-report.json" : null);
     const APP = cfg.appId, MAJOR = cfg.shellMajor;
-    const store = deps.kv ?? kvFor(cfg);
+    // A dry run with no login and no Cloudflare keys reads the files `shipvo publish --dry-run` wrote.
+    const offline = !deps.kv && dry && !hasStore();
+    const store = deps.kv ?? (offline ? offlineKv() : kvFor(cfg));
+    if (offline)
+        console.log("Offline rehearsal: reading pointers from .shipvo/dry-run (written by shipvo publish --dry-run). No login used, nothing is sent.");
     // Read every source pointer before touching the network or writing anything.
     const plans = [];
     for (const pf of platforms) {
@@ -74,10 +86,10 @@ export async function promote(argv, deps = {}) {
             catch { /* unreadable pointer: skip */ }
         }
         if (!body)
-            throw new Error(`No ${pf} pointer found on any band. Run shipvo publish --bands b0 first.`);
+            throw new CliFailure(`No ${pf} pointer found on any band. Run shipvo publish --bands b0 first.`, "no_pointer", 1, [{ command: "shipvo publish --bands b0 --json", why: "Publish to the first cohort." }]);
         const release = body.release;
         if (explicit && explicit.length && explicit.every((b) => b === from))
-            throw new Error(`${from} is the source band (release ${release}). Pass --to with a different band.`);
+            throw new UsageError(`${from} is the source band (release ${release}). Pass --to with a different band.`);
         // Never write an older release over a newer one: promote widens, it does not downgrade. --force does not change this.
         const cand = (explicit ?? BANDS).filter((b) => b !== from && (explicit || have.get(b) !== release));
         const newer = cand.filter((b) => (have.get(b) ?? 0) > release).map((b) => [b, have.get(b)]);
@@ -90,7 +102,7 @@ export async function promote(argv, deps = {}) {
             rep = JSON.parse(readFileSync(reportFile, "utf8"));
         }
         catch (e) {
-            throw new Error(`Could not read the test report ${reportFile} (${e instanceof Error ? e.message : String(e)}).`);
+            throw new CliFailure(`Could not read the test report ${reportFile} (${e instanceof Error ? e.message : String(e)}).`, "report_unreadable", 1, [{ command: "shipvo test --report shipvo-test-report.json --json", why: "Write a fresh test report." }]);
         }
         const rel = rep.release == null ? null : String(rep.release);
         const failing = (Array.isArray(rep.flows) ? rep.flows : []).filter((f) => f.status === "failed").map((f) => f.name ?? "(unnamed flow)");
@@ -98,14 +110,14 @@ export async function promote(argv, deps = {}) {
         if (mine.length && failing.length) {
             const msg = `Test report ${reportFile} has ${failing.length} failing flow${failing.length === 1 ? "" : "s"} for release ${mine[0].release}: ${failing.join(", ")}.`;
             if (!force)
-                throw new Error(`${msg} Fix them and run shipvo test --report again, or pass --force to promote anyway.`);
+                throw new CliFailure(`${msg} Fix them and run shipvo test --report again, or pass --force to promote anyway.`, "tests_failed", 1, [{ command: `shipvo test --report ${reportFile} --json`, why: "Run the flows again after the fix." }]);
             console.log(`${msg} Overridden by --force.`);
         }
         else if (!mine.length) {
             console.log(`Warning: test report ${reportFile} is for ${rel === null ? "no release" : `release ${rel}`}, not release ${plans.map((x) => x.release).join(", ")}. It is stale and was not used.`);
         }
     }
-    if (!force) {
+    if (!force && !offline) {
         const base = cfg.controlPlane.replace(/\/$/, "");
         let data;
         try {
@@ -115,18 +127,20 @@ export async function promote(argv, deps = {}) {
             data = (await r.json());
         }
         catch (e) {
-            throw new Error(`Could not read the release status from ${base} (${e instanceof Error ? e.message : String(e)}). Try again, or pass --force to promote without the check.`);
+            throw new CliFailure(`Could not read the release status from ${base} (${e instanceof Error ? e.message : String(e)}). Try again, or pass --force to promote without the check.`, "remote_failed", 1, [{ command: "shipvo doctor --json", why: "Check the control plane." }]);
         }
         for (const { release } of plans) {
             if (data.halted && typeof data.halted === "object" && data.halted.release === release)
-                throw new Error(`Release ${release} is halted. Publish a new release or run shipvo rollback, or pass --force to promote it anyway.`);
+                throw new CliFailure(`Release ${release} is halted. Publish a new release or run shipvo rollback, or pass --force to promote it anyway.`, "blocked", 1, STATUS);
             const ev = data.releases?.find((r) => r.release === release)?.events ?? {};
             const n = REVERT_EVENTS.reduce((s, k) => s + (ev[k] ?? 0), 0);
             if (n > 0)
-                throw new Error(`Release ${release} has ${n} reported revert${n === 1 ? "" : "s"}. Check shipvo status, publish a fix, or pass --force to promote it anyway.`);
+                throw new CliFailure(`Release ${release} has ${n} reported revert${n === 1 ? "" : "s"}. Check shipvo status, publish a fix, or pass --force to promote it anyway.`, "blocked", 1, STATUS);
         }
     }
+    const result = [];
     for (const { pf, release, from, body, targets, newer } of plans) {
+        result.push({ platform: pf, release, from, bands: targets, skipped_newer: newer.map(([band, release]) => ({ band, release })) });
         for (const [b, r] of newer)
             console.log(`Skipped ${b} (${pf}): it already has release ${r}, which is newer than ${release}.`);
         if (!targets.length && newer.length) {
@@ -150,4 +164,12 @@ export async function promote(argv, deps = {}) {
     }
     if (dry)
         console.log("Dry run: nothing was written.");
+    const count = result.reduce((n, r) => n + r.bands.length, 0);
+    const data = { dry_run: dry, promoted: result };
+    if (count === 0)
+        return { code: "nothing_to_promote", summary: "Nothing to promote: no band needs this release.", data, next: STATUS };
+    const list = result.map((r) => `${r.platform} release ${r.release} to ${r.bands.join(", ")}`).join("; ");
+    if (dry)
+        return { code: "dry_run", summary: `Would promote ${list}. Nothing was written.`, data, next: [{ command: `shipvo promote ${argv.filter((x) => x !== "--dry-run").join(" ")}`.trim(), why: "Do the promote." }] };
+    return { code: "promoted", summary: `Promoted ${list}.`, data, next: STATUS };
 }

package/dist/publish.d.ts

@@ -1,11 +1,23 @@
-export declare const PUBLISH_HELP = "Usage: shipvo publish [flags]\n\nBuild, sign and publish an over-the-air release.\n\nFlags (write a value after a space, not =; on/off flags can be bare, or true/false):\n  --bands b0,b1,b2             Cohorts to publish to (default b0,b1,b2)\n  --platform android|ios|all   Platform to publish (default android)\n  --release N                  Release number (default: the next one)\n  --min-shell X.Y.Z            Oldest app shell that can run this release (default: version in app.json)\n  --hermes-bytecode-version V  Refuse bundles built for another Hermes version, for example 96 or 96,98\n  --max-bases N                How many older releases to build patches from (default 6)\n  --skip-export               Reuse the last build in dist-ota/\n  --skip-web                  Do not publish the web copy for the simulator\n  --dry-run                    Build and sign, write files locally, send nothing\n  --dry-run-policy             Check the policy in shipvo.json for these --bands, print the result, publish nothing\n  --out <dir>                  Where --dry-run writes files (default .shipvo/dry-run)\n  --help                       Show this help\n";
+import path from "node:path";
+/** True when `file` is strictly inside `root`. Uses the platform's separator, so it works with Windows paths too. */
+export declare function isInside(root: string, file: string, p?: typeof path.posix): boolean;
+export declare const PUBLISH_HELP = "Usage: shipvo publish [flags]\n\nBuild, sign and publish an over-the-air release.\n\nFlags (write a value after a space, not =; on/off flags can be bare, or true/false):\n  --bands b0,b1,b2             Cohorts to publish to (default b0,b1,b2)\n  --platform android|ios|all   Platform to publish (default android)\n  --release N                  Release number (default: the next one)\n  --min-shell X.Y.Z            Oldest app shell that can run this release (default: version in app.json)\n  --hermes-bytecode-version V  Refuse bundles built for another Hermes version, for example 96 or 96,98\n  --max-bases N                How many older releases to build patches from (default 6)\n  --skip-export               Reuse the last build in dist-ota/\n  --skip-web                  Do not publish the web copy for the simulator\n  --dry-run                    Build and sign, write files locally, send nothing\n  --dry-run-policy             Check the policy in shipvo.json for these --bands, print the result, publish nothing\n  --out <dir>                  Where --dry-run writes files (default .shipvo/dry-run)\n  --json                       Print one JSON envelope on stdout; text and build output go to stderr\n  --help                       Show this help\n";
 export declare function publish(argv: string[]): Promise<void>;
+/** The publish result in plain words. `--json` carries the full detail. */
+export declare function publishedSummary(release: number, bands: string[]): string;
+/** The rollback result in plain words. */
+export declare function rolledBackSummary(to: number, release: number): string;
 /** Bytes in plain units: KB below 1 MB, so a small bundle never reads as 0.00 MB. */
 export declare function formatSize(bytes: number): string;
 /** The dry-run result in plain words. `info` says what happened with patches on Android. */
 export declare function dryRunSummary(release: number, bytes: number, outDir: string, info?: {
     bases: number;
-    bsdiff: boolean;
     patches: number;
 }): string;
+/** The line for a listing file that is not there. It says the file is optional and what to do. */
+export declare function missingListingNote(file: string, name: string): string;
+/** Upload one listing file to the store prefix. A missing file prints a note and returns null. */
+export declare function uploadListingFile(kv: {
+    put: (k: string, b: BodyInit, m: string) => Promise<unknown>;
+}, store: string, file: string, name: string): Promise<string | null>;
 export declare function rollback(argv: string[]): Promise<void>;

package/dist/publish.js

@@ -1,14 +1,15 @@
 // `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, mkdirSync, mkdtempSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import path, { dirname, join, relative, resolve } from "node:path";
 import { sha256Hex, signBytes } from "./index.js";
-import { checkBundle, parseDeclared } from "./hermes.js";
+import { bsdiff } from "./bsdiff.js";
+import { checkBundle, checkEngine, installedHermesEngine, parseDeclared, parseEngine } 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";
+import { CliFailure, UsageError, runJson } from "./json-out.js";
+import { args as parse, hasStore, kv as kvFor, loadConfig, offlineKv, 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)]));
 /** Release numbers are shared across platforms, so one number means one commit everywhere. */
@@ -34,7 +35,7 @@ const platformsOf = (a) => {
         return ["android", "ios"];
     if (p === "android" || p === "ios")
         return [p];
-    throw new Error(`--platform must be android, ios or all (got "${a.platform}")`);
+    throw new UsageError(`--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) {
@@ -42,7 +43,7 @@ function checkFlags(argv, known) {
     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(" ")}`);
+        throw new UsageError(`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. */
@@ -52,7 +53,12 @@ function switchFlag(a, name) {
         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}")`);
+    throw new UsageError(`--${name} is an on/off flag: use --${name}, --${name} true or --${name} false (got "${v}")`);
+}
+/** True when `file` is strictly inside `root`. Uses the platform's separator, so it works with Windows paths too. */
+export function isInside(root, file, p = path) {
+    const rel = p.relative(root, file);
+    return rel !== "" && !rel.startsWith("..") && !p.isAbsolute(rel);
 }
 /** 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) {
@@ -65,7 +71,7 @@ function localKv(dir) {
         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 + "/"))
+            if (!isInside(root, f))
                 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 });
@@ -74,7 +80,7 @@ function localKv(dir) {
         },
     };
 }
-const PUBLISH_FLAGS = ["bands", "platform", "release", "min-shell", "hermes-bytecode-version", "max-bases", "skip-export", "skip-web", "dry-run", "dry-run-policy", "out"];
+const PUBLISH_FLAGS = ["bands", "platform", "release", "min-shell", "hermes-bytecode-version", "max-bases", "skip-export", "skip-web", "dry-run", "dry-run-policy", "out", "json"];
 export const PUBLISH_HELP = `Usage: shipvo publish [flags]
 
 Build, sign and publish an over-the-air release.
@@ -91,37 +97,46 @@ Flags (write a value after a space, not =; on/off flags can be bare, or true/fal
   --dry-run                    Build and sign, write files locally, send nothing
   --dry-run-policy             Check the policy in shipvo.json for these --bands, print the result, publish nothing
   --out <dir>                  Where --dry-run writes files (default .shipvo/dry-run)
+  --json                       Print one JSON envelope on stdout; text and build output go to stderr
   --help                       Show this help
 `;
+const DOCTOR = [{ command: "shipvo doctor --json", why: "Check your setup." }];
 export async function publish(argv) {
     if (argv.includes("--help") || argv.includes("-h")) {
         console.log(PUBLISH_HELP);
         return;
     }
+    if (argv.includes("--json"))
+        return runJson(() => publishRun(argv, true), DOCTOR);
+    await publishRun(argv, false);
+}
+async function publishRun(argv, json) {
+    // In --json mode the build tools must not write to stdout either.
+    const io = json ? ["inherit", 2, 2] : "inherit";
     checkFlags(argv, PUBLISH_FLAGS);
     const a = parse(argv), cfg = loadConfig(), SEED = seed();
     if (switchFlag(a, "dry-run-policy")) {
         const verdict = checkPublishPolicy(cfg.policy, (a.bands || "b0,b1,b2").split(","));
-        if (verdict.ok)
-            console.log(cfg.policy === undefined ? "No policy in shipvo.json: nothing to check." : "Policy allows this publish.");
-        else {
-            console.error(`Refused by policy rule ${verdict.rule}: ${verdict.reason}`);
-            process.exitCode = 1;
+        if (verdict.ok) {
+            const msg = cfg.policy === undefined ? "No policy in shipvo.json: nothing to check." : "Policy allows this publish.";
+            console.log(msg);
+            return { code: "policy_ok", summary: msg, data: { policy: cfg.policy === undefined ? "none" : "allowed", bands: (a.bands || "b0,b1,b2").split(",") }, next: [{ command: "shipvo publish --dry-run --json", why: "Build and sign without sending." }] };
         }
-        return;
+        return refused(verdict, json);
     }
     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");
+        throw new UsageError("--out only works with --dry-run");
     if (a.out === "true")
-        throw new Error("--out needs a directory: pass --out <dir>");
+        throw new UsageError("--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)");
+        throw new UsageError("--hermes-bytecode-version needs a value: pass a value like 96 (or 96,98)");
     const declaredHermes = parseDeclared(a["hermes-bytecode-version"] ?? cfg.hermesBytecodeVersion);
+    const hermesEngine = checkEngine(installedHermesEngine(process.cwd()), parseEngine(cfg.hermesEngine)); // fails before anything is uploaded
     const skippedNative = [];
     const nativeModules = requiredNativeModules(".", skippedNative);
     if (skippedNative.length)
@@ -131,11 +146,8 @@ export async function publish(argv) {
     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;
-        }
+        if (!verdict.ok)
+            return refused(verdict, json);
     }
     const platforms = platformsOf(a);
     const release = Number(a.release || 0) || (await currentRelease(kv, APP, MAJOR)) + 1;
@@ -143,16 +155,16 @@ export async function publish(argv) {
     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 };
+    const patchInfo = { bases: 0, 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 (!skipExport)
-            execSync(`npx expo export --platform ${pf} --output-dir ${root} --clear`, { stdio: "inherit" });
+            execSync(`npx expo export --platform ${pf} --output-dir ${root} --clear`, { stdio: io });
         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);
+            throw new CliFailure("no bundle in " + jsDir, "no_bundle", 1, [{ command: "shipvo publish --json", why: "Run again without --skip-export so the bundle is built." }]);
         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);
@@ -180,29 +192,23 @@ export async function publish(argv) {
                 }
                 catch { }
             }
-            // Only look for bsdiff4 when there is an older bundle to patch from; a first release needs no patches.
-            let bsdiff = false;
+            // Memory grows with bundle size (plain arrays); only a thrown error falls back to the full bundle.
+            // Patches are built in-process (no Python or other tool); a first release has no older bundle to patch from.
             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-"));
-                writeFileSync(join(work, "new.hbc"), bytes);
                 for (const [fromSha, key] of bases) {
                     if (fromSha === newSha)
                         continue;
                     const base = await kv.getBytes(key);
                     if (!base)
                         continue;
-                    writeFileSync(join(work, "old.hbc"), base);
-                    execSync(`python3 -c "import bsdiff4; bsdiff4.file_diff('${join(work, "old.hbc")}', '${join(work, "new.hbc")}', '${join(work, "p.bsdiff")}')"`);
-                    const patch = new Uint8Array(readFileSync(join(work, "p.bsdiff")));
+                    let patch;
+                    try {
+                        patch = bsdiff(new Uint8Array(base), bytes);
+                    }
+                    catch {
+                        console.error(`Could not build a small patch from release ${fromSha.slice(0, 8)}; publishing the full bundle`);
+                        continue;
+                    }
                     if (patch.length >= bytes.length * 0.6)
                         continue;
                     const pkey = `b/${APP}/${pf === "ios" ? "ios-" : ""}d-${fromSha.slice(0, 16)}-r${release}.bsdiff`;
@@ -211,14 +217,13 @@ export async function publish(argv) {
                 }
             }
             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 (!skipWeb && pf === platforms[0]) {
-            web = await publishWeb(kv, cfg, APP, release, dry ? outDir : undefined);
+            web = await publishWeb(kv, cfg, APP, release, dry ? outDir : undefined, io);
         }
         else if (!skipWeb) {
             try {
@@ -230,10 +235,10 @@ 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, ...(hermesVersion ? { hermes_bytecode_version: hermesVersion } : {}), ...(nativeModules ? { required_native_modules: nativeModules } : {}), ...(web ? { web } : {}) });
+                addons: [], screens: [], min_shell_version: MIN_SHELL, ...(hermesVersion ? { hermes_bytecode_version: hermesVersion } : {}), ...(hermesVersion && hermesEngine ? { hermes_engine: hermesEngine } : {}), ...(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, ...(hermesVersion ? { hermes_bytecode_version: hermesVersion } : {}), ...(nativeModules ? { required_native_modules: nativeModules } : {}), web }), "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, ...(hermesVersion ? { hermes_bytecode_version: hermesVersion } : {}), ...(hermesVersion && hermesEngine ? { hermes_engine: hermesEngine } : {}), ...(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)
@@ -247,14 +252,41 @@ export async function publish(argv) {
     if (dry)
         console.log(dryRunSummary(release, totalBytes, outDir, patchInfo));
     else
-        console.log(JSON.stringify(summary));
+        console.log(publishedSummary(release, bands));
+    const flags = [a.bands ? `--bands ${a.bands}` : "", a.platform ? `--platform ${a.platform}` : ""].filter(Boolean).join(" ");
+    const data = { ...summary, platforms, total_bytes: totalBytes };
+    if (dry)
+        return { code: "dry_run", summary: `Dry run complete: release ${release}, ${formatSize(totalBytes)}. Nothing was sent.`, data, next: [{ command: `shipvo publish ${flags} --json`.replace(/ +/g, " "), why: "Publish for real." }] };
+    const rest = ["b0", "b1", "b2"].filter((b) => !bands.includes(b));
+    const next = [{ command: "shipvo status --json", why: "See how the release does on phones." }];
+    if (rest.length)
+        next.push({ command: `shipvo promote --to ${rest.join(",")} --json`, why: `Widen release ${release} to ${rest.join(", ")} when it looks healthy.` });
+    return { code: "published", summary: `Published release ${release} to ${bands.join(", ")} (${platforms.join(", ")}).`, data, next };
+}
+function refused(verdict, json) {
+    const msg = `Refused by policy rule ${verdict.rule}: ${verdict.reason}`;
+    if (json)
+        throw new CliFailure(msg, "policy_refused", 1, [{ command: "shipvo publish --dry-run-policy --json", why: "Check the policy for other --bands." }]);
+    console.error(msg);
+    process.exitCode = 1;
+    return { code: "policy_refused", summary: msg, data: {}, next: [] };
+}
+/** The publish result in plain words. `--json` carries the full detail. */
+export function publishedSummary(release, bands) {
+    const rest = ["b0", "b1", "b2"].filter((b) => !bands.includes(b));
+    const next = rest.length ? `Next: shipvo status, then shipvo promote --to ${rest.join(",")}.` : "Next: shipvo status.";
+    return `Published release ${release} to ${bands.join(", ")}. ${next}`;
+}
+/** The rollback result in plain words. */
+export function rolledBackSummary(to, release) {
+    return `Rolled back to the code of release ${to} as new release ${release}. Next: shipvo status.`;
 }
 /** 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 }) {
+export function dryRunSummary(release, bytes, outDir, info = { bases: 0, patches: 0 }) {
     const lines = [
         `Dry run complete. Nothing was sent.`,
         `  Release:  ${release}`,
@@ -265,14 +297,32 @@ export function dryRunSummary(release, bytes, outDir, info = { bases: 0, bsdiff:
         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 if (info.patches === 0)
+        lines.push(`No small patch was built, so this update is a full bundle. Full bundles still work.`);
     else
         lines.push(`Patches built: ${info.patches}.`);
     return lines.join("\n");
 }
-async function publishWeb(kv, cfg, APP, release, outDir) {
-    execSync("PN_SIM=1 npx expo export --platform web --output-dir dist-web --clear", { stdio: "inherit" });
+/** The line for a listing file that is not there. It says the file is optional and what to do. */
+export function missingListingNote(file, name) {
+    if (name === "icon")
+        return `No app icon yet (optional). Add ${file} to show one in the store.`;
+    if (name.startsWith("shot-"))
+        return `No screenshot yet (optional). Add ${file} to show it in the store.`;
+    return `No ${name} yet (optional). Add ${file} to show it in the store.`;
+}
+/** Upload one listing file to the store prefix. A missing file prints a note and returns null. */
+export async function uploadListingFile(kv, store, file, name) {
+    if (!existsSync(file)) {
+        console.error(missingListingNote(file, name));
+        return null;
+    }
+    const ext = file.slice(file.lastIndexOf(".")).toLowerCase();
+    await kv.put(`${store}/${name}${ext}`, new Uint8Array(readFileSync(file)), MIME[ext] ?? "application/octet-stream");
+    return `${name}${ext}`;
+}
+async function publishWeb(kv, cfg, APP, release, outDir, io = "inherit") {
+    execSync("npx expo export --platform web --output-dir dist-web --clear", { stdio: io, env: { ...process.env, PN_SIM: "1" } });
     const base = `w/${APP}/r${release}`;
     const files = [];
     let indexSha = "";
@@ -304,10 +354,7 @@ async function publishWeb(kv, cfg, APP, release, outDir) {
     // 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`;
-    const up = async (file, name) => { if (!existsSync(file)) {
-        console.error(`listing: ${file} not found, skipped`);
-        return null;
-    } const ext = file.slice(file.lastIndexOf(".")).toLowerCase(); await kv.put(`${store}/${name}${ext}`, new Uint8Array(readFileSync(file)), MIME[ext] ?? "application/octet-stream"); return `${name}${ext}`; };
+    const up = (file, name) => uploadListingFile(kv, store, file, name);
     const icon = L.icon ? await up(L.icon, "icon") : null;
     const shots = [];
     for (const [i, f] of (L.screenshots ?? []).entries()) {
@@ -325,11 +372,23 @@ async function publishWeb(kv, cfg, APP, release, outDir) {
     return web;
 }
 export async function rollback(argv) {
-    checkFlags(argv, ["to", "bands", "platform", "dry-run"]);
-    const a = parse(argv), dry = a["dry-run"] !== undefined, cfg = loadConfig(), SEED = seed(), kv = kvFor(cfg);
+    if (argv.includes("--json"))
+        return runJson(() => rollbackRun(argv, true), [...DOCTOR, { command: "shipvo status --json", why: "See the newest releases." }]);
+    await rollbackRun(argv, false);
+}
+async function rollbackRun(argv, json) {
+    checkFlags(argv, ["to", "bands", "platform", "dry-run", "json"]);
+    const a = parse(argv), dry = a["dry-run"] !== undefined, cfg = loadConfig();
+    const offline = dry && !hasStore();
+    const SEED = dry ? "" : seed(), kv = offline ? offlineKv() : kvFor(cfg);
+    if (offline)
+        console.error("Offline rehearsal: reading releases from .shipvo/dry-run (written by shipvo publish --dry-run). No login used, nothing is sent.");
     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] [--dry-run]");
+        const usage = "Usage: shipvo rollback --to <release> [--bands b0,b1,b2] [--platform android|ios|all] [--dry-run] [--json]";
+        if (json)
+            throw new UsageError(usage);
+        console.error(usage);
         process.exit(2);
     }
     const release = (await currentRelease(kv, APP, MAJOR)) + 1, issued_at = new Date().toISOString();
@@ -338,6 +397,8 @@ export async function rollback(argv) {
     for (const pf of platforms) {
         const bytes = await kv.getBytes(`b/${APP}/${bundleName(to, pf)}`);
         if (!bytes) {
+            if (json)
+                throw new CliFailure(`Release ${to} ${pf} bundle not found`, "not_found", 1, [{ command: "shipvo status --json", why: "See which releases exist." }]);
             console.error(`Release ${to} ${pf} bundle not found`);
             process.exit(1);
         }
@@ -355,9 +416,12 @@ export async function rollback(argv) {
                 await kv.put(pointerKey(APP, MAJOR, band, pf), JSON.stringify({ body, signature: signBytes(new TextEncoder().encode(body), SEED) }), "application/json");
         }
     }
+    const data = { app: APP, rolled_back_to_code_of: to, new_release: release, min_shell_version: minShell, issued_at, platforms, bands, dry_run: dry };
     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;
+        const real = argv.filter((x) => x !== "--dry-run").join(" ");
+        return { code: "dry_run", summary: `Rollback preview: release ${to} code becomes release ${release}. Nothing was written.`, data, next: [{ command: `shipvo rollback ${real}`, why: "Do the rollback." }] };
     }
-    console.log(JSON.stringify({ app: APP, rolled_back_to_code_of: to, new_release: release, min_shell_version: minShell, issued_at }));
+    console.log(rolledBackSummary(to, release));
+    return { code: "rolled_back", summary: `Rolled back to the code of release ${to} as release ${release}.`, data, next: [{ command: "shipvo status --json", why: "Check that phones pick up the rollback." }] };
 }

package/dist/qr.d.ts

@@ -0,0 +1,9 @@
+export declare const QR_MAX_BYTES = 134;
+/** Reed-Solomon error codewords for `data`. */
+export declare function rsRemainder(data: number[], degree: number): number[];
+/** The 15 format bits for level L and a mask number. */
+export declare function formatBits(mask: number): number;
+/** Encodes text as a QR code. Returns rows of modules, true for dark. Throws when the text is over 134 bytes. */
+export declare function qrMatrix(text: string): boolean[][];
+/** Draws the matrix for a terminal: black on white with ANSI colours, two rows per line, a 2 module quiet zone. */
+export declare function qrToTerminal(matrix: boolean[][], quiet?: number): string;