lynkeus 0.3.0 → 0.5.0

package/lib/commands/headless.js

@@ -1,11 +1,13 @@
 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 { 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 +29,176 @@ 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 } : {});
+/**
+ * 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, env, apiEnv = 'API_URL') => {
+    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) => {
+    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.
+ */
+/** The app's react folder, when lynkeus-headless would load another copy; undefined when they are one. */
+export const duplicateReact = (root) => {
+    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) => {
+    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 = [];
+    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.',
+        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,17 +214,44 @@ 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) => {
+                try {
+                    if (child.pid)
+                        process.kill(-child.pid, signal);
+                }
+                catch {
+                    // already gone
+                }
+            };
+            const 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) => {
                 process.stderr.write(chunk);
                 tail = (tail + chunk.toString()).slice(-20000);
             });
             const code = await new Promise((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)
@@ -99,8 +270,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 +285,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 +300,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;

package/lib/commands/init.js

@@ -1,9 +1,20 @@
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
-import { packageName } from '../config.js';
+import { ensureToken, packageName, readToken } from '../config.js';
 const APP_CANDIDATES = ['App.tsx', 'App.jsx', 'App.js', 'app/App.tsx', 'src/App.tsx', 'src/App.jsx', 'src/App.js'];
 const INDEX_CANDIDATES = ['index.js', 'index.tsx', 'index.ts'];
 const findFirst = (root, candidates) => candidates.find((c) => fs.existsSync(path.join(root, c)));
+/** The file that already mounts the agent: the entry, or the App component of an app that renders `<Lynkeus>` itself. */
+const mountedIn = (root) => [...INDEX_CANDIDATES, ...APP_CANDIDATES].find((file) => {
+    try {
+        return /from ['"]lynkeus-agent(\/auto)?['"]/.test(fs.readFileSync(path.join(root, file), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+});
 const relImport = (fromFile, toFile) => {
     const rel = path
         .relative(path.dirname(fromFile), toFile)
@@ -11,7 +22,36 @@ const relImport = (fromFile, toFile) => {
         .replace(/\.(tsx|ts|jsx|js)$/, '');
     return rel.startsWith('.') ? rel : `./${rel}`;
 };
-const entryTemplate = (appImport, apiEnv, appName, locale) => {
+/** The folder of an Expo Router app's routes, which is the app when there is no root component to import. */
+const routesOf = (root) => {
+    try {
+        createRequire(path.join(root, 'package.json')).resolve('expo-router/package.json');
+    }
+    catch {
+        return undefined;
+    }
+    return ['src/app', 'app'].find((dir) => fs.existsSync(path.join(root, dir, '_layout.tsx')) ||
+        fs.existsSync(path.join(root, dir, '_layout.js')) ||
+        fs.existsSync(path.join(root, dir, 'index.tsx')));
+};
+const appBlock = (source) => 'component' in source
+    ? `// Whatever the app's index runs before rendering (polyfills, i18n, services):
+// require it here too, then the App.
+const { default: App } = require('${source.component}')`
+    : `// An Expo Router app has no root component: the router is the app, over the route
+// files in ${source.dir}, read here as the bundler would read them. Whatever the
+// app's root layout does not run before rendering (polyfills, i18n), require it first.
+process.env.EXPO_ROUTER_IMPORT_MODE = 'sync'
+// Its testing library first: it stands in for what has no native side here (expo-linking's
+// scheme, Reanimated), and the router must load after it.
+const { getMockContext } = require('expo-router/testing-library')
+const React = require('react')
+const { ExpoRoot } = require('expo-router')
+const routes = getMockContext(require('path').resolve(__dirname, '${source.routes}'))
+// Mounted as a device build mounts it, so the agent finds the router's navigation by itself.
+require('lynkeus-agent/auto').auto({ token: process.env.LYNKEUS_TOKEN })
+const App = () => React.createElement(ExpoRoot, { context: routes })`;
+const entryTemplate = (source, apiEnv, appName, locale) => {
     const LOCALE = locale?.languageTag || locale?.country || locale?.language
         ? `\n  // The locale this app is built for, from lynkeus.config.json.\n  locale: ${JSON.stringify({ country: locale.country, languageTag: locale.languageTag, languageCode: locale.language })},`
         : "\n  // locale: { country: 'DE', languageTag: 'de-DE', languageCode: 'de' },";
@@ -36,9 +76,7 @@ installDefaultMocks({
 // lists the native modules the app references that nothing covers yet:
 //   jest.mock('some-native-package', () => ({ method: () => undefined }))
 
-// Whatever the app's index runs before rendering (polyfills, i18n, services):
-// require it here too, then the App.
-const { default: App } = require('${appImport}')
+${appBlock(source)}
 
 export { App }
 `;
@@ -67,14 +105,29 @@ const addTokenPlugin = (root) => {
         return `${file} already has ${TOKEN_PLUGIN}`;
     const plugins = /\bplugins\s*:\s*\[/.exec(text);
     const presets = /^([ \t]*)presets\s*:/m.exec(text);
-    if (!plugins && !presets)
+    // A config written on one line has its presets after the brace, not at the start of a line.
+    const inline = plugins || presets ? null : /\bpresets\s*:/.exec(text);
+    if (!plugins && !presets && !inline)
         return byHand;
     const next = plugins
         ? `${text.slice(0, plugins.index + plugins[0].length)}'${TOKEN_PLUGIN}', ${text.slice(plugins.index + plugins[0].length)}`
-        : `${text.slice(0, presets.index)}${presets[1]}plugins: ['${TOKEN_PLUGIN}'],\n${text.slice(presets.index)}`;
+        : presets
+            ? `${text.slice(0, presets.index)}${presets[1]}plugins: ['${TOKEN_PLUGIN}'],\n${text.slice(presets.index)}`
+            : `${text.slice(0, inline.index)}plugins: ['${TOKEN_PLUGIN}'], ${text.slice(inline.index)}`;
     fs.writeFileSync(path.join(root, file), next);
     return `added ${TOKEN_PLUGIN} to ${file}`;
 };
+const EXPO_ENV = '.env.local';
+const EXPO_TOKEN = 'EXPO_PUBLIC_LYNKEUS_TOKEN';
+/** Expo passes the app only variables that start with EXPO_PUBLIC_, and reads them from `.env.local`, which its template keeps out of git. */
+const giveExpoTheToken = (root, token) => {
+    const file = path.join(root, EXPO_ENV);
+    const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    if (new RegExp(`^${EXPO_TOKEN}=`, 'm').test(text))
+        return `${EXPO_ENV} already sets ${EXPO_TOKEN}`;
+    fs.writeFileSync(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${EXPO_TOKEN}=${token}\n`);
+    return `wrote ${EXPO_TOKEN} to ${EXPO_ENV} (check it is in .gitignore: Expo's template ignores .env*.local)`;
+};
 /**
  * Mounts the agent from the app's entry, before anything registers the root component. An Expo Router app
  * has no entry of its own (`"main": "expo-router/entry"`), so it gets one that mounts the agent and then
@@ -86,7 +139,11 @@ export const mountAgent = (root) => {
     const expo = !!(manifest.dependencies?.expo ?? manifest.devDependencies?.expo);
     const index = findFirst(root, INDEX_CANDIDATES);
     const routed = manifest.main === 'expo-router/entry';
-    if (routed && !index) {
+    const already = mountedIn(root);
+    if (already) {
+        notes.push(`${already} already mounts the agent`);
+    }
+    else if (routed && !index) {
         fs.writeFileSync(path.join(root, 'index.js'), `${mountLines(true)}\nimport 'expo-router/entry'\n`);
         fs.writeFileSync(path.join(root, 'package.json'), `${JSON.stringify({ ...JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')), main: 'index.js' }, null, 2)}\n`);
         notes.push("wrote index.js (mounts the agent, then loads expo-router) and pointed package.json's main at it");
@@ -98,24 +155,23 @@ export const mountAgent = (root) => {
     else {
         const indexPath = path.join(root, index);
         const text = fs.readFileSync(indexPath, 'utf8');
-        if (text.includes('lynkeus-agent/auto')) {
-            notes.push(`${index} already mounts the agent`);
-        }
-        else {
-            // After the last import, so the app's own polyfills still run first.
-            const imports = [...text.matchAll(/^import .*$/gm)];
-            const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length + 1 : 0;
-            fs.writeFileSync(indexPath, text.slice(0, at) + mountLines(expo) + text.slice(at));
-            notes.push(`added auto() to ${index}`);
-        }
+        // After the last import, so the app's own polyfills still run first.
+        const imports = [...text.matchAll(/^import .*$/gm)];
+        const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length + 1 : 0;
+        fs.writeFileSync(indexPath, text.slice(0, at) + mountLines(expo) + text.slice(at));
+        notes.push(`added auto() to ${index}`);
     }
+    const { token, made } = ensureToken(root);
+    if (made)
+        notes.push('made a token for this project in .lynkeus/token (kept out of git); the CLI, the MCP server and the app all read it');
     if (!expo) {
         notes.push(addTokenPlugin(root));
-        notes.push('start Metro with LYNKEUS_TOKEN set to the value the CLI reads; after changing it, start Metro with --reset-cache');
+        notes.push('restart Metro with --reset-cache so the bundle picks the token up; LYNKEUS_TOKEN in the environment still wins over the file');
     }
     if (expo) {
+        notes.push(giveExpoTheToken(root, token));
         notes.push('Expo: the agent has native code, so it runs in a development build (npx expo run:ios, npx expo run:android), not in Expo Go');
-        notes.push('Expo: start the dev server with EXPO_PUBLIC_LYNKEUS_TOKEN set to the same value as LYNKEUS_TOKEN; Expo passes the app only variables with that prefix');
+        notes.push('Expo: restart the dev server so it reads .env.local; EXPO_PUBLIC_LYNKEUS_TOKEN in the environment still wins over the file');
     }
     return notes;
 };
@@ -123,20 +179,169 @@ export const init = (root, opts) => {
     const notes = [];
     const entryPath = path.join(root, opts.entry);
     const app = opts.app ?? findFirst(root, APP_CANDIDATES);
-    if (!app)
-        throw new Error(`no App component found (${APP_CANDIDATES.join(', ')}); pass --component <path>`);
+    const routes = app ? undefined : routesOf(root);
+    if (!app && !routes)
+        throw new Error(`no App component found (${APP_CANDIDATES.join(', ')}) and no Expo Router routes; pass --component <path>`);
     if (fs.existsSync(entryPath) && !opts.force) {
         notes.push(`${opts.entry} exists; left as is (--force overwrites)`);
     }
     else {
         fs.mkdirSync(path.dirname(entryPath), { recursive: true });
-        fs.writeFileSync(entryPath, entryTemplate(relImport(entryPath, path.join(root, app)), opts.apiEnv, packageName(root), opts.locale));
-        notes.push(`wrote ${opts.entry} (app: ${app})`);
+        const source = app
+            ? { component: relImport(entryPath, path.join(root, app)) }
+            : { routes: path.relative(path.dirname(entryPath), path.join(root, routes)).replace(/\\/g, '/'), dir: routes };
+        fs.writeFileSync(entryPath, entryTemplate(source, opts.apiEnv, packageName(root), opts.locale));
+        notes.push(`wrote ${opts.entry} (${app ? `app: ${app}` : `Expo Router, routes in ${routes}`})`);
     }
     if (opts.auto)
         notes.push(...mountAgent(root));
-    notes.push("jest: make sure transformIgnorePatterns lets 'lynkeus-[^/]+' through, next to react-native (lynkeus headless doctor checks it)");
-    notes.push(`next: LYNKEUS_TOKEN=<token> ${opts.apiEnv}=http://127.0.0.1:3000/ lynkeus headless start`);
+    // `headless start` refuses to run without one, and an app tested only headless never runs `lynkeus init`.
+    else if (ensureToken(root).made)
+        notes.push('made a token for this project in .lynkeus/token (kept out of git); the CLI and the MCP server read it');
+    notes.push("jest: when the app has no jest configuration, `headless start` passes the preset it needs (jest-expo for Expo, React Native's otherwise) and the packages to transpile; an app that sets its own lets 'lynkeus-[^/]+' through, next to react-native");
+    notes.push(`next: ${opts.apiEnv}=http://127.0.0.1:3000/ lynkeus headless start  (or put "apiUrl": "http://127.0.0.1:3000/" in lynkeus.config.json; the token is the project's, in .lynkeus/token)`);
     notes.push('      then, in another shell: lynkeus screen  (or lynkeus headless doctor to see what still needs a mock)');
     return notes;
 };
+const AGENT = 'lynkeus-agent';
+/** The package manager whose lockfile is in the app's folder or above it: an app in a monorepo has it at the top. */
+const managerOf = (root) => {
+    for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'bun.lockb')) || fs.existsSync(path.join(dir, 'bun.lock')))
+            return 'bun';
+        if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml')))
+            return 'pnpm';
+        if (fs.existsSync(path.join(dir, 'yarn.lock')))
+            return 'yarn';
+        if (fs.existsSync(path.join(dir, 'package-lock.json')) || fs.existsSync(path.join(dir, '.git')) || path.dirname(dir) === dir)
+            return 'npm';
+    }
+};
+const installCommand = (root, expo) => {
+    if (expo)
+        return ['npx', 'expo', 'install', AGENT];
+    const manager = managerOf(root);
+    return manager === 'npm' ? ['npm', 'install', AGENT] : [manager, 'add', AGENT];
+};
+/**
+ * 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 const installFailure = (ran) => `${ran.stderr ?? ''}\n${ran.error?.message ?? ''}`
+    .split('\n')
+    .map((line) => line.replace(/^(npm (error|ERR!)|error|ERR_PNPM_\w+|YN\d{4}:)\s*/, '').trim())
+    .filter((line) => line && !/^code \w+$|^node_modules\/|_logs|complete log|full report|^Fix the upstream|^this command with|^to accept an incorrect/i.test(line))
+    .slice(0, 8)
+    .join('; ');
+const hasAgent = (manifest) => !!(manifest.dependencies?.[AGENT] ?? manifest.devDependencies?.[AGENT]);
+/** 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 const installAgent = (root) => {
+    const manifest = readManifest(root);
+    if (hasAgent(manifest))
+        return `${AGENT} is already a dependency`;
+    const command = installCommand(root, !!(manifest.dependencies?.expo ?? manifest.devDependencies?.expo));
+    const ran = spawnSync(command[0], command.slice(1), { cwd: root, encoding: 'utf8', timeout: 300_000 });
+    if (ran.status === 0)
+        return `installed ${AGENT} (${command.join(' ')}); it has native code, so build the app again`;
+    const said = installFailure(ran);
+    return `could not install ${AGENT} with \`${command.join(' ')}\`${said ? `: ${said}` : ''}; run it yourself, then \`lynkeus init\` again`;
+};
+/** What a project has of lynkeus and what it still lacks, each with the one thing that fixes it. Reads files only. */
+export const setupChecks = (root) => {
+    const manifest = readManifest(root);
+    if (!manifest.dependencies && !manifest.devDependencies)
+        return [{ what: 'a package.json here', ok: false, fix: 'run this from the app\u2019s folder (or pass --root)' }];
+    const expo = !!(manifest.dependencies?.expo ?? manifest.devDependencies?.expo);
+    const checks = [];
+    const depends = hasAgent(manifest);
+    checks.push({ what: `${AGENT} is a dependency`, ok: depends, fix: '`lynkeus init` installs it' });
+    if (depends)
+        checks.push({
+            what: `${AGENT} is installed`,
+            ok: fs.existsSync(path.join(root, 'node_modules', AGENT, 'package.json')),
+            fix: 'install the project\u2019s dependencies',
+        });
+    const mounted = mountedIn(root);
+    checks.push({ what: mounted ? `${mounted} mounts the agent` : 'the app mounts the agent', ok: !!mounted, fix: '`lynkeus init` adds it to the entry' });
+    if (!expo) {
+        const babel = findFirst(root, BABEL_CANDIDATES);
+        checks.push({
+            what: 'babel.config.js has lynkeus-agent/babel',
+            ok: !!babel && fs.readFileSync(path.join(root, babel), 'utf8').includes(TOKEN_PLUGIN),
+            fix: '`lynkeus init` adds it',
+        });
+    }
+    const token = readToken(root);
+    checks.push({ what: 'the project has a token', ok: !!token, fix: '`lynkeus init` makes one in .lynkeus/token' });
+    if (expo && token) {
+        const env = path.join(root, EXPO_ENV);
+        const given = !!process.env[EXPO_TOKEN] || (fs.existsSync(env) && new RegExp(`^${EXPO_TOKEN}=`, 'm').test(fs.readFileSync(env, 'utf8')));
+        checks.push({ what: `Expo is given the token (${EXPO_TOKEN})`, ok: given, fix: '`lynkeus init` writes it to .env.local' });
+    }
+    return checks;
+};
+/** What `lynkeus headless start` runs on: jest hosts the app, Testing Library renders it, lynkeus-headless serves the agent. */
+const HEADLESS_PACKAGES = ['jest', '@testing-library/react-native', 'lynkeus-headless'];
+const resolvable = (root, name) => {
+    try {
+        createRequire(path.join(root, 'package.json')).resolve(`${name}/package.json`);
+        return true;
+    }
+    catch (error) {
+        // A package whose exports leave package.json out is still there.
+        return error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED';
+    }
+};
+const JEST_PRESET = '@react-native/jest-preset';
+/** The app's React Native version, when it is installed. */
+const reactNativeVersion = (root) => {
+    try {
+        const file = createRequire(path.join(root, 'package.json')).resolve('react-native/package.json');
+        return JSON.parse(fs.readFileSync(file, 'utf8')).version;
+    }
+    catch {
+        return undefined;
+    }
+};
+// React Native 0.86 moved its jest preset out of `react-native`, which now throws when jest asks it for one.
+const presetMoved = (version) => {
+    const [major, minor] = (version ?? '').split('.').map(Number);
+    return major === 0 ? (minor ?? 0) >= 86 : (major ?? 0) > 0;
+};
+const JEST_EXPO = 'jest-expo';
+const isExpo = (root) => {
+    const manifest = readManifest(root);
+    return !!(manifest.dependencies?.expo ?? manifest.devDependencies?.expo);
+};
+/**
+ * The jest preset the app needs and lacks: an Expo app's is jest-expo, which gives Expo's modules the native
+ * side they look for (\`globalThis.expo\`); React Native 0.86 and later keep theirs out of \`react-native\`.
+ */
+const presetNeeded = (root) => (isExpo(root) ? JEST_EXPO : presetMoved(reactNativeVersion(root)) ? JEST_PRESET : undefined);
+/** The packages the headless host needs that this project cannot load yet. */
+export const headlessMissing = (root) => [...HEADLESS_PACKAGES, ...[presetNeeded(root)].filter((p) => !!p)].filter((name) => !resolvable(root, name));
+/** The preset \`headless start\` gives jest when the app's own configuration names none. */
+export const jestPreset = (root) => (resolvable(root, JEST_EXPO) ? JEST_EXPO : resolvable(root, JEST_PRESET) ? JEST_PRESET : 'react-native');
+const devInstallCommand = (root, names) => ({ bun: ['bun', 'add', '-d'], pnpm: ['pnpm', 'add', '-D'], yarn: ['yarn', 'add', '-D'], npm: ['npm', 'install', '--save-dev'] })[managerOf(root)].concat(names);
+const install = (root, command, names) => {
+    const ran = spawnSync(command[0], command.slice(1), { cwd: root, encoding: 'utf8', timeout: 300_000 });
+    if (ran.status === 0)
+        return `installed ${names.join(', ')} (${command.join(' ')})`;
+    const said = installFailure(ran);
+    return `could not install ${names.join(', ')} with \`${command.join(' ')}\`${said ? `: ${said}` : ''}; run it yourself`;
+};
+/** Adds what the headless host needs as development dependencies; a line saying what happened. */
+export const installHeadless = (root) => {
+    const missing = headlessMissing(root);
+    if (!missing.length)
+        return `jest, Testing Library, lynkeus-headless and the ${jestPreset(root)} preset are installed`;
+    const lines = [];
+    const plain = missing.filter((name) => name !== JEST_EXPO);
+    // The React Native preset is released with React Native, version for version.
+    if (plain.length)
+        lines.push(install(root, devInstallCommand(root, plain.map((name) => (name === JEST_PRESET ? `${name}@${reactNativeVersion(root)}` : name))), plain));
+    // Expo's installer picks the jest-expo of the app's SDK.
+    if (missing.includes(JEST_EXPO))
+        lines.push(install(root, ['npx', 'expo', 'install', JEST_EXPO, '--', '--save-dev'], [JEST_EXPO]));
+    return lines.join('\n');
+};

package/lib/commands/map.d.ts

@@ -1,2 +1,4 @@
+/** Source files a branch changed against `base`, committed or not. */
+export declare const changedSources: (root: string, base: string, err: (line: string) => void) => string[];
 export declare const mapCommands: import("../registry.js").Command[];
 export declare const mapCheckWorkflow: (depth: number) => string;