@shipvo/cli 0.1.3 → 0.1.5

package/dist/agents.js

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { args } from "./config.js";
+export const BEGIN = "<!-- shipvo:begin -->";
+export const END = "<!-- shipvo:end -->";
+export const SKILL_LINE = "npx skills add shipvo/shipvo --skill shipvo -g";
+/** What kind of app lives in `dir`. A shipvo.json wins; then Capacitor, Expo, bare React Native. */
+export function detectProject(dir) {
+    if (existsSync(join(dir, "shipvo.json")))
+        return "shipvo";
+    let deps = {};
+    try {
+        const p = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        deps = { ...p.devDependencies, ...p.dependencies };
+    }
+    catch { /* no package.json */ }
+    if (existsSync(join(dir, "capacitor.config.ts")) || existsSync(join(dir, "capacitor.config.json")) || "@capacitor/core" in deps)
+        return "capacitor";
+    if ("expo" in deps)
+        return "expo";
+    if ("react-native" in deps)
+        return "react-native";
+    return "unknown";
+}
+const LABEL = { shipvo: "a Shipvo app", expo: "an Expo app", "react-native": "a bare React Native app", capacitor: "a Capacitor app", unknown: "an app" };
+/** The text between (and including) our markers. */
+export function agentsSection(kind) {
+    return [
+        BEGIN,
+        "## Shipvo",
+        "",
+        `This project is ${LABEL[kind]} that uses Shipvo for over-the-air updates and the app simulator.`,
+        "",
+        "- Use `shipvo` commands instead of editing release or signing files by hand.",
+        "- When you are not sure what to do next, run `shipvo status --json`. It prints `next`: the commands to run and why.",
+        "- Exit codes of `shipvo status --json`: 0 ok, 1 action needed, 2 error.",
+        "- To drive the app, use the `shipvo` MCP server from `.mcp.json` (`@shipvo/mcp`).",
+        END,
+    ].join("\n");
+}
+/** Put `section` between the markers. Text outside the markers is never changed. Returns null when the markers are broken (one missing, or END before BEGIN). */
+export function upsertSection(text, section) {
+    const b = text.indexOf(BEGIN);
+    const e = text.indexOf(END);
+    if ((b === -1) !== (e === -1) || (b !== -1 && e < b))
+        return null;
+    if (b !== -1 && e !== -1)
+        return text.slice(0, b) + section + text.slice(e + END.length);
+    if (!text.trim())
+        return section + "\n";
+    return text.replace(/\n*$/, "\n\n") + section + "\n";
+}
+const SERVER = { command: "npx", args: ["-y", "@shipvo/mcp"] };
+/** Add the `shipvo` server and keep every other server and key. Returns null if the file is not valid JSON. */
+export function mergeMcp(text) {
+    let doc = {};
+    if (text !== null && text.trim()) {
+        try {
+            doc = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        if (!doc || typeof doc !== "object" || Array.isArray(doc))
+            return null;
+    }
+    const servers = (doc.mcpServers && typeof doc.mcpServers === "object" ? doc.mcpServers : {});
+    servers.shipvo = SERVER;
+    return JSON.stringify({ ...doc, mcpServers: servers }, null, 2) + "\n";
+}
+/** `shipvo agents setup [--dry-run] [--json]`. Exit 0 done, 2 error. */
+export async function agentsCmd(argv, dir = process.cwd()) {
+    const [sub, ...rest] = argv;
+    if (sub !== "setup") {
+        console.error("Usage: shipvo agents setup [--dry-run] [--json]");
+        return 2;
+    }
+    const a = args(rest);
+    const dry = a["dry-run"] !== undefined, json = a.json !== undefined;
+    const kind = detectProject(dir);
+    const changes = [];
+    const writes = [];
+    const plan = (file, next, note) => {
+        const path = join(dir, file);
+        const old = existsSync(path) ? readFileSync(path, "utf8") : null;
+        if (next === null) {
+            changes.push({ file, action: "skip", note });
+            return;
+        }
+        if (old === next) {
+            changes.push({ file, action: "unchanged" });
+            return;
+        }
+        changes.push({ file, action: old === null ? "create" : "update" });
+        writes.push({ path, text: next });
+    };
+    const read = (f) => existsSync(join(dir, f)) ? readFileSync(join(dir, f), "utf8") : null;
+    plan("AGENTS.md", upsertSection(read("AGENTS.md") ?? "", agentsSection(kind)), "AGENTS.md has a broken shipvo marker; fix it and run again.");
+    const targets = [".mcp.json", ...(existsSync(join(dir, ".cursor")) ? [".cursor/mcp.json"] : [])];
+    for (const f of targets) {
+        const merged = mergeMcp(read(f));
+        plan(f, merged, `${f} is not valid JSON; I left it alone. Fix it and run again.`);
+    }
+    const bad = changes.some((c) => c.action === "skip");
+    if (!dry && !bad)
+        for (const w of writes) {
+            mkdirSync(dirname(w.path), { recursive: true });
+            writeFileSync(w.path, w.text);
+        }
+    const wrote = !dry && !bad;
+    if (json)
+        console.log(JSON.stringify({ ok: !bad, project: kind, dry_run: dry, changes, skill_install: SKILL_LINE }));
+    else {
+        console.log(`Project: ${LABEL[kind]}.`);
+        for (const c of changes)
+            console.log(`  ${c.file}: ${c.action === "skip" ? c.note : c.action === "unchanged" ? "already up to date" : `${dry ? "would " : ""}${c.action}${dry ? "" : "d"}`}`);
+        if (dry)
+            console.log("Dry run: nothing was written.");
+        else if (wrote && !changes.some((c) => c.action !== "unchanged"))
+            console.log("Nothing to change.");
+        console.log(`Install the skill: ${SKILL_LINE}`);
+    }
+    return bad ? 2 : 0;
+}

package/dist/audit.d.ts

@@ -0,0 +1,13 @@
+export declare const AUDIT_FLAGS: string[];
+export declare const AUDIT_COLUMNS: readonly ["id", "app_id", "at", "actor", "actor_kind", "action", "release", "release_id", "before", "after"];
+export declare const AUDIT_HELP = "Usage: shipvo audit <app> [--format json|csv] [--limit n]\n\nPrint the app's audit log, newest first, to stdout. Pages through the control plane.\n\nFlags (write a value after a space, not =):\n  --format json|csv   Output format (default json)\n  --limit n           Stop after n entries (default: all)\n  --help              Show this help\n\nNeeds SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).\n";
+type Row = Record<string, unknown> & {
+    id: number;
+};
+/** One CSV field: quoted, with "" for quotes. Values that start with = + - @ get a leading ' so spreadsheets do not run them. */
+export declare function csvField(v: unknown): string;
+export declare function toCsv(rows: Row[]): string;
+export declare function audit(argv: string[], deps?: {
+    fetchFn?: typeof fetch;
+}): Promise<void>;
+export {};

package/dist/audit.js

@@ -0,0 +1,75 @@
+// `shipvo audit <app>`: export an app's audit log as JSON or CSV on stdout.
+import { args as parse, loadConfig, publishToken } from "./config.js";
+export const AUDIT_FLAGS = ["format", "limit"];
+export const AUDIT_COLUMNS = ["id", "app_id", "at", "actor", "actor_kind", "action", "release", "release_id", "before", "after"];
+const PAGE = 200;
+export const AUDIT_HELP = `Usage: shipvo audit <app> [--format json|csv] [--limit n]
+
+Print the app's audit log, newest first, to stdout. Pages through the control plane.
+
+Flags (write a value after a space, not =):
+  --format json|csv   Output format (default json)
+  --limit n           Stop after n entries (default: all)
+  --help              Show this help
+
+Needs SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).
+`;
+/** One CSV field: quoted, with "" for quotes. Values that start with = + - @ get a leading ' so spreadsheets do not run them. */
+export function csvField(v) {
+    let s = v === null || v === undefined ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
+    if (/^[=+\-@]/.test(s))
+        s = "'" + s;
+    return `"${s.replace(/"/g, '""')}"`;
+}
+export function toCsv(rows) {
+    return [AUDIT_COLUMNS.map(csvField).join(","), ...rows.map((r) => AUDIT_COLUMNS.map((c) => csvField(r[c])).join(","))].join("\n");
+}
+export async function audit(argv, deps = {}) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(AUDIT_HELP);
+        return;
+    }
+    const bad = argv.filter((x) => x.startsWith("--") && !AUDIT_FLAGS.includes(x.slice(2)));
+    if (bad.length)
+        throw new Error(`Unknown flag ${bad.join(", ")}. Known flags: ${AUDIT_FLAGS.map((k) => "--" + k).join(" ")}`);
+    const a = parse(argv);
+    // Positional app id: the first argument that is not a flag or a flag's value.
+    const appId = argv.find((x, i) => !x.startsWith("--") && !(i > 0 && AUDIT_FLAGS.includes(argv[i - 1].slice(2)) && argv[i - 1].startsWith("--")));
+    if (!appId)
+        throw new Error("Usage: shipvo audit <app> [--format json|csv] [--limit n]");
+    const format = a.format ?? "json";
+    if (format !== "json" && format !== "csv")
+        throw new Error(`--format must be json or csv (got "${a.format}").`);
+    let max = Infinity;
+    if (argv.includes("--limit")) {
+        max = Number(a.limit);
+        if (!Number.isInteger(max) || max < 1)
+            throw new Error(`--limit must be a positive whole number (got "${a.limit}").`);
+    }
+    const token = process.env.SHIPVO_OWNER_TOKEN?.trim() || publishToken();
+    if (!token)
+        throw new Error("No credentials. Set SHIPVO_OWNER_TOKEN, or run `shipvo app create` to get a publish token (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).");
+    const base = loadConfig().controlPlane.replace(/\/$/, "");
+    const f = deps.fetchFn ?? fetch;
+    const rows = [];
+    let before;
+    while (rows.length < max) {
+        const want = Math.min(PAGE, max - rows.length);
+        const url = `${base}/audit/${encodeURIComponent(appId)}?limit=${want}${before !== undefined ? `&before=${before}` : ""}`;
+        let r;
+        try {
+            r = await f(url, { headers: { authorization: `Bearer ${token}` } });
+        }
+        catch (e) {
+            throw new Error(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
+        }
+        if (!r.ok)
+            throw new Error(`Audit request failed: HTTP ${r.status}${r.status === 401 ? " (the token was not accepted for this app)" : ""}.`);
+        const page = (await r.json()).rows ?? [];
+        rows.push(...page);
+        if (page.length < want)
+            break;
+        before = page[page.length - 1].id;
+    }
+    console.log(format === "csv" ? toCsv(rows) : JSON.stringify(rows, null, 2));
+}

