lynkeus 0.2.0

package/lib/knowledge/screens.js

@@ -0,0 +1,125 @@
+/**
+ * The structure of each route the last time it was read, under
+ * .lynkeus/screens/, and in changes.jsonl every testID that appeared,
+ * disappeared or moved since: a suite that never asserts on an element still
+ * tells you the day it vanished.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { diffScreens } from '../flow/artifacts.js';
+import { appendJsonl, readJsonl, today } from '../files.js';
+// Sub-pixel rounding and font hinting move an element a point or two without any layout change.
+const GEOMETRY_TOLERANCE = 4;
+const presented = (e) => !e.hidden || e.hidden === 'inert';
+const framesOf = (screen) => {
+    const out = {};
+    for (const e of screen.elements.filter(presented)) {
+        if (!e.testId || !e.frame || out[e.testId])
+            continue;
+        out[e.testId] = { x: Math.round(e.frame.x), y: Math.round(e.frame.y), w: Math.round(e.frame.w), h: Math.round(e.frame.h) };
+    }
+    return out;
+};
+export const diffGeometry = (before, after, tolerance = GEOMETRY_TOLERANCE) => {
+    const lines = [];
+    for (const [id, a] of Object.entries(after)) {
+        const b = before[id];
+        if (!b)
+            continue;
+        const moved = Math.abs(a.x - b.x) > tolerance || Math.abs(a.y - b.y) > tolerance;
+        const resized = Math.abs(a.w - b.w) > tolerance || Math.abs(a.h - b.h) > tolerance;
+        const collapsed = (a.w === 0 || a.h === 0) && b.w > 0 && b.h > 0;
+        if (collapsed)
+            lines.push(`#${id} collapsed to ${a.w}×${a.h} (was ${b.w}×${b.h})`);
+        else if (moved && resized)
+            lines.push(`#${id} moved (${b.x},${b.y})→(${a.x},${a.y}) and resized ${b.w}×${b.h}→${a.w}×${a.h}`);
+        else if (moved)
+            lines.push(`#${id} moved (${b.x},${b.y})→(${a.x},${a.y})`);
+        else if (resized)
+            lines.push(`#${id} resized ${b.w}×${b.h}→${a.w}×${a.h}`);
+    }
+    return lines;
+};
+const dirOf = (lynkeusDir) => path.join(lynkeusDir, 'screens');
+const fileOf = (lynkeusDir, route) => path.join(dirOf(lynkeusDir), `${route.replace(/[^\w.-]/g, '_')}.json`);
+const changesFile = (lynkeusDir) => path.join(dirOf(lynkeusDir), 'changes.jsonl');
+const strip = (screen) => screen.elements.filter(presented).map((e) => {
+    const { frame: _frame, ...rest } = e;
+    return rest;
+});
+const label = (e) => `${e.kind}${e.testId ? ` #${e.testId}` : ''}${e.text ? ` ${JSON.stringify(e.text.slice(0, 60))}` : ''}`;
+/** Stores the screen under its route and returns what changed since the previous read. */
+export const record = (lynkeusDir, screen) => {
+    if (!screen.route)
+        return null;
+    fs.mkdirSync(dirOf(lynkeusDir), { recursive: true });
+    const file = fileOf(lynkeusDir, screen.route);
+    const date = today();
+    const elements = strip(screen);
+    let previous = null;
+    try {
+        previous = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch { }
+    const frames = framesOf(screen);
+    const next = { route: screen.route, path: screen.path, seen: (previous?.seen ?? 0) + 1, date, elements, frames };
+    fs.writeFileSync(file, JSON.stringify(next, null, 1));
+    if (!previous)
+        return null;
+    const diff = diffScreens({ ...screen, elements: previous.elements }, { ...screen, elements });
+    // Texts carry values that change every run; only a testID appearing or disappearing is worth a line.
+    const added = diff.added.filter((e) => e.testId).map(label);
+    const removed = diff.removed.filter((e) => e.testId).map(label);
+    const moved = previous.frames ? diffGeometry(previous.frames, frames) : [];
+    if (added.length === 0 && removed.length === 0 && moved.length === 0)
+        return null;
+    const change = {
+        route: screen.route,
+        date,
+        added,
+        removed,
+        moved,
+        changedText: diff.changedText.map((c) => `#${c.after.testId}: ${JSON.stringify(c.before.text ?? '')} → ${JSON.stringify(c.after.text ?? '')}`).slice(0, 10),
+    };
+    appendJsonl(changesFile(lynkeusDir), change);
+    return change;
+};
+/** What runs have seen, by route: the routes and interpolated testIDs a static parser cannot find. */
+export const observed = (lynkeusDir) => {
+    const out = new Map();
+    let files = [];
+    try {
+        files = fs.readdirSync(dirOf(lynkeusDir)).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return out;
+    }
+    for (const file of files) {
+        let stored;
+        try {
+            stored = JSON.parse(fs.readFileSync(path.join(dirOf(lynkeusDir), file), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!stored.route)
+            continue;
+        const testIds = [];
+        for (const e of stored.elements ?? []) {
+            if (!e.testId || e.hidden)
+                continue;
+            if (!testIds.includes(e.testId))
+                testIds.push(e.testId);
+        }
+        out.set(stored.route, { route: stored.route, path: stored.path ?? [], seen: stored.seen ?? 1, date: stored.date, testIds });
+    }
+    return out;
+};
+export const changes = (lynkeusDir, last = 50) => readJsonl(changesFile(lynkeusDir)).slice(-last);
+export const describeChange = (c) => [
+    `${c.date}  ${c.route}`,
+    ...c.added.map((a) => `    + ${a}`),
+    ...c.removed.map((r) => `    - ${r}`),
+    ...(c.moved ?? []).map((m) => `    ⇢ ${m}`),
+    ...c.changedText.map((t) => `    ~ ${t}`),
+].join('\n');

package/lib/knowledge/tree.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The screen as nested lines of meaning (kinds, labels, testIDs, values,
+ * states) and no geometry: a spacing tweak changes nothing, a renamed heading
+ * or a lost button is a changed line. Diffed like code.
+ */
+import type { Screen } from 'lynkeus-protocol';
+export declare const screenTree: (screen: Screen) => string;
+export type TreeDiff = {
+    added: string[];
+    removed: string[];
+    same: number;
+};
+/** The lines only one side has. */
+export declare const diffTrees: (before: string, after: string) => TreeDiff;
+export declare const describeTreeDiff: (d: TreeDiff) => string;

package/lib/knowledge/tree.js

@@ -0,0 +1,63 @@
+const quote = (s) => JSON.stringify(s);
+const node = (e) => {
+    const parts = [e.kind];
+    const label = e.text ?? e.accessibilityLabel;
+    if (label)
+        parts.push(quote(label.length > 80 ? `${label.slice(0, 77)}…` : label));
+    if (e.testId)
+        parts.push(`#${e.testId}`);
+    if (e.value !== undefined && e.value !== '')
+        parts.push(`value=${quote(e.value)}`);
+    if (e.placeholder)
+        parts.push(`placeholder=${quote(e.placeholder)}`);
+    const state = [!e.enabled ? 'disabled' : '', e.covered ? 'covered' : '', e.hidden ?? '', e.focused ? 'focused' : ''].filter(Boolean);
+    if (state.length)
+        parts.push(`[${state.join(' ')}]`);
+    return parts.join(' ');
+};
+const meaningful = (e) => e.kind !== 'view' || e.accessibilityLabel !== undefined || e.testId !== undefined;
+export const screenTree = (screen) => {
+    const lines = [`- screen ${screen.route ?? '?'}${screen.path.length > 1 ? ` (${screen.path.join(' > ')})` : ''}`];
+    // Relative to the nearest listed ancestor, so the layout views left out leave no gaps.
+    const level = new Map();
+    for (const e of screen.elements) {
+        const parentLevel = e.parent !== undefined && e.parent >= 0 ? (level.get(e.parent) ?? 0) : 0;
+        if (!meaningful(e)) {
+            level.set(e.i, parentLevel);
+            continue;
+        }
+        const mine = parentLevel + 1;
+        level.set(e.i, mine);
+        lines.push(`${'  '.repeat(mine)}- ${node(e)}`);
+    }
+    return `${lines.join('\n')}\n`;
+};
+/** The lines only one side has. */
+export const diffTrees = (before, after) => {
+    const a = before.split('\n').filter(Boolean);
+    const b = after.split('\n').filter(Boolean);
+    const countA = new Map();
+    for (const l of a)
+        countA.set(l, (countA.get(l) ?? 0) + 1);
+    const added = [];
+    let same = 0;
+    for (const l of b) {
+        const n = countA.get(l) ?? 0;
+        if (n > 0) {
+            countA.set(l, n - 1);
+            same += 1;
+        }
+        else
+            added.push(l);
+    }
+    const removed = [];
+    for (const [l, n] of countA)
+        for (let i = 0; i < n; i++)
+            removed.push(l);
+    return { added, removed, same };
+};
+export const describeTreeDiff = (d) => {
+    if (!d.added.length && !d.removed.length)
+        return '  (the tree did not change)';
+    return [...d.removed.map((l) => `- ${l.trim()}`), ...d.added.map((l) => `+ ${l.trim()}`)].map((l) => `  ${l}`).join('\n');
+};

package/lib/knowledge/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What lynkeus reads from an app's source. Facts are kept per file and
+ * attributed to screens by traversal: most testIDs and navigations live in
+ * shared components, so attributing them at extraction would always miss some.
+ */
+/** As declared to the navigator, e.g. `Settings.Profile`. */
+export type RouteName = string;
+/** Relative to the app's root. */
+export type SourcePath = string;
+/** A testID written as a literal; one built at runtime is only found on the device. */
+export type Selector = {
+    id: string;
+    line: number;
+};
+/** What the user touches to cause a navigation. */
+export type NavigationTrigger = {
+    kind: 'testId';
+    testId: string;
+}
+/** The element has a testID built at runtime. */
+ | {
+    kind: 'dynamicTestId';
+    expression: string;
+}
+/** Nothing to attribute it to: conditional routing, effects, deep links. */
+ | {
+    kind: 'unknown';
+};
+export type NavigationEdge = {
+    /** The route when it is a literal, otherwise the source expression. */
+    to: string;
+    line: number;
+    confidence: 'static' | 'dynamic';
+    via: NavigationTrigger;
+    /** `element` when the call sits in the element's own handler, `handler` when it was reached through a named function. */
+    linkage?: 'element' | 'handler';
+};
+export type FileFacts = {
+    selectors: Selector[];
+    navigates: NavigationEdge[];
+    /** First-party imports; a name imported through a barrel points at the file that defines it. */
+    imports: SourcePath[];
+    /** The barrels those names came through: a dependency only when the barrel itself changes. */
+    barrels?: SourcePath[];
+};
+export type ScreenNode = {
+    route: RouteName;
+    /** The component bound in the navigator. */
+    component: string;
+    /** Null when the component could not be resolved to a file. */
+    file: SourcePath | null;
+    declaredIn: SourcePath;
+};
+export type ScreenGraph = {
+    app: string;
+    root: string;
+    extractedAt: string;
+    screens: Record<RouteName, ScreenNode>;
+    files: Record<SourcePath, FileFacts>;
+    /** What could not be read, so the graph is never silently wrong. */
+    warnings: string[];
+};

package/lib/knowledge/types.js

@@ -0,0 +1,6 @@
+/**
+ * What lynkeus reads from an app's source. Facts are kept per file and
+ * attributed to screens by traversal: most testIDs and navigations live in
+ * shared components, so attributing them at extraction would always miss some.
+ */
+export {};

package/lib/knowledge/why.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The screen, the last requests and the trace after a failure, read the way a
+ * person would: a dead navigator, a gone session, a 5xx, a covered target, a
+ * wording difference, a screen still loading. Each rule names what to do next.
+ */
+import type { RequestRecord, Screen, TraceEvent } from 'lynkeus-protocol';
+export type Evidence = {
+    screen: Screen;
+    requests: RequestRecord[];
+    inFlight: number;
+    trace?: TraceEvent[];
+    /** What the failed command was looking for. */
+    target?: {
+        testId?: string;
+        text?: string;
+        route?: string;
+    };
+};
+export type Finding = {
+    rule: string;
+    message: string;
+};
+export declare const explain: (e: Evidence) => Finding[];
+export declare const describeWhy: (findings: Finding[]) => string;

package/lib/knowledge/why.js

@@ -0,0 +1,153 @@
+import { pathOf } from './problems.js';
+const fold = (t) => t
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .trim();
+const distance = (a, b) => {
+    const m = a.length;
+    const n = b.length;
+    let prev = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+        const cur = [i];
+        for (let j = 1; j <= n; j++)
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        prev = cur;
+    }
+    return prev[n];
+};
+const similar = (a, b) => {
+    if (a.includes(b) || b.includes(a))
+        return true;
+    if (a.length > 200 || b.length > 200)
+        return false;
+    return distance(a, b) <= Math.max(2, Math.floor(Math.max(a.length, b.length) * 0.25));
+};
+export const explain = (e) => {
+    const out = [];
+    const els = e.screen.elements;
+    const done = e.requests.filter((r) => r.status !== undefined || r.error);
+    const status = (n) => done.filter((r) => r.status === n);
+    if (!e.screen.route && els.length === 0) {
+        const crash = e.trace
+            ?.slice()
+            .reverse()
+            .find((t) => t.kind === 'crash');
+        out.push(crash && crash.kind === 'crash'
+            ? {
+                rule: 'dead-navigator',
+                message: `the screen is empty and has no route: a component threw and took the tree with it — ${crash.message}${crash.stack ? `\n    ${crash.stack.split('\n').slice(1, 4).join('\n    ')}` : ''}`,
+            }
+            : {
+                rule: 'dead-navigator',
+                message: 'the screen is empty and has no route: a component threw while rendering. Reset the app and look for the render error in the host log.',
+            });
+    }
+    if (done.length && done.every((r) => r.status === 401))
+        out.push({
+            rule: 'session-gone',
+            message: 'every request answered 401: the session is gone (a logout, a reset, or a key revoked elsewhere). Log in again.',
+        });
+    const forbidden = status(403);
+    if (forbidden.length >= 2)
+        out.push({
+            rule: 'forbidden',
+            message: `the backend refuses ${[...new Set(forbidden.map((r) => pathOf(r.url)))].slice(0, 3).join(', ')} with 403: an account state or a permission, not the screen. Check what the case expects of this user.`,
+        });
+    const five = done.find((r) => (r.status ?? 0) >= 500);
+    if (five)
+        out.push({
+            rule: 'backend-error',
+            message: `the backend answered ${five.status} on ${five.method} ${pathOf(five.url)}: a server error, not the app. Reproduce it with curl before touching the case.`,
+        });
+    if (status(429).length)
+        out.push({
+            rule: 'rate-limited',
+            message: 'a request answered 429: the backend is rate limiting this client. Space the runs out or raise the limit locally.',
+        });
+    const stall = e.trace
+        ?.slice()
+        .reverse()
+        .find((t) => t.kind === 'stall');
+    if (stall && stall.kind === 'stall')
+        out.push({
+            rule: 'render-loop',
+            message: `the host broke a render loop${stall.component ? ` in ${stall.component}` : ''} (${stall.renders} updates in ${stall.windowMs}ms): the screen is dead until a reset. A component whose effect and store feed each other.`,
+        });
+    if (e.target) {
+        const { testId, text, route } = e.target;
+        const match = (el) => (testId && el.testId === testId) || (text && (el.text === text || el.accessibilityLabel === text));
+        const found = els.find(match);
+        if (found?.hidden) {
+            out.push({
+                rule: 'hidden',
+                message: `${testId ? `#${testId}` : JSON.stringify(text)} is in the tree but not presented (${found.hidden}): it belongs to a screen the app is not showing. Close what is open, or target something inside it.`,
+            });
+        }
+        if (found?.covered)
+            out.push({
+                rule: 'covered',
+                message: `${testId ? `#${testId}` : JSON.stringify(text)} is on the screen but covered: a sheet or overlay is over it. Close it, or press what covers it.`,
+            });
+        if (found && !found.enabled)
+            out.push({
+                rule: 'disabled',
+                message: `${testId ? `#${testId}` : JSON.stringify(text)} is on the screen but disabled: a form is not valid yet, or a request it depends on is in flight.`,
+            });
+        if (!found && text) {
+            const want = fold(text);
+            const near = els
+                .map((el) => el.text ?? el.accessibilityLabel)
+                .filter((t) => !!t)
+                .find((t) => similar(fold(t), want));
+            if (near && near !== text)
+                out.push({ rule: 'near-match', message: `the text is not there, but ${JSON.stringify(near)} is: a wording, accent or case difference?` });
+            const listed = els.filter((el) => el.testId && /-\d+-item$/.test(el.testId));
+            const prefix = want.slice(0, 4);
+            if (listed.length >= 10 && prefix && listed.filter((el) => fold(el.text ?? '').includes(prefix)).length >= listed.length / 2)
+                out.push({
+                    rule: 'capped-list',
+                    message: `the list shows ${listed.length} near matches and yours is not among them: the data has accumulated look-alikes and the list is capped. Search by something unique, or reset the data.`,
+                });
+        }
+        if (route && e.screen.route && e.screen.route !== route) {
+            const recent = e.trace
+                ?.filter((t) => t.kind === 'route')
+                .slice(-3)
+                .map((t) => (t.kind === 'route' ? t.route : undefined))
+                .filter(Boolean) ?? [];
+            if (recent.includes(route))
+                out.push({
+                    rule: 'route-left',
+                    message: `the app was on ${route} and moved to ${e.screen.route}: something navigated after the step (a redirect, a gate, a modal). The trace shows the order.`,
+                });
+        }
+    }
+    if (e.inFlight > 0)
+        out.push({
+            rule: 'in-flight',
+            message: `${e.inFlight} request(s) still in flight when the command gave up: the screen had not finished loading. A longer timeout, or wait for the request it needs.`,
+        });
+    if (done.length === 0 && e.inFlight === 0 && e.target?.route)
+        out.push({
+            rule: 'no-requests',
+            message: 'no request left the app while this ran: nothing was fetched. Is the user logged in, and is the app talking to the backend it should?',
+        });
+    // Hosts the sandbox refuses are usually third parties nobody needs: named only when nothing else explains it.
+    const refused = done.filter((r) => r.status === 0 && r.error && /networkHosts|is off/.test(r.error));
+    if (refused.length && e.target && out.length === 0)
+        out.push({
+            rule: 'host-refused',
+            message: `${refused.length} request(s) were refused by the host (${[...new Set(refused.map((r) => r.url.replace(/^https?:\/\//, '').split('/')[0]))].slice(0, 3).join(', ')}): if the screen needs one of them, allow the host in networkHosts or mock it.`,
+        });
+    const lastCommand = e.trace
+        ?.slice()
+        .reverse()
+        .find((t) => t.kind === 'command' && t.error);
+    if (lastCommand && lastCommand.kind === 'command' && out.length === 0)
+        out.push({ rule: 'last-error', message: `the last command that failed was ${lastCommand.method}: ${lastCommand.error}` });
+    return out;
+};
+export const describeWhy = (findings) => findings.length
+    ? findings.map((f) => `  • ${f.message}`).join('\n')
+    : '  (nothing in the evidence explains it: the screen, requests and trace look ordinary)';

package/lib/mcp/server.d.ts

@@ -0,0 +1,4 @@
+import type { Session } from '../cli.js';
+export declare const serve: (session: Session, options?: {
+    full?: boolean;
+}) => Promise<void>;

package/lib/mcp/server.js

@@ -0,0 +1,111 @@
+import { createRequire } from 'node:module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { commands, overMcp } from '../registry.js';
+import { execute } from '../runtime.js';
+import { TARGET_HELP } from '../targets.js';
+const text = (body) => ({ content: [{ type: 'text', text: body }] });
+const propertyFor = (f) => ({
+    type: f.type === 'list' ? 'array' : f.type,
+    ...(f.type === 'list' ? { items: { type: 'string' } } : {}),
+    description: f.help + (f.default !== undefined ? ` (default ${f.default})` : ''),
+});
+const describe = (c) => {
+    const details = c.mcpDetails ?? c.details;
+    return details ? `${c.summary}\n\n${details}` : c.summary;
+};
+const identifier = (name) => name.replace(/[^a-z0-9]+/gi, '_');
+// Written by hand: a schema library adds fields to every tool that a model pays for on every turn.
+const schemaFor = (c) => {
+    const properties = {};
+    const required = [];
+    for (const p of c.positionals ?? []) {
+        const key = identifier(p.name);
+        properties[key] = p.rest ? { type: 'array', items: { type: 'string' }, description: p.help } : { type: 'string', description: p.help };
+        if (p.required)
+            required.push(key);
+    }
+    for (const [name, f] of Object.entries(c.flags ?? {}))
+        if (!c.mcpOmit?.includes(name))
+            properties[identifier(name)] = propertyFor(f);
+    return { type: 'object', properties, ...(required.length ? { required } : {}) };
+};
+/** Back to an argv, so the same runtime serves both surfaces. */
+const argvFor = (c, input) => {
+    const av = c.name.split(' ');
+    for (const p of c.positionals ?? []) {
+        const v = input[identifier(p.name)];
+        if (v === undefined)
+            continue;
+        if (Array.isArray(v))
+            av.push(...v.map(String));
+        else
+            av.push(String(v));
+    }
+    for (const [name, f] of Object.entries(c.flags ?? {})) {
+        const v = input[identifier(name)];
+        if (v === undefined)
+            continue;
+        if (f.type === 'boolean') {
+            if (v)
+                av.push(`--${name}`);
+        }
+        else if (f.type === 'list')
+            for (const item of v)
+                av.push(`--${name}`, item);
+        else
+            av.push(`--${name}`, String(v));
+    }
+    return av;
+};
+export const serve = async (session, options = {}) => {
+    const { version } = createRequire(import.meta.url)('../../package.json');
+    const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} } });
+    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.
+    const { config } = session.ctx;
+    const locale = config.language || config.locale ? JSON.stringify({ language: config.language, ...config.locale }, null, 2) : undefined;
+    // The grammar of a target is spelled where a model meets it first; after that it is a word.
+    let spelled = false;
+    const once = (help) => {
+        if (!help.includes(TARGET_HELP))
+            return help;
+        const out = spelled ? help.replace(TARGET_HELP, 'target') : help;
+        spelled = true;
+        return out;
+    };
+    const tools = served.map((c) => {
+        const schema = schemaFor(c);
+        for (const property of Object.values(schema.properties))
+            property.description = once(property.description);
+        return { name: identifier(c.name), description: describe(c), inputSchema: schema };
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            ...(locale
+                ? [
+                    {
+                        name: 'app_locale',
+                        description: 'The language and region this app is built for, as its own configuration declares them.',
+                        inputSchema: { type: 'object', properties: {} },
+                    },
+                ]
+                : []),
+            ...tools,
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (request.params.name === 'app_locale' && locale)
+            return text(locale);
+        const c = byName.get(request.params.name);
+        if (!c)
+            return { ...text(`✗ no tool ${request.params.name}`), isError: true };
+        const r = await execute(argvFor(c, (request.params.arguments ?? {})), session.ctx);
+        if (r.error)
+            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());
+};

