lynkeus 0.4.0 → 0.5.0

package/lib/commands/coverage.js

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

package/lib/commands/device.js

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

package/lib/commands/drive.js

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

package/lib/commands/fixtures.d.ts

@@ -0,0 +1,7 @@
+import { type Description } from '../cases/fixtures.js';
+/** What a server keeps of the contract and what it leaves out, as lines a person can act on. */
+export declare const checkDescription: (d: Description | undefined) => {
+    ok: boolean;
+    lines: string[];
+};
+export declare const fixturesCommands: import("../registry.js").Command[];

package/lib/commands/fixtures.js

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

package/lib/commands/headless.d.ts

@@ -1 +1,12 @@
+/**
+ * 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 declare const cacheFor: (root: string, env: Record<string, string | undefined>, apiEnv?: string) => string;
+/**
+ * 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 declare const duplicateReact: (root: string) => string | undefined;
 export declare const headlessCommands: import("../registry.js").Command[];

package/lib/commands/headless.js

@@ -1,5 +1,7 @@
 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, readToken } from '../config.js';
 import { describeExplanations, explainError } from '../knowledge/errors.js';
@@ -30,6 +32,17 @@ 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
@@ -55,6 +68,22 @@ const aliasesOf = (root) => {
  * 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') : '';
@@ -66,13 +95,23 @@ const jestDefaults = (root) => {
         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) })}`);
+        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'))
@@ -175,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', ...jestDefaults(ctx.root), ...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: { ...apiFromConfig(ctx.config), ...process.env, LYNKEUS_TOKEN: token, 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)

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;

package/lib/commands/map.js

@@ -25,6 +25,23 @@ const describeAffected = (affected, chain) => {
     }
     return lines;
 };
+/** Source files a branch changed against `base`, committed or not. */
+export const changedSources = (root, base, err) => {
+    const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' });
+    try {
+        const names = `${git('diff', '--name-only', `${base}...HEAD`)}\n${git('diff', '--name-only', 'HEAD')}`;
+        return [
+            ...new Set(names
+                .split('\n')
+                .map((l) => l.trim())
+                .filter((l) => /\.[cm]?[jt]sx?$/.test(l))),
+        ];
+    }
+    catch (error) {
+        err(`could not diff against ${base}: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+};
 export const mapCommands = [
     define({
         name: 'map build',
@@ -214,20 +231,7 @@ export const mapCommands = [
         run: async (ctx) => {
             const graph = ctx.graph();
             const base = ctx.flags.base;
-            const git = (...args) => execFileSync('git', args, { cwd: ctx.root, encoding: 'utf8' });
-            let changed = [];
-            try {
-                const names = `${git('diff', '--name-only', `${base}...HEAD`)}\n${git('diff', '--name-only', 'HEAD')}`;
-                changed = [
-                    ...new Set(names
-                        .split('\n')
-                        .map((l) => l.trim())
-                        .filter((l) => /\.[cm]?[jt]sx?$/.test(l))),
-                ];
-            }
-            catch (error) {
-                ctx.err(`could not diff against ${base}: ${error instanceof Error ? error.message : String(error)}`);
-            }
+            const changed = changedSources(ctx.root, base, ctx.err);
             const affected = screensAffectedBy(graph, changed, ctx.flags.depth);
             const lines = [`changed against ${base}: ${changed.length} source file(s)`, ...describeAffected(affected, true)];
             if (!affected.length && changed.length)

package/lib/commands/os.js

@@ -30,11 +30,27 @@ export const osCommands = [
     define({
         name: 'os appstate',
         group: 'os',
-        summary: 'Headless: AppState listeners see the change (background, then active: what refetches or re-locks)',
-        positionals: [{ name: 'state', help: 'active | background | inactive', required: true }],
+        summary: 'AppState listeners see the change (background, then active: what refetches or re-locks); a host answers it, a simulator or an emulator does it for real',
+        positionals: [{ name: 'state', help: 'active | background | inactive (inactive: a host only)', required: true }],
+        flags: { app: { type: 'string', help: 'the app to bring back on a simulator or emulator (default: the config’s app)', value: 'bundleId' } },
         aliases: ['appstate'],
         needs: 'app',
-        run: agent('appstate', (ctx) => ({ state: ctx.args[0] })),
+        run: async (ctx) => {
+            const device = await ctx.device();
+            try {
+                return { json: await device.command('appstate', { state: ctx.args[0] }) };
+            }
+            catch (error) {
+                // A host stands in for the OS; on a simulator or an emulator the OS itself moves the app.
+                if ((await device.resolved()).id === 'headless')
+                    throw error;
+                const done = await simulator('appstate')(ctx);
+                // Back in front, the app dials in again; what comes next reads its screen.
+                if (ctx.args[0] === 'active')
+                    await device.server.waitForApp(15_000);
+                return done;
+            }
+        },
     }),
     define({
         name: 'os network',
@@ -61,7 +77,7 @@ export const osCommands = [
     define({
         name: 'os biometrics',
         group: 'os',
-        summary: 'Headless: the sensor and what the next prompts answer',
+        summary: 'The sensor and what the next prompts answer; on a simulator, --available enrolls Face ID or Touch ID or not',
         flags: {
             available: { type: 'string', help: 'FaceID | TouchID | none', value: 'kind' },
             next: { type: 'string', help: 'outcomes of the next prompts, in order', value: 'success,fail,cancel' },
@@ -69,11 +85,28 @@ export const osCommands = [
         },
         aliases: ['biometrics'],
         needs: 'app',
-        run: agent('biometrics', ({ flags }) => ({
-            available: flags.available || undefined,
-            next: flags.next ? flags.next.split(',') : undefined,
-            fallback: flags.fallback || undefined,
-        })),
+        run: async (ctx) => {
+            const device = await ctx.device();
+            const params = {
+                available: ctx.flags.available || undefined,
+                next: ctx.flags.next ? ctx.flags.next.split(',') : undefined,
+                fallback: ctx.flags.fallback || undefined,
+            };
+            try {
+                return { json: await device.command('biometrics', params) };
+            }
+            catch (error) {
+                const info = await device.resolved();
+                if (info.id === 'headless')
+                    throw error;
+                // A device's prompts answer the person in front of it: only a simulator's enrollment is set from outside.
+                // Anything else stays the host's, and the runner says the step cannot run here.
+                if (info.platform !== 'ios' || !params.available || params.next || params.fallback)
+                    throw error;
+                ctx.args = [String(params.available)];
+                return simulator('biometrics')(ctx);
+            }
+        },
     }),
     define({
         name: 'os scan',
@@ -102,7 +135,7 @@ export const osCommands = [
     define({
         name: 'mock',
         group: 'os',
-        summary: 'Headless: answer a request before the network (--sticky survives a reset)',
+        summary: 'Answer a request before the network: a host stands in for it, on a device the agent answers in the app (--sticky survives a host reset)',
         positionals: [{ name: 'route', help: "'GET /path' (a bare path matches any method)" }],
         flags: {
             status: { type: 'number', help: 'HTTP status to answer', default: 200, value: 'code' },

package/lib/commands/report.d.ts

@@ -10,6 +10,8 @@ export type Pushed = {
 };
 /** What a run changed against the one before, in a line or two for a terminal or a pull request comment. */
 export declare const describeChanges: (changes: Pushed["changes"]) => string[];
+/** An uncompressed tar: frames are PNG or AVIF, already compressed, and a tar is read as it arrives. */
+export declare const tarOf: (entries: [string, Uint8Array][]) => Uint8Array;
 /**
  * Uploads a run directory (`case run --out`) to the reports service: the run, its cases, then every frame and
  * film the cases name. A file the organization's plan does not keep (a film on Free) is left out and listed.
@@ -19,6 +21,8 @@ export declare const pushRun: (dir: string, o: {
     key: string;
     project: string;
     fetch?: Fetch;
+    onReady?: (url: string) => void;
+    onProgress?: (line: string) => void;
 }) => Promise<Pushed>;
 type Service = {
     url: string;