lynkeus 0.3.0 → 0.4.0

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/report.js

@@ -75,9 +75,9 @@ export const plan = async (o) => {
     return { ...now, url: String((await ask(o, 'POST', route, o.go === 'upgrade' ? 'opening checkout' : 'opening the billing portal')).url) };
 };
 export const service = () => {
-    const url = process.env.LYNKEUS_REPORTS_URL;
+    const url = process.env.LYNKEUS_REPORTS_URL || 'https://lynkeus.io';
     const key = process.env.LYNKEUS_REPORTS_KEY;
-    return url && key ? { url, key } : 'set LYNKEUS_REPORTS_URL and LYNKEUS_REPORTS_KEY (the organization’s API key)';
+    return key ? { url, key } : 'set LYNKEUS_REPORTS_KEY to an API key of your organization (lynkeus.io, API keys); LYNKEUS_REPORTS_URL names another service';
 };
 export const reportCommands = [
     define({

package/lib/config.d.ts

@@ -5,6 +5,17 @@ export declare const graphFile: (root?: string) => string;
 export declare const edgesFile: (root?: string) => string;
 export declare const frontierFile: (root?: string) => string;
 export declare const runsDir: (root?: string) => string;
+export declare const tokenFile: (root?: string) => string;
+/**
+ * The secret the app and its driver share. LYNKEUS_TOKEN wins; otherwise it is the one `lynkeus init` wrote to
+ * `.lynkeus/token`, which the app's bundle reads too, so nobody has to set a variable in two terminals.
+ */
+export declare const readToken: (root?: string) => string | undefined;
+/** Makes the project's token if it has none, and keeps it out of git: `.lynkeus` also holds what a team commits. */
+export declare const ensureToken: (root?: string) => {
+    token: string;
+    made: boolean;
+};
 export declare const loadGraph: (root?: string) => ScreenGraph | null;
 /**
  * `lynkeus.config.json` in the app's folder: what would otherwise be repeated
@@ -17,6 +28,11 @@ export type LynkeusConfig = {
     entry?: string;
     /** The environment variable the app reads its API base from; the headless entry refuses one that is not local. */
     apiEnv?: string;
+    /**
+     * The local backend `headless start` hands the app under `apiEnv` when the environment sets none: an agent
+     * starting the host over MCP cannot export a variable.
+     */
+    apiUrl?: string;
     /** The driver port the app dials. */
     port?: number;
     /** Simulator udid or name. */

package/lib/config.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJson } from './files.js';
@@ -6,6 +7,35 @@ export const graphFile = (root) => path.join(lynkeusDir(root), 'graph.json');
 export const edgesFile = (root) => path.join(lynkeusDir(root), 'edges.jsonl');
 export const frontierFile = (root) => path.join(lynkeusDir(root), 'frontier.jsonl');
 export const runsDir = (root) => path.join(lynkeusDir(root), 'runs');
+export const tokenFile = (root) => path.join(lynkeusDir(root), 'token');
+/**
+ * The secret the app and its driver share. LYNKEUS_TOKEN wins; otherwise it is the one `lynkeus init` wrote to
+ * `.lynkeus/token`, which the app's bundle reads too, so nobody has to set a variable in two terminals.
+ */
+export const readToken = (root) => {
+    if (process.env.LYNKEUS_TOKEN)
+        return process.env.LYNKEUS_TOKEN;
+    try {
+        return fs.readFileSync(tokenFile(root), 'utf8').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Makes the project's token if it has none, and keeps it out of git: `.lynkeus` also holds what a team commits. */
+export const ensureToken = (root) => {
+    const had = readToken(root);
+    if (had)
+        return { token: had, made: false };
+    const token = crypto.randomBytes(24).toString('hex');
+    fs.mkdirSync(lynkeusDir(root), { recursive: true });
+    fs.writeFileSync(tokenFile(root), `${token}\n`, { mode: 0o600 });
+    const ignore = path.join(lynkeusDir(root), '.gitignore');
+    const ignored = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
+    if (!ignored.split('\n').includes('token'))
+        fs.writeFileSync(ignore, `${ignored}${ignored && !ignored.endsWith('\n') ? '\n' : ''}token\n`);
+    return { token, made: true };
+};
 export const loadGraph = (root) => {
     const file = graphFile(root);
     return fs.existsSync(file) ? readJson(file) : null;

package/lib/device/driver.js

@@ -4,7 +4,7 @@
  * only launching, screenshots and the status bar go through simctl or adb.
  */
 import { AgentServer } from 'lynkeus-client';
-import { portFromEnv } from '../config.js';
+import { portFromEnv, readToken } from '../config.js';
 import { withoutHost } from '../knowledge/problems.js';
 import { lifecycleFor } from './platform.js';
 export class Device {
@@ -17,7 +17,7 @@ export class Device {
         this.info = info;
         this.#resolving = options.resolving;
         // The app serves commands only to a driver that presents its token; without one, anything on the loopback could drive a dev build.
-        this.server = options.server ?? new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: portFromEnv() });
+        this.server = options.server ?? new AgentServer({ token: readToken(), port: portFromEnv() });
         this.#lifecycle = lifecycleFor(info.platform);
         this.#appId = options.appId ?? null;
     }

package/lib/mcp/server.js

@@ -59,9 +59,22 @@ const argvFor = (c, input) => {
     }
     return av;
 };
+// What a model is told once, when it connects: the order things are done in, so "set lynkeus up" and "write me
+// a test for this" need nothing more from the person asking.
+const INSTRUCTIONS = `lynkeus drives a React Native app (bare or Expo) by what is on its screen, and runs cases written as readable steps.
+
+In a project you do not know, call status first: it lists what is set up and, for what is not, the one thing that fixes it.
+
+To set lynkeus up: call init (it installs lynkeus-agent, mounts it from the app's entry and makes the project's token; nobody sets a variable). The agent has native code, so the app must then be built again (npx react-native run-ios or run-android; npx expo run:ios or run:android, never Expo Go) with Metro restarted with --reset-cache. Do that with your shell if you have one, or ask the person to. Then status until an app is attached.
+
+To write a test: call case_init once if the project has no cases, and read the README.md it writes for the format. Go to the screen with press, type and wait, calling screen to see what is there; prefer testIDs (#id) over text. Write the case as a markdown file in the cases folder, then call case_run with that file. A failed step comes back with the screen it failed on: fix the case or report the app's bug, do not weaken the check.
+
+To test without a simulator: call headless_init (it installs what the Node host needs and writes its entry; an Expo Router app works too), then headless_doctor for the native modules still to mock, then case_run with host. The backend the app talks to must be local: set apiUrl in lynkeus.config.json.
+
+To share a run: case_run with out, screenshots and push uploads it and prints the report's address. That needs LYNKEUS_REPORTS_KEY in this server's environment.`;
 export const serve = async (session, options = {}) => {
     const { version } = createRequire(import.meta.url)('../../package.json');
-    const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} } });
+    const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     const served = commands().filter((c) => overMcp(c, !!options.full));
     const byName = new Map(served.map((c) => [identifier(c.name), c]));
     // So a model reading the app's screens knows their language before it starts guessing.
