@shipvo/cli 0.0.1 → 0.1.1

package/dist/app.d.ts

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

package/dist/app.js

@@ -0,0 +1,62 @@
+// `shipvo app create`: register this app with the hosted control plane and get a scoped publish token.
+// `shipvo app list`: the apps your account has registered.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+import { savedCreds } from "./login.js";
+export async function appCmd(argv) {
+    const [sub] = argv;
+    const c = savedCreds();
+    if (!c) {
+        console.error("Not signed in. Run `shipvo login` first.");
+        process.exit(1);
+    }
+    if (sub === "list") {
+        const r = await fetch(`${c.control}/apps`, { headers: { authorization: `Bearer ${c.key}` } });
+        const d = await r.json();
+        if (!r.ok) {
+            console.error(d.hint ?? d.error);
+            process.exit(1);
+        }
+        console.log(d.apps.length ? d.apps.map((a) => `${a.app_id}  ${a.name}  r${a.latest_release ?? "-"}  ${(a.bytes_used / 1048576).toFixed(1)} MB  ${a.listed ? (a.approved ? "public" : "listing under review") : "private"}`).join("\n") : "No apps yet. Run `shipvo app create` inside an app made with `shipvo init`.");
+        return;
+    }
+    if (sub === "delete") {
+        const id = argv[1];
+        if (!id || !argv.includes("--yes")) {
+            console.error("Usage: shipvo app delete <app-id> --yes   (removes the app's published files, tokens and registration; installed shells keep the code they have)");
+            process.exit(2);
+        }
+        const r = await fetch(`${c.control}/apps/${id}`, { method: "DELETE", headers: { authorization: `Bearer ${c.key}` } });
+        const d = await r.json();
+        if (!r.ok) {
+            console.error(r.status === 404 ? `No app "${id}" on your account.` : d.hint ?? d.error);
+            process.exit(1);
+        }
+        console.log(`Deleted "${id}" (${d.files_deleted} files).`);
+        return;
+    }
+    if (sub !== "create") {
+        console.error("Usage: shipvo app create | list | delete <id> --yes");
+        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 d = await r.json();
+    if (!r.ok) {
+        console.error(`Could not register "${cfg.appId}": ${d.message ?? d.hint ?? d.error}`);
+        process.exit(1);
+    }
+    mkdirSync(join(process.cwd(), ".shipvo"), { recursive: true });
+    writeFileSync(join(process.cwd(), ".shipvo", "publish-token"), d.publish_token + "\n", { mode: 0o600 });
+    console.log(`${d.created ? "Registered" : "Updated"} "${d.app_id}" (publish token expires ${String(d.expires_at).slice(0, 10)}).`);
+    if (cfg.listing?.public)
+        console.log(`Listing requested: once reviewed, "${cfg.appId}" appears on shipvo.dev/apps and any signed-in agent can open it. Set listing.public to false in shipvo.json and run this again to withdraw.`);
+    else
+        console.log(`Private: only your key opens it. To list it publicly, add { "listing": { "public": true, "description": "...", "category": "shop" } } to shipvo.json and run this again.`);
+    console.log(`Token saved to .shipvo/publish-token (git-ignored), so \`shipvo publish\` works on this machine now.`);
+    console.log(`For CI, add two repository secrets: SHIPVO_PUBLISH_TOKEN (the token) and SHIPVO_SIGNING_SEED (from .shipvo/seed.txt).`);
+    if (cfg.controlPlane.replace(/\/$/, "") !== String(d.control_plane).replace(/\/$/, ""))
+        console.log(`Note: shipvo.json controlPlane is ${cfg.controlPlane}, but you registered on ${d.control_plane}. Installed shells only trust the one built into them.`);
+    console.log(`Agents can open it once published: open_app("${d.app_id}@latest") with your key from \`shipvo mcp\`.`);
+}

package/dist/cli.js

@@ -2,25 +2,56 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { b64, keyFromSeed, sha256Hex, signBytes, signDoc, verifyDoc } from "./index.js";
+import { seed } from "./config.js";
+import { init } from "./init.js";
+import { publish, rollback } from "./publish.js";
+import { sim } from "./sim.js";
+import { keys, login, mcp } from "./login.js";
+import { appCmd } from "./app.js";
 const [cmd, ...rest] = process.argv.slice(2);
-const seed = () => {
-    const s = process.env.PURENATIVE_SIGNING_SEED || (process.env.PURENATIVE_SIGNING_SEED_FILE && readFileSync(process.env.PURENATIVE_SIGNING_SEED_FILE, "utf8").trim());
-    if (!s) {
-        console.error("Set PURENATIVE_SIGNING_SEED or PURENATIVE_SIGNING_SEED_FILE");
-        process.exit(2);
-    }
-    return s;
-};
 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 PURENATIVE_SIGNING_SEED
+  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);
+        break;
+    case "sim":
+        await sim(rest);
+        break;
+    case "publish":
+        await publish(rest);
+        break;
+    case "rollback":
+        await rollback(rest);
+        break;
+    case "login":
+        await login(rest);
+        break;
+    case "app":
+        await appCmd(rest);
+        break;
+    case "keys":
+        await keys();
+        break;
+    case "mcp":
+        mcp();
+        break;
     case "keygen": {
         const s = b64(randomBytes(32));
         const out = rest[rest.indexOf("--out") + 1];

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+/** shipvo.json at the app root: what `shipvo init` writes and every other command reads. */
+export type ShipvoConfig = {
+    appId: string;
+    name: string;
+    shellMajor: number;
+    /** Control plane the shell trusts (also in app.json's @shipvo/runtime plugin props). */
+    controlPlane: string;
+    /** Base64 Ed25519 public key built into the shell. */
+    publicKey: string;
+    /** Where `shipvo publish` writes: the control plane's Cloudflare KV namespace. */
+    kv?: {
+        namespaceId: string;
+    };
+    /** Marketplace listing (hosted control plane): shown to agents and on shipvo.dev once reviewed. */
+    listing?: {
+        public?: boolean;
+        description?: string;
+        category?: string;
+    };
+};
+export declare function loadConfig(dir?: string): ShipvoConfig;
+export declare const args: (argv: string[]) => Record<string, string | undefined>;
+/** Signing seed: SHIPVO_SIGNING_SEED (PURENATIVE_SIGNING_SEED still accepted) or a *_FILE path. */
+export declare function seed(): string;
+/** The publish token `shipvo app create` issued: SHIPVO_PUBLISH_TOKEN (CI) or .shipvo/publish-token. */
+export declare function publishToken(): string | null;
+/** Where publish/rollback write: your own Cloudflare KV (self-hosted control plane) or the hosted control plane with a publish token. */
+export declare function kv(cfg: ShipvoConfig): {
+    get(k: string): Promise<string | null>;
+    getBytes(k: string): Promise<Uint8Array<ArrayBuffer> | null>;
+    keys(prefix: string): Promise<any>;
+    put(k: string, body: BodyInit, type: string): Promise<void>;
+};

package/dist/config.js

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export function loadConfig(dir = process.cwd()) {
+    const p = join(dir, "shipvo.json");
+    if (!existsSync(p))
+        throw new Error("No shipvo.json here. Run this inside an app created with `shipvo init`, or create one (see docs/getting-started.md).");
+    const c = JSON.parse(readFileSync(p, "utf8"));
+    for (const k of ["appId", "controlPlane", "publicKey"])
+        if (!c[k])
+            throw new Error(`shipvo.json: "${k}" is required`);
+    return { shellMajor: 1, name: c.appId, ...c };
+}
+const argPairs = (argv) => Object.fromEntries(argv.reduce((a, x, i, all) => (x.startsWith("--") ? [...a, [x.slice(2), all[i + 1] === undefined || all[i + 1].startsWith("--") ? "true" : all[i + 1]]] : a), []));
+export const args = (argv) => argPairs(argv);
+/** Signing seed: SHIPVO_SIGNING_SEED (PURENATIVE_SIGNING_SEED still accepted) or a *_FILE path. */
+export function seed() {
+    const e = process.env;
+    const s = e.SHIPVO_SIGNING_SEED || e.PURENATIVE_SIGNING_SEED
+        || ((e.SHIPVO_SIGNING_SEED_FILE || e.PURENATIVE_SIGNING_SEED_FILE) && readFileSync((e.SHIPVO_SIGNING_SEED_FILE || e.PURENATIVE_SIGNING_SEED_FILE), "utf8").trim());
+    const local = (() => { try {
+        return readFileSync(join(process.cwd(), ".shipvo", "seed.txt"), "utf8").trim();
+    }
+    catch {
+        return "";
+    } })(); // what `shipvo init` wrote
+    if (!s && local)
+        return local;
+    if (!s) {
+        console.error("Set SHIPVO_SIGNING_SEED or SHIPVO_SIGNING_SEED_FILE (the seed `shipvo keygen` printed), or keep it at .shipvo/seed.txt.");
+        process.exit(2);
+    }
+    return s;
+}
+/** The publish token `shipvo app create` issued: SHIPVO_PUBLISH_TOKEN (CI) or .shipvo/publish-token. */
+export function publishToken() {
+    if (process.env.SHIPVO_PUBLISH_TOKEN)
+        return process.env.SHIPVO_PUBLISH_TOKEN.trim();
+    try {
+        return readFileSync(join(process.cwd(), ".shipvo", "publish-token"), "utf8").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Publishing through the hosted control plane: the same get/put/keys, scoped to this app and signed-pointer checked server side. */
+function hostedKv(cfg, token) {
+    const base = `${cfg.controlPlane.replace(/\/$/, "")}/apps/${cfg.appId}/kv`;
+    const auth = { Authorization: `Bearer ${token}` };
+    const path = (k) => `${base}/${k.split("/").map(encodeURIComponent).join("/")}`;
+    return {
+        async get(k) { const r = await fetch(path(k), { headers: auth }); if (r.status === 401)
+            throw new Error("publish token rejected: run `shipvo app create` for a new one"); return r.ok ? r.text() : null; },
+        async getBytes(k) { const r = await fetch(path(k), { headers: auth }); return r.ok ? new Uint8Array(await r.arrayBuffer()) : null; },
+        async keys(prefix) { const r = await fetch(`${base}?prefix=${encodeURIComponent(prefix)}`, { headers: auth }); return r.ok ? (await r.json()).keys : []; },
+        async put(k, body, type) {
+            const r = await fetch(path(k), { method: "PUT", headers: { ...auth, "content-type": type }, body });
+            if (!r.ok) {
+                let m = "";
+                try {
+                    const j = await r.json();
+                    m = j.message ?? j.error;
+                }
+                catch { }
+                throw new Error(`publish ${k}: ${r.status} ${m}`);
+            }
+        },
+    };
+}
+/** Where publish/rollback write: your own Cloudflare KV (self-hosted control plane) or the hosted control plane with a publish token. */
+export function kv(cfg) {
+    const ACC = process.env.CLOUDFLARE_ACCOUNT_ID, TOKEN = process.env.CLOUDFLARE_API_TOKEN;
+    const NS = process.env.SHIPVO_KV_ID || process.env.PURENATIVE_KV_ID || cfg.kv?.namespaceId;
+    if (!(ACC && TOKEN && NS)) {
+        const pt = publishToken();
+        if (pt)
+            return hostedKv(cfg, pt);
+        console.error("Nothing to publish with. Hosted: run `shipvo login`, then `shipvo app create` (or set SHIPVO_PUBLISH_TOKEN). Self-hosted: set CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN and SHIPVO_KV_ID.");
+        process.exit(2);
+    }
+    const url = (k) => `https://api.cloudflare.com/client/v4/accounts/${ACC}/storage/kv/namespaces/${NS}/values/${encodeURIComponent(k)}`;
+    const auth = { Authorization: `Bearer ${TOKEN}` };
+    return {
+        async get(k) { const r = await fetch(url(k), { headers: auth }); return r.ok ? r.text() : null; },
+        async getBytes(k) { const r = await fetch(url(k), { headers: auth }); return r.ok ? new Uint8Array(await r.arrayBuffer()) : null; },
+        async keys(prefix) {
+            const r = await fetch(`https://api.cloudflare.com/client/v4/accounts/${ACC}/storage/kv/namespaces/${NS}/keys?prefix=${encodeURIComponent(prefix)}&limit=1000`, { headers: auth });
+            return r.ok ? (await r.json()).result.map((k) => k.name) : [];
+        },
+        async put(k, body, type) {
+            const r = await fetch(url(k), { method: "PUT", headers: { ...auth, "content-type": type }, body });
+            if (!r.ok)
+                throw new Error(`KV put ${k}: ${r.status} ${await r.text()}`);
+        },
+    };
+}

package/dist/init.d.ts

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

package/dist/init.js

@@ -0,0 +1,193 @@
+// `shipvo init <dir>`: a new Expo app wired to Shipvo: signed OTA runtime + plugin, the device API, the simulator,
+// a publish workflow and a shipvo.json. Everything an agent needs to open it is in place on the first commit.
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join, resolve } from "node:path";
+import { b64, keyFromSeed } from "./index.js";
+import { args as parse } from "./config.js";
+const HOSTED = "https://api.shipvo.dev";
+const SDK = { expo: "~58.0.21", camera: "~58.0.14", clipboard: "~58.0.4", localAuth: "~58.0.2", location: "~58.0.20", notifications: "~58.1.7", statusBar: "~58.0.4", constants: "~58.0.0", metroRuntime: "~58.0.15", react: "19.3.0", rn: "0.88.1", rnw: "^0.21.4" };
+const title = (s) => s.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+export async function init(argv) {
+    const [dirArg] = argv.filter((x) => !x.startsWith("--") && !argv[argv.indexOf(x) - 1]?.startsWith("--"));
+    const a = parse(argv);
+    if (!dirArg) {
+        console.error("Usage: shipvo init <dir> [--app-id myshop] [--name \"My Shop\"] [--control-plane URL] [--public-key B64] [--bundle-id com.example.myshop]");
+        process.exit(2);
+    }
+    const dir = resolve(dirArg);
+    if (existsSync(dir)) {
+        console.error(`${dir} already exists`);
+        process.exit(1);
+    }
+    const appId = (a["app-id"] || dirArg.split("/").pop().toLowerCase().replace(/[^a-z0-9-]/g, "-")).slice(0, 32);
+    const name = a.name || title(appId);
+    const controlPlane = (a["control-plane"] || HOSTED).replace(/\/$/, "");
+    const bundleId = a["bundle-id"] || `dev.shipvo.${appId.replace(/-/g, "")}`;
+    // Signing key: use the one given, or make one. The seed never enters the repo; the public key is pinned in the shell.
+    let publicKey = a["public-key"], seedNote = "";
+    if (!publicKey) {
+        const seed = b64(randomBytes(32));
+        publicKey = b64(keyFromSeed(seed).publicKey);
+        mkdirSync(join(dir, ".shipvo"), { recursive: true });
+        writeFileSync(join(dir, ".shipvo", "seed.txt"), seed, { mode: 0o600 });
+        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("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" },
+        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" },
+    }, null, 2) + "\n");
+    w("app.json", JSON.stringify({ expo: {
+            name, slug: appId, version: "1.0.0", orientation: "portrait", userInterfaceStyle: "automatic",
+            ios: { bundleIdentifier: bundleId, supportsTablet: false },
+            android: { package: bundleId, versionCode: 1, predictiveBackGestureEnabled: false },
+            web: { output: "single" },
+            plugins: [
+                ["@shipvo/runtime", { baseUrl: controlPlane, publicKey, appId, shellMajor: 1 }],
+                ["expo-camera", { cameraPermission: `${name} uses the camera to scan codes.` }],
+                ["expo-location", { locationWhenInUsePermission: `${name} uses your location to find what is near you.` }],
+                ["expo-local-authentication", { faceIDPermission: `${name} uses Face ID to confirm actions.` }],
+                ["expo-notifications", {}],
+            ],
+        } }, null, 2) + "\n");
+    w("tsconfig.json", JSON.stringify({ extends: "expo/tsconfig.base", compilerOptions: { strict: true, allowImportingTsExtensions: true, noEmit: true }, exclude: ["node_modules"] }, null, 2) + "\n");
+    w("metro.config.js", `// Shipvo: PN_SIM=1 web builds use the simulated device (system sheets in the accessibility tree) instead of Expo's native modules.
+const { getDefaultConfig } = require("expo/metro-config");
+const withShipvoSim = require("@shipvo/device/metro");
+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." };
+`);
+    w("App.tsx", APP_TSX(name, appId));
+    w(".github/workflows/publish.yml", WORKFLOW);
+    w("README.md", README(name, appId, controlPlane));
+    console.log(`
+Created ${name} in ${dirArg}
+
+  cd ${dirArg}
+  npm install                 # or pnpm / bun
+  npx playwright install chromium
+  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)
+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)
+
+${seedNote}
+Public key pinned in the shell: ${publicKey}
+`);
+}
+const APP_TSX = (name, appId) => `import { useEffect, useRef, useState } from "react";
+import { AppState, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
+import { StatusBar } from "expo-status-bar";
+import { Runtime } from "@shipvo/runtime";
+import { device } from "@shipvo/device";
+import { ScanHost } from "@shipvo/device/scan";
+import { RELEASE } from "./src/release";
+
+const POLL_MS = 10_000;
+
+export default function App() {
+  const [state] = useState(() => { try { return Runtime.getState(); } catch { return null; } });
+  const [log, setLog] = useState<string[]>([]);
+  const busy = useRef(false);
+  const add = (t: string) => setLog((l) => [t, ...l].slice(0, 20));
+
+  // 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 {}
+    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"})\`); }
+      finally { busy.current = false; }
+    };
+    check(); const id = setInterval(() => { if (AppState.currentState === "active") check(); }, POLL_MS);
+    return () => clearInterval(id);
+  }, []);
+
+  // Device API: real on phones, simulated in the simulator (agents answer the system sheets and set what the camera sees).
+  const scan = async () => { try { const r = await device.camera.scan({ prompt: "Point at a code" }); add(r ? \`Scanned \${r.data}\` : "Scan cancelled"); } catch (e: any) { add(String(e.message)); } };
+  const locate = async () => { try { const c = await device.location.current(); add(\`At \${c.latitude.toFixed(4)}, \${c.longitude.toFixed(4)}\`); } catch (e: any) { add(String(e.message)); } };
+  const notify = async () => { await device.notifications.show({ title: "${name}", body: "Hello from a notification.", data: {} }); add("Notification sent"); };
+  const confirm = async () => { const r = await device.auth.confirm("Confirm it is you"); add(r.ok ? "Confirmed" : \`Not confirmed (\${r.reason})\`); };
+
+  return (
+    <View style={s.root}>
+      <StatusBar style="dark" />
+      <ScrollView contentContainerStyle={s.page}>
+        <Text style={s.h1} accessibilityRole="header">${name}</Text>
+        <View style={s.hero}><Text style={s.heroText}>{RELEASE.headline}</Text><Text style={s.heroNote}>{RELEASE.note}</Text></View>
+        <Text style={s.h2} accessibilityRole="header">Try the device</Text>
+        <Btn label="Scan a code" onPress={scan} />
+        <Btn label="Use my location" onPress={locate} />
+        <Btn label="Confirm with fingerprint" onPress={confirm} />
+        <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>
+      </ScrollView>
+      <ScanHost accent="#1F4E5F" />
+    </View>
+  );
+}
+
+function Btn({ label, onPress }: { label: string; onPress: () => void }) {
+  return <Pressable accessibilityRole="button" accessibilityLabel={label} onPress={onPress} style={s.btn}><Text style={s.btnText}>{label}</Text></Pressable>;
+}
+
+const s = StyleSheet.create({
+  root: { flex: 1, backgroundColor: "#F6F8F7" },
+  page: { padding: 20, paddingTop: 56, gap: 12 },
+  h1: { fontSize: 28, fontWeight: "800", color: "#111" }, h2: { fontSize: 17, fontWeight: "700", color: "#111", marginTop: 8 },
+  hero: { backgroundColor: "#1F4E5F", borderRadius: 16, padding: 20, gap: 6 },
+  heroText: { color: "#fff", fontSize: 20, fontWeight: "800" }, heroNote: { color: "#fff", opacity: 0.9 },
+  btn: { minHeight: 48, borderRadius: 10, borderWidth: 1, borderColor: "#CBD5D1", alignItems: "center", justifyContent: "center", backgroundColor: "#fff" },
+  btnText: { fontSize: 16, fontWeight: "700", color: "#111" },
+  line: { fontSize: 14, color: "#111" }, muted: { fontSize: 13, color: "#5B6B66" },
+});
+`;
+const WORKFLOW = `name: publish
+on:
+  push:
+    branches: [main]
+    paths: ["src/**", "App.tsx"]
+  workflow_dispatch:
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    concurrency: shipvo-publish
+    if: \${{ github.event_name != 'push' || !contains(github.event.head_commit.message, '[no-ota]') }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci
+      - run: pip install --break-system-packages bsdiff4
+      - name: Build, sign and publish over the air
+        env:
+          SHIPVO_PUBLISH_TOKEN: \${{ secrets.SHIPVO_PUBLISH_TOKEN }}   # from \`shipvo app create\`; self-hosting instead: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, SHIPVO_KV_ID
+          SHIPVO_SIGNING_SEED: \${{ secrets.SHIPVO_SIGNING_SEED }}
+        run: npx shipvo publish | tee -a "$GITHUB_STEP_SUMMARY"
+`;
+const README = (name, appId, cp) => `# ${name}
+
+A [Shipvo](https://github.com/shipvo/shipvo) app: one React Native codebase that people install from the stores and AI agents operate in a simulator, kept current with signed over-the-air releases.
+
+- \`npm run sim\` opens it in the simulator; \`npx -y @shipvo/mcp\` lets Claude, Cursor or ChatGPT use it (\`open_app("${appId}")\`).
+- \`npx expo run:android\` builds the native shell (the trust root and control plane \`${cp}\` are pinned in it).
+- Push to \`main\`: the publish workflow signs the new JavaScript and every phone and simulator gets it.
+- \`src/release.ts\` is the first thing to edit; \`App.tsx\` shows the device API (camera, location, biometrics, notifications).
+`;

