@shipvo/cli 0.1.5 → 0.1.6

package/dist/flows.js

@@ -0,0 +1,264 @@
+// Lumi flows: recognise sign up, log in, search, add to cart and checkout by control labels and screen text,
+// drive each to its end with valid input, then once with invalid input. No AI model. Works on any `Driver`.
+import { elements, signature, sampleValue, describeStep } from "./explore.js";
+export const FLOW_NAMES = ["signup", "login", "search", "add_to_cart", "checkout"];
+const FIELD_ROLES = new Set(["textbox", "searchbox"]);
+const RISKY = /\b(log ?out|sign ?out|delete|remove|cancel|erase|deactivate|clear all|unsubscribe)\b/i;
+const RED = /Uncaught (\w*Error)|Unhandled Runtime Error|Application error|Something went wrong/i;
+const NET = /network request failed|network error|failed to fetch|no internet|(?:can't|cannot|couldn't|unable to) connect|connection (?:failed|lost|error)/i;
+const REJECTED = /invalid|incorrect|wrong|required|must be|not valid|too short|try again|\berror\b|can't be empty|enter a/i;
+const ORDER_DONE = /\border\b[^\n]{0,40}\b(placed|confirmed|complete|successful)|payment (?:approved|successful|complete)|thank you|receipt/i;
+const ADDED = /\badded\b|in (?:your )?(?:cart|bag|basket)/i;
+const ADD_BTN = /^add\b.*\b(cart|bag|basket)\b|^add (?:\d+ )?to (?:cart|bag|basket)/i;
+const CART_NAV = /\b(cart|bag|basket|checkout)\b/i;
+/** Controls that look like a product: a price in the label, or the word product. */
+const PRODUCT = /\d[\d\s.,]*\s?(?:FCFA|XAF|USD|EUR|GBP|[$€£])|[$€£]\s?\d/i;
+const NAV_ONLY = /^(back|go back|close|home|menu|settings|about)\b/i;
+class Fail extends Error {
+}
+/** Fields (text boxes) in a tree, with the same nth numbering the walker uses. */
+function fieldsOf(tree) {
+    const out = [];
+    const seen = new Map();
+    for (const l of tree.split("\n")) {
+        const m = /^\s*- (textbox|searchbox)(?: "((?:[^"\\]|\\.)*)")?[^\n]*?\[ref=(\w+)\]/.exec(l);
+        if (!m || /\[disabled\]/.test(l))
+            continue;
+        const name = (m[2] ?? "").trim();
+        const key = `${m[1]}|${name}`;
+        const nth = seen.get(key) ?? 0;
+        seen.set(key, nth + 1);
+        out.push({ role: m[1], name, ref: m[3], nth });
+    }
+    return out;
+}
+class Session {
+    d;
+    steps = [];
+    screen = "";
+    constructor(d) {
+        this.d = d;
+    }
+    async settle(r, step) {
+        this.steps.push(step);
+        if (!r.ok || r.screen == null)
+            throw new Fail(`${describeStep(step)} failed: ${r.error ?? "no screen"}`);
+        this.screen = r.screen;
+        for (const e of await this.d.errors())
+            throw new Fail(`${describeStep(step)} raised an error: ${e}`);
+        const bad = RED.exec(r.screen)?.[0] ?? NET.exec(r.screen)?.[0];
+        if (bad)
+            throw new Fail(`${describeStep(step)} led to a screen that shows "${bad}"`);
+    }
+    async open() { this.steps = []; await this.settle(await this.d.open(), { action: "open" }); }
+    async tap(e) { await this.settle(await this.d.tap(e.ref), { action: "tap", role: e.role, name: e.name, nth: e.nth }); }
+    async type(e, text, enter = false) {
+        if (!this.d.type)
+            throw new Fail("this simulator cannot type");
+        await this.settle(await this.d.type(e.ref, text, enter), { action: "type", role: e.role, name: e.name, nth: e.nth, text, ...(enter ? { enter: true } : {}) });
+    }
+    async back() { const r = await this.d.back(); if (r.ok && r.screen != null) {
+        this.screen = r.screen;
+        this.steps.push({ action: "back" });
+        return true;
+    } return false; }
+    buttons(re) { return elements(this.screen).filter((e) => e.name && !RISKY.test(e.name) && (!re || re.test(e.name))); }
+    /** Type into every field on the screen, in order. Fields are found again after each one, since refs can change. */
+    async fill(invalid, only) {
+        const want = fieldsOf(this.screen).filter((f) => !only || only.test(f.name));
+        for (const f of want) {
+            const cur = fieldsOf(this.screen).find((x) => x.role === f.role && x.name === f.name && x.nth === f.nth);
+            if (cur)
+                await this.type(cur, sampleValue(f.name, invalid), invalid && fieldsOf(this.screen).length === 1);
+        }
+        return want.length;
+    }
+}
+/** Look for something on this screen, then one tap away through navigation controls. If not found, step back (twice at most) and look again. */
+async function locate(s, test, prefer) {
+    for (let up = 0; up < 3; up++) {
+        const here = test(s.screen);
+        if (here)
+            return here;
+        const start = signature(s.screen);
+        const hops = s.buttons().filter((e) => !NAV_ONLY.test(e.name) && !FIELD_ROLES.has(e.role) && !ADD_BTN.test(e.name));
+        hops.sort((a, b) => Number(!!prefer?.test(b.name)) - Number(!!prefer?.test(a.name)));
+        for (const h of hops.slice(0, 8)) {
+            await s.tap(h);
+            const found = test(s.screen);
+            if (found)
+                return found;
+            if (!(await s.back()) || signature(s.screen) !== start)
+                return null;
+        }
+        if (!(await s.back()))
+            return null;
+    }
+    return null;
+}
+const submitBtn = (s, re) => s.buttons(re).find((b) => !FIELD_ROLES.has(b.role));
+const stillForm = (tree, needPass) => fieldsOf(tree).some((f) => (needPass ? /pass/i : /./).test(f.name));
+async function authFlow(s, kind, invalid) {
+    const entry = kind === "signup" ? /sign ?up|register|create (?:an )?account|join/i : /log ?in|sign ?in/i;
+    const submit = kind === "signup" ? /sign ?up|register|create|continue|submit|next|join/i : /log ?in|sign ?in|continue|submit/i;
+    const hasForm = (t) => (fieldsOf(t).some((f) => /pass/i.test(f.name)) || fieldsOf(t).some((f) => /e-?mail|user/i.test(f.name))) && !!elements(t).some((e) => submit.test(e.name)) ? t : null;
+    await s.open();
+    let form = await locate(s, hasForm);
+    if (!form) {
+        const e = s.buttons(entry)[0];
+        if (e) {
+            await s.tap(e);
+            form = hasForm(s.screen);
+        }
+        else {
+            const hop = await locate(s, (t) => (elements(t).find((x) => entry.test(x.name)) ? t : null), /account|profile|menu/i);
+            if (hop) {
+                await s.tap(elements(s.screen).find((x) => entry.test(x.name)));
+                form = hasForm(s.screen);
+            }
+        }
+    }
+    if (!form)
+        return { status: "not_found", message: `No ${kind === "signup" ? "sign up" : "log in"} form found on the first screen or one tap away`, steps: s.steps };
+    await s.fill(invalid);
+    const btn = submitBtn(s, submit);
+    if (!btn)
+        throw new Fail("no submit button after filling the form");
+    await s.tap(btn);
+    const left = !stillForm(s.screen, true) && !REJECTED.test(s.screen);
+    if (invalid)
+        return left ? { status: "failed", message: "The app accepted invalid input and moved on", step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps } : { status: "passed", message: "The app rejected invalid input and stayed on the form", steps: s.steps };
+    return left ? { status: "passed", message: "The form was accepted and the app moved on", steps: s.steps } : { status: "failed", message: `The app did not accept valid input${REJECTED.exec(s.screen) ? ` (screen shows "${REJECTED.exec(s.screen)[0]}")` : ""}`, step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps };
+}
+async function searchFlow(s, invalid) {
+    const isSearch = (t) => fieldsOf(t).find((f) => /search|find|query/i.test(f.name)) ?? null;
+    await s.open();
+    const f = await locate(s, isSearch, /search|find/i);
+    if (!f)
+        return { status: "not_found", message: "No search field found on the first screen or one tap away", steps: s.steps };
+    // The typed text shows in the field itself, so leave the field lines out of every check.
+    const noFields = (t) => signature(t.split("\n").filter((l) => !/^\s*- (textbox|searchbox)\b/.test(l)).join("\n"));
+    const before = noFields(s.screen);
+    const field = isSearch(s.screen);
+    await s.type(field, sampleValue(field.name, invalid), true);
+    if (invalid)
+        return { status: "passed", message: "An empty search did not crash the app", steps: s.steps };
+    const go = noFields(s.screen) === before ? submitBtn(s, /^(search|find|go)$/i) : undefined;
+    if (go)
+        await s.tap(go);
+    return noFields(s.screen) !== before || noFields(s.screen).includes(sampleValue(field.name, false))
+        ? { status: "passed", message: "The screen responded to the search", steps: s.steps }
+        : { status: "failed", message: "The screen did not change after searching", step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps };
+}
+async function addToCart(s, invalid) {
+    const addIn = (t) => (elements(t).find((e) => ADD_BTN.test(e.name)) ? t : null);
+    if (!(await locate(s, addIn, PRODUCT)))
+        return null;
+    const qty = fieldsOf(s.screen).find((f) => /qty|quantity/i.test(f.name));
+    if (invalid) {
+        if (!qty)
+            return { status: "not_run", message: "No quantity field to give a bad value", steps: s.steps };
+        await s.type(qty, "abc");
+        await s.tap(elements(s.screen).find((e) => ADD_BTN.test(e.name)));
+        return ADDED.test(s.screen) && /abc/.test(s.screen) ? { status: "failed", message: "The app added a quantity of \"abc\"", step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps } : { status: "passed", message: "A bad quantity did not crash the app or get added", steps: s.steps };
+    }
+    const before = signature(s.screen);
+    await s.tap(elements(s.screen).find((e) => ADD_BTN.test(e.name)));
+    return signature(s.screen) !== before || ADDED.test(s.screen)
+        ? { status: "passed", message: "The add button changed the screen", steps: s.steps }
+        : { status: "failed", message: "Nothing changed after the add button", step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps };
+}
+async function cartFlow(s, invalid) {
+    await s.open();
+    const r = await addToCart(s, invalid);
+    if (!r)
+        return { status: "not_found", message: "No add-to-cart button found on the first screen or one tap away", steps: s.steps };
+    return r;
+}
+const FINAL = /place order|pay\b|pay now|confirm|submit order|complete/i;
+const CHOICE = /pickup|delivery|ship|card|mobile money|cash|standard|express|any day|use my location|fingerprint/i;
+const NEXT = /continue|next|proceed|review/i;
+async function checkoutFlow(s, invalid) {
+    await s.open();
+    // A cart needs something in it first.
+    if (!(await addToCart(s, false)))
+        return { status: "not_found", message: "No add-to-cart button found, so there is no way to reach checkout", steps: s.steps };
+    const isCheckout = (t) => (elements(t).find((e) => /check ?out|choose delivery|place order|proceed to pay/i.test(e.name)) ? t : null);
+    if (!(await locate(s, isCheckout, CART_NAV)))
+        return { status: "not_found", message: "No checkout control found after adding to the cart", steps: s.steps };
+    const tapped = new Set();
+    let submitted = false;
+    for (let i = 0; i < 10; i++) {
+        if (ORDER_DONE.test(s.screen))
+            return invalid ? { status: "failed", message: "The order went through with invalid input", step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps } : { status: "passed", message: "The order was placed", steps: s.steps };
+        // Invalid input: once a submit leaves the form in place, the app rejected it. Picking another option (such as pickup) would skip the bad field.
+        if (invalid && submitted && fieldsOf(s.screen).length)
+            break;
+        await s.fill(invalid);
+        const key = (e) => `${signature(s.screen)}|${e.role}|${e.name}|${e.nth}`;
+        const cands = [...s.buttons(FINAL), ...s.buttons(CHOICE), ...s.buttons(/check ?out|choose delivery/i), ...s.buttons(NEXT)].filter((e) => !tapped.has(key(e)) && !FIELD_ROLES.has(e.role));
+        const next = cands[0];
+        if (!next)
+            break;
+        tapped.add(key(next));
+        const hadFields = fieldsOf(s.screen).length > 0;
+        await s.tap(next);
+        if (hadFields && FINAL.test(next.name))
+            submitted = true;
+    }
+    if (ORDER_DONE.test(s.screen))
+        return invalid ? { status: "failed", message: "The order went through with invalid input", step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps } : { status: "passed", message: "The order was placed", steps: s.steps };
+    if (invalid)
+        return { status: "passed", message: "Checkout did not complete with invalid input", steps: s.steps };
+    return { status: "failed", message: "Checkout stopped before the order was placed: no control left to continue", step: describeStep(s.steps[s.steps.length - 1]), steps: s.steps };
+}
+async function once(d, flow, invalid) {
+    const s = new Session(d);
+    try {
+        if (flow === "signup" || flow === "login")
+            return await authFlow(s, flow, invalid);
+        if (flow === "search")
+            return await searchFlow(s, invalid);
+        if (flow === "add_to_cart")
+            return await cartFlow(s, invalid);
+        return await checkoutFlow(s, invalid);
+    }
+    catch (e) {
+        if (!(e instanceof Fail))
+            throw e;
+        return { status: "failed", message: e.message, step: s.steps.length ? describeStep(s.steps[s.steps.length - 1]) : undefined, steps: s.steps };
+    }
+}
+/** Turn the `--flows` value into flow names. A bare flag (the arg parser gives "true") means all of them. */
+export function parseFlowNames(v) {
+    if (v === "true")
+        return [...FLOW_NAMES];
+    const names = v.split(",").map((x) => x.trim().replace(/-/g, "_")).filter(Boolean);
+    const bad = names.find((n) => !FLOW_NAMES.includes(n));
+    if (bad)
+        throw new Error(`--flows: unknown flow "${bad}". Use ${FLOW_NAMES.join(", ")}`);
+    return names;
+}
+/** Run each flow with valid input, then once with invalid input. Each run starts on a fresh phone. */
+export async function runFlows(d, o = {}) {
+    const out = [];
+    for (const flow of o.flows ?? FLOW_NAMES) {
+        const valid = await once(d, flow, false).catch((e) => ({ status: "failed", message: `The flow stopped: ${e instanceof Error ? e.message : String(e)}`, steps: [] }));
+        const status = valid.status === "not_run" ? "not_found" : valid.status;
+        const invalid = status === "not_found" ? { status: "not_run", message: "The flow was not found", steps: [] } : await once(d, flow, true).catch((e) => ({ status: "failed", message: `The flow stopped: ${e instanceof Error ? e.message : String(e)}`, steps: [] }));
+        out.push({ flow, status, message: valid.message, step: valid.step, steps: valid.steps, invalid });
+    }
+    return { app: o.app ?? "", generatedAt: new Date().toISOString(), flows: out };
+}
+export function renderFlows(r) {
+    const L = [`# Flow report: ${r.app}`, "", "| Flow | Valid input | Invalid input |", "| --- | --- | --- |"];
+    for (const f of r.flows)
+        L.push(`| ${f.flow.replaceAll("_", " ")} | ${f.status} | ${f.invalid.status === "not_run" ? "not run" : f.invalid.status} |`);
+    L.push("");
+    for (const f of r.flows) {
+        L.push(`## ${f.flow.replaceAll("_", " ")}`, "", `- Valid input: ${f.status}. ${f.message}.${f.step ? ` Failed at: ${f.step}.` : ""}`, `- Invalid input: ${f.invalid.status === "not_run" ? "not run" : f.invalid.status}. ${f.invalid.message}.${f.invalid.step ? ` Failed at: ${f.invalid.step}.` : ""}`, "");
+        if (f.status === "failed")
+            L.push("Steps to reproduce:", "", ...f.steps.map((s, i) => `${i + 1}. ${describeStep(s)}`), "");
+    }
+    return L.join("\n");
+}

