lynkeus 0.2.0

package/src/config.ts

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { CasesConfig } from './cases/runner.js';
+import { readJson } from './files.js';
+import type { ScreenGraph } from './knowledge/types.js';
+
+export const lynkeusDir = (root = process.cwd()) => path.join(root, '.lynkeus');
+export const graphFile = (root?: string) => path.join(lynkeusDir(root), 'graph.json');
+export const edgesFile = (root?: string) => path.join(lynkeusDir(root), 'edges.jsonl');
+export const frontierFile = (root?: string) => path.join(lynkeusDir(root), 'frontier.jsonl');
+export const runsDir = (root?: string) => path.join(lynkeusDir(root), 'runs');
+
+export const loadGraph = (root?: string): ScreenGraph | null => {
+  const file = graphFile(root);
+  return fs.existsSync(file) ? readJson<ScreenGraph>(file) : null;
+};
+
+/**
+ * `lynkeus.config.json` in the app's folder: what would otherwise be repeated
+ * as flags or environment on every invocation. Flags win over the
+ * environment, the environment over the file.
+ */
+export type LynkeusConfig = {
+  cases?: CasesConfig;
+  /** The headless entry (default `qa/headless.tsx`). */
+  entry?: string;
+  /** The environment variable the app reads its API base from; the headless entry refuses one that is not local. */
+  apiEnv?: string;
+  /** The driver port the app dials. */
+  port?: number;
+  /** Simulator udid or name. */
+  device?: string;
+  /** Bundle id or application id. */
+  app?: string;
+  /**
+   * The language this app speaks, passed on and never interpreted: `os
+   * language` defaults to it, the headless entry mocks this locale, and an MCP
+   * client is told, so a model reading the screens knows their language.
+   */
+  language?: string;
+  locale?: { languageTag?: string; country?: string };
+  /** How long to wait for the app to attach, in ms. */
+  attachTimeout?: number;
+  /** The lint baseline `lint` compares against when no file is given. */
+  lintBaseline?: string;
+  /** Regular expressions for the text this app shows when it is broken; `smoke` and `crawl` report a match. */
+  errorCopy?: string[];
+  /** The shape of an untranslated key, and the smallest acceptable touch target in points. */
+  lint?: { i18nKeyPatterns?: string[]; minTouchTarget?: number };
+  /**
+   * Regular expressions for the testIDs of controls whose content changes on
+   * its own (a ticking clock, a countdown). Their text stops counting as a
+   * commit, or `idle` would wait out its whole timeout on every screen that
+   * shows one.
+   */
+  live?: string[];
+  /** Keep React.StrictMode in the headless host. Off by default: its double renders inflate what the host measures. */
+  strictMode?: boolean;
+  /** Regular expressions matched against a control's testID and label. lynkeus ships none: only the app knows which controls are irreversible. */
+  crawl?: {
+    /** Never pressed. */
+    never?: string[];
+    /** Close an overlay the app raises. */
+    close?: string[];
+    /** Go back. Without them the crawl takes a small control in the top-left corner for one. */
+    back?: string[];
+  };
+};
+
+export const configFile = (root?: string) => path.join(root ?? process.cwd(), 'lynkeus.config.json');
+
+const readConfig = (file: string): LynkeusConfig => {
+  if (!fs.existsSync(file)) return {};
+  try {
+    const config = readJson<LynkeusConfig>(file);
+    // Paths under `cases` are relative to the file that declares them.
+    if (config.cases) config.cases.base = path.dirname(path.resolve(file));
+    return config;
+  } catch (error) {
+    throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+};
+
+/** The app's configuration, under the one `LYNKEUS_CONFIG` names: cases and fixtures often live in a repository of their own. */
+export const loadConfig = (root?: string): LynkeusConfig => {
+  const own = readConfig(configFile(root));
+  const extra = process.env.LYNKEUS_CONFIG ? readConfig(path.resolve(process.env.LYNKEUS_CONFIG)) : {};
+  return { ...own, ...extra };
+};
+
+export const portFromEnv = (config: LynkeusConfig = {}): number | undefined => (process.env.LYNKEUS_PORT ? Number(process.env.LYNKEUS_PORT) : config.port);
+
+/** A list of regular expressions from the configuration, as one that matches any of them. */
+export const anyOf = (patterns: string[] | undefined): RegExp | undefined => (patterns?.length ? new RegExp(patterns.join('|'), 'i') : undefined);
+
+export const packageName = (root: string): string => {
+  try {
+    return (JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) as { name?: string }).name ?? path.basename(root);
+  } catch {
+    return path.basename(root);
+  }
+};

