@shipvo/cli 0.1.4 → 0.1.5

package/dist/eas.js

@@ -0,0 +1,258 @@
+// `shipvo eas setup` and `shipvo eas build`: make a Capacitor repo ready for `eas build` and `eas submit`
+// with the customer's own Expo account. Shipvo writes files; it never holds Expo credentials.
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+export const ANDROID_IMAGE = "latest";
+export const IOS_IMAGE = "macos-tahoe-26.5-xcode-26.6";
+export const NODE_VERSION = "22";
+export const JDK_VERSION = "21";
+const SCHEME_PATH = "ios/App/App.xcodeproj/xcshareddata/xcschemes/App.xcscheme";
+const SHIM = "ios/App.xcodeproj";
+const SHIM_TARGET = "App/App.xcodeproj";
+/** Look for a Capacitor project at `root`. Returns undefined when it is not one. */
+export function detectCapacitor(root) {
+    const configFile = readdirSync(root).find((f) => /^capacitor\.config\.(ts|js|json|mjs|cjs)$/.test(f));
+    const android = existsSync(join(root, "android"));
+    const ios = existsSync(join(root, "ios/App/App.xcodeproj"));
+    if (!configFile || (!android && !ios))
+        return undefined;
+    return { configFile, android, ios };
+}
+const androidYaml = `# Written by \`shipvo eas setup\`. Safe to edit; setup will not overwrite this file.
+# Docs: https://docs.expo.dev/custom-builds/get-started/
+build:
+  name: Capacitor Android release
+  steps:
+    - eas/checkout
+    - eas/install_node_modules
+    - run:
+        name: Install JDK ${JDK_VERSION}
+        command: |
+          source "$HOME/.sdkman/bin/sdkman-init.sh"
+          sdk install java ${JDK_VERSION}-tem < /dev/null
+          set-env JAVA_HOME "$(sdk home java ${JDK_VERSION}-tem)"
+    - run:
+        name: Build the web app
+        command: npm run build
+    - run:
+        name: Sync Capacitor
+        command: npx cap sync android
+    - eas/inject_android_credentials
+    - eas/run_gradle:
+        inputs:
+          command: :app:bundleRelease
+    - eas/find_and_upload_build_artifacts
+`;
+const iosYaml = `# Written by \`shipvo eas setup\`. Safe to edit; setup will not overwrite this file.
+# Docs: https://docs.expo.dev/custom-builds/get-started/
+# Before the first build, run \`shipvo eas build\`: it creates the ios/App.xcodeproj link that the EAS CLI scheme check needs on your machine before upload.
+build:
+  name: Capacitor iOS release
+  steps:
+    - eas/checkout
+    - eas/install_node_modules
+    - run:
+        name: Build the web app
+        command: npm run build
+    - run:
+        name: Sync Capacitor
+        command: npx cap sync ios
+    - run:
+        name: Install CocoaPods dependencies
+        command: cd ios/App && pod install
+    - eas/resolve_apple_team_id_from_credentials:
+        id: resolve_apple_team_id
+    - eas/prebuild_credentials_ios:
+        inputs:
+          project_dir: ios
+    - eas/configure_ios_credentials
+    - run:
+        name: Write ExportOptions.plist
+        # Nothing else creates this file. The team id comes from the EAS credentials step above;
+        # the profile name is read from the Xcode project that eas/configure_ios_credentials updated.
+        command: |
+          BUNDLE_ID="$(xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release -showBuildSettings | awk -F' = ' '/ PRODUCT_BUNDLE_IDENTIFIER /{print $2; exit}')"
+          PROFILE="$(xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release -showBuildSettings | awk -F' = ' '/ PROVISIONING_PROFILE_SPECIFIER /{print $2; exit}')"
+          cat > ios/App/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</string>
+            <key>teamID</key><string>\${{ steps.resolve_apple_team_id.outputs.apple_team_id }}</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>provisioningProfiles</key>
+            <dict><key>$BUNDLE_ID</key><string>$PROFILE</string></dict>
+          </dict>
+          </plist>
+          PLIST
+    - run:
+        name: Archive with distribution signing
+        command: |
+          xcodebuild archive \\
+            -workspace ios/App/App.xcworkspace \\
+            -scheme App \\
+            -configuration Release \\
+            -archivePath build/App.xcarchive \\
+            DEVELOPMENT_TEAM="\${{ steps.resolve_apple_team_id.outputs.apple_team_id }}" \\
+            CODE_SIGN_STYLE=Manual
+          xcodebuild -exportArchive \\
+            -archivePath build/App.xcarchive \\
+            -exportPath build/export \\
+            -exportOptionsPlist ios/App/ExportOptions.plist
+    - eas/find_and_upload_build_artifacts
+`;
+const scheme = `<?xml version="1.0" encoding="UTF-8"?>
+<Scheme LastUpgradeVersion="1600" version="1.7">
+  <BuildAction parallelizeBuildables="YES" buildImplicitDependencies="YES">
+    <BuildActionEntries>
+      <BuildActionEntry buildForTesting="YES" buildForRunning="YES" buildForProfiling="YES" buildForArchiving="YES" buildForAnalyzing="YES">
+        <BuildableReference BuildableIdentifier="primary" BlueprintName="App" BuildableName="App.app" BlueprintIdentifier="504EC3011FED79650016851F" ReferencedContainer="container:App.xcodeproj"/>
+      </BuildActionEntry>
+    </BuildActionEntries>
+  </BuildAction>
+  <LaunchAction buildConfiguration="Debug" selectedDebuggerIdentifier="Xcode.DebuggerFoundation.Debugger.LLDB" selectedLauncherIdentifier="Xcode.DebuggerFoundation.Launcher.LLDB" launchStyle="0" useCustomWorkingDirectory="NO" ignoresPersistentStateOnLaunch="NO" debugDocumentVersioning="YES" debugServiceExtension="internal" allowLocationSimulation="YES"/>
+  <ArchiveAction buildConfiguration="Release" revealArchiveInOrganizer="YES"/>
+</Scheme>
+`;
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return {};
+        throw new Error(`${path} is not valid JSON. Fix it and run the command again.`);
+    }
+}
+/** Merge our profiles into an existing eas.json without touching the customer's own settings. */
+function easJson(root, p) {
+    const j = readJson(join(root, "eas.json"));
+    for (const k of ["cli", "build", "submit"]) {
+        if (j[k] !== undefined && (j[k] === null || typeof j[k] !== "object" || Array.isArray(j[k]))) {
+            throw new Error(`${join(root, "eas.json")} is not valid: "${k}" must be an object. Fix it and run the command again.`);
+        }
+    }
+    j.cli = { appVersionSource: "remote", ...(j.cli ?? {}) };
+    j.build ??= {};
+    if (p.android)
+        j.build["shipvo-android"] ??= { android: { image: ANDROID_IMAGE, buildType: "app-bundle", config: "android.yml" }, distribution: "store" };
+    if (p.ios)
+        j.build["shipvo-ios"] ??= { ios: { image: IOS_IMAGE, node: NODE_VERSION, config: "ios.yml" }, distribution: "store", autoIncrement: true };
+    j.submit ??= {};
+    if (p.android)
+        j.submit["shipvo-android"] ??= { android: {} };
+    if (p.ios)
+        j.submit["shipvo-ios"] ??= { ios: {} };
+    return JSON.stringify(j, null, 2) + "\n";
+}
+function gitignore(root) {
+    const path = join(root, ".gitignore");
+    const cur = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (cur.split(/\r?\n/).some((l) => l.trim() === SHIM))
+        return undefined;
+    const sep = cur === "" || cur.endsWith("\n") ? "" : "\n";
+    return `${cur}${sep}# Created by \`shipvo eas build\` for EAS; never commit\n${SHIM}\n`;
+}
+/** Work out which files need writing. Existing build YAMLs and schemes are never overwritten. */
+export function planEasSetup(root, p) {
+    const out = [];
+    const add = (path, content, overwrite) => {
+        const exists = existsSync(join(root, path));
+        if (exists && !overwrite)
+            return;
+        if (exists && readFileSync(join(root, path), "utf8") === content)
+            return;
+        out.push({ path, content, action: exists ? "update" : "create" });
+    };
+    add("eas.json", easJson(root, p), true);
+    if (p.android)
+        add(".eas/build/android.yml", androidYaml, false);
+    if (p.ios) {
+        add(".eas/build/ios.yml", iosYaml, false);
+        add(SCHEME_PATH, scheme, false);
+    }
+    const gi = p.ios ? gitignore(root) : undefined;
+    if (gi !== undefined)
+        out.push({ path: ".gitignore", content: gi, action: existsSync(join(root, ".gitignore")) ? "update" : "create" });
+    return out;
+}
+/** Create the `ios/App.xcodeproj -> App/App.xcodeproj` link the EAS CLI scheme check needs. Returns true if it made one. */
+export function ensureSchemeShim(root) {
+    const link = join(root, SHIM);
+    try {
+        lstatSync(link);
+        return false;
+    }
+    catch { /* missing: create it */ }
+    try {
+        symlinkSync(SHIM_TARGET, link, "dir");
+    }
+    catch (e) {
+        throw new Error(`Could not create the link ${SHIM} -> ${SHIM_TARGET} (${e.message}). Create it yourself (on Windows, run as administrator or turn on Developer Mode), then run the command again.`);
+    }
+    return true;
+}
+export const ONE_TIME_STEPS = [
+    ["eas-cli", "init"],
+    ["eas-cli", "build:version:set", "-p", "ios"],
+];
+export const IOS_UNPROVEN = "Note: the iOS signing steps in .eas/build/ios.yml are unproven. The step names were not checked against Expo's custom build functions (https://docs.expo.dev/custom-builds/schema/), so your first iOS build is the check.";
+const defaultRunner = (cmd, args, cwd) => spawnSync(cmd, args, { cwd, stdio: "inherit" }).status ?? 1;
+export async function easCmd(args, o = {}) {
+    const cwd = o.cwd ?? process.cwd();
+    const log = o.log ?? ((s) => console.log(s));
+    const runner = o.runner ?? defaultRunner;
+    const [sub, ...rest] = args;
+    if (sub !== "setup" && sub !== "build") {
+        throw new Error("Usage: shipvo eas setup [--dry-run] [--run] | shipvo eas build [eas build args]");
+    }
+    const project = detectCapacitor(cwd);
+    if (!project)
+        throw new Error("This is not a Capacitor project. Run this in a folder with capacitor.config.* and an android/ or ios/App/App.xcodeproj folder.");
+    if (sub === "build") {
+        if (project.ios && ensureSchemeShim(cwd))
+            log(`Linked ${SHIM} -> ${SHIM_TARGET} (git-ignored).`);
+        return runner("npx", ["eas-cli", "build", ...rest], cwd);
+    }
+    const known = ["--dry-run", "--run"];
+    const bad = rest.filter((a) => !known.includes(a));
+    if (bad.length)
+        throw new Error(`Unknown option for shipvo eas setup: ${bad.join(" ")}. Use --dry-run or --run.`);
+    const dry = rest.includes("--dry-run");
+    const runSteps = rest.includes("--run") && !dry;
+    const plan = planEasSetup(cwd, project);
+    for (const f of plan) {
+        log(`${dry ? "Would " + f.action : f.action === "create" ? "Created" : "Updated"} ${f.path}`);
+        if (dry)
+            log(f.content.replace(/^/gm, "  "));
+        else {
+            mkdirSync(dirname(join(cwd, f.path)), { recursive: true });
+            writeFileSync(join(cwd, f.path), f.content);
+        }
+    }
+    if (!plan.length)
+        log("Nothing to change: this repo is already set up for EAS.");
+    if (project.ios)
+        log(IOS_UNPROVEN);
+    if (dry)
+        return 0;
+    log("\nRemaining one-time steps:");
+    for (const s of ONE_TIME_STEPS)
+        log(`  npx ${s.join(" ")}`);
+    if (project.ios)
+        log("Before an iOS build, build with `shipvo eas build -p ios --profile shipvo-ios`: it creates the git-ignored ios/App.xcodeproj link first.");
+    if (runSteps) {
+        for (const s of ONE_TIME_STEPS) {
+            if (s[1] === "build:version:set" && !project.ios)
+                continue;
+            const code = runner("npx", [...s], cwd);
+            if (code !== 0) {
+                log(`\`npx ${s.join(" ")}\` failed (exit ${code}). Fix that and run it again.`);
+                return code;
+            }
+        }
+    }
+    return 0;
+}