package/dist/autohalt.d.ts

@@ -0,0 +1,5 @@
+export declare const AUTOHALT_FLAGS: string[];
+export declare const AUTOHALT_HELP = "Usage: shipvo auto-halt [flags]\n\nStop serving a release on its own when too many devices fail to apply it.\nWith no flags, print the current setting.\n\nFlags (write a value after a space, not =):\n  --threshold 0.2     Halt when more than this share of reports failed (above 0, at most 1)\n  --min-reports 20    Wait for this many reports first (1 to 10000, default 20)\n  --off               Turn auto-halt off\n  --dry-run           Print what would change, write nothing\n  --help              Show this help\n\nNeeds SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).\n";
+export declare function autoHalt(argv: string[], deps?: {
+    fetchFn?: typeof fetch;
+}): Promise<void>;

package/dist/autohalt.js

@@ -0,0 +1,84 @@
+// `shipvo auto-halt`: show, turn on or turn off auto-halt for this app, through the control plane.
+import { args as parse, loadConfig, publishToken } from "./config.js";
+import { describeAutoHalt } from "./status.js";
+export const AUTOHALT_FLAGS = ["threshold", "min-reports", "off", "dry-run"];
+export const AUTOHALT_HELP = `Usage: shipvo auto-halt [flags]
+
+Stop serving a release on its own when too many devices fail to apply it.
+With no flags, print the current setting.
+
+Flags (write a value after a space, not =):
+  --threshold 0.2     Halt when more than this share of reports failed (above 0, at most 1)
+  --min-reports 20    Wait for this many reports first (1 to 10000, default 20)
+  --off               Turn auto-halt off
+  --dry-run           Print what would change, write nothing
+  --help              Show this help
+
+Needs SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).
+`;
+const describe = (s) => describeAutoHalt(s.enabled ? { threshold: s.threshold, min_reports: s.min_reports } : null);
+export async function autoHalt(argv, deps = {}) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(AUTOHALT_HELP);
+        return;
+    }
+    const bad = argv.filter((x) => x.startsWith("--") && !AUTOHALT_FLAGS.includes(x.slice(2)));
+    if (bad.length) {
+        const eq = bad.find((x) => x.includes("="));
+        throw new Error(`Unknown flag ${bad.join(", ")}.${eq ? ` Write "${eq.replace("=", " ")}" (a space, not =).` : ""} Known flags: ${AUTOHALT_FLAGS.map((k) => "--" + k).join(" ")}`);
+    }
+    const a = parse(argv), cfg = loadConfig();
+    const dry = argv.includes("--dry-run"), off = argv.includes("--off");
+    const hasT = argv.includes("--threshold"), hasM = argv.includes("--min-reports");
+    if (off && (hasT || hasM))
+        throw new Error("--off cannot be combined with --threshold or --min-reports.");
+    let threshold, minReports = 20;
+    if (hasT || hasM) {
+        if (!hasT)
+            throw new Error("--min-reports needs --threshold too, for example --threshold 0.2 --min-reports 20.");
+        threshold = a.threshold === "true" || a.threshold === undefined ? NaN : Number(a.threshold);
+        if (!(threshold > 0 && threshold <= 1))
+            throw new Error(`--threshold must be a number above 0 and at most 1, for example 0.2 (got "${a.threshold}").`);
+        if (hasM) {
+            minReports = a["min-reports"] === "true" || a["min-reports"] === undefined ? NaN : Number(a["min-reports"]);
+            if (!Number.isInteger(minReports) || minReports < 1 || minReports > 10000)
+                throw new Error(`--min-reports must be a whole number from 1 to 10000 (got "${a["min-reports"]}").`);
+        }
+    }
+    const token = process.env.SHIPVO_OWNER_TOKEN?.trim() || publishToken();
+    if (!token)
+        throw new Error("No credentials. Set SHIPVO_OWNER_TOKEN, or run `shipvo app create` to get a publish token (SHIPVO_PUBLISH_TOKEN or .shipvo/publish-token).");
+    const base = cfg.controlPlane.replace(/\/$/, "");
+    const url = `${base}/app/${encodeURIComponent(cfg.appId)}/api/halt-config`;
+    const call = async (method, body) => {
+        let r;
+        try {
+            r = await (deps.fetchFn ?? fetch)(url, { method, headers: { authorization: `Bearer ${token}`, ...(body ? { "content-type": "application/json" } : {}) }, body: body ? JSON.stringify(body) : undefined });
+        }
+        catch (e) {
+            throw new Error(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
+        }
+        if (r.status === 401 || r.status === 403)
+            throw new Error(`The control plane at ${base} rejected your token (${r.status}). Check SHIPVO_OWNER_TOKEN or your publish token.`);
+        if (!r.ok) {
+            let m = "";
+            try {
+                m = (await r.json()).message ?? "";
+            }
+            catch { /* no body */ }
+            throw new Error(`Auto-halt request failed: HTTP ${r.status}${m ? ` ${m}` : ""}`);
+        }
+        return (await r.json());
+    };
+    if (!off && threshold === undefined) {
+        console.log(describe(await call("GET")));
+        return;
+    }
+    const want = off ? { enabled: false } : { enabled: true, threshold, min_reports: minReports };
+    if (dry) {
+        console.log(`Would set ${describe(want)}`);
+        console.log("Dry run: nothing was written.");
+        return;
+    }
+    console.log(describe(off ? await call("DELETE") : await call("PUT", { threshold, min_reports: minReports })));
+}