package/dist/help.d.ts

@@ -1,5 +1,5 @@
-export declare const COMMANDS: readonly ["init", "sim", "run", "explore", "preview", "publish", "promote", "auto-halt", "rollback", "app", "eas", "login", "doctor", "store", "ci", "status", "agents", "audit", "test", "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  sim --watch [--verbose]     Rebuild on file changes and keep serving; --verbose shows full build errors\n                              First run installs playwright and, if no Chrome or Edge is found, downloads Chromium once.\n                              Set SHIPVO_NO_AUTO_INSTALL=1 to turn the automatic installs off.\n  run android|ios [--no-open] [--port n]  Open the app in a phone frame in your browser (no Playwright)\n  run android|ios --native    Run on an emulator or simulator with npx expo run:android / run:ios\n  explore [--max-depth 3] [--max-steps 100] [--fail-on-findings]  Walk the app in the simulator, write explore-report.md and .json\n  preview [--json]            Publish a public 24-hour preview link (here.now, no account)\n\nShip\n  publish [--bands b0,b1,b2] [--release N]  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  promote [--to b1,b2]        Widen a staged release to more bands (same release, new signature)\n  promote --dry-run           Preview a promote, write nothing\n  promote --report <file>     Refuse to widen when the test report has a failing flow for this release\n  auto-halt [--threshold 0.2 --min-reports 20 | --off]  Show, turn on or turn off auto-halt\n  rollback --to <release>     Republish an earlier release as a new release\n  rollback --to <n> --dry-run Preview a rollback, write nothing\n  app create | list | delete  Register, list or remove apps on the hosted control plane\n  eas setup [--dry-run] [--run]  Make a Capacitor repo ready for eas build and submit (your own Expo account)\n  eas build [args]            Link the iOS scheme, then run eas build\n  login                       Sign in with GitHub and get a key for the hosted simulator\n  store details --dry-run     Draft Play Data safety answers and a privacy policy from shipvo.json\n  store setup [--company yes|no] [--android-now] [--play-account-before-2023-11-13]\n                              Pick the store accounts to open and write store-plan.json\n  store screenshots [--out dir] [--sim url]\n                              Render each route at store sizes (fast mode: simulator, not the native UI)\n  store testers [--package id] [--track alpha] [--play-key file] [--json]\n                              Steps to get your 12 testers; add the Shipvo Testers group to the closed track\n  store status [--mark <step> [--as waiting|done]]\n                              Show each store's steps and what to do next\n  ci init --framework capacitor [--dry-run] [--force]\n                              Write .github/workflows/shipvo-build.yml (signed Android and iOS builds)\n  status [--app id] [--json]  Show how releases do; --json lists what to do next (exit 0 ok, 1 action needed, 2 error)\n  agents setup [--dry-run] [--json]  Write AGENTS.md section and .mcp.json for AI agents\n  audit <app> [--format json|csv] [--limit n]  Export the audit log to stdout\n  test [files] [--repair [--write]] [--report <file> [--release <id>]]  Run tests/*.steps; --repair shows a diff for broken steps, --write saves it; --report writes JSON results keyed by commit and release\n  doctor [--port <n>]         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 const COMMANDS: readonly ["init", "sim", "smoke", "run", "explore", "lumi", "preview", "publish", "promote", "auto-halt", "rollback", "app", "eas", "login", "doctor", "store", "ci", "status", "agents", "skills", "audit", "migrate", "approvals", "test", "keys", "mcp", "keygen", "pubkey", "hash", "sign-file", "sign-json", "verify-json", "verify"];
+export declare const help = "shipvo <command>\n\nStart\n  init <dir> [--json]         Create a new app wired to Shipvo\n  sim [--port 4545]           Build the app and run it in the simulator\n  sim --watch [--verbose]     Rebuild on file changes and keep serving; --verbose shows full build errors\n                              First run installs playwright and, if no Chrome or Edge is found, downloads Chromium once.\n                              Set SHIPVO_NO_AUTO_INSTALL=1 to turn the automatic installs off.\n  smoke [android|ios] [--timeout 30] [--json]  Check the app loads in the simulator as the Android (default) or iPhone-style phone: no thrown errors, a first screen with elements (exit 0 ok, 1 failed, 2 setup error)\n  run android|ios [--no-open] [--port n] [--lan]  Open the app in a phone frame in your browser (no Playwright)\n                              --lan also serves it to a phone on your Wi-Fi: URL + QR code, token required\n  run android|ios --native    Run on an emulator or simulator with npx expo run:android / run:ios\n  explore [--max-depth 3] [--max-steps 100] [--seed 1] [--flows [signup,login,search,add-to-cart,checkout]] [--fail-on-findings] [--changed-from <sha>] [--issues-dir <dir>] [--json]  Walk the app in the simulator, write explore-report.md and .json\n  lumi [android|ios] [--ui-port 4547] [--no-open]  Open the app on Shipvo Phone with the Lumi sidebar: live feed, findings, coverage, and a command box (test my app, test <flow>, stop, replay bug <n>)\n  preview [--json]            Publish a public 24-hour preview link (here.now, no account)\n\nShip\n  publish [--bands b0,b1,b2] [--release N]  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  promote [--to b1,b2]        Widen a staged release to more bands (same release, new signature)\n  promote --dry-run           Preview a promote, write nothing\n  promote --report <file>     Refuse to widen when the test report has a failing flow for this release\n  auto-halt [--threshold 0.2 --min-reports 20 | --off]  Show, turn on or turn off auto-halt\n  rollback --to <release>     Republish an earlier release as a new release\n  rollback --to <n> --dry-run Preview a rollback, write nothing\n  app create | list | delete  Register, list or remove apps on the hosted control plane\n  eas setup [--dry-run] [--run]  Make a Capacitor repo ready for eas build and submit (your own Expo account)\n  eas build [args]            Link the iOS scheme, then run eas build\n  login [--json]              Sign in with GitHub and get a key for the hosted simulator\n  store details --dry-run     Draft Play Data safety answers and a privacy policy from shipvo.json\n  store setup [--company yes|no] [--android-now] [--play-account-before-2023-11-13]\n                              Pick the store accounts to open and write store-plan.json\n  store screenshots [--out dir] [--sim url]\n                              Render each route at store sizes (fast mode: simulator, not the native UI)\n  store testers [--package id] [--track alpha] [--play-key file] [--json]\n                              Steps to get your 12 testers; add the Shipvo Testers group to the closed track\n  store status [--mark <step> [--as waiting|done]]\n                              Show each store's steps and what to do next\n  ci init --check             Write .github/workflows/shipvo-check.yml (test and explore on every pull request)\n  ci init --framework capacitor [--dry-run] [--force]\n                              Write .github/workflows/shipvo-build.yml (signed Android and iOS builds)\n  status [--app id] [--json]  Show how releases do; --json lists what to do next (exit 0 ok, 1 action needed, 2 error)\n  agents setup [--dry-run] [--json]  Write AGENTS.md section and .mcp.json for AI agents, and copy the skills of your @shipvo/* dependencies\n  skills sync [--dry-run] [--json]   Only copy the skills of your @shipvo/* dependencies into .agents/skills and .claude/skills\n  approvals list|approve <id> [--app id] [--json]  List promotes held for a second owner, or approve one\n  audit <app> [--format json|csv] [--limit n] [--json]  Export the audit log to stdout\n  test [files] [--repair [--write]] [--report <file> [--release <id>] [--platform android|ios] [--upload]] [--json]  Run tests/*.steps; --repair shows a diff for broken steps, --write saves it; --report writes JSON results keyed by commit and release\n  doctor [--port <n>] [--json]  Check setup before first publish\n  migrate --plan [--json]     Read-only plan to switch from Expo EAS Update (expo-updates) to Shipvo\n  migrate --apply [--force] [--json]  Make the safe edits (EAS Update or CodePush) (backups in .shipvo/migrate-backup/)\n  keys [--json]               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  keys rotate sign|upload     Sign a key rotation with the root key (offline), upload it\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;

package/dist/help.js

@@ -1,18 +1,21 @@
 export const COMMANDS = [
-    "init", "sim", "run", "explore", "preview", "publish", "promote", "auto-halt", "rollback", "app", "eas", "login", "doctor", "store", "ci", "status", "agents", "audit", "test", "keys", "mcp",
+    "init", "sim", "smoke", "run", "explore", "lumi", "preview", "publish", "promote", "auto-halt", "rollback", "app", "eas", "login", "doctor", "store", "ci", "status", "agents", "skills", "audit", "migrate", "approvals", "test", "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
+  init <dir> [--json]         Create a new app wired to Shipvo
   sim [--port 4545]           Build the app and run it in the simulator
   sim --watch [--verbose]     Rebuild on file changes and keep serving; --verbose shows full build errors
                               First run installs playwright and, if no Chrome or Edge is found, downloads Chromium once.
                               Set SHIPVO_NO_AUTO_INSTALL=1 to turn the automatic installs off.
-  run android|ios [--no-open] [--port n]  Open the app in a phone frame in your browser (no Playwright)
+  smoke [android|ios] [--timeout 30] [--json]  Check the app loads in the simulator as the Android (default) or iPhone-style phone: no thrown errors, a first screen with elements (exit 0 ok, 1 failed, 2 setup error)
+  run android|ios [--no-open] [--port n] [--lan]  Open the app in a phone frame in your browser (no Playwright)
+                              --lan also serves it to a phone on your Wi-Fi: URL + QR code, token required
   run android|ios --native    Run on an emulator or simulator with npx expo run:android / run:ios
-  explore [--max-depth 3] [--max-steps 100] [--fail-on-findings]  Walk the app in the simulator, write explore-report.md and .json
+  explore [--max-depth 3] [--max-steps 100] [--seed 1] [--flows [signup,login,search,add-to-cart,checkout]] [--fail-on-findings] [--changed-from <sha>] [--issues-dir <dir>] [--json]  Walk the app in the simulator, write explore-report.md and .json
+  lumi [android|ios] [--ui-port 4547] [--no-open]  Open the app on Shipvo Phone with the Lumi sidebar: live feed, findings, coverage, and a command box (test my app, test <flow>, stop, replay bug <n>)
   preview [--json]            Publish a public 24-hour preview link (here.now, no account)
 
 Ship
@@ -27,7 +30,7 @@ Ship
   app create | list | delete  Register, list or remove apps on the hosted control plane
   eas setup [--dry-run] [--run]  Make a Capacitor repo ready for eas build and submit (your own Expo account)
   eas build [args]            Link the iOS scheme, then run eas build
-  login                       Sign in with GitHub and get a key for the hosted simulator
+  login [--json]              Sign in with GitHub and get a key for the hosted simulator
   store details --dry-run     Draft Play Data safety answers and a privacy policy from shipvo.json
   store setup [--company yes|no] [--android-now] [--play-account-before-2023-11-13]
                               Pick the store accounts to open and write store-plan.json
@@ -37,16 +40,22 @@ Ship
                               Steps to get your 12 testers; add the Shipvo Testers group to the closed track
   store status [--mark <step> [--as waiting|done]]
                               Show each store's steps and what to do next
+  ci init --check             Write .github/workflows/shipvo-check.yml (test and explore on every pull request)
   ci init --framework capacitor [--dry-run] [--force]
                               Write .github/workflows/shipvo-build.yml (signed Android and iOS builds)
   status [--app id] [--json]  Show how releases do; --json lists what to do next (exit 0 ok, 1 action needed, 2 error)
-  agents setup [--dry-run] [--json]  Write AGENTS.md section and .mcp.json for AI agents
-  audit <app> [--format json|csv] [--limit n]  Export the audit log to stdout
-  test [files] [--repair [--write]] [--report <file> [--release <id>]]  Run tests/*.steps; --repair shows a diff for broken steps, --write saves it; --report writes JSON results keyed by commit and release
-  doctor [--port <n>]         Check setup before first publish
-  keys                        Show the stored key's status and quota
+  agents setup [--dry-run] [--json]  Write AGENTS.md section and .mcp.json for AI agents, and copy the skills of your @shipvo/* dependencies
+  skills sync [--dry-run] [--json]   Only copy the skills of your @shipvo/* dependencies into .agents/skills and .claude/skills
+  approvals list|approve <id> [--app id] [--json]  List promotes held for a second owner, or approve one
+  audit <app> [--format json|csv] [--limit n] [--json]  Export the audit log to stdout
+  test [files] [--repair [--write]] [--report <file> [--release <id>] [--platform android|ios] [--upload]] [--json]  Run tests/*.steps; --repair shows a diff for broken steps, --write saves it; --report writes JSON results keyed by commit and release
+  doctor [--port <n>] [--json]  Check setup before first publish
+  migrate --plan [--json]     Read-only plan to switch from Expo EAS Update (expo-updates) to Shipvo
+  migrate --apply [--force] [--json]  Make the safe edits (EAS Update or CodePush) (backups in .shipvo/migrate-backup/)
+  keys [--json]               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
+  keys rotate sign|upload     Sign a key rotation with the root key (offline), upload it
   mcp                         Print the MCP config that agents need
 
 Advanced

package/dist/hermes.d.ts

@@ -9,3 +9,13 @@ export declare function parseDeclared(v: unknown): number[] | undefined;
  * 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;
+/** Validate a Hermes engine build id such as "250829098.0.10". Undefined, null and "" mean "not declared". */
+export declare function parseEngine(v: unknown): string | undefined;
+/**
+ * The engine build of the Hermes compiler this project uses: the version of the `hermes-compiler` package
+ * (React Native 0.83+ depends on it), looked up from the project, then from react-native's own install.
+ * Returns undefined when it cannot be found or the version is not an engine id.
+ */
+export declare function installedHermesEngine(cwd: string): string | undefined;
+/** Refuse a publish when the app declares an engine build and the compiler in use is another one (or cannot be identified). Returns the id to record. */
+export declare function checkEngine(installed: string | undefined, declared: string | undefined): string | undefined;

package/dist/hermes.js

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 // 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.
@@ -39,3 +42,50 @@ export function checkBundle(file, bytes, declared) {
         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;
 }
+const ENGINE_ID = /^\d+\.\d+\.\d+$/;
+/** Validate a Hermes engine build id such as "250829098.0.10". Undefined, null and "" mean "not declared". */
+export function parseEngine(v) {
+    if (v === undefined || v === null || v === "")
+        return undefined;
+    if (typeof v !== "string" || !ENGINE_ID.test(v.trim()))
+        throw new Error(`hermesEngine must look like 250829098.0.10 (got ${JSON.stringify(v)})`);
+    return v.trim();
+}
+/**
+ * The engine build of the Hermes compiler this project uses: the version of the `hermes-compiler` package
+ * (React Native 0.83+ depends on it), looked up from the project, then from react-native's own install.
+ * Returns undefined when it cannot be found or the version is not an engine id.
+ */
+export function installedHermesEngine(cwd) {
+    const from = (base) => { try {
+        return createRequire(join(base, "package.json")).resolve("hermes-compiler/package.json");
+    }
+    catch {
+        return undefined;
+    } };
+    let path = from(cwd);
+    if (!path) {
+        try {
+            path = from(dirname(createRequire(join(cwd, "package.json")).resolve("react-native/package.json")));
+        }
+        catch { }
+    }
+    if (!path)
+        return undefined;
+    try {
+        const v = JSON.parse(readFileSync(path, "utf8")).version;
+        return typeof v === "string" && ENGINE_ID.test(v) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Refuse a publish when the app declares an engine build and the compiler in use is another one (or cannot be identified). Returns the id to record. */
+export function checkEngine(installed, declared) {
+    if (declared && installed !== declared) {
+        throw new Error(installed
+            ? `The app declares Hermes engine ${declared} (hermesEngine in shipvo.json), but hermes-compiler here is ${installed}. Build with the same Hermes as the shell, or update hermesEngine if the shell changed.`
+            : `The app declares Hermes engine ${declared} (hermesEngine in shipvo.json), but the hermes-compiler version could not be read from this project. Install hermes-compiler, or remove hermesEngine.`);
+    }
+    return installed;
+}

package/dist/init.d.ts

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

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")) {
@@ -153,7 +189,7 @@ 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}")
@@ -161,7 +197,7 @@ AI agents: npx -y @shipvo/mcp points Claude / Cursor / ChatGPT at the simulator;
 Next steps:
   1. cd ${dirArg}
   2. npm install                   # or pnpm install / bun install; needed before any shipvo command
-  3. npx shipvo sim                # open the app on a simulated phone in your browser
+  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
@@ -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

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[]>;