lynkeus 0.3.0 → 0.5.0

package/src/commands/coverage.ts

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { coverageOf, impactOf, readSeen } from '../cases/coverage.js';
+import { draftCase } from '../cases/draft.js';
+import { Fixtures } from '../cases/fixtures.js';
+import { readCases } from '../cases/format.js';
+import { edgesFile } from '../config.js';
+import * as edges from '../knowledge/edges.js';
+import { plan } from '../knowledge/plan.js';
+import { screensAffectedBy } from '../knowledge/query.js';
+import { type Base, define } from '../registry.js';
+import { caseFiles } from './cases.js';
+import { changedSources } from './map.js';
+
+// The project's cases and what they cover, read the way `case run` reads them.
+const coverageFor = (ctx: Base & { graph: () => { screens: Record<string, unknown> } }, seenFlag: unknown) => {
+  const config = ctx.config.cases ?? {};
+  const home = config.base ?? ctx.root;
+  const files = caseFiles([], home, config.dir);
+  if (typeof files === 'string') return files;
+  const cases = files.flatMap(readCases);
+  const seenDir = path.resolve(ctx.root, typeof seenFlag === 'string' ? seenFlag : '.lynkeus/seen');
+  return { cases, coverage: coverageOf(cases, Object.keys(ctx.graph().screens).sort(), readSeen(seenDir)) };
+};
+
+export const coverageCommands = [
+  define({
+    name: 'case coverage',
+    group: 'runs',
+    summary: 'Which of the app’s screens the cases touch, which none does, and which a case names that the app no longer has',
+    details:
+      'A screen counts as touched when a case goes to it (`app.nav`), waits for it (`app.wait`), checks it (`app.see: { route }`), or went through it on its last passing run (`case run --seen <dir>`, read from .lynkeus/seen unless --seen says where). The screens come from the route graph (`lynkeus map build`).',
+    flags: {
+      route: { type: 'string', help: 'only this screen: the cases that touch it', value: 'Route' },
+      seen: { type: 'string', help: 'where `case run --seen` kept the screens of passing cases (default .lynkeus/seen)', value: 'dir' },
+    },
+    needs: 'graph',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const read = coverageFor(ctx, ctx.flags.seen);
+      if (typeof read === 'string') return { text: read, code: 1 };
+      const { cases, coverage } = read;
+      if (typeof ctx.flags.route === 'string') {
+        const ids = coverage.byRoute[ctx.flags.route] ?? [];
+        return { text: `${ctx.flags.route}: ${ids.length ? ids.join(', ') : 'no case'}`, json: { route: ctx.flags.route, cases: ids } };
+      }
+      const pct = coverage.routes ? Math.round((100 * coverage.covered.length) / coverage.routes) : 0;
+      const top = Object.entries(coverage.byRoute)
+        .filter(([r]) => !coverage.unknown.includes(r))
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, 8);
+      const lines = [
+        `${coverage.covered.length} of ${coverage.routes} screens touched by a case (${pct}%), from ${cases.length} case${cases.length === 1 ? '' : 's'}`,
+        ...(top.length ? ['most covered:', ...top.map(([r, ids]) => `  ${r.padEnd(34)} ${ids.length}`)] : []),
+        ...(coverage.unknown.length
+          ? ['named by a case, unknown to the app (renamed? a typo?):', ...coverage.unknown.map((r) => `  ${r} ← ${coverage.byRoute[r]!.join(', ')}`)]
+          : []),
+        `${coverage.uncovered.length} screen${coverage.uncovered.length === 1 ? '' : 's'} no case touches${coverage.uncovered.length ? ':' : ''}`,
+        ...coverage.uncovered.slice(0, 30).map((r) => `  ${r}`),
+        ...(coverage.uncovered.length > 30 ? [`  … ${coverage.uncovered.length - 30} more (--json)`] : []),
+      ];
+      return { text: lines.join('\n'), json: coverage };
+    },
+  }),
+  define({
+    name: 'case impact',
+    group: 'runs',
+    summary: 'The cases a branch’s changes reach, to run only those, and the reached screens no case covers',
+    details:
+      'The screens the diff against --base touches or imports (as `map check` finds them), crossed with what each case covers (as `case coverage` finds it). --files prints one case file per line: `lynkeus case run $(lynkeus case impact --files)`.',
+    flags: {
+      base: { type: 'string', help: 'git ref to diff against', default: 'main', value: 'ref' },
+      depth: { type: 'number', help: 'how many imports away a change still reaches a screen', default: 4, value: 'n' },
+      seen: { type: 'string', help: 'where `case run --seen` kept the screens of passing cases (default .lynkeus/seen)', value: 'dir' },
+      files: { type: 'boolean', help: 'print only the case files, one per line' },
+    },
+    needs: 'graph',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const read = coverageFor(ctx, ctx.flags.seen);
+      if (typeof read === 'string') return { text: read, code: 1 };
+      const base = ctx.flags.base as string;
+      const changed = changedSources(ctx.root, base, ctx.err);
+      const affected = screensAffectedBy(ctx.graph(), changed, ctx.flags.depth as number);
+      const impact = impactOf(affected, read.coverage);
+      if (ctx.flags.files) return { text: [...new Set(impact.cases.map((c) => c.file))].join('\n'), json: impact };
+      const lines = [
+        `${changed.length} source file${changed.length === 1 ? '' : 's'} changed against ${base}; they reach ${new Set(affected.map((a) => a.route)).size} screen(s)`,
+        ...(impact.cases.length
+          ? [`cases to run (${impact.cases.length}):`, ...impact.cases.map((c) => `  ${c.id.padEnd(46)} ${c.routes.join(', ')} (via ${c.via})`)]
+          : ['no case touches them']),
+        ...(impact.untested.length ? [`reached, and touched by no case (${impact.untested.length}):`, ...impact.untested.map((r) => `  ${r}`)] : []),
+      ];
+      return { text: lines.join('\n'), json: { base, changed, ...impact } };
+    },
+  }),
+  define({
+    name: 'case new',
+    group: 'runs',
+    summary: 'Draft a case for a screen: the way there, the backend setup to pick from, and the checks left to write',
+    details:
+      'Prints a case to finish: the frontmatter with the questions a reader needs answered, the setup the project’s fixtures server offers (from `lynkeus.describe`, commented out: what state the case needs is the author’s call), the presses from --from (default `cases.start`) to the screen as `map plan` knows them, and the checks to write. --write saves it as <cases dir>/<id>.md, never over a file that is there.',
+    positionals: [{ name: 'id', help: 'the case id, which is also its file name', required: true }],
+    flags: {
+      to: { type: 'string', help: 'the screen the case is about', value: 'Route' },
+      from: { type: 'string', help: 'where it begins (default: cases.start in lynkeus.config.json)', value: 'Route' },
+      title: { type: 'string', help: 'what a person can do there, as the report will title it', value: 'text' },
+      write: { type: 'boolean', help: 'save it in the cases folder instead of printing it' },
+    },
+    needs: 'graph',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const config = ctx.config.cases ?? {};
+      const id = ctx.args[0]!;
+      if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) return { text: `${id}: an id is lower case letters, digits, dots, dashes and underscores`, code: 2 };
+      const to = ctx.flags.to as string | undefined;
+      const from = (ctx.flags.from as string | undefined) ?? config.start;
+      if (!to) return { text: 'case new needs --to <Route>, the screen the case is about', code: 2 };
+      if (!from) return { text: 'case new needs --from <Route>, or cases.start in lynkeus.config.json', code: 2 };
+      const graph = ctx.graph();
+      if (!graph.screens[to]) return { text: `${to}: the app has no such screen (lynkeus map routes lists them)`, code: 1 };
+      const server = config.fixtures ? new Fixtures(config.fixtures, config.base ?? ctx.root) : undefined;
+      const described = server ? await server.describe().finally(() => server.close()) : undefined;
+      const text = draftCase({
+        id,
+        title: ctx.flags.title as string | undefined,
+        from,
+        to,
+        path: plan(graph, from, to, edges.load(edgesFile(ctx.root))) ?? undefined,
+        fixtures: described?.details,
+        fixturesSilent: !!server && !described,
+        macros: Object.keys(config.macros ?? {}),
+      });
+      if (!ctx.flags.write) return { text, json: { id, text } };
+      const dir = path.resolve(config.base ?? ctx.root, config.dir ?? 'cases');
+      const file = path.join(dir, `${id}.md`);
+      if (fs.existsSync(file)) return { text: `${path.relative(ctx.root, file)} is there already; pick another id or edit it`, code: 1 };
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(file, text);
+      return { text: `wrote ${path.relative(ctx.root, file)}`, json: { id, file } };
+    },
+  }),
+];

