@shipvo/cli 0.1.4 → 0.1.6

package/dist/smoke.js

@@ -0,0 +1,117 @@
+// `shipvo smoke`: does the app load? Starts the simulator (startSim), opens the app, waits for the first screen to settle.
+import { existsSync } from "node:fs";
+import { args as parse, BOOLEAN_FLAGS, loadConfig } from "./config.js";
+import { simDriver, startSim } from "./explore.js";
+import { detectPackageManager, installCommand } from "./ensure-playwright.js";
+import { emit, envelope } from "./json-out.js";
+const MAX_ERRORS = 5;
+/** Elements in an accessibility tree: lines that carry a ref. */
+export const countElements = (tree) => (tree ?? "").split("\n").filter((l) => /\[ref=/.test(l)).length;
+async function screenOf(base, session) {
+    const r = await fetch(base.replace(/\/$/, "") + "/act", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ session, action: "screen" }), signal: AbortSignal.timeout(30000) });
+    if (!r.ok)
+        throw new Error(`simulator /act -> ${r.status}`);
+    return (await r.json()).screen ?? "";
+}
+const installNext = () => { const { cmd, args } = installCommand(detectPackageManager(process.cwd(), existsSync)); return { command: `${cmd} ${args.join(" ")} && npx playwright install chromium`, why: "Install the browser the simulator needs." }; };
+/** Words that are not flags or flag values: the platform. */
+const positionals = (argv) => { const out = []; for (let i = 0; i < argv.length; i++) {
+    const x = argv[i];
+    if (x.startsWith("--")) {
+        if (!BOOLEAN_FLAGS.has(x.slice(2)) && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--"))
+            i++;
+    }
+    else
+        out.push(x);
+} return out; };
+/** Runs the check and returns the envelope and exit code. Never prints. */
+export async function smokeCheck(argv, deps) {
+    const a = parse(argv);
+    const setup = (msg, next = [{ command: "shipvo doctor --json", why: "Check the setup." }]) => ({ doc: envelope("setup_error", msg, {}, next, 2), exit: 2 });
+    const pos = positionals(argv);
+    if (pos.length > 1 || (pos[0] !== undefined && pos[0] !== "android" && pos[0] !== "ios"))
+        return setup(`Unknown platform "${pos.join(" ")}". Use android or ios.`, [{ command: "shipvo smoke android", why: "Pick android or ios." }, { command: "shipvo smoke ios", why: "Or the iPhone style." }]);
+    const platform = pos[0] === "ios" ? "ios" : "android";
+    const t = a.timeout === undefined ? 30 : Number(a.timeout);
+    if (!(t > 0) || !Number.isFinite(t))
+        return setup("--timeout must be a number of seconds above 0", [{ command: "shipvo smoke --timeout 30", why: "Use a positive number." }]);
+    let cfg;
+    try {
+        cfg = loadConfig();
+    }
+    catch (e) {
+        return setup(e instanceof Error ? e.message : String(e), [{ command: "shipvo init .", why: "Set up this folder." }]);
+    }
+    const json = argv.includes("--json");
+    let sim;
+    try {
+        sim = await (deps?.start ?? (() => startSim(a, cfg, json)))();
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        const browser = /playwright|chromium|browser|exited before it was ready/i.test(msg);
+        return setup(msg, browser ? [installNext(), { command: "shipvo doctor --json", why: "Check the setup." }] : undefined);
+    }
+    let timer;
+    try {
+        const session = `smoke-${Date.now().toString(36)}`;
+        const driver = (deps?.driver ?? simDriver)(sim.base, cfg.appId, session, platform);
+        const get = deps?.screen ?? screenOf;
+        const started = Date.now();
+        const timedOut = new Promise((ok) => { timer = setTimeout(() => ok("timeout"), t * 1000); });
+        const run = (async () => {
+            const opened = await driver.open();
+            if (!opened.ok)
+                throw new Error(opened.error ?? "the simulator could not open the app");
+            let tree = opened.screen ?? "";
+            // Settled: two snapshots in a row are the same.
+            for (let i = 0; i < 20; i++) {
+                const next = await get(sim.base, session);
+                const same = next === tree;
+                tree = next;
+                if (same)
+                    break;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+            return { ms: Date.now() - started, tree, errors: await driver.errors() };
+        })();
+        run.catch(() => { });
+        const r = await Promise.race([run, timedOut]);
+        if (r === "timeout") {
+            const data = { platform, time_to_first_screen_ms: null, elements: 0, errors: [], error_count: 0 };
+            return { doc: envelope("timeout", `The app did not show a first screen within ${t} s`, data, [{ command: `shipvo smoke ${platform} --timeout ${Math.ceil(t * 2)} --json`, why: "Try a longer timeout." }], 1), exit: 1 };
+        }
+        const elements = countElements(r.tree);
+        const data = { platform, time_to_first_screen_ms: r.ms, elements, errors: r.errors.slice(0, MAX_ERRORS), error_count: r.errors.length };
+        if (r.errors.length)
+            return { doc: envelope("errors", `The app threw ${r.errors.length} error${r.errors.length === 1 ? "" : "s"} while loading: ${r.errors[0]}`, data, [{ command: `shipvo smoke ${platform} --json`, why: "Run again after fixing." }], 1), exit: 1 };
+        if (!elements)
+            return { doc: envelope("empty_screen", "The first screen has no elements", data, [{ command: `shipvo smoke ${platform} --json`, why: "Run again after fixing." }], 1), exit: 1 };
+        return { doc: envelope("ok", `The app loads on ${platform}: first screen in ${r.ms} ms, ${elements} element${elements === 1 ? "" : "s"}, no errors`, data, [{ command: "shipvo test --json", why: "Run your step files." }], 0), exit: 0 };
+    }
+    catch (e) {
+        return setup(e instanceof Error ? e.message : String(e));
+    }
+    finally {
+        clearTimeout(timer);
+        sim.stop();
+    }
+}
+/** Returns the exit code: 0 loads, 1 failed, 2 setup error. */
+export async function smoke(argv) {
+    const { doc, exit } = await smokeCheck(argv);
+    if (argv.includes("--json"))
+        emit(doc);
+    else {
+        console.log(doc.summary);
+        const d = doc.data;
+        for (const e of d.errors ?? [])
+            console.log(`  error: ${e}`);
+        if ((d.error_count ?? 0) > (d.errors?.length ?? 0))
+            console.log(`  …and ${d.error_count - d.errors.length} more`);
+        if (exit)
+            for (const n of doc.next)
+                console.error(`Next: ${n.command}  (${n.why})`);
+    }
+    return exit;
+}

package/dist/spawn-bin.d.ts

@@ -0,0 +1,11 @@
+export interface SpawnCall {
+    command: string;
+    args: string[];
+    shell?: boolean;
+}
+/**
+ * Build the arguments for `spawn`. On Windows, npx, npm and pnpm are `.cmd`
+ * shims, which need a shell, so the args are quoted for cmd.exe.
+ * On other platforms the call is returned unchanged.
+ */
+export declare function spawnBin(command: string, args: string[], platform?: NodeJS.Platform): SpawnCall;

package/dist/spawn-bin.js

@@ -0,0 +1,21 @@
+const WIN_CMD_SHIMS = new Set(["npx", "npm", "pnpm"]);
+const NEEDS_QUOTES = /[\s&|<>^(),;=]/;
+function quoteForCmd(arg) {
+    if (!NEEDS_QUOTES.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Build the arguments for `spawn`. On Windows, npx, npm and pnpm are `.cmd`
+ * shims, which need a shell, so the args are quoted for cmd.exe.
+ * On other platforms the call is returned unchanged.
+ */
+export function spawnBin(command, args, platform = process.platform) {
+    if (platform !== "win32")
+        return { command, args };
+    return {
+        command: WIN_CMD_SHIMS.has(command) ? `${command}.cmd` : command,
+        args: args.map(quoteForCmd),
+        shell: true,
+    };
+}

package/dist/status.d.ts

@@ -1,3 +1,5 @@
+import { type Next } from "./json-out.js";
+export type { Next };
 type Row = {
     release: number;
     events: Record<string, number>;
@@ -8,9 +10,77 @@ type AutoHalt = {
     threshold: number;
     min_reports: number;
 } | null;
+type Halted = {
+    release: number;
+    reports: number;
+    failed: number;
+    threshold: number;
+};
 /** Plain-text table: one row per release, one column per event name, then the two medians. */
 export declare function formatStatus(releases: Row[]): string;
+/** What a band serves: a release number, null when it has none (404), or "?" when it cannot be read. */
+export type BandValue = number | null | "?";
+/** Release each band serves, from the public pointer. A halted release or a failed read gives "?", not "no release". */
+export declare function fetchBands(base: string, appId: string, major: number, fetchFn: typeof fetch): Promise<Record<string, BandValue>>;
+/** "bands: b0=4 b1=4 b2=4", plus a hint to promote when readable bands differ. "-" is no release, "?" is unreadable. */
+export declare function describeBands(bands: Record<string, BandValue>): string[];
 /** "auto-halt: off" or "auto-halt: on at 20% after 20 reports". */
 export declare function describeAutoHalt(c: AutoHalt | undefined): string;
+export type TestRelease = {
+    release: number;
+    passing: number;
+    failing: number;
+    failing_flows?: {
+        name: string;
+        first_failed_release: number;
+    }[];
+};
+/** Test results the app uploaded with shipvo test --upload. Empty when none exist or the control plane cannot say. */
+export declare function fetchTestResults(base: string, appId: string, fetchFn: typeof fetch): Promise<TestRelease[]>;
+/** "tests: release 3: 2 failing (checkout, since release 2)" lines, newest first. */
+export declare function describeTests(tests: TestRelease[]): string[];
+export type StatusJson = {
+    ok: boolean;
+    code: "ok" | "no_project" | "no_signing_key" | "release_halted" | "no_release" | "error";
+    summary: string;
+    data: {
+        project: {
+            kind: string;
+            app_id: string | null;
+        };
+        sim: {
+            running: boolean;
+            port: number;
+        };
+        run_server: {
+            running: boolean;
+            port: number | null;
+        };
+        signing_key: {
+            present: boolean;
+        };
+        pending_release: {
+            newest: number | null;
+            halted: Halted | null;
+            auto_halt: AutoHalt | null;
+        } | null;
+        store_step: {
+            id: string;
+            title: string;
+            state: string;
+        } | null;
+        skills: {
+            package: string;
+            name: string;
+            synced: boolean;
+        }[];
+        tests: TestRelease[];
+    };
+    next: Next[];
+};
+/** `shipvo status --json`: exit 0 ok, 1 action needed, 2 error. */
+export declare function statusJson(appArg: string | undefined, fetchFn: typeof fetch, dir?: string): Promise<{
+    doc: StatusJson;
+    exit: number;
+}>;
 export declare function status(argv: string[], fetchFn?: typeof fetch): Promise<number>;
-export {};

package/dist/status.js

@@ -1,4 +1,10 @@
-import { args, loadConfig } from "./config.js";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { routeStore } from "@shipvo/store";
+import { args, loadConfig, publishToken } from "./config.js";
+import { detectProject, skillStatus } from "./agents.js";
+import { portFree } from "./sim.js";
+import { emit } from "./json-out.js";
 const ms = (v) => (typeof v === "number" ? String(Math.round(v)) : "-");
 /** Plain-text table: one row per release, one column per event name, then the two medians. */
 export function formatStatus(releases) {
@@ -8,6 +14,41 @@ export function formatStatus(releases) {
     const w = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
     return rows.map((r) => r.map((c, i) => (i === 0 ? c.padEnd(w[i]) : c.padStart(w[i]))).join("  ")).join("\n");
 }
+const BANDS = ["b0", "b1", "b2"];
+/** Release each band serves, from the public pointer. A halted release or a failed read gives "?", not "no release". */
+export async function fetchBands(base, appId, major, fetchFn) {
+    const out = {};
+    await Promise.all(BANDS.map(async (b) => {
+        out[b] = "?";
+        try {
+            const r = await fetchFn(`${base}/p/${encodeURIComponent(appId)}/${major}/${b}`);
+            if (r.status === 404) {
+                // Only "no_release" means none. release_halted and mismatch errors also answer 404.
+                const e = (await r.json().catch(() => null));
+                if (e?.error === "no_release")
+                    out[b] = null;
+                return;
+            }
+            if (!r.ok)
+                return;
+            const env = (await r.json());
+            const rel = JSON.parse(String(env.body)).release;
+            if (typeof rel === "number")
+                out[b] = rel;
+        }
+        catch { /* unreadable: show "?" */ }
+    }));
+    return out;
+}
+/** "bands: b0=4 b1=4 b2=4", plus a hint to promote when readable bands differ. "-" is no release, "?" is unreadable. */
+export function describeBands(bands) {
+    const line = `bands: ${BANDS.map((b) => `${b}=${bands[b] ?? "-"}`).join(" ")}`;
+    const readable = BANDS.map((b) => bands[b] ?? null).filter((v) => v !== "?");
+    if (new Set(readable).size < 2)
+        return [line];
+    const newest = Math.max(...readable.filter((v) => v !== null));
+    return [line, `Bands differ. Run shipvo promote to give every band the newest release (${newest}).`];
+}
 /** "auto-halt: off" or "auto-halt: on at 20% after 20 reports". */
 export function describeAutoHalt(c) {
     if (!c || typeof c.threshold !== "number")
@@ -15,8 +56,122 @@ export function describeAutoHalt(c) {
     const n = c.min_reports ?? 20;
     return `auto-halt: on at ${Math.round(c.threshold * 1000) / 10}% after ${n} report${n === 1 ? "" : "s"}`;
 }
+/** Test results the app uploaded with shipvo test --upload. Empty when none exist or the control plane cannot say. */
+export async function fetchTestResults(base, appId, fetchFn) {
+    const token = publishToken();
+    if (!token)
+        return [];
+    try {
+        const r = await fetchFn(`${base}/r/${encodeURIComponent(appId)}/tests`, { headers: { authorization: `Bearer ${token}` } });
+        if (!r.ok)
+            return [];
+        const d = (await r.json());
+        return Array.isArray(d.releases) ? d.releases : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** "tests: release 3: 2 failing (checkout, since release 2)" lines, newest first. */
+export function describeTests(tests) {
+    return tests.map((t) => `tests: release ${t.release}: ${t.failing ? `${t.failing} failing (${(t.failing_flows ?? []).map((f) => `${f.name}${f.first_failed_release === t.release ? "" : `, since release ${f.first_failed_release}`}`).join("; ")})` : `all ${t.passing} passing`}`);
+}
+const alive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} };
+/** Local facts for `status --json`: no network. */
+async function localFacts(dir, simPort = 4545) {
+    const hasKey = !!(process.env.SHIPVO_SIGNING_SEED || process.env.PURENATIVE_SIGNING_SEED || (process.env.SHIPVO_SIGNING_SEED_FILE && existsSync(process.env.SHIPVO_SIGNING_SEED_FILE)) || (process.env.PURENATIVE_SIGNING_SEED_FILE && existsSync(process.env.PURENATIVE_SIGNING_SEED_FILE)) || existsSync(join(dir, ".shipvo", "seed.txt")));
+    let run = { running: false, port: null };
+    try {
+        const r = JSON.parse(readFileSync(join(dir, ".shipvo", "run.json"), "utf8"));
+        if (typeof r.pid === "number" && alive(r.pid))
+            run = { running: true, port: typeof r.port === "number" ? r.port : null };
+    }
+    catch { /* not running */ }
+    let storeStep = null;
+    try {
+        const plan = JSON.parse(readFileSync(join(dir, "store-plan.json"), "utf8"));
+        const r = routeStore(plan.answers);
+        const step = [...r.play.steps, ...r.apple.steps].find((x) => (plan.marks?.[x.id] ?? "todo") !== "done");
+        if (step)
+            storeStep = { id: step.id, title: step.title, state: plan.marks?.[step.id] ?? "todo" };
+    }
+    catch { /* no plan */ }
+    return { hasKey, run, storeStep, sim: { running: !(await portFree(simPort)), port: simPort } };
+}
+/** `shipvo status --json`: exit 0 ok, 1 action needed, 2 error. */
+export async function statusJson(appArg, fetchFn, dir = process.cwd()) {
+    const kind = detectProject(dir);
+    const f = await localFacts(dir);
+    const shared = { sim: f.sim, run_server: f.run, signing_key: { present: f.hasKey }, store_step: f.storeStep, skills: skillStatus(dir) };
+    let tests = [];
+    const mk = (code, summary, next, appId, pending, exit) => ({
+        doc: { ok: exit === 0, code, summary, data: { project: { kind, app_id: appId }, ...shared, pending_release: pending, tests }, next }, exit,
+    });
+    if (!existsSync(join(dir, "shipvo.json"))) {
+        return mk("no_project", "No shipvo.json here.", [{ command: kind === "unknown" ? "shipvo init myapp" : "shipvo init .", why: "This folder is not set up for Shipvo yet." }], null, null, 1);
+    }
+    let cfg;
+    try {
+        cfg = loadConfig(dir);
+    }
+    catch (e) {
+        return mk("error", e instanceof Error ? e.message : String(e), [{ command: "shipvo doctor", why: "shipvo.json is missing a field." }], null, null, 2);
+    }
+    const appId = appArg ?? cfg.appId;
+    let data;
+    const baseUrl = cfg.controlPlane.replace(/\/$/, "");
+    try {
+        const r = await fetchFn(`${baseUrl}/t/${encodeURIComponent(appId)}/summary`);
+        if (!r.ok)
+            throw new Error(`HTTP ${r.status}`);
+        data = (await r.json());
+    }
+    catch (e) {
+        return mk("error", `Could not reach the control plane at ${baseUrl} (${e instanceof Error ? e.message : String(e)}).`, [{ command: "shipvo doctor", why: "Check the control plane URL and network." }], appId, null, 2);
+    }
+    const releases = data.releases ?? [];
+    tests = await fetchTestResults(baseUrl, appId, fetchFn);
+    const pending = { newest: releases.length ? Math.max(...releases.map((r) => r.release)) : null, halted: data.halted ?? null, auto_halt: data.auto_halt ?? null };
+    const next = [];
+    let code = "ok", exit = 0;
+    let summary = pending.newest === null ? `No releases with telemetry yet for "${appId}".` : `Newest release ${pending.newest} is reporting for "${appId}".`;
+    if (!f.hasKey) {
+        code = "no_signing_key";
+        exit = 1;
+        summary = "No signing key found.";
+        next.push({ command: "shipvo keygen --out .shipvo/seed.txt", why: "You cannot publish without a signing key." });
+    }
+    if (pending.halted) {
+        code = "release_halted";
+        exit = 1;
+        summary = `Release ${pending.halted.release} is halted: ${pending.halted.failed} of ${pending.halted.reports} devices failed.`;
+        const prev = releases.map((r) => r.release).filter((n) => n < pending.halted.release);
+        const to = prev.length ? String(Math.max(...prev)) : "<release>";
+        next.unshift({ command: `shipvo rollback --to ${to}`, why: "Send devices back to a release that works, or publish a fixed one." });
+    }
+    else if (code === "ok" && pending.newest === null) {
+        code = "no_release";
+        next.push({ command: "shipvo publish --dry-run", why: "Check a first release before you publish it." });
+    }
+    if (!f.sim.running && !f.run.running)
+        next.push({ command: "shipvo sim", why: "Start the simulator to try the app." });
+    if (f.storeStep)
+        next.push({ command: f.storeStep.state === "waiting" ? "shipvo store status" : `shipvo store status --mark ${f.storeStep.id}`, why: `Store step "${f.storeStep.title}" is ${f.storeStep.state === "todo" ? "next" : f.storeStep.state}.` });
+    return mk(code, summary, next, appId, pending, exit);
+}
 export async function status(argv, fetchFn = fetch) {
     const a = args(argv);
+    if (argv.includes("--json")) {
+        const { doc, exit } = await statusJson(a.app && a.app !== "true" ? a.app : undefined, fetchFn);
+        emit(doc);
+        return exit;
+    }
     const cfg = loadConfig();
     const appId = a.app && a.app !== "true" ? a.app : cfg.appId;
     const base = cfg.controlPlane.replace(/\/$/, "");
@@ -32,16 +187,15 @@ export async function status(argv, fetchFn = fetch) {
         console.error(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
         return 1;
     }
-    if (argv.includes("--json")) {
-        console.log(JSON.stringify(data));
-        return 0;
-    }
     const releases = data.releases ?? [];
     // An older control plane has no auto_halt field: say nothing rather than a wrong "off".
     if ("auto_halt" in data)
         console.log(describeAutoHalt(data.auto_halt));
+    const printBands = async () => { for (const l of describeBands(await fetchBands(base, appId, cfg.shellMajor, fetchFn)))
+        console.log(l); };
     if (!releases.length) {
         console.log(`No telemetry yet for "${appId}".`);
+        await printBands();
         return 0;
     }
     const h = data.halted;
@@ -50,5 +204,8 @@ export async function status(argv, fetchFn = fetch) {
         console.log(`Release ${h.release} is halted: ${h.failed} of ${h.reports} devices failed (limit ${pct}%). Publish a new release or run shipvo rollback to clear.`);
     }
     console.log(formatStatus(releases));
+    for (const l of describeTests(await fetchTestResults(base, appId, fetchFn)))
+        console.log(l);
+    await printBands();
     return 0;
 }

package/dist/store.d.ts

@@ -1,2 +1,38 @@
+import type { ScreenshotSetId } from "@shipvo/store";
 /** `shipvo store details --dry-run [--out dir]`: print the answers, write two files. Nothing is uploaded; no credentials are read. */
 export declare function store(argv: string[]): Promise<void>;
+/** Sets filled from app routes, with the one size we render each at and the pixel ratio. Feature graphic and icon are not app screens. */
+export declare const RENDER_SETS: {
+    set: ScreenshotSetId;
+    width: number;
+    height: number;
+    scale: number;
+}[];
+/** Renders one screen at a size and returns JPEG bytes. `route` is undefined for the start screen. */
+export type Renderer = (size: {
+    width: number;
+    height: number;
+    scale: number;
+}, route: string | undefined) => Promise<Uint8Array>;
+/** Fast mode: render each route at each set's size, write files, print the checker result per file. Returns the exit code. */
+export declare function renderScreenshots(routes: string[] | undefined, render: Renderer, outDir: string): Promise<number>;
+/** Add the group to a track's Google Groups through one Play edit, keeping groups already there. Returns the final list. */
+export declare function addTesterGroup(opts: {
+    pkg: string;
+    token: string;
+    group: string;
+    track?: string;
+    fetch?: typeof fetch;
+}): Promise<{
+    groups: string[];
+    added: boolean;
+}>;
+export declare function testersGuide(pkg: string, track?: string): {
+    package: string;
+    track: string;
+    group: string;
+    joinUrl: string;
+    optInUrl: string;
+    firstUploadByHand: string;
+    steps: string[];
+};