lynkeus 0.2.0

package/src/knowledge/why.ts

@@ -0,0 +1,189 @@
+/**
+ * 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 { Element, RequestRecord, Screen, TraceEvent } from 'lynkeus-protocol';
+
+import { pathOf } from './problems.js';
+
+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 };
+
+const fold = (t: string): string =>
+  t
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .trim();
+
+const distance = (a: string, b: string): number => {
+  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: string, b: string): boolean => {
+  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: Evidence): Finding[] => {
+  const out: Finding[] = [];
+  const els = e.screen.elements;
+  const done = e.requests.filter((r) => r.status !== undefined || r.error);
+  const status = (n: number) => 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: Element) => (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 is string => !!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: Finding[]): string =>
+  findings.length
+    ? findings.map((f) => `  • ${f.message}`).join('\n')
+    : '  (nothing in the evidence explains it: the screen, requests and trace look ordinary)';

package/src/mcp/server.ts

@@ -0,0 +1,109 @@
+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 type { FlagSpec } from '../args.js';
+import type { Session } from '../cli.js';
+import { type Command, commands, overMcp } from '../registry.js';
+import { execute } from '../runtime.js';
+import { TARGET_HELP } from '../targets.js';
+
+const text = (body: string) => ({ content: [{ type: 'text' as const, text: body }] });
+
+type Property = { type: string; items?: { type: string }; description: string };
+
+const propertyFor = (f: FlagSpec): Property => ({
+  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: Command) => {
+  const details = c.mcpDetails ?? c.details;
+  return details ? `${c.summary}\n\n${details}` : c.summary;
+};
+
+const identifier = (name: string) => 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: Command) => {
+  const properties: Record<string, Property> = {};
+  const required: string[] = [];
+  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' as const, properties, ...(required.length ? { required } : {}) };
+};
+
+/** Back to an argv, so the same runtime serves both surfaces. */
+const argvFor = (c: Command, input: Record<string, unknown>): string[] => {
+  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 as string[]) av.push(`--${name}`, item);
+    else av.push(`--${name}`, String(v));
+  }
+  return av;
+};
+
+export const serve = async (session: Session, options: { full?: boolean } = {}) => {
+  const { version } = createRequire(import.meta.url)('../../package.json') as { version: string };
+  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: string) => {
+    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' as const, 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 ?? {}) as Record<string, unknown>), 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/src/registry.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 { GLOBAL_FLAGS, parseArgs, type FlagSpec, type FlagValues, type PositionalSpec } from './args.js';
+
+export type Group = 'drive' | 'os' | 'map' | 'runs' | 'headless';
+
+const GROUPS: Record<Group, { title: string; blurb: string }> = {
+  drive: { title: 'Drive', blurb: 'the app that is running, through the agent inside it' },
+  os: { title: 'os', blurb: 'what the outside world hands the app: links, clock, sensors, the network, the simulator' },
+  map: { title: 'map', blurb: "what lynkeus knows before touching anything, from the app's source and from walks" },
+  runs: { title: 'Runs', blurb: 'flows, smokes, crawls and recordings' },
+  headless: { title: 'headless', blurb: 'the app hosted in Node under jest, no simulator' },
+};
+
+/** 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 const define = (c: Command): Command => c;
+
+const byName = new Map<string, Command>();
+const all: Command[] = [];
+
+export const register = (commands: Command[]): void => {
+  for (const c of commands) {
+    for (const name of [c.name, ...(c.aliases ?? [])]) {
+      if (byName.has(name)) throw new Error(`${name} is defined twice`);
+      byName.set(name, c);
+    }
+    all.push(c);
+  }
+};
+
+export const commands = (): Command[] => all;
+export const find = (name: string): Command | undefined => byName.get(name);
+
+/** The command an argv names, and the rest of the argv. */
+export const resolve = (argv: string[]): { command: Command; rest: string[] } | undefined => {
+  const two = argv.length >= 2 ? byName.get(argv.slice(0, 2).join(' ')) : undefined;
+  if (two) return { command: two, rest: argv.slice(2) };
+  const one = argv[0] ? byName.get(argv[0]) : undefined;
+  return one ? { command: one, rest: argv.slice(1) } : undefined;
+};
+
+export const parseFor = (command: Command, rest: string[]) => parseArgs(rest, command.positionals, command.flags);
+
+export const inSession = (c: Command): boolean => c.session ?? c.needs !== 'nothing';
+
+export const overMcp = (c: Command, full: boolean): boolean => {
+  if (c.mcp === false || (c.needs === 'nothing' && c.mcp === undefined)) return false;
+  return c.mcp === 'core' || full;
+};
+
+const flagSignature = (name: string, f: FlagSpec) => `--${name}${f.type === 'boolean' ? '' : ` <${f.value ?? f.type}>`}`;
+
+const signature = (c: Command): string => {
+  const pos = (c.positionals ?? []).map((p) => (p.required ? `<${p.name}>` : `[${p.name}]`) + (p.rest ? '…' : '')).join(' ');
+  const fl = Object.entries(c.flags ?? {})
+    .map(([n, f]) => `[${flagSignature(n, f)}]`)
+    .join(' ');
+  return [c.name, pos, fl].filter(Boolean).join(' ');
+};
+
+const inGroups = () => (Object.keys(GROUPS) as Group[]).map((g) => ({ ...GROUPS[g], list: all.filter((c) => c.group === g) })).filter((g) => g.list.length);
+
+export const usage = (): string => {
+  const lines = ['lynkeus — drive a React Native app from the outside, through the agent inside it', ''];
+  for (const g of inGroups()) {
+    lines.push(`${g.title} — ${g.blurb}`);
+    for (const c of g.list) {
+      const sig = c.example ?? signature(c);
+      lines.push(sig.length > 44 ? `  ${sig}\n${' '.repeat(47)}${c.summary}` : `  ${sig.padEnd(45)}${c.summary}`);
+    }
+    lines.push('');
+  }
+  lines.push(
+    `Global: ${Object.entries(GLOBAL_FLAGS)
+      .map(([n, f]) => flagSignature(n, f))
+      .join('  ')}`,
+    '`lynkeus help <command>` for details; `lynkeus session` runs many commands on one connection; `lynkeus mcp` serves the core of them to an AI harness (`--full`: all).',
+  );
+  return lines.join('\n');
+};
+
+export const helpFor = (c: Command): string => {
+  const lines = [`lynkeus ${signature(c)}`, '', c.summary];
+  if (c.details) lines.push('', c.details);
+  if (c.positionals?.length) {
+    lines.push('', 'Arguments');
+    for (const p of c.positionals) lines.push(`  ${p.name.padEnd(14)} ${p.help}${p.required ? '' : ' (optional)'}`);
+  }
+  const flags = Object.entries(c.flags ?? {});
+  if (flags.length) {
+    lines.push('', 'Flags');
+    for (const [n, f] of flags) lines.push(`  ${flagSignature(n, f).padEnd(24)} ${f.help}${f.default !== undefined ? ` (default ${f.default})` : ''}`);
+  }
+  if (c.aliases?.length) lines.push('', `Also: ${c.aliases.join(', ')}`);
+  const needs = c.needs === 'app' ? 'the app running with the agent' : c.needs === 'graph' ? 'a graph (lynkeus map build)' : 'nothing';
+  const mcp = c.mcp === 'core' ? '; served over MCP' : overMcp(c, true) ? '; served over MCP with --full' : '';
+  lines.push('', `Needs: ${needs}${inSession(c) ? '; available in a session' : ''}${mcp}`);
+  return lines.join('\n');
+};
+
+const flagRow = (n: string, f: FlagSpec) => `| \`${flagSignature(n, f)}\` | ${f.help}${f.default !== undefined ? ` (default \`${f.default}\`)` : ''} |`;
+
+/** The reference document, generated so it cannot drift from the commands. */
+export const referenceMarkdown = (): string => {
+  const lines = [
+    '# lynkeus command reference',
+    '',
+    'Generated from the command registry (`lynkeus help --markdown`). Every command accepts the global flags at the end.',
+    '',
+  ];
+  for (const g of inGroups()) {
+    lines.push(`## ${g.title}`, '', `${g.blurb}.`, '');
+    for (const c of g.list) {
+      lines.push(`### \`lynkeus ${signature(c)}\``, '', c.summary + (c.details ? `\n\n${c.details}` : ''), '');
+      if (c.positionals?.length) {
+        lines.push('| Argument | |', '|---|---|');
+        for (const p of c.positionals) lines.push(`| \`${p.name}\` | ${p.help}${p.required ? '' : ' (optional)'} |`);
+        lines.push('');
+      }
+      const flags = Object.entries(c.flags ?? {});
+      if (flags.length) lines.push('| Flag | |', '|---|---|', ...flags.map(([n, f]) => flagRow(n, f)), '');
+      if (c.aliases?.length) lines.push(`Also accepted: ${c.aliases.map((a) => `\`${a}\``).join(', ')}.`, '');
+    }
+  }
+  lines.push(
+    '## Modes',
+    '',
+    '`lynkeus session` keeps one connection and reads JSON arrays of arguments on stdin, one command per line, answering one JSON object per line (`{ok, out, json?}` or `{ok:false, error, why?}`); `exit` ends it. `lynkeus mcp` serves the core commands as MCP tools over stdio; `lynkeus mcp --full` serves all of them. `lynkeus help <command>` prints one command; `lynkeus help --markdown` prints this document.',
+    '',
+    '## Global flags',
+    '',
+    '| Flag | |',
+    '|---|---|',
+    ...Object.entries(GLOBAL_FLAGS).map(([n, f]) => flagRow(n, f)),
+    '',
+  );
+  return lines.join('\n');
+};

package/src/runtime.ts

@@ -0,0 +1,54 @@
+/**
+ * Runs one command from an argv: resolve, parse, run, and on failure read the
+ * evidence. The terminal, session lines, a recording's stdin, cases and the
+ * MCP server all come through here.
+ */
+import { UsageError } from './args.js';
+import { describeWhy, explain } from './knowledge/why.js';
+import { type Base, helpFor, parseFor, resolve } from './registry.js';
+import { type Expected, expectedOf } from './targets.js';
+
+export type Outcome = { text?: string; json?: unknown; code: number; error?: string; why?: string };
+
+/** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
+export const whyFor = async (base: Base, expected?: Expected): Promise<string> => {
+  try {
+    const device = await base.device();
+    const [screen, requests, trace] = await Promise.all([device.screen(), device.requests(), device.trace()]);
+    return describeWhy(
+      explain({ screen, requests: requests.requests.slice(-40), inFlight: requests.inFlight, trace: trace.events.slice(-40), target: expected }),
+    );
+  } catch {
+    return '';
+  }
+};
+
+const TARGET_ARG: Record<string, number> = { press: 0, see: 0, wait: 0, swipe: 1, nav: 0, type: 1 };
+
+export const execute = async (argv: string[], base: Base): Promise<Outcome> => {
+  const found = resolve(argv);
+  if (!found) return { code: 2, error: `unknown command "${argv.slice(0, 2).join(' ')}"; \`lynkeus help\` lists them` };
+  const { command, rest } = found;
+  let parsed: ReturnType<typeof parseFor>;
+  try {
+    parsed = parseFor(command, rest);
+  } catch (error) {
+    if (error instanceof UsageError) return { code: 2, error: `${error.message}\n\n${helpFor(command)}` };
+    throw error;
+  }
+  if (parsed.flags.help) return { code: 0, text: helpFor(command) };
+  try {
+    const result = await command.run({ ...base, ...parsed });
+    if (result === undefined) return { code: 0 };
+    if (typeof result === 'string') return { code: 0, text: result };
+    return { code: result.code ?? 0, text: result.text ?? (result.json === undefined ? undefined : JSON.stringify(result.json)), json: result.json };
+  } catch (error) {
+    const out: Outcome = { code: 1, error: error instanceof Error ? error.message : String(error) };
+    const at = TARGET_ARG[command.name];
+    if (at !== undefined) {
+      const why = await whyFor(base, expectedOf(parsed.args[at]));
+      if (why) out.why = why;
+    }
+    return out;
+  }
+};

