lynkeus 0.2.0

package/lib/cases/templates.js

@@ -0,0 +1,156 @@
+/**
+ * What `lynkeus case init` writes: one case to copy from, the reference of the
+ * format next to it, and a fixtures server with two empty fixtures, so a
+ * project starts from something that runs instead of from a blank folder.
+ */
+export const EXAMPLE_CASE = `---
+id: example
+title: "A user who was given points sees them on the first screen"
+description: >
+  What this proves and why it matters, in a sentence or two. A case reads top
+  to bottom: what has to exist, what the person does, what must be true after.
+---
+setup:
+  # Anything that is not an app step is a fixture: fixtures.mjs answers it.
+  - create_user: { as: u, name: "Ana" }
+
+steps:
+  - app.see: { text: "Hello" }
+  # \`user: u\` points at what \`create_user\` answered (cases.refs in lynkeus.config.json).
+  - give_points: { user: u, points: 25 }
+  - app.see: { text: "25 points", timeoutMs: 10000 }
+  - assert: { user: u, path: points, equals: 25 }
+
+expected: |
+  The points on screen and the points the backend holds are both 25.
+`;
+export const FORMAT = `# Cases
+
+A case is a markdown file: frontmatter that names it, then \`setup\`, \`steps\`
+and \`expected\`. \`lynkeus case run cases/example.md\` runs one; without files
+it runs every case in this folder. A step that fails stops the case, and the
+report carries the screen, the requests and the reason.
+
+## Steps that drive the app
+
+| Step | Value | |
+|---|---|---|
+| \`app.press\` | target, or \`{ target, within?, nth?, optional?, hold? }\` | Waits for the control to be there and enabled. \`optional\` presses only if it is on screen. |
+| \`app.type\` | \`{ text, target?, submit?, clear? }\` | \`target\` is tapped first; \`submit\` ends with the return key. |
+| \`app.swipe\` | \`{ direction, target?, distance? }\` or \`{ from, to }\` | |
+| \`app.wait\` | route, target, ms, \`{ target, scroll? }\` or \`{ request, status? }\` | \`scroll\` swipes until the target is in the window. A \`request\` is \`METHOD /path\`. |
+| \`app.see\` | target, or \`{ testId?, text?, route?, request?, event?, layer?, absent?, timeoutMs? }\` | An assertion on what the app shows or did. Everything named must hold. |
+| \`app.nav\` | route, or \`{ route, params }\` | A teleport, for getting to where the case starts. |
+| \`app.back\` | | |
+| \`app.requests\` | \`mark\` | From here on, \`request\` only counts what the app asks for. |
+| \`app.call\` | \`{ command, params?, expect?, as? }\` | A command the app registered with \`qa.register\`. |
+| \`app.run\` | \`{ flow, vars? }\` | A lynkeus flow, from the flows folder. |
+| \`app.events\` / \`app.event\` | \`clear\` / \`{ name, props?, absent? }\` | What the app told its analytics. |
+| \`app.<command>\` | its arguments by name | Any other lynkeus command: \`app.mock\`, \`app.network\`, \`app.appstate\`, \`app.deeplink\`… |
+
+A target is \`#testId\`, \`"text"\`, an index or \`x,y\`.
+
+A case that runs over several inputs declares \`matrix: { locale: [en, fr] }\`
+in its frontmatter and runs once per combination; \`{{matrix.locale}}\` is that
+run's value.
+
+One case runs on a host and on a device. What only one of them needs — closing a
+native screen the host never shows — is kept to it:
+
+\`\`\`yaml
+  - on: device        # or headless, ios, android
+    do:
+      - app.press: "364,84"
+\`\`\`
+
+## Steps that prepare and read the backend
+
+Any other step name is a **fixture**: lynkeus sends it to the command in
+\`cases.fixtures\` (lynkeus.config.json) as one JSON line and reads one back.
+
+\`\`\`
+→ {"command": "create_user", "params": {"name": "Ana"}, "env": {"NAME": "Ana"}}
+← {"ok": true, "user_id": "u_1", "name": "Ana"}
+\`\`\`
+
+\`as: u\` keeps the answer; \`{{u.user_id}}\` reads it later. \`assert\` calls
+the \`inspect\` fixture and checks one path of its answer with \`equals\`,
+\`includes\`, \`gte\`, \`lte\`, \`near\`, \`matches\`, \`present\` or \`absent\`.
+\`exec: { run: "…", as? }\` runs a shell command and keeps its JSON output.
+
+## Steps of your own
+
+\`cases.macros\` names a step and the steps it stands for. Inside,
+\`{{param.x}}\` is what the case passed, and a parameter that names an alias
+is that alias.
+
+\`\`\`json
+"macros": {
+  "app.login": [
+    { "app.call": { "command": "reset" } },
+    { "app.deeplink": "myapp://dev-login?user={{param.as.user_id}}" },
+    { "when": "wait", "do": { "app.wait": "{{param.wait}}" } }
+  ]
+}
+\`\`\`
+
+\`when\` runs a step only if the case passed that parameter (\`"when": "wait"\`)
+or passed that value (\`"when": "method=phone"\`); \`unless\` is the opposite.
+
+\`cases.interruptions\` names what the app may put in the way of any step — a
+lock screen, a consent sheet — and the steps that get past it:
+\`{ "see": "#unlock-keypad", "do": ["app.unlock"], "unless": "keypad" }\`. It
+runs before a press, a type, a swipe or a see finds it there; a step whose own
+words match \`unless\` is about it, and is left alone.
+
+Cases and fixtures often live in a repository of their own: \`LYNKEUS_CONFIG\`
+names a second configuration file, read over the app's, and the paths under
+its \`cases\` are relative to it.
+`;
+export const FIXTURES = `#!/usr/bin/env node
+// The fixtures of this project: how a case prepares the backend and reads it.
+// lynkeus starts this once per run and talks JSON lines to it: one line in per
+// step, one line out. Replace the bodies with calls to your backend — its
+// admin API, a script, a database seed.
+import readline from 'node:readline';
+
+const users = new Map();
+
+const fixtures = {
+  async create_user({ name = 'Test user' }) {
+    const user = { user_id: \`u_\${users.size + 1}\`, name, points: 0 };
+    users.set(user.user_id, user);
+    return user;
+  },
+  async give_points({ user_id, points }) {
+    const user = users.get(user_id);
+    if (!user) throw new Error(\`no user \${user_id}\`);
+    user.points += Number(points);
+    return { user_id, points: user.points };
+  },
+  // What \`assert\` reads.
+  async inspect({ user_id }) {
+    return users.get(user_id) ?? {};
+  },
+};
+
+for await (const line of readline.createInterface({ input: process.stdin })) {
+  if (!line.trim()) continue;
+  const { command, params } = JSON.parse(line);
+  try {
+    const fixture = fixtures[command];
+    if (!fixture) throw new Error(\`no fixture \${command}\`);
+    console.log(JSON.stringify({ ok: true, ...(await fixture(params ?? {})) }));
+  } catch (error) {
+    console.log(JSON.stringify({ ok: false, error: error.message }));
+  }
+}
+`;
+export const CONFIG = {
+    dir: 'cases',
+    flows: 'flows',
+    fixtures: { command: 'node cases/fixtures.mjs' },
+    inspect: 'inspect',
+    refs: { user: 'user_id' },
+    macros: {},
+};

