@shipvo/cli 0.1.2 → 0.1.3

package/README.md

@@ -26,7 +26,7 @@ npx -y @shipvo/cli sim                  # serve the app in the simulator for age
 | `mcp` | Print the MCP config agents need |
 | `keygen [--out seed.txt]` | Create an Ed25519 release signing key |
 | `pubkey` | Print the public key for the current seed |
-| `hash <file>`, `sign-file <file>`, `sign-json <file>`, `verify-json <file> <key>` | Low-level signing helpers |
+| `hash <file>`, `sign-file <file>`, `sign-json <file>`, `verify-json <file> <key>`, `verify <pointer> [key]` (release pointers) | Low-level signing helpers |
 
 Changing computers? See [Moving to a new machine](new-machine.md).
 

package/dist/cli.js

@@ -7,29 +7,12 @@ import { init } from "./init.js";
 import { publish, rollback } from "./publish.js";
 import { sim } from "./sim.js";
 import { keys, login, mcp } from "./login.js";
+import { verifyPointer } from "./verify.js";
 import { signingKey } from "./signing.js";
 import { appCmd } from "./app.js";
+import { doctor } from "./doctor.js";
+import { help, unknownCommand } from "./help.js";
 const [cmd, ...rest] = process.argv.slice(2);
-const help = `shipvo <command>
-
-  init <dir>                  New app wired to Shipvo: OTA runtime, device API, simulator, publish workflow
-  sim [--port 4545]           Build the app for the simulator and serve it (agents: open_app("<appId>"))
-  publish [--bands b0,b1,b2]  Build, sign and publish an over-the-air release (+ the agent-facing web artifact)
-  rollback --to <release>     Republish an earlier release's code as a new release
-  app create | list | delete  Register this app with the hosted control plane (publish token), list yours, or remove one
-  login                       Sign in with GitHub and get a key for the hosted simulator
-  keys                        Show the stored key's status and quota
-  keys export [--out f]       Print (or save) this app's release signing seed, to back it up or move machines
-  keys import [seed|--file f] Restore the signing seed on a new machine (checked against shipvo.json)
-  mcp                         Print the MCP config agents need (hosted and local)
-
-  keygen [--out seed.txt]     Create an Ed25519 release signing key; prints the public key
-  pubkey                      Print the public key for the seed in SHIPVO_SIGNING_SEED
-  hash <file>                 SHA-256 and size of a bundle
-  sign-file <file>            Ed25519 signature (base64) over a file's bytes
-  sign-json <file.json>       Sign a JSON document (canonical form); writes signature into it
-  verify-json <file.json> <public-key-b64>
-`;
 switch (cmd) {
     case "init":
         await init(rest);
@@ -46,6 +29,9 @@ switch (cmd) {
     case "login":
         await login(rest);
         break;
+    case "doctor":
+        await doctor(rest);
+        break;
     case "app":
         await appCmd(rest);
         break;
@@ -92,7 +78,31 @@ switch (cmd) {
         console.log(ok ? "valid" : "INVALID");
         process.exit(ok ? 0 : 1);
     }
-    default:
+    case "verify": {
+        if (!rest[0]) {
+            console.error("Usage: shipvo verify <pointer file> [public-key-b64]");
+            process.exit(2);
+        }
+        const key = rest[1] ?? b64(keyFromSeed(seed()).publicKey);
+        let text;
+        try {
+            text = readFileSync(rest[0], "utf8");
+        }
+        catch {
+            console.error(`Cannot read ${rest[0]}`);
+            process.exit(2);
+        }
+        const ok = verifyPointer(text, key);
+        console.log(ok ? "valid" : "INVALID");
+        process.exit(ok ? 0 : 1);
+    }
+    case undefined:
+    case "--help":
+    case "-h":
+    case "help":
         console.log(help);
-        process.exit(cmd ? 1 : 0);
+        break;
+    default:
+        console.error(unknownCommand(cmd));
+        process.exit(1);
 }

package/dist/config.d.ts

@@ -7,6 +7,8 @@ export type ShipvoConfig = {
     controlPlane: string;
     /** Base64 Ed25519 public key built into the shell. */
     publicKey: string;
+    /** Hermes bytecode version(s) the app's shells run. If set, `shipvo publish` refuses bundles that differ. */
+    hermesBytecodeVersion?: number | number[];
     /** Where `shipvo publish` writes: the control plane's Cloudflare KV namespace. */
     kv?: {
         namespaceId: string;

package/dist/doctor.d.ts

@@ -0,0 +1,17 @@
+import { existsSync } from "node:fs";
+type CheckResult = {
+    name: string;
+    ok: boolean;
+    fix: string;
+};
+type DoctorDeps = {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    nodeVersion: string;
+    fetchFn: typeof fetch;
+    fileExists: typeof existsSync;
+    readText: (path: string) => string;
+};
+export declare function runDoctorChecks(overrides?: Partial<DoctorDeps>): Promise<CheckResult[]>;
+export declare function doctor(argv: string[]): Promise<void>;
+export {};

package/dist/doctor.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { b64, keyFromSeed } from "./index.js";
+import { parseDeclared } from "./hermes.js";
+const defaultDeps = () => ({
+    cwd: process.cwd(),
+    env: process.env,
+    nodeVersion: process.versions.node,
+    fetchFn: fetch,
+    fileExists: existsSync,
+    readText: (path) => readFileSync(path, "utf8"),
+});
+const parseMajor = (v) => Number(v.split(".")[0] || 0);
+const pub = (s) => b64(keyFromSeed(s).publicKey);
+function resolveSeed(env, cwd, readText) {
+    const direct = env.SHIPVO_SIGNING_SEED || env.PURENATIVE_SIGNING_SEED;
+    if (direct)
+        return direct;
+    const file = env.SHIPVO_SIGNING_SEED_FILE || env.PURENATIVE_SIGNING_SEED_FILE;
+    if (file) {
+        try {
+            return readText(file).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        return readText(join(cwd, ".shipvo", "seed.txt")).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function loadShipvoConfig(deps) {
+    const path = join(deps.cwd, "shipvo.json");
+    if (!deps.fileExists(path)) {
+        return { cfg: null, parseCheck: { name: "shipvo.json parses", ok: false, fix: "run this in your app root (or create shipvo.json with `shipvo init`)" } };
+    }
+    try {
+        const cfg = JSON.parse(deps.readText(path));
+        return { cfg, parseCheck: { name: "shipvo.json parses", ok: true, fix: "none" } };
+    }
+    catch {
+        return { cfg: null, parseCheck: { name: "shipvo.json parses", ok: false, fix: "fix JSON syntax in shipvo.json" } };
+    }
+}
+export async function runDoctorChecks(overrides = {}) {
+    const deps = { ...defaultDeps(), ...overrides };
+    const results = [];
+    const nodeMajor = parseMajor(deps.nodeVersion);
+    results.push({
+        name: "Node version (>=22)",
+        ok: Number.isInteger(nodeMajor) && nodeMajor >= 22,
+        fix: "use Node 22 or newer (for example: `nvm use 22`)",
+    });
+    const { cfg, parseCheck } = loadShipvoConfig(deps);
+    results.push(parseCheck);
+    const signingOk = (() => {
+        if (!cfg?.publicKey || typeof cfg.publicKey !== "string")
+            return false;
+        const s = resolveSeed(deps.env, deps.cwd, deps.readText);
+        if (!s)
+            return false;
+        try {
+            return pub(s) === cfg.publicKey;
+        }
+        catch {
+            return false;
+        }
+    })();
+    const needCfg = "fix shipvo.json first";
+    results.push({ name: "signing key matches shipvo.json publicKey", ok: signingOk, fix: !cfg ? needCfg : "restore the right seed with `shipvo keys import` (or set SHIPVO_SIGNING_SEED)" });
+    let controlPlaneOk = false;
+    let cpFix = "check shipvo.json controlPlane and your network access (5 second timeout)";
+    if (cfg?.controlPlane && typeof cfg.controlPlane === "string") {
+        try {
+            const res = await deps.fetchFn(cfg.controlPlane.replace(/\/$/, ""), { signal: AbortSignal.timeout(5000) });
+            if (res.status >= 500)
+                cpFix = `the control plane answered HTTP ${res.status}; check its deploy and logs`;
+            else
+                controlPlaneOk = true;
+        }
+        catch { }
+    }
+    results.push({ name: "control plane reachable", ok: controlPlaneOk, fix: !cfg ? needCfg : cpFix });
+    let hermesOk = true;
+    if (cfg && Object.prototype.hasOwnProperty.call(cfg, "hermesBytecodeVersion")) {
+        try {
+            parseDeclared(cfg.hermesBytecodeVersion); // undefined means "not declared", which passes
+        }
+        catch {
+            hermesOk = false;
+        }
+    }
+    results.push({ name: "hermesBytecodeVersion (if present) is set", ok: hermesOk, fix: "set hermesBytecodeVersion to a positive integer or list (for example 96 or [96, 98])" });
+    return results;
+}
+export async function doctor(argv) {
+    if (argv.length) {
+        console.error("Usage: shipvo doctor");
+        process.exit(2);
+    }
+    const results = await runDoctorChecks();
+    for (const r of results)
+        console.log(`${r.ok ? `PASS ${r.name}` : `FAIL ${r.name} — fix: ${r.fix}`}`);
+    if (results.some((r) => !r.ok))
+        process.exit(1);
+}

package/dist/help.d.ts

@@ -0,0 +1,6 @@
+export declare const COMMANDS: readonly ["init", "sim", "publish", "rollback", "app", "login", "doctor", "keys", "mcp", "keygen", "pubkey", "hash", "sign-file", "sign-json", "verify-json", "verify"];
+export declare const help = "shipvo <command>\n\nStart\n  init <dir>                  Create a new app wired to Shipvo\n  sim [--port 4545]           Build the app and run it in the simulator\n\nShip\n  publish [--bands b0,b1,b2]  Build, sign and publish an over-the-air release\n  publish --dry-run [--out d] Check a release offline: build and sign, write nothing remote\n  rollback --to <release>     Republish an earlier release as a new release\n  app create | list | delete  Register, list or remove apps on the hosted control plane\n  login                       Sign in with GitHub and get a key for the hosted simulator\n  doctor                      Check setup before first publish\n  keys                        Show the stored key's status and quota\n  keys export [--out f]       Print or save this app's signing seed, to back it up\n  keys import [seed|--file f] Restore the signing seed on a new machine\n  mcp                         Print the MCP config that agents need\n\nAdvanced\n  keygen [--out seed.txt]     Create an Ed25519 signing key and print the public key\n  pubkey                      Print the public key for SHIPVO_SIGNING_SEED\n  hash <file>                 Print the SHA-256 and size of a file\n  sign-file <file>            Print the Ed25519 signature (base64) of a file\n  sign-json <file.json>       Sign a JSON document and write the signature into it\n  verify <pointer> [public-key-b64]\n                              Check a release pointer (such as one from publish --dry-run)\n  verify-json <file.json> <public-key-b64>\n                              Check the signature of a JSON document\n";
+export declare function distance(a: string, b: string): number;
+/** Closest command within edit distance 2, or undefined. */
+export declare function suggest(input: string): string | undefined;
+export declare function unknownCommand(input: string): string;

package/dist/help.js

@@ -0,0 +1,61 @@
+export const COMMANDS = [
+    "init", "sim", "publish", "rollback", "app", "login", "doctor", "keys", "mcp",
+    "keygen", "pubkey", "hash", "sign-file", "sign-json", "verify-json", "verify",
+];
+export const help = `shipvo <command>
+
+Start
+  init <dir>                  Create a new app wired to Shipvo
+  sim [--port 4545]           Build the app and run it in the simulator
+
+Ship
+  publish [--bands b0,b1,b2]  Build, sign and publish an over-the-air release
+  publish --dry-run [--out d] Check a release offline: build and sign, write nothing remote
+  rollback --to <release>     Republish an earlier release as a new release
+  app create | list | delete  Register, list or remove apps on the hosted control plane
+  login                       Sign in with GitHub and get a key for the hosted simulator
+  doctor                      Check setup before first publish
+  keys                        Show the stored key's status and quota
+  keys export [--out f]       Print or save this app's signing seed, to back it up
+  keys import [seed|--file f] Restore the signing seed on a new machine
+  mcp                         Print the MCP config that agents need
+
+Advanced
+  keygen [--out seed.txt]     Create an Ed25519 signing key and print the public key
+  pubkey                      Print the public key for SHIPVO_SIGNING_SEED
+  hash <file>                 Print the SHA-256 and size of a file
+  sign-file <file>            Print the Ed25519 signature (base64) of a file
+  sign-json <file.json>       Sign a JSON document and write the signature into it
+  verify <pointer> [public-key-b64]
+                              Check a release pointer (such as one from publish --dry-run)
+  verify-json <file.json> <public-key-b64>
+                              Check the signature of a JSON document
+`;
+export function distance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/** Closest command within edit distance 2, or undefined. */
+export function suggest(input) {
+    let best;
+    let bestD = 3;
+    for (const c of COMMANDS) {
+        const d = distance(input.toLowerCase(), c);
+        if (d < bestD) {
+            best = c;
+            bestD = d;
+        }
+    }
+    return best;
+}
+export function unknownCommand(input) {
+    const s = suggest(input);
+    return `shipvo: '${input}' is not a command.${s ? ` Did you mean '${s}'?` : ""}\nRun 'shipvo --help' to see all commands.\n`;
+}

package/dist/hermes.d.ts

@@ -0,0 +1,11 @@
+/** True if the bytes start with the Hermes bytecode magic number. */
+export declare const isHermesBytecode: (b: Uint8Array) => boolean;
+/** The bytecode version in the header, or null if this is not Hermes bytecode. */
+export declare function hermesBytecodeVersion(b: Uint8Array): number | null;
+/** Parse a declared version list such as "96" or "96,98" (CLI flag) or a number / number[] (shipvo.json). */
+export declare function parseDeclared(v: unknown): number[] | undefined;
+/**
+ * Decide what to record in the release. Returns the version (or undefined when nothing is known).
+ * Throws when the bundle is not bytecode but the app declares a bytecode version, or when the versions differ.
+ */
+export declare function checkBundle(file: string, bytes: Uint8Array, declared?: number[]): number | undefined;

package/dist/hermes.js

@@ -0,0 +1,41 @@
+// Read the Hermes bytecode version from a bundle header, and check it against what the app's shells declare.
+// A Hermes bytecode file starts with an 8-byte magic number (little-endian 0x1F1903C103BC1FC6),
+// followed by the bytecode format version as a 32-bit little-endian integer.
+// Layout source: the BytecodeFileHeader struct in facebook/hermes, include/hermes/BCGen/HBC/BytecodeFileFormat.h
+// (fields MAGIC, then VERSION).
+const MAGIC = [0xc6, 0x1f, 0xbc, 0x03, 0xc1, 0x03, 0x19, 0x1f];
+/** True if the bytes start with the Hermes bytecode magic number. */
+export const isHermesBytecode = (b) => b.length >= 12 && MAGIC.every((m, i) => b[i] === m);
+/** The bytecode version in the header, or null if this is not Hermes bytecode. */
+export function hermesBytecodeVersion(b) {
+    if (!isHermesBytecode(b))
+        return null;
+    return new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(8, true);
+}
+/** Parse a declared version list such as "96" or "96,98" (CLI flag) or a number / number[] (shipvo.json). */
+export function parseDeclared(v) {
+    if (v === undefined || v === null || v === "")
+        return undefined;
+    const list = Array.isArray(v) ? v : String(v).split(",");
+    const nums = list.map((x) => Number(String(x).trim()));
+    if (!nums.length || nums.some((n) => !Number.isInteger(n) || n <= 0))
+        throw new Error(`hermes bytecode version must be positive integers (got ${JSON.stringify(v)})`);
+    return nums;
+}
+/**
+ * Decide what to record in the release. Returns the version (or undefined when nothing is known).
+ * Throws when the bundle is not bytecode but the app declares a bytecode version, or when the versions differ.
+ */
+export function checkBundle(file, bytes, declared) {
+    const version = hermesBytecodeVersion(bytes);
+    if (version === null) {
+        if (file.endsWith(".hbc"))
+            throw new Error(`${file} has a .hbc name but no Hermes bytecode header. Was it compiled with hermesc?`);
+        if (declared)
+            throw new Error(`${file} is plain JavaScript, but the app declares Hermes bytecode version ${declared.join(", ")}. Enable Hermes bytecode in the export, or remove hermesBytecodeVersion.`);
+        return undefined;
+    }
+    if (declared && !declared.includes(version))
+        throw new Error(`${file} is Hermes bytecode version ${version}, but the app's shells run ${declared.join(", ")}. Build with the same Hermes as the shell, or update hermesBytecodeVersion if the shell changed.`);
+    return version;
+}

package/dist/init.js

@@ -68,7 +68,7 @@ module.exports = withShipvoSim(getDefaultConfig(__dirname));
     w("index.ts", `import { registerRootComponent } from "expo";\nimport App from "./App";\nregisterRootComponent(App);\n`);
     w(".gitignore", `node_modules/\n.expo/\ndist/\ndist-ota/\ndist-web/\nsim-dist/\nweb-build/\n/ios\n/android\n.kotlin/\n*.jks\n*.p8\n*.p12\n*.key\n*.mobileprovision\n*.tsbuildinfo\n.env*.local\n.DS_Store\n# never commit the release signing seed\n.shipvo/\n`);
     w("src/release.ts", `// Edit and push: the publish workflow signs and ships this to every installed phone and to the simulator.
-export const RELEASE = { headline: "Release 1: hello from ${name}.", note: "Edit src/release.ts and run \`shipvo publish\`." };
+export const RELEASE = { headline: "Hello from ${name}.", note: "Edit src/release.ts and run \`shipvo publish\`." };
 `);
     w("App.tsx", APP_TSX(name, appId));
     w(".github/workflows/publish.yml", WORKFLOW);
@@ -111,7 +111,7 @@ export default function App() {
 
   // Over-the-air updates: tell the runtime the first screen rendered (so this release is kept), then poll while open.
   useEffect(() => {
-    try { const h = Runtime.markHealthy(); add(\`Running release \${h.release}\`); } catch {}
+    try { const h = Runtime.markHealthy(); add(h.release ? \`Running release \${h.release}\` : "Running local build"); } catch {}
     const check = async () => {
       if (busy.current || !state?.baseUrl) return; busy.current = true;
       try { const r = await Runtime.checkForUpdate(true); if (r.status === "staged") add(\`Applied release \${r.release} (\${r.via ?? "full"})\`); }
@@ -140,7 +140,7 @@ export default function App() {
         <Btn label="Send a notification" onPress={notify} />
         <Text style={s.h2} accessibilityRole="header">Log</Text>
         {log.length === 0 ? <Text style={s.muted}>Nothing yet.</Text> : log.map((l, i) => <Text key={i} style={s.line}>{l}</Text>)}
-        <Text style={s.muted}>App id ${appId} · shell {state?.shellVersion ?? "none"} · release {state?.runningRelease ?? 0}</Text>
+        <Text style={s.muted}>App id ${appId} · shell {state?.shellVersion ?? "none"} · {state?.runningRelease ? \`release \${state.runningRelease}\` : "local build"}</Text>
       </ScrollView>
       <ScanHost accent="#1F4E5F" />
     </View>
@@ -194,8 +194,8 @@ const TEST_APP = (name) => `// Tests that run your app in the Shipvo simulator:
 // Run them with "npm test" (start the simulator first: npm run sim) and in CI (.github/workflows/test.yml).
 import { test, expect } from "@shipvo/test/vitest";
 
-test("the app opens and shows its release", async ({ phone }) => {
-  expect(phone).toSee(/Release \\d+/);
+test("the app opens and shows its headline", async ({ phone }) => {
+  expect(phone).toSee("Hello from ${name}.");
   expect(phone.screen).not.toMatch(/something went wrong|unhandled|exception/i);
 });
 

package/dist/login.js

@@ -65,11 +65,14 @@ export async function keys() {
 export function mcp() {
     const c = savedCreds();
     if (!c) {
-        console.error("Not signed in. Run `shipvo login`.");
-        process.exit(1);
+        printLocalMcp();
+        console.log("\nTo let agents open your published app from anywhere, run `shipvo login` for a hosted config.");
+        return;
     }
     printMcp(c.mcp_url, c.key);
 }
+const LOCAL_MCP = `Local simulator (no login needed). Run \`npm run sim\` first:\n${JSON.stringify({ mcpServers: { shipvo: { command: "npx", args: ["-y", "@shipvo/mcp"] } } }, null, 2)}`;
+function printLocalMcp() { console.log(LOCAL_MCP); }
 function printMcp(url, key) {
     console.log(`Claude Desktop / Cursor / Claude Code (remote):\n${JSON.stringify({ mcpServers: { shipvo: { url, headers: { Authorization: `Bearer ${key}` } } } }, null, 2)}\n`);
     console.log(`ChatGPT (custom MCP connector, cannot send headers): ${url}/${key}\n`);

package/dist/publish.d.ts

@@ -1,2 +1,11 @@
+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 =):\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 true           Reuse the last build in dist-ota/\n  --skip-web true              Do not publish the web copy for the simulator\n  --dry-run                    Build and sign, write files locally, send nothing\n  --out <dir>                  Where --dry-run writes files (default .shipvo/dry-run)\n  --help                       Show this help\n";
 export declare function publish(argv: string[]): Promise<void>;
+/** 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;
 export declare function rollback(argv: string[]): Promise<void>;

package/dist/publish.js

@@ -1,10 +1,11 @@
 // `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, resolve } from "node:path";
 import { sha256Hex, signBytes } from "./index.js";
+import { checkBundle, parseDeclared } from "./hermes.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,14 +34,80 @@ 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(" ")}`);
+    }
+}
+/** 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 =):
+  --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 true           Reuse the last build in dist-ota/
+  --skip-web true              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 = a["dry-run"] !== undefined; // a plain switch: any use turns it on
+    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 bands = (a.bands || "b0,b1,b2").split(",");
     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, ...(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}`;
@@ -51,15 +118,16 @@ export async function publish(argv) {
         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, on Android, each shell's embedded bundle); devices verify the patched result against the signed sha256.
+        // iOS patches only from earlier iOS releases: the iOS runtime has no embedded-bundle baseline yet.
         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 +135,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`);
-            for (const k of await kv.keys(`base/${APP}/`)) {
+                bases.set(h.sha256, `b/${APP}/${bundleName(h.release, pf)}`);
+            if (pf === "android")
+                for (const k of await kv.keys(`base/${APP}/`)) {
+                    try {
+                        const b = JSON.parse((await kv.get(k)));
+                        bases.set(b.sha256, b.key);
+                    }
+                    catch { }
+                }
+            // 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 {
-                    const b = JSON.parse((await kv.get(k)));
-                    bases.set(b.sha256, b.key);
+                    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.");
                 }
-                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");
             }
             if (bsdiff) {
                 const work = mkdtempSync(join(tmpdir(), "shipvo-"));
@@ -97,11 +169,14 @@ 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).
@@ -119,11 +194,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 } : {}), ...(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 } : {}), 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,7 +208,32 @@ 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) {
     execSync("PN_SIM=1 npx expo export --platform web --output-dir dist-web --clear", { stdio: "inherit" });
@@ -186,6 +287,7 @@ async function publishWeb(kv, cfg, APP, release) {
     return web;
 }
 export async function rollback(argv) {
+    checkFlags(argv, ["to", "bands", "platform"]);
     const a = parse(argv), cfg = loadConfig(), SEED = seed(), kv = kvFor(cfg);
     const APP = cfg.appId, MAJOR = cfg.shellMajor, to = Number(a.to);
     if (!to) {

package/dist/sim.js

@@ -2,10 +2,37 @@
 import { execSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 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). */
+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();
+    });
+}
 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 +45,10 @@ 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}  (open_app("${cfg.appId}") from @shipvo/mcp; Ctrl-C to stop)`);
+    }
 }

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;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "license": "Apache-2.0",
   "bin": {
@@ -11,7 +11,7 @@
   "dependencies": {
     "@noble/ed25519": "^2.1.0",
     "@noble/hashes": "^1.5.0",
-    "@shipvo/schema": "0.0.1"
+    "@shipvo/schema": "0.0.3"
   },
   "devDependencies": {
     "typescript": "^5.6.3",