package/src/targets.ts

@@ -0,0 +1,44 @@
+import type { Target } from 'lynkeus-protocol';
+
+export const TARGET_HELP = '#testId | "text" | 12 (index) | 100,200';
+
+/** `#testId`, `12` (an index), `100,200` (a point), anything else a text; `#testId[2]` or `text[2]` is the third match. */
+export const parseTarget = (raw: string): Target => {
+  const nth = /^(.+)\[(\d+)\]$/.exec(raw);
+  if (nth && !/^\d+$/.test(nth[1]!)) {
+    const base = parseTarget(nth[1]!);
+    if ('testId' in base || 'text' in base) return { ...base, nth: Number(nth[2]) };
+  }
+  if (raw.startsWith('#')) return { testId: raw.slice(1) };
+  if (/^\d+,\d+$/.test(raw)) {
+    const [x, y] = raw.split(',').map(Number);
+    return { x: x!, y: y! };
+  }
+  if (/^\d+$/.test(raw)) return { i: Number(raw) };
+  return { text: raw };
+};
+
+/** A target narrowed to the match nearest another (`--in`) and to a position among the matches (`--nth`). */
+export const scopedTarget = (raw: string, flags: { in?: unknown; nth?: unknown }): Target => {
+  const target = parseTarget(raw);
+  if (!('testId' in target) && !('text' in target)) return target;
+  const scope = typeof flags.in === 'string' ? parseTarget(flags.in) : undefined;
+  if (scope && !('testId' in scope) && !('text' in scope)) throw new Error('--in takes a #testId or a text');
+  return {
+    ...target,
+    ...(scope ? { within: 'testId' in scope ? { testId: scope.testId } : { text: scope.text } } : {}),
+    ...(typeof flags.nth === 'number' ? { nth: flags.nth } : {}),
+  };
+};
+
+export const isRoute = (raw: string) => /^[A-Z]\w*(\.[A-Z]\w*)*$/.test(raw);
+
+export type Expected = { testId?: string; text?: string; route?: string };
+
+/** What a command was looking for, as `why` reads it. */
+export const expectedOf = (raw: string | undefined): Expected | undefined => {
+  if (!raw) return undefined;
+  if (isRoute(raw)) return { route: raw };
+  const t = parseTarget(raw);
+  return 'testId' in t ? { testId: t.testId } : 'text' in t ? { text: t.text } : undefined;
+};