lynkeus 0.3.0 → 0.4.0

package/lib/cases/runner.d.ts

@@ -90,8 +90,10 @@ export type CaseReport = {
 export type Evidence = {
     dir: string;
     screenshots?: boolean;
+    settleMs?: number;
     video?: {
         fps: number;
+        scale?: number;
     };
 };
 export type RunOptions = {

package/lib/cases/runner.js

@@ -379,8 +379,12 @@ export const runCase = async (c, options) => {
                     if (await scrollTo(async () => (await seen(params)) === undefined))
                         return;
                 }
-                else
-                    await d.waitFor({ target: what, timeoutMs: 20_000 }).catch(() => undefined);
+                else {
+                    // A step that names its own timeout gets no more than what is left of it; one that does not may
+                    // wait for a carousel to come round.
+                    const long = typeof params.timeoutMs === 'number' ? Math.max(0, deadline - Date.now()) : 20_000;
+                    await d.waitFor({ target: what, timeoutMs: long }).catch(() => undefined);
+                }
                 continue;
             }
             if (Date.now() > deadline && Date.now() < hard && (await (await device()).screen()).busy) {
@@ -733,7 +737,8 @@ export const runCase = async (c, options) => {
     let filming = false;
     if (film && evidence?.video) {
         const d = await device();
-        filming = await d.command('record', { path: film, fps: evidence.video.fps }).then(() => true, () => false);
+        // A host that films at one size only ignores the scale.
+        filming = await d.command('record', { path: film, fps: evidence.video.fps, ...(evidence.video.scale ? { scale: evidence.video.scale } : {}) }).then(() => true, () => false);
     }
     // What the app sent before the case began is not the case's.
     if (capturing)
@@ -760,9 +765,11 @@ export const runCase = async (c, options) => {
         if (evidence?.screenshots) {
             // A step may end mid-transition (a screen fading in, the splash fading out): the frame is of where the
             // step left the app, so two runs' frames of the same step show the same screen.
-            // Long enough for what arrives after a short delay; a screen that never settles (an animation that
-            // keeps going) is noted as such, and its frame is of a moment, not of a state.
-            const settled = await d.idle({ quietMs: 700, timeoutMs: 3000 }).then((r) => r.idle, () => false);
+            // A screen that never settles (an animation that keeps going) is noted as such, and its frame is of a
+            // moment, not of a state. The wait is paid on every step: short for a report, and long enough for what
+            // arrives after a short delay (700 ms) where two runs' frames are compared pixel by pixel.
+            const quietMs = evidence.settleMs ?? 150;
+            const settled = await d.idle({ quietMs, timeoutMs: Math.max(1000, quietMs * 4) }).then((r) => r.idle, () => false);
             const file = path.join(evidence.dir, `${String(index).padStart(2, '0')}-${report.step
                 .toLowerCase()
                 .replace(/[^a-z0-9]+/g, '-')

package/lib/cli.js

@@ -10,7 +10,7 @@ import { mapCommands } from './commands/map.js';
 import { osCommands } from './commands/os.js';
 import { reportCommands } from './commands/report.js';
 import { runsCommands } from './commands/runs.js';
-import { graphFile, loadConfig, loadGraph, portFromEnv } from './config.js';
+import { graphFile, loadConfig, loadGraph, portFromEnv, readToken } from './config.js';
 import { agentMismatch } from './device/agentVersion.js';
 import { HEADLESS_HOST, pickAgentDevice, pickAndroidDevice } from './device/devices.js';
 import { Device } from './device/driver.js';
@@ -51,7 +51,7 @@ 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 told = mismatchTold ? undefined : agentMismatch(hello);
             if (!told)

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';
@@ -26,6 +27,18 @@ const startHost = async (root, err) => {
     });
     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(' · ');
+        return plain.match(/^\s*(\w*Error\b.*|Cannot find module.*)$/m)?.[1]?.trim() ?? tail(3);
+    };
     await new Promise((resolve, reject) => {
         const settle = (error) => {
             clearTimeout(timer);
@@ -39,12 +52,11 @@ const startHost = async (root, err) => {
             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');
     return host;
@@ -190,6 +202,12 @@ export const caseCommands = [
             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' },
+            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',
+            },
             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 +217,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 +234,29 @@ export const caseCommands = [
         },
         needs: 'nothing',
         session: false,
-        mcp: false,
+        mcp: 'core',
+        mcpOmit: [
+            'seen',
+            'report',
+            'events',
+            'settle',
+            '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,7 +279,10 @@ 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.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'));
@@ -409,7 +453,9 @@ 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` : ''}`,
                 ...(ledger ? ledger.flaky(reports.map((r) => r.id)) : []),
                 ...(reportsTo && out
@@ -473,7 +519,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/doctor.js

@@ -73,6 +73,12 @@ const PATTERNS = [
     { re: /requireNativeComponent\s*(?:<[^>]*>)?\(\s*['"]([^'"]+)['"]/g, how: 'requireNativeComponent' },
     { re: /codegenNativeComponent\s*<[^>]*>\(\s*['"]([^'"]+)['"]/g, how: 'codegenNativeComponent' },
 ];
+/**
+ * The text with its comments blanked, lines kept where they were: a mock or a native module named in a comment
+ * (the generated entry shows `jest.mock('some-native-package', …)` as an example) is neither. Only comments that
+ * own their line are taken, so a `//` inside a string (a URL) stays.
+ */
+const withoutComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, ' ')).replace(/^[ \t]*\/\/.*$/gm, '');
 const scanNativeRefs = (root) => {
     const files = [];
     for (const d of SCAN_DIRS)
@@ -81,7 +87,7 @@ const scanNativeRefs = (root) => {
     for (const file of files) {
         let text;
         try {
-            text = fs.readFileSync(file, 'utf8');
+            text = withoutComments(fs.readFileSync(file, 'utf8'));
         }
         catch {
             continue;
@@ -104,7 +110,7 @@ const entryMocks = (root, entry) => {
     const entryPath = path.join(root, entry);
     let text = '';
     try {
-        text = fs.readFileSync(entryPath, 'utf8');
+        text = withoutComments(fs.readFileSync(entryPath, 'utf8'));
     }
     catch {
         return { specs, files };

package/lib/commands/headless.js

@@ -1,11 +1,11 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { lynkeusDir, portFromEnv } from '../config.js';
+import { lynkeusDir, portFromEnv, readToken } from '../config.js';
 import { describeExplanations, explainError } from '../knowledge/errors.js';
 import { define } from '../registry.js';
 import { doctor } from './doctor.js';
-import { init, mountAgent } from './init.js';
+import { headlessMissing, init, installAgent, installHeadless, jestPreset, mountAgent, setupChecks } from './init.js';
 const ENTRY_FLAG = { entry: { type: 'string', help: 'the headless entry (or `entry` in lynkeus.config.json)', value: 'file' } };
 const entryOf = (ctx) => ctx.flags.entry ?? ctx.config.entry ?? 'qa/headless.tsx';
 /** The jest test that hosts the app. The port is written in, not read from the environment there: babel would inline the first run's value into jest's transform cache. */
@@ -27,34 +27,139 @@ import * as entry from '${entryImport}';
 hostApp(() => <entry.App />, { ${options.join(', ')} });
 `;
 };
+const JEST_CONFIGS = ['jest.config.js', 'jest.config.cjs', 'jest.config.mjs', 'jest.config.ts', 'jest.config.json'];
+// React Native and most of what an app adds to it ship untranspiled ES modules, which jest leaves alone unless told.
+const apiFromConfig = (config) => (config.apiUrl ? { [config.apiEnv ?? 'API_URL']: config.apiUrl } : {});
+const TRANSFORM_PACKAGES = '((jest-)?react-native[^/]*|@react-native[^/]*|@react-navigation|react-navigation|expo(nent)?|@expo(nent)?/.*|expo-.*|@unimodules|unimodules|@shopify|@gorhom|@sentry/react-native|lynkeus-[^/]+|yoga-layout|@testing-library|immer|@reduxjs/toolkit|react-redux|redux|reselect|@expo-google-fonts|native-base|standard-navigation)';
+/**
+ * The import aliases in tsconfig.json's `paths`, as jest mappings, the longest first: \`@/assets/*\` has to be
+ * tried before \`@/*\`, which jest-expo does not do. The bundler reads them; jest knows nothing of them.
+ */
+const aliasesOf = (root) => {
+    let options;
+    try {
+        const text = fs.readFileSync(path.join(root, 'tsconfig.json'), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+        options = JSON.parse(text).compilerOptions;
+    }
+    catch {
+        return {};
+    }
+    const base = path.join(root, options?.baseUrl ?? '.');
+    const literal = (text) => text.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    return Object.fromEntries(Object.entries(options?.paths ?? {})
+        .filter(([alias, [target]]) => alias.endsWith('/*') && target?.endsWith('/*'))
+        .sort(([a], [b]) => b.length - a.length)
+        .map(([alias, [target]]) => [`^${literal(alias.slice(0, -1))}(.*)$`, `${path.join(base, target.slice(0, -1))}$1`]));
+};
+/**
+ * What jest is told when the app has not said it itself, so an app with no jest set up runs headless as it is:
+ * the preset its framework needs (jest-expo for Expo, React Native's otherwise), and which packages under node_modules to transpile.
+ */
+const jestDefaults = (root) => {
+    const file = JEST_CONFIGS.find((f) => fs.existsSync(path.join(root, f)));
+    let config = file ? fs.readFileSync(path.join(root, file), 'utf8') : '';
+    if (!file) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+            config = manifest.jest ? JSON.stringify(manifest.jest) : '';
+        }
+        catch { }
+    }
+    const flags = [];
+    if (!config) {
+        // A style sheet imported from native code (Expo's templates import global.css) means nothing to jest, even
+        // behind an alias, so it is mapped first. Jest merges these with the preset's own mappings.
+        const stub = path.join(lynkeusDir(root), 'style-stub.js');
+        fs.mkdirSync(path.dirname(stub), { recursive: true });
+        fs.writeFileSync(stub, 'module.exports = {};\n');
+        flags.push('--preset', jestPreset(root), `--moduleNameMapper=${JSON.stringify({ '\\.(css|less|sass|scss)$': stub, ...aliasesOf(root) })}`);
+    }
+    // Two that must stay as they are, as jest-expo leaves them: babel running itself, or Reanimated's plugin, fails.
+    if (!config.includes('transformIgnorePatterns'))
+        flags.push(`--transformIgnorePatterns=node_modules/(?!${TRANSFORM_PACKAGES}/)`, '--transformIgnorePatterns=/node_modules/react-native-reanimated/plugin/', '--transformIgnorePatterns=/node_modules/@react-native/babel-preset/');
+    return flags;
+};
 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)",
+        summary: "Set lynkeus up in this app: install the agent, mount it from the app's entry, make the project's token",
+        details: 'React Native or Expo (an Expo Router app gets an entry of its own). Safe to run again: it changes only what is missing. The agent has native code, so the app is built again afterwards (`npx react-native run-ios`, `npx expo run:ios`) and Metro restarted with `--reset-cache`; `lynkeus status` says what is left.',
+        flags: { 'no-install': { type: 'boolean', help: 'do not add lynkeus-agent to the app; mount it only' } },
         needs: 'nothing',
+        mcp: 'core',
         run: async (ctx) => {
-            const lines = mountAgent(ctx.root);
+            const lines = [...(ctx.flags['no-install'] ? [] : [installAgent(ctx.root)]), ...mountAgent(ctx.root)];
+            lines.push('next: build the app again and open it, then `lynkeus status` (over MCP: the status tool) to see that it attaches');
             return { text: lines.join('\n'), json: lines };
         },
     }),
+    define({
+        name: 'status',
+        group: 'drive',
+        summary: 'What this project has of lynkeus and what is missing: the agent, the token, a running app, cases, the reports key',
+        details: 'The first thing to call in a project you do not know: each line that fails says what fixes it. `--offline` skips waiting for the app.',
+        flags: { offline: { type: 'boolean', help: 'check the files only; do not wait for a running app' } },
+        needs: 'nothing',
+        mcp: 'core',
+        run: async (ctx) => {
+            const checks = setupChecks(ctx.root);
+            const ready = checks.every((c) => c.ok);
+            if (ready && !ctx.flags.offline) {
+                try {
+                    const device = await ctx.device();
+                    checks.push({ what: `an app is attached (${device.info.name})`, ok: true });
+                }
+                catch {
+                    checks.push({
+                        what: 'an app is attached',
+                        ok: false,
+                        fix: 'open a development build made after `lynkeus init`, with Metro restarted (`--reset-cache`); or `lynkeus headless start` for no simulator',
+                    });
+                }
+            }
+            const unloadable = headlessMissing(ctx.root);
+            checks.push({
+                what: unloadable.length ? 'the app can run headless, in Node with no simulator' : 'the app can run headless (jest, Testing Library, lynkeus-headless)',
+                ok: !unloadable.length && fs.existsSync(path.join(ctx.root, entryOf(ctx))),
+                fix: '`lynkeus headless init` installs what it needs and writes its entry; optional',
+            });
+            const dir = path.resolve(ctx.config.cases?.base ?? ctx.root, ctx.config.cases?.dir ?? 'cases');
+            const cases = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !/^(README|FORMAT|CATALOG)\.md$/i.test(f)).length : 0;
+            checks.push({
+                what: cases ? `${cases} case${cases === 1 ? '' : 's'} in ${path.relative(ctx.root, dir) || '.'}` : 'cases to run',
+                ok: cases > 0,
+                fix: '`lynkeus case init` writes an example and the format',
+            });
+            checks.push({
+                what: 'runs can be pushed to the reports service',
+                ok: !!process.env.LYNKEUS_REPORTS_KEY,
+                fix: 'set LYNKEUS_REPORTS_KEY to an API key of your organization (lynkeus.io, API keys); optional',
+            });
+            const text = checks.map((c) => `${c.ok ? '✓' : '✗'} ${c.what}${c.ok || !c.fix ? '' : ` — ${c.fix}`}`).join('\n');
+            return { text, json: checks };
+        },
+    }),
     define({
         name: 'headless start',
         group: 'headless',
         summary: 'Host the app in Node (jest + RNTL) and wait for a driver; same protocol, no simulator',
-        details: 'Needs LYNKEUS_TOKEN in the environment (the value the app reads for its token). LYNKEUS_PORT moves the host and its driver together; LYNKEUS_HOST says where the driver is listening, for a host that is not in the same place as its driver (a container dialling out, say). Arguments after `--` go to jest. When the host crashes, the last lines say what the error usually means.',
+        details: "Needs the project's token: the one `lynkeus init` wrote to .lynkeus/token, or LYNKEUS_TOKEN in the environment. The app's API base comes from the environment variable `apiEnv` names, or else from `apiUrl` in lynkeus.config.json. LYNKEUS_PORT moves the host and its driver together; LYNKEUS_HOST says where the driver is listening, for a host that is not in the same place as its driver (a container dialling out, say). Arguments after `--` go to jest. When the host crashes, the last lines say what the error usually means.",
         flags: ENTRY_FLAG,
         aliases: ['headless'],
         needs: 'nothing',
         session: false,
         mcp: false,
         run: async (ctx) => {
-            const token = process.env.LYNKEUS_TOKEN;
+            const token = readToken(ctx.root);
             if (!token)
                 return {
-                    text: 'lynkeus headless needs LYNKEUS_TOKEN in the environment (the same value the app reads for its token): a hosted app talks to a real backend, and without one any local process could drive it.',
+                    text: 'lynkeus headless needs a token (`lynkeus init` makes one in .lynkeus/token, or set LYNKEUS_TOKEN): a hosted app talks to a real backend, and without one any local process could drive it.',
                     code: 1,
                 };
+            const missing = headlessMissing(ctx.root);
+            if (missing.length)
+                return { text: `lynkeus headless runs the app under jest and needs ${missing.join(', ')}; \`lynkeus headless init\` installs them.`, code: 1 };
             const entry = entryOf(ctx);
             if (!fs.existsSync(path.join(ctx.root, entry)))
                 return { text: `No ${entry} in ${ctx.root}. \`lynkeus headless init\` writes one; it must export \`App\` and, optionally, \`navigation\`.`, code: 1 };
@@ -70,10 +175,10 @@ export const headlessCommands = [
             fs.writeFileSync(testFile, hostTest(rel.startsWith('.') ? rel : `./${rel}`, port, ctx.config, path.basename(ctx.root)));
             // Node resolves `localhost` to ::1 first; local backends usually listen on IPv4 only.
             const nodeOptions = [process.env.NODE_OPTIONS, '--dns-result-order=ipv4first'].filter(Boolean).join(' ');
-            const child = spawn('npx', ['jest', testFile, '--runInBand', '--watchAll=false', ...ctx.passthrough], {
+            const child = spawn('npx', ['jest', testFile, '--runInBand', '--watchAll=false', ...jestDefaults(ctx.root), ...ctx.passthrough], {
                 cwd: ctx.root,
                 stdio: ['inherit', 'inherit', 'pipe'],
-                env: { ...process.env, CI: '1', NODE_OPTIONS: nodeOptions },
+                env: { ...apiFromConfig(ctx.config), ...process.env, LYNKEUS_TOKEN: token, CI: '1', NODE_OPTIONS: nodeOptions },
             });
             let tail = '';
             child.stderr?.on('data', (chunk) => {
@@ -99,8 +204,12 @@ export const headlessCommands = [
             'api-env': { type: 'string', help: 'the env var the app reads its API base from', value: 'NAME' },
             auto: { type: 'boolean', help: 'also mount the agent from index.js with auto()' },
             force: { type: 'boolean', help: 'overwrite an existing entry' },
+            'no-install': { type: 'boolean', help: 'do not add jest, Testing Library and lynkeus-headless to the project' },
         },
         needs: 'nothing',
+        mcp: 'core',
+        mcpOmit: ['entry', 'auto', 'force'],
+        mcpDetails: 'Prepares the app to run in Node, no simulator: installs jest, Testing Library and lynkeus-headless, writes the entry. Then `case_run` with `host`.',
         run: async (ctx) => {
             const lines = init(ctx.root, {
                 entry: entryOf(ctx),
@@ -110,6 +219,8 @@ export const headlessCommands = [
                 force: !!ctx.flags.force,
                 locale: { ...ctx.config.locale, language: ctx.config.language },
             });
+            if (!ctx.flags['no-install'])
+                lines.unshift(installHeadless(ctx.root));
             return { text: lines.join('\n'), json: lines };
         },
     }),
@@ -123,6 +234,9 @@ export const headlessCommands = [
             explain: { type: 'string', help: 'turn a jest error into its usual cause and fix', value: 'text' },
         },
         needs: 'nothing',
+        mcp: 'core',
+        mcpOmit: ['entry'],
+        mcpDetails: 'Which native modules the app uses that nothing mocks yet, so the headless host would fail on them; `fix` writes stubs for them into the entry. `explain` turns the first line of a jest error into its cause.',
         run: async (ctx) => {
             if (ctx.flags.explain) {
                 const found = explainError(ctx.flags.explain);

package/lib/commands/init.d.ts

@@ -17,3 +17,26 @@ export type InitOptions = {
  */
 export declare const mountAgent: (root: string) => string[];
 export declare const init: (root: string, opts: InitOptions) => string[];
+/**
+ * What a failed install said, short enough for one line. npm ends its errors with where its logs are, so
+ * the last lines alone told nothing; the reason (a peer range that does not match, say) comes before them.
+ */
+export declare const installFailure: (ran: {
+    stderr?: string | null;
+    error?: Error;
+}) => string;
+/** Adds lynkeus-agent to the app when it is not a dependency yet. It has native code, so the app is built again after. */
+export declare const installAgent: (root: string) => string;
+export type SetupCheck = {
+    what: string;
+    ok: boolean;
+    fix?: string;
+};
+/** What a project has of lynkeus and what it still lacks, each with the one thing that fixes it. Reads files only. */
+export declare const setupChecks: (root: string) => SetupCheck[];
+/** The packages the headless host needs that this project cannot load yet. */
+export declare const headlessMissing: (root: string) => string[];
+/** The preset \`headless start\` gives jest when the app's own configuration names none. */
+export declare const jestPreset: (root: string) => string;
+/** Adds what the headless host needs as development dependencies; a line saying what happened. */
+export declare const installHeadless: (root: string) => string;