@shipvo/cli 0.1.5 → 0.1.6

package/dist/explore.js

@@ -1,28 +1,78 @@
 // `shipvo explore`: a deterministic walker over the simulator's accessibility tree. No LLM call.
 // The walker (`walk`) only needs a `Driver`, so tests run it against a fake app. `explore` wires it to the simulator.
 import { execSync, spawn } from "node:child_process";
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { createRequire } from "node:module";
 import { args as parse, loadConfig } from "./config.js";
 import { portFree, waitListening } from "./sim.js";
 import { ensurePlaywright } from "./ensure-playwright.js";
+import { writeIssues } from "./explore-issues.js";
+import { emit, envelope } from "./json-out.js";
+import { runFlows, renderFlows, parseFlowNames } from "./flows.js";
+/** Smallest tap target: 44 x 44 pt on iOS (Apple HIG), 48 x 48 dp on Android (Material and Android accessibility guide). */
+export const MIN_TARGET = { ios: 44, android: 48 };
 export const PARITY_LIMITS = [
     "The simulator runs the app's web build in headless Chromium. It is not a phone and not the native app.",
     "Camera, location, biometrics, payments and notifications are simulated. Native crashes and native-only bugs cannot show up here.",
-    "The walker only taps. It does not type, scroll or swipe, so content below the fold and rails are only seen if on screen.",
+    "The walker taps and types into text fields. It does not scroll or swipe, so content below the fold and rails are only seen if on screen.",
     "Layout, speed and memory are not measured.",
     "See docs/parity-results.md for what was measured against Android emulators and the iOS Simulator.",
 ];
 const ACTIONABLE = new Set(["button", "link", "tab", "checkbox", "switch", "radio", "menuitem"]);