package/dist/ensure-playwright.d.ts

@@ -0,0 +1,21 @@
+export type PackageManager = "pnpm" | "yarn" | "bun" | "npm";
+export interface EnsurePlaywrightDeps {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Does this path exist? Used to find the lockfile. */
+    exists: (path: string) => boolean;
+    /** Runs a command in `cwd`. Throws if it fails. */
+    run: (cmd: string, args: string[], cwd: string) => void;
+    log: (line: string) => void;
+    /** True when `playwright` resolves from the app. Defaults to the same lookup order as `doctor`. */
+    resolves?: (cwd: string) => boolean;
+}
+export declare function detectPackageManager(cwd: string, exists: (path: string) => boolean): PackageManager;
+export declare function installCommand(pm: PackageManager): {
+    cmd: string;
+    args: string[];
+};
+/** Installs `playwright` as a dev dependency with the app's package manager when it is missing. */
+export declare function ensurePlaywright(deps: Partial<EnsurePlaywrightDeps> & {
+    cwd: string;
+}): void;

package/dist/ensure-playwright.js

@@ -0,0 +1,64 @@
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+];
+export function detectPackageManager(cwd, exists) {
+    for (const [file, pm] of LOCKFILES)
+        if (exists(join(cwd, file)))
+            return pm;
+    return "npm";
+}
+export function installCommand(pm) {
+    switch (pm) {
+        case "pnpm": return { cmd: "pnpm", args: ["add", "-D", "playwright"] };
+        case "yarn": return { cmd: "yarn", args: ["add", "-D", "playwright"] };
+        case "bun": return { cmd: "bun", args: ["add", "-d", "playwright"] };
+        default: return { cmd: "npm", args: ["install", "--save-dev", "playwright"] };
+    }
+}
+/** Same lookup order as doctor's playwrightChromiumPath: the app, this package, @shipvo/sim, then the global npm root. */
+function playwrightResolves(cwd) {
+    const tries = [
+        () => createRequire(join(cwd, "package.json")).resolve("playwright"),
+        () => createRequire(import.meta.url).resolve("playwright"),
+        () => createRequire(createRequire(import.meta.url).resolve("@shipvo/sim/package.json")).resolve("playwright"),
+        () => createRequire(import.meta.url).resolve(join(execSync("npm root -g", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(), "playwright")),
+    ];
+    for (const t of tries) {
+        try {
+            t();
+            return true;
+        }
+        catch { }
+    }
+    return false;
+}
+/** Installs `playwright` as a dev dependency with the app's package manager when it is missing. */
+export function ensurePlaywright(deps) {
+    const { cwd } = deps;
+    const env = deps.env ?? process.env;
+    const exists = deps.exists ?? existsSync;
+    const run = deps.run ?? ((cmd, args, dir) => { execFileSync(cmd, args, { cwd: dir, stdio: "inherit" }); });
+    const log = deps.log ?? ((line) => console.log(line));
+    if ((deps.resolves ?? playwrightResolves)(cwd))
+        return;
+    const { cmd, args } = installCommand(detectPackageManager(cwd, exists));
+    const line = [cmd, ...args].join(" ");
+    if (env.SHIPVO_NO_AUTO_INSTALL === "1") {
+        throw new Error(`playwright is not installed and SHIPVO_NO_AUTO_INSTALL=1 is set. Run \`${line}\` in ${cwd}.`);
+    }
+    log(`playwright is not installed. Running: ${line}`);
+    try {
+        run(cmd, args, cwd);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`\`${line}\` failed: ${msg}`);
+    }
+}

