@shipvo/cli 0.1.4 → 0.1.6

package/dist/init.js

@@ -1,25 +1,26 @@
 // `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 { existsSync, mkdirSync, readFileSync, 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";
 import { adopt, detectProject, isAdoptArgs, isBareApp, positional } from "./adopt.js";
+import { CliFailure, UsageError, runJson, trapExit } from "./json-out.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 TEMPLATES = ["blank", "content", "shop"];
 const INIT_NEEDS_DIR = `shipvo: init needs a folder name.
 Try:  shipvo init myshop
 This creates ./myshop with a ready app. Other options (app id, bundle id, control plane) have defaults; see 'shipvo init --help'.`;
-const INIT_HELP = `Usage: shipvo init <dir> [options]
+export const INIT_HELP = `Usage: shipvo init <dir> [options]
        shipvo init [.] [--dry-run] [--yes] [--device]   (adopt mode, inside an existing Expo or bare React Native app)
 
 Adopt mode: run it inside an Expo app (package.json with expo, plus app.json or app.config.js/ts).
 It shows a plan, then applies it after you confirm. It installs @shipvo/runtime, adds the config plugin
 and a signing key, writes shipvo.json, adds sim/publish/rollback scripts, and adds a publish workflow if
 there is none. It never overwrites a file and never touches ios/ or android/. It refuses apps that use
-expo-updates or CodePush. See docs/cli.md.
+expo-updates or CodePush; for expo-updates, run shipvo migrate --plan. See docs/cli.md.
 
 In a bare React Native app (ios/ and android/ committed, no Expo config plugins) it also writes the Shipvo
 values into AndroidManifest.xml and Info.plist, and runs npx install-expo-modules@latest if Expo Modules are
@@ -42,9 +43,44 @@ Creates <dir> with a ready app. Every option is optional.
                            blank    the starter with device API buttons.
                            content  a list screen and a detail screen reading titles and text from src/data/articles.json.
                            shop     a product list, a product page and a cart, reading products and prices from src/data/products.json.
