lynkeus 0.2.0

package/lib/__tests__/args.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/args.test.js

@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { pairs, parseArgs, splitLine, UsageError } from '../args.js';
+import { driveCommands } from '../commands/drive.js';
+import { headlessCommands } from '../commands/headless.js';
+import { mapCommands } from '../commands/map.js';
+import { osCommands } from '../commands/os.js';
+import { runsCommands } from '../commands/runs.js';
+const FLAGS = {
+    direct: { type: 'boolean', help: '' },
+    depth: { type: 'number', help: '', default: 4 },
+    var: { type: 'list', help: '' },
+    out: { type: 'string', help: '' },
+};
+test('booleans never eat the next positional; numbers are numbers; lists collect', () => {
+    const p = parseArgs(['--direct', 'a.ts', 'b.ts', '--depth', '2', '--var', 'x=1', '--var', 'y=2'], [{ name: 'file', help: '', required: true, rest: true }], FLAGS);
+    assert.deepEqual(p.args, ['a.ts', 'b.ts']);
+    assert.equal(p.flags.direct, true);
+    assert.equal(p.flags.depth, 2);
+    assert.deepEqual(p.flags.var, ['x=1', 'y=2']);
+    assert.deepEqual(pairs(p.flags.var), { x: '1', y: '2' });
+});
+test('defaults, --no-flag, --flag=value and passthrough after --', () => {
+    const p = parseArgs(['--no-direct', '--out=x.json', '--', '--jest-flag'], [], FLAGS);
+    assert.equal(p.flags.direct, false);
+    assert.equal(p.flags.depth, 4);
+    assert.equal(p.flags.out, 'x.json');
+    assert.deepEqual(p.passthrough, ['--jest-flag']);
+});
+test('unknown flags, missing values and missing positionals are usage errors that name what exists', () => {
+    assert.throws(() => parseArgs(['--nope'], [], FLAGS), (e) => e instanceof UsageError && /--direct/.test(e.message));
+    assert.throws(() => parseArgs(['--depth', '--direct'], [], FLAGS), /--depth needs a value/);
+    assert.throws(() => parseArgs(['--depth', 'x'], [], FLAGS), /expects a number/);
+    assert.throws(() => parseArgs([], [{ name: 'target', help: '', required: true }], FLAGS), /missing <target>/);
+    assert.throws(() => parseArgs(['a', 'b'], [{ name: 'one', help: '' }], FLAGS), /unexpected argument "b"/);
+});
+test('a session line splits on spaces and keeps quoted text together', () => {
+    assert.deepEqual(splitLine('press "Comenzar ya" --hold 200'), ['press', 'Comenzar ya', '--hold', '200']);
+});
+test('every command is named once, documented, and its aliases are unique', () => {
+    const all = [...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...headlessCommands];
+    const names = new Set();
+    for (const c of all) {
+        assert.ok(c.summary.length > 10, `${c.name} has a summary`);
+        assert.ok(!names.has(c.name), `${c.name} defined once`);
+        names.add(c.name);
+        for (const a of c.aliases ?? []) {
+            assert.ok(!names.has(a), `${a} unique`);
+            names.add(a);
+        }
+        for (const [flag, spec] of Object.entries(c.flags ?? {}))
+            assert.ok(spec.help, `${c.name} --${flag} has help`);
+        for (const p of c.positionals ?? [])
+            assert.ok(p.help, `${c.name} <${p.name}> has help`);
+    }
+    for (const short of ['plan', 'deeplink', 'appstate', 'network', 'clock', 'biometrics', 'scan', 'gallery', 'headless'])
+        assert.ok(names.has(short), `${short} accepted`);
+});
+test('MCP serves a small core by default and everything else on request', () => {
+    const all = [...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...headlessCommands];
+    const core = all.filter((c) => c.mcp === 'core').map((c) => c.name);
+    assert.deepEqual(core.sort(), ['call', 'map plan', 'map show', 'os deeplink', 'press', 'screen', 'type', 'wait', 'why']);
+});
+test('what MCP leaves out of a tool is still a flag of the command', () => {
+    for (const c of [...driveCommands, ...osCommands, ...mapCommands, ...runsCommands, ...headlessCommands]) {
+        for (const flag of c.mcpOmit ?? [])
+            assert.ok(c.flags?.[flag], `${c.name} omits --${flag}, which it does not have`);
+    }
+});