package/dist/login.d.ts

@@ -0,0 +1,9 @@
+export declare function savedCreds(): {
+    key: string;
+    control: string;
+    mcp_url: string;
+    login?: string;
+} | null;
+export declare function login(argv: string[]): Promise<void>;
+export declare function keys(): Promise<void>;
+export declare function mcp(): void;

package/dist/login.js

@@ -0,0 +1,77 @@
+// `shipvo login`: sign in with GitHub (device flow) and get an API key for the hosted simulator.
+// `shipvo keys`: show the stored key's status. `shipvo mcp`: print the MCP config for agents.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { args as parse } from "./config.js";
+const HOSTED = "https://api.shipvo.dev";
+const credFile = () => join(process.env.SHIPVO_HOME || join(homedir(), ".shipvo"), "credentials.json");
+export function savedCreds() {
+    try {
+        return JSON.parse(readFileSync(credFile(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function login(argv) {
+    const a = parse(argv);
+    const control = (a["control-plane"] || process.env.SHIPVO_CONTROL || HOSTED).replace(/\/$/, "");
+    const start = await fetch(`${control}/auth/device/start`, { method: "POST" });
+    const s = await start.json();
+    if (!start.ok) {
+        console.error(`Login is not available on ${control}: ${s.message ?? s.error}`);
+        process.exit(1);
+    }
+    console.log(`\nOpen ${s.verification_uri} and enter the code:\n\n    ${s.user_code}\n\nWaiting for GitHub…`);
+    const deadline = Date.now() + (s.expires_in ?? 900) * 1000;
+    let interval = (s.interval ?? 5) * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, interval));
+        const r = await fetch(`${control}/auth/device/poll`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ device_code: s.device_code }) });
+        const d = await r.json();
+        if (r.status === 202) {
+            if (d.status === "slow_down")
+                interval += 5000;
+            continue;
+        }
+        if (!r.ok) {
+            console.error(`Login failed: ${d.status ?? d.error}`);
+            process.exit(1);
+        }
+        mkdirSync(join(credFile(), ".."), { recursive: true });
+        writeFileSync(credFile(), JSON.stringify({ key: d.key, control, mcp_url: d.mcp.url, login: d.login, apps: d.apps, saved_at: new Date().toISOString() }, null, 2), { mode: 0o600 });
+        console.log(`\nSigned in as ${d.login}. Key ${d.prefix}… saved to ${credFile()} (quota: ${d.quota_minutes} sandbox minutes; expires ${String(d.expires_at).slice(0, 10)}; apps: ${d.apps.join(", ")}).\n`);
+        printMcp(d.mcp.url, d.key);
+        return;
+    }
+    console.error("Timed out waiting for GitHub.");
+    process.exit(1);
+}
+export async function keys() {
+    const c = savedCreds();
+    if (!c) {
+        console.error("Not signed in. Run `shipvo login`.");
+        process.exit(1);
+    }
+    const r = await fetch(`${c.control}/auth/me`, { headers: { authorization: `Bearer ${c.key}` } });
+    const d = await r.json();
+    if (!r.ok) {
+        console.error(d.error === "key_expired" ? `Key ${c.key.slice(0, 12)}… expired on ${d.expires_at}. Run \`shipvo login\` to get a new one.` : `Key ${c.key.slice(0, 12)}… is not valid any more (${d.error}). Run \`shipvo login\`.`);
+        process.exit(1);
+    }
+    console.log(JSON.stringify({ login: d.github_login, prefix: d.prefix, scope: d.scope, app: d.app_id, expires_at: d.expires_at, used_minutes: d.used_minutes, quota_minutes: d.quota_minutes, last_used_at: d.last_used_at, mcp_url: c.mcp_url }, null, 2));
+}
+export function mcp() {
+    const c = savedCreds();
+    if (!c) {
+        console.error("Not signed in. Run `shipvo login`.");
+        process.exit(1);
+    }
+    printMcp(c.mcp_url, c.key);
+}
+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`);
+    console.log(`Local simulator instead: { "mcpServers": { "shipvo": { "command": "npx", "args": ["-y", "@shipvo/mcp"] } } } after \`shipvo sim\`.`);
+}