package/dist/ci.d.ts

@@ -0,0 +1,3 @@
+export declare const WORKFLOW_PATH: string;
+/** `shipvo ci init --framework capacitor [--dry-run] [--force]`. Returns the exit code. */
+export declare function ci(argv: string[], cwd?: string): Promise<number>;

package/dist/ci.js

@@ -0,0 +1,42 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { args } from "./config.js";
+export const WORKFLOW_PATH = join(".github", "workflows", "shipvo-build.yml");
+/** Find the template: next to the built CLI (npm), or in the repo's `templates/` (development). */
+function templatePath(framework) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const rel = join("templates", framework, "github-actions", "build.yml");
+    for (const c of [join(here, rel), join(here, "..", "..", "..", rel)])
+        if (existsSync(c))
+            return c;
+    throw new Error(`template for ${framework} not found`);
+}
+/** `shipvo ci init --framework capacitor [--dry-run] [--force]`. Returns the exit code. */
+export async function ci(argv, cwd = process.cwd()) {
+    const [sub, ...rest] = argv;
+    if (sub !== "init") {
+        console.error("Usage: shipvo ci init --framework capacitor [--dry-run] [--force]");
+        return 2;
+    }
+    const a = args(rest);
+    if (a.framework !== "capacitor") {
+        console.error("shipvo ci init: --framework capacitor is the only framework with a template so far");
+        return 2;
+    }
+    const body = readFileSync(templatePath("capacitor"), "utf8");
+    const target = resolve(cwd, WORKFLOW_PATH);
+    if (a["dry-run"] !== undefined && a["dry-run"] !== "false") {
+        console.log(`Would write ${WORKFLOW_PATH}${existsSync(target) ? " (file exists; --force needed)" : ""}. Nothing was written.\n`);
+        console.log(body);
+        return 0;
+    }
+    if (existsSync(target) && (a.force === undefined || a.force === "false")) {
+        console.error(`${WORKFLOW_PATH} already exists. Use --force to overwrite it.`);
+        return 1;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, body);
+    console.log(`Wrote ${WORKFLOW_PATH}. Add the secrets listed in docs/capacitor.md, then run the "Shipvo build" workflow.`);
+    return 0;
+}