package/lib/__tests__/check.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/check.test.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { diffGraphs, newFindings } from '../commands/check.js';
+import { mapCheckWorkflow } from '../commands/map.js';
+import { summarizeRuns } from '../commands/flake.js';
+const graph = (screens, files) => ({
+    app: 'x',
+    root: '/x',
+    extractedAt: '',
+    warnings: [],
+    screens: Object.fromEntries(Object.entries(screens).map(([route, file]) => [route, { route, component: route, file, declaredIn: 'nav.tsx' }])),
+    files: Object.fromEntries(Object.entries(files).map(([file, f]) => [
+        file,
+        {
+            selectors: (f.selectors ?? []).map((id) => ({ id, line: 1 })),
+            navigates: (f.navigates ?? []).map((to) => ({ to, line: 1, confidence: 'static', via: { kind: 'unknown' } })),
+            imports: [],
+        },
+    ])),
+});
+test('a graph diff names routes, navigations and testIDs that changed', () => {
+    const base = graph({ A: 'a.tsx', B: 'b.tsx' }, { 'a.tsx': { selectors: ['go-b'], navigates: ['B'] }, 'b.tsx': { selectors: ['submit'] } });
+    const head = graph({ A: 'a.tsx', B: 'b.tsx', C: 'c.tsx' }, { 'a.tsx': { selectors: ['go-b', 'go-c'], navigates: ['B', 'C'] }, 'b.tsx': {}, 'c.tsx': {} });
+    const d = diffGraphs(base, head);
+    assert.deepEqual(d.routesAdded, ['C']);
+    assert.deepEqual(d.edgesAdded, [{ from: 'A', to: 'C' }]);
+    assert.deepEqual(d.selectorsAdded, [{ file: 'a.tsx', id: 'go-c' }]);
+    assert.deepEqual(d.selectorsRemoved, [{ file: 'b.tsx', id: 'submit' }]);
+});
+test('lint findings already in the baseline are not new', () => {
+    const f1 = { finding: { rule: 'unlabeled-control', severity: 'warn', element: 3, message: 'button without a label' }, testId: 'x' };
+    const f2 = { finding: { rule: 'small-target', severity: 'warn', element: 4, message: '20×20' }, testId: 'y' };
+    const fresh = newFindings({ A: [{ rule: 'unlabeled-control', testId: 'x', message: 'button without a label' }] }, 'A', [f1, f2]);
+    assert.deepEqual(fresh, [f2]);
+});
+test('flake runs are summarised by the step and error they died on', () => {
+    const ok = (ms) => ({ name: 'f', ok: true, totalMs: ms, vars: {}, steps: [{ step: { press: { testId: 'a' } }, ok: true, ms: 1 }] });
+    const bad = (err) => ({
+        name: 'f',
+        ok: false,
+        totalMs: 900,
+        vars: {},
+        steps: [
+            { step: { press: { testId: 'a' } }, ok: true, ms: 1 },
+            { step: { waitFor: { route: 'A' } }, ok: false, ms: 1, error: err },
+        ],
+    });
+    const s = summarizeRuns([ok(100), bad('Timed out waiting for A (on Z)'), ok(300), bad('Timed out waiting for A (on Y)')]);
+    assert.equal(s.passed, 2);
+    assert.equal(s.failures.length, 1);
+    assert.equal(s.failures[0].times, 2);
+    assert.equal(s.failures[0].step, 2);
+    assert.match(s.failures[0].what, /waitFor/);
+});
+test('the map check workflow diffs against the pull request base and keeps one comment', () => {
+    const yml = mapCheckWorkflow(2);
+    assert.match(yml, /lynkeus map check --base origin\/\$\{\{ github\.base_ref \}\} --depth 2/);
+    assert.match(yml, /--edit-last/);
+    assert.match(yml, /pull-requests: write/);
+});