+  --json                 Print one JSON envelope on stdout; progress goes to stderr.
   --help                 Show this text.`;
 const title = (s) => s.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+/** `shipvo init --json`: the same work, reported as one envelope. The seed is never in it; only the path of the seed file. */
+async function initJson(argv) {
+    const [dirArg] = positional(argv.filter((x) => x !== "--json"));
+    const dry = argv.includes("--dry-run");
+    return runJson(async () => {
+        const adoptMode = isAdoptArgs(argv) && (dirArg === "." || detectProject(process.cwd()).isExpo || isBareApp(process.cwd()));
+        if (adoptMode && !argv.includes("--yes") && !dry)
+            throw new UsageError("init --json in an existing app needs --yes to apply the plan, or --dry-run to only print it.");
+        await trapExit(() => init(argv.filter((x) => x !== "--json")), (m, st) => {
+            const code = st === 2 ? "usage" : /already exists/.test(m) ? "dir_exists" : "init_failed";
+            return new CliFailure(m, code, st, code === "usage" ? [{ command: "shipvo init --help", why: "See the options." }] : code === "dir_exists" ? [{ command: "shipvo init <new-dir> --json", why: "Pick a folder that does not exist." }] : [{ command: "shipvo doctor --json", why: "Check your setup." }]);
+        });
+        const dir = adoptMode ? process.cwd() : resolve(dirArg);
+        let cfg = {};
+        try {
+            cfg = JSON.parse(readFileSync(join(dir, "shipvo.json"), "utf8"));
+        }
+        catch { }
+        const seedFile = join(dir, ".shipvo", "seed.txt");
+        const cd = adoptMode ? [] : [`cd ${dirArg} && `];
+        return {
+            code: dry ? "dry_run" : adoptMode ? "adopted" : "created",
+            summary: dry ? "Printed the plan. Nothing was changed." : adoptMode ? `Added Shipvo to this app${cfg.appId ? ` ("${cfg.appId}")` : ""}.` : `Created "${cfg.appId}" in ${dirArg}.`,
+            data: { mode: adoptMode ? "adopt" : "create", dry_run: dry, dir, app_id: cfg.appId ?? null, control_plane: cfg.controlPlane ?? null, public_key: cfg.publicKey ?? null, seed_file: !dry && existsSync(seedFile) ? seedFile : null },
+            next: dry ? [{ command: "shipvo init . --yes --json", why: "Apply the plan." }] : [
+                { command: `${cd[0] ?? ""}npm install`, why: "Install dependencies before any shipvo command." },
+                { command: `${cd[0] ?? ""}npx shipvo run android`, why: "See the app on a simulated phone (npx shipvo run ios for iOS)." },
+                { command: `${cd[0] ?? ""}npx shipvo publish --json`, why: "Send your first update." },
+            ],
+        };
+    }, [{ command: "shipvo init --help", why: "See the options." }]);
+}
 export async function init(argv) {
+    if (argv.includes("--json") && !argv.includes("--help") && !argv.includes("-h"))
+        return initJson(argv);
     const [dirArg] = positional(argv);
     const a = parse(argv);
     if (argv.includes("--help") || argv.includes("-h")) {
@@ -97,7 +133,7 @@ export async function init(argv) {
             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", "@shipvo/test": "^0.1.0", "@types/react": "~19.3.0", playwright: "^1.63.0", typescript: "~6.0.3", vitest: "^2.1.4" },
+        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 <1.65.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",
@@ -133,7 +169,7 @@ export const RELEASE = { headline: "Hello from ${name}.", note: "Edit src/releas
         w("App.tsx", SHOP_APP_TSX(name));
         w("src/cart.tsx", SHOP_CART_STATE);
         w("src/money.ts", SHOP_MONEY);
-        w("src/data/shop.json", SHOP_CONFIG);
+        w("src/data/shop.json", SHOP_CONFIG(name));
         w("src/screens/List.tsx", SHOP_LIST);
         w("src/screens/Detail.tsx", SHOP_DETAIL);
         w("src/screens/Cart.tsx", SHOP_CART);
@@ -153,19 +189,19 @@ Created ${name} in ${dirArg}
 ${seedNote}
 Public key pinned in the shell: ${publicKey}
 
-Phones:  npx expo run:android   (needs Android Studio once). iOS: npx expo run:ios, then shipvo publish --platform all
+Phones:  the browser phone (npx shipvo run android) needs no Android Studio. For a real build use npx expo run:android (needs Android Studio once) or 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)
 AI agents: npx -y @shipvo/mcp points Claude / Cursor / ChatGPT at the simulator; then open_app("${appId}")
 
-Install first: npm install (or pnpm / bun), then npx playwright install chromium
-
 Next steps:
   1. cd ${dirArg}
-  2. npx shipvo doctor             # setup checks
-  3. npm run sim                   # open the app in the simulator on http://localhost:4545
-  4. npx shipvo publish --dry-run  # see what a release would contain
-  5. npx shipvo preview            # get a link you can open on any phone
+  2. npm install                   # or pnpm install / bun install; needed before any shipvo command
+  3. npx shipvo run android        # the app on a simulated phone in your browser (npx shipvo run ios for iOS)
+  4. npx shipvo doctor             # setup checks
+  5. npx shipvo app create ${appId}   # register the app (run npx shipvo login first)
+  6. npx shipvo publish            # send your first update
+  7. npx shipvo preview            # get a link you can open on any phone
 `);
 }
 const APP_TSX = (name, appId) => `import { useEffect, useRef, useState } from "react";
@@ -360,7 +396,6 @@ jobs:
       - 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
@@ -482,7 +517,7 @@ const SHOP_DATA = JSON.stringify([
     { id: "wool-beanie", name: "Wool beanie", price: 2400, description: "A warm hat in undyed wool." },
     { id: "steel-bottle", name: "Steel bottle", price: 2900, description: "A one litre bottle with a screw cap." },
 ], null, 2) + "\n";
-const SHOP_CONFIG = JSON.stringify({ currency: "$", code: "USD", position: "before", decimals: 2, locale: "en-US" }, null, 2) + "\n";
+const SHOP_CONFIG = (name) => JSON.stringify({ name, currency: "$", code: "USD", position: "before", decimals: 2, locale: "en-US" }, null, 2) + "\n";
 const SHOP_MONEY = `// Prices are whole minor units (cents) in src/data/products.json. This is the one place that turns them into text.
 // To change the currency, edit src/data/shop.json. "code" is the ISO 4217 code sent to the payment provider ("$" is only a symbol). For FCFA: { "currency": "FCFA", "code": "XAF", "position": "after", "decimals": 0, "locale": "fr-FR" }
 import shop from "./data/shop.json";
