@shipvo/cli 0.1.1 → 0.1.3

package/README.md

@@ -3,11 +3,33 @@
 Command-line tools for [Shipvo](https://github.com/shipvo/shipvo), the open-source React Native framework for signed over-the-air updates.
 
 ```bash
-npx @shipvo/cli keygen --out seed.txt   # Ed25519 release signing key
-npx @shipvo/cli hash bundle.hbc         # SHA-256 and size
-npx @shipvo/cli sign-file bundle.hbc    # signature over bytes
+npx -y @shipvo/cli init my-app          # new app wired to Shipvo
+npx -y @shipvo/cli login                # sign in with GitHub, get a key for the hosted simulator
+npx -y @shipvo/cli app create           # register the app, save a publish token
+npx -y @shipvo/cli publish              # build, sign and ship an over-the-air release
+npx -y @shipvo/cli sim                  # serve the app in the simulator for agents
 ```
 
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init <dir>` | New app with the OTA runtime, device API, simulator and publish workflow |
+| `sim [--port 4545]` | Build for the simulator and serve it |
+| `publish [--bands b0,b1,b2]` | Build, sign and publish a release plus the agent-facing web artifact |
+| `rollback --to <release>` | Republish an earlier release's code as a new release |
+| `login` | Sign in with GitHub; issues a 30-day key |
+| `app create` / `list` / `delete <id> --yes` | Register the app (publish token), list yours, or remove one |
+| `keys` | Status and quota of the stored sign-in key |
+| `keys export [--out file]` | Print or save the release signing seed so you can back it up |
+| `keys import <seed>` / `--file f` / stdin | Restore the seed on a new machine; refused if it does not match `shipvo.json` |
+| `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>`, `verify <pointer> [key]` (release pointers) | Low-level signing helpers |
+
+Changing computers? See [Moving to a new machine](new-machine.md).
+
 Also usable as a library: `signDoc`, `verifyDoc`, `signBytes`, `sha256Hex`, `keyFromSeed`.
 
 License: Apache-2.0

package/dist/app.js

@@ -41,7 +41,7 @@ export async function appCmd(argv) {
         process.exit(2);
     }
     const cfg = loadConfig();
-    const r = await fetch(`${c.control}/apps`, { method: "POST", headers: { authorization: `Bearer ${c.key}`, "content-type": "application/json" }, body: JSON.stringify({ app_id: cfg.appId, name: cfg.name, public_key: cfg.publicKey, description: cfg.listing?.description ?? "", category: cfg.listing?.category ?? "other", listed: !!cfg.listing?.public }) });
+    const r = await fetch(`${c.control}/apps`, { method: "POST", headers: { authorization: `Bearer ${c.key}`, "content-type": "application/json" }, body: JSON.stringify({ app_id: cfg.appId, name: cfg.name, public_key: cfg.publicKey, description: cfg.listing?.description ?? "", category: cfg.listing?.category ?? "other", listed: !!cfg.listing?.public, tagline: cfg.listing?.tagline ?? "", website: cfg.listing?.website ?? "" }) });
     const d = await r.json();
     if (!r.ok) {
         console.error(`Could not register "${cfg.appId}": ${d.message ?? d.hint ?? d.error}`);

package/dist/cli.js

@@ -7,26 +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
-  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);
@@ -43,11 +29,17 @@ switch (cmd) {
     case "login":
         await login(rest);
         break;
+    case "doctor":
+        await doctor(rest);
+        break;
     case "app":
         await appCmd(rest);
         break;
     case "keys":
-        await keys();
+        if (rest[0] === "export" || rest[0] === "import")
+            await signingKey(rest);
+        else
+            await keys();
         break;
     case "mcp":
         mcp();
@@ -86,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;
@@ -16,6 +18,11 @@ export type ShipvoConfig = {
         public?: boolean;
         description?: string;
         category?: string;
+        tagline?: string;
+        icon?: string;
+        screenshots?: string[];
+        website?: string;
+        capabilities?: string[];
     };
 };
 export declare function loadConfig(dir?: string): ShipvoConfig;

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

@@ -34,17 +34,17 @@ export async function init(argv) {
         seedNote = `A release signing key was created at .shipvo/seed.txt (git-ignored). Back it up offline and put it in the SHIPVO_SIGNING_SEED secret of your CI. Lose it and you cannot publish to installed shells.`;
     }
     const w = (p, body) => { mkdirSync(join(dir, p, ".."), { recursive: true }); writeFileSync(join(dir, p), body); };
-    w("shipvo.json", JSON.stringify({ appId, name, shellMajor: 1, controlPlane, publicKey, listing: { public: false, description: "", category: "other" } }, null, 2) + "\n");
+    w("shipvo.json", JSON.stringify({ appId, name, shellMajor: 1, controlPlane, publicKey, listing: { public: false, tagline: "", description: "", category: "other", icon: "assets/icon.png", screenshots: [], website: "", capabilities: ["camera", "location", "biometrics", "payments", "notifications"] } }, null, 2) + "\n");
     w("package.json", JSON.stringify({
         name: appId, version: "1.0.0", main: "index.ts", private: true,
-        scripts: { start: "expo start", android: "expo run:android", ios: "expo run:ios", web: "expo start --web", sim: "shipvo sim", publish: "shipvo publish", rollback: "shipvo rollback", typecheck: "tsc --noEmit" },
+        scripts: { start: "expo start", test: "vitest run", android: "expo run:android", ios: "expo run:ios", web: "expo start --web", sim: "shipvo sim", publish: "shipvo publish", rollback: "shipvo rollback", typecheck: "tsc --noEmit" },
         dependencies: {
             "@expo/metro-runtime": SDK.metroRuntime, expo: SDK.expo, "expo-camera": SDK.camera, "expo-clipboard": SDK.clipboard, "expo-constants": SDK.constants,
             "expo-local-authentication": SDK.localAuth, "expo-location": SDK.location, "expo-notifications": SDK.notifications, "expo-status-bar": SDK.statusBar,
             react: SDK.react, "react-dom": SDK.react, "react-native": SDK.rn, "react-native-web": SDK.rnw,
             "@shipvo/device": "^0.1.0", "@shipvo/runtime": "^0.1.0",
         },
-        devDependencies: { "@shipvo/cli": "^0.1.0", "@shipvo/sim": "^0.1.0", "@types/react": "~19.3.0", playwright: "^1.63.0", typescript: "~6.0.3" },
+        devDependencies: { "@shipvo/cli": "^0.1.0", "@shipvo/sim": "^0.1.0", "@shipvo/test": "^0.1.0", "@types/react": "~19.3.0", playwright: "^1.63.0", typescript: "~6.0.3", vitest: "^2.1.4" },
     }, null, 2) + "\n");
     w("app.json", JSON.stringify({ expo: {
             name, slug: appId, version: "1.0.0", orientation: "portrait", userInterfaceStyle: "automatic",
@@ -68,10 +68,13 @@ 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 push to main." };
+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);
+    w(".github/workflows/test.yml", TEST_WORKFLOW);
+    w("tests/app.test.ts", TEST_APP(name));
+    w("vitest.config.ts", VITEST_CONFIG);
     w("README.md", README(name, appId, controlPlane));
     console.log(`
 Created ${name} in ${dirArg}
@@ -82,7 +85,7 @@ Created ${name} in ${dirArg}
   npm run sim                 # the app in the simulator on http://localhost:4545
   npx -y @shipvo/mcp          # point Claude / Cursor / ChatGPT at it and open_app("${appId}")
 
-Phones:  npx expo run:android   (needs Android Studio once; the OTA runtime is Android-first)
+Phones:  npx expo run:android   (needs Android Studio once). iOS: npx expo run:ios, then shipvo publish --platform all
 Publish: shipvo login, then shipvo app create (hosted), or set CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID and SHIPVO_KV_ID (self-hosted); then npm run publish
          (self-hosting instead? see docs/self-hosting.md)
 
@@ -108,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"})\`); }
@@ -137,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>
@@ -159,6 +162,79 @@ const s = StyleSheet.create({
   line: { fontSize: 14, color: "#111" }, muted: { fontSize: 13, color: "#5B6B66" },
 });
 `;
+const TEST_WORKFLOW = `name: test
+# Runs your app in the Shipvo simulator on a plain Linux runner (no emulator, no device) and fails the build if it breaks.
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_call:
+jobs:
+  simulator:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - name: Build the app for the simulator and serve it
+        run: |
+          npx shipvo sim --port 4545 > sim.log 2>&1 &
+          for i in $(seq 1 180); do curl -sf localhost:4545/app/ >/dev/null && break; sleep 1; done
+          curl -sf localhost:4545/app/ >/dev/null || { cat sim.log; exit 1; }
+      - name: Test the app in the simulator
+        run: npx vitest run
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with: { name: simulator-log, path: sim.log }
+`;
+const TEST_APP = (name) => `// Tests that run your app in the Shipvo simulator: a phone-sized, headless copy of the real app. No emulator, no device.
+// 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 headline", async ({ phone }) => {
+  expect(phone).toSee("Hello from ${name}.");
+  expect(phone.screen).not.toMatch(/something went wrong|unhandled|exception/i);
+});
+
+test("location: the app asks, then reads the phone's location", async ({ phone }) => {
+  await phone.device.set({ location: { latitude: 4.0511, longitude: 9.7679 } });
+  await phone.tap("Use my location");
+  expect(phone).toSee("access this device's location");
+  await phone.tap("While using the app");
+  await phone.waitFor(/4\\.05/);
+});
+
+test("camera: scanning reads what is in front of it", async ({ phone }) => {
+  await phone.device.set({ camera: { barcode: { type: "qr", data: "HELLO-123" } } });
+  await phone.tap("Scan a code");
+  await phone.tap("While using the app");
+  await phone.waitFor(/HELLO-123/);
+});
+
+test("fingerprint: success and failure are both handled", async ({ phone }) => {
+  await phone.device.set({ biometrics: { enrolled: true, nextResult: "success" } });
+  await phone.tap("Confirm with fingerprint");
+  await phone.tap("Use fingerprint");
+  await phone.waitFor("Confirmed");
+  await phone.device.set({ biometrics: { nextResult: "fail" } });
+  await phone.tap("Confirm with fingerprint");
+  await phone.tap("Use fingerprint");
+  await phone.waitFor(/Not confirmed/);
+});
+
+test("notifications: a push can be opened from the shade", async ({ phone }) => {
+  await phone.tap("Send a notification");
+  expect(await phone.notifications()).toHaveLength(1);
+  await phone.openNotification();
+  expect(await phone.deviceLog()).toContainEqual(expect.objectContaining({ kind: "notification_opened" }));
+});
+`;
+const VITEST_CONFIG = `import { defineConfig } from "vitest/config";
+export default defineConfig({ test: { include: ["tests/**/*.test.ts"], testTimeout: 30_000 } });
+`;
 const WORKFLOW = `name: publish
 on:
   push:
