lynkeus 0.3.0 → 0.4.0

package/src/commands/cases.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, 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';
@@ -29,6 +30,18 @@ const startHost = async (root: string, err: (line: string) => void): Promise<Chi
   });
   let output = '';
   const tail = (n: number) => 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<void>((resolve, reject) => {
     const settle = (error?: Error) => {
       clearTimeout(timer);
@@ -39,11 +52,11 @@ const startHost = async (root: string, err: (line: string) => void): Promise<Chi
     const read = (chunk: Buffer) => {
       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;
@@ -195,6 +208,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',
@@ -204,6 +223,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 },
@@ -220,7 +240,30 @@ 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;
@@ -241,7 +284,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'));
@@ -414,7 +460,10 @@ export const caseCommands = [
       const unsupported = count('unsupported');
       const summary = [
         ...reports.map(
-          (r) => `${{ passed: '✅', failed: '❌', unsupported: '🚫' }[r.result]} ${r.id}${r.retried && r.result === 'passed' ? '  ⚠ passed on retry' : ''}`,
+          (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)) : []),
@@ -481,7 +530,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/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/headless.ts

@@ -2,11 +2,11 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 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 +31,150 @@ 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 } : {});
+
+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.
+ */
+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[] = [];
+  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.',
+      "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,10 +190,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: Buffer) => {
@@ -103,8 +218,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 +234,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 +248,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);