@shipvo/cli 0.1.3 → 0.1.5

package/dist/status.js

@@ -0,0 +1,147 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { routeStore } from "@shipvo/store";
+import { args, loadConfig } from "./config.js";
+import { detectProject } from "./agents.js";
+import { portFree } from "./sim.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) {
+    const names = [...new Set(releases.flatMap((r) => Object.keys(r.events ?? {})))].sort();
+    const rows = [["release", ...names, "apply ms", "cold start ms"],
+        ...releases.map((r) => [String(r.release), ...names.map((n) => String(r.events?.[n] ?? 0)), ms(r.apply_ms_median), ms(r.cold_start_ms_median)])];
+    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");
+}
+/** "auto-halt: off" or "auto-halt: on at 20% after 20 reports". */
+export function describeAutoHalt(c) {
+    if (!c || typeof c.threshold !== "number")
+        return "auto-halt: off";
+    const n = c.min_reports ?? 20;
+    return `auto-halt: on at ${Math.round(c.threshold * 1000) / 10}% after ${n} report${n === 1 ? "" : "s"}`;
+}
+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 };
+    const mk = (code, summary, next, appId, pending, exit) => ({
+        doc: { ok: exit === 0, code, summary, data: { project: { kind, app_id: appId }, ...shared, pending_release: pending }, 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 ?? [];
+    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);
+        console.log(JSON.stringify(doc));
+        return exit;
+    }
+    const cfg = loadConfig();
+    const appId = a.app && a.app !== "true" ? a.app : cfg.appId;
+    const base = cfg.controlPlane.replace(/\/$/, "");
+    const url = `${base}/t/${encodeURIComponent(appId)}/summary`;
+    let data;
+    try {
+        const r = await fetchFn(url);
+        if (!r.ok)
+            throw new Error(`HTTP ${r.status}`);
+        data = (await r.json());
+    }
+    catch (e) {
+        console.error(`Could not reach the control plane at ${base} (${e instanceof Error ? e.message : String(e)}).`);
+        return 1;
+    }
+    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));
+    if (!releases.length) {
+        console.log(`No telemetry yet for "${appId}".`);
+        return 0;
+    }
+    const h = data.halted;
+    if (h && typeof h === "object") {
+        const pct = Math.round(h.threshold * 1000) / 10;
+        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));
+    return 0;
+}

package/dist/store.d.ts

@@ -0,0 +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[];
+};

package/dist/store.js