@@ -107,5 +120,21 @@ export const serve = async (session, options = {}) => {
             return { ...text(`✗ ${r.error}${r.why ? `\n\nwhy:\n${r.why}` : ''}`), isError: true };
         return text(r.text || (r.json !== undefined ? JSON.stringify(r.json, null, 2) : 'ok'));
     });
-    await server.connect(new StdioServerTransport());
+    // The client going away ends the server: the session holds the driver's port open, and a server left behind
+    // keeps the next one (or a case run) from binding it.
+    const transport = new StdioServerTransport();
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void session
+            .stop()
+            .catch(() => undefined)
+            .finally(() => process.exit(0));
+    };
+    process.stdin.once('end', stop);
+    process.stdin.once('close', stop);
+    transport.onclose = stop;
+    await server.connect(transport);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkeus",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Drive a React Native app running lynkeus-agent from the terminal, a test runner or an MCP client: screens, flows, smoke, crawl, and the app's screen graph.",
   "type": "module",
   "bin": "./lib/cli.js",
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "lynkeus-client": "^0.3.0",
-    "lynkeus-protocol": "^0.3.0",
+    "lynkeus-client": "^0.4.0",
+    "lynkeus-protocol": "^0.4.0",
     "pngjs": "^7.0.0",
     "ts-morph": "^24.0.0",
     "yaml": "^2"