@@ -166,7 +242,10 @@ on:
     paths: ["src/**", "App.tsx"]
   workflow_dispatch:
 jobs:
+  test:
+    uses: ./.github/workflows/test.yml   # the simulator test must pass before anything ships to phones
   publish:
+    needs: test
     runs-on: ubuntu-latest
     concurrency: shipvo-publish
     if: \${{ github.event_name != 'push' || !contains(github.event.head_commit.message, '[no-ota]') }}

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,153 +1,319 @@
 // `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 { 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", ".ttf": "font/ttf", ".svg": "image/svg+xml" };
+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. */
 async function currentRelease(kv, app, major) {
     let max = 0;
-    for (const b of ["b0", "b1", "b2"]) {
-        const raw = await kv.get(`p/${app}/${major}/${b}`);
-        if (raw)
-            try {
-                max = Math.max(max, JSON.parse(JSON.parse(raw).body).release);
-            }
-            catch { }
-    }
+    for (const b of ["b0", "b1", "b2"])
+        for (const k of [`p/${app}/${major}/${b}`, `p/${app}/${major}/ios/${b}`]) {
+            const raw = await kv.get(k);
+            if (raw)
+                try {
+                    max = Math.max(max, JSON.parse(JSON.parse(raw).body).release);
+                }
+                catch { }
+        }
     return max;
 }