package/dist/publish.d.ts

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

package/dist/publish.js

@@ -0,0 +1,153 @@
+// `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 { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sha256Hex, signBytes } from "./index.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 walk = (d) => readdirSync(d).flatMap((f) => (statSync(join(d, f)).isDirectory() ? walk(join(d, f)) : [join(d, f)]));
+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 { }
+    }
+    return max;
+}
+export async function publish(argv) {
+    const a = parse(argv), cfg = loadConfig(), SEED = seed(), kv = 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
+    const bands = (a.bands || "b0,b1,b2").split(",");
+    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);
+        }
+        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) });
+        }
+    }
+    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));
+            }
+            await kv.put(`${base}/${rel}`, new Uint8Array(body), MIME[rel.slice(rel.lastIndexOf("."))] ?? "application/octet-stream");
+            files.push(rel);
+        }
+        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}/`);
+    }
+    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");
+    }
+    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) })) }));
+}
+export async function rollback(argv) {
+    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]");
+        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");
+    }
+    console.log(JSON.stringify({ app: APP, rolled_back_to_code_of: to, new_release: release, min_shell_version: minShell, issued_at }));
+}

package/dist/sim.d.ts

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

package/dist/sim.js

@@ -0,0 +1,25 @@
+// `shipvo sim`: build the app's web bundle with the simulated device and serve it in the simulator.
+import { execSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { args as parse, loadConfig } from "./config.js";
+export async function sim(argv) {
+    const a = parse(argv);
+    const cfg = loadConfig();
+    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" } });
+    }
+    let server;
+    try {
+        server = createRequire(process.cwd() + "/package.json").resolve("@shipvo/sim/server.mjs");
+    }
+    catch {
+        console.error("Install @shipvo/sim (and playwright) in this app: npm i -D @shipvo/sim playwright && npx playwright install chromium");
+        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));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/cli",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "type": "module",
   "license": "Apache-2.0",
   "bin": {
@@ -18,7 +18,7 @@
     "vitest": "^2.1.4",
     "@types/node": "^22.8.0"
   },
-  "description": "Shipvo CLI: Ed25519 signing, hashing and publishing of over-the-air React Native releases.",
+  "description": "Shipvo CLI: create an app (init), run it in the simulator (sim), sign and publish over-the-air releases (publish, rollback), manage signing keys.",
   "keywords": [
     "react-native",
     "expo",
@@ -58,7 +58,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
     "test": "vitest run"
   }
 }