lynkeus 0.2.0 → 0.3.0

package/src/commands/cases.ts

@@ -1,15 +1,23 @@
 import { type ChildProcess, spawn } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import { Fixtures } from '../cases/fixtures.js';
 import { readCases } from '../cases/format.js';
-import { type CaseReport, runCase } from '../cases/runner.js';
+import type { Case } from '../cases/format.js';
+import { type CasesConfig, type CaseReport, missingFixtures, type Prepared, preparable, runCase } from '../cases/runner.js';
 import { CONFIG, EXAMPLE_CASE, FIXTURES, FORMAT } from '../cases/templates.js';
-import { configFile } from '../config.js';
+import { claimPorts } from '../cases/portClaim.js';
+import { configFile, portFromEnv } from '../config.js';
 import { readJson, writeJson } from '../files.js';
+import { Ahead, InMemory, type Store } from '../cases/ahead.js';
+import { Flakes } from '../cases/flakes.js';
+import { RunFile } from '../cases/runfile.js';
 import { eventsFile } from '../knowledge/events.js';
-import { define } from '../registry.js';
+import { type Base, define } from '../registry.js';
+import { describeChanges, pushRun, service } from './report.js';
+import { TraceSink } from '../cases/traces.js';
 
 const startHost = async (root: string, err: (line: string) => void): Promise<ChildProcess> => {
   // Its own process group: the host starts a test runner of its own, and stopping one without the other leaves an app dialing in.
@@ -47,11 +55,30 @@ const stopGroup = (pid: number) => {
   } catch {}
 };
 
+/**
+ * Stops a host and waits until it is gone. The next case's host dials the same port, and a host still on
+ * its way out dials it too: whichever reaches the driver first is the one the case talks to.
+ */
+const stopHost = async (host: ChildProcess): Promise<void> => {
+  if (!host.pid || host.exitCode !== null || host.signalCode !== null) return;
+  const gone = new Promise<void>((resolve) => host.once('exit', () => resolve()));
+  host.stdin?.end();
+  stopGroup(host.pid);
+  const late = setTimeout(() => {
+    try {
+      process.kill(-host.pid!, 'SIGKILL');
+    } catch {}
+  }, 2000);
+  await gone;
+  clearTimeout(late);
+};
+
 const describe = (report: CaseReport): string => {
-  const counts = { passed: 0, failed: 0, skipped: 0 };
+  const counts = { passed: 0, failed: 0, skipped: 0, unsupported: 0 };
   for (const s of report.steps) counts[s.status] += 1;
+  const headline = { passed: '✅ PASSED', failed: '❌ FAILED', unsupported: '🚫 NOT ON THIS HOST' }[report.result];
   const lines = [
-    `${report.result === 'passed' ? '✅ PASSED' : '❌ FAILED'}  ✅ ${counts.passed}${counts.failed ? `  ❌ ${counts.failed}` : ''}${counts.skipped ? `  ⏭️ ${counts.skipped}` : ''}  — ${(report.ms / 1000).toFixed(1)}s`,
+    `${headline}  ✅ ${counts.passed}${counts.failed ? `  ❌ ${counts.failed}` : ''}${counts.unsupported ? `  🚫 ${counts.unsupported}` : ''}${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}`));
@@ -59,6 +86,98 @@ const describe = (report: CaseReport): string => {
   return lines.join('\n');
 };
 