@@ -0,0 +1,297 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { join } from "node:path";
+import { createSign } from "node:crypto";
+import { checkScreenshot, checkSet, SCREENSHOT_SETS, deriveStoreDetails, renderDataSafetyCsv, renderPrivacyPolicy, routeStore, SHIPVO_TESTERS_GROUP, SHIPVO_TESTERS_JOIN_URL } from "@shipvo/store";
+import { args, loadConfig } from "./config.js";
+import { startSim } from "./explore.js";
+/** `shipvo store details --dry-run [--out dir]`: print the answers, write two files. Nothing is uploaded; no credentials are read. */
+export async function store(argv) {
+    const [sub, ...rest] = argv;
+    if (sub === "setup")
+        return setup(rest);
+    if (sub === "status")
+        return status(rest);
+    if (sub === "testers")
+        return testers(rest);
+    if (sub === "screenshots")
+        return screenshots(rest);
+    if (sub !== "details") {
+        console.error("Usage: shipvo store details --dry-run [--out dir] | store setup | store status | store screenshots | store testers");
+        process.exit(2);
+    }
+    const a = args(rest);
+    if (a["dry-run"] === undefined || a["dry-run"] === "false") {
+        console.error("shipvo store details: upload is not available yet; use --dry-run");
+        process.exit(2);
+    }
+    const cfg = loadConfig();
+    const d = deriveStoreDetails(cfg);
+    const out = a.out && a.out !== "true" ? a.out : ".shipvo/store";
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, "data-safety.csv"), renderDataSafetyCsv(d));
+    writeFileSync(join(out, "privacy-policy.md"), renderPrivacyPolicy(d));
+    console.log(`Data safety answers for ${d.appName} (derived from shipvo.json):`);
+    if (d.rows.length === 0)
+        console.log("  No declared capability touches user data.");
+    for (const r of d.rows)
+        console.log(`  ${r.dataType}: collected ${r.collected}, shared ${r.shared}, purpose ${r.purpose}`);
+    if (d.fill.total > 0)
+        console.log(`Filled without you: ${d.fill.filled} of ${d.fill.total} fields.`);
+    console.log(`\nYou still need to answer (${d.unknown.length}):`);
+    for (const u of d.unknown)
+        console.log(`  - ${u.question}`);
+    console.log(`\nWrote ${join(out, "data-safety.csv")} and ${join(out, "privacy-policy.md")}. Nothing was uploaded.`);
+}
+const PLAN_FILE = "store-plan.json";
+function fail(msg) { console.error(msg); process.exit(2); }
+function yesNo(flag, v) {
+    if (v === undefined)
+        return undefined;
+    if (["yes", "true"].includes(v))
+        return true;
+    if (["no", "false"].includes(v))
+        return false;
+    return fail(`shipvo store setup: --${flag} must be yes or no, not "${v}".`);
+}
+async function ask(rl, q, def) {
+    const r = (await rl.question(`${q} [${def ? "Y/n" : "y/N"}] `)).trim().toLowerCase();
+    return r === "" ? def : r.startsWith("y");
+}
+function describe(title, r, marks, withStatus) {
+    console.log(`${title}: ${r.account} account. ${r.accountNote}`);
+    let next;
+    for (const s of r.steps) {
+        const m = marks[s.id] ?? "todo";
+        if (!next && m !== "done")
+            next = s;
+        console.log(`  ${withStatus ? `[${m}] ` : "- "}${s.id}: ${s.title}${s.wait ? ` (wait: ${s.wait})` : ""}`);
+    }
+    if (!withStatus)
+        return;
+    if (!next)
+        console.log("  Done: this store is live.");
+    else if ((marks[next.id] ?? "todo") === "waiting")
+        console.log(`  Next: wait. ${next.wait ?? next.title}. Then run \`shipvo store status --mark ${next.id}\`.`);
+    else
+        console.log(`  Next: ${next.action} Then run \`shipvo store status --mark ${next.id}\`.`);
+}
+function printPlan(plan, withStatus) {
+    const r = routeStore(plan.answers);
+    describe("Google Play", r.play, plan.marks, withStatus);
+    console.log("");
+    describe("App Store", r.apple, plan.marks, withStatus);
+    if (!withStatus)
+        for (const n of r.notes)
+            console.log(`\n${n}`);
+}
+/** `shipvo store setup [--company yes|no] [--android-now] [--play-account-before-2023-11-13]`: write store-plan.json. No store calls. */
+async function setup(argv) {
+    const a = args(argv);
+    let company = yesNo("company", a.company);
+    let androidNow = yesNo("android-now", a["android-now"]);
+    let before = yesNo("play-account-before-2023-11-13", a["play-account-before-2023-11-13"]);
+    if (company === undefined && process.stdin.isTTY) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        company = await ask(rl, "Do you have a registered company?", false);
+        if (!company) {
+            androidNow ??= await ask(rl, "Do you need Android live right now?", false);
+            before ??= await ask(rl, "Did you make a Google Play developer account before 13 Nov 2023?", false);
+        }
+        rl.close();
+    }
+    const answers = { company: company ?? false, androidNow: androidNow ?? false, playAccountBefore20231113: before ?? false };
+    const plan = { version: 1, answers, marks: {} };
+    writeFileSync(PLAN_FILE, JSON.stringify(plan, null, 2) + "\n");
+    console.log("Your store plan:\n");
+    printPlan(plan, false);
+    console.log(`\nWrote ${PLAN_FILE}. Run \`shipvo store status\` to see what to do next. Nothing was uploaded.`);
+}
+/** `shipvo store status [--mark <step> [--as waiting|done]]`: one timeline per store. */
+async function status(argv) {
+    if (!existsSync(PLAN_FILE))
+        fail(`No ${PLAN_FILE} here. Run \`shipvo store setup\` first.`);
+    const plan = JSON.parse(readFileSync(PLAN_FILE, "utf8"));
+    const a = args(argv);
+    if (a.mark !== undefined) {
+        const r = routeStore(plan.answers);
+        const ids = [...r.play.steps, ...r.apple.steps].map((s) => s.id);
+        if (!ids.includes(a.mark))
+            fail(`Unknown step "${a.mark}". Steps: ${ids.join(", ")}.`);
+        const as = a.as ?? "done";
+        if (as !== "waiting" && as !== "done")
+            fail(`--as must be waiting or done, not "${as}".`);
+        plan.marks[a.mark] = as;
+        writeFileSync(PLAN_FILE, JSON.stringify(plan, null, 2) + "\n");
+        console.log(`Marked ${a.mark} as ${as}.\n`);
+    }
+    printPlan(plan, true);
+}
+/** 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 const RENDER_SETS = [
+    { set: "iphone", width: 1290, height: 2796, scale: 3 },
+    { set: "ipad-13", width: 2064, height: 2752, scale: 2 },
+    { set: "play-phone", width: 1080, height: 1920, scale: 3 },
+    { set: "play-tablet-7", width: 1200, height: 1920, scale: 2 },
+    { set: "play-tablet-10", width: 1200, height: 1920, scale: 2 },
+];
+/** Fast mode: render each route at each set's size, write files, print the checker result per file. Returns the exit code. */
+export async function renderScreenshots(routes, render, outDir) {
+    console.log("fast mode: simulator render, not the native UI");
+    const screens = [undefined, ...(routes ?? [])];
+    let failed = 0;
+    for (const { set, width, height, scale } of RENDER_SETS) {
+        const spec = SCREENSHOT_SETS[set];
+        const dir = join(outDir, set);
+        mkdirSync(dir, { recursive: true });
+        const used = screens.slice(0, spec.max);
+        if (used.length < screens.length)
+            console.log(`${spec.label}: the store takes ${spec.max} at most; rendering the first ${spec.max} of ${screens.length} screens.`);
+        const files = [];
+        for (const [i, route] of used.entries()) {
+            const slug = route === undefined ? "start" : route.replace(/^[a-z][a-z0-9+.-]*:\/*/i, "").replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase() || "route";
+            const base = `${String(i + 1).padStart(2, "0")}-${slug}`;
+            const bytes = await render({ width, height, scale }, route);
+            const r = checkScreenshot({ name: base, bytes }, set);
+            const file = join(dir, `${base}.${r.format === "png" ? "png" : r.format === "jpeg" ? "jpg" : "bin"}`);
+            writeFileSync(file, bytes);
+            files.push({ name: file, bytes });
+            if (r.ok)
+                console.log(`${file}: ok`);
+            else {
+                failed++;
+                console.log(`${file}: FAILED`);
+                for (const p of r.problems)
+                    console.log(`  - ${p}`);
+            }
+        }
+        const c = checkSet(files, set);
+        for (const p of c.problems.filter((p) => /file\(s\)/.test(p))) {
+            failed++;
+            console.log(`${spec.label}: ${p}`);
+        }
+        for (const n of c.notes ?? [])
+            console.log(`${spec.label}: note: ${n}`);
+    }
+    console.log(`\nFiles are in ${outDir}. Check the sizes against the store pages before you submit.`);
+    return failed ? 1 : 0;
+}
+/** `shipvo store screenshots [--out dir] [--sim url] [--port n] [--skip-build]`: fast mode only. */
+async function screenshots(argv) {
+    const a = args(argv);
+    if (a.mode !== undefined && a.mode !== "fast")
+        fail(`shipvo store screenshots: only fast mode exists so far; --mode ${a.mode} is not available.`);
+    const cfg = loadConfig();
+    const out = a.out && a.out !== "true" ? a.out : "store-assets/raw";
+    const sim = await startSim(a, cfg);
+    let code = 1;
+    try {
+        const post = async (path, body) => {
+            const r = await fetch(sim.base.replace(/\/$/, "") + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(60000) });
+            if (!r.ok)
+                throw new Error(`simulator ${path} -> ${r.status}`);
+            return (await r.json());
+        };
+        const session = `shots-${Date.now().toString(36)}`;
+        code = await renderScreenshots(cfg.routes, async (size, route) => {
+            const open = await post("/session", { session, app: cfg.appId, ...size });
+            if (open.ok === false)
+                throw new Error(`could not open the app: ${open.error ?? "unknown error"}`);
+            if (route !== undefined) {
+                const r = await post("/act", { session, action: "open_url", url: route });
+                if (!r.ok)
+                    throw new Error(`could not open ${route}: ${r.error ?? "unknown error"}`);
+            }
+            const shot = await post("/act", { session, action: "screenshot", format: "jpeg", inline: true });
+            if (!shot.ok || !shot.data)
+                throw new Error(`screenshot failed: ${shot.error ?? "no data"}`);
+            return new Uint8Array(Buffer.from(shot.data, "base64"));
+        }, out);
+    }
+    finally {
+        sim.stop();
+    }
+    process.exitCode = code;
+}
+const PLAY_API = "https://androidpublisher.googleapis.com/androidpublisher/v3/applications";
+const b64u = (b) => Buffer.from(b).toString("base64url");
+/** Trade a Play service account key for an access token. The key stays in memory; it is never stored. */
+async function playToken(key, f) {
+    const now = Math.floor(Date.now() / 1000);
+    const head = `${b64u(JSON.stringify({ alg: "RS256", typ: "JWT" }))}.${b64u(JSON.stringify({ iss: key.client_email, scope: "https://www.googleapis.com/auth/androidpublisher", aud: "https://oauth2.googleapis.com/token", iat: now, exp: now + 3600 }))}`;
+    const sig = createSign("RSA-SHA256").update(head).sign(key.private_key).toString("base64url");
+    const r = await f("https://oauth2.googleapis.com/token", { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: `${head}.${sig}` }) });
+    const j = (await r.json().catch(() => ({})));
+    if (!r.ok || !j.access_token)
+        throw new Error(`Google sign-in with the service account key failed (${r.status})`);
+    return j.access_token;
+}
+/** Add the group to a track's Google Groups through one Play edit, keeping groups already there. Returns the final list. */
+export async function addTesterGroup(opts) {
+    const f = opts.fetch ?? fetch, track = opts.track ?? "alpha", base = `${PLAY_API}/${encodeURIComponent(opts.pkg)}/edits`;
+    const call = async (url, method, body) => {
+        const r = await f(url, { method, headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+        const j = (await r.json().catch(() => ({})));
+        if (!r.ok)
+            throw new Error(`Play API ${method} ${url.replace(PLAY_API, "")} -> ${r.status}${j.error?.message ? `: ${j.error.message}` : ""}`);
+        return j;
+    };
+    const edit = await call(base, "POST", {});
+    const cur = await call(`${base}/${edit.id}/testers/${track}`, "GET");
+    const groups = Array.isArray(cur.googleGroups) ? cur.googleGroups : [];
+    if (groups.includes(opts.group)) {
+        await call(`${base}/${edit.id}`, "DELETE").catch(() => { });
+        return { groups, added: false };
+    }
+    const next = [...groups, opts.group];
+    await call(`${base}/${edit.id}/testers/${track}`, "PUT", { googleGroups: next });
+    await call(`${base}/${edit.id}:commit`, "POST");
+    return { groups: next, added: true };
+}
+export function testersGuide(pkg, track = "alpha") {
+    return {
+        package: pkg, track,
+        group: SHIPVO_TESTERS_GROUP, joinUrl: SHIPVO_TESTERS_JOIN_URL,
+        optInUrl: `https://play.google.com/apps/testing/${pkg}`,
+        firstUploadByHand: "Play requires the first upload of a new app to be made by hand in Play Console. This command cannot do that.",
+        steps: [
+            "In Play Console, open Testing > Closed testing and create a track (or use the default one).",
+            "Upload your first build by hand. Play does not allow the API to do the first upload.",
+            `Add testers as Google Groups: ${SHIPVO_TESTERS_GROUP}, plus a group of your own people. Or run \`shipvo store testers --play-key <file>\` to add it through the API.`,
+            `Share your opt-in link: https://play.google.com/apps/testing/${pkg}`,
+            `Join Shipvo Testers yourself (${SHIPVO_TESTERS_JOIN_URL}) and test other founders' apps. The community works because everyone tests.`,
+            "Keep at least 12 testers opted in for 14 days in a row. The clock starts when 12 have opted in; if the count drops below 12 it resets.",
+        ],
+    };
+}
+/** `shipvo store testers [--package id] [--track alpha] [--play-key file] [--json]`: print the steps. Calls Play only with --play-key. */
+async function testers(argv) {
+    const a = args(argv);
+    const pkg = a.package && a.package !== "true" ? a.package : loadConfig().appId;
+    const track = a.track && a.track !== "true" ? a.track : "alpha";
+    const guide = testersGuide(pkg, track);
+    let api;
+    if (a["play-key"] !== undefined) {
+        if (a["play-key"] === "true")
+            fail("shipvo store testers: --play-key needs a file path.");
+        try {
+            const key = JSON.parse(readFileSync(a["play-key"], "utf8"));
+            api = await addTesterGroup({ pkg, track, group: SHIPVO_TESTERS_GROUP, token: await playToken(key, fetch) });
+        }
+        catch (e) {
+            api = { error: e.message };
+            process.exitCode = 1;
+        }
+    }
+    if (a.json !== undefined && a.json !== "false") {
+        console.log(JSON.stringify({ ...guide, ...(api ? { api } : {}) }, null, 2));
+        return;
+    }
+    console.log(`Get your 12 testers for ${pkg} (closed track "${track}"):\n`);
+    guide.steps.forEach((s, i) => console.log(`  ${i + 1}. ${s}`));
+    console.log(`\n${guide.firstUploadByHand}`);
+    if (api)
+        console.log("error" in api ? `\nCould not update the track: ${api.error}` : api.added ? `\nAdded ${SHIPVO_TESTERS_GROUP} to the "${track}" track. Groups now: ${api.groups.join(", ")}.` : `\n${SHIPVO_TESTERS_GROUP} was already on the "${track}" track. Nothing changed.`);
+    else
+        console.log("\nNo Play call was made. Pass --play-key <service-account.json> to add the group through the API; the key is read once and never stored.");
+}

package/dist/templates/capacitor/github-actions/build.yml

@@ -0,0 +1,122 @@
+# Shipvo build template for Capacitor apps. Written by `shipvo ci init --framework capacitor`.
+# Builds a signed Android bundle and a signed iOS app in your own GitHub Actions.
+# Add the secrets listed in docs/capacitor.md (Settings > Secrets and variables > Actions).
+name: Shipvo build
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+  push:
+    tags: ["v*"]
+
+jobs:
+  android:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+      - run: npm ci
+      - run: npm run build
+      - run: npx cap sync android
+      - name: Decode the upload keystore
+        env:
+          ANDROID_KEYSTORE_BASE64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
+        run: echo "$ANDROID_KEYSTORE_BASE64" | base64 --decode > "$RUNNER_TEMP/upload.keystore"
+      - name: Build the signed bundle
+        working-directory: android
+        env:
+          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        run: >
+          ./gradlew bundleRelease
+          -Pandroid.injected.signing.store.file="$RUNNER_TEMP/upload.keystore"
+          -Pandroid.injected.signing.store.password="$ANDROID_KEYSTORE_PASSWORD"
+          -Pandroid.injected.signing.key.alias="$ANDROID_KEY_ALIAS"
+          -Pandroid.injected.signing.key.password="$ANDROID_KEY_PASSWORD"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: android-release
+          path: android/app/build/outputs/bundle/release/*.aab
+          if-no-files-found: error
+
+  ios:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npx cap sync ios
+      - name: Install the signing certificate and profile
+        env:
+          IOS_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE_BASE64 }}
+          IOS_CERTIFICATE_PASSWORD: ${{ secrets.IOS_CERTIFICATE_PASSWORD }}
+          IOS_PROFILE_BASE64: ${{ secrets.IOS_PROFILE_BASE64 }}
+          KEYCHAIN_PASSWORD: ${{ secrets.IOS_KEYCHAIN_PASSWORD }}
+        run: |
+          KEYCHAIN="$RUNNER_TEMP/build.keychain-db"
+          echo "$IOS_CERTIFICATE_BASE64" | base64 --decode > "$RUNNER_TEMP/cert.p12"
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN"
+          security import "$RUNNER_TEMP/cert.p12" -P "$IOS_CERTIFICATE_PASSWORD" -A -t cert -f pkcs12 -k "$KEYCHAIN"
+          security set-key-partition-list -S apple-tool:,apple: -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN"
+          security list-keychain -d user -s "$KEYCHAIN" "$HOME/Library/Keychains/login.keychain-db"
+          mkdir -p "$HOME/Library/MobileDevice/Provisioning Profiles"
+          echo "$IOS_PROFILE_BASE64" | base64 --decode > "$HOME/Library/MobileDevice/Provisioning Profiles/build.mobileprovision"
+      - name: Archive
+        env:
+          IOS_SCHEME: ${{ vars.IOS_SCHEME || 'App' }}
+          IOS_TEAM_ID: ${{ secrets.IOS_TEAM_ID }}
+          IOS_PROFILE_NAME: ${{ secrets.IOS_PROFILE_NAME }}
+        run: >
+          xcodebuild archive
+          -workspace ios/App/App.xcworkspace
+          -scheme "$IOS_SCHEME"
+          -configuration Release
+          -archivePath "$RUNNER_TEMP/App.xcarchive"
+          DEVELOPMENT_TEAM="$IOS_TEAM_ID"
+          CODE_SIGN_STYLE=Manual
+          PROVISIONING_PROFILE_SPECIFIER="$IOS_PROFILE_NAME"
+          CODE_SIGN_IDENTITY="Apple Distribution"
+      - name: Export the .ipa
+        env:
+          IOS_TEAM_ID: ${{ secrets.IOS_TEAM_ID }}
+          IOS_PROFILE_NAME: ${{ secrets.IOS_PROFILE_NAME }}
+          IOS_BUNDLE_ID: ${{ secrets.IOS_BUNDLE_ID }}
+        run: |
+          cat > "$RUNNER_TEMP/ExportOptions.plist" <<PLIST
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0"><dict>
+            <key>method</key><string>app-store-connect</string>
+            <key>teamID</key><string>$IOS_TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>provisioningProfiles</key><dict><key>$IOS_BUNDLE_ID</key><string>$IOS_PROFILE_NAME</string></dict>
+          </dict></plist>
+          PLIST
+          xcodebuild -exportArchive -archivePath "$RUNNER_TEMP/App.xcarchive" -exportOptionsPlist "$RUNNER_TEMP/ExportOptions.plist" -exportPath "$RUNNER_TEMP/export"
+          mkdir -p dist-ios && cp "$RUNNER_TEMP"/export/*.ipa dist-ios/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ios-release
+          path: dist-ios/*.ipa
+          if-no-files-found: error
+      - name: Remove the keychain and certificate
+        if: always()
+        run: |
+          security delete-keychain "$RUNNER_TEMP/build.keychain-db" || true
+          rm -f "$RUNNER_TEMP/cert.p12"

package/dist/test.d.ts

@@ -0,0 +1,46 @@
+type Node = {
+    role: string;
+    name: string;
+    text: string;
+    ref: string;
+};
+type StepLike = {
+    kind: string;
+    target?: string;
+    text?: string;
+    enter?: boolean;
+    line: number;
+};
+type PhoneLike = {
+    screen: string;
+};
+export type TestKit = {
+    openApp(): Promise<PhoneLike>;
+    parseSteps(text: string): StepLike[];
+    runSteps(phone: PhoneLike, steps: StepLike[]): Promise<void>;
+    redact?(text: string): string;
+    proposeRepair(step: StepLike, tree: string): {
+        kind: "repaired";
+        step: StepLike;
+        reason: string;
+    } | {
+        kind: "unresolved";
+        candidates: Node[];
+    };
+};
+/** The same step as a plain-language line (only the target of a tap or type step is ever rewritten). */
+export declare function stepLine(s: StepLike): string;
+/** A unified diff that replaces single lines (line numbers are 1-based, old and new have the same count). Empty when nothing changes. */
+export declare function unifiedDiff(file: string, text: string, edits: Map<number, string>): string;
+/** Apply line edits, keeping indentation. Every other line, including comments and blank lines, is untouched. */
+export declare function applyEdits(text: string, edits: Map<number, string>): string;
+export type FlowReport = {
+    name: string;
+    status: "passed" | "failed";
+    steps: StepLike[];
+    failedStep: StepLike | null;
+    message: string | null;
+};
+/** Runs the suite. Returns the exit code: 0 when every step passed (or every failure was repaired and written), 1 otherwise. */
+export declare function testCmd(argv: string[], kit?: TestKit, rawLog?: (s: string) => void): Promise<number>;
+export {};