lynkeus 0.2.0 → 0.3.0

package/lib/commands/init.d.ts

@@ -10,4 +10,10 @@ export type InitOptions = {
         language?: string;
     };
 };
+/**
+ * Mounts the agent from the app's entry, before anything registers the root component. An Expo Router app
+ * has no entry of its own (`"main": "expo-router/entry"`), so it gets one that mounts the agent and then
+ * loads the router.
+ */
+export declare const mountAgent: (root: string) => string[];
 export declare const init: (root: string, opts: InitOptions) => string[];

package/lib/commands/init.js

@@ -43,6 +43,82 @@ const { default: App } = require('${appImport}')
 export { App }
 `;
 };
+const readManifest = (root) => {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+};
+/** Expo inlines only the variables that start with EXPO_PUBLIC_; anything else is undefined in the app. */
+const tokenIn = (expo) => (expo ? 'process.env.EXPO_PUBLIC_LYNKEUS_TOKEN' : 'process.env.LYNKEUS_TOKEN');
+const mountLines = (expo) => `import { auto } from 'lynkeus-agent/auto'\n// Dev-only QA agent; a release build never evaluates the client.\nauto({ token: ${tokenIn(expo)} })\n`;
+const BABEL_CANDIDATES = ['babel.config.js', 'babel.config.cjs'];
+const TOKEN_PLUGIN = 'lynkeus-agent/babel';
+/** React Native gives the app no environment: the plugin writes LYNKEUS_TOKEN where the entry reads it. */
+const addTokenPlugin = (root) => {
+    const byHand = `add '${TOKEN_PLUGIN}' to the plugins in babel.config.js, so the app can read LYNKEUS_TOKEN`;
+    const file = findFirst(root, BABEL_CANDIDATES);
+    if (!file)
+        return byHand;
+    const text = fs.readFileSync(path.join(root, file), 'utf8');
+    if (text.includes(TOKEN_PLUGIN))
+        return `${file} already has ${TOKEN_PLUGIN}`;
+    const plugins = /\bplugins\s*:\s*\[/.exec(text);
+    const presets = /^([ \t]*)presets\s*:/m.exec(text);
+    if (!plugins && !presets)
+        return byHand;
+    const next = plugins
+        ? `${text.slice(0, plugins.index + plugins[0].length)}'${TOKEN_PLUGIN}', ${text.slice(plugins.index + plugins[0].length)}`
+        : `${text.slice(0, presets.index)}${presets[1]}plugins: ['${TOKEN_PLUGIN}'],\n${text.slice(presets.index)}`;
+    fs.writeFileSync(path.join(root, file), next);
+    return `added ${TOKEN_PLUGIN} to ${file}`;
+};
+/**
+ * Mounts the agent from the app's entry, before anything registers the root component. An Expo Router app
+ * has no entry of its own (`"main": "expo-router/entry"`), so it gets one that mounts the agent and then
+ * loads the router.
+ */
+export const mountAgent = (root) => {
+    const notes = [];
+    const manifest = readManifest(root);
+    const expo = !!(manifest.dependencies?.expo ?? manifest.devDependencies?.expo);
+    const index = findFirst(root, INDEX_CANDIDATES);
+    const routed = manifest.main === 'expo-router/entry';
+    if (routed && !index) {
+        fs.writeFileSync(path.join(root, 'index.js'), `${mountLines(true)}\nimport 'expo-router/entry'\n`);
+        fs.writeFileSync(path.join(root, 'package.json'), `${JSON.stringify({ ...JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')), main: 'index.js' }, null, 2)}\n`);
+        notes.push("wrote index.js (mounts the agent, then loads expo-router) and pointed package.json's main at it");
+    }
+    else if (!index) {
+        notes.push(`no index.js to add the auto mount to; add it yourself: import { auto } from 'lynkeus-agent/auto'; auto({ token: ${tokenIn(expo)} })`);
+        return notes;
+    }
+    else {
+        const indexPath = path.join(root, index);
+        const text = fs.readFileSync(indexPath, 'utf8');
+        if (text.includes('lynkeus-agent/auto')) {
+            notes.push(`${index} already mounts the agent`);
+        }
+        else {
+            // After the last import, so the app's own polyfills still run first.
+            const imports = [...text.matchAll(/^import .*$/gm)];
+            const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length + 1 : 0;
+            fs.writeFileSync(indexPath, text.slice(0, at) + mountLines(expo) + text.slice(at));
+            notes.push(`added auto() to ${index}`);
+        }
+    }
+    if (!expo) {
+        notes.push(addTokenPlugin(root));
+        notes.push('start Metro with LYNKEUS_TOKEN set to the value the CLI reads; after changing it, start Metro with --reset-cache');
+    }
+    if (expo) {
+        notes.push('Expo: the agent has native code, so it runs in a development build (npx expo run:ios, npx expo run:android), not in Expo Go');
+        notes.push('Expo: start the dev server with EXPO_PUBLIC_LYNKEUS_TOKEN set to the same value as LYNKEUS_TOKEN; Expo passes the app only variables with that prefix');
+    }
+    return notes;
+};
 export const init = (root, opts) => {
     const notes = [];
     const entryPath = path.join(root, opts.entry);
@@ -57,27 +133,8 @@ export const init = (root, opts) => {
         fs.writeFileSync(entryPath, entryTemplate(relImport(entryPath, path.join(root, app)), opts.apiEnv, packageName(root), opts.locale));
         notes.push(`wrote ${opts.entry} (app: ${app})`);
     }
-    if (opts.auto) {
-        const index = findFirst(root, INDEX_CANDIDATES);
-        if (!index) {
-            notes.push("no index.js to add the auto mount to; add it yourself: import { auto } from 'lynkeus-agent/auto'; auto({ token: ... })");
-        }
-        else {
-            const indexPath = path.join(root, index);
-            const text = fs.readFileSync(indexPath, 'utf8');
-            if (text.includes('lynkeus-agent/auto')) {
-                notes.push(`${index} already mounts the agent`);
-            }
-            else {
-                const line = "import { auto } from 'lynkeus-agent/auto'\n// Dev-only QA agent; a release build never evaluates the client.\nauto({ token: process.env.LYNKEUS_TOKEN })\n";
-                // After the last import, so the app's own polyfills still run first.
-                const imports = [...text.matchAll(/^import .*$/gm)];
-                const at = imports.length ? imports[imports.length - 1].index + imports[imports.length - 1][0].length + 1 : 0;
-                fs.writeFileSync(indexPath, text.slice(0, at) + line + text.slice(at));
-                notes.push(`added auto() to ${index}`);
-            }
-        }
-    }
+    if (opts.auto)
+        notes.push(...mountAgent(root));
     notes.push("jest: make sure transformIgnorePatterns lets 'lynkeus-[^/]+' through, next to react-native (lynkeus headless doctor checks it)");
     notes.push(`next: LYNKEUS_TOKEN=<token> ${opts.apiEnv}=http://127.0.0.1:3000/ lynkeus headless start`);
     notes.push('      then, in another shell: lynkeus screen  (or lynkeus headless doctor to see what still needs a mock)');

package/lib/commands/report.d.ts

@@ -0,0 +1,97 @@
+type Fetch = typeof fetch;
+export type Pushed = {
+    url: string;
+    files: number;
+    refused: string[];
+    changes?: {
+        newFailures: string[];
+        fixed: string[];
+    };
+};
+/** 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[];
+/**
+ * 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.
+ */
+export declare const pushRun: (dir: string, o: {
+    url: string;
+    key: string;
+    project: string;
+    fetch?: Fetch;
+}) => Promise<Pushed>;
+type Service = {
+    url: string;
+    key: string;
+    fetch?: Fetch;
+};
+export type ListedRun = {
+    project: string;
+    platform: string | null;
+    totals: Record<string, number>;
+    createdAt: string;
+    url: string;
+};
+export declare const listRuns: (o: Service & {
+    limit?: number;
+}) => Promise<ListedRun[]>;
+export type Flaky = {
+    id: string;
+    title: string;
+    runs: number;
+    firstTryRate: number;
+    state: 'flaky' | 'broken';
+    recent: ('passed' | 'retried' | 'failed')[];
+    lastFailure: string | null;
+};
+export declare const flakes: (o: Service & {
+    project: string;
+    runs?: number;
+}) => Promise<{
+    runs: number;
+    cases: Flaky[];
+}>;
+export type CaseRun = {
+    at: string;
+    outcome: 'passed' | 'retried' | 'failed';
+    ms: number | null;
+    branch?: string | null;
+    commit?: string | null;
+    url: string;
+};
+export declare const caseHistory: (o: Service & {
+    project: string;
+    id: string;
+    runs?: number;
+}) => Promise<{
+    title: string;
+    runs: CaseRun[];
+}>;
+export type Plan = {
+    name: string;
+    plan: string;
+    days: number;
+    projects: number | null;
+    film: boolean;
+};
+/** The organization's plan, and with `upgrade` or `manage` the Stripe page that changes it. */
+export declare const plan: (o: Service & {
+    go?: "upgrade" | "manage";
+}) => Promise<{
+    url: null;
+    name: string;
+    plan: string;
+    days: number;
+    projects: number | null;
+    film: boolean;
+} | {
+    url: string;
+    name: string;
+    plan: string;
+    days: number;
+    projects: number | null;
+    film: boolean;
+}>;
+export declare const service: () => Service | string;
+export declare const reportCommands: import("../registry.js").Command[];
+export {};

package/lib/commands/report.js

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { define } from '../registry.js';
+/** What a run changed against the one before, in a line or two for a terminal or a pull request comment. */
+export const describeChanges = (changes) => changes
+    ? [
+        ...(changes.newFailures.length ? [`newly failing (${changes.newFailures.length}): ${changes.newFailures.join(', ')}`] : []),
+        ...(changes.fixed.length ? [`fixed since the run before (${changes.fixed.length}): ${changes.fixed.join(', ')}`] : []),
+    ]
+    : [];
+const answer = async (response, doing) => {
+    if (response.ok)
+        return response.json();
+    const body = (await response.json().catch(() => ({})));
+    throw new Error(`${doing}: ${body.error ?? `the service answered ${response.status}`}`);
+};
+/**
+ * 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.
+ */
+export const pushRun = async (dir, o) => {
+    const call = o.fetch ?? fetch;
+    const auth = { authorization: `Bearer ${o.key}` };
+    const base = o.url.replace(/\/+$/, '');
+    const run = JSON.parse(fs.readFileSync(path.join(dir, 'run.json'), 'utf8'));
+    const cases = fs.readFileSync(path.join(dir, 'cases.jsonl'), 'utf8');
+    const created = await answer(await call(`${base}/v1/runs`, {
+        method: 'POST',
+        headers: { ...auth, 'content-type': 'application/json' },
+        body: JSON.stringify({ project: o.project, run }),
+    }), 'creating the run');
+    const id = String(created.id);
+    await answer(await call(`${base}/v1/runs/${id}/cases`, { method: 'PUT', headers: auth, body: cases }), 'sending its cases');
+    const named = new Set();
+    for (const line of cases.split('\n')) {
+        if (!line.trim())
+            continue;
+        const c = JSON.parse(line);
+        for (const p of [c.video, ...(c.steps ?? []).map((s) => s.screenshot)])
+            if (p)
+                named.add(p);
+    }
+    let files = 0;
+    const refused = [];
+    for (const file of named) {
+        const local = path.join(dir, file);
+        if (!fs.existsSync(local))
+            continue;
+        const response = await call(`${base}/v1/runs/${id}/files/${file.split('/').map(encodeURIComponent).join('/')}`, {
+            method: 'PUT',
+            headers: auth,
+            body: fs.readFileSync(local),
+        });
+        if (response.status === 402)
+            refused.push(file);
+        else {
+            await answer(response, `sending ${file}`);
+            files += 1;
+        }
+    }
+    const finished = await answer(await call(`${base}/v1/runs/${id}/finish`, { method: 'POST', headers: auth }), 'finishing the run');
+    const changes = finished.changes;
+    return { url: String(finished.url), files, refused, ...(changes ? { changes } : {}) };
+};
+const ask = async (o, method, route, doing) => answer(await (o.fetch ?? fetch)(`${o.url.replace(/\/+$/, '')}${route}`, { method, headers: { authorization: `Bearer ${o.key}` } }), doing);
+export const listRuns = async (o) => (await ask(o, 'GET', `/v1/runs?limit=${o.limit ?? 20}`, 'listing the runs')).runs;
+export const flakes = async (o) => (await ask(o, 'GET', `/v1/flakes?project=${encodeURIComponent(o.project)}&runs=${o.runs ?? 30}`, 'reading flake trends'));
+export const caseHistory = async (o) => (await ask(o, 'GET', `/v1/cases/history?project=${encodeURIComponent(o.project)}&case=${encodeURIComponent(o.id)}&runs=${o.runs ?? 50}`, 'reading the case’s history'));
+/** The organization's plan, and with `upgrade` or `manage` the Stripe page that changes it. */
+export const plan = async (o) => {
+    const now = (await ask(o, 'GET', '/v1/billing', 'reading the plan'));
+    if (!o.go)
+        return { ...now, url: null };
+    const route = o.go === 'upgrade' ? '/v1/billing/checkout' : '/v1/billing/portal';
+    return { ...now, url: String((await ask(o, 'POST', route, o.go === 'upgrade' ? 'opening checkout' : 'opening the billing portal')).url) };
+};
+export const service = () => {
+    const url = process.env.LYNKEUS_REPORTS_URL;
+    const key = process.env.LYNKEUS_REPORTS_KEY;
+    return url && key ? { url, key } : 'set LYNKEUS_REPORTS_URL and LYNKEUS_REPORTS_KEY (the organization’s API key)';
+};
+export const reportCommands = [
+    define({
+        name: 'report push',
+        group: 'runs',
+        summary: 'Upload a run to the reports service and print the report’s address',
+        details: 'Uploads what `case run --out <dir>` wrote: the run, its cases, and every frame and film they name. The report shows the film in step with the steps, the events each step sent, and why a case failed. The service and the organization’s key come from LYNKEUS_REPORTS_URL and LYNKEUS_REPORTS_KEY; a film the organization’s plan does not keep is left out and said so.',
+        positionals: [{ name: 'dir', help: 'the run directory `case run --out` wrote', required: true }],
+        flags: {
+            project: { type: 'string', help: 'the project the run is filed under (default: the app’s folder name)', value: 'name' },
+        },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const dir = path.resolve(ctx.args[0]);
+            if (!fs.existsSync(path.join(dir, 'cases.jsonl')))
+                return { text: `${ctx.args[0]}: no cases.jsonl; pass the directory \`case run --out\` wrote`, code: 2 };
+            const to = service();
+            if (typeof to === 'string')
+                return { text: to, code: 2 };
+            const project = typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root);
+            try {
+                const pushed = await pushRun(dir, { ...to, project });
+                const notes = [...describeChanges(pushed.changes), ...(pushed.refused.length ? [`not kept on this plan: ${pushed.refused.join(', ')}`] : [])];
+                return { text: [pushed.url, ...notes].join('\n'), json: pushed };
+            }
+            catch (error) {
+                return { text: error.message, code: 1 };
+            }
+        },
+    }),
+    define({
+        name: 'report list',
+        group: 'runs',
+        summary: 'List the organization’s reports, newest first',
+        details: 'Each line is when the run started, its project and platform, how many cases passed, and the report’s address.',
+        flags: { limit: { type: 'string', help: 'how many runs (default 20, at most 100)', value: 'n' } },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const to = service();
+            if (typeof to === 'string')
+                return { text: to, code: 2 };
+            try {
+                const runs = await listRuns({ ...to, limit: Number(ctx.flags.limit) || 20 });
+                if (runs.length === 0)
+                    return { text: 'no reports yet: `lynkeus report push <dir>` uploads one', json: runs };
+                const lines = runs.map((r) => `${r.createdAt.slice(0, 16).replace('T', ' ')}  ${r.project}${r.platform ? ` ${r.platform}` : ''}  ${r.totals.passed ?? 0}/${r.totals.cases ?? 0} passed  ${r.url}`);
+                return { text: lines.join('\n'), json: runs };
+            }
+            catch (error) {
+                return { text: error.message, code: 1 };
+            }
+        },
+    }),
+    define({
+        name: 'report plan',
+        group: 'runs',
+        summary: 'Show the organization’s plan, or open the page that changes it',
+        details: 'Free keeps frames for 7 days and one project; Team keeps films too, for 90 days, and any number of projects. `--upgrade` prints the Stripe checkout for Team; `--manage` prints Stripe’s portal for the card, the invoices and cancelling.',
+        flags: {
+            upgrade: { type: 'boolean', help: 'print the Stripe checkout address for the Team plan' },
+            manage: { type: 'boolean', help: 'print the Stripe portal address for a paying organization' },
+        },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const to = service();
+            if (typeof to === 'string')
+                return { text: to, code: 2 };
+            const go = ctx.flags.upgrade ? 'upgrade' : ctx.flags.manage ? 'manage' : undefined;
+            try {
+                const now = await plan({ ...to, go });
+                const keeps = `${now.film ? 'films and frames' : 'frames'} for ${now.days} days, ${now.projects ?? 'any number of'} project${now.projects === 1 ? '' : 's'}`;
+                return { text: `${now.name}: ${now.plan} (${keeps})${now.url ? `\n${now.url}` : ''}`, json: now };
+            }
+            catch (error) {
+                return { text: error.message, code: 1 };
+            }
+        },
+    }),
+    define({
+        name: 'report flakes',
+        group: 'runs',
+        summary: 'List the cases that do not always pass at the first try, across the project’s last runs',
+        details: 'Reads the reports pushed for the project and ranks its cases by how often they passed at the first try, the least reliable first. Each line shows the recent runs newest first (✓ passed, ↻ passed on a retry, ✗ failed) and the last report where it went wrong. A case that failed its last three runs is broken rather than flaky. On the Team plan.',
+        flags: {
+            project: { type: 'string', help: 'the project (default: the app’s folder name)', value: 'name' },
+            runs: { type: 'string', help: 'how many of the latest runs to read (default 30)', value: 'n' },
+        },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const to = service();
+            if (typeof to === 'string')
+                return { text: to, code: 2 };
+            const project = typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root);
+            try {
+                const found = await flakes({ ...to, project, runs: Number(ctx.flags.runs) || 30 });
+                if (found.cases.length === 0)
+                    return { text: `${project}: every case passed at the first try in the last ${found.runs} runs`, json: found };
+                const mark = { passed: '✓', retried: '↻', failed: '✗' };
+                const lines = found.cases.map((c) => `${c.state === 'broken' ? 'broken' : 'flaky '}  ${Math.round(c.firstTryRate * 100)
+                    .toString()
+                    .padStart(3)}%  ${c.recent.map((r) => mark[r]).join('')}  ${c.id}${c.lastFailure ? `  ${c.lastFailure}` : ''}`);
+                return { text: [`${project}: ${found.runs} runs`, ...lines].join('\n'), json: found };
+            }
+            catch (error) {
+                return { text: error.message, code: 1 };
+            }
+        },
+    }),
+    define({
+        name: 'report history',
+        group: 'runs',
+        summary: 'Show how one case came out in each of the project’s last runs',
+        details: 'Newest first: ✓ passed, ↻ passed on a retry, ✗ failed, with how long it took, the branch and commit the run was made from, and the report to open. What tells a case that fails now and then from one a commit broke.',
+        positionals: [{ name: 'case', help: 'the case id', required: true }],
+        flags: {
+            project: { type: 'string', help: 'the project (default: the app’s folder name)', value: 'name' },
+            runs: { type: 'string', help: 'how many of the latest runs to read (default 50)', value: 'n' },
+        },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const to = service();
+            if (typeof to === 'string')
+                return { text: to, code: 2 };
+            const project = typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root);
+            try {
+                const found = await caseHistory({ ...to, project, id: ctx.args[0], runs: Number(ctx.flags.runs) || 50 });
+                if (found.runs.length === 0)
+                    return { text: `${ctx.args[0]} is in none of ${project}'s recent runs`, json: found };
+                const mark = { passed: '✓', retried: '↻', failed: '✗' };
+                const lines = found.runs.map((r) => `${mark[r.outcome]}  ${r.at.slice(0, 16).replace('T', ' ')}  ${(r.ms === null ? '—' : `${(r.ms / 1000).toFixed(1)}s`).padStart(6)}  ${[r.branch, r.commit].filter(Boolean).join(' @ ') || '—'}  ${r.url}`);
+                return { text: [`${found.title} (${project})`, ...lines].join('\n'), json: found };
+            }
+            catch (error) {
+                return { text: error.message, code: 1 };
+            }
+        },
+    }),
+];