package/src/device/devices.ts

@@ -0,0 +1,44 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+export type Platform = 'ios' | 'android';
+
+export type DeviceInfo = {
+  id: string;
+  name: string;
+  platform: Platform;
+  type: 'simulator' | 'emulator' | 'physical';
+  connected: boolean;
+};
+
+export const bootedSimulators = async (): Promise<DeviceInfo[]> => {
+  // No Xcode (Linux, CI) means no simulators, not a crash: the app may be hosted headless.
+  let stdout: string;
+  try {
+    ({ stdout } = await run('xcrun', ['simctl', 'list', 'devices', 'booted', '-j']));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const parsed = JSON.parse(stdout) as { devices: Record<string, { udid: string; name: string; state: string }[]> };
+  return Object.values(parsed.devices)
+    .flat()
+    .filter((d) => d.state === 'Booted')
+    .map((d) => ({ id: d.udid, name: d.name, platform: 'ios', type: 'simulator', connected: true }));
+};
+
+export const HEADLESS_HOST: DeviceInfo = { id: 'headless', name: 'headless host', platform: 'ios', type: 'simulator', connected: true };
+
+export const pickAgentDevice = async (wanted?: string): Promise<DeviceInfo> => {
+  const devices = await bootedSimulators();
+  const id = wanted ?? process.env.LYNKEUS_DEVICE;
+  const device = id ? devices.find((d) => d.id === id || d.name.includes(id)) : devices[0];
+  if (!device) {
+    // A headless host dials the driver itself: nothing to boot or attach to.
+    if (!id && devices.length === 0) return HEADLESS_HOST;
+    throw new Error(id ? `No booted simulator matching "${id}".` : 'No booted simulator. Boot one first.');
+  }
+  return device;
+};

package/src/device/driver.ts

@@ -0,0 +1,197 @@
+/**
+ * An app running the agent. The screen is the React tree the app hands over and
+ * touches are synthesized inside its process, so an action costs milliseconds;
+ * only launching, screenshots and the status bar go through simctl or adb.
+ */
+import { AgentServer } from 'lynkeus-client';
+import type { CoreMethods, Screen, TraceEvent } from 'lynkeus-protocol';
+
+import { portFromEnv } from '../config.js';
+import { withoutHost } from '../knowledge/problems.js';
+import type { DeviceInfo } from './devices.js';
+import { lifecycleFor, type PlatformLifecycle } from './platform.js';
+
+export class Device {
+  info: DeviceInfo;
+  readonly server: AgentServer;
+
+  #lifecycle: PlatformLifecycle;
+  #appId: string | null;
+  #resolving?: Promise<DeviceInfo>;
+
+  constructor(info: DeviceInfo, options: { server?: AgentServer; appId?: string | null; resolving?: Promise<DeviceInfo> } = {}) {
+    this.info = info;
+    this.#resolving = options.resolving;
+    // The app serves commands only to a driver that presents its token; without one, anything on the loopback could drive a dev build.
+    this.server = options.server ?? new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: portFromEnv() });
+    this.#lifecycle = lifecycleFor(info.platform);
+    this.#appId = options.appId ?? null;
+  }
+
+  /** The device as the OS knows it: reading the screen needs none of it; launching, screenshots and OS commands do. */
+  async resolved(): Promise<DeviceInfo> {
+    if (this.#resolving) {
+      this.info = await this.#resolving;
+      this.#resolving = undefined;
+    }
+    return this.info;
+  }
+
+  get appId(): string | null {
+    return this.#appId;
+  }
+
+  async stop(): Promise<void> {
+    await this.server.close();
+  }
+
+  async launchApp(appId: string, options: { fresh?: boolean } = {}): Promise<void> {
+    this.#appId = appId;
+    await this.server.listen();
+    await this.#lifecycle.launchApp((await this.resolved()).id, appId, options.fresh ?? true);
+    await this.server.waitForApp();
+  }
+
+  async openUrl(url: string): Promise<void> {
+    await this.server.call('deepLink', { url });
+  }
+
+  /** Pins the clock, battery and radios so a pixel baseline survives the calendar. */
+  async freezeChrome(): Promise<void> {
+    await this.#lifecycle.freezeChrome((await this.resolved()).id);
+  }
+
+  async screenshot(destination: string): Promise<void> {
+    await this.#lifecycle.screenshot((await this.resolved()).id, destination);
+  }
+
+  screen(): Promise<Screen> {
+    return this.server.call('screen');
+  }
+
+  press(params: CoreMethods['press']['params']): Promise<CoreMethods['press']['result']> {
+    return this.server.call('press', params);
+  }
+
+  type(params: CoreMethods['type']['params']): Promise<CoreMethods['type']['result']> {
+    return this.server.call('type', params);
+  }
+
+  swipe(params: CoreMethods['swipe']['params']): Promise<CoreMethods['swipe']['result']> {
+    return this.server.call('swipe', params);
+  }
+
+  back(): Promise<CoreMethods['back']['result']> {
+    return this.server.call('back');
+  }
+
+  async navigate(name: string, params?: object): Promise<void> {
+    await this.server.call('navigate', { name, params });
+  }
+
+  // The agent's own timeout governs; the transport waits a little longer so it hears the agent's answer.
+  waitFor(params: CoreMethods['waitFor']['params']): Promise<CoreMethods['waitFor']['result']> {
+    return this.server.call('waitFor', params, (params.timeoutMs ?? 5000) + 2000);
+  }
+
+  idle(params?: CoreMethods['idle']['params']): Promise<CoreMethods['idle']['result']> {
+    return this.server.call('idle', params, (params?.timeoutMs ?? 3000) + 2000);
+  }
+
+  requests(since?: number): Promise<CoreMethods['requests']['result']> {
+    return this.server.call('requests', { since });
+  }
+
+  trace(since?: number): Promise<CoreMethods['trace']['result']> {
+    return this.server.call('trace', { since });
+  }
+
+  /** A command the app registered with `qa.register`. */
+  command<T = unknown>(name: string, params?: unknown): Promise<T> {
+    return this.server.call<T>(name, params);
+  }
+}
+
+const quote = (value: string) => JSON.stringify(value);
+
+export const describeTrace = (events: TraceEvent[]): string => {
+  if (events.length === 0) return '(no events)';
+  const t0 = events[0]!.t;
+  const rel = (t: number) => `+${String(t - t0).padStart(6)}ms`;
+  return events
+    .map((e) => {
+      if (e.kind === 'route') return `${rel(e.t)}  route    ${e.route ?? '?'}  (${e.path.join(' > ')})`;
+      if (e.kind === 'request')
+        return `${rel(e.t)}  request  ${String(e.status ?? '…').padStart(3)} ${e.method.padEnd(5)} ${withoutHost(e.url)}${e.error ? `  (${e.error})` : ''}`;
+      if (e.kind === 'stall')
+        return `${rel(e.t)}  stall    render loop broken: ${e.renders} updates${e.component ? ` to ${e.component}` : ''} in ${e.windowMs}ms`;
+      if (e.kind === 'touch')
+        return `${rel(e.t)}  touch    ${e.testId ? `#${e.testId}` : e.text ? JSON.stringify(e.text) : `${e.x},${e.y}`}  on ${e.route ?? '?'}`;
+      if (e.kind === 'crash') return `${rel(e.t)}  crash    ${e.message}`;
+      if (e.kind === 'event') return `${rel(e.t)}  event    ${e.name}${e.props ? ` ${JSON.stringify(e.props)}` : ''}`;
+      if (e.kind === 'store')
+        return `${rel(e.t)}  store    ${e.store}: ${Object.entries(e.changed)
+          .map(([k, v]) => `${k} ${JSON.stringify(v.from)}→${JSON.stringify(v.to)}`)
+          .join(', ')}`;
+      return `${rel(e.t)}  command  ${e.method} ${e.ms}ms${e.error ? `  ✗ ${e.error}` : ''}`;
+    })
+    .join('\n');
+};
+
+type DescribeOptions = {
+  limit?: number;
+  /** Also what the platform is not presenting: behind a layer, out of the accessibility tree. */
+  all?: boolean;
+  /** Each element's centre, in points. */
+  frames?: boolean;
+  /** The commit count and the read's cost in the header. */
+  verbose?: boolean;
+};
+
+export const describeScreen = (screen: Screen, options: DescribeOptions = {}): string => {
+  const { limit = 80, all = false, frames = false, verbose = false } = options;
+  const layer = screen.presenting ? ` +${screen.presenting.modal ? 'modal' : 'overlay'}${screen.presenting.testId ? `#${screen.presenting.testId}` : ''}` : '';
+  // Plain views are layout; one that names itself (a testID, a label) is content.
+  const named = screen.elements.filter((e) => e.kind !== 'view' || e.accessibilityLabel !== undefined || e.testId !== undefined);
+  // What sits inside a button is the button: its icon is not something else to read or press.
+  const insideButton = (e: Screen['elements'][number]) => {
+    for (let p = e.parent; p !== undefined; p = screen.elements[p]?.parent) if (screen.elements[p]?.kind === 'button') return true;
+    return false;
+  };
+  // An inert control is still read, even though it cannot be touched.
+  const listed = all ? named : named.filter((e) => (!e.hidden || e.hidden === 'inert') && !(e.kind === 'view' && insideButton(e)));
+  const counts = new Map<string, number>();
+  if (!all) for (const e of named) if (e.hidden && e.hidden !== 'inert') counts.set(e.hidden, (counts.get(e.hidden) ?? 0) + 1);
+  const hiddenTotal = [...counts.values()].reduce((sum, n) => sum + n, 0);
+  const hiddenNote = hiddenTotal ? ` · ${hiddenTotal} hidden: ${[...counts].map(([reason, n]) => `${n} ${reason}`).join(', ')}` : '';
+  const stats = verbose ? ` commit=${screen.commit}${screen.busy ? ' busy' : ''} ${screen.costMs}ms` : screen.busy ? ' busy' : '';
+  // The path says which navigators hold the route; alone, it only repeats it.
+  const trail = screen.path.join(' > ');
+  const header = `${screen.route ?? '?'}${trail === screen.route ? '' : ` (${trail})`}${layer}${stats}${hiddenNote}`;
+  // An index is how to point at what has no name of its own, or shares it: a control
+  // with a testID nothing else carries is pointed at by that.
+  const nameOf = (e: Screen['elements'][number]) => (e.testId ? `#${e.testId}` : (e.text ?? e.accessibilityLabel));
+  const uses = new Map<string, number>();
+  for (const e of listed) {
+    const name = nameOf(e);
+    if (name !== undefined) uses.set(name, (uses.get(name) ?? 0) + 1);
+  }
+  const lines = listed.slice(0, limit).map((e) => {
+    const id = e.testId ? ` #${e.testId}` : '';
+    const name = nameOf(e);
+    const index = name !== undefined && uses.get(name) === 1 ? '' : `${e.i} `;
+    // A label that only repeats the testID says nothing new.
+    const label = (e.text ?? e.accessibilityLabel) === e.testId ? undefined : (e.text ?? e.accessibilityLabel);
+    const value =
+      e.kind === 'input'
+        ? ` value=${quote(e.value ?? '')}${e.placeholder ? ` placeholder=${quote(e.placeholder)}` : ''}${e.focused ? ' *focused' : ''}`
+        : e.value !== undefined
+          ? ` value=${quote(e.value)}` // a QR's encoded string, say
+          : '';
+    const state = `${e.enabled ? '' : ' !disabled'}${e.covered ? ' ~covered' : ''}${e.hidden ? ` ~${e.hidden}` : ''}`;
+    const at = frames ? ` @${Math.round(e.frame.x + e.frame.w / 2)},${Math.round(e.frame.y + e.frame.h / 2)}` : '';
+    return `${index}${e.kind}${id}${label ? ` ${quote(label)}` : ''}${value}${state}${at}`;
+  });
+  const rest = listed.length - lines.length;
+  return [header, ...lines, rest > 0 ? `… ${rest} more` : ''].filter(Boolean).join('\n');
+};