+const pointerKey = (app, major, band, pf) => (pf === "ios" ? `p/${app}/${major}/ios/${band}` : `p/${app}/${major}/${band}`);
+/** Android keeps its original key names; iOS bundles, patches and history are namespaced so the two never collide. */
+const bundleName = (release, pf) => (pf === "ios" ? `ios-r${release}.hbc` : `r${release}.hbc`);
+const platformsOf = (a) => {
+    const p = (a.platform || "android").toLowerCase();
+    if (p === "all")
+        return ["android", "ios"];
+    if (p === "android" || p === "ios")
+        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;
-    if (a["skip-export"] !== "true")
-        execSync("npx expo export --platform android --output-dir dist-ota --clear", { stdio: "inherit" });
-    const jsDir = "dist-ota/_expo/static/js/android";
-    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 name = `r${release}.hbc`, newSha = sha256Hex(bytes);
-    await kv.put(`b/${APP}/${name}`, bytes, "application/octet-stream");
-    // Patches from recent releases and from each shell's embedded bundle; devices verify the patched result against the signed sha256.
-    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 {
-        return JSON.parse((await kv.get(k)));
-    }
-    catch {
-        return null;
-    } })))
-        .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}/`)) {
-        try {
-            const b = JSON.parse((await kv.get(k)));
-            bases.set(b.sha256, b.key);
+    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}`;
+        if (a["skip-export"] !== "true")
+            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: 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 = [];
+        {
+            const MAX_BASES = Number(a["max-bases"] || 6);
+            const bases = new Map();
+            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 {
+                return null;
+            } })))
+                .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}/${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 {
+                    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")));
+                    if (patch.length >= bytes.length * 0.6)
+                        continue;
+                    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"}`);
         }
-        catch { }
-    }
-    const patches = [];
-    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-"));
-        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")));
-            if (patch.length >= bytes.length * 0.6)
-                continue;
-            const pkey = `b/${APP}/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) });
+        // 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);
         }
-    }
-    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.
-    let web = null;
-    if (a["skip-web"] !== "true") {
-        execSync("PN_SIM=1 npx expo export --platform web --output-dir dist-web --clear", { stdio: "inherit" });
-        const base = `w/${APP}/r${release}`;
-        const files = [];
-        let indexSha = "";
-        for (const f of walk("dist-web")) {
-            const rel = f.slice("dist-web/".length);
-            if (rel === "metadata.json")
-                continue;
-            let body = readFileSync(f);
-            if (rel === "index.html") {
-                body = Buffer.from(body.toString("utf8").replace(/(src|href)="\//g, `$1="/${base}/`));
-                indexSha = sha256Hex(new Uint8Array(body));
+        else if (a["skip-web"] !== "true") {
+            try {
+                web = JSON.parse((await kv.get(`h/${APP}/r${release}`)))?.web ?? null;
             }
-            await kv.put(`${base}/${rel}`, new Uint8Array(body), MIME[rel.slice(rel.lastIndexOf("."))] ?? "application/octet-stream");
-            files.push(rel);
+            catch { }
         }