package/lib/config.d.ts

@@ -39,10 +39,19 @@ export type LynkeusConfig = {
     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. */
+    /**
+     * The shape of an untranslated key, the smallest acceptable touch target in points, and how text contrast is
+     * judged: `false` turns it off; otherwise the least ratio for ordinary and for large text (4.5 and 3, WCAG 2 AA)
+     * and the testIDs to leave out, as regular expressions.
+     */
     lint?: {
         i18nKeyPatterns?: string[];
         minTouchTarget?: number;
+        contrast?: false | {
+            normal?: number;
+            large?: number;
+            ignore?: string[];
+        };
     };
     /**
      * Regular expressions for the testIDs of controls whose content changes on

package/lib/device/agentVersion.d.ts

@@ -0,0 +1,7 @@
+import type { HelloEvent } from 'lynkeus-protocol';
+export declare const CLI_VERSION: string;
+/**
+ * An agent of another release can answer without an error and still do something else (type into
+ * nothing): what to tell the person running it, or nothing when the two match.
+ */
+export declare const agentMismatch: (hello: Pick<HelloEvent, "agentVersion">, cli?: string) => string | undefined;

package/lib/device/agentVersion.js

@@ -0,0 +1,12 @@
+import { createRequire } from 'node:module';
+export const CLI_VERSION = createRequire(import.meta.url)('../../package.json').version;
+/**
+ * An agent of another release can answer without an error and still do something else (type into
+ * nothing): what to tell the person running it, or nothing when the two match.
+ */
+export const agentMismatch = (hello, cli = CLI_VERSION) => {
+    if (hello.agentVersion === cli)
+        return undefined;
+    const agent = hello.agentVersion ? `lynkeus-agent ${hello.agentVersion}` : 'a lynkeus-agent too old to say its version';
+    return `⚠️  The app runs ${agent}, this CLI is lynkeus ${cli}: they can misread each other without an error. Install lynkeus-agent@${cli} in the app and rebuild it (or run the lynkeus CLI of the agent's version).`;
+};

package/lib/device/devices.d.ts

@@ -7,5 +7,10 @@ export type DeviceInfo = {
     connected: boolean;
 };
 export declare const bootedSimulators: () => Promise<DeviceInfo[]>;
+/** The serials `adb devices` lists as ready, in its order; none when there is no adb to ask. */
+export declare const parseAdbDevices: (stdout: string) => DeviceInfo[];
+export declare const androidDevices: () => Promise<DeviceInfo[]>;
+/** The Android device an app that said it runs on Android is on: the one asked for, or the first that is up. */
+export declare const pickAndroidDevice: (wanted?: string) => Promise<DeviceInfo>;
 export declare const HEADLESS_HOST: DeviceInfo;
 export declare const pickAgentDevice: (wanted?: string) => Promise<DeviceInfo>;

package/lib/device/devices.js

@@ -18,6 +18,33 @@ export const bootedSimulators = async () => {
         .filter((d) => d.state === 'Booted')
         .map((d) => ({ id: d.udid, name: d.name, platform: 'ios', type: 'simulator', connected: true }));
 };
+/** The serials `adb devices` lists as ready, in its order; none when there is no adb to ask. */
+export const parseAdbDevices = (stdout) => stdout
+    .split('\n')
+    .slice(1)
+    .map((line) => line.trim().split(/\s+/))
+    .filter(([serial, state]) => serial && state === 'device')
+    .map(([serial]) => ({ id: serial, name: serial, platform: 'android', type: serial.startsWith('emulator-') ? 'emulator' : 'physical', connected: true }));
+export const androidDevices = async () => {
+    try {
+        return parseAdbDevices((await run('adb', ['devices'])).stdout);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+/** The Android device an app that said it runs on Android is on: the one asked for, or the first that is up. */
+export const pickAndroidDevice = async (wanted) => {
+    const devices = await androidDevices();
+    const id = wanted ?? process.env.LYNKEUS_DEVICE;
+    // A name meant for a simulator (the config's `device` when both platforms are driven) is not a reason to fail here.
+    const device = (id ? devices.find((d) => d.id === id) : undefined) ?? devices[0];
+    if (!device)
+        throw new Error('No Android device or emulator is up (adb devices lists none).');
+    return device;
+};
 export const HEADLESS_HOST = { id: 'headless', name: 'headless host', platform: 'ios', type: 'simulator', connected: true };
 export const pickAgentDevice = async (wanted) => {
     const devices = await bootedSimulators();

package/lib/flow/runner.js

@@ -86,6 +86,34 @@ export const runFlow = async (flow, options) => {
     }
     return report;
 };
+/**
+ * A keypad the app raises slides in, and under load its keys are listed a while before they can take a
+ * press: disabled, under the screen it is leaving, or still moving. A press then lands on nothing, and the
+ * code comes up a digit short.
+ */
+const keyReady = async (device, key, timeoutMs) => {
+    const deadline = Date.now() + timeoutMs;
+    let was;
+    for (;;) {
+        const found = (await device.server.call('find', key));
+        const at = found ? JSON.stringify(found.frame) : undefined;
+        const why = !found || (found.hidden && found.hidden !== 'inert')
+            ? 'not on screen'
+            : !found.enabled
+                ? 'disabled'
+                : found.covered
+                    ? 'covered'
+                    : at !== was
+                        ? 'moving'
+                        : undefined;
+        if (!why)
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`keypad key #${key.testId} is ${why} after ${timeoutMs} ms`);
+        was = at;
+        await device.idle({ quietMs: 50, timeoutMs: 200 }).catch(() => undefined);
+    }
+};
 const execute = async (step, flow, device, vars) => {
     if ('note' in step)
         return;
@@ -118,7 +146,11 @@ const execute = async (step, flow, device, vars) => {
     }
     if ('keypad' in step) {
         for (const digit of step.keypad.digits) {
-            await device.press({ testId: step.keypad.pattern.replace('{d}', digit), mode: step.keypad.mode });
+            const key = { testId: step.keypad.pattern.replace('{d}', digit) };
+            await keyReady(device, key, step.keypad.timeoutMs ?? 5000);
+            await device.press({ ...key, mode: step.keypad.mode });
+            // A code field fed by the app's state drops a digit pressed before the last one rendered.
+            await device.idle({ quietMs: 50, timeoutMs: 400 }).catch(() => undefined);
         }
         return;
     }

package/lib/flow/types.d.ts

@@ -61,12 +61,13 @@ export type FlowStep =
         gone?: boolean;
     };
 }
-/** Presses one button per digit, e.g. a code on `digit-{d}-button`. */
+/** Presses one button per digit, e.g. a code on `digit-{d}-button`, each once it is there, enabled, uncovered and still (`timeoutMs` per key, 5000 by default). */
  | {
     keypad: {
         digits: string;
         pattern: string;
         mode?: 'native' | 'js';
+        timeoutMs?: number;
     };
 }
 /** An app command registered with `qa.register`; the result is saved under `as`. */

package/lib/knowledge/contrast.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How well a screen's text stands out from what is behind it, measured on the pixels of a screenshot: the
+ * colors an app declares say nothing of a label over a photo, a gradient or a translucent sheet.
+ */
+import type { Screen } from 'lynkeus-protocol';
+import type { Finding } from './lint.js';
+export type Pixels = {
+    width: number;
+    height: number;
+    data: Uint8Array | Buffer;
+};
+export type Rgb = [number, number, number];
+export type Contrast = {
+    ratio: number;
+    text: Rgb;
+    background: Rgb;
+    plain: boolean;
+};
+export type ContrastOptions = {
+    /** The least ratio for ordinary text (WCAG 2 AA asks 4.5). */
+    normal?: number;
+    /** The least ratio for large text: 18 points, or 14 and bold (WCAG 2 AA asks 3). */
+    large?: number;
+    /** testIDs left out: a watermark, a brand color nobody may change. */
+    ignore?: RegExp[];
+};
+/** WCAG's relative luminance of an sRGB color. */
+export declare const luminance: ([r, g, b]: Rgb) => number;
+/** WCAG's contrast ratio, from 1 (the same color) to 21 (black on white). */
+export declare const contrastRatio: (a: Rgb, b: Rgb) => number;
+export declare const hex: (rgb: Rgb) => string;
+/**
+ * The contrast of the text inside a rectangle of the picture, in pixels. The background is the color most
+ * of the rectangle has; the text is the color, among those with enough pixels to be glyphs, that stands
+ * furthest from it. Anything else in the box (an icon beside a label) can only raise the figure, so a low one
+ * is a finding and a high one is not a certificate.
+ */
+export declare const measureContrast: (picture: Pixels, box: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}) => Contrast | undefined;
+/** A finding for every text on the screen whose contrast falls short, most serious first. */
+export declare const lintContrast: (screen: Screen, picture: Pixels, options?: ContrastOptions) => Finding[];