lynkeus 0.3.0 → 0.5.0

package/lib/cli.js

@@ -8,15 +8,29 @@ 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 { ciCommands } from './commands/ci.js';
+import { coverageCommands } from './commands/coverage.js';
+import { fixturesCommands } from './commands/fixtures.js';
 import { reportCommands } from './commands/report.js';
 import { runsCommands } from './commands/runs.js';
-import { graphFile, loadConfig, loadGraph, portFromEnv } from './config.js';
-import { agentMismatch } from './device/agentVersion.js';
+import { graphFile, loadConfig, loadGraph, portFromEnv, readToken } from './config.js';
+import { agentMismatch, appSwitched, helloIdentity } from './device/agentVersion.js';
 import { HEADLESS_HOST, pickAgentDevice, pickAndroidDevice } 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, ...reportCommands, ...headlessCommands]);
+register([
+    ...driveCommands,
+    ...osCommands,
+    ...mapCommands,
+    ...runsCommands,
+    ...caseCommands,
+    ...coverageCommands,
+    ...ciCommands,
+    ...fixturesCommands,
+    ...reportCommands,
+    ...headlessCommands,
+]);
 /** The global flags, read leniently from the whole argv before any command parses its own. */
 const globals = (argv) => {
     const out = {};
@@ -39,6 +53,8 @@ const globals = (argv) => {
 };
 // Once per process: a suite reattaches for every case.
 let mismatchTold = false;
+let switchTold = false;
+let lastApp;
 // `ownHost`: the port belongs to a host this run started for a case; whatever dials in is the device.
 const contextFor = (argv, attached = false, port, ownHost = false) => {
     const g = globals(argv);
@@ -51,8 +67,15 @@ const contextFor = (argv, attached = false, port, ownHost = false) => {
         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: port ?? portFromEnv(config) });
+        const server = new AgentServer({ token: readToken(root), port: port ?? portFromEnv(config) });
         server.on('hello', (hello) => {
+            const identity = helloIdentity(hello);
+            const switched = switchTold ? undefined : appSwitched(lastApp, identity, server.port);
+            lastApp = identity;
+            if (switched) {
+                switchTold = true;
+                err(switched);
+            }
             const told = mismatchTold ? undefined : agentMismatch(hello);
             if (!told)
                 return;

package/lib/commands/cases.d.ts

@@ -1 +1,9 @@
+import { type CaseReport } from '../cases/runner.js';
+/** The case files named (a directory stands for every case under it), or every case under the cases directory; a sentence when there are none. */
+export declare const caseFiles: (args: string[], home: string, casesDir: string | undefined) => string[] | string;
+/** A run that could not be uploaded still ran: the failure is said, not raised. */
+export declare const missingEvidence: (reports: CaseReport[], asked: {
+    video: boolean;
+}) => string[];
+export declare const keptOrDeleted: (dir: string, afterPush: "keep" | "delete", complete: boolean) => string;
 export declare const caseCommands: import("../registry.js").Command[];

package/lib/commands/cases.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
 import { Fixtures } from '../cases/fixtures.js';
 import { readCases } from '../cases/format.js';
 import { missingFixtures, preparable, runCase } from '../cases/runner.js';
@@ -16,6 +17,8 @@ import { eventsFile } from '../knowledge/events.js';
 import { define } from '../registry.js';
 import { describeChanges, pushRun, service } from './report.js';
 import { TraceSink } from '../cases/traces.js';
+import { megabytes, sizeOf } from '../cases/runDirs.js';
+import { startNativeLogs } from '../cases/nativeLogs.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'], {
@@ -24,8 +27,27 @@ const startHost = async (root, err) => {
         stdio: ['ignore', 'pipe', 'pipe'],
         detached: true,
     });
+    // Everything the host prints, for the render errors and warnings a failed case points at; the console keeps the run's own lines.
+    const logFile = path.join(os.tmpdir(), `lynkeus-headless-${process.pid}.log`);
+    const logStream = fs.createWriteStream(logFile);
+    logStream.on('error', () => { });
+    host.once('exit', () => logStream.end());
     let output = '';
     const tail = (n) => output.trim().split('\n').slice(-n).join(' · ');
+    // `headless start` ends a crash with what it usually means; without that, the error line jest printed.
+    const why = () => {
+        const plain = stripVTControlCharacters(output);
+        const explained = plain.split('lynkeus: what this looks like')[1];
+        if (explained)
+            return explained
+                .trim()
+                .split('\n')
+                .map((line) => line.trim())
+                .join(' · ');
+        // Jest prints a suite that throws while loading as "● Test suite failed to run", then the thrown message.
+        const thrown = plain.match(/Test suite failed to run\s*\n\s*\n?\s*(\S.*)$/m)?.[1]?.trim();
+        return thrown ?? plain.match(/^\s*(\w*Error\b.*|Cannot find module.*)$/m)?.[1]?.trim() ?? tail(3);
+    };
     await new Promise((resolve, reject) => {
         const settle = (error) => {
             clearTimeout(timer);
@@ -36,17 +58,18 @@ const startHost = async (root, err) => {
         };
         const timer = setTimeout(() => settle(new Error(`the host did not come up within 180 s: ${tail(3)}`)), 180_000);
         const read = (chunk) => {
+            logStream.write(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)}`)));
+        // A suite that fails to load exits right after printing why, so its explanation is read in full here.
+        host.once('exit', (code) => settle(new Error(`${/Test suite failed/.test(output) ? 'the host failed to start' : `the host exited (${code})`}: ${why()}`)));
     });
-    err('host: up');
+    // The listeners above stay: the log takes all the host prints until it stops.
+    err(`host: up (its log: ${logFile})`);
     return host;
 };
 const stopGroup = (pid) => {
@@ -101,19 +124,27 @@ const idleShare = async () => {
     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, home, casesDir) => {
+/** Every case under a directory and its subdirectories, in path order, so a suite can group its cases in folders. */
+const casesIn = (dir) => fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => !e.name.startsWith('.') && e.name !== 'node_modules')
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((e) => {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory())
+        return casesIn(full);
+    return e.name.endsWith('.md') && !/^(README|FORMAT|CATALOG)\.md$/i.test(e.name) ? [full] : [];
+});
+/** The case files named (a directory stands for every case under it), or every case under the cases directory; a sentence when there are none. */
+export const caseFiles = (args, home, casesDir) => {
     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`;
+    const named = args.map((f) => path.resolve(f));
+    const missing = named.find((f) => !fs.existsSync(f));
+    if (missing)
+        return `no such case file: ${path.relative(process.cwd(), missing) || missing}`;
+    const files = named.length ? named.flatMap((f) => (fs.statSync(f).isDirectory() ? casesIn(f) : [f])) : fs.existsSync(dir) ? casesIn(dir) : [];
+    const where = named.length === 1 ? path.relative(home, named[0]) : path.relative(home, dir);
+    return files.length > 0 ? files : `no cases under ${where || '.'}; \`lynkeus case init\` writes one`;
 };
 /**
  * Runs the setups of `cases` ahead of them, in order, `jobs` at a time: never more than `limit` waiting
@@ -165,15 +196,41 @@ const spawnHost = (command, port, job, cwd) => spawn('/bin/sh', ['-c', command.r
     detached: true,
 });
 /** A run that could not be uploaded still ran: the failure is said, not raised. */
-const pushed = async (dir, to, project) => {
+// A run that kept evidence but none of a kind says so when it ends, not only as a gap in the report.
+export const missingEvidence = (reports, asked) => {
+    if (reports.length === 0)
+        return [];
+    const steps = reports.flatMap((r) => r.steps);
+    const fromApp = steps.some((s) => s.sent?.some((e) => e.via !== 'server')) || reports.some((r) => (r.events?.length ?? 0) > 0);
+    return [
+        ...(fromApp ? [] : ['⚠ no case kept an analytics event from the app (the agent keeps the calls that reach Mixpanel, AppsFlyer and Firebase Analytics).']),
+        ...(asked.video && !reports.some((r) => r.video)
+            ? ['⚠ --video kept no film: this host does not film (fastsim does; a simulator, an emulator or headless keep frames only).']
+            : []),
+    ];
+};
+const pushed = async (dir, to, project, err, afterPush = 'keep') => {
     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');
+        const run = await pushRun(dir, { ...to, project, onReady: (url) => err(`report: ${url} (its frames are on their way)`), onProgress: err });
+        return [
+            `report: ${run.url}${run.refused.length ? ` (not kept on this plan: ${run.refused.join(', ')})` : ''}`,
+            ...describeChanges(run.changes),
+            keptOrDeleted(dir, afterPush, run.refused.length === 0),
+        ].join('\n');
     }
     catch (error) {
         return `the report was not uploaded: ${error.message}`;
     }
 };
+// After a push: the folder deleted when the config asks and the service took every file, else how much it holds.
+export const keptOrDeleted = (dir, afterPush, complete) => {
+    const bytes = sizeOf(dir);
+    if (afterPush === 'delete' && complete) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        return `run folder deleted after the push (${megabytes(bytes)})`;
+    }
+    return `run folder: ${megabytes(bytes)} on disk${afterPush === 'delete' ? ', kept because some files were not taken' : ''} · \`lynkeus report prune ${path.dirname(dir)} --older 7d\` frees old ones`;
+};
 export const caseCommands = [
     define({
         name: 'case run',
@@ -189,7 +246,32 @@ export const caseCommands = [
             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' },
+            'no-app-events': {
+                type: 'boolean',
+                help: "with --out: leave the app's own event list unread. Reading it can turn on the app's tracking debug, which may draw on the screen; frames two runs compare should not have it",
+            },
             screenshots: { type: 'boolean', help: 'with --out: a frame of the screen after every step of the app' },
+            settle: {
+                type: 'number',
+                help: 'with --screenshots: how long the screen must stay still before a frame, in ms; 700 for frames two runs can be compared by',
+                default: 150,
+                value: 'ms',
+            },
+            'frames-on-change': {
+                type: 'boolean',
+                help: 'with --screenshots: a step that only looks (app.see, app.wait) on an unchanged screen shares the last frame',
+            },
+            still: {
+                type: 'number',
+                help: 'with --screenshots, on a simulator or emulator: take each frame again until two in a row match, this many ms apart (a native transition the agent cannot see)',
+                value: 'ms',
+            },
+            frames: {
+                type: 'string',
+                help: "with --screenshots: avif, the default and a few percent of the bytes (a simulator's or emulator's PNG is encoded again), or png, exact, only for frames two runs are compared by pixel for pixel",
+                default: 'avif',
+                value: 'avif|png',
+            },
             video: { type: 'boolean', help: 'with --out: film each case, where the host films (the step says at what second it began)' },
             traces: {
                 type: 'boolean',
@@ -199,6 +281,7 @@ export const caseCommands = [
             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' },
+            'video-scale': { type: 'number', help: 'pixels per point of the film, where the host takes one (fastsim: 1 to 3, 2 unless told)', 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 },
@@ -215,7 +298,32 @@ export const caseCommands = [
         },
         needs: 'nothing',
         session: false,
-        mcp: false,
+        mcp: 'core',
+        mcpOmit: [
+            'seen',
+            'report',
+            'events',
+            'settle',
+            'still',
+            'frames-on-change',
+            'frames',
+            'traces',
+            'traces-port',
+            'video-fps',
+            'video-scale',
+            'flakes',
+            'prepared',
+            'jobs',
+            'ports',
+            'host-command',
+            'in-order',
+            'ahead',
+            'idle',
+            'continue',
+            'video',
+            'project',
+        ],
+        mcpDetails: 'Runs case files (default: all in cases.dir) against the attached app, or with `host` in Node. A case that fails comes back with its screen and reason. `out` + `screenshots` + `push` uploads the run and prints its address.',
         run: async (ctx) => {
             const config = ctx.config.cases ?? {};
             const home = config.base ?? ctx.root;
@@ -238,12 +346,18 @@ export const caseCommands = [
                 ? {
                     dir: out.evidenceDir(id, attempt),
                     screenshots: !!ctx.flags.screenshots,
-                    ...(ctx.flags.video ? { video: { fps: Number(ctx.flags['video-fps'] ?? 30) } } : {}),
+                    settleMs: Number(ctx.flags.settle ?? 150),
+                    ...(ctx.flags.still ? { stillMs: Number(ctx.flags.still) } : {}),
+                    ...(ctx.flags['frames-on-change'] ? { onChange: true } : {}),
+                    frames: ctx.flags.frames === 'png' ? 'png' : 'avif',
+                    ...(ctx.flags.video
+                        ? { video: { fps: Number(ctx.flags['video-fps'] ?? 30), ...(ctx.flags['video-scale'] ? { scale: Number(ctx.flags['video-scale']) } : {}) } }
+                        : {}),
                 }
                 : 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 events = typeof ctx.flags.events === 'string' || (out !== undefined && !ctx.flags['no-app-events']);
             const claimed = dry
                 ? undefined
                 : claimPorts(typeof ctx.flags.ports === 'string'
@@ -297,6 +411,14 @@ export const caseCommands = [
                 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 };
+                // One simulator or emulator, one log: with several jobs a line could not be told to its case.
+                const native = out && jobs === 1 && !hostCommand && !ctx.flags.host && ctx.config.app
+                    ? await ctx
+                        .device()
+                        .then((d) => d.resolved())
+                        .then((info) => startNativeLogs(info, ctx.config.app))
+                        .catch(() => undefined)
+                    : undefined;
                 // 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']) {
@@ -354,6 +476,7 @@ export const caseCommands = [
                                         continue: !!ctx.flags.continue,
                                         routes: seenDir ? (host ? 'fresh' : true) : false,
                                         traces,
+                                        nativeLogs: native,
                                     });
                                     if (seenDir && report.result === 'passed' && report.routes?.length) {
                                         fs.mkdirSync(seenDir, { recursive: true });
@@ -402,6 +525,7 @@ export const caseCommands = [
                 await preparing;
                 if (out)
                     out.finish({ platform: seen?.platform, native: seen?.native });
+                native?.stop();
             }
             finally {
                 stop();
@@ -409,12 +533,17 @@ export const caseCommands = [
             const count = (result) => reports.filter((r) => r.result === result).length;
             const unsupported = count('unsupported');
             const summary = [
-                ...reports.map((r) => `${{ passed: '✅', failed: '❌', unsupported: '🚫' }[r.result]} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}`),
+                ...reports.map((r) => `${{ passed: '✅', failed: '❌', unsupported: '🚫' }[r.result]} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}` +
+                    // In a session or over MCP the caller reads this answer and nothing else: a case that did not pass brings its steps.
+                    (ctx.attached && r.result !== 'passed' ? `\n${describe(r)}` : '')),
                 `${count('passed')}/${reports.length} passed${unsupported ? `, ${unsupported} cannot run on this host` : ''}`,
+                // Its full path: a relative --out resolves against where the CLI was started, which over MCP is the app's folder.
+                ...(out ? [`run kept in ${path.resolve(ctx.flags.out)}`] : []),
+                ...(out ? missingEvidence(reports, { video: !!ctx.flags.video }) : []),
                 ...(ledger ? ledger.flaky(reports.map((r) => r.id)) : []),
                 ...(reportsTo && out
                     ? [
-                        await pushed(path.resolve(ctx.flags.out), reportsTo, typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root)),
+                        await pushed(path.resolve(ctx.flags.out), reportsTo, typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root), ctx.err, ctx.config.report?.afterPush === 'delete' ? 'delete' : 'keep'),
                     ]
                     : []),
             ].join('\n');
@@ -473,7 +602,7 @@ export const caseCommands = [
         flags: { force: { type: 'boolean', help: 'overwrite what is there' } },
         needs: 'nothing',
         session: false,
-        mcp: false,
+        mcp: 'core',
         run: async (ctx) => {
             const dir = path.resolve(ctx.root, ctx.config.cases?.dir ?? 'cases');
             fs.mkdirSync(dir, { recursive: true });

package/lib/commands/ci.d.ts

@@ -0,0 +1,13 @@
+/** The case results of a run folder, by each case's last attempt. */
+export declare const resultsOf: (dir: string) => {
+    id: string;
+    result: string;
+    title?: string;
+}[];
+/** The summary a CI job shows: how many passed, which failed, and the report. */
+export declare const summaryOf: (results: {
+    id: string;
+    result: string;
+    title?: string;
+}[], report: string | undefined, picked: string) => string;
+export declare const ciCommands: import("../registry.js").Command[];

package/lib/commands/ci.js

@@ -0,0 +1,184 @@
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { coverageOf, impactOf, readSeen } from '../cases/coverage.js';
+import { readCases } from '../cases/format.js';
+import { screensAffectedBy } from '../knowledge/query.js';
+import { define } from '../registry.js';
+import { caseFiles } from './cases.js';
+import { changedSources } from './map.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The case results of a run folder, by each case's last attempt. */
+export const resultsOf = (dir) => {
+    const file = path.join(dir, 'cases.jsonl');
+    if (!fs.existsSync(file))
+        return [];
+    const last = new Map();
+    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        const c = JSON.parse(line);
+        last.set(c.id, c);
+    }
+    return [...last.values()];
+};
+/** The summary a CI job shows: how many passed, which failed, and the report. */
+export const summaryOf = (results, report, picked) => {
+    const failed = results.filter((r) => r.result === 'failed');
+    const passed = results.filter((r) => r.result === 'passed').length;
+    return [
+        `### lynkeus: ${passed}/${results.length} cases passed${failed.length ? `, ${failed.length} failed` : ''}`,
+        '',
+        picked,
+        ...(report ? ['', `[Open the report](${report})`] : []),
+        ...(failed.length ? ['', '| Failed | |', '|---|---|', ...failed.map((f) => `| \`${f.id}\` | ${f.title ?? ''} |`)] : []),
+        '',
+    ].join('\n');
+};
+const waitFor = async (ok, timeoutMs, every = 3000) => {
+    const until = Date.now() + timeoutMs;
+    for (;;) {
+        if (await ok())
+            return true;
+        if (Date.now() > until)
+            return false;
+        await sleep(every);
+    }
+};
+export const ciCommands = [
+    define({
+        name: 'ci',
+        group: 'runs',
+        summary: 'Run the suite the way a CI job does: bring the backend and N hosts up, run the cases across them, report, tear down',
+        details: 'Reads `ci` in lynkeus.config.json: `backend.up` / `backend.down` (the project’s commands; lynkeus knows no backend) and `backend.ready` (a URL to wait for), `hosts.count` and `hosts.command` (default: a headless host; `{port}` is where it dials), `push`, and extra `run` flags. --affected runs only the cases a branch’s changes reach (as `case impact` finds them). Writes the job summary to $GITHUB_STEP_SUMMARY when it is set. The exit code is the suite’s.',
+        flags: {
+            affected: { type: 'boolean', help: 'only the cases the changes against --base reach' },
+            base: { type: 'string', help: 'git ref --affected diffs against', default: 'origin/main', value: 'ref' },
+            jobs: { type: 'number', help: 'how many hosts and jobs (default ci.hosts.count, else 2)', value: 'n' },
+            out: { type: 'string', help: 'where the run goes', default: 'lynkeus-run', value: 'dir' },
+            'keep-up': { type: 'boolean', help: 'leave the backend and the hosts up afterwards' },
+            'dry-run': { type: 'boolean', help: 'say what it would do and run nothing' },
+        },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const ci = ctx.config.ci ?? {};
+            const config = ctx.config.cases ?? {};
+            const home = config.base ?? ctx.root;
+            const self = process.argv[1];
+            const say = (line) => ctx.err(`▸ ${line}`);
+            const jobs = Math.max(1, Number(ctx.flags.jobs ?? ci.hosts?.count ?? 2));
+            const out = path.resolve(ctx.root, String(ctx.flags.out));
+            // Which cases: all, or the ones the branch's changes reach.
+            const all = caseFiles([], home, config.dir);
+            if (typeof all === 'string')
+                return { text: all, code: 1 };
+            let files = all;
+            let picked = `All ${all.length} case files.`;
+            if (ctx.flags.affected) {
+                const graphFile = path.join(ctx.root, '.lynkeus', 'graph.json');
+                if (!fs.existsSync(graphFile))
+                    spawnSync(process.execPath, [self, 'map', 'build'], { cwd: ctx.root, stdio: 'inherit' });
+                const cases = all.flatMap(readCases);
+                const graph = ctx.graph();
+                const coverage = coverageOf(cases, Object.keys(graph.screens).sort(), readSeen(path.join(ctx.root, '.lynkeus', 'seen')));
+                const changed = changedSources(ctx.root, String(ctx.flags.base), ctx.err);
+                const impact = impactOf(screensAffectedBy(graph, changed), coverage);
+                files = [...new Set(impact.cases.map((c) => c.file))];
+                picked = `${files.length} of ${all.length} case files: the ones the ${changed.length} changed source file(s) against ${ctx.flags.base} reach.`;
+                if (files.length === 0) {
+                    if (process.env.GITHUB_STEP_SUMMARY)
+                        fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `### lynkeus: no case to run\n\n${picked}\n`);
+                    return { text: `no case to run: ${picked}`, json: { files } };
+                }
+            }
+            const ports = Array.from({ length: jobs }, (_, i) => 8123 + i);
+            const hostCommand = ci.hosts?.command ?? `LYNKEUS_PORT={port} "${process.execPath}" "${self}" headless start`;
+            const runArgs = [
+                'case',
+                'run',
+                ...files,
+                '--jobs',
+                String(jobs),
+                '--ports',
+                ports.join(','),
+                '--out',
+                out,
+                '--screenshots',
+                ...(ci.push ? ['--push'] : []),
+                ...(ci.run ?? []),
+            ];
+            if (ctx.flags['dry-run']) {
+                const plan = [
+                    picked,
+                    ci.backend ? `backend: \`${ci.backend.up}\`${ci.backend.ready ? `, ready at ${ci.backend.ready}` : ''}` : 'backend: none declared (ci.backend)',
+                    `hosts: ${jobs} × \`${hostCommand}\` on ${ports.join(', ')}`,
+                    `run: lynkeus ${runArgs.slice(0, 2).join(' ')} … ${runArgs.slice(2 + files.length).join(' ')}`,
+                ];
+                return { text: plan.join('\n'), json: { files, ports, hostCommand, runArgs } };
+            }
+            const hosts = [];
+            const down = () => {
+                if (ctx.flags['keep-up'])
+                    return say('left up (--keep-up)');
+                for (const h of hosts)
+                    if (h.pid)
+                        try {
+                            process.kill(-h.pid, 'SIGTERM');
+                        }
+                        catch { }
+                if (ci.backend?.down) {
+                    say('backend down');
+                    spawnSync('/bin/sh', ['-c', ci.backend.down], { cwd: ctx.root, stdio: 'inherit' });
+                }
+            };
+            try {
+                if (ci.backend) {
+                    say(`backend up: ${ci.backend.up}`);
+                    const up = spawnSync('/bin/sh', ['-c', ci.backend.up], { cwd: ctx.root, stdio: 'inherit' });
+                    if (up.status !== 0)
+                        return { text: `the backend did not come up (\`${ci.backend.up}\` exited ${up.status})`, code: 1 };
+                    if (ci.backend.ready) {
+                        const url = ci.backend.ready;
+                        say(`waiting for ${url}`);
+                        const ready = await waitFor(() => fetch(url).then((r) => r.ok, () => false), ci.backend.timeoutMs ?? 300_000);
+                        if (!ready)
+                            return { text: `${url} never answered`, code: 1 };
+                    }
+                }
+                say(`${jobs} host${jobs === 1 ? '' : 's'}: ${hostCommand}`);
+                for (const port of ports)
+                    hosts.push(spawn('/bin/sh', ['-c', hostCommand.replaceAll('{port}', String(port))], { cwd: ctx.root, stdio: ['pipe', 'ignore', 'ignore'], detached: true }));
+                // A host compiles the app before it answers: the slow part.
+                for (const port of ports) {
+                    const answered = () => spawnSync(process.execPath, [self, 'screen'], {
+                        cwd: ctx.root,
+                        env: { ...process.env, LYNKEUS_PORT: String(port) },
+                        stdio: 'ignore',
+                        timeout: 20_000,
+                    }).status === 0;
+                    if (!(await waitFor(answered, ci.hosts?.timeoutMs ?? 600_000, 5000)))
+                        return { text: `the host on ${port} never attached`, code: 1 };
+                    say(`host on ${port} ready`);
+                }
+                say(`running ${files.length} case file(s) on ${jobs} host(s)`);
+                const run = spawnSync(process.execPath, [self, ...runArgs], {
+                    cwd: ctx.root,
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'inherit'],
+                    maxBuffer: 64 * 1024 * 1024,
+                });
+                process.stdout.write(run.stdout ?? '');
+                const report = /report: (https?:\/\/\S+)/.exec(run.stdout ?? '')?.[1];
+                const summary = summaryOf(resultsOf(out), report, picked);
+                if (process.env.GITHUB_STEP_SUMMARY)
+                    fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
+                return { text: summary, code: run.status ?? 1 };
+            }
+            finally {
+                down();
+            }
+        },
+    }),
+];

package/lib/commands/coverage.d.ts

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