-        web = { base: `/${base}/`, entry: "index.html", sha256: indexSha, files: files.length };
-        const idxKey = `w/${APP}/releases`;
-        let idx = { releases: [] };
-        try {
-            idx = JSON.parse((await kv.get(idxKey))) ?? idx;
+        const issued_at = new Date().toISOString();
+        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 } : {}), ...(web ? { web } : {}) });
+            await kv.put(pointerKey(APP, MAJOR, band, pf), JSON.stringify({ body, signature: signBytes(new TextEncoder().encode(body), SEED) }), "application/json");
         }
-        catch { }
-        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}/`);
+        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;
+    }
+    if (platforms.length === 1 && platforms[0] === "android") { // original single-platform output shape
+        const an = summary.android;
+        Object.assign(summary, { bytes: an.bytes, patches: an.patches });
+        delete summary.android;
+    }
+    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" });
+    const base = `w/${APP}/r${release}`;
+    const files = [];
+    let indexSha = "";
+    for (const f of walk("dist-web")) {
+        const rel = f.slice("dist-web/".length);
+        if (rel === "metadata.json")
+            continue;
+        let body = readFileSync(f);
+        if (rel === "index.html") {
+            body = Buffer.from(body.toString("utf8").replace(/(src|href)="\//g, `$1="/${base}/`));
+            indexSha = sha256Hex(new Uint8Array(body));
+        }
+        await kv.put(`${base}/${rel}`, new Uint8Array(body), MIME[rel.slice(rel.lastIndexOf("."))] ?? "application/octet-stream");
+        files.push(rel);
+    }
+    const web = { base: `/${base}/`, entry: "index.html", sha256: indexSha, files: files.length };
+    const idxKey = `w/${APP}/releases`;
+    let idx = { releases: [] };
+    try {
+        idx = JSON.parse((await kv.get(idxKey))) ?? idx;
+    }
+    catch { }
+    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}/`);
+    // 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 icon = L.icon ? await up(L.icon, "icon") : null;
+    const shots = [];
+    for (const [i, f] of (L.screenshots ?? []).entries()) {
+        const n = await up(f, `shot-${i + 1}`);
+        if (n)
+            shots.push(n);
     }
-    const issued_at = new Date().toISOString();
-    for (const band of bands) {
-        const body = JSON.stringify({ schema_version: "1.0", app_id: APP, shell_major: MAJOR, band, 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 } : {}) });
-        await kv.put(`p/${APP}/${MAJOR}/${band}`, JSON.stringify({ body, signature: signBytes(new TextEncoder().encode(body), SEED) }), "application/json");
+    let note = {};
+    try {
+        const src = readFileSync("src/release.ts", "utf8");
+        note = { headline: src.match(/headline:\s*"([^"]*)"/)?.[1], note: src.match(/note:\s*"([^"]*)"/)?.[1] };
     }
-    await kv.put(`h/${APP}/r${release}`, JSON.stringify({ release, issued_at, sha256: newSha, size: bytes.length, min_shell_version: MIN_SHELL, web }), "application/json");
-    console.log(JSON.stringify({ app: APP, release, bands, bytes: bytes.length, min_shell_version: MIN_SHELL, web, patches: patches.map((p) => ({ from: p.from_sha256.slice(0, 12), kb: +(p.size / 1024).toFixed(1) })) }));
+    catch { }
+    await kv.put(`${store}/manifest.json`, JSON.stringify({ icon, screenshots: shots, tagline: L.tagline ?? "", website: L.website ?? "", capabilities: L.capabilities ?? [], release, release_note: note, updated_at: new Date().toISOString() }), "application/json");
+    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) {
-        console.error("Usage: shipvo rollback --to <release> [--bands b0,b1,b2]");
+        console.error("Usage: shipvo rollback --to <release> [--bands b0,b1,b2] [--platform android|ios|all]");
         process.exit(2);
     }
-    const bytes = await kv.getBytes(`b/${APP}/r${to}.hbc`);
-    if (!bytes) {
-        console.error(`Release ${to} bundle not found`);
-        process.exit(1);
-    }
     const release = (await currentRelease(kv, APP, MAJOR)) + 1, issued_at = new Date().toISOString();
-    let minShell = "1.0.0", web = undefined;
-    try {
-        const h = JSON.parse((await kv.get(`h/${APP}/r${to}`)));
-        minShell = h.min_shell_version || minShell;
-        web = h.web ?? undefined;
-    }
-    catch { }
-    for (const band of (a.bands || "b0,b1,b2").split(",")) {
-        const body = JSON.stringify({ schema_version: "1.0", app_id: APP, shell_major: MAJOR, band, release, issued_at,
-            core: { version: `1.0.${release}`, sha256: sha256Hex(bytes), size: bytes.length, url: `b/${APP}/r${to}.hbc` }, addons: [], screens: [], min_shell_version: minShell, ...(web ? { web } : {}) });
-        await kv.put(`p/${APP}/${MAJOR}/${band}`, JSON.stringify({ body, signature: signBytes(new TextEncoder().encode(body), SEED) }), "application/json");
+    let minShell = "1.0.0";
+    for (const pf of platformsOf(a)) {
+        const bytes = await kv.getBytes(`b/${APP}/${bundleName(to, pf)}`);
+        if (!bytes) {
+            console.error(`Release ${to} ${pf} bundle not found`);
+            process.exit(1);
+        }
+        let web = undefined;
+        try {
+            const h = JSON.parse((await kv.get(pf === "ios" ? `h/${APP}/ios-r${to}` : `h/${APP}/r${to}`)));
+            minShell = h.min_shell_version || minShell;
+            web = h.web ?? undefined;
+        }
+        catch { }
+        for (const band of (a.bands || "b0,b1,b2").split(",")) {
+            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");
+        }
     }
     console.log(JSON.stringify({ app: APP, rolled_back_to_code_of: to, new_release: release, min_shell_version: minShell, issued_at }));
 }

package/dist/signing.d.ts

@@ -0,0 +1 @@
+export declare function signingKey(argv: string[]): Promise<void>;

package/dist/signing.js

@@ -0,0 +1,72 @@
+// `shipvo keys export` / `shipvo keys import`: move the release signing seed between machines.
+// The seed is the only thing that can update phones that already have the app installed
+// (every installed shell pins its public key), so moving it is an explicit step, not a hidden file copy.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { b64, keyFromSeed } from "./index.js";
+import { args, loadConfig, seed } from "./config.js";
+const pub = (s) => b64(keyFromSeed(s).publicKey);
+const valid = (s) => { try {
+    return /^[A-Za-z0-9+/=_-]{43,44}$/.test(s) && !!pub(s);
+}
+catch {
+    return false;
+} };
+export async function signingKey(argv) {
+    const [sub, ...rest] = argv, a = args(rest);
+    const cfg = loadConfig();
+    if (sub === "export") {
+        const s = seed();
+        if (pub(s) !== cfg.publicKey) {
+            console.error(`This seed does not match the public key in shipvo.json (${cfg.publicKey.slice(0, 12)}…). It would not be accepted by installed shells.`);
+            process.exit(1);
+        }
+        if (a.out && a.out !== "true") {
+            writeFileSync(a.out, s + "\n", { mode: 0o600 });
+            console.error(`Seed for "${cfg.appId}" written to ${a.out}. Store it in a password manager or an offline vault, then delete this file.`);
+        }
+        else {
+            console.error(`SECRET: anyone with this seed can ship code to every phone that has "${cfg.appId}". Keep it in a password manager; never paste it into chat, commits or tickets.\n`);
+            console.log(s);
+        }
+        console.error(`Public key (not secret, pinned in installed shells): ${cfg.publicKey}`);
+        return;
+    }
+    // import: seed from an argument, --file, or stdin
+    let s = rest.find((x, i) => !x.startsWith("--") && rest[i - 1] !== "--file") ?? "";
+    if (!s && a.file && a.file !== "true")
+        s = readFileSync(a.file, "utf8");
+    if (!s && !process.stdin.isTTY)
+        s = readFileSync(0, "utf8");
+    s = s.trim();
+    if (!s) {
+        console.error("Usage: shipvo keys import <seed>   |   shipvo keys import --file seed.txt   |   echo <seed> | shipvo keys import");
+        process.exit(2);
+    }
+    if (!valid(s)) {
+        console.error("That does not look like a Shipvo signing seed (a 32-byte value in base64).");
+        process.exit(1);
+    }
+    if (pub(s) !== cfg.publicKey) {
+        console.error(`This seed belongs to a different key (${pub(s).slice(0, 12)}…), but shipvo.json pins ${cfg.publicKey.slice(0, 12)}….\nPublishing with it would be rejected by the control plane and ignored by installed shells.`);
+        process.exit(1);
+    }
+    const dir = join(process.cwd(), ".shipvo"), file = join(dir, "seed.txt");
+    if (existsSync(file) && readFileSync(file, "utf8").trim() === s) {
+        console.log("Already in place. Nothing to do.");
+        return;
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(file, s + "\n", { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch { }
+    console.log(`Signing key for "${cfg.appId}" restored to .shipvo/seed.txt (matches shipvo.json).`);
+    try {
+        if (!/^\.shipvo\/?$/m.test(readFileSync(join(process.cwd(), ".gitignore"), "utf8")))
+            console.log("Warning: .gitignore does not ignore .shipvo/. Add it so the seed is never committed.");
+    }
+    catch { }
+    console.log("Next: `shipvo login` then `shipvo app create` to get a publish token on this machine.");
+}

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.1",
+  "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",