@shipvo/cli 0.1.5 → 0.1.6

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