package/dist/explore.d.ts

@@ -0,0 +1,84 @@
+export type Step = {
+    action: "open";
+} | {
+    action: "open_url";
+    url: string;
+} | {
+    action: "tap";
+    role: string;
+    name: string;
+    nth: number;
+} | {
+    action: "back";
+};
+export type Reply = {
+    ok: boolean;
+    screen?: string | null;
+    error?: string;
+    code?: string;
+    delivery?: string;
+    reason?: string;
+};
+/** What the walker needs from a simulator session. */
+export type Driver = {
+    /** Start a fresh phone on the app. */
+    open(): Promise<Reply>;
+    openUrl(url: string): Promise<Reply>;
+    tap(ref: string): Promise<Reply>;
+    back(): Promise<Reply>;
+    /** Uncaught page errors since the last call. */
+    errors(): Promise<string[]>;
+};
+export type Kind = "error" | "not_delivered" | "action_failed" | "dead_end" | "unnamed";
+export type Finding = {
+    kind: Kind;
+    message: string;
+    screen: string;
+    steps: Step[];
+};
+export type Report = {
+    app: string;
+    generatedAt: string;
+    steps: number;
+    screens: number;
+    maxSteps: number;
+    maxDepth: number;
+    stoppedEarly: string | null;
+    error: string | null;
+    findings: Finding[];
+    parityLimits: string[];
+};
+export declare const PARITY_LIMITS: string[];
+type El = {
+    role: string;
+    name: string;
+    ref: string;
+    nth: number;
+};
+/** Actionable elements in a tree, in order. `nth` counts earlier elements with the same role and name. Disabled ones are left out. */
+export declare function elements(tree: string): El[];
+/** The tree without refs, to tell whether two screens are the same. */
+export declare const signature: (tree: string) => string;
+/** Steps in plain lines, for the report. */
+export declare const describeStep: (s: Step) => string;
+export declare function walk(driver: Driver, o?: {
+    routes?: string[];
+    maxDepth?: number;
+    maxSteps?: number;
+    app?: string;
+}): Promise<Report>;
+export declare function renderMarkdown(r: Report): string;
+/** Driver for a running simulator. */
+export declare function simDriver(base: string, app: string, session?: string): Driver;
+/** Use the simulator at `--sim <url>`, or build the app and start one on `--port` (default 4546). `stop` kills the one we started. */
+export declare function startSim(a: Record<string, string | undefined>, cfg: {
+    name: string;
+    appId: string;
+    controlPlane: string;
+}): Promise<{
+    base: string;
+    stop: () => void;
+}>;
+/** Returns the exit code. */
+export declare function explore(argv: string[]): Promise<number>;
+export {};