@@ -496,6 +531,9 @@ export const formatPrice = (minor: number) => {
   return position === "after" ? num + " " + currency : currency + num;
 };
 
+// The payee shown on the payment sheet and the receipt. It is "name" in shop.json.
+export const shopName = (shop as { name?: string }).name ?? "Shop";
+
 // What device.pay.charge takes: "amount" is in whole currency units (10710 for 10710 FCFA, 12.5 for $12.50), as in the device docs.
 // Prices are minor units, so divide by 10 ** decimals. "currency" is the ISO code from shop.json.
 export const chargeRequest = (minor: number) => {
@@ -538,6 +576,15 @@ import products from "./src/data/products.json";
 
 type Route = { name: "list" } | { name: "detail"; id: string } | { name: "cart" };
 
+// Send a placed order to the backend. The simulator records it, so end_session lists it. Add your own backend call here.
+async function sendOrder(order: Record<string, unknown>) {
+  try {
+    const st = Runtime.getState();
+    if (!st?.baseUrl) return;
+    await fetch(st.baseUrl + "/o/" + st.appId, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ order, release: st.runningRelease ?? 0 }) });
+  } catch {}
+}
+
 export default function App() {
   const [route, setRoute] = useState<Route>({ name: "list" });
   // Tell the runtime the first screen rendered, so this release is kept.
@@ -560,7 +607,7 @@ export default function App() {
     <CartProvider>
       <View style={s.root}>
         <StatusBar style="dark" />
-        {route.name === "cart" ? <Cart onBack={toList} />
+        {route.name === "cart" ? <Cart onBack={toList} onOrder={sendOrder} />
           : product ? <Detail product={product} onBack={toList} onCart={toCart} />
           : <List title="${name}" products={products} onOpen={(id) => setRoute({ name: "detail", id })} onCart={toCart} />}
       </View>
@@ -637,10 +684,10 @@ const SHOP_CART = `import { useState } from "react";
 import { Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
 import { device } from "@shipvo/device";
 import { useCart } from "../cart";
-import { chargeRequest, formatPrice } from "../money";
+import { chargeRequest, formatPrice, shopName } from "../money";
 import products from "../data/products.json";
 
-export function Cart({ onBack }: { onBack: () => void }) {
+export function Cart({ onBack, onOrder }: { onBack: () => void; onOrder?: (order: Record<string, unknown>) => void | Promise<void> }) {
   const { lines, remove, clear, totalCents } = useCart();
   const [status, setStatus] = useState<string | null>(null);
   const [busy, setBusy] = useState(false);
@@ -650,8 +697,13 @@ export function Cart({ onBack }: { onBack: () => void }) {
     setBusy(true);
     setStatus("Paying...");
     try {
-      const r = await device.pay.charge({ provider: "mobile_money", ...chargeRequest(totalCents), to: "My Shop", reference: "order-" + Date.now() }, "1234");
-      if (r.ok) { clear(); setStatus("Order placed"); } else setStatus("Payment failed: " + r.reason);
+      const reference = "order-" + Date.now();
+      const r = await device.pay.charge({ provider: "mobile_money", ...chargeRequest(totalCents), to: shopName, reference }, "1234");
+      if (r.ok) {
+        // Only a paid order is sent to the backend.
+        await onOrder?.({ id: reference, total: totalCents, payment: "mobile_money", receipt: r.receipt, lines: lines.map((l) => ({ product_id: l.id, quantity: l.qty })) });
+        clear(); setStatus("Order placed");
+      } else setStatus("Payment failed: " + r.reason);
     } catch (e: any) { setStatus("Payment failed: " + String(e?.message ?? e)); }
     finally { setBusy(false); }
   };

package/dist/json-out.d.ts

@@ -0,0 +1,53 @@
+export type Next = {
+    command: string;
+    why: string;
+};
+export type Envelope<C extends string = string, D = unknown> = {
+    ok: boolean;
+    /** Short stable string. */
+    code: C;
+    summary: string;
+    data: D;
+    /** One to three commands to run next, most urgent first. */
+    next: Next[];
+};
+/** Exit codes shared by the `--json` commands. */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+};
+/** Print the envelope as one line on stdout. */
+export declare function emit(doc: Envelope<string, unknown>): void;
+/** Build an envelope. `ok` is true exactly when the exit code is 0. */
+export declare function envelope<C extends string, D>(code: C, summary: string, data: D, next: Next[], exit: number): Envelope<C, D>;
+/** A failure with a stable code, an exit code and a suggested follow-up. Without `--json` it is a plain error. */
+export declare class CliFailure extends Error {
+    readonly code: string;
+    readonly exit: number;
+    readonly next: Next[];
+    constructor(message: string, code?: string, exit?: number, next?: Next[]);
+}
+/** A bad flag or value. Exit code 2. */
+export declare class UsageError extends CliFailure {
+    constructor(message: string);
+}
+/** What a command reports on success in `--json` mode. */
+export type Done = {
+    code: string;
+    summary: string;
+    data: unknown;
+    next: Next[];
+};
+/**
+ * Run `fn` so that stdout holds only the envelope: console.log goes to stderr while it runs.
+ * A thrown error becomes a failure envelope (exit 2 for a UsageError, 1 otherwise). Sets process.exitCode.
+ */
+export declare function runJson(fn: () => Promise<Done>, fallbackNext: Next[]): Promise<void>;
+/**
+ * Run a text-mode command that ends with `process.exit` after printing to stderr. An exit becomes a thrown
+ * CliFailure built by `classify(message, status)`; the stderr text is still written. Status 0 returns normally.
+ */
+export declare function trapExit(fn: () => Promise<unknown>, classify: (message: string, status: number) => CliFailure): Promise<void>;
+/** Collect what `fn` prints with console.log instead of printing it. Used so output that holds a secret never reaches a stream. */
+export declare function captureLog(fn: () => Promise<unknown>): Promise<string[]>;

package/dist/json-out.js

@@ -0,0 +1,91 @@
+/** Exit codes shared by the `--json` commands. */
+export const EXIT = { ok: 0, failed: 1, usage: 2 };
+/** Print the envelope as one line on stdout. */
+export function emit(doc) {
+    console.log(JSON.stringify(doc));
+}
+/** Build an envelope. `ok` is true exactly when the exit code is 0. */
+export function envelope(code, summary, data, next, exit) {
+    return { ok: exit === 0, code, summary, data, next: next.slice(0, 3) };
+}
+/** A failure with a stable code, an exit code and a suggested follow-up. Without `--json` it is a plain error. */
+export class CliFailure extends Error {
+    code;
+    exit;
+    next;
+    constructor(message, code = "failed", exit = EXIT.failed, next = []) {
+        super(message);
+        this.code = code;
+        this.exit = exit;
+        this.next = next;
+    }
+}
+/** A bad flag or value. Exit code 2. */
+export class UsageError extends CliFailure {
+    constructor(message) { super(message, "usage", EXIT.usage, [{ command: "shipvo help", why: "See the commands and flags." }]); }
+}
+/**
+ * Run `fn` so that stdout holds only the envelope: console.log goes to stderr while it runs.
+ * A thrown error becomes a failure envelope (exit 2 for a UsageError, 1 otherwise). Sets process.exitCode.
+ */
+export async function runJson(fn, fallbackNext) {
+    const log = console.log;
+    console.log = console.error;
+    let doc, exit;
+    try {
+        const d = await fn();
+        exit = 0;
+        doc = envelope(d.code, d.summary, d.data, d.next, 0);
+    }
+    catch (e) {
+        const f = e instanceof CliFailure ? e : null;
+        exit = f?.exit ?? EXIT.failed;
+        doc = envelope(f?.code ?? "failed", e instanceof Error ? e.message : String(e), {}, f && f.next.length ? f.next : fallbackNext, exit);
+    }
+    finally {
+        console.log = log;
+    }
+    emit(doc);
+    process.exitCode = exit;
+}
+class ExitSignal extends Error {
+    status;
+    constructor(status) {
+        super("exit");
+        this.status = status;
+    }
+}
+/**
+ * Run a text-mode command that ends with `process.exit` after printing to stderr. An exit becomes a thrown
+ * CliFailure built by `classify(message, status)`; the stderr text is still written. Status 0 returns normally.
+ */
+export async function trapExit(fn, classify) {
+    const exit = process.exit, err = console.error, msgs = [];
+    process.exit = ((c) => { throw new ExitSignal(c ?? 0); });
+    console.error = (...a) => { msgs.push(a.map(String).join(" ")); err(...a); };
+    try {
+        await fn();
+    }
+    catch (e) {
+        if (!(e instanceof ExitSignal))
+            throw e;
+        if (e.status !== 0)
+            throw classify(msgs.join("\n").trim(), e.status);
+    }
+    finally {
+        process.exit = exit;
+        console.error = err;
+    }
+}
+/** Collect what `fn` prints with console.log instead of printing it. Used so output that holds a secret never reaches a stream. */
+export async function captureLog(fn) {
+    const log = console.log, lines = [];
+    console.log = (...a) => { lines.push(a.map(String).join(" ")); };
+    try {
+        await fn();
+    }
+    finally {
+        console.log = log;
+    }
+    return lines;
+}

package/dist/keys-json.d.ts

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

package/dist/keys-json.js

@@ -0,0 +1,71 @@
+// `shipvo keys ... --json`: status, export, import and rotate as one envelope. Wraps the text commands, so their output paths are untouched.
+// The seed is never in an envelope or on a stream: export needs --out, and import reports only the public key.
+import { args, loadConfig } from "./config.js";
+import { keys } from "./login.js";
+import { signingKey } from "./signing.js";
+import { CliFailure, UsageError, captureLog, runJson, trapExit } from "./json-out.js";
+const LOGIN = { command: "shipvo login", why: "Sign in again." };
+const FALLBACK = [{ command: "shipvo doctor --json", why: "Check your setup." }];
+function project() {
+    try {
+        return loadConfig();
+    }
+    catch (e) {
+        throw new CliFailure(e instanceof Error ? e.message : String(e), "no_project", 1, [{ command: "shipvo init . --yes --json", why: "Add Shipvo to this app." }, { command: "shipvo init myapp --json", why: "Or start a new app." }]);
+    }
+}
+const failIn = (table, fallbackCode = "failed") => (m, st) => {
+    const hit = table.find(([re]) => re.test(m));
+    return new CliFailure(m, st === 2 ? "usage" : hit?.[1] ?? fallbackCode, st, hit?.[2] ?? FALLBACK);
+};
+export async function keysJson(argv) {
+    const [sub, ...rest] = argv.filter((x) => x !== "--json");
+    const rawRest = rest;
+    return runJson(async () => {
+        if (sub === undefined) {
+            const lines = await captureLog(() => trapExit(() => keys(), failIn([
+                [/Not signed in/, "not_signed_in", [LOGIN]], [/expired/, "key_expired", [LOGIN]], [/not valid any more/, "key_invalid", [LOGIN]],
+            ])));
+            const d = JSON.parse(lines.join("\n"));
+            return { code: "ok", summary: `Signed in as ${d.login}. Key ${d.prefix}… has used ${d.used_minutes} of ${d.quota_minutes} sandbox minutes.`, data: d, next: [{ command: "shipvo app create", why: "Register the app and save a publish token." }, { command: "shipvo doctor --json", why: "Check the setup." }] };
+        }
+        if (sub !== "export" && sub !== "import" && sub !== "rotate")
+            throw new UsageError(`Unknown keys command "${sub}". Use keys, keys export, keys import or keys rotate.`);
+        const cfg = project();
+        if (sub === "export") {
+            const out = args(rawRest).out;
+            if (!out || out === "true")
+                throw new UsageError("keys export --json needs --out <file>. The seed is never printed in an envelope.");
+            await trapExit(() => signingKey(["export", ...rawRest]), failIn([
+                [/Set SHIPVO_SIGNING_SEED/, "no_seed", [{ command: "shipvo keys import", why: "Restore the seed on this machine." }]],
+                [/does not match the public key/, "seed_mismatch", [{ command: "shipvo keys import", why: "Restore the seed that matches shipvo.json." }]],
+            ]));
+            return { code: "exported", summary: `Seed for "${cfg.appId}" written to ${out}. Move it to a password manager, then delete the file.`, data: { app_id: cfg.appId, public_key: cfg.publicKey, out }, next: [{ command: `shipvo keys import --file ${out}`, why: "Restore it on another machine." }] };
+        }
+        if (sub === "import") {
+            const lines = await captureLog(() => trapExit(() => signingKey(["import", ...rawRest]), failIn([
+                [/Usage: shipvo keys import/, "usage", [{ command: "shipvo keys import --file seed.txt", why: "Read the seed from a file." }]],
+                [/does not look like/, "invalid_seed", [{ command: "shipvo keys import --file seed.txt", why: "Use the seed that `shipvo keys export` saved." }]],
+                [/belongs to a different key/, "seed_mismatch", [{ command: "shipvo keys import --file seed.txt", why: "Use the seed for this app's public key." }]],
+            ])));
+            const text = lines.join("\n");
+            return {
+                code: /Already in place/.test(text) ? "unchanged" : "imported",
+                summary: /Already in place/.test(text) ? "The seed was already in place. Nothing to do." : `Signing key for "${cfg.appId}" restored to .shipvo/seed.txt (matches shipvo.json).`,
+                data: { app_id: cfg.appId, public_key: cfg.publicKey, seed_file: ".shipvo/seed.txt", gitignore_warning: /\.gitignore does not ignore/.test(text) },
+                next: [{ command: "shipvo login", why: "Sign in on this machine." }, { command: "shipvo app create", why: "Get a publish token on this machine." }],
+            };
+        }
+        // rotate sign | upload. The signed envelope is public, so it is safe in data.
+        const lines = await captureLog(() => trapExit(() => signingKey(["rotate", ...rawRest, "--json"]), failIn([
+            [/^Usage:/, "usage", [{ command: "shipvo keys rotate sign --root-seed-file <file> --new-key <public key> --sequence <n>", why: "Sign a rotation statement offline." }]],
+            [/Not signed in/, "not_signed_in", [LOGIN]],
+            [/refused the statement/, "refused", FALLBACK],
+            [/Could not reach/, "remote_failed", FALLBACK],
+        ], "rotate_failed")));
+        const out = JSON.parse(lines.join("\n"));
+        if (rest[0] === "sign")
+            return { code: "rotation_signed", summary: `Signed rotation statement ${args(rest).sequence} for "${cfg.appId}". Save data.envelope to a file, then upload it.`, data: { app_id: cfg.appId, envelope: out }, next: [{ command: "shipvo keys rotate upload <file>", why: "Upload the saved envelope. Needs shipvo login as the app owner." }] };
+        return { code: "rotation_uploaded", summary: "Uploaded. Phones switch when they next fetch it.", data: { app_id: cfg.appId, response: out }, next: [{ command: "shipvo status --json", why: "Check the app." }] };
+    }, FALLBACK);
+}

package/dist/login.js

@@ -4,6 +4,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { args as parse } from "./config.js";
+import { CliFailure, runJson } from "./json-out.js";
 const HOSTED = "https://api.shipvo.dev";
 const credFile = () => join(process.env.SHIPVO_HOME || join(homedir(), ".shipvo"), "credentials.json");
 export function savedCreds() {
@@ -15,14 +16,25 @@ export function savedCreds() {
     }
 }
 export async function login(argv) {
+    if (argv.includes("--json"))
+        return runJson(() => loginRun(argv, true), [{ command: "shipvo login --json", why: "Try signing in again." }, { command: "shipvo doctor --json", why: "Check your setup." }]);
+    await loginRun(argv, false);
+}
+/** Device sign-in. With `json`, failures throw (the envelope reports them), the device URL and code go in `data`, and the key is never printed. */
+async function loginRun(argv, json) {
+    const again = [{ command: "shipvo login --json", why: "Start a new sign-in." }];
+    const fail = (msg, code) => {
+        if (json)
+            throw new CliFailure(msg, code, 1, again);
+        console.error(msg);
+        process.exit(1);
+    };
     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);
-    }
+    if (!start.ok)
+        fail(`Login is not available on ${control}: ${s.message ?? s.error}`, "login_unavailable");
     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;
@@ -35,18 +47,22 @@ export async function login(argv) {
                 interval += 5000;
             continue;
         }
-        if (!r.ok) {
-            console.error(`Login failed: ${d.status ?? d.error}`);
-            process.exit(1);
-        }
+        if (!r.ok)
+            fail(`Login failed: ${d.status ?? d.error}`, d.status === "expired_token" || d.status === "expired" ? "login_expired" : "login_failed");
         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 });
+        if (json) {
+            return {
+                code: "signed_in", summary: `Signed in as ${d.login}. The key is saved to ${credFile()}.`,
+                data: { login: d.login, key_prefix: d.prefix, saved_to: credFile(), quota_minutes: d.quota_minutes, expires_at: d.expires_at, apps: d.apps, mcp_url: d.mcp.url, device: { verification_uri: s.verification_uri, user_code: s.user_code } },
+                next: [{ command: "shipvo app create", why: "Register the app and save a publish token." }, { command: "shipvo doctor --json", why: "Check the setup." }],
+            };
+        }
         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;
+        return { code: "signed_in", summary: "", data: {}, next: [] };
     }
-    console.error("Timed out waiting for GitHub.");
-    process.exit(1);
+    return fail("Timed out waiting for GitHub.", "login_timeout");
 }
 export async function keys() {
     const c = savedCreds();

package/dist/lumi.d.ts

@@ -0,0 +1,104 @@
+import { type Server } from "node:http";
+import { type Driver, type Skin } from "./explore.js";
+export type Mood = "idle" | "working" | "happy" | "worried";
+export type Command = {
+    kind: "test-all";
+} | {
+    kind: "test-flow";
+    flow: string;
+} | {
+    kind: "bad-input";
+    flow: string;
+} | {
+    kind: "stop";
+} | {
+    kind: "replay";
+    n: number;
+} | {
+    kind: "help";
+} | {
+    kind: "unknown";
+};
+/** Reads a line of text as a command. No AI: a few patterns, case and spacing ignored. */
+export declare function parseCommand(text: string): Command;
+export declare const COMMAND_LIST: string[];
+export type FeedItem = {
+    at: string;
+    text: string;
+    kind: "step" | "info" | "bug";
+};
+export type State = {
+    mood: Mood;
+    running: boolean;
+    label: string;
+    feed: FeedItem[];
+    findings: {
+        n: number;
+        kind: string;
+        message: string;
+        steps: string[];
+    }[];
+    coverage: {
+        screens: number;
+        controlsSeen: number;
+        controlsTried: number;
+    };
+};
+export type LumiOptions = {
+    routes?: string[];
+    maxDepth?: number;
+    maxSteps?: number;
+    seed?: number;
+    skin?: Skin;
+    app?: string;
+    settleMs?: number;
+    walkDelayMs?: number;
+};
+export declare class Lumi {
+    private driver;
+    private o;
+    private feed;
+    private known;
+    private screens;
+    private seen;
+    private tried;
+    private mood;
+    private running;
+    private label;
+    private stopFlag;
+    private listeners;
+    private job;
+    constructor(driver: Driver, o?: LumiOptions);
+    subscribe(fn: (s: State) => void): () => void;
+    state(): State;
+    /** Resolves when the current run or replay has ended. */
+    idle(): Promise<void>;
+    private emit;
+    private say;
+    /** Names you can use after `test` and `try`: configured routes, then the controls on the start screen. */
+    flows(): Promise<string[]>;
+    private resolve;
+    /** Handles one line from the command box. Returns the short reply at once; a run goes on in the background (see `idle`). */
+    command(text: string): Promise<string>;
+    private start;
+    private run;
+    /** Does the steps of a bug again, one by one, and says whether the screen is the same as when it was found. */
+    private replay;
+}
+/** "tide://cart" -> "cart", "/orders/open" -> "open". */
+export declare function routeName(url: string): string;
+/** The whole page: the phone frame with the live app picture in it, and the sidebar. */
+export declare function lumiPage(frame: {
+    html: string;
+    css: string;
+}, title: string): string;
+export type LumiServerOptions = {
+    lumi: Lumi;
+    page: string;
+    shot: () => Promise<Buffer | null>;
+    port: number;
+};
+/** Local server for the page. It only answers requests whose Host is this machine's address, and only commands from this page. */
+export declare function startLumiServer(o: LumiServerOptions): Promise<Server>;
+/** Builds the app, opens it on Shipvo Phone in the browser with the Lumi sidebar. Runs until Ctrl-C. */
+export declare function lumi(argv: string[]): Promise<number>;