package/src/cases/runner.ts

@@ -91,7 +91,7 @@ export type CaseReport = {
 };
 
 /** Where a case keeps what it can show of itself: a frame per step, a film. Each is taken only where the host can. */
-export type Evidence = { dir: string; screenshots?: boolean; video?: { fps: number } };
+export type Evidence = { dir: string; screenshots?: boolean; settleMs?: number; video?: { fps: number; scale?: number } };
 
 export type RunOptions = {
   base: Base;
@@ -449,7 +449,12 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
         if (looks === 1) await d.waitFor({ target: what, timeoutMs: 1500 }).catch(() => undefined);
         else if (looks === 2) {
           if (await scrollTo(async () => (await seen(params)) === undefined)) return;
-        } else await d.waitFor({ target: what, timeoutMs: 20_000 }).catch(() => undefined);
+        } else {
+          // A step that names its own timeout gets no more than what is left of it; one that does not may
+          // wait for a carousel to come round.
+          const long = typeof params.timeoutMs === 'number' ? Math.max(0, deadline - Date.now()) : 20_000;
+          await d.waitFor({ target: what, timeoutMs: long }).catch(() => undefined);
+        }
         continue;
       }
       if (Date.now() > deadline && Date.now() < hard && (await (await device()).screen()).busy) {
@@ -769,7 +774,8 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
   let filming = false;
   if (film && evidence?.video) {
     const d = await device();
-    filming = await d.command('record', { path: film, fps: evidence.video.fps }).then(
+    // A host that films at one size only ignores the scale.
+    filming = await d.command('record', { path: film, fps: evidence.video.fps, ...(evidence.video.scale ? { scale: evidence.video.scale } : {}) }).then(
       () => true,
       () => false,
     );
@@ -796,9 +802,11 @@ export const runCase = async (c: Case, options: RunOptions): Promise<CaseReport>
     if (evidence?.screenshots) {
       // A step may end mid-transition (a screen fading in, the splash fading out): the frame is of where the
       // step left the app, so two runs' frames of the same step show the same screen.
-      // Long enough for what arrives after a short delay; a screen that never settles (an animation that
-      // keeps going) is noted as such, and its frame is of a moment, not of a state.
-      const settled = await d.idle({ quietMs: 700, timeoutMs: 3000 }).then(
+      // A screen that never settles (an animation that keeps going) is noted as such, and its frame is of a
+      // moment, not of a state. The wait is paid on every step: short for a report, and long enough for what
+      // arrives after a short delay (700 ms) where two runs' frames are compared pixel by pixel.
+      const quietMs = evidence.settleMs ?? 150;
+      const settled = await d.idle({ quietMs, timeoutMs: Math.max(1000, quietMs * 4) }).then(
         (r) => r.idle,
         () => false,
       );

package/src/cli.ts

@@ -13,7 +13,7 @@ import { mapCommands } from './commands/map.js';
 import { osCommands } from './commands/os.js';
 import { reportCommands } from './commands/report.js';
 import { runsCommands } from './commands/runs.js';
-import { graphFile, loadConfig, loadGraph, portFromEnv } from './config.js';
+import { graphFile, loadConfig, loadGraph, portFromEnv, readToken } from './config.js';
 import { agentMismatch } from './device/agentVersion.js';
 import { HEADLESS_HOST, pickAgentDevice, pickAndroidDevice } from './device/devices.js';
 import { Device } from './device/driver.js';
@@ -56,7 +56,7 @@ const contextFor = (argv: string[], attached = false, port?: number, ownHost = f
     const appId = (g.app as string | undefined) ?? process.env.LYNKEUS_APP_ID ?? config.app;
     const started = performance.now();
     const attachedIn = (d: Device) => err(`attached in ${Math.round(performance.now() - started)}ms (${d.info.name})`);
-    const server = new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: port ?? portFromEnv(config) });
+    const server = new AgentServer({ token: readToken(root), port: port ?? portFromEnv(config) });
     server.on('hello', (hello: HelloEvent) => {
       const told = mismatchTold ? undefined : agentMismatch(hello);
       if (!told) return;