lynkeus 0.2.0

package/lib/registry.js

@@ -0,0 +1,113 @@
+import { GLOBAL_FLAGS, parseArgs } from './args.js';
+const GROUPS = {
+    drive: { title: 'Drive', blurb: 'the app that is running, through the agent inside it' },
+    os: { title: 'os', blurb: 'what the outside world hands the app: links, clock, sensors, the network, the simulator' },
+    map: { title: 'map', blurb: "what lynkeus knows before touching anything, from the app's source and from walks" },
+    runs: { title: 'Runs', blurb: 'flows, smokes, crawls and recordings' },
+    headless: { title: 'headless', blurb: 'the app hosted in Node under jest, no simulator' },
+};
+export const define = (c) => c;
+const byName = new Map();
+const all = [];
+export const register = (commands) => {
+    for (const c of commands) {
+        for (const name of [c.name, ...(c.aliases ?? [])]) {
+            if (byName.has(name))
+                throw new Error(`${name} is defined twice`);
+            byName.set(name, c);
+        }
+        all.push(c);
+    }
+};
+export const commands = () => all;
+export const find = (name) => byName.get(name);
+/** The command an argv names, and the rest of the argv. */
+export const resolve = (argv) => {
+    const two = argv.length >= 2 ? byName.get(argv.slice(0, 2).join(' ')) : undefined;
+    if (two)
+        return { command: two, rest: argv.slice(2) };
+    const one = argv[0] ? byName.get(argv[0]) : undefined;
+    return one ? { command: one, rest: argv.slice(1) } : undefined;
+};
+export const parseFor = (command, rest) => parseArgs(rest, command.positionals, command.flags);
+export const inSession = (c) => c.session ?? c.needs !== 'nothing';
+export const overMcp = (c, full) => {
+    if (c.mcp === false || (c.needs === 'nothing' && c.mcp === undefined))
+        return false;
+    return c.mcp === 'core' || full;
+};
+const flagSignature = (name, f) => `--${name}${f.type === 'boolean' ? '' : ` <${f.value ?? f.type}>`}`;
+const signature = (c) => {
+    const pos = (c.positionals ?? []).map((p) => (p.required ? `<${p.name}>` : `[${p.name}]`) + (p.rest ? '…' : '')).join(' ');
+    const fl = Object.entries(c.flags ?? {})
+        .map(([n, f]) => `[${flagSignature(n, f)}]`)
+        .join(' ');
+    return [c.name, pos, fl].filter(Boolean).join(' ');
+};
+const inGroups = () => Object.keys(GROUPS).map((g) => ({ ...GROUPS[g], list: all.filter((c) => c.group === g) })).filter((g) => g.list.length);
+export const usage = () => {
+    const lines = ['lynkeus — drive a React Native app from the outside, through the agent inside it', ''];
+    for (const g of inGroups()) {
+        lines.push(`${g.title} — ${g.blurb}`);
+        for (const c of g.list) {
+            const sig = c.example ?? signature(c);
+            lines.push(sig.length > 44 ? `  ${sig}\n${' '.repeat(47)}${c.summary}` : `  ${sig.padEnd(45)}${c.summary}`);
+        }
+        lines.push('');
+    }
+    lines.push(`Global: ${Object.entries(GLOBAL_FLAGS)
+        .map(([n, f]) => flagSignature(n, f))
+        .join('  ')}`, '`lynkeus help <command>` for details; `lynkeus session` runs many commands on one connection; `lynkeus mcp` serves the core of them to an AI harness (`--full`: all).');
+    return lines.join('\n');
+};
+export const helpFor = (c) => {
+    const lines = [`lynkeus ${signature(c)}`, '', c.summary];
+    if (c.details)
+        lines.push('', c.details);
+    if (c.positionals?.length) {
+        lines.push('', 'Arguments');
+        for (const p of c.positionals)
+            lines.push(`  ${p.name.padEnd(14)} ${p.help}${p.required ? '' : ' (optional)'}`);
+    }
+    const flags = Object.entries(c.flags ?? {});
+    if (flags.length) {
+        lines.push('', 'Flags');
+        for (const [n, f] of flags)
+            lines.push(`  ${flagSignature(n, f).padEnd(24)} ${f.help}${f.default !== undefined ? ` (default ${f.default})` : ''}`);
+    }
+    if (c.aliases?.length)
+        lines.push('', `Also: ${c.aliases.join(', ')}`);
+    const needs = c.needs === 'app' ? 'the app running with the agent' : c.needs === 'graph' ? 'a graph (lynkeus map build)' : 'nothing';
+    const mcp = c.mcp === 'core' ? '; served over MCP' : overMcp(c, true) ? '; served over MCP with --full' : '';
+    lines.push('', `Needs: ${needs}${inSession(c) ? '; available in a session' : ''}${mcp}`);
+    return lines.join('\n');
+};
+const flagRow = (n, f) => `| \`${flagSignature(n, f)}\` | ${f.help}${f.default !== undefined ? ` (default \`${f.default}\`)` : ''} |`;
+/** The reference document, generated so it cannot drift from the commands. */
+export const referenceMarkdown = () => {
+    const lines = [
+        '# lynkeus command reference',
+        '',
+        'Generated from the command registry (`lynkeus help --markdown`). Every command accepts the global flags at the end.',
+        '',
+    ];
+    for (const g of inGroups()) {
+        lines.push(`## ${g.title}`, '', `${g.blurb}.`, '');
+        for (const c of g.list) {
+            lines.push(`### \`lynkeus ${signature(c)}\``, '', c.summary + (c.details ? `\n\n${c.details}` : ''), '');
+            if (c.positionals?.length) {
+                lines.push('| Argument | |', '|---|---|');
+                for (const p of c.positionals)
+                    lines.push(`| \`${p.name}\` | ${p.help}${p.required ? '' : ' (optional)'} |`);
+                lines.push('');
+            }
+            const flags = Object.entries(c.flags ?? {});
+            if (flags.length)
+                lines.push('| Flag | |', '|---|---|', ...flags.map(([n, f]) => flagRow(n, f)), '');
+            if (c.aliases?.length)
+                lines.push(`Also accepted: ${c.aliases.map((a) => `\`${a}\``).join(', ')}.`, '');
+        }
+    }
+    lines.push('## Modes', '', '`lynkeus session` keeps one connection and reads JSON arrays of arguments on stdin, one command per line, answering one JSON object per line (`{ok, out, json?}` or `{ok:false, error, why?}`); `exit` ends it. `lynkeus mcp` serves the core commands as MCP tools over stdio; `lynkeus mcp --full` serves all of them. `lynkeus help <command>` prints one command; `lynkeus help --markdown` prints this document.', '', '## Global flags', '', '| Flag | |', '|---|---|', ...Object.entries(GLOBAL_FLAGS).map(([n, f]) => flagRow(n, f)), '');
+    return lines.join('\n');
+};

package/lib/runtime.d.ts

@@ -0,0 +1,12 @@
+import { type Base } from './registry.js';
+import { type Expected } from './targets.js';
+export type Outcome = {
+    text?: string;
+    json?: unknown;
+    code: number;
+    error?: string;
+    why?: string;
+};
+/** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
+export declare const whyFor: (base: Base, expected?: Expected) => Promise<string>;
+export declare const execute: (argv: string[], base: Base) => Promise<Outcome>;

package/lib/runtime.js

@@ -0,0 +1,56 @@
+/**
+ * Runs one command from an argv: resolve, parse, run, and on failure read the
+ * evidence. The terminal, session lines, a recording's stdin, cases and the
+ * MCP server all come through here.
+ */
+import { UsageError } from './args.js';
+import { describeWhy, explain } from './knowledge/why.js';
+import { helpFor, parseFor, resolve } from './registry.js';
+import { expectedOf } from './targets.js';
+/** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
+export const whyFor = async (base, expected) => {
+    try {
+        const device = await base.device();
+        const [screen, requests, trace] = await Promise.all([device.screen(), device.requests(), device.trace()]);
+        return describeWhy(explain({ screen, requests: requests.requests.slice(-40), inFlight: requests.inFlight, trace: trace.events.slice(-40), target: expected }));
+    }
+    catch {
+        return '';
+    }
+};
+const TARGET_ARG = { press: 0, see: 0, wait: 0, swipe: 1, nav: 0, type: 1 };
+export const execute = async (argv, base) => {
+    const found = resolve(argv);
+    if (!found)
+        return { code: 2, error: `unknown command "${argv.slice(0, 2).join(' ')}"; \`lynkeus help\` lists them` };
+    const { command, rest } = found;
+    let parsed;
+    try {
+        parsed = parseFor(command, rest);
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            return { code: 2, error: `${error.message}\n\n${helpFor(command)}` };
+        throw error;
+    }
+    if (parsed.flags.help)
+        return { code: 0, text: helpFor(command) };
+    try {
+        const result = await command.run({ ...base, ...parsed });
+        if (result === undefined)
+            return { code: 0 };
+        if (typeof result === 'string')
+            return { code: 0, text: result };
+        return { code: result.code ?? 0, text: result.text ?? (result.json === undefined ? undefined : JSON.stringify(result.json)), json: result.json };
+    }
+    catch (error) {
+        const out = { code: 1, error: error instanceof Error ? error.message : String(error) };
+        const at = TARGET_ARG[command.name];
+        if (at !== undefined) {
+            const why = await whyFor(base, expectedOf(parsed.args[at]));
+            if (why)
+                out.why = why;
+        }
+        return out;
+    }
+};