package/dist/cli.js

@@ -5,104 +5,158 @@ import { b64, keyFromSeed, sha256Hex, signBytes, signDoc, verifyDoc } from "./in
 import { seed } from "./config.js";
 import { init } from "./init.js";
 import { publish, rollback } from "./publish.js";
+import { promote } from "./promote.js";
+import { autoHalt } from "./autohalt.js";
+import { explore } from "./explore.js";
 import { sim } from "./sim.js";
+import { preview } from "./preview.js";
+import { run } from "./run.js";
 import { keys, login, mcp } from "./login.js";
 import { verifyPointer } from "./verify.js";
 import { signingKey } from "./signing.js";
 import { appCmd } from "./app.js";
+import { status } from "./status.js";
+import { agentsCmd } from "./agents.js";
 import { doctor } from "./doctor.js";
-import { help, unknownCommand } from "./help.js";
+import { audit } from "./audit.js";
+import { store } from "./store.js";
+import { ci } from "./ci.js";
+import { easCmd } from "./eas.js";
+import { testCmd } from "./test.js";
+import { failure, help, unknownCommand } from "./help.js";
 const [cmd, ...rest] = process.argv.slice(2);
-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 "doctor":
-        await doctor(rest);
-        break;
-    case "app":
-        await appCmd(rest);
-        break;
-    case "keys":
-        if (rest[0] === "export" || rest[0] === "import")
-            await signingKey(rest);
-        else
-            await keys();
-        break;
-    case "mcp":
-        mcp();
-        break;
-    case "keygen": {
-        const s = b64(randomBytes(32));
-        const out = rest[rest.indexOf("--out") + 1];
-        if (rest.includes("--out") && out) {
-            writeFileSync(out, s, { mode: 0o600 });
-            console.error(`Seed written to ${out}. Back it up offline; never commit it.`);
+try {
+    switch (cmd) {
+        case "init":
+            await init(rest);
+            break;
+        case "sim":
+            await sim(rest);
+            break;
+        case "explore":
+            process.exitCode = await explore(rest);
+            break;
+        case "run":
+            process.exitCode = await run(rest);
+            break;
+        case "preview":
+            await preview(rest);
+            break;
+        case "publish":
+            await publish(rest);
+            break;
+        case "promote":
+            await promote(rest);
+            break;
+        case "auto-halt":
+            await autoHalt(rest);
+            break;
+        case "rollback":
+            await rollback(rest);
+            break;
+        case "login":
+            await login(rest);
+            break;
+        case "doctor":
+            await doctor(rest);
+            break;
+        case "status":
+            process.exitCode = await status(rest);
+            break;
+        case "agents":
+            process.exitCode = await agentsCmd(rest);
+            break;
+        case "audit":
+            await audit(rest);
+            break;
+        case "test":
+            process.exitCode = await testCmd(rest);
+            break;
+        case "store":
+            await store(rest);
+            break;
+        case "ci":
+            process.exitCode = await ci(rest);
+            break;
+        case "eas":
+            process.exitCode = await easCmd(rest);
+            break;
+        case "app":
+            await appCmd(rest);
+            break;
+        case "keys":
+            if (rest[0] === "export" || rest[0] === "import")
+                await signingKey(rest);
+            else
+                await keys();
+            break;
+        case "mcp":
+            mcp();
+            break;
+        case "keygen": {
+            const s = b64(randomBytes(32));
+            const out = rest[rest.indexOf("--out") + 1];
+            if (rest.includes("--out") && out) {
+                writeFileSync(out, s, { mode: 0o600 });
+                console.error(`Seed written to ${out}. Back it up offline; never commit it.`);
+            }
+            else
+                console.log(`seed (secret): ${s}`);
+            console.log(`public key: ${b64(keyFromSeed(s).publicKey)}`);
+            break;
         }
-        else
-            console.log(`seed (secret): ${s}`);
-        console.log(`public key: ${b64(keyFromSeed(s).publicKey)}`);
-        break;
-    }
-    case "pubkey":
-        console.log(b64(keyFromSeed(seed()).publicKey));
-        break;
-    case "hash": {
-        const b = readFileSync(rest[0]);
-        console.log(JSON.stringify({ sha256: sha256Hex(b), size: b.length }));
-        break;
-    }
-    case "sign-file":
-        console.log(signBytes(new Uint8Array(readFileSync(rest[0])), seed()));
-        break;
-    case "sign-json": {
-        const d = JSON.parse(readFileSync(rest[0], "utf8"));
-        writeFileSync(rest[0], JSON.stringify(signDoc(d, seed()), null, 2));
-        console.log("signed");
-        break;
-    }
-    case "verify-json": {
-        const ok = verifyDoc(JSON.parse(readFileSync(rest[0], "utf8")), rest[1]);
-        console.log(ok ? "valid" : "INVALID");
-        process.exit(ok ? 0 : 1);
-    }
-    case "verify": {
-        if (!rest[0]) {
-            console.error("Usage: shipvo verify <pointer file> [public-key-b64]");
-            process.exit(2);
+        case "pubkey":
+            console.log(b64(keyFromSeed(seed()).publicKey));
+            break;
+        case "hash": {
+            const b = readFileSync(rest[0]);
+            console.log(JSON.stringify({ sha256: sha256Hex(b), size: b.length }));
+            break;
+        }
+        case "sign-file":
+            console.log(signBytes(new Uint8Array(readFileSync(rest[0])), seed()));
+            break;
+        case "sign-json": {
+            const d = JSON.parse(readFileSync(rest[0], "utf8"));
+            writeFileSync(rest[0], JSON.stringify(signDoc(d, seed()), null, 2));
+            console.log("signed");
+            break;
         }
-        const key = rest[1] ?? b64(keyFromSeed(seed()).publicKey);
-        let text;
-        try {
-            text = readFileSync(rest[0], "utf8");
+        case "verify-json": {
+            const ok = verifyDoc(JSON.parse(readFileSync(rest[0], "utf8")), rest[1]);
+            console.log(ok ? "valid" : "INVALID");
+            process.exit(ok ? 0 : 1);
         }
-        catch {
-            console.error(`Cannot read ${rest[0]}`);
-            process.exit(2);
+        case "verify": {
+            if (!rest[0]) {
+                console.error("Usage: shipvo verify <pointer file> [public-key-b64]");
+                process.exit(2);
+            }
+            const key = rest[1] ?? b64(keyFromSeed(seed()).publicKey);
+            let text;
+            try {
+                text = readFileSync(rest[0], "utf8");
+            }
+            catch {
+                console.error(`Cannot read ${rest[0]}`);
+                process.exit(2);
+            }
+            const ok = verifyPointer(text, key);
+            console.log(ok ? "valid" : "INVALID");
+            process.exit(ok ? 0 : 1);
         }
-        const ok = verifyPointer(text, key);
-        console.log(ok ? "valid" : "INVALID");
-        process.exit(ok ? 0 : 1);
+        case undefined:
+        case "--help":
+        case "-h":
+        case "help":
+            console.log(help);
+            break;
+        default:
+            console.error(unknownCommand(cmd));
+            process.exit(1);
     }
-    case undefined:
-    case "--help":
-    case "-h":
-    case "help":
-        console.log(help);
-        break;
-    default:
-        console.error(unknownCommand(cmd));
-        process.exit(1);
+}
+catch (e) {
+    console.error(failure(e));
+    process.exit(1);
 }

package/dist/config.d.ts

@@ -9,10 +9,20 @@ export type ShipvoConfig = {
     publicKey: string;
     /** Hermes bytecode version(s) the app's shells run. If set, `shipvo publish` refuses bundles that differ. */
     hermesBytecodeVersion?: number | number[];
+    /** What AI agents may do through `@shipvo/mcp` owner commands. "ask" (default): irreversible commands need confirm: true. "deny": they are refused. "allow": no confirm step (the owner must set it). */
+    agentPolicy?: "ask" | "deny" | "allow";
+    /** Owner commands agents may never run. */
+    agentDeny?: string[];
     /** Where `shipvo publish` writes: the control plane's Cloudflare KV namespace. */
     kv?: {
         namespaceId: string;
     };
+    /** Where `shipvo preview` publishes: "here.now" (default, no account) or "control-plane" (not built yet). */
+    preview?: "here.now" | "control-plane";
+    /** Release rules checked by `shipvo publish --dry-run`. Validated there, not at load, so a bad section never breaks other commands. */
+    policy?: unknown;
+    /** Deep links `shipvo explore` opens after the start screen (for example "tide://cart"). Needs an onUrl listener in the app. */
+    routes?: string[];
     /** Marketplace listing (hosted control plane): shown to agents and on shipvo.dev once reviewed. */
     listing?: {
         public?: boolean;