package/lib/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { type Base } from './registry.js';
+export type Session = {
+    ctx: Base;
+    stop: () => Promise<void>;
+};

package/lib/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import readline from 'node:readline';
+import { AgentServer } from 'lynkeus-client';
+import { GLOBAL_FLAGS } from './args.js';
+import { caseCommands } from './commands/cases.js';
+import { driveCommands } from './commands/drive.js';
+import { headlessCommands } from './commands/headless.js';
+import { mapCommands } from './commands/map.js';
+import { osCommands } from './commands/os.js';
+import { runsCommands } from './commands/runs.js';
+import { graphFile, loadConfig, loadGraph, portFromEnv } from './config.js';
+import { HEADLESS_HOST, pickAgentDevice } from './device/devices.js';
+import { Device } from './device/driver.js';
+import { commands, find, helpFor, inSession, referenceMarkdown, register, resolve, usage } from './registry.js';
+import { execute } from './runtime.js';
+register([...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...caseCommands, ...headlessCommands]);
+/** The global flags, read leniently from the whole argv before any command parses its own. */
+const globals = (argv) => {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === '--')
+            break;
+        if (!t.startsWith('--'))
+            continue;
+        const name = t.slice(2).split('=')[0];
+        const spec = GLOBAL_FLAGS[name];
+        if (!spec)
+            continue;
+        if (spec.type === 'boolean')
+            out[name] = true;
+        else
+            out[name] = t.includes('=') ? t.slice(t.indexOf('=') + 1) : argv[i + 1];
+    }
+    return out;
+};
+const contextFor = (argv, attached = false) => {
+    const g = globals(argv);
+    const root = path.resolve(g.root ?? process.cwd());
+    const config = loadConfig(root);
+    const err = (line) => console.error(line);
+    let graph;
+    let device;
+    const connect = async () => {
+        const appId = g.app ?? process.env.LYNKEUS_APP_ID ?? config.app;
+        const started = performance.now();
+        const attachedIn = (d) => err(`attached in ${Math.round(performance.now() - started)}ms (${d.info.name})`);
+        const server = new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: portFromEnv(config) });
+        const picking = pickAgentDevice(g.device ?? process.env.LYNKEUS_DEVICE ?? config.device);
+        if (g.launch && appId) {
+            const d = new Device(await picking, { appId, server });
+            await d.launchApp(appId, { fresh: true });
+            attachedIn(d);
+            return d;
+        }
+        // Asking the OS which simulators are up takes longer than the app takes to dial in, so listen first.
+        picking.catch(() => undefined);
+        await server.listen();
+        const hello = await server
+            .waitForApp(Number(g['attach-timeout'] ?? process.env.LYNKEUS_ATTACH_TIMEOUT_MS ?? config.attachTimeout ?? 15000))
+            .catch(async (error) => {
+            await server.close();
+            await picking;
+            throw error;
+        });
+        const headless = hello.app?.runtime === 'headless';
+        const info = {
+            ...HEADLESS_HOST,
+            name: headless ? HEADLESS_HOST.name : String(hello.app?.name ?? hello.platform),
+            platform: hello.platform === 'android' ? 'android' : 'ios',
+        };
+        const d = new Device(info, { appId: appId ?? null, server, resolving: headless ? undefined : picking });
+        attachedIn(d);
+        return d;
+    };
+    const ctx = {
+        root,
+        config,
+        attached,
+        err,
+        graph: () => {
+            graph ??= loadGraph(root);
+            if (!graph)
+                throw new Error(`No graph at ${graphFile(root)}: run \`lynkeus map build\` in the app's folder first.`);
+            return graph;
+        },
+        device: () => {
+            device ??= connect();
+            return device;
+        },
+    };
+    return {
+        ctx,
+        stop: async () => {
+            await device?.then((d) => d.stop()).catch(() => undefined);
+        },
+    };
+};
+/** Each stdin line is a JSON array of arguments (`["press", "#x"]`); each answer is one JSON line. */
+const session = async (argv) => {
+    const { ctx, stop } = contextFor(argv, true);
+    const device = await ctx.device();
+    console.log(JSON.stringify({ ok: true, out: `attached (${device.info.name})` }));
+    for await (const line of readline.createInterface({ input: process.stdin })) {
+        if (!line.trim())
+            continue;
+        let av;
+        try {
+            av = JSON.parse(line);
+        }
+        catch {
+            console.log(JSON.stringify({ ok: false, error: 'each line must be a JSON array of arguments' }));
+            continue;
+        }
+        if (av[0] === 'exit')
+            break;
+        const found = resolve(av)?.command;
+        if (found && !inSession(found)) {
+            console.log(JSON.stringify({ ok: false, error: `${found.name} is not available in a session` }));
+            continue;
+        }
+        const r = await execute(av, ctx);
+        console.log(JSON.stringify(r.error
+            ? { ok: false, error: r.error, ...(r.why ? { why: r.why } : {}) }
+            : { ok: r.code === 0, out: r.text ?? '', ...(r.json !== undefined ? { json: r.json } : {}) }));
+    }
+    await stop();
+};
+const help = (argv) => {
+    if (argv.includes('--markdown'))
+        return referenceMarkdown();
+    const topic = argv
+        .slice(1)
+        .filter((a) => !a.startsWith('--'))
+        .join(' ');
+    if (!topic)
+        return usage();
+    const c = find(topic);
+    return c ? helpFor(c) : `no command "${topic}"\n\n${usage()}`;
+};
+const main = async () => {
+    const argv = process.argv.slice(2);
+    const [first] = argv;
+    if (!first || first === 'help' || first === '--help')
+        return console.log(help(argv));
+    if (first === 'commands')
+        return console.log(commands()
+            .map((c) => c.name)
+            .join('\n'));
+    if (first === 'mcp') {
+        const { serve } = await import('./mcp/server.js');
+        return serve(contextFor(argv, true), { full: argv.includes('--full') });
+    }
+    if (first === 'session') {
+        await session(argv);
+        return process.exit(0);
+    }
+    const { ctx, stop } = contextFor(argv);
+    const outcome = await execute(argv, ctx);
+    if (outcome.error) {
+        console.error(`✗ ${outcome.error}`);
+        if (outcome.why)
+            console.error(`why:\n${outcome.why}`);
+    }
+    else if (globals(argv).json && outcome.json !== undefined)
+        console.log(JSON.stringify(outcome.json, null, 2));
+    else if (outcome.text)
+        console.log(outcome.text);
+    await stop();
+    process.exit(outcome.code);
+};
+void main();