package/lib/registry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * One definition per command, read by every surface: the terminal's parser and
+ * usage, session lines, the MCP tools and the reference document.
+ */
+import type { LynkeusConfig } from './config.js';
+import type { Device } from './device/driver.js';
+import type { ScreenGraph } from './knowledge/types.js';
+import { type FlagSpec, type FlagValues, type PositionalSpec } from './args.js';
+export type Group = 'drive' | 'os' | 'map' | 'runs' | 'headless';
+/** What a command runs against: one per process, or per session or MCP server. */
+export type Base = {
+    root: string;
+    config: LynkeusConfig;
+    /** The live app, connected on first use. */
+    device: () => Promise<Device>;
+    /** The static graph; throws with advice when there is none. */
+    graph: () => ScreenGraph;
+    /** Progress and diagnostics, on stderr. */
+    err: (line: string) => void;
+    /** Inside `lynkeus session` and over MCP: one connection, many commands. */
+    attached: boolean;
+};
+export type Ctx = Base & {
+    args: string[];
+    flags: FlagValues;
+    passthrough: string[];
+};
+export type Result = {
+    /** What a person reads; the JSON on one line when left out. */
+    text?: string;
+    /** What a program reads; printed instead of the text under --json. */
+    json?: unknown;
+    code?: number;
+};
+export type Command = {
+    /** `press`, or `map build` for a grouped command. */
+    name: string;
+    group: Group;
+    summary: string;
+    /** Longer help, for `lynkeus help <command>` and the reference. */
+    details?: string;
+    positionals?: PositionalSpec[];
+    flags?: Record<string, FlagSpec>;
+    /** Other spellings it answers to, left out of the usage. */
+    aliases?: string[];
+    needs: 'nothing' | 'graph' | 'app';
+    /** `core` is served to every MCP client; other commands that need the app or the graph only with `mcp --full`. */
+    mcp?: boolean | 'core';
+    /** Flags a model has no use for (artifacts, timing knobs): left out of the MCP schema. */
+    mcpOmit?: string[];
+    /** What a model is told instead of `details`. */
+    mcpDetails?: string;
+    /** Runnable from a session line (default: when it needs the app or the graph). */
+    session?: boolean;
+    /** The usage line, when the generated one would mislead. */
+    example?: string;
+    run: (ctx: Ctx) => Promise<Result | string | undefined>;
+};
+export declare const define: (c: Command) => Command;
+export declare const register: (commands: Command[]) => void;
+export declare const commands: () => Command[];
+export declare const find: (name: string) => Command | undefined;
+/** The command an argv names, and the rest of the argv. */
+export declare const resolve: (argv: string[]) => {
+    command: Command;
+    rest: string[];
+} | undefined;
+export declare const parseFor: (command: Command, rest: string[]) => {
+    args: string[];
+    flags: FlagValues;
+    passthrough: string[];
+};
+export declare const inSession: (c: Command) => boolean;
+export declare const overMcp: (c: Command, full: boolean) => boolean;
+export declare const usage: () => string;
+export declare const helpFor: (c: Command) => string;
+/** The reference document, generated so it cannot drift from the commands. */
+export declare const referenceMarkdown: () => string;