package/lib/__tests__/init.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/init.test.js

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { init } from '../commands/init.js';
+import { explainError } from '../knowledge/errors.js';
+const tmpApp = () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-init-'));
+    fs.mkdirSync(path.join(root, 'app'));
+    fs.writeFileSync(path.join(root, 'app', 'App.tsx'), 'export default () => null');
+    fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'demo' }));
+    fs.writeFileSync(path.join(root, 'index.js'), "import { AppRegistry } from 'react-native'\nimport App from './app/App'\n\nAppRegistry.registerComponent('demo', () => App)\n");
+    return root;
+};
+test('init writes an entry that requires the app and refuses non-local backends', () => {
+    const root = tmpApp();
+    const notes = init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: false, force: false });
+    const entry = fs.readFileSync(path.join(root, 'qa/headless.tsx'), 'utf8');
+    assert.match(entry, /require\('\.\.\/app\/App'\)/);
+    assert.match(entry, /process\.env\.API_URL/);
+    assert.match(entry, /installDefaultMocks/);
+    assert.ok(notes.some((n) => n.includes('wrote qa/headless.tsx')));
+    // Second run leaves it alone.
+    const again = init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: false, force: false });
+    assert.ok(again.some((n) => n.includes('left as is')));
+});
+test('init --auto adds the mount after the imports, once', () => {
+    const root = tmpApp();
+    init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: true, force: false });
+    init(root, { entry: 'qa/headless.tsx', apiEnv: 'API_URL', auto: true, force: false });
+    const index = fs.readFileSync(path.join(root, 'index.js'), 'utf8');
+    assert.equal(index.split('lynkeus-agent/auto').length, 2);
+    assert.ok(index.indexOf('auto(') < index.indexOf('registerComponent'));
+    assert.ok(index.indexOf("import App from './app/App'") < index.indexOf('lynkeus-agent/auto'));
+});
+test('the error catalogue names the module behind a TurboModule crash', () => {
+    const [e] = explainError("Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'RNCWebView' could not be found. Verify that a module by this name is registered");
+    assert.ok(e);
+    assert.match(e.cause, /RNCWebView/);
+    assert.equal(explainError('all good').length, 0);
+});