package/lib/commands/cases.d.ts

@@ -0,0 +1 @@
+export declare const caseCommands: import("../registry.js").Command[];

package/lib/commands/cases.js

@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Fixtures } from '../cases/fixtures.js';
+import { readCases } from '../cases/format.js';
+import { runCase } from '../cases/runner.js';
+import { CONFIG, EXAMPLE_CASE, FIXTURES, FORMAT } from '../cases/templates.js';
+import { configFile } from '../config.js';
+import { readJson, writeJson } from '../files.js';
+import { eventsFile } from '../knowledge/events.js';
+import { define } from '../registry.js';
+const startHost = async (root, err) => {
+    // Its own process group: the host starts a test runner of its own, and stopping one without the other leaves an app dialing in.
+    const host = spawn(process.execPath, [process.argv[1], 'headless', 'start'], {
+        cwd: root,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: true,
+    });
+    let output = '';
+    const tail = (n) => output.trim().split('\n').slice(-n).join(' · ');
+    await new Promise((resolve, reject) => {
+        const settle = (error) => {
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => settle(new Error(`the host did not come up within 180 s: ${tail(3)}`)), 180_000);
+        const read = (chunk) => {
+            output = (output + chunk.toString()).slice(-4000);
+            if (/waiting for a driver/.test(output))
+                settle();
+            else if (/Test suite failed/.test(output))
+                settle(new Error(`the host failed to start: ${tail(5)}`));
+        };
+        host.stdout?.on('data', read);
+        host.stderr?.on('data', read);
+        host.once('exit', (code) => settle(new Error(`the host exited (${code}): ${tail(3)}`)));
+    });
+    err('host: up');
+    return host;
+};
+const stopGroup = (pid) => {
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch { }
+};
+const describe = (report) => {
+    const counts = { passed: 0, failed: 0, skipped: 0 };
+    for (const s of report.steps)
+        counts[s.status] += 1;
+    const lines = [
+        `${report.result === 'passed' ? '✅ PASSED' : '❌ FAILED'}  ✅ ${counts.passed}${counts.failed ? `  ❌ ${counts.failed}` : ''}${counts.skipped ? `  ⏭️ ${counts.skipped}` : ''}  — ${(report.ms / 1000).toFixed(1)}s`,
+    ];
+    if (report.evidence?.screen)
+        lines.push('— screen at the failure:', ...report.evidence.screen.split('\n').map((l) => `    ${l}`));
+    if (report.evidence?.requests?.length)
+        lines.push('— requests:', ...report.evidence.requests.map((l) => `    ${l}`));
+    if (report.evidence?.why)
+        lines.push('— why:', ...report.evidence.why.split('\n').map((l) => `    ${l}`));
+    return lines.join('\n');
+};
+export const caseCommands = [
+    define({
+        name: 'case run',
+        group: 'runs',
+        summary: 'Run cases: setup through fixtures, steps against the app, the evidence when one fails',
+        details: 'A case is a markdown file with `setup`, `steps` and `expected` (`lynkeus case init` writes an example and the reference). Without files, every case in `cases.dir`. A failed case runs once more before it counts as failed, unless `--once`. `--host` hosts the app in Node for the run.',
+        positionals: [{ name: 'files', help: 'case files (default: every .md under cases.dir)', rest: true }],
+        flags: {
+            host: { type: 'boolean', help: 'start `headless start` for the run and stop it after' },
+            once: { type: 'boolean', help: 'no second chance for a case that fails' },
+            report: { type: 'string', help: 'append one JSON line per case', value: 'file' },
+            events: { type: 'string', help: 'keep what the app told its analytics, per case, as <dir>/<case id>/events.jsonl', value: 'dir' },
+            'dry-run': { type: 'boolean', help: 'parse and list the steps without running them' },
+        },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const config = ctx.config.cases ?? {};
+            const home = config.base ?? ctx.root;
+            const dir = path.resolve(home, config.dir ?? 'cases');
+            const files = ctx.args.length
+                ? ctx.args.map((f) => path.resolve(f))
+                : fs.existsSync(dir)
+                    ? fs
+                        .readdirSync(dir)
+                        .filter((f) => f.endsWith('.md') && !/^(README|FORMAT|CATALOG)\.md$/i.test(f) && !f.startsWith('.'))
+                        .sort()
+                        .map((f) => path.join(dir, f))
+                    : [];
+            if (files.length === 0)
+                return { text: `no cases under ${path.relative(ctx.root, dir) || '.'}; \`lynkeus case init\` writes one`, code: 1 };
+            const cases = files.flatMap(readCases);
+            const dry = !!ctx.flags['dry-run'];
+            const events = typeof ctx.flags.events === 'string';
+            const host = ctx.flags.host && !dry ? await startHost(ctx.root, ctx.err) : undefined;
+            const fixtures = config.fixtures && !dry ? new Fixtures(config.fixtures, home) : undefined;
+            const stop = () => {
+                fixtures?.close();
+                if (host?.pid)
+                    stopGroup(host.pid);
+            };
+            const interrupted = () => {
+                stop();
+                process.exit(130);
+            };
+            process.once('SIGINT', interrupted);
+            process.once('SIGTERM', interrupted);
+            const reports = [];
+            try {
+                for (const c of cases) {
+                    ctx.err(`▶ ${c.id}${c.title ? ` — ${c.title}` : ''}`);
+                    let report = await runCase(c, { base: ctx, config, fixtures, dry, events, log: ctx.err });
+                    ctx.err(describe(report));
+                    if (report.result === 'failed' && !ctx.flags.once && !dry) {
+                        ctx.err(`  retrying ${c.id} once`);
+                        report = { ...(await runCase(c, { base: ctx, config, fixtures, events, log: ctx.err })), retried: true };
+                        ctx.err(describe(report));
+                    }
+                    if (events && report.events) {
+                        const out = path.resolve(ctx.flags.events, c.id);
+                        fs.mkdirSync(out, { recursive: true });
+                        fs.writeFileSync(eventsFile(out), report.events.map((e) => `${JSON.stringify(e)}\n`).join(''));
+                    }
+                    reports.push(report);
+                    if (ctx.flags.report)
+                        fs.appendFileSync(path.resolve(ctx.flags.report), `${JSON.stringify(report)}\n`);
+                }
+            }
+            finally {
+                stop();
+            }
+            const passed = reports.filter((r) => r.result === 'passed').length;
+            const summary = [
+                ...reports.map((r) => `${r.result === 'passed' ? '✅' : '❌'} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}`),
+                `${passed}/${reports.length} passed`,
+            ].join('\n');
+            return { text: summary, json: reports, code: passed === reports.length ? 0 : 1 };
+        },
+    }),
+    define({
+        name: 'case init',
+        group: 'runs',
+        summary: 'Write an example case, the reference of the format and a fixtures server to start from',
+        flags: { force: { type: 'boolean', help: 'overwrite what is there' } },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const dir = path.resolve(ctx.root, ctx.config.cases?.dir ?? 'cases');
+            fs.mkdirSync(dir, { recursive: true });
+            const notes = [];
+            const write = (file, content) => {
+                if (fs.existsSync(file) && !ctx.flags.force)
+                    return notes.push(`kept ${path.relative(ctx.root, file)}`);
+                fs.writeFileSync(file, content);
+                notes.push(`wrote ${path.relative(ctx.root, file)}`);
+            };
+            write(path.join(dir, 'example.md'), EXAMPLE_CASE);
+            write(path.join(dir, 'README.md'), FORMAT);
+            write(path.join(dir, 'fixtures.mjs'), FIXTURES);
+            const file = configFile(ctx.root);
+            if (ctx.config.cases && !ctx.flags.force)
+                notes.push('kept cases in lynkeus.config.json');
+            else {
+                const current = fs.existsSync(file) ? readJson(file) : {};
+                writeJson(file, { ...current, cases: { ...CONFIG, dir: path.relative(ctx.root, dir) } });
+                notes.push('added cases to lynkeus.config.json');
+            }
+            notes.push('next: `lynkeus case run cases/example.md --dry-run`, then make fixtures.mjs talk to your backend');
+            return { text: notes.join('\n'), json: { dir } };
+        },
+    }),
+];