package/src/commands/device.ts

@@ -76,8 +76,26 @@ export const simulatorArgv = (platform: Platform, deviceId: string, sub: string,
           { bin: 'xcrun', args: ['simctl', 'launch', deviceId, app, '-AppleLanguages', `(${tag})`, '-AppleLocale', locale] },
         ];
       }
+      case 'biometrics': {
+        // The simulator's Face ID / Touch ID enrollment, as Features ▸ Face ID ▸ Enrolled toggles it; which of the two
+        // the device has is its model's.
+        const [available] = args;
+        if (!available) throw new Error('lynkeus os biometrics --available FaceID|TouchID|none on a simulator');
+        const enrolled = available === 'none' ? '0' : '1';
+        return [
+          { bin: 'xcrun', args: ['simctl', 'spawn', deviceId, 'notifyutil', '-s', 'com.apple.BiometricKit.enrollmentChanged', enrolled] },
+          { bin: 'xcrun', args: ['simctl', 'spawn', deviceId, 'notifyutil', '-p', 'com.apple.BiometricKit.enrollmentChanged'] },
+        ];
+      }
+      case 'appstate': {
+        // Another app in front puts this one in the background; launching it again brings it back as it was.
+        const [state] = args;
+        if (state === 'background') return [{ bin: 'xcrun', args: ['simctl', 'launch', deviceId, 'com.apple.Preferences'] }];
+        if (state === 'active') return [{ bin: 'xcrun', args: ['simctl', 'launch', deviceId, needApp()] }];
+        throw new Error('lynkeus os appstate background|active on a simulator');
+      }
       default:
-        throw new Error(`unknown os subcommand "${sub}"; one of permissions, push, appearance, location, language`);
+        throw new Error(`unknown os subcommand "${sub}"; one of permissions, push, appearance, location, language, appstate`);
     }
   }
   const adb = (a: string[]): Invocation => ({ bin: 'adb', args: ['-s', deviceId, ...a] });
@@ -99,8 +117,15 @@ export const simulatorArgv = (platform: Platform, deviceId: string, sub: string,
       const [lat, lon] = where.split(',');
       return [adb(['emu', 'geo', 'fix', lon!, lat!])];
     }
+    case 'appstate': {
+      // Home sends the app to the background; its launcher intent brings the same task back, not a new one.
+      const [state] = args;
+      if (state === 'background') return [adb(['shell', 'input', 'keyevent', 'KEYCODE_HOME'])];
+      if (state === 'active') return [adb(['shell', 'monkey', '--pct-syskeys', '0', '-p', needApp(), '-c', 'android.intent.category.LAUNCHER', '1'])];
+      throw new Error('lynkeus os appstate background|active on an emulator or a phone');
+    }
     default:
-      throw new Error(`"${sub}" is not available on Android through lynkeus; permissions, appearance and location are`);
+      throw new Error(`"${sub}" is not available on Android through lynkeus; permissions, appearance, location and appstate are`);
   }
 };
 

package/src/commands/doctor.ts

@@ -78,6 +78,13 @@ const PATTERNS: { re: RegExp; how: string }[] = [
   { 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: string): string => text.replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, ' ')).replace(/^[ \t]*\/\/.*$/gm, '');