package/lib/__tests__/record.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/record.test.js

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { simulatorArgv } from '../commands/device.js';
+import { draftFlow } from '../commands/record.js';
+const ev = (partial, seq) => ({ seq, t: seq * 100, ...partial });
+test('a recording becomes presses with what each one caused', () => {
+    const flow = draftFlow([
+        ev({ kind: 'route', route: 'First.Screen', path: ['First.Screen'] }, 1),
+        ev({ kind: 'touch', x: 10, y: 20, testId: 'primary-button', route: 'First.Screen' }, 2),
+        ev({ kind: 'request', method: 'GET', url: 'http://x/api/items', status: 200, ms: 40 }, 3),
+        ev({ kind: 'route', route: 'Second.Screen', path: ['Second.Screen'] }, 4),
+        ev({ kind: 'touch', x: 10, y: 20, text: 'Second option', route: 'Second.Screen' }, 5),
+        ev({ kind: 'store', store: 'session', changed: { step: { from: 1, to: 2 } } }, 6),
+        ev({ kind: 'touch', x: 5, y: 5, route: 'Second.Screen' }, 7),
+    ]);
+    assert.deepEqual(flow.steps, [
+        { press: { testId: 'primary-button' } },
+        { waitFor: { route: 'Second.Screen', timeoutMs: 10000 } },
+        { note: 'requests: GET /api/items 200' },
+        { press: { text: 'Second option' } },
+        { note: 'stores changed: session.step' },
+        { note: 'touch at 5,5 on Second.Screen hit nothing lynkeus could name' },
+    ]);
+});
+test('device subcommands map to simctl and adb', () => {
+    assert.deepEqual(simulatorArgv('ios', 'UDID', 'permissions', ['grant', 'camera'], 'com.example.myapp')[0], {
+        bin: 'xcrun',
+        args: ['simctl', 'privacy', 'UDID', 'grant', 'camera', 'com.example.myapp'],
+    });
+    assert.deepEqual(simulatorArgv('ios', 'UDID', 'appearance', ['dark'])[0].args, ['simctl', 'ui', 'UDID', 'appearance', 'dark']);
+    assert.deepEqual(simulatorArgv('ios', 'UDID', 'location', ['-34.6,-58.4'])[0].args, ['simctl', 'location', 'UDID', 'set', '-34.6,-58.4']);
+    assert.equal(simulatorArgv('ios', 'UDID', 'language', ['de-DE'], 'com.example.myapp').length, 2);
+    assert.deepEqual(simulatorArgv('android', 'emu', 'permissions', ['grant', 'camera'], 'com.example.myapp')[0].args, [
+        '-s',
+        'emu',
+        'shell',
+        'pm',
+        'grant',
+        'com.example.myapp',
+        'android.permission.CAMERA',
+    ]);
+    assert.throws(() => simulatorArgv('ios', 'UDID', 'permissions', ['grant', 'camera']), /--app/);
+    assert.throws(() => simulatorArgv('ios', 'UDID', 'appearance', ['blue']), /light\|dark/);
+});

package/lib/__tests__/snapshot.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/snapshot.test.js

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+import { PNG } from 'pngjs';
+import { comparePng, snapshot } from '../commands/snapshot.js';
+const png = (w, h, paint) => {
+    const p = new PNG({ width: w, height: h });
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++) {
+            const i = (y * w + x) * 4;
+            const [r, g, b] = paint(x, y);
+            p.data[i] = r;
+            p.data[i + 1] = g;
+            p.data[i + 2] = b;
+            p.data[i + 3] = 255;
+        }
+    return PNG.sync.write(p);
+};
+test('pixels that moved are counted and painted into a diff', () => {
+    const a = png(10, 10, () => [255, 255, 255]);
+    const b = png(10, 10, (x, y) => (x < 2 && y < 2 ? [0, 0, 0] : [250, 250, 250]));
+    const c = comparePng(a, b);
+    assert.equal(c.different, 4); // the 250 vs 255 shade stays under the channel threshold
+    assert.equal(c.ratio, 0.04);
+    assert.ok(c.diff);
+    const d = PNG.sync.read(c.diff);
+    assert.deepEqual([d.data[0], d.data[1], d.data[2]], [255, 0, 0]);
+});
+test('a first capture is the baseline; a small change matches; a big one writes a diff', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-snap-'));
+    const lynkeusDir = path.join(root, '.lynkeus');
+    const runsDir = path.join(lynkeusDir, 'runs');
+    const white = png(20, 20, () => [255, 255, 255]);
+    assert.equal(snapshot(lynkeusDir, 'card', white, { runsDir }).status, 'baseline');
+    const nearly = png(20, 20, (x, y) => (x === 0 && y === 0 ? [0, 0, 0] : [255, 255, 255]));
+    assert.equal(snapshot(lynkeusDir, 'card', nearly, { runsDir, tolerance: 0.01 }).status, 'match');
+    const half = png(20, 20, (x) => (x < 10 ? [0, 0, 0] : [255, 255, 255]));
+    const r = snapshot(lynkeusDir, 'card', half, { runsDir });
+    assert.equal(r.status, 'mismatch');
+    assert.ok(fs.existsSync(r.diffFile));
+    assert.equal(snapshot(lynkeusDir, 'card', half, { runsDir, update: true }).status, 'baseline');
+    assert.equal(snapshot(lynkeusDir, 'card', half, { runsDir }).status, 'match');
+    const other = png(30, 20, () => [255, 255, 255]);
+    assert.ok(snapshot(lynkeusDir, 'card', other, { runsDir }).comparison?.sizeMismatch);
+});