package/lib/commands/check.d.ts

@@ -0,0 +1,36 @@
+import type { Finding } from '../knowledge/lint.js';
+import type { ScreenGraph } from '../knowledge/types.js';
+export type GraphDiff = {
+    routesAdded: string[];
+    routesRemoved: string[];
+    edgesAdded: {
+        from: string;
+        to: string;
+    }[];
+    edgesRemoved: {
+        from: string;
+        to: string;
+    }[];
+    selectorsAdded: {
+        file: string;
+        id: string;
+    }[];
+    selectorsRemoved: {
+        file: string;
+        id: string;
+    }[];
+};
+export declare const diffGraphs: (base: ScreenGraph, head: ScreenGraph) => GraphDiff;
+/** Lint findings per route, as `lynkeus lint --save` writes them. */
+export type LintBaseline = Record<string, {
+    rule: string;
+    testId?: string;
+    message: string;
+}[]>;
+type LintedFinding = {
+    finding: Finding;
+    testId?: string;
+};
+export declare const newFindings: (baseline: LintBaseline, route: string, findings: LintedFinding[]) => LintedFinding[];
+export declare const describeGraphDiff: (d: GraphDiff) => string;
+export {};

package/lib/commands/check.js

@@ -0,0 +1,67 @@
+const edgesOf = (g) => {
+    const fileRoute = new Map();
+    for (const s of Object.values(g.screens))
+        if (s.file)
+            fileRoute.set(s.file, s.route);
+    const out = new Set();
+    for (const [file, facts] of Object.entries(g.files)) {
+        const from = fileRoute.get(file) ?? file;
+        for (const n of facts.navigates)
+            if (n.confidence === 'static')
+                out.add(`${from} ${n.to}`);
+    }
+    return out;
+};
+const selectorsOf = (g) => {
+    const out = new Set();
+    for (const [file, facts] of Object.entries(g.files))
+        for (const s of facts.selectors)
+            out.add(`${file} ${s.id}`);
+    return out;
+};
+const minus = (a, b) => [...a].filter((x) => !b.has(x)).sort();
+const pair = (s) => {
+    const [from, to] = s.split(' ');
+    return { from: from, to: to };
+};
+const selector = (s) => {
+    const { from, to } = pair(s);
+    return { file: from, id: to };
+};
+export const diffGraphs = (base, head) => {
+    const br = new Set(Object.keys(base.screens));
+    const hr = new Set(Object.keys(head.screens));
+    const be = edgesOf(base);
+    const he = edgesOf(head);
+    const bs = selectorsOf(base);
+    const hs = selectorsOf(head);
+    return {
+        routesAdded: minus(hr, br),
+        routesRemoved: minus(br, hr),
+        edgesAdded: minus(he, be).map(pair),
+        edgesRemoved: minus(be, he).map(pair),
+        selectorsAdded: minus(hs, bs).map(selector),
+        selectorsRemoved: minus(bs, hs).map(selector),
+    };
+};
+const key = (rule, testId, message) => `${rule}|${testId ?? ''}|${message}`;
+export const newFindings = (baseline, route, findings) => {
+    const seen = new Set((baseline[route] ?? []).map((b) => key(b.rule, b.testId, b.message)));
+    return findings.filter((f) => !seen.has(key(f.finding.rule, f.testId, f.finding.message)));
+};
+export const describeGraphDiff = (d) => {
+    const lines = [];
+    const list = (title, items) => {
+        if (items.length)
+            lines.push(`  ${title}`, ...items.map((i) => `    ${i}`));
+    };
+    list('routes added', d.routesAdded);
+    list('routes removed', d.routesRemoved);
+    const edge = (e) => `${e.from} → ${e.to}`;
+    const selector = (s) => `#${s.id}  (${s.file})`;
+    list('navigations added', d.edgesAdded.map(edge));
+    list('navigations removed', d.edgesRemoved.map(edge));
+    list('testIDs added', d.selectorsAdded.map(selector));
+    list('testIDs removed', d.selectorsRemoved.map(selector));
+    return lines.length ? lines.join('\n') : '  (the screen graph did not change)';
+};

package/lib/commands/crawl/return.d.ts

@@ -0,0 +1,20 @@
+import type { Screen } from 'lynkeus-protocol';
+import type { Device } from '../../device/driver.js';
+import type { CrawlOptions } from '../crawl.js';
+/** Fatal: exploring a logged-out app would record its intro screens as reachable from logged-in ones, and poison `plan`. */
+export declare class RecoveryError extends Error {
+}
+type Context = {
+    device: Device;
+    options: CrawlOptions;
+    goTo: (route: string | undefined) => Promise<void>;
+};
+/** How the crawl gets back to where it was standing, or back to life. */
+export declare const createReturns: ({ device, options, goTo }: Context) => {
+    dead: (s: Screen) => boolean;
+    recover: () => Promise<void>;
+    settle: () => Promise<Screen>;
+    revive: () => Promise<Screen>;
+    restore: (origin: Screen, layer?: string) => Promise<boolean>;
+};
+export {};