+const FIELDS = new Set(["textbox", "searchbox"]);
+/** Labels that end a session or destroy data. The walker taps them last. `cancel` is here too; being last, it is still tapped, so a modal is not skipped. */
+const RISKY = /\b(log ?out|sign ?out|delete|remove|cancel|erase|deactivate|clear all|unsubscribe)\b/i;
+const NETWORK = /network request failed|network error|networkerror|failed to fetch|no internet|you(?:'| a)re offline|(?:can't|cannot|couldn't|unable to) connect|connection (?:failed|lost|error)|ERR_(?:INTERNET|CONNECTION|NAME_NOT)\w*/i;
+/** Only loading indicators count. Text such as a heading "Loading history" does not. */
+const loading = (tree) => /^\s*- (?:progressbar|spinner|activity ?indicator)\b/im.test(tree);
+/** Nothing drawn: no names and no text anywhere in the tree. */
+const blank = (tree) => !/"|: \S/.test(tree);
+/** Small seeded random numbers (mulberry32), so a seed repeats a run exactly. */
+function rng(seed) {
+    let a = seed >>> 0;
+    return () => { a = (a + 0x6d2b79f5) >>> 0; let t = a; t = Math.imul(t ^ (t >>> 15), t | 1); t ^= t + Math.imul(t ^ (t >>> 7), t | 61); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+function shuffle(xs, rand) {
+    const a = [...xs];
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+}
+/** A value for a field, from its label: one the field should accept, or one it should reject. */
+export function sampleValue(name, invalid) {
+    const n = name.toLowerCase();
+    const pick = (ok, bad) => (invalid ? bad : ok);
+    if (/e-?mail/.test(n))
+        return pick("ada@example.com", "not-an-email");
+    if (/pass/.test(n))
+        return pick("Correct-Horse-9", "1");
+    if (/phone|tel|mobile/.test(n))
+        return pick("+14155550123", "12");
+    if (/zip|postal|post code/.test(n))
+        return pick("94107", "00");
+    if (/url|website|link/.test(n))
+        return pick("https://example.com", "not a url");
+    if (/age|qty|quantity|number|amount|count|price|year/.test(n))
+        return pick("42", "abc");
+    if (/search|find|query/.test(n))
+        return pick("test", "");
+    if (/name/.test(n))
+        return pick("Ada Lovelace", "");
+    return pick("hello", "");
+}
 const unquote = (raw) => { const q = /^(\s*- )'(.*)'(:.*)?$/.exec(raw); return q ? q[1] + q[2].replace(/''/g, "'") + (q[3] ?? "") : raw; };
 /** Actionable elements in a tree, in order. `nth` counts earlier elements with the same role and name. Disabled ones are left out. */
-export function elements(tree) {
+export const elements = (tree) => parseEls(tree, ACTIONABLE);
+function parseEls(tree, roles) {
     const out = [];
     const seen = new Map();
     for (const raw of tree.split("\n")) {
         const l = unquote(raw);
         const m = /^\s*- ([\w-]+)(?: ("(?:[^"\\]|\\.)*"))?[^\n]*?\[ref=(\w+)\]/.exec(l);
-        if (!m || !ACTIONABLE.has(m[1]) || /\[disabled\]/.test(l))
+        if (!m || !roles.has(m[1]) || /\[disabled\]/.test(l))
             continue;
         let name = "";
         try {
@@ -38,6 +88,7 @@ export function elements(tree) {
     }
     return out;
 }
+export const fieldElements = (tree) => parseEls(tree, FIELDS);
 /** The tree without refs, to tell whether two screens are the same. */
 export const signature = (tree) => tree.replace(/\s*\[ref=\w+\]/g, "");
 const redScreen = (tree) => /Uncaught (\w*Error)|Unhandled Runtime Error|Application error|Something went wrong/i.exec(tree)?.[0];
@@ -45,112 +96,196 @@ const redScreen = (tree) => /Uncaught (\w*Error)|Unhandled Runtime Error|Applica
 const hasBack = (els) => els.some((e) => /^(back|go back|close)$/i.test(e.name));
 const label = (e) => `${e.role} "${e.name}"`;
 /** Steps in plain lines, for the report. */
-export const describeStep = (s) => s.action === "open" ? "open the app" : s.action === "open_url" ? `open_url ${s.url}` : s.action === "tap" ? `tap ${label(s)}${s.nth ? ` (number ${s.nth + 1} with that name)` : ""}` : "back";
+export const describeStep = (s) => s.action === "open" ? "open the app" : s.action === "open_url" ? `open_url ${s.url}` : s.action === "type" ? `type "${s.text}" into ${label(s)}${s.nth ? ` (number ${s.nth + 1} with that name)` : ""}${s.enter ? " and press Enter" : ""}` : s.action === "tap" ? `tap ${label(s)}${s.nth ? ` (number ${s.nth + 1} with that name)` : ""}` : "back";
+/**
+ * Walks the app. Each round it picks the screen to work on with an upper confidence bound: screens with nothing tried yet
+ * come first, then screens whose taps found new screens, with a bonus for rarely tried ones. On that screen it takes safe actions
+ * before risky ones (log out, delete, cancel, remove). Text fields get a valid value, then an invalid one.
+ */
 export async function walk(driver, o = {}) {
-    const maxDepth = o.maxDepth ?? 3, maxSteps = o.maxSteps ?? 100;
+    const skin = o.skin ?? "android", min = MIN_TARGET[skin];
+    const maxDepth = o.maxDepth ?? 3, maxSteps = o.maxSteps ?? 100, settleMs = o.settleMs ?? 400;
+    const rand = rng(o.seed ?? 1);
     const findings = [];
     const seenFinding = new Set();
-    const seenScreens = new Set();
-    let steps = 0;
+    const seen = new Set();
+    const nodes = new Map();
+    let steps = 0, cut = 0;
     let stopped = null;
-    let cut = 0;
     const add = (f) => { const k = `${f.kind}|${f.message}|${signature(f.screen)}`; if (!seenFinding.has(k)) {
         seenFinding.add(k);
         findings.push(f);
+        o.onEvent?.({ type: "finding", n: findings.length, finding: f });
     } };
     const need = (r, what) => { if (!r.ok || r.screen == null)
         throw new Error(`explore: ${what} failed: ${r.error ?? "no screen"}`); return r.screen; };
+    const find = (tree, s, roles = ACTIONABLE) => parseEls(tree, roles).find((e) => e.role === s.role && e.name === s.name && e.nth === s.nth);
     /** Put the phone back on the screen reached by `path`. Replays are not counted as steps. */
     async function replay(path) {
         let screen = "";
         for (const s of path) {
-            const r = s.action === "open" ? await driver.open() : s.action === "open_url" ? await driver.openUrl(s.url) : s.action === "back" ? await driver.back()
-                : await driver.tap(find(screen, s)?.ref ?? "missing");
+            let r;
+            if (s.action === "open")
+                r = await driver.open();
+            else if (s.action === "open_url")
+                r = await driver.openUrl(s.url);
+            else if (s.action === "back")
+                r = await driver.back();
+            else if (s.action === "type")
+                r = driver.type ? await driver.type(find(screen, s, FIELDS)?.ref ?? "missing", s.text, s.enter) : { ok: false, error: "this simulator cannot type" };
+            else
+                r = await driver.tap(find(screen, s)?.ref ?? "missing");
             screen = need(r, `replaying "${describeStep(s)}"`);
         }
         // Errors raised while replaying are drained here. On a later replay they would repeat an earlier finding.
         // The caller of the first replay of a start path keeps them.
         return { screen, errors: await driver.errors() };
     }
-    const find = (tree, s) => elements(tree).find((e) => e.role === s.role && e.name === s.name && e.nth === s.nth);
+    const addError = (e, screen, path) => add(NETWORK.test(e) ? { kind: "network_failed", message: `Network failed: ${e}`, screen, steps: path } : { kind: "error", message: `Uncaught error: ${e}`, screen, steps: path });
     async function checkErrors(screen, path) {
         for (const e of await driver.errors())
-            add({ kind: "error", message: `Uncaught error: ${e}`, screen, steps: path });
+            addError(e, screen, path);
         const red = redScreen(screen);
         if (red)
             add({ kind: "error", message: `Red screen: the screen shows "${red}"`, screen, steps: path });
+        const net = NETWORK.exec(screen)?.[0];
+        if (net)
+            add({ kind: "network_failed", message: `Network failed: the screen shows "${net}"`, screen, steps: path });
     }
-    async function visit(screen, path, depth) {
+    /** A screen seen for the first time: run the per-screen checks and list what can be done on it. */
+    async function register(screen, path, depth) {
         const sig = signature(screen);
-        if (seenScreens.has(sig))
+        if (seen.has(sig))
             return;
-        seenScreens.add(sig);
+        seen.add(sig);
         await checkErrors(screen, path);
         const els = elements(screen);
+        o.onEvent?.({ type: "screen", screens: seen.size, sig, controls: els.map((e) => ({ role: e.role, name: e.name })) });
         if (!els.length)
             add({ kind: "dead_end", message: "Dead end: the screen has no actionable element", screen, steps: path });
+        if (blank(screen))
+            add({ kind: "blank_screen", message: "Blank screen: nothing is drawn on it", screen, steps: path });
         for (const e of els)
             if (!e.name)
                 add({ kind: "unnamed", message: `Unnamed ${e.role}: it has no accessible name`, screen, steps: path });
-        let current = screen;
-        for (const e of els) {
-            if (!e.name || /^(back|go back)$/i.test(e.name))
-                continue;
-            if (steps >= maxSteps) {
-                stopped ??= `max-steps (${maxSteps}) reached`;
-                return;
+        for (const e of els)
+            if (e.name && e.nth === 1) {
+                const n = els.filter((x) => x.role === e.role && x.name === e.name).length;
+                add({ kind: "duplicate_name", message: `Duplicate name: ${n} ${e.role}s are named "${e.name}", so a screen reader cannot tell them apart`, screen, steps: path });
             }
-            const target = find(current, e);
-            if (!target) {
-                current = (await replay(path)).screen;
-                if (!find(current, e))
+        if (driver.sizes) {
+            // A simulator without the `sizes` action must not break the walk: skip the size check for this screen.
+            const sizes = await driver.sizes().catch(() => ({}));
+            for (const e of els) {
+                const z = sizes[e.ref];
+                if (!z || (z[0] >= min && z[1] >= min))
                     continue;
+                add({ kind: "small_target", message: `Small target: ${e.name ? label(e) : e.role}${e.nth ? ` (number ${e.nth + 1})` : ""} is ${z[0]} x ${z[1]}, under the ${min} x ${min} minimum for ${skin}`, screen, steps: path });
             }
-            const step = { action: "tap", role: e.role, name: e.name, nth: e.nth };
-            const here = [...path, step];
-            steps++;
-            const r = await driver.tap(find(current, e).ref);
-            if (r.delivery === "not_delivered")
-                add({ kind: "not_delivered", message: `Not delivered (${r.reason ?? "unknown reason"}): ${r.error ?? "the app did not receive the tap"}`, screen: current, steps: here });
-            else if (!r.ok)
-                add({ kind: "action_failed", message: `Action failed${r.code ? ` [${r.code}]` : ""}: ${r.error ?? "unknown"}`, screen: current, steps: here });
-            const after = r.screen ?? current;
-            await checkErrors(after, here);
-            const crashed = !r.ok || r.screen == null || !!redScreen(after);
-            const next = signature(after);
-            if (!crashed && next !== signature(current) && !seenScreens.has(next)) {
-                if (depth >= maxDepth) {
-                    cut++;
-                    seenScreens.add(next);
-                }
-                else {
-                    await visit(after, here, depth + 1);
-                    if (steps >= maxSteps && stopped)
-                        return;
-                }
+        }
+        if (driver.snapshot && loading(screen)) {
+            // Look again, twice. A screen that still shows a loading indicator after that is stuck.
+            let still = true;
+            for (let i = 0; i < 2 && still; i++) {
+                await new Promise((r) => setTimeout(r, settleMs));
+                const r = await driver.snapshot().catch(() => null);
+                still = !!r?.ok && r.screen != null && loading(r.screen);
             }
-            // Back to this screen: Back button first, a full replay if that does not land here.
-            if (next !== signature(current) || crashed) {
-                let b;
-                if (!crashed && hasBack(elements(after)))
-                    b = await driver.back();
-                current = b?.ok && b.screen != null && signature(b.screen) === sig ? b.screen : (await replay(path)).screen;
+            if (still)
+                add({ kind: "stuck_loading", message: "Stuck loading: the screen still shows a loading indicator after waiting", screen, steps: path });
+        }
+        const taps = shuffle(els.filter((e) => e.name && !/^(back|go back)$/i.test(e.name)), rand).map((el) => ({ kind: "tap", el, risky: RISKY.test(el.name), done: false }));
+        const fs = driver.type ? parseEls(screen, FIELDS) : [];
+        const typeActs = (invalid) => fs.map((el) => ({ kind: "type", el, text: sampleValue(el.name, invalid), enter: invalid, risky: false, done: false }));
+        nodes.set(sig, { sig, path, depth, acts: o.input === "bad" ? [...typeActs(true), ...taps] : [...typeActs(false), ...taps, ...typeActs(true)], n: 0, reward: 0 });
+    }
+    const todo = (n) => n.acts.filter((a) => !a.done);
+    /** Upper confidence bound over the screens that still have something to try. Untried screens first, risky-only screens last. */
+    function pick(here, total) {
+        const all = [...nodes.values()].filter((n) => todo(n).length);
+        const safe = all.filter((n) => todo(n).some((a) => !a.risky));
+        let best = null, bestScore = -Infinity;
+        for (const n of safe.length ? safe : all) {
+            const ucb = n.n === 0 ? 1e9 : n.reward / n.n + Math.sqrt((2 * Math.log(total + 1)) / n.n);
+            const score = ucb + (n.sig === here ? 0.01 : 0) + rand() * 1e-6;
+            if (score > bestScore) {
+                best = n;
+                bestScore = score;
             }
-            else
-                current = after;
         }
+        return best;
     }
-    const starts = [[{ action: "open" }], ...(o.routes ?? []).map((url) => [{ action: "open" }, { action: "open_url", url }])];
+    const starts = o.startPaths ?? [...(o.onlyRoutes ? [] : [[{ action: "open" }]]), ...(o.routes ?? []).map((url) => [{ action: "open" }, { action: "open_url", url }])];
     let error = null;
     try {
         for (const path of starts) {
-            if (stopped)
-                break;
             const { screen, errors } = await replay(path);
             // The first replay of a start path is the only time load-time errors are seen.
             for (const e of errors)
-                add({ kind: "error", message: `Uncaught error: ${e}`, screen, steps: path });
-            await visit(screen, path, 1);
+                addError(e, screen, path);
+            await register(screen, path, 1);
+        }
+        let screen = null;
+        let at = null;
+        for (;;) {
+            const node = pick(screen == null ? null : signature(screen), steps);
+            if (!node)
+                break;
+            if (o.shouldStop?.()) {
+                stopped = "stopped by you";
+                break;
+            }
+            if (steps >= maxSteps) {
+                stopped = `max-steps (${maxSteps}) reached`;
+                break;
+            }
+            // Get to the node's screen: the Back button when it is one step up, a full replay otherwise.
+            if (screen == null || signature(screen) !== node.sig) {
+                let landed = null;
+                if (at && screen != null && at.path.length === node.path.length + 1 && hasBack(elements(screen))) {
+                    const b = await driver.back();
+                    if (b.ok && b.screen != null && signature(b.screen) === node.sig)
+                        landed = b.screen;
+                }
+                screen = landed ?? (await replay(node.path)).screen;
+            }
+            const a = todo(node).find((x) => !x.risky) ?? todo(node)[0];
+            a.done = true;
+            const target = find(screen, a.el, a.kind === "type" ? FIELDS : ACTIONABLE);
+            if (!target) {
+                at = node;
+                continue;
+            }
+            const step = a.kind === "type" ? { action: "type", role: a.el.role, name: a.el.name, nth: a.el.nth, text: a.text, ...(a.enter ? { enter: true } : {}) } : { action: "tap", role: a.el.role, name: a.el.name, nth: a.el.nth };
+            const here = [...node.path, step];
+            steps++;
+            node.n++;
+            o.onEvent?.({ type: "step", n: steps, step, text: describeStep(step) });
+            const r = a.kind === "type" ? await driver.type(target.ref, a.text, a.enter) : await driver.tap(target.ref);
+            if (r.delivery === "not_delivered")
+                add({ kind: "not_delivered", message: `Not delivered (${r.reason ?? "unknown reason"}): ${r.error ?? "the app did not receive the tap"}`, screen, steps: here });
+            else if (!r.ok)
+                add({ kind: "action_failed", message: `Action failed${r.code ? ` [${r.code}]` : ""}: ${r.error ?? "unknown"}`, screen, steps: here });
+            const after = r.screen ?? screen;
+            await checkErrors(after, here);
+            const crashed = !r.ok || r.screen == null || !!redScreen(after);
+            const next = signature(after);
+            if (crashed) {
+                screen = null;
+                at = null;
+                continue;
+            }
+            if (next !== node.sig && !seen.has(next)) {
+                node.reward++;
+                if (node.depth >= maxDepth) {
+                    cut++;
+                    seen.add(next);
+                }
+                else
+                    await register(after, here, node.depth + 1);
+            }
+            screen = after;
+            at = nodes.get(next) ?? null;
         }
     }
     catch (e) {
@@ -159,7 +294,7 @@ export async function walk(driver, o = {}) {
     }
     if (!stopped && cut)
         stopped = `max-depth (${maxDepth}) reached: ${cut} screen${cut === 1 ? "" : "s"} were not walked`;
-    return { app: o.app ?? "", generatedAt: new Date().toISOString(), steps, screens: seenScreens.size, maxSteps, maxDepth, stoppedEarly: stopped, error, findings, parityLimits: PARITY_LIMITS };
+    return { app: o.app ?? "", generatedAt: new Date().toISOString(), steps, screens: seen.size, maxSteps, maxDepth, stoppedEarly: stopped, error, findings, parityLimits: PARITY_LIMITS };
 }
 export function renderMarkdown(r) {
     const L = [`# Explore report: ${r.app}`, "", "## Simulator limits", "", ...r.parityLimits.map((p) => `- ${p}`), "", "## Run", "",
@@ -174,7 +309,7 @@ export function renderMarkdown(r) {
     return L.join("\n");
 }
 /** Driver for a running simulator. */
-export function simDriver(base, app, session = `explore-${Date.now().toString(36)}`) {
+export function simDriver(base, app, session = `explore-${Date.now().toString(36)}`, platform) {
     const post = async (path, body) => {
         const r = await fetch(base.replace(/\/$/, "") + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(30000) });
         if (!r.ok)
@@ -183,15 +318,18 @@ export function simDriver(base, app, session = `explore-${Date.now().toString(36
     };
     const act = (body) => post("/act", { session, ...body });
     return {
-        open: () => post("/session", { session, app }),
+        open: () => post("/session", { session, app, ...(platform ? { device: { platform } } : {}) }),
         openUrl: (url) => act({ action: "open_url", url }),
         tap: (ref) => act({ action: "tap", ref }),
         back: () => act({ action: "back" }),
+        type: (ref, text, enter) => act({ action: "type", ref, text, ...(enter ? { enter: true } : {}) }),
+        snapshot: () => act({ action: "screen" }),
         errors: async () => (await act({ action: "errors" })).errors ?? [],
+        sizes: async () => (await act({ action: "sizes" })).sizes ?? {},
     };
 }
 /** Use the simulator at `--sim <url>`, or build the app and start one on `--port` (default 4546). `stop` kills the one we started. */
-export async function startSim(a, cfg) {
+export async function startSim(a, cfg, quiet = false) {
     let base = a.sim;
     let child;
     if (!base) {
@@ -200,9 +338,9 @@ export async function startSim(a, cfg) {
             throw new Error(`Port ${port} is in use. Stop the other simulator, pass --port <n>, or pass --sim <url> to use one that is running.`);
         if (a["skip-build"] !== "true" || !existsSync("sim-dist/index.html")) {
             console.error(`Building ${cfg.name} for the simulator…`);
-            execSync("PN_SIM=1 npx expo export --platform web --output-dir sim-dist --clear", { stdio: "inherit", env: { ...process.env, PN_SIM: "1" } });
+            execSync("npx expo export --platform web --output-dir sim-dist --clear", { stdio: quiet ? ["ignore", 2, 2] : "inherit", env: { ...process.env, PN_SIM: "1" } });
         }
-        ensurePlaywright({ cwd: process.cwd() });
+        ensurePlaywright({ cwd: process.cwd(), quiet });
         let server;
         try {
             server = createRequire(process.cwd() + "/package.json").resolve("@shipvo/sim/server.mjs");
@@ -219,27 +357,138 @@ export async function startSim(a, cfg) {
     }
     return { base, stop: () => { child?.kill(); } };
 }
-/** Returns the exit code. */
+/** Returns the exit code. With `--json`, stdout is one envelope and everything else goes to stderr. */
 export async function explore(argv) {
+    if (!argv.includes("--json"))
+        return exploreRun(argv, false);
+    try {
+        return await exploreRun(argv, true);
+    }
+    catch (e) {
+        emit(envelope("error", e instanceof Error ? e.message : String(e), { findings: [] }, [{ command: "shipvo doctor --json", why: "Check the setup." }], 2));
+        return 2;
+    }
+}
+/** The app's URL scheme: `expo.scheme` in app.json, else the scheme of a configured route such as "tide://cart". */
+export function appScheme(routes, dir = process.cwd()) {
+    try {
+        const j = JSON.parse(readFileSync(join(dir, "app.json"), "utf8"));
+        const sc = j.expo?.scheme ?? j.scheme;
+        const first = Array.isArray(sc) ? sc[0] : sc;
+        if (first)
+            return first;
+    }
+    catch { /* no app.json: try the configured routes */ }
+    return routes?.map((r) => /^([a-z][a-z0-9+.-]*):\/\//i.exec(r)?.[1]).find(Boolean);
+}
+/**
+ * Deep links to walk for `--changed-from <sha>`: the changed, routable screens (up to four), as `<scheme>://<screen>`.
+ * The walker opens them with the simulator's `open_url` action, which needs a URL the app's `onUrl` listener understands.
+ * If the diff cannot be read (for example a shallow checkout), or the app has no known scheme, say so and fall back to the full walk.
+ */
+export async function routesFromChange(sha, log = console.error, scheme) {
+    const { changedFiles, changedScreens } = await import("./ci-comment.js");
+    const { routableScreens } = await import("./ci-shots.js");
+    let files;
+    try {
+        files = changedFiles(sha);
+    }
+    catch (e) {
+        log(`could not read the diff: ${e instanceof Error ? e.message : e}. Walking the whole app.`);
+        return { onlyRoutes: false };
+    }
+    const screens = routableScreens(changedScreens(files));
+    if (!screens.length)
+        return { routes: [], onlyRoutes: true };
+    if (!scheme) {
+        log("could not find the app's URL scheme (expo.scheme in app.json), so changed screens cannot be opened. Walking the whole app.");
+        return { onlyRoutes: false };
+    }
+    return { routes: screens.map(([, r]) => `${scheme}://${r === "/" ? "" : r.slice(1)}`), onlyRoutes: true };
+}
+/** Exit code and `--json` code. A failed flow counts as a finding for `--fail-on-findings`; it has its own code when the walk found nothing. */
+export function outcome(report, flowsFailed, failOn) {
+    const code = report.error ? "walk_failed" : report.findings.length ? "findings" : flowsFailed ? "flows_failed" : "ok";
+    return { exit: report.error ? 1 : (report.findings.length || flowsFailed) && failOn ? 1 : 0, code };
+}
+async function exploreRun(argv, json) {
     const a = parse(argv);
     const cfg = loadConfig();
     const num = (k, d) => { if (a[k] === undefined)
         return d; const n = Number(a[k]); if (!Number.isInteger(n) || n < 1)
         throw new Error(`--${k} must be a whole number of 1 or more`); return n; };
     const maxDepth = num("max-depth", 3), maxSteps = num("max-steps", 100);
-    const sim = await startSim(a, cfg);
+    const sim = await startSim(a, cfg, json);
     const base = sim.base;
     try {
-        const report = await walk(simDriver(base, cfg.appId), { routes: cfg.routes, maxDepth, maxSteps, app: cfg.appId });
+        if (a.skin !== undefined && a.skin !== "ios" && a.skin !== "android")
+            throw new Error("--skin must be android or ios");
+        let routes = cfg.routes, onlyRoutes = false;
+        if (a["changed-from"] !== undefined) {
+            if (a["changed-from"] === "true")
+                throw new Error("--changed-from needs a commit sha");
+            // With --changed-from, the changed screens replace the configured routes. Only a failed diff falls back to them.
+            ({ routes = cfg.routes, onlyRoutes } = await routesFromChange(a["changed-from"], console.error, appScheme(cfg.routes)));
+        }
+        let seed;
+        if (a.seed !== undefined) {
+            seed = Number(a.seed);
+            if (!Number.isInteger(seed) || seed < 0)
+                throw new Error("--seed must be a whole number of 0 or more");
+        }
+        const flowNames = a.flows !== undefined ? parseFlowNames(a.flows) : undefined;
+        const report = await walk(simDriver(base, cfg.appId), { routes, onlyRoutes, maxDepth, maxSteps, seed, app: cfg.appId, skin: a.skin });
         const out = a.out ?? "explore-report";
-        writeFileSync(`${out}.md`, renderMarkdown(report));
+        const nothingChanged = onlyRoutes && !routes?.length;
+        if (nothingChanged)
+            console.error("No screens changed, nothing explored.");
+        writeFileSync(`${out}.md`, (nothingChanged ? "No screens changed, nothing explored.\n\n" : "") + renderMarkdown(report));
         writeFileSync(`${out}.json`, JSON.stringify(report, null, 2) + "\n");
-        console.log(`${report.findings.length ? `${report.findings.length} finding${report.findings.length === 1 ? "" : "s"}` : `No findings in ${report.steps} steps`}${report.stoppedEarly ? `. Stopped early: ${report.stoppedEarly}` : ""}. Wrote ${out}.md and ${out}.json`);
-        if (report.error) {
-            console.error(report.error);
-            return 1;
+        let flowsFailed = false;
+        let flowInfo = {};
+        let flowFiles = [];
+        if (flowNames) {
+            const fr = await runFlows(simDriver(base, cfg.appId), { flows: flowNames, app: cfg.appId });
+            writeFileSync(`${out}-flows.md`, renderFlows(fr));
+            writeFileSync(`${out}-flows.json`, JSON.stringify(fr, null, 2) + "\n");
+            flowsFailed = fr.flows.some((f) => f.status === "failed");
+            flowFiles = [`${out}-flows.md`, `${out}-flows.json`];
+            flowInfo = { flows: fr.flows.map((f) => ({ flow: f.flow, status: f.status, invalid_status: f.invalid.status, message: f.message })) };
+            const msg = `Flows: ${fr.flows.map((f) => `${f.flow} ${f.status}`).join(", ")}. Wrote ${out}-flows.md and ${out}-flows.json`;
+            if (json)
+                console.error(msg);
+            else
+                console.log(msg);
+        }
+        let issueInfo = {};
+        const line = `${report.findings.length ? `${report.findings.length} finding${report.findings.length === 1 ? "" : "s"}` : `No findings in ${report.steps} steps`}${report.stoppedEarly ? `. Stopped early: ${report.stoppedEarly}` : ""}. Wrote ${out}.md and ${out}.json`;
+        if (a["issues-dir"] !== undefined) {
+            if (a["issues-dir"] === "true")
+                throw new Error("--issues-dir needs a directory");
+            const { files, commands } = writeIssues(report.findings, a.skin ?? "android", a["issues-dir"]);
+            if (!json) {
+                if (!files.length)
+                    console.log("No findings, so no issue files written.");
+                else
+                    console.log(`Wrote ${files.length} issue file${files.length === 1 ? "" : "s"} to ${a["issues-dir"]}. To file them:\n${commands.join("\n")}`);
+            }
+            else
+                issueInfo = { issue_files: files, file_commands: commands };
         }
-        return report.findings.length && a["fail-on-findings"] === "true" ? 1 : 0;
+        const failOn = a["fail-on-findings"] === "true";
+        const { exit, code } = outcome(report, flowsFailed, failOn);
+        if (json) {
+            const data = { ...issueInfo, ...flowInfo, report_files: [`${out}.md`, `${out}.json`, ...flowFiles], steps: report.steps, screens: report.screens, stopped_early: report.stoppedEarly, error: report.error, findings: report.findings.map((f) => ({ kind: f.kind, message: f.message, steps: f.steps.map(describeStep) })) };
+            const next = report.error ? [{ command: "shipvo doctor --json", why: "Check the simulator setup." }]
+                : report.findings.length || flowsFailed ? [{ command: `open ${out}.md`, why: "Read the steps to reproduce each finding." }, { command: "shipvo explore --json", why: "Run again after fixing to confirm." }]
+                    : [{ command: "shipvo test --json", why: "Run your step files." }];
+            emit(envelope(code, report.error ?? line, data, next, exit));
+        }
+        else
+            console.log(line);
+        if (report.error && !json)
+            console.error(report.error);
+        return exit;
     }
     finally {
         sim.stop();

package/dist/flows.d.ts

@@ -0,0 +1,31 @@
+import { type Driver, type Step } from "./explore.js";
+export type FlowName = "signup" | "login" | "search" | "add_to_cart" | "checkout";
+export declare const FLOW_NAMES: FlowName[];
+export type FlowStatus = "passed" | "failed" | "not_found";
+export type FlowRun = {
+    status: FlowStatus | "not_run";
+    message: string;
+    step?: string;
+    steps: Step[];
+};
+export type FlowResult = {
+    flow: FlowName;
+    status: FlowStatus;
+    message: string;
+    step?: string;
+    steps: Step[];
+    invalid: FlowRun;
+};
+export type FlowReport = {
+    app: string;
+    generatedAt: string;
+    flows: FlowResult[];
+};
+/** Turn the `--flows` value into flow names. A bare flag (the arg parser gives "true") means all of them. */
+export declare function parseFlowNames(v: string): FlowName[];
+/** Run each flow with valid input, then once with invalid input. Each run starts on a fresh phone. */
+export declare function runFlows(d: Driver, o?: {
+    flows?: FlowName[];
+    app?: string;
+}): Promise<FlowReport>;
+export declare function renderFlows(r: FlowReport): string;