+
 const scanNativeRefs = (root: string): NativeRef[] => {
   const files: string[] = [];
   for (const d of SCAN_DIRS) walk(path.join(root, d), files);
@@ -85,7 +92,7 @@ const scanNativeRefs = (root: string): NativeRef[] => {
   for (const file of files) {
     let text: string;
     try {
-      text = fs.readFileSync(file, 'utf8');
+      text = withoutComments(fs.readFileSync(file, 'utf8'));
     } catch {
       continue;
     }
@@ -107,7 +114,7 @@ const entryMocks = (root: string, entry: string): { specs: Set<string>; files: S
   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/src/commands/drive.ts

@@ -166,7 +166,7 @@ export const driveCommands = [
   define({
     name: 'wait',
     mcp: 'core',
-    mcpOmit: ['nth'],
+    mcpOmit: ['nth', 'since'],
     group: 'drive',
     summary: 'Until a route or element appears (or leaves), or a number of ms',
     positionals: [{ name: 'what', help: `Route | route:index | ${TARGET_HELP} | 800 (ms)`, required: true }],
@@ -175,6 +175,7 @@ export const driveCommands = [
       gone: { type: 'boolean', help: 'until it leaves the screen' },
       scroll: { type: 'boolean', help: 'scroll until it is in the window' },
       timeout: { type: 'number', help: 'give up after', default: 10000, value: 'ms' },
+      since: { type: 'number', help: 'a trace mark: a route reached after it counts, even if already left', value: 'seq' },
     },
     needs: 'app',
     run: async (ctx) => {
@@ -189,6 +190,7 @@ export const driveCommands = [
           gone: ctx.flags.gone ? true : undefined,
           scroll: ctx.flags.scroll ? true : undefined,
           timeoutMs: ctx.flags.timeout as number,
+          since: ctx.flags.since as number | undefined,
         }),
       };
     },

package/src/commands/fixtures.ts

@@ -0,0 +1,102 @@
+import { FIXTURES_PROTOCOL, type FixtureCommand } from 'lynkeus-protocol';
+
+import { DESCRIBE, type Description, Fixtures, lastDescription, readDescription } from '../cases/fixtures.js';
+import { define } from '../registry.js';
+
+const paramsOf = (c: FixtureCommand) =>
+  Object.entries(c.params ?? {})
+    .map(([k, p]) => `${k}${p.required ? '' : '?'}${p.values ? `=${p.values.join('|')}` : p.type ? `:${p.type}` : ''}`)
+    .join(' ');
+
+/** What a server keeps of the contract and what it leaves out, as lines a person can act on. */
+export const checkDescription = (d: Description | undefined): { ok: boolean; lines: string[] } => {
+  if (!d) return { ok: false, lines: ['✗ `lynkeus.describe` got no list of commands: answer {"commands": [...]} (docs/FIXTURES.md)'] };
+  const lines: string[] = [];
+  let ok = true;
+  if (d.down) {
+    ok = false;
+    lines.push(`✗ the server runs but cannot serve: ${d.down}`);
+  }
+  if (d.protocol !== undefined && d.protocol > FIXTURES_PROTOCOL) {
+    ok = false;
+    lines.push(`✗ it speaks fixtures protocol ${d.protocol}; this lynkeus knows ${FIXTURES_PROTOCOL}`);
+  }
+  const names = new Set<string>();
+  for (const c of d.details) {
+    if (names.has(c.name)) {
+      ok = false;
+      lines.push(`✗ ${c.name} is listed twice`);
+    }
+    names.add(c.name);
+  }
+  const bare = d.details.filter((c) => !c.summary);
+  lines.push(`✓ ${d.commands.length} command${d.commands.length === 1 ? '' : 's'}`);
+  if (bare.length)
+    lines.push(
+      `· ${bare.length} without a summary (${bare
+        .slice(0, 6)
+        .map((c) => c.name)
+        .join(', ')}${bare.length > 6 ? ', …' : ''}): a summary and params let authors and models pick a setup`,
+    );
+  return { ok, lines };
+};
+
+export const fixturesCommands = [
+  define({
+    name: 'fixtures describe',
+    group: 'runs',
+    summary: 'List what the project’s fixtures server can do: each command, what it makes or reads, its parameters',
+    details:
+      'Starts the command `cases.fixtures` names, asks `lynkeus.describe`, and prints each command with its summary and parameters, for whoever writes a case. A server that answers names only shows names. What it answered last (here or before a run) is kept in .lynkeus and shown for a day without starting it; --fresh asks again.',
+    flags: { fresh: { type: 'boolean', help: 'ask the server even when it described itself in the last day' } },
+    needs: 'nothing',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const config = ctx.config.cases ?? {};
+      if (!config.fixtures) return { text: 'the project declares no fixtures (cases.fixtures in lynkeus.config.json)', code: 1 };
+      const root = config.base ?? ctx.root;
+      const kept = ctx.flags.fresh ? undefined : lastDescription(root, config.fixtures.command);
+      const recent = kept && Date.now() - kept.at < 24 * 3600_000 ? kept : undefined;
+      let d = recent?.description;
+      if (!d) {
+        const server = new Fixtures(config.fixtures, root);
+        d = await server.describe().finally(() => server.close());
+      }
+      if (!d) return { text: 'the fixtures server did not describe itself (it answers `lynkeus.describe` with {"commands": [...]})', code: 1 };
+      const text = d.details.map((c) => `${c.name}${c.params ? ` ${paramsOf(c)}` : ''}${c.summary ? `\n    ${c.summary}` : ''}`).join('\n');
+      const age = recent ? `\n(as the server described itself ${Math.round((Date.now() - recent.at) / 60_000)} min ago; --fresh asks it again)` : '';
+      return { text: d.down ? `${text}\n(the server cannot serve now: ${d.down})` : `${text}${age}`, json: d };
+    },
+  }),
+  define({
+    name: 'fixtures check',
+    group: 'runs',
+    summary: 'Tell whether the project’s fixtures server keeps the fixtures protocol',
+    details:
+      'Starts the server, asks `lynkeus.describe`, and checks the answer against the contract in docs/FIXTURES.md: a list of commands, no name twice, a protocol version this lynkeus knows, and whether it is up. It changes nothing in the backend.',
+    needs: 'nothing',
+    session: false,
+    mcp: 'core',
+    run: async (ctx) => {
+      const config = ctx.config.cases ?? {};
+      if (!config.fixtures) return { text: 'the project declares no fixtures (cases.fixtures in lynkeus.config.json)', code: 1 };
+      const server = new Fixtures(config.fixtures, config.base ?? ctx.root);
+      // Its own call, not describe(): a server that never answers is told apart from one that answers wrong.
+      const answered = await server.call(DESCRIBE, {}).then(
+        (answer) => ({ answer }),
+        (error: Error) => ({ error: error.message }),
+      );
+      server.close();
+      if ('error' in answered)
+        return {
+          text: `✗ the fixtures server gave no answer to lynkeus.describe: ${answered.error}\n  (is its backend up? the command is \`${config.fixtures.command}\`)`,
+          json: { ok: false, error: answered.error },
+          code: 1,
+        };
+      const d = readDescription(answered.answer);
+      const { ok, lines } = checkDescription(d);
+      return { text: lines.join('\n'), json: { ok, description: d }, code: ok ? 0 : 1 };
+    },
+  }),
+];

package/src/commands/headless.ts

@@ -1,12 +1,14 @@
 import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 
-import { type LynkeusConfig, lynkeusDir, portFromEnv } from '../config.js';
+import { type LynkeusConfig, lynkeusDir, portFromEnv, readToken } from '../config.js';
 import { describeExplanations, explainError } from '../knowledge/errors.js';
 import { type Ctx, 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' 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';
@@ -31,35 +33,187 @@ 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: LynkeusConfig): Record<string, string> => (config.apiUrl ? { [config.apiEnv ?? 'API_URL']: config.apiUrl } : {});
+
+/**
+ * A jest cache of its own for each API base. Babel inlines `process.env` into the code it transforms and jest
+ * keeps that output, so a host started with another API address kept calling the first one it was started with.
+ */
+export const cacheFor = (root: string, env: Record<string, string | undefined>, apiEnv = 'API_URL'): string => {
+  const key = createHash('sha256')
+    .update(`${apiEnv}=${env[apiEnv] ?? ''}`)
+    .digest('hex')
+    .slice(0, 12);
+  return path.join(lynkeusDir(root), 'jest-cache', key);
+};
+
+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: string): Record<string, string> => {
+  let options: { baseUrl?: string; paths?: Record<string, string[]> } | undefined;
+  try {
+    const text = fs.readFileSync(path.join(root, 'tsconfig.json'), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+    options = (JSON.parse(text) as { compilerOptions?: typeof options }).compilerOptions;
+  } catch {
+    return {};
+  }
+  const base = path.join(root, options?.baseUrl ?? '.');
+  const literal = (text: string) => 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.
+ */
+/** The app's react folder, when lynkeus-headless would load another copy; undefined when they are one. */
+export const duplicateReact = (root: string): string | undefined => {
+  const require = createRequire(import.meta.url);
+  try {
+    // Its exports leave out package.json: from its entry up to the folder that holds one.
+    let headless = path.dirname(fs.realpathSync(require.resolve('lynkeus-headless', { paths: [root] })));
+    while (!fs.existsSync(path.join(headless, 'package.json')) && path.dirname(headless) !== headless) headless = path.dirname(headless);
+    const ours = path.dirname(require.resolve('react/package.json', { paths: [root] }));
+    const theirs = path.dirname(require.resolve('react/package.json', { paths: [headless] }));
+    return fs.realpathSync(ours) === fs.realpathSync(theirs) ? undefined : ours;
+  } catch {
+    return undefined;
+  }
+};
+
+const jestDefaults = (root: string): string[] => {
+  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')) as { jest?: unknown };
+      config = manifest.jest ? JSON.stringify(manifest.jest) : '';
+    } catch {}
+  }
+  const flags: string[] = [];
+  const react = duplicateReact(root);
+  // lynkeus-headless with a React of its own (a linked package, a workspace, pnpm) breaks every hook: the app and
+  // the renderer must share the app's copy.
+  const sameReact = react ? { '^react$': react, '^react/(.*)$': `${react}/$1` } : {};
+  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), ...sameReact })}`);
+  } else if (react) {
+    if (config.includes('moduleNameMapper'))
+      process.stderr.write(
+        `lynkeus: lynkeus-headless finds another copy of react than the app's; add to moduleNameMapper in the app's jest config: '^react$': '${react}', '^react/(.*)$': '${react}/$1'\n`,
+      );
+    else flags.push(`--moduleNameMapper=${JSON.stringify(sameReact)}`);
+  }
+  // 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.',
+      "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 };
@@ -75,17 +229,41 @@ 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], {
+      // LYNKEUS_HEADLESS tells the app's jest setup a host is starting, not its unit tests: a setup that stubs a native
+      // SDK whole can leave it real there, so the call reaches the stand-in `nativeMocks` shows.
+      const env = { ...apiFromConfig(ctx.config), ...process.env, LYNKEUS_TOKEN: token, LYNKEUS_HEADLESS: '1', CI: '1', NODE_OPTIONS: nodeOptions };
+      const cache = `--cacheDirectory=${cacheFor(ctx.root, env, ctx.config.apiEnv)}`;
+      const child = spawn('npx', ['jest', testFile, '--runInBand', '--watchAll=false', ...jestDefaults(ctx.root), cache, ...ctx.passthrough], {
         cwd: ctx.root,
         stdio: ['inherit', 'inherit', 'pipe'],
-        env: { ...process.env, CI: '1', NODE_OPTIONS: nodeOptions },
+        env,
+        // Its own process group: npx, jest and the host it runs end together. Stopping only npx left the
+        // host dialing the port, where a later run's driver took it for the app it meant to drive.
+        detached: true,
+      });
+      const stop = (signal: NodeJS.Signals) => {
+        try {
+          if (child.pid) process.kill(-child.pid, signal);
+        } catch {
+          // already gone
+        }
+      };
+      const signals: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+      const forward = signals.map((signal) => {
+        const handler = () => stop(signal);
+        process.on(signal, handler);
+        return () => process.off(signal, handler);
       });
+      const onExit = () => stop('SIGTERM');
+      process.on('exit', onExit);
       let tail = '';
       child.stderr?.on('data', (chunk: Buffer) => {
         process.stderr.write(chunk);
         tail = (tail + chunk.toString()).slice(-20000);
       });
       const code = await new Promise<number>((resolve) => child.on('exit', (c) => resolve(c ?? 0)));
+      for (const off of forward) off();
+      process.off('exit', onExit);
       if (code) {
         const found = explainError(tail);
         if (found.length) ctx.err(describeExplanations(found));
@@ -103,8 +281,13 @@ 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),
@@ -114,6 +297,7 @@ 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 };
     },
   }),
@@ -127,6 +311,10 @@ 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 as string);