package/lib/__tests__/targets.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/targets.test.js

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { describeScreen } from '../device/driver.js';
+import { parseTarget, scopedTarget } from '../targets.js';
+test('a #-prefixed string is a testId', () => {
+    assert.deepEqual(parseTarget('#next-button'), { testId: 'next-button' });
+});
+test('an x,y pair is a point', () => {
+    assert.deepEqual(parseTarget('100,200'), { x: 100, y: 200 });
+});
+test('a bare integer is an index', () => {
+    assert.deepEqual(parseTarget('12'), { i: 12 });
+});
+test('anything else is text', () => {
+    assert.deepEqual(parseTarget('Some label'), { text: 'Some label' });
+});
+test('a testId that contains a comma is still a testId, not a point', () => {
+    assert.deepEqual(parseTarget('#a,b'), { testId: 'a,b' });
+});
+test('describeScreen prints the value a QR image carries', () => {
+    const screen = {
+        route: 'X',
+        path: ['X'],
+        commit: 1,
+        busy: false,
+        window: { w: 390, h: 844 },
+        costMs: 1,
+        elements: [{ i: 0, kind: 'image', frame: { x: 0, y: 0, w: 168, h: 169 }, enabled: true, depth: 0, accessibilityLabel: 'qr', value: 'QR-TEST-0001' }],
+    };
+    assert.match(describeScreen(screen), /image .*value="QR-TEST-0001"/);
+});
+test('describeScreen lists a view with a testID and leaves plain layout out', () => {
+    const screen = {
+        route: 'X',
+        path: ['X'],
+        commit: 1,
+        busy: false,
+        window: { w: 390, h: 844 },
+        costMs: 1,
+        elements: [
+            { i: 0, kind: 'view', frame: { x: 0, y: 0, w: 390, h: 844 }, enabled: true, depth: 0 },
+            { i: 1, kind: 'view', frame: { x: 0, y: 0, w: 390, h: 400 }, enabled: true, depth: 1, testId: 'intro-page-advances' },
+        ],
+    };
+    const text = describeScreen(screen);
+    assert.match(text, /view +#intro-page-advances/);
+    assert.doesNotMatch(text, /^0? ?view$/m);
+});
+test('describeScreen leaves out what is not presented, counts it, and lists it with --all', () => {
+    const el = (i, over) => ({ i, kind: 'button', frame: { x: 0, y: 0, w: 100, h: 40 }, enabled: true, depth: 0, ...over });
+    const screen = {
+        route: 'X',
+        path: ['X'],
+        commit: 7,
+        busy: false,
+        window: { w: 390, h: 844 },
+        costMs: 3,
+        elements: [
+            el(0, { testId: 'tab-a', hidden: 'a11y' }),
+            el(1, { testId: 'behind', hidden: 'behind-overlay' }),
+            el(2, { testId: 'slide', hidden: 'inert' }),
+            el(3, { testId: 'close', enabled: false }),
+        ],
+    };
+    const text = describeScreen(screen);
+    assert.equal(text.split('\n')[0] ?? '', 'X · 2 hidden: 1 a11y, 1 behind-overlay');
+    assert.doesNotMatch(text, /#tab-a|#behind/);
+    assert.match(text, /^button #slide ~inert$/m);
+    assert.match(text, /^button #close !disabled$/m);
+    assert.match(describeScreen(screen, { all: true }), /#behind ~behind-overlay/);
+    assert.match(describeScreen(screen, { frames: true }), /#slide ~inert @50,20$/m);
+    assert.match(describeScreen(screen, { verbose: true }).split('\n')[0] ?? '', /commit=7 3ms/);
+});
+test("describeScreen leaves a button's icon out", () => {
+    const screen = {
+        route: 'X',
+        path: ['X'],
+        commit: 1,
+        busy: false,
+        window: { w: 390, h: 844 },
+        costMs: 1,
+        elements: [
+            { i: 0, kind: 'button', frame: { x: 0, y: 0, w: 100, h: 40 }, enabled: true, depth: 0, testId: 'open' },
+            { i: 1, kind: 'view', frame: { x: 0, y: 0, w: 20, h: 20 }, enabled: true, depth: 1, testId: 'SvgArrow', parent: 0 },
+            { i: 2, kind: 'view', frame: { x: 0, y: 50, w: 20, h: 20 }, enabled: true, depth: 0, testId: 'page-marker' },
+        ],
+    };
+    assert.doesNotMatch(describeScreen(screen), /SvgArrow/);
+    assert.match(describeScreen(screen), /#page-marker/);
+    assert.match(describeScreen(screen, { all: true }), /SvgArrow/);
+});
+test('describeScreen gives an index only to what cannot be named apart', () => {
+    const el = (i, over) => ({ i, kind: 'button', frame: { x: 0, y: 0, w: 100, h: 40 }, enabled: true, depth: 0, ...over });
+    const screen = {
+        route: 'X',
+        path: ['X'],
+        commit: 1,
+        busy: false,
+        window: { w: 390, h: 844 },
+        costMs: 1,
+        elements: [
+            el(0, { testId: 'save' }),
+            el(1, { testId: 'like' }),
+            el(2, { testId: 'like' }),
+            el(3, { kind: 'text', text: 'Hello' }),
+            el(4, { kind: 'view', testId: 'marker', accessibilityLabel: 'marker' }),
+            el(5, {}),
+        ],
+    };
+    assert.deepEqual(describeScreen(screen).split('\n').slice(1), [
+        'button #save',
+        '1 button #like',
+        '2 button #like',
+        'text "Hello"',
+        'view #marker',
+        '5 button',
+    ]);
+});
+test('a [n] suffix picks the nth match of a testId or text', () => {
+    assert.deepEqual(parseTarget('#field[2]'), { testId: 'field', nth: 2 });
+    assert.deepEqual(parseTarget('Ciudad[0]'), { text: 'Ciudad', nth: 0 });
+});
+test('--in and --nth narrow a target', () => {
+    assert.deepEqual(scopedTarget('#like-message-button', { in: 'hi from Ana' }), { testId: 'like-message-button', within: { text: 'hi from Ana' } });
+    assert.deepEqual(scopedTarget('#like-message-button', { in: '#feed', nth: 2 }), { testId: 'like-message-button', within: { testId: 'feed' }, nth: 2 });
+    assert.deepEqual(scopedTarget('100,200', { in: '#feed' }), { x: 100, y: 200 });
+});

package/lib/args.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Booleans never consume the next token (`--direct a.ts` keeps `a.ts`),
+ * `--no-<flag>` clears one, and a repeated list flag collects.
+ */
+export type FlagSpec = {
+    type: 'string' | 'number' | 'boolean' | 'list';
+    help: string;
+    default?: string | number | boolean;
+    /** The placeholder in usage: `--timeout <ms>`. */
+    value?: string;
+};
+export type PositionalSpec = {
+    name: string;
+    help: string;
+    required?: boolean;
+    /** Takes every argument left. */
+    rest?: boolean;
+};
+export type FlagValues = Record<string, string | number | boolean | string[] | undefined>;
+export declare class UsageError extends Error {
+}
+export declare const GLOBAL_FLAGS: Record<string, FlagSpec>;
+export declare const parseArgs: (argv: string[], positionals?: PositionalSpec[], flags?: Record<string, FlagSpec>) => {
+    args: string[];
+    flags: FlagValues;
+    passthrough: string[];
+};
+export declare const pairs: (list: string[] | undefined) => Record<string, string>;
+/** Double quotes group; everything else splits on spaces. */
+export declare const splitLine: (line: string) => string[];

package/lib/args.js

@@ -0,0 +1,86 @@
+export class UsageError extends Error {
+}
+export const GLOBAL_FLAGS = {
+    root: { type: 'string', help: "the app's folder (default: the current one)", value: 'dir' },
+    device: { type: 'string', help: 'simulator udid or name', value: 'udid|name' },
+    app: { type: 'string', help: 'bundle id, for launching and simulator commands', value: 'bundleId' },
+    launch: { type: 'boolean', help: 'relaunch the app before attaching (needs --app)' },
+    'attach-timeout': { type: 'number', help: 'how long to wait for the app to attach', default: 15000, value: 'ms' },
+    json: { type: 'boolean', help: 'machine-readable output when the command has one' },
+    help: { type: 'boolean', help: 'this text' },
+};
+export const parseArgs = (argv, positionals = [], flags = {}) => {
+    const specs = { ...GLOBAL_FLAGS, ...flags };
+    const out = {};
+    const args = [];
+    let passthrough = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--') {
+            passthrough = argv.slice(i + 1);
+            break;
+        }
+        if (token.startsWith('--') && token.length > 2) {
+            const eq = token.indexOf('=');
+            let name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+            let inline = eq === -1 ? undefined : token.slice(eq + 1);
+            let negated = false;
+            if (!specs[name] && name.startsWith('no-') && specs[name.slice(3)]?.type === 'boolean') {
+                name = name.slice(3);
+                negated = true;
+            }
+            const spec = specs[name];
+            if (!spec)
+                throw new UsageError(`unknown flag --${name}; flags: ${Object.keys(specs)
+                    .map((f) => `--${f}`)
+                    .join(' ')}`);
+            if (spec.type === 'boolean') {
+                out[name] = !negated && (inline === undefined ? true : inline !== 'false');
+                continue;
+            }
+            if (inline === undefined) {
+                inline = argv[i + 1];
+                if (inline === undefined || (inline.startsWith('--') && inline.length > 2))
+                    throw new UsageError(`--${name} needs a value${spec.value ? ` <${spec.value}>` : ''}`);
+                i++;
+            }
+            if (spec.type === 'number') {
+                const n = Number(inline);
+                if (Number.isNaN(n))
+                    throw new UsageError(`--${name} expects a number, got "${inline}"`);
+                out[name] = n;
+            }
+            else if (spec.type === 'list') {
+                out[name] = [...(out[name] ?? []), inline];
+            }
+            else
+                out[name] = inline;
+            continue;
+        }
+        args.push(token);
+    }
+    for (const [name, spec] of Object.entries(specs))
+        if (out[name] === undefined && spec.default !== undefined)
+            out[name] = spec.default;
+    const required = positionals.filter((p) => p.required);
+    if (args.length < required.length)
+        throw new UsageError(`missing ${required
+            .slice(args.length)
+            .map((p) => `<${p.name}>`)
+            .join(' ')}`);
+    const last = positionals[positionals.length - 1];
+    if (!last?.rest && args.length > positionals.length)
+        throw new UsageError(`unexpected argument "${args[positionals.length]}"`);
+    return { args, flags: out, passthrough };
+};
+export const pairs = (list) => {
+    const out = {};
+    for (const item of list ?? []) {
+        const eq = item.indexOf('=');
+        if (eq > 0)
+            out[item.slice(0, eq)] = item.slice(eq + 1);
+    }
+    return out;
+};
+/** Double quotes group; everything else splits on spaces. */
+export const splitLine = (line) => (line.match(/"[^"]*"|\S+/g) ?? []).map((a) => a.replace(/^"|"$/g, ''));

package/lib/cases/__tests__/format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/cases/__tests__/format.test.js

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { dig, interpolate, matcherOf, matches, parseCase, readCases } from '../format.js';
+const CASE = `---
+id: gift
+title: "A gift shows up"
+---
+setup:
+  - create_user: { as: u, name: "Ana" }
+steps:
+  - app.press: "#open"
+  - app.back
+  - assert: { user: u, path: score, equals: 25 }
+expected: |
+  The score is 25.
+`;
+test('a case is its frontmatter, its setup, its steps and what it expects', () => {
+    const c = parseCase(CASE, 'cases/gift.md');
+    assert.equal(c.id, 'gift');
+    assert.deepEqual(c.setup, [{ verb: 'create_user', value: { as: 'u', name: 'Ana' } }]);
+    assert.deepEqual(c.steps.map((s) => s.verb), ['app.press', 'app.back', 'assert']);
+    assert.equal(c.expected, 'The score is 25.');
+});
+test('a file without frontmatter, or a step with two verbs, is refused with its place', () => {
+    assert.throws(() => parseCase('steps: []', 'x.md'), /x\.md: no frontmatter/);
+    assert.throws(() => parseCase('---\nid: x\n---\nsteps:\n  - { a: 1, b: 2 }\n', 'x.md'), /steps\[0\] must be one step/);
+});
+test('a path reads into lists, and a star collects from every element', () => {
+    const json = { accounts: [{ code: 'usd' }, { code: 'eur' }], user: { id: 7 } };
+    assert.equal(dig(json, 'accounts.1.code'), 'eur');
+    assert.deepEqual(dig(json, 'accounts.*.code'), ['usd', 'eur']);
+    assert.equal(dig(json, 'user.name.first'), undefined);
+});
+test('a reference alone keeps its type; inside text it is text; a missing one says which', () => {
+    const scope = { u: { user_id: 7, name: 'Ana' } };
+    assert.deepEqual(interpolate({ id: '{{u.user_id}}', hi: 'hi {{u.name}}', n: 3 }, scope), { id: 7, hi: 'hi Ana', n: 3 });
+    assert.match(interpolate('x{{random.letters}}', scope), /^x[a-z]{6}$/);
+    assert.throws(() => interpolate('{{v.user_id}}', scope), /no alias 'v'/);
+    assert.throws(() => interpolate('{{u.phone}}', scope), /\{\{u\.phone\}\} is empty/);
+});
+test('matchers compare numbers as numbers and lists by any element', () => {
+    assert.equal(matches('25.0', { equals: 25 }), true);
+    assert.equal(matches('abc', { equals: 'abc' }), true);
+    assert.equal(matches(['usd', 'bridge_usd'], { includes: 'bridge' }), true);
+    assert.equal(matches(9, { gte: 10 }), false);
+    assert.equal(matches(null, { absent: true }), true);
+    assert.equal(matches('AUTORIZADO', { matches: '^AUT' }), true);
+    assert.deepEqual(matcherOf({ path: 'a', equals: 1, user: 'u' }), { equals: 1 });
+    assert.equal(matcherOf({ path: 'a' }), undefined);
+});
+test('a case with a matrix runs once per combination, named after it', () => {
+    const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'lynkeus-matrix-')), 'm.md');
+    fs.writeFileSync(file, '---\nid: m\nmatrix: { locale: [en, fr], login: [phone] }\n---\nsteps:\n  - create_user: { locale: "{{matrix.locale}}" }\n');
+    const cases = readCases(file);
+    assert.deepEqual(cases.map((c) => c.id), ['m[locale=en,login=phone]', 'm[locale=fr,login=phone]']);
+    assert.deepEqual(cases[1].setup, []);
+    assert.deepEqual(cases[1].steps[0].value, { locale: 'fr' });
+});

package/lib/cases/__tests__/runner.test.d.ts

@@ -0,0 +1 @@
+export {};