package/src/device/platform.ts

@@ -0,0 +1,74 @@
+import { execFile } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+import type { Platform } from './devices.js';
+
+const run = promisify(execFile);
+
+export type PlatformLifecycle = {
+  launchApp(deviceId: string, appId: string, fresh: boolean): Promise<void>;
+  screenshot(deviceId: string, destination: string): Promise<void>;
+  freezeChrome(deviceId: string): Promise<void>;
+};
+
+const ios: PlatformLifecycle = {
+  async launchApp(deviceId, appId, fresh) {
+    const args = ['simctl', 'launch'];
+    if (fresh) args.push('--terminate-running-process');
+    await run('xcrun', [...args, deviceId, appId]);
+  },
+
+  async screenshot(deviceId, destination) {
+    await run('xcrun', ['simctl', 'io', deviceId, 'screenshot', destination]);
+  },
+
+  async freezeChrome(deviceId) {
+    await run('xcrun', [
+      'simctl',
+      'status_bar',
+      deviceId,
+      'override',
+      '--time',
+      '9:41',
+      '--batteryState',
+      'charged',
+      '--batteryLevel',
+      '100',
+      '--cellularMode',
+      'active',
+      '--cellularBars',
+      '4',
+      '--wifiMode',
+      'active',
+      '--wifiBars',
+      '3',
+    ]);
+  },
+};
+
+const adb = (deviceId: string, args: string[]) => run('adb', ['-s', deviceId, ...args]);
+
+const android: PlatformLifecycle = {
+  async launchApp(deviceId, appId, fresh) {
+    if (fresh) await adb(deviceId, ['shell', 'am', 'force-stop', appId]);
+    await adb(deviceId, ['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1']);
+  },
+
+  async screenshot(deviceId, destination) {
+    const { stdout } = await run('adb', ['-s', deviceId, 'exec-out', 'screencap', '-p'], { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+    await writeFile(destination, stdout);
+  },
+
+  async freezeChrome(deviceId) {
+    await adb(deviceId, ['shell', 'settings', 'put', 'global', 'sysui_demo_allowed', '1']);
+    const demo = (args: string[]) => adb(deviceId, ['shell', 'am', 'broadcast', '-a', 'com.android.systemui.demo', ...args]);
+    await demo(['-e', 'command', 'enter']);
+    await demo(['-e', 'command', 'clock', '-e', 'hhmm', '0941']);
+    await demo(['-e', 'command', 'battery', '-e', 'level', '100', '-e', 'plugged', 'false']);
+    await demo(['-e', 'command', 'network', '-e', 'wifi', 'show', '-e', 'level', '4']);
+    await demo(['-e', 'command', 'notifications', '-e', 'visible', 'false']);
+  },
+};
+
+export const lifecycleFor = (platform: Platform): PlatformLifecycle => (platform === 'ios' ? ios : android);

package/src/files.ts

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const readJson = <T>(file: string): T => JSON.parse(fs.readFileSync(file, 'utf8')) as T;
+
+export const writeJson = (file: string, value: unknown): void => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+};
+
+export const readJsonl = <T>(file: string): T[] => {
+  if (!fs.existsSync(file)) return [];
+  return fs
+    .readFileSync(file, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line) as T);
+};
+
+export const appendJsonl = (file: string, row: unknown): void => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${JSON.stringify(row)}\n`);
+};
+
+// Through a temporary file and a rename, so a reader never sees half a file.
+export const writeJsonl = (file: string, rows: unknown[]): void => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, rows.map((row) => `${JSON.stringify(row)}\n`).join(''));
+  fs.renameSync(tmp, file);
+};
+
+export const today = () => new Date().toISOString().slice(0, 10);
+
+export const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');

package/src/flow/artifacts.ts

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { Element, Screen } from 'lynkeus-protocol';
+
+import { stamp } from '../files.js';
+
+export const runDir = (root: string, flowName: string): string => {
+  const slug = flowName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  const dir = path.join(root, slug, stamp());
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+export const stepFile = (dir: string, index: number, extension: string) => path.join(dir, `step-${String(index).padStart(2, '0')}.${extension}`);
+
+const key = (e: Element) => `${e.kind}|${e.testId ?? ''}|${e.text ?? e.accessibilityLabel ?? ''}`;
+
+export type ScreenDiff = {
+  route: { before?: string; after?: string; changed: boolean };
+  added: Element[];
+  removed: Element[];
+  changedText: { before: Element; after: Element }[];
+};
+
+/** Structural difference between two screens: no geometry, so layout jitter is not a change. */
+export const diffScreens = (before: Screen, after: Screen): ScreenDiff => {
+  const beforeByKey = new Map(before.elements.map((e) => [key(e), e]));
+  const afterByKey = new Map(after.elements.map((e) => [key(e), e]));
+  const added = after.elements.filter((e) => !beforeByKey.has(key(e)));
+  const removed = before.elements.filter((e) => !afterByKey.has(key(e)));
+
+  // Same identity (testId) but different text: a value or a label changed.
+  const changedText: ScreenDiff['changedText'] = [];
+  const removedById = new Map(removed.filter((e) => e.testId).map((e) => [e.testId!, e]));
+  for (const e of added) {
+    const previous = e.testId ? removedById.get(e.testId) : undefined;
+    if (previous) changedText.push({ before: previous, after: e });
+  }
+  const paired = new Set(changedText.flatMap((c) => [c.before, c.after]));
+  return {
+    route: { before: before.route, after: after.route, changed: before.route !== after.route },
+    added: added.filter((e) => !paired.has(e)),
+    removed: removed.filter((e) => !paired.has(e)),
+    changedText,
+  };
+};
+
+const label = (e: Element) => `${e.kind} ${e.testId ? `#${e.testId}` : ''} ${e.text ? JSON.stringify(e.text.slice(0, 60)) : ''}`.trim();
+
+export const describeDiff = (diff: ScreenDiff): string => {
+  const lines: string[] = [];
+  if (diff.route.changed) lines.push(`route ${diff.route.before ?? '?'} → ${diff.route.after ?? '?'}`);
+  for (const c of diff.changedText) lines.push(`~ ${label(c.before)} → ${JSON.stringify(c.after.text ?? '')}`);
+  for (const e of diff.added) lines.push(`+ ${label(e)}`);
+  for (const e of diff.removed) lines.push(`- ${label(e)}`);
+  return lines.length ? lines.join('\n') : '(no structural change)';
+};