+/** The share of the machine's CPU that sat idle over the next 300 ms. */
+const idleShare = async (): Promise<number> => {
+  const total = () =>
+    os.cpus().reduce(
+      (sum, cpu) => {
+        const t = cpu.times;
+        return { idle: sum.idle + t.idle, all: sum.all + t.idle + t.user + t.sys + t.nice + t.irq };
+      },
+      { idle: 0, all: 0 },
+    );
+  const before = total();
+  await new Promise((r) => setTimeout(r, 300));
+  const after = total();
+  return after.all > before.all ? (after.idle - before.idle) / (after.all - before.all) : 1;
+};
+
+/** The case files named, or every case under the cases directory; a sentence when there are none. */
+const caseFiles = (args: string[], home: string, casesDir: string | undefined): string[] | string => {
+  const dir = path.resolve(home, casesDir ?? 'cases');
+  const files = args.length
+    ? 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))
+      : [];
+  return files.length > 0 ? files : `no cases under ${path.relative(home, dir) || '.'}; \`lynkeus case init\` writes one`;
+};
+
+type PrepareOptions = { base: Base; config: CasesConfig; store: Store; open: () => Fixtures; limit: number; idle: number; jobs: number };
+
+/**
+ * Runs the setups of `cases` ahead of them, in order, `jobs` at a time: never more than `limit` waiting
+ * to be taken, and only while the machine has `idle` of its CPU to spare. A case that started first is skipped.
+ */
+const prepareAhead = async (cases: Case[], o: PrepareOptions): Promise<{ made: number; skipped: number }> => {
+  let next = 0;
+  let made = 0;
+  let skipped = 0;
+  // Far enough ahead, or the machine busy: a setup made then only takes the CPU from the cases
+  // running now, and the suite gains nothing from having it early.
+  const room = async (): Promise<boolean> => {
+    if (o.store.waiting() < o.limit) return (await idleShare()) >= o.idle;
+    // A timer, not a bare check: the jobs that take the waiting setups may run in this same process,
+    // and a loop that never yields to the event loop would keep them from ever taking one.
+    await new Promise((r) => setTimeout(r, 100));
+    return false;
+  };
+  const worker = async () => {
+    const fixtures = o.open();
+    await fixtures.ahead();
+    try {
+      for (let c = cases[next++]; c; c = cases[next++]) {
+        while (!o.store.started(c) && !(await room()));
+        if (o.store.started(c)) {
+          skipped++;
+          continue;
+        }
+        const done = c;
+        await runCase(done, { base: o.base, config: o.config, fixtures, setupOnly: { keep: (p) => o.store.keep(done, p) } });
+        made++;
+      }
+    } finally {
+      fixtures.close();
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, o.jobs) }, worker));
+  return { made, skipped };
+};
+
+/** A host for one case, started by the project's own command: `{port}` is where it dials the driver. */
+const spawnHost = (command: string, port: number, job: number, cwd: string): ChildProcess =>
+  spawn('/bin/sh', ['-c', command.replaceAll('{port}', String(port)).replaceAll('{job}', String(job))], {
+    cwd,
+    env: process.env,
+    // stdin stays open for the host's life: a host that serves until its stdin closes stops with the case.
+    stdio: ['pipe', 'ignore', 'ignore'],
+    detached: true,
+  });
+
+/** A run that could not be uploaded still ran: the failure is said, not raised. */
+const pushed = async (dir: string, to: Exclude<ReturnType<typeof service>, string>, project: string) => {
+  try {
+    const run = await pushRun(dir, { ...to, project });
+    return [`report: ${run.url}${run.refused.length ? ` (not kept on this plan: ${run.refused.join(', ')})` : ''}`, ...describeChanges(run.changes)].join('\n');
+  } catch (error) {
+    return `the report was not uploaded: ${(error as Error).message}`;
+  }
+};
+
 export const caseCommands = [
   define({
     name: 'case run',
@@ -70,8 +189,33 @@ export const caseCommands = [
     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' },
+      continue: { type: 'boolean', help: "keep running a case's steps after one fails (a failed setup still stops it)" },
+      seen: { type: 'string', help: 'write <dir>/<case id>.json with the screens each passing case went through, for a coverage map', value: 'dir' },
       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' },
+      out: { type: 'string', help: 'write the run as a directory a report can read: run.json and cases.jsonl, a line per attempt', value: 'dir' },
+      screenshots: { type: 'boolean', help: 'with --out: a frame of the screen after every step of the app' },
+      video: { type: 'boolean', help: 'with --out: film each case, where the host films (the step says at what second it began)' },
+      traces: {
+        type: 'boolean',
+        help: 'listen for the backend’s OpenTelemetry traces (OTLP over HTTP) and keep, under each step, what the backend did for it; point the backend’s OTEL_EXPORTER_OTLP_ENDPOINT at http://localhost:<traces-port>',
+      },
+      'traces-port': { type: 'number', help: 'where --traces listens', default: 4318, value: 'port' },
+      push: { type: 'boolean', help: 'with --out: upload the run to the reports service when it ends and print the report’s address' },
+      project: { type: 'string', help: 'with --push: the project the run is filed under (default: the app’s folder name)', value: 'name' },
+      'video-fps': { type: 'number', help: 'frames per second of the film', default: 30, value: 'n' },
+      flakes: { type: 'string', help: 'the ledger of how each case did across runs (default .lynkeus/flakes.json)', value: 'file' },
+      prepared: { type: 'string', help: 'where `case prepare` leaves setups made ahead; a case found there skips its setup', value: 'dir' },
+      jobs: { type: 'number', help: 'cases at once, each on its own host (needs --ports)', value: 'n', default: 1 },
+      ports: { type: 'string', help: 'the driver port of each job, comma-separated: where its host dials in', value: 'list' },
+      'host-command': {
+        type: 'string',
+        help: 'starts a fresh host for every case and stops it after; {port} is where the host dials, {job} the job',
+        value: 'command',
+      },
+      'in-order': { type: 'boolean', help: 'with --jobs: take the cases in the order given, not the longest first' },
+      ahead: { type: 'number', help: 'make up to this many setups ahead of their cases while others run (0: none)', value: 'n', default: 0 },
+      idle: { type: 'number', help: 'with --ahead: start a setup only while this share of the CPU is idle', value: 'share', default: 0.25 },
       'dry-run': { type: 'boolean', help: 'parse and list the steps without running them' },
     },
     needs: 'nothing',
@@ -80,23 +224,56 @@ export const caseCommands = [
     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 files = caseFiles(ctx.args, home, config.dir);
+      if (typeof files === 'string') return { text: files, code: 1 };
       const cases = files.flatMap(readCases);
       const dry = !!ctx.flags['dry-run'];
-      const events = typeof ctx.flags.events === 'string';
+      const seenDir = typeof ctx.flags.seen === 'string' && !dry ? path.resolve(ctx.flags.seen) : undefined;
+      const out = typeof ctx.flags.out === 'string' && !dry ? new RunFile(path.resolve(ctx.flags.out), ctx.root) : undefined;
+      if ((ctx.flags.screenshots || ctx.flags.video) && !out)
+        return { text: '--screenshots and --video keep what they take in the run directory: add --out <dir>', code: 2 };
+      // Checked before the run, so a missing key does not surface only after every case has run.
+      const reportsTo = ctx.flags.push && out ? service() : undefined;
+      if (ctx.flags.push && !out) return { text: '--push uploads the run directory: add --out <dir>', code: 2 };
+      if (typeof reportsTo === 'string') return { text: reportsTo, code: 2 };
+      const evidenceOf = (id: string, attempt: number) =>
+        out && (ctx.flags.screenshots || ctx.flags.video)
+          ? {
+              dir: out.evidenceDir(id, attempt),
+              screenshots: !!ctx.flags.screenshots,
+              ...(ctx.flags.video ? { video: { fps: Number(ctx.flags['video-fps'] ?? 30) } } : {}),
+            }
+          : undefined;
+      const ledger = dry ? undefined : new Flakes(path.resolve(ctx.root, typeof ctx.flags.flakes === 'string' ? ctx.flags.flakes : '.lynkeus/flakes.json'));
+      // A run file files each event under its step, so it needs them collected.
+      const events = typeof ctx.flags.events === 'string' || out !== undefined;
+      const claimed = dry
+        ? undefined
+        : claimPorts(
+            typeof ctx.flags.ports === 'string'
+              ? ctx.flags.ports
+                  .split(',')
+                  .map(Number)
+                  .filter(Number.isInteger)
+                  .slice(0, Math.max(1, Number(ctx.flags.jobs ?? 1)))
+              : [portFromEnv(ctx.config) ?? 8123],
+          );
+      if (claimed && 'refused' in claimed) return { text: claimed.refused, code: 1 };
       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 traces = ctx.flags.traces && !dry ? new TraceSink(Number(ctx.flags['traces-port'] ?? 4318)) : undefined;
+      if (traces) {
+        try {
+          await traces.start();
+        } catch (error) {
+          fixtures?.close();
+          return { text: `--traces could not listen on port ${traces.port}: ${(error as Error).message}`, code: 2 };
+        }
+        ctx.err(`backend traces: listening on http://localhost:${traces.port} (the backend's OTEL_EXPORTER_OTLP_ENDPOINT)`);
+      }
       const stop = () => {
+        traces?.close();
+        claimed?.release();
         fixtures?.close();
         if (host?.pid) stopGroup(host.pid);
       };
@@ -108,32 +285,193 @@ export const caseCommands = [
       process.once('SIGTERM', interrupted);
       const reports: (CaseReport & { retried?: boolean })[] = [];
       try {
-        for (const c of cases) {
-          ctx.err(`▶ ${c.id}${c.title ? ` — ${c.title}` : ''}`);
-          let report: CaseReport & { retried?: boolean } = 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 as string, 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 as string), `${JSON.stringify(report)}\n`);
+        // A case that names a fixture the server does not have fails halfway, after it has changed the backend. Better not to start.
+        const described = await fixtures?.describe();
+        if (described?.down) return { text: `the fixtures server cannot serve: ${described.down}`, code: 1 };
+        if (described) {
+          const missing = cases.flatMap((c) => missingFixtures(c, config, described.commands).map((name) => `${c.id}: no fixture ${name}`));
+          if (missing.length > 0) return { text: [...missing, `the fixtures command answers: ${described.commands.join(', ')}`].join('\n'), code: 1 };
         }
+        const jobs = Math.max(1, Number(ctx.flags.jobs ?? 1));
+        const ports = typeof ctx.flags.ports === 'string' ? ctx.flags.ports.split(',').map(Number) : [];
+        const hostCommand = typeof ctx.flags['host-command'] === 'string' && !dry ? ctx.flags['host-command'] : undefined;
+        if ((jobs > 1 || hostCommand) && (ports.length < jobs || ports.some((p) => !Number.isInteger(p)) || !ctx.forPort))
+          return { text: `--jobs and --host-command need a driver port per job: --ports with ${jobs}`, code: 2 };
+        // Several jobs finish together only if the longest cases start first: one left for the end runs alone
+        // while the other jobs wait. A case the ledger has not timed goes first too, as it may be long.
+        if (jobs > 1 && ledger && !ctx.flags['in-order']) {
+          const took = (id: string) => ledger.lastMs(id) ?? Number.POSITIVE_INFINITY;
+          cases.sort((a, b) => took(b.id) - took(a.id));
+        }
+        const limit = Number(ctx.flags.ahead ?? 0);
+        const store: Store | undefined =
+          typeof ctx.flags.prepared === 'string' && !dry ? new Ahead(path.resolve(ctx.flags.prepared)) : limit > 0 && fixtures ? new InMemory() : undefined;
+        const declared = config.fixtures;
+        // The setups of the cases to come, made while these run, in the order the jobs will take them.
+        const preparing =
+          limit > 0 && declared && store && !dry
+            ? prepareAhead(
+                cases.filter((c) => preparable(c, config)),
+                {
+                  base: ctx,
+                  config,
+                  store,
+                  open: () => new Fixtures(declared, home),
+                  limit,
+                  idle: Number(ctx.flags.idle ?? 0.25),
+                  jobs: 1,
+                },
+              )
+            : undefined;
+        let next = 0;
+        const job = async (index: number) => {
+          // Each job keeps its own connection to the fixtures server, warm from one case to the next.
+          const own = index === 0 ? fixtures : declared && !dry ? new Fixtures(declared, home) : undefined;
+          const port = ports[index];
+          try {
+            for (let c = cases[next++]; c; c = cases[next++]) {
+              const lines: string[] = [];
+              // With several jobs a case's lines are held and printed together, not interleaved.
+              const log = jobs > 1 ? (line: string) => lines.push(line) : ctx.err;
+              log(`▶ ${c.id}${c.title ? ` — ${c.title}` : ''}`);
+              store?.start(c);
+              const attempt = async (n: number, prepared?: Prepared) => {
+                const host = hostCommand && port !== undefined ? spawnHost(hostCommand, port, index, ctx.root) : undefined;
+                const scoped = port !== undefined && ctx.forPort ? ctx.forPort(port) : { base: ctx as Base, stop: async () => undefined };
+                const startedAt = new Date();
+                try {
+                  // A host just started is still drawing its first screens; with the setup made ahead nothing
+                  // else gives it that moment before the first press.
+                  if (host)
+                    await scoped.base
+                      .device()
+                      .then((d) => d.idle({ quietMs: 300, timeoutMs: 5000 }))
+                      .catch(() => undefined);
+                  const report = await runCase(c, {
+                    base: scoped.base,
+                    config,
+                    fixtures: own,
+                    dry,
+                    events,
+                    evidence: evidenceOf(c.id, n),
+                    log,
+                    prepared,
+                    continue: !!ctx.flags.continue,
+                    routes: seenDir ? (host ? 'fresh' : true) : false,
+                    traces,
+                  });
+                  if (seenDir && report.result === 'passed' && report.routes?.length) {
+                    fs.mkdirSync(seenDir, { recursive: true });
+                    fs.writeFileSync(path.join(seenDir, `${c.id}.json`), `${JSON.stringify({ id: c.id, routes: report.routes }, null, 2)}\n`);
+                  }
+                  return { report, startedAt, hello: (await scoped.base.device().catch(() => undefined))?.server.hello ?? undefined };
+                } finally {
+                  if (host) await stopHost(host);
+                  await scoped.stop();
+                }
+              };
+              let {
+                report,
+                startedAt,
+                hello,
+              }: { report: CaseReport & { retried?: boolean }; startedAt: Date; hello?: { platform?: string; native?: boolean } } = await attempt(
+                1,
+                store?.take(c),
+              );
+              seen ??= hello;
+              log(describe(report));
+              out?.add(c, { report, attempt: 1, startedAt });
+              if (report.result === 'failed' && !ctx.flags.once && !dry) {
+                log(`  retrying ${c.id} once`);
+                const again = await attempt(2);
+                report = { ...again.report, retried: true };
+                startedAt = again.startedAt;
+                log(describe(report));
+                out?.add(c, { report, attempt: 2, startedAt });
+              }
+              if (jobs > 1) ctx.err(lines.join('\n'));
+              ledger?.note(report);
+              if (typeof ctx.flags.events === 'string' && report.events) {
+                const dir = path.resolve(ctx.flags.events as string, c.id);
+                fs.mkdirSync(dir, { recursive: true });
+                fs.writeFileSync(eventsFile(dir), report.events.map((e) => `${JSON.stringify(e)}\n`).join(''));
+              }
+              reports.push(report);
+              if (ctx.flags.report) fs.appendFileSync(path.resolve(ctx.flags.report as string), `${JSON.stringify(report)}\n`);
+            }
+          } finally {
+            if (own !== fixtures) own?.close();
+          }
+        };
+        let seen: { platform?: string; native?: boolean } | undefined;
+        await Promise.all(Array.from({ length: jobs }, (_, i) => job(i)));
+        await preparing;
+        if (out) out.finish({ platform: seen?.platform, native: seen?.native });
       } finally {
         stop();
       }
-      const passed = reports.filter((r) => r.result === 'passed').length;
+      const count = (result: CaseReport['result']) => reports.filter((r) => r.result === result).length;
+      const unsupported = count('unsupported');
       const summary = [
-        ...reports.map((r) => `${r.result === 'passed' ? '✅' : '❌'} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}`),
-        `${passed}/${reports.length} passed`,
+        ...reports.map(
+          (r) => `${{ passed: '✅', failed: '❌', unsupported: '🚫' }[r.result]} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}`,
+        ),
+        `${count('passed')}/${reports.length} passed${unsupported ? `, ${unsupported} cannot run on this host` : ''}`,
+        ...(ledger ? ledger.flaky(reports.map((r) => r.id)) : []),
+        ...(reportsTo && out
+          ? [
+              await pushed(
+                path.resolve(ctx.flags.out as string),
+                reportsTo,
+                typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root),
+              ),
+            ]
+          : []),
       ].join('\n');
-      return { text: summary, json: reports, code: passed === reports.length ? 0 : 1 };
+      ledger?.save();
+      // A case this host cannot run is not a failure of the app; only a failed case fails the run.
+      return { text: summary, json: reports, code: count('failed') === 0 ? 0 : 1 };
+    },
+  }),
+  define({
+    name: 'case prepare',
+    group: 'runs',
+    summary: 'Run the setup of cases ahead of them, so each starts at its first step',
+    details:
+      'For a suite that starts `case run --prepared <dir>` once per case: start this first, with the same cases in the order they will run, and leave it running. It runs every setup made only of the project fixtures and leaves what each produced in <dir>; a case that starts before its setup is ready runs its own, and this skips it. It asks the fixtures server for a lower priority (`lynkeus.ahead`), so it takes what the running cases leave of the machine.',
+    positionals: [{ name: 'files', help: 'case files, in the order they will run (default: every .md under cases.dir)', rest: true }],
+    flags: {
+      prepared: { type: 'string', help: 'where to leave the setups (emptied first)', value: 'dir', default: '.lynkeus/prepared' },
+      jobs: { type: 'number', help: 'setups made at once', value: 'n', default: 1 },
+      ahead: { type: 'number', help: 'setups kept ready and not yet taken, at most', value: 'n', default: 4 },
+      idle: { type: 'number', help: 'start a setup only while at least this share of the CPU is idle (0 to 1)', value: 'share', default: 0.25 },
+    },
+    needs: 'nothing',
+    session: false,
+    mcp: false,
+    run: async (ctx) => {
+      const config = ctx.config.cases ?? {};
+      if (!config.fixtures) return { text: 'the project declares no fixtures (cases.fixtures in lynkeus.config.json): nothing to prepare', code: 1 };
+      const declared = config.fixtures;
+      const home = config.base ?? ctx.root;
+      const files = caseFiles(ctx.args, home, config.dir);
+      if (typeof files === 'string') return { text: files, code: 1 };
+      const cases = files.flatMap(readCases).filter((c) => preparable(c, config));
+      const probe = new Fixtures(declared, home);
+      const described = await probe.describe().finally(() => probe.close());
+      if (described?.down) return { text: `the fixtures server cannot serve: ${described.down}`, code: 1 };
+      const store = new Ahead(path.resolve(ctx.root, String(ctx.flags.prepared ?? '.lynkeus/prepared')));
+      store.clear();
+      const { made, skipped } = await prepareAhead(cases, {
+        base: ctx,
+        config,
+        store,
+        open: () => new Fixtures(declared, home),
+        limit: Math.max(1, Number(ctx.flags.ahead ?? 4)),
+        idle: Number(ctx.flags.idle ?? 0.25),
+        jobs: Number(ctx.flags.jobs ?? 1),
+      });
+      return { text: `${made} setups made ahead, ${skipped} cases had started first`, json: { made, skipped } };
     },
   }),
   define({

package/src/commands/check.ts

@@ -55,15 +55,22 @@ export 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 }[]>;
+export type LintBaseline = Record<string, { rule: string; testId?: string; subject?: string; message: string }[]>;
 
 type LintedFinding = { finding: Finding; testId?: string };
 
-const key = (rule: string, testId: string | undefined, message: string) => `${rule}|${testId ?? ''}|${message}`;
+const key = (rule: string, testId: string | undefined, what: string) => `${rule}|${testId ?? ''}|${what}`;
 
+/**
+ * A finding is known by its rule and what it is about, not by what was measured: a target that went from
+ * 32 to 30 points is the finding the baseline already has. A baseline saved before findings named their
+ * subject has only the message to go by.
+ */
 export const newFindings = (baseline: LintBaseline, route: string, findings: LintedFinding[]): LintedFinding[] => {
-  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)));
+  const seen = new Set((baseline[route] ?? []).map((b) => key(b.rule, b.testId, b.subject ?? b.message)));
+  return findings.filter(
+    (f) => !seen.has(key(f.finding.rule, f.testId, f.finding.subject ?? f.finding.message)) && !seen.has(key(f.finding.rule, f.testId, f.finding.message)),
+  );
 };
 
 export const describeGraphDiff = (d: GraphDiff): string => {

package/src/commands/drive.ts

@@ -1,16 +1,20 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
+import { PNG } from 'pngjs';
+
 import { lynkeusDir } from '../config.js';
 import { describeScreen, describeTrace } from '../device/driver.js';
 import { readJson, writeJson } from '../files.js';
+import { lintContrast } from '../knowledge/contrast.js';
 import { describeFindings, lintScreen } from '../knowledge/lint.js';
 import { describePerf, summarize, visitsFrom } from '../knowledge/perf.js';
 import * as screens from '../knowledge/screens.js';
 import { screenTree } from '../knowledge/tree.js';
 import { define } from '../registry.js';
 import { whyFor } from '../runtime.js';
-import { expectedOf, isRoute, parseTarget, scopedTarget, TARGET_HELP } from '../targets.js';
+import { expectedOf, isRoute, parseTarget, routeOf, scopedTarget, TARGET_HELP } from '../targets.js';
 import { type LintBaseline, newFindings } from './check.js';
 
 const SCOPE_FLAGS = {
@@ -165,7 +169,7 @@ export const driveCommands = [
     mcpOmit: ['nth'],
     group: 'drive',
     summary: 'Until a route or element appears (or leaves), or a number of ms',
-    positionals: [{ name: 'what', help: `Route | ${TARGET_HELP} | 800 (ms)`, required: true }],
+    positionals: [{ name: 'what', help: `Route | route:index | ${TARGET_HELP} | 800 (ms)`, required: true }],
     flags: {
       ...SCOPE_FLAGS,
       gone: { type: 'boolean', help: 'until it leaves the screen' },
@@ -181,7 +185,7 @@ export const driveCommands = [
       }
       return {
         json: await (await ctx.device()).waitFor({
-          ...(isRoute(raw) ? { route: raw } : { target: scopedTarget(raw, ctx.flags) }),
+          ...(isRoute(raw) ? { route: routeOf(raw) } : { target: scopedTarget(raw, ctx.flags) }),
           gone: ctx.flags.gone ? true : undefined,
           scroll: ctx.flags.scroll ? true : undefined,
           timeoutMs: ctx.flags.timeout as number,
@@ -206,7 +210,7 @@ export const driveCommands = [
     name: 'see',
     group: 'drive',
     summary: 'Assert a route or element is on screen now (exit 1 if not)',
-    positionals: [{ name: 'what', help: `Route | ${TARGET_HELP}`, required: true }],
+    positionals: [{ name: 'what', help: `Route | route:index | ${TARGET_HELP}`, required: true }],
     flags: {
       absent: { type: 'boolean', help: 'assert it is not there' },
       within: { type: 'number', help: 'allow it this long to appear', default: 0, value: 'ms' },
@@ -217,7 +221,7 @@ export const driveCommands = [
       const device = await ctx.device();
       try {
         const result = await device.waitFor({
-          ...(isRoute(raw) ? { route: raw } : { target: parseTarget(raw) }),
+          ...(isRoute(raw) ? { route: routeOf(raw) } : { target: parseTarget(raw) }),
           gone: ctx.flags.absent ? true : undefined,
           timeoutMs: Math.max(1, ctx.flags.within as number),
         });
@@ -341,9 +345,10 @@ export const driveCommands = [
   define({
     name: 'lint',
     group: 'drive',
-    summary: 'Unlabeled controls, small targets, untranslated keys, covered or clipped elements',
+    summary: 'Unlabeled controls, small targets, low-contrast text, untranslated keys, covered or clipped elements',
     flags: {
       strict: { type: 'boolean', help: 'exit 1 on any warning' },
+      'no-contrast': { type: 'boolean', help: 'skip the contrast of text against its background (it takes a screenshot)' },
       save: { type: 'string', help: "keep this screen's findings in a baseline file", value: 'file' },
       baseline: { type: 'string', help: 'print only what is new against a baseline file', value: 'file' },
     },
@@ -353,20 +358,38 @@ export const driveCommands = [
       const { lint, lintBaseline } = ctx.config;
       let findings = lintScreen(screen, { i18nKeyPatterns: lint?.i18nKeyPatterns?.map((p) => new RegExp(p, 'i')), minTouchTarget: lint?.minTouchTarget });
       const route = screen.route ?? '?';
+      const notes: string[] = [];
+      if (lint?.contrast !== false && !ctx.flags['no-contrast']) {
+        // Contrast is read off the pixels, so it needs a host that can take a picture of the screen.
+        const file = path.join(os.tmpdir(), `lynkeus-lint-${process.pid}-${Date.now()}.png`);
+        try {
+          await (await ctx.device()).screenshot(file);
+          const picture = PNG.sync.read(fs.readFileSync(file));
+          const contrast = lint?.contrast;
+          findings = [
+            ...findings,
+            ...lintContrast(screen, picture, { normal: contrast?.normal, large: contrast?.large, ignore: contrast?.ignore?.map((p) => new RegExp(p)) }),
+          ];
+        } catch {
+          notes.push('contrast not measured: this host takes no screenshots');
+        } finally {
+          fs.rmSync(file, { force: true });
+        }
+      }
       const withIds = findings.map((finding) => ({ finding, testId: screen.elements[finding.element]?.testId }));
       const lines: string[] = [];
       const save = ctx.flags.save as string | undefined;
       const baselineFile = (ctx.flags.baseline as string | undefined) ?? lintBaseline;
       if (save) {
         const baseline = fs.existsSync(save) ? readJson<LintBaseline>(save) : {};
-        baseline[route] = withIds.map((f) => ({ rule: f.finding.rule, testId: f.testId, message: f.finding.message }));
+        baseline[route] = withIds.map((f) => ({ rule: f.finding.rule, testId: f.testId, subject: f.finding.subject, message: f.finding.message }));
         writeJson(save, baseline);
         lines.push(`saved ${findings.length} finding(s) for ${route} → ${save}`);
       } else if (baselineFile && fs.existsSync(baselineFile)) {
         findings = newFindings(readJson<LintBaseline>(baselineFile), route, withIds).map((f) => f.finding);
         lines.push(findings.length ? `${findings.length} new against ${baselineFile}:` : `nothing new on ${route} against ${baselineFile}`);
       }
-      lines.push(describeFindings(findings, screen.route));
+      lines.push(describeFindings(findings, screen.route), ...notes);
       return { text: lines.join('\n'), json: findings, code: ctx.flags.strict && findings.some((f) => f.severity === 'warn') ? 1 : 0 };
     },
   }),

package/src/commands/headless.ts

@@ -6,7 +6,7 @@ import { type LynkeusConfig, lynkeusDir, portFromEnv } from '../config.js';
 import { describeExplanations, explainError } from '../knowledge/errors.js';
 import { type Ctx, define } from '../registry.js';
 import { doctor } from './doctor.js';
-import { init } from './init.js';
+import { init, mountAgent } from './init.js';
 
 const ENTRY_FLAG = { entry: { type: 'string' as const, help: 'the headless entry (or `entry` in lynkeus.config.json)', value: 'file' } };
 const entryOf = (ctx: Ctx) => (ctx.flags.entry as string | undefined) ?? ctx.config.entry ?? 'qa/headless.tsx';
@@ -32,6 +32,16 @@ hostApp(() => <entry.App />, { ${options.join(', ')} });
 };
 
 export const headlessCommands = [
+  define({
+    name: 'init',
+    group: 'drive',
+    summary: "Mount the agent from the app's entry: React Native or Expo (Expo Router gets an entry of its own)",
+    needs: 'nothing',
+    run: async (ctx) => {
+      const lines = mountAgent(ctx.root);
+      return { text: lines.join('\n'), json: lines };
+    },
+  }),
   define({
     name: 'headless start',
     group: 'headless',
@@ -121,7 +131,7 @@ export const headlessCommands = [
       if (ctx.flags.explain) {
         const found = explainError(ctx.flags.explain as string);
         return {
-          text: found.length ? describeExplanations(found).trim() : 'nothing in the catalogue matches; paste the first line of the error, not the stack.',
+          text: found.length ? describeExplanations(found).trim() : 'nothing in the catalog matches; paste the first line of the error, not the stack.',
           json: found,
         };
       }