package/dist/explore.js

@@ -0,0 +1,247 @@
+// `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 { createRequire } from "node:module";
+import { args as parse, loadConfig } from "./config.js";
+import { portFree, waitListening } from "./sim.js";
+import { ensurePlaywright } from "./ensure-playwright.js";
+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.",
+    "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 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) {
+    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))
+            continue;
+        let name = "";
+        try {
+            name = m[2] ? JSON.parse(m[2]).trim() : "";
+        }
+        catch {
+            name = m[2].slice(1, -1).trim();
+        }
+        const key = `${m[1]}|${name}`;
+        const nth = seen.get(key) ?? 0;
+        seen.set(key, nth + 1);
+        out.push({ role: m[1], name, ref: m[3], nth });
+    }
+    return out;
+}
+/** 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];
+// Accepts "close" too, but the sim `back` action only clicks a button named exactly "Back"; the replay fallback covers the rest.
+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 async function walk(driver, o = {}) {
+    const maxDepth = o.maxDepth ?? 3, maxSteps = o.maxSteps ?? 100;
+    const findings = [];
+    const seenFinding = new Set();
+    const seenScreens = new Set();
+    let steps = 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);
+    } };
+    const need = (r, what) => { if (!r.ok || r.screen == null)
+        throw new Error(`explore: ${what} failed: ${r.error ?? "no screen"}`); return r.screen; };
+    /** 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");
+            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);
+    async function checkErrors(screen, path) {
+        for (const e of await driver.errors())
+            add({ kind: "error", message: `Uncaught error: ${e}`, screen, steps: path });
+        const red = redScreen(screen);
+        if (red)
+            add({ kind: "error", message: `Red screen: the screen shows "${red}"`, screen, steps: path });
+    }
+    async function visit(screen, path, depth) {
+        const sig = signature(screen);
+        if (seenScreens.has(sig))
+            return;
+        seenScreens.add(sig);
+        await checkErrors(screen, path);
+        const els = elements(screen);
+        if (!els.length)
+            add({ kind: "dead_end", message: "Dead end: the screen has no actionable element", 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;
+            }
+            const target = find(current, e);
+            if (!target) {
+                current = (await replay(path)).screen;
+                if (!find(current, e))
+                    continue;
+            }
+            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;
+                }
+            }
+            // 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;
+            }
+            else
+                current = after;
+        }
+    }
+    const starts = [[{ 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);
+        }
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+        stopped = `the walk failed: ${error}`;
+    }
+    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 };
+}
+export function renderMarkdown(r) {
+    const L = [`# Explore report: ${r.app}`, "", "## Simulator limits", "", ...r.parityLimits.map((p) => `- ${p}`), "", "## Run", "",
+        `- Steps taken: ${r.steps} (limit ${r.maxSteps}). Screens seen: ${r.screens}. Depth limit: ${r.maxDepth}.`,
+        `- ${r.stoppedEarly ? `Stopped early: ${r.stoppedEarly}.` : "Stopped early: no. The walk ended because every reachable screen within the limits was visited."}`, ""];
+    L.push("## Findings", "");
+    if (!r.findings.length)
+        L.push(`No findings in ${r.steps} steps.`, "");
+    r.findings.forEach((f, i) => {
+        L.push(`### ${i + 1}. ${f.message}`, "", "Steps to reproduce:", "", ...f.steps.map((s, j) => `${j + 1}. ${describeStep(s)}`), "", "Typed steps:", "", "```json", JSON.stringify(f.steps), "```", "");
+    });
+    return L.join("\n");
+}
+/** Driver for a running simulator. */
+export function simDriver(base, app, session = `explore-${Date.now().toString(36)}`) {
+    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)
+            throw new Error(`simulator ${path} -> ${r.status}`);
+        return (await r.json());
+    };
+    const act = (body) => post("/act", { session, ...body });
+    return {
+        open: () => post("/session", { session, app }),
+        openUrl: (url) => act({ action: "open_url", url }),
+        tap: (ref) => act({ action: "tap", ref }),
+        back: () => act({ action: "back" }),
+        errors: async () => (await act({ action: "errors" })).errors ?? [],
+    };
+}
+/** 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) {
+    let base = a.sim;
+    let child;
+    if (!base) {
+        const port = a.port || "4546";
+        if (!(await portFree(Number(port))))
+            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" } });
+        }
+        ensurePlaywright({ cwd: process.cwd() });
+        let server;
+        try {
+            server = createRequire(process.cwd() + "/package.json").resolve("@shipvo/sim/server.mjs");
+        }
+        catch {
+            throw new Error("@shipvo/sim is not installed in this app. Run `npm i -D @shipvo/sim` (or use your package manager).");
+        }
+        let exited = false;
+        child = spawn(process.execPath, [server, "--port", port, "--app", cfg.appId], { stdio: ["ignore", "ignore", "inherit"], env: { ...process.env, PN_CONTROL: cfg.controlPlane } });
+        child.on("exit", () => { exited = true; });
+        if (!(await waitListening(Number(port), () => exited)))
+            throw new Error("the simulator exited before it was ready");
+        base = `http://localhost:${port}`;
+    }
+    return { base, stop: () => { child?.kill(); } };
+}
+/** Returns the exit code. */
+export async function explore(argv) {
+    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 base = sim.base;
+    try {
+        const report = await walk(simDriver(base, cfg.appId), { routes: cfg.routes, maxDepth, maxSteps, app: cfg.appId });
+        const out = a.out ?? "explore-report";
+        writeFileSync(`${out}.md`, 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;
+        }
+        return report.findings.length && a["fail-on-findings"] === "true" ? 1 : 0;
+    }
+    finally {
+        sim.stop();
+    }
+}