package/lib/targets.d.ts

@@ -0,0 +1,17 @@
+import type { Target } from 'lynkeus-protocol';
+export declare const TARGET_HELP = "#testId | \"text\" | 12 (index) | 100,200";
+/** `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match. */
+export declare const parseTarget: (raw: string) => Target;
+/** A target narrowed to the match nearest another (`--in`) and to a position among the matches (`--nth`). */
+export declare const scopedTarget: (raw: string, flags: {
+    in?: unknown;
+    nth?: unknown;
+}) => Target;
+export declare const isRoute: (raw: string) => boolean;
+export type Expected = {
+    testId?: string;
+    text?: string;
+    route?: string;
+};
+/** What a command was looking for, as `why` reads it. */
+export declare const expectedOf: (raw: string | undefined) => Expected | undefined;

package/lib/targets.js

@@ -0,0 +1,43 @@
+export const TARGET_HELP = '#testId | "text" | 12 (index) | 100,200';
+/** `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match. */
+export const parseTarget = (raw) => {
+    const nth = /^(.+)\[(\d+)\]$/.exec(raw);
+    if (nth && !/^\d+$/.test(nth[1])) {
+        const base = parseTarget(nth[1]);
+        if ('testId' in base || 'text' in base)
+            return { ...base, nth: Number(nth[2]) };
+    }
+    if (raw.startsWith('#'))
+        return { testId: raw.slice(1) };
+    if (/^\d+,\d+$/.test(raw)) {
+        const [x, y] = raw.split(',').map(Number);
+        return { x: x, y: y };
+    }
+    if (/^\d+$/.test(raw))
+        return { i: Number(raw) };
+    return { text: raw };
+};
+/** A target narrowed to the match nearest another (`--in`) and to a position among the matches (`--nth`). */
+export const scopedTarget = (raw, flags) => {
+    const target = parseTarget(raw);
+    if (!('testId' in target) && !('text' in target))
+        return target;
+    const scope = typeof flags.in === 'string' ? parseTarget(flags.in) : undefined;
+    if (scope && !('testId' in scope) && !('text' in scope))
+        throw new Error('--in takes a #testId or a text');
+    return {
+        ...target,
+        ...(scope ? { within: 'testId' in scope ? { testId: scope.testId } : { text: scope.text } } : {}),
+        ...(typeof flags.nth === 'number' ? { nth: flags.nth } : {}),
+    };
+};
+export const isRoute = (raw) => /^[A-Z]\w*(\.[A-Z]\w*)*$/.test(raw);
+/** What a command was looking for, as `why` reads it. */
+export const expectedOf = (raw) => {
+    if (!raw)
+        return undefined;
+    if (isRoute(raw))
+        return { route: raw };
+    const t = parseTarget(raw);
+    return 'testId' in t ? { testId: t.testId } : 'text' in t ? { text: t.text } : undefined;
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "lynkeus",
+  "version": "0.2.0",
+  "description": "Drive a React Native app running lynkeus-agent from the terminal, a test runner or an MCP client: screens, flows, smoke, crawl, and the app's screen graph.",
+  "type": "module",
+  "bin": "./lib/cli.js",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test src/__tests__/*.test.ts src/knowledge/__tests__/*.test.ts src/cases/__tests__/*.test.ts",
+    "dev": "tsx src/cli.ts",
+    "docs": "node lib/cli.js help --markdown > ../../docs/COMMANDS.md"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonamischener/lynkeus.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "lynkeus-client": "^0.2.0",
+    "lynkeus-protocol": "^0.2.0",
+    "pngjs": "^7.0.0",
+    "ts-morph": "^24.0.0",
+    "yaml": "^2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/pngjs": "^6.0.5",
+    "tsx": "^4.19.2",
+    "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/jonamischener/lynkeus#readme"
+}

package/src/__tests__/args.test.ts

@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { pairs, parseArgs, splitLine, UsageError } from '../args.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';
+
+const FLAGS = {
+  direct: { type: 'boolean' as const, help: '' },
+  depth: { type: 'number' as const, help: '', default: 4 },
+  var: { type: 'list' as const, help: '' },
+  out: { type: 'string' as const, help: '' },
+};
+
+test('booleans never eat the next positional; numbers are numbers; lists collect', () => {
+  const p = parseArgs(
+    ['--direct', 'a.ts', 'b.ts', '--depth', '2', '--var', 'x=1', '--var', 'y=2'],
+    [{ name: 'file', help: '', required: true, rest: true }],
+    FLAGS,
+  );
+  assert.deepEqual(p.args, ['a.ts', 'b.ts']);
+  assert.equal(p.flags.direct, true);
+  assert.equal(p.flags.depth, 2);
+  assert.deepEqual(p.flags.var, ['x=1', 'y=2']);
+  assert.deepEqual(pairs(p.flags.var as string[]), { x: '1', y: '2' });
+});
+
+test('defaults, --no-flag, --flag=value and passthrough after --', () => {
+  const p = parseArgs(['--no-direct', '--out=x.json', '--', '--jest-flag'], [], FLAGS);
+  assert.equal(p.flags.direct, false);
+  assert.equal(p.flags.depth, 4);
+  assert.equal(p.flags.out, 'x.json');
+  assert.deepEqual(p.passthrough, ['--jest-flag']);
+});
+
+test('unknown flags, missing values and missing positionals are usage errors that name what exists', () => {
+  assert.throws(
+    () => parseArgs(['--nope'], [], FLAGS),
+    (e: unknown) => e instanceof UsageError && /--direct/.test((e as Error).message),
+  );
+  assert.throws(() => parseArgs(['--depth', '--direct'], [], FLAGS), /--depth needs a value/);
+  assert.throws(() => parseArgs(['--depth', 'x'], [], FLAGS), /expects a number/);
+  assert.throws(() => parseArgs([], [{ name: 'target', help: '', required: true }], FLAGS), /missing <target>/);
+  assert.throws(() => parseArgs(['a', 'b'], [{ name: 'one', help: '' }], FLAGS), /unexpected argument "b"/);
+});
+
+test('a session line splits on spaces and keeps quoted text together', () => {
+  assert.deepEqual(splitLine('press "Comenzar ya" --hold 200'), ['press', 'Comenzar ya', '--hold', '200']);
+});
+
+test('every command is named once, documented, and its aliases are unique', () => {
+  const all = [...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...headlessCommands];
+  const names = new Set<string>();
+  for (const c of all) {
+    assert.ok(c.summary.length > 10, `${c.name} has a summary`);
+    assert.ok(!names.has(c.name), `${c.name} defined once`);
+    names.add(c.name);
+    for (const a of c.aliases ?? []) {
+      assert.ok(!names.has(a), `${a} unique`);
+      names.add(a);
+    }
+    for (const [flag, spec] of Object.entries(c.flags ?? {})) assert.ok(spec.help, `${c.name} --${flag} has help`);
+    for (const p of c.positionals ?? []) assert.ok(p.help, `${c.name} <${p.name}> has help`);
+  }
+  for (const short of ['plan', 'deeplink', 'appstate', 'network', 'clock', 'biometrics', 'scan', 'gallery', 'headless'])
+    assert.ok(names.has(short), `${short} accepted`);
+});
+
+test('MCP serves a small core by default and everything else on request', () => {
+  const all = [...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...headlessCommands];
+  const core = all.filter((c) => c.mcp === 'core').map((c) => c.name);
+  assert.deepEqual(core.sort(), ['call', 'map plan', 'map show', 'os deeplink', 'press', 'screen', 'type', 'wait', 'why']);
+});
+
+test('what MCP leaves out of a tool is still a flag of the command', () => {
+  for (const c of [...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...headlessCommands]) {
+    for (const flag of c.mcpOmit ?? []) assert.ok(c.flags?.[flag], `${c.name} omits --${flag}, which it does not have`);
+  }
+});

package/src/__tests__/check.test.ts

@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { diffGraphs, newFindings } from '../commands/check.js';
+import { mapCheckWorkflow } from '../commands/map.js';
+import { summarizeRuns } from '../commands/flake.js';
+import type { FlowReport } from '../flow/types.js';
+import type { ScreenGraph } from '../knowledge/types.js';
+
+const graph = (screens: Record<string, string | null>, files: Record<string, { selectors?: string[]; navigates?: string[] }>): ScreenGraph =>
+  ({
+    app: 'x',
+    root: '/x',
+    extractedAt: '',
+    warnings: [],
+    screens: Object.fromEntries(Object.entries(screens).map(([route, file]) => [route, { route, component: route, file, declaredIn: 'nav.tsx' }])),
+    files: Object.fromEntries(
+      Object.entries(files).map(([file, f]) => [
+        file,
+        {
+          selectors: (f.selectors ?? []).map((id) => ({ id, line: 1 })),
+          navigates: (f.navigates ?? []).map((to) => ({ to, line: 1, confidence: 'static', via: { kind: 'unknown' } })),
+          imports: [],
+        },
+      ]),
+    ),
+  }) as unknown as ScreenGraph;
+
+test('a graph diff names routes, navigations and testIDs that changed', () => {
+  const base = graph({ A: 'a.tsx', B: 'b.tsx' }, { 'a.tsx': { selectors: ['go-b'], navigates: ['B'] }, 'b.tsx': { selectors: ['submit'] } });
+  const head = graph({ A: 'a.tsx', B: 'b.tsx', C: 'c.tsx' }, { 'a.tsx': { selectors: ['go-b', 'go-c'], navigates: ['B', 'C'] }, 'b.tsx': {}, 'c.tsx': {} });
+  const d = diffGraphs(base, head);
+  assert.deepEqual(d.routesAdded, ['C']);
+  assert.deepEqual(d.edgesAdded, [{ from: 'A', to: 'C' }]);
+  assert.deepEqual(d.selectorsAdded, [{ file: 'a.tsx', id: 'go-c' }]);
+  assert.deepEqual(d.selectorsRemoved, [{ file: 'b.tsx', id: 'submit' }]);
+});
+
+test('lint findings already in the baseline are not new', () => {
+  const f1 = { finding: { rule: 'unlabeled-control', severity: 'warn' as const, element: 3, message: 'button without a label' }, testId: 'x' };
+  const f2 = { finding: { rule: 'small-target', severity: 'warn' as const, element: 4, message: '20×20' }, testId: 'y' };
+  const fresh = newFindings({ A: [{ rule: 'unlabeled-control', testId: 'x', message: 'button without a label' }] }, 'A', [f1, f2]);
+  assert.deepEqual(fresh, [f2]);
+});
+
+test('flake runs are summarised by the step and error they died on', () => {
+  const ok = (ms: number): FlowReport => ({ name: 'f', ok: true, totalMs: ms, vars: {}, steps: [{ step: { press: { testId: 'a' } }, ok: true, ms: 1 }] });
+  const bad = (err: string): FlowReport => ({
+    name: 'f',
+    ok: false,
+    totalMs: 900,
+    vars: {},
+    steps: [
+      { step: { press: { testId: 'a' } }, ok: true, ms: 1 },
+      { step: { waitFor: { route: 'A' } }, ok: false, ms: 1, error: err },
+    ],
+  });
+  const s = summarizeRuns([ok(100), bad('Timed out waiting for A (on Z)'), ok(300), bad('Timed out waiting for A (on Y)')]);
+  assert.equal(s.passed, 2);
+  assert.equal(s.failures.length, 1);
+  assert.equal(s.failures[0]!.times, 2);
+  assert.equal(s.failures[0]!.step, 2);
+  assert.match(s.failures[0]!.what, /waitFor/);
+});
+
+test('the map check workflow diffs against the pull request base and keeps one comment', () => {
+  const yml = mapCheckWorkflow(2);
+  assert.match(yml, /lynkeus map check --base origin\/\$\{\{ github\.base_ref \}\} --depth 2/);
+  assert.match(yml, /--edit-last/);
+  assert.match(yml, /pull-requests: write/);
+});

package/src/__tests__/init.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+
+import { init } from '../commands/init.js';
+import { explainError } from '../knowledge/errors.js';
+
+const tmpApp = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-init-'));
+  fs.mkdirSync(path.join(root, 'app'));
+  fs.writeFileSync(path.join(root, 'app', 'App.tsx'), 'export default () => null');
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'demo' }));
+  fs.writeFileSync(
+    path.join(root, 'index.js'),
+    "import { AppRegistry } from 'react-native'\nimport App from './app/App'\n\nAppRegistry.registerComponent('demo', () => App)\n",
+  );
+  return root;
+};
+
+test('init writes an entry that requires the app and refuses non-local backends', () => {
+  const root = tmpApp();
+  const notes = init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: false, force: false });
+  const entry = fs.readFileSync(path.join(root, 'qa/headless.tsx'), 'utf8');
+  assert.match(entry, /require\('\.\.\/app\/App'\)/);
+  assert.match(entry, /process\.env\.API_URL/);
+  assert.match(entry, /installDefaultMocks/);
+  assert.ok(notes.some((n) => n.includes('wrote qa/headless.tsx')));
+  // Second run leaves it alone.
+  const again = init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: false, force: false });
+  assert.ok(again.some((n) => n.includes('left as is')));
+});
+
+test('init --auto adds the mount after the imports, once', () => {
+  const root = tmpApp();
+  init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: true, force: false });
+  init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: true, force: false });
+  const index = fs.readFileSync(path.join(root, 'index.js'), 'utf8');
+  assert.equal(index.split('lynkeus-agent/auto').length, 2);
+  assert.ok(index.indexOf('auto(') < index.indexOf('registerComponent'));
+  assert.ok(index.indexOf("import App from './app/App'") < index.indexOf('lynkeus-agent/auto'));
+});
+
+test('the error catalogue names the module behind a TurboModule crash', () => {
+  const [e] = explainError(
+    "Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'RNCWebView' could not be found. Verify that a module by this name is registered",
+  );
+  assert.ok(e);
+  assert.match(e.cause, /RNCWebView/);
+  assert.equal(explainError('all good').length, 0);
+});

package/src/__tests__/record.test.ts

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { simulatorArgv } from '../commands/device.js';
+import { draftFlow } from '../commands/record.js';
+import type { TraceEvent } from 'lynkeus-protocol';
+
+const ev = (partial: Record<string, unknown>, seq: number): TraceEvent => ({ seq, t: seq * 100, ...partial }) as unknown as TraceEvent;
+
+test('a recording becomes presses with what each one caused', () => {
+  const flow = draftFlow([
+    ev({ kind: 'route', route: 'First.Screen', path: ['First.Screen'] }, 1),
+    ev({ kind: 'touch', x: 10, y: 20, testId: 'primary-button', route: 'First.Screen' }, 2),
+    ev({ kind: 'request', method: 'GET', url: 'http://x/api/items', status: 200, ms: 40 }, 3),
+    ev({ kind: 'route', route: 'Second.Screen', path: ['Second.Screen'] }, 4),
+    ev({ kind: 'touch', x: 10, y: 20, text: 'Second option', route: 'Second.Screen' }, 5),
+    ev({ kind: 'store', store: 'session', changed: { step: { from: 1, to: 2 } } }, 6),
+    ev({ kind: 'touch', x: 5, y: 5, route: 'Second.Screen' }, 7),
+  ]);
+  assert.deepEqual(flow.steps, [
+    { press: { testId: 'primary-button' } },
+    { waitFor: { route: 'Second.Screen', timeoutMs: 10000 } },
+    { note: 'requests: GET /api/items 200' },
+    { press: { text: 'Second option' } },
+    { note: 'stores changed: session.step' },
+    { note: 'touch at 5,5 on Second.Screen hit nothing lynkeus could name' },
+  ]);
+});
+
+test('device subcommands map to simctl and adb', () => {
+  assert.deepEqual(simulatorArgv('ios', 'UDID', 'permissions', ['grant', 'camera'], 'com.example.myapp')[0], {
+    bin: 'xcrun',
+    args: ['simctl', 'privacy', 'UDID', 'grant', 'camera', 'com.example.myapp'],
+  });
+  assert.deepEqual(simulatorArgv('ios', 'UDID', 'appearance', ['dark'])[0]!.args, ['simctl', 'ui', 'UDID', 'appearance', 'dark']);
+  assert.deepEqual(simulatorArgv('ios', 'UDID', 'location', ['-34.6,-58.4'])[0]!.args, ['simctl', 'location', 'UDID', 'set', '-34.6,-58.4']);
+  assert.equal(simulatorArgv('ios', 'UDID', 'language', ['de-DE'], 'com.example.myapp').length, 2);
+  assert.deepEqual(simulatorArgv('android', 'emu', 'permissions', ['grant', 'camera'], 'com.example.myapp')[0]!.args, [
+    '-s',
+    'emu',
+    'shell',
+    'pm',
+    'grant',
+    'com.example.myapp',
+    'android.permission.CAMERA',
+  ]);
+  assert.throws(() => simulatorArgv('ios', 'UDID', 'permissions', ['grant', 'camera']), /--app/);
+  assert.throws(() => simulatorArgv('ios', 'UDID', 'appearance', ['blue']), /light\|dark/);
+});

package/src/__tests__/snapshot.test.ts

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { PNG } from 'pngjs';
+
+import { comparePng, snapshot } from '../commands/snapshot.js';
+
+const png = (w: number, h: number, paint: (x: number, y: number) => [number, number, number]): Buffer => {
+  const p = new PNG({ width: w, height: h });
+  for (let y = 0; y < h; y++)
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4;
+      const [r, g, b] = paint(x, y);
+      p.data[i] = r;
+      p.data[i + 1] = g;
+      p.data[i + 2] = b;
+      p.data[i + 3] = 255;
+    }
+  return PNG.sync.write(p);
+};
+
+test('pixels that moved are counted and painted into a diff', () => {
+  const a = png(10, 10, () => [255, 255, 255]);
+  const b = png(10, 10, (x, y) => (x < 2 && y < 2 ? [0, 0, 0] : [250, 250, 250]));
+  const c = comparePng(a, b);
+  assert.equal(c.different, 4); // the 250 vs 255 shade stays under the channel threshold
+  assert.equal(c.ratio, 0.04);
+  assert.ok(c.diff);
+  const d = PNG.sync.read(c.diff!);
+  assert.deepEqual([d.data[0], d.data[1], d.data[2]], [255, 0, 0]);
+});
+
+test('a first capture is the baseline; a small change matches; a big one writes a diff', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-snap-'));
+  const lynkeusDir = path.join(root, '.lynkeus');
+  const runsDir = path.join(lynkeusDir, 'runs');
+  const white = png(20, 20, () => [255, 255, 255]);
+  assert.equal(snapshot(lynkeusDir, 'card', white, { runsDir }).status, 'baseline');
+  const nearly = png(20, 20, (x, y) => (x === 0 && y === 0 ? [0, 0, 0] : [255, 255, 255]));
+  assert.equal(snapshot(lynkeusDir, 'card', nearly, { runsDir, tolerance: 0.01 }).status, 'match');
+  const half = png(20, 20, (x) => (x < 10 ? [0, 0, 0] : [255, 255, 255]));
+  const r = snapshot(lynkeusDir, 'card', half, { runsDir });
+  assert.equal(r.status, 'mismatch');
+  assert.ok(fs.existsSync(r.diffFile!));
+  assert.equal(snapshot(lynkeusDir, 'card', half, { runsDir, update: true }).status, 'baseline');
+  assert.equal(snapshot(lynkeusDir, 'card', half, { runsDir }).status, 'match');
+  const other = png(30, 20, () => [255, 255, 255]);
+  assert.ok(snapshot(lynkeusDir, 'card', other, { runsDir }).comparison?.sizeMismatch);
+});