browser-broker 0.1.0

package/dist/src/cli/commands.js

@@ -0,0 +1,270 @@
+import { PAGE_ACTIONS } from "../browser/driver.js";
+/**
+ * The action verbs, for the help text.
+ *
+ * Read from the same list the service validates against, so a verb added
+ * there appears in `broker act --help` without anybody remembering to add it
+ * — the drift this table's own header warns about.
+ */
+const PAGE_ACTION_NAMES = PAGE_ACTIONS;
+/**
+ * Twelve commands for twelve tools (§5.3).
+ *
+ * ── Two of them are `broker sign in` and `broker sign in done` ──────────
+ *
+ * **Not `broker login`, which stays exactly where it is** (§5.5). That
+ * command is a person driving, and these two are a *caller* asking a person
+ * to drive — they take a lease key, and `broker login` has no lease in the
+ * picture at all. Both routes in exist on purpose and §5.5.1 says which is
+ * which: sign in ahead of time with `broker login` when you know a profile
+ * needs it, and let a caller ask on demand when it turns out one does.
+ *
+ * The words join to the operation name (`sign in` to `sign_in`, `sign in
+ * done` to `sign_in_done`), which is not a coincidence: `check-operations.mjs`
+ * derives a command's operation by joining its words with an underscore, so a
+ * command spelled any other way would be invisible to the check that proves
+ * the shipped executable reaches the service.
+ *
+ * The diff rides on `capture` as an argument exactly as it does on the tool
+ * surface (§3.11) rather than being an eleventh command, and the two removed
+ * tools are absent rather than deprecated (§3.1).
+ */
+export const OPERATION_COMMANDS = [
+    {
+        words: ['claim'],
+        operation: 'claim',
+        summary: 'Ask for a lease. Get one tab, or a place in the queue.',
+        options: [
+            {
+                flag: '--wait',
+                summary: 'Poll a queued place until it is granted, lost or refused, rather than returning the place.',
+            },
+        ],
+    },
+    { words: ['status'], operation: 'status', summary: 'Where your lease stands. Extends it.' },
+    {
+        words: ['release'],
+        operation: 'release',
+        summary: 'Give back your tab, or your place in the queue.',
+    },
+    {
+        words: ['tab', 'replace'],
+        operation: 'tab_replace',
+        summary: 'Discard this lease’s tab and open a fresh one in its place.',
+    },
+    { words: ['navigate'], operation: 'navigate', summary: 'Point your tab at an address.' },
+    {
+        words: ['act'],
+        operation: 'act',
+        summary: 'Click, type, fill, press, select, hover, check, scroll, resize, emulate, dialog.',
+        // **Undocumented options are unusable options**, and this command had
+        // none listed at all — so `broker act --help` printed `--json` and
+        // `--help` and nothing else, for the verb with the most arguments on the
+        // surface. A caller refused by `resize` had no second place to look, which
+        // is what turned one bad message into a dead end.
+        options: [
+            { flag: '--action <verb>', summary: `One of: ${PAGE_ACTION_NAMES.join(', ')}.` },
+            {
+                flag: '--target <ref>',
+                summary: 'The element, as a reference from the most recent snapshot. Needed by click, type, ' +
+                    'fill, press, select, hover, check and drag.',
+            },
+            {
+                flag: '--value <text>',
+                summary: 'What to apply: the text to type or fill, the option to select, the key to press.',
+            },
+            {
+                flag: '--target-ref <ref>',
+                summary: 'The second element, for drag: where the dragged element is dropped.',
+            },
+            {
+                flag: '--width <n> --height <n>',
+                summary: 'For resize, the viewport in pixels. `--value 390x844` says the same thing.',
+            },
+            {
+                flag: '--colour-scheme <light|dark|no-preference>',
+                summary: 'For emulate. At least one preference is needed, and each is set independently.',
+            },
+            {
+                flag: '--reduced-motion <reduce|no-preference>',
+                summary: 'For emulate.',
+            },
+            {
+                flag: '--forced-colours <active|none>',
+                summary: 'For emulate.',
+            },
+        ],
+    },
+    {
+        words: ['read'],
+        operation: 'read',
+        summary: 'The page snapshot; console, network or cookies on request.',
+    },
+    { words: ['evaluate'], operation: 'evaluate', summary: 'Evaluate an expression in the page.' },
+    {
+        words: ['capture'],
+        operation: 'capture',
+        summary: 'Take a picture, and optionally the difference from an earlier one.',
+    },
+    {
+        words: ['sign', 'in'],
+        operation: 'sign_in',
+        summary: 'Ask a person to sign in on the tab this lease already holds.',
+        options: [
+            { flag: '--what <text>', summary: 'What they are signing into, relayed to them verbatim.' },
+            {
+                flag: '--request-seconds <n>',
+                summary: 'A shorter wait than the default. Capped, never extended.',
+            },
+        ],
+    },
+    {
+        words: ['sign', 'in', 'done'],
+        operation: 'sign_in_done',
+        summary: 'The person has signed in: give the browser back, keeping this lease and its tab.',
+    },
+    {
+        words: ['feedback'],
+        operation: 'feedback',
+        summary: 'Record that something helped or got in the way; with no arguments, read the rows back.',
+    },
+];
+/**
+ * The commands with no service operation behind them.
+ *
+ * §5.5 names four; the fifth is `diffs`, which reads the comparison history
+ * back. It sits here rather than beside the operations because it decides
+ * nothing and takes no lease — it is a read of what has already been recorded,
+ * which is the same reason `events` is not an operation either.
+ */
+export const STANDALONE_COMMANDS = [
+    {
+        words: ['snapshot'],
+        summary: 'Write the operations document to a path and exit.',
+        owedBy: 'the row that builds the operations document',
+    },
+    {
+        words: ['doctor'],
+        summary: 'Report every precondition separately, and exit non-zero on any failure.',
+        owedBy: 'the row that builds the preconditions report',
+    },
+    {
+        words: ['login'],
+        summary: 'Claim a browser for a person to sign in to.',
+        owedBy: 'the row that builds the sign-in handshake',
+    },
+    {
+        words: ['init'],
+        summary: 'Run the setup handshake explicitly and show its report.',
+        owedBy: 'the row that builds the setup report',
+    },
+    {
+        words: ['diffs'],
+        summary: 'List the recorded comparisons, filtered by lease, tab or outcome.',
+        owedBy: 'the row that builds changed-region review',
+        options: [
+            { flag: '--capture <id>', summary: 'Only comparisons made from this capture.' },
+            { flag: '--target <id>', summary: 'Only comparisons made against this earlier capture.' },
+            { flag: '--lease <id>', summary: 'Only comparisons recorded under this lease.' },
+            { flag: '--limit <n>', summary: 'At most this many comparisons.' },
+        ],
+    },
+    {
+        // The bytes of one recorded image, named by the identifier of a row.
+        // Standalone for the same reason `diffs` is: it takes no tab budget,
+        // drives no browser and decides nothing — it reads what is already
+        // recorded. §3.1 fixes the agent surface at twelve tools and none of them
+        // serves bytes, deliberately: the tools return paths so a caller pays for
+        // the part it opens.
+        words: ['image'],
+        summary: 'Write the bytes of one recorded image — a capture, an overlay or a region crop.',
+        owedBy: 'the row that builds image delivery',
+        options: [
+            { flag: '--capture <id>', summary: 'The capture whose bytes to write.' },
+            { flag: '--overlay <id>', summary: 'The comparison whose overlay to write.' },
+            { flag: '--region <id>', summary: 'The comparison whose changed region to crop.' },
+            { flag: '--index <n>', summary: 'Which region, largest first; defaults to the largest.' },
+            { flag: '--side <before|after>', summary: 'Which capture a region crop is cut from.' },
+            { flag: '--out <file>', summary: 'The file to write the bytes to. Required.' },
+            { flag: '--lease-key <key>', summary: 'Your lease key; an artifact belongs to its lease.' },
+        ],
+    },
+    {
+        // The capture telemetry rollups (#37). Standalone for the same reason
+        // `diffs` is: it takes no lease and no tab budget, drives no browser and
+        // decides nothing — it adds up what has already been recorded. §5.4 puts
+        // "list captures" on the operations command surface, which is this one.
+        words: ['captures'],
+        summary: 'What pictures cost, and what diffs did, over a window.',
+        owedBy: 'the row that builds the capture telemetry rollups',
+        options: [
+            { flag: '--since <t>', summary: 'Captures taken at or after this timestamp.' },
+            { flag: '--until <t>', summary: 'Captures taken strictly before this timestamp.' },
+            { flag: '--lease <id>', summary: 'Only captures taken under this lease.' },
+            { flag: '--capture <id>', summary: 'Instead: what diffs ran from and against one capture.' },
+            { flag: '--targets', summary: 'Instead: which captures are most diffed against.' },
+            { flag: '--limit <n>', summary: 'At most this many rows, where a listing is returned.' },
+        ],
+    },
+    {
+        // The administrative operation that asks a live browser what it actually
+        // has open (§2.6 step 2, §4.3). Standalone because it is not one of the
+        // ten and must never be: closing a page is browser-scoped, so §3.13 keeps
+        // it off the agent surface and `browser_scoped.never` (§7.3) makes that a
+        // build rule. It is a command for the reason §4.3 gives about the rest of
+        // that surface — a person runs it, and the ledger records that a person
+        // did.
+        words: ['reconcile'],
+        summary: 'Ask a browser what it has open; close pages no live lease owns, and end leases whose page is gone.',
+        owedBy: 'the row that builds reconciliation against a live browser',
+        options: [
+            {
+                flag: '--browser <regular|private>',
+                summary: 'Which browser to reconcile. May also be given as the first word.',
+            },
+        ],
+    },
+    {
+        // Reading the ledger back. Standalone for the same reason `diffs` is: it
+        // takes no lease and no tab budget, drives no browser and decides nothing —
+        // it is a read of history. Listed here because this table is what
+        // `broker --help` prints, and a command absent from it is a command a
+        // caller has no way to discover.
+        words: ['events'],
+        summary: 'Read the decision ledger, filtered by kind, outcome, guard, session or claim.',
+        owedBy: 'the row that builds the ledger read',
+        options: [
+            { flag: '--kind <a,b>', summary: 'Only these event kinds, comma-separated.' },
+            { flag: '--outcome <name>', summary: 'Only entries with this outcome.' },
+            { flag: '--guard <rule>', summary: 'Only entries naming this rule.' },
+            { flag: '--session-id <id>', summary: 'Only entries for this session.' },
+            { flag: '--claim-id <id>', summary: 'Only entries for this claim.' },
+            { flag: '--since <n>', summary: 'Entries after this cursor, oldest first.' },
+            { flag: '--before <n>', summary: 'Entries before this cursor.' },
+            { flag: '--limit <n>', summary: 'At most this many entries.' },
+        ],
+    },
+];
+/**
+ * Match an argument vector against the table, longest name first.
+ *
+ * Longest first is not a preference: `tab replace` is two words and `tab`
+ * alone is not a command, so a shortest-first match would resolve `tab
+ * replace` to an unknown noun and never reach the verb.
+ */
+export function parseCommand(argv) {
+    const candidates = [
+        ...OPERATION_COMMANDS.map((command) => ({ kind: 'operation', command })),
+        ...STANDALONE_COMMANDS.map((command) => ({ kind: 'standalone', command })),
+    ].sort((a, b) => b.command.words.length - a.command.words.length);
+    for (const candidate of candidates) {
+        const { words } = candidate.command;
+        if (words.every((word, index) => argv[index] === word)) {
+            const rest = argv.slice(words.length);
+            return candidate.kind === 'operation'
+                ? { kind: 'operation', command: candidate.command, rest }
+                : { kind: 'standalone', command: candidate.command, rest };
+        }
+    }
+    return { kind: 'unknown', attempted: argv.filter((word) => !word.startsWith('-')).join(' ') };
+}

package/dist/src/cli/conformance-driver.js

@@ -0,0 +1,119 @@
+import { cliAdapter, EXIT } from "./adapter.js";
+import { OPERATION_COMMANDS } from "./commands.js";
+import { run } from "./index.js";
+/**
+ * How the conformance suite drives the command line.
+ *
+ * ── It goes through the real entry point, and that is the whole point ────
+ *
+ * `MILESTONES.md`: "drive the command line through its entry point with an
+ * argument vector". So this calls {@link run} — the same function
+ * `src/bin/broker.ts` calls — with an argv it built, and reads the outcome
+ * back out of the exit code and the streams.
+ *
+ * **The alternative is the hollow version, and it is worth naming so nobody
+ * reinvents it.** A driver that called `cliAdapter.invoke` directly, or worse
+ * called the service itself, would produce a green matrix while testing none
+ * of the argument parsing, none of the exit-code mapping and none of the
+ * never-printed rule — every part of this route that could hold a rule of its
+ * own. That is the "tested a local copy of the logic so the shipped code was
+ * never exercised" failure, and it passes.
+ *
+ * ── Why it reads the machine-readable mode ──────────────────────────────
+ *
+ * The suite compares codes and rule names, never sentences (`SCHEMA.md`
+ * §3.14). The machine-readable mode is where this route puts a code and a
+ * rule name as data rather than as prose, so parsing that document is reading
+ * the route's own contract instead of matching English out of a message —
+ * which would be brittle *and* would be asserting the one thing §3.14 says
+ * never to compare across surfaces.
+ */
+/** Turn a neutral case input into this route's own vocabulary: an argv. */
+export function argvFor(testCase) {
+    const command = OPERATION_COMMANDS.find((entry) => entry.operation === testCase.operation);
+    if (command === undefined) {
+        throw new Error(`the command line has no command for "${testCase.operation}"`);
+    }
+    const argv = [...command.words];
+    for (const [key, value] of Object.entries(testCase.input)) {
+        // The terminal spells keys with hyphens; the service names them with
+        // underscores (§3). The adapter normalises on the way in, so the
+        // translation is inverted here rather than being a second convention.
+        const flag = `--${key.replaceAll('_', '-')}`;
+        if (value === true) {
+            argv.push(flag);
+            continue;
+        }
+        if (value === false || value === undefined || value === null) {
+            continue;
+        }
+        // A shell carries text. A case whose input is a structure has written
+        // something this transport cannot express, and coercing it would put
+        // `[object Object]` on the command line and then assert against whatever
+        // came back — a comparison that runs, means nothing, and passes. Failing
+        // here names the case instead.
+        if (typeof value !== 'string' && typeof value !== 'number') {
+            throw new TypeError(`case "${testCase.name}" gives ${flag} a value the command line cannot carry`);
+        }
+        argv.push(flag, String(value));
+    }
+    argv.push('--json');
+    return argv;
+}
+/**
+ * Read the outcome back out of what a command wrote and the code it exited
+ * with.
+ *
+ * Both are checked against each other rather than one being trusted: a
+ * document saying `refused` alongside an exit code of zero is a real bug on
+ * this route — a caller reading only the code would proceed as though the
+ * operation had happened (§5.6) — so the mismatch is raised here instead of
+ * being silently resolved in favour of whichever is read first.
+ */
+export function outcomeFrom(code, out) {
+    const document = JSON.parse(out.join('\n'));
+    if (document === null || typeof document !== 'object') {
+        throw new Error('the machine-readable mode did not produce a document');
+    }
+    const record = document;
+    if (record['outcome'] === 'accepted') {
+        if (code !== EXIT.accepted) {
+            throw new Error(`accepted document alongside exit code ${String(code)}`);
+        }
+        return { outcome: 'accepted', value: (record['value'] ?? {}) };
+    }
+    if (record['outcome'] === 'refused') {
+        if (code !== EXIT.refused) {
+            throw new Error(`refused document alongside exit code ${String(code)}`);
+        }
+        return {
+            outcome: 'refused',
+            code: String(record['code']),
+            rule: String(record['rule']),
+            // The sentence went to the error stream in this mode and is never
+            // compared (§3.14), so it is not read back here.
+            message: '',
+            ...(record['details'] === undefined
+                ? {}
+                : { details: record['details'] }),
+        };
+    }
+    throw new Error(`the document names no outcome: ${out.join('\n')}`);
+}
+/** The command line's conformance driver. */
+export const cliConformanceDriver = {
+    adapter: cliAdapter,
+    run: async (service, testCase, observe) => {
+        const out = [];
+        const err = [];
+        const code = await run(argvFor(testCase), {
+            service,
+            streams: { out: (line) => out.push(line), err: (line) => err.push(line) },
+        });
+        return {
+            outcome: outcomeFrom(code, out),
+            driverCalls: observe.driverCalls(),
+            liveClaimCount: observe.liveClaimCount(),
+        };
+    },
+};

package/dist/src/cli/diffs.js

@@ -0,0 +1,122 @@
+import { listComparisons } from "../service/comparison-store.js";
+export const DIFFS_USAGE = [
+    'broker diffs — list the comparisons this store has recorded.',
+    '',
+    'Usage:',
+    '  broker diffs [--capture <id>] [--target <id>] [--lease <id>] [--limit <n>] [--json]',
+    '',
+    'Filters combine, so the diffs one lease ran against one capture is two of them:',
+    '  --capture <id>  diffs run FROM this capture',
+    '  --target <id>   diffs run AGAINST this capture',
+    '  --lease <id>    diffs run by this lease',
+    '  --limit <n>     at most this many, most recent first',
+    '  --json          one JSON document, for something reading rather than someone',
+].join('\n');
+const FILTERS = {
+    '--capture': 'sourceCaptureId',
+    '--target': 'targetCaptureId',
+    '--lease': 'claimId',
+};
+/**
+ * Parse the arguments after `diffs`.
+ *
+ * **An unrecognised flag refuses rather than being ignored**, and a value-taking
+ * flag with nothing after it refuses too. Ignoring either would run a query
+ * nobody asked for and print a result that looks like an answer — the same
+ * reasoning §6.3 applies to a variable that is set and unreadable.
+ */
+export function parseDiffsArguments(argv) {
+    const query = {};
+    let json = false;
+    for (let at = 0; at < argv.length; at += 1) {
+        const argument = argv[at] ?? '';
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (argument === '--limit') {
+            const raw = argv[at + 1];
+            if (raw === undefined) {
+                return { ok: false, message: '--limit needs a number after it.' };
+            }
+            const value = Number(raw);
+            if (!Number.isInteger(value) || value < 1) {
+                return {
+                    ok: false,
+                    message: `--limit takes a whole number of at least one; got ${JSON.stringify(raw)}.`,
+                };
+            }
+            query.limit = value;
+            at += 1;
+            continue;
+        }
+        const field = FILTERS[argument];
+        if (field !== undefined) {
+            const value = argv[at + 1];
+            if (value === undefined || value.startsWith('--')) {
+                return { ok: false, message: `${argument} needs an identifier after it.` };
+            }
+            query[field] = value;
+            at += 1;
+            continue;
+        }
+        return { ok: false, message: `Unrecognised option: ${argument}` };
+    }
+    return { ok: true, query, json };
+}
+/** A ratio as a percentage with two decimals, which is the readable form. */
+function asPercentage(ratio) {
+    return `${(ratio * 100).toFixed(2)}%`;
+}
+/**
+ * Run the command.
+ *
+ * Returns an exit code rather than exiting, so the whole of it is reachable
+ * from a test — the arrangement `src/cli/index.ts` establishes and the reason
+ * its dispatcher is importable.
+ */
+export function runDiffs(argv, options) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        options.streams.out(DIFFS_USAGE);
+        return 0;
+    }
+    const parsed = parseDiffsArguments(argv);
+    if (!parsed.ok) {
+        options.streams.err(parsed.message);
+        options.streams.err(DIFFS_USAGE);
+        return 2;
+    }
+    const comparisons = listComparisons(options.db, parsed.query);
+    if (parsed.json) {
+        options.streams.out(JSON.stringify(comparisons, null, 2));
+        return 0;
+    }
+    if (comparisons.length === 0) {
+        // **Says what was asked, not merely that there was nothing.** An empty
+        // listing after a mistyped identifier looks identical to one after a
+        // correct identifier with no diffs behind it, and the first is far more
+        // likely — the same reasoning §1.9 applies to a missing diff target.
+        const asked = Object.entries(parsed.query)
+            .filter(([, value]) => value !== undefined)
+            .map(([key, value]) => `${key}=${String(value)}`);
+        options.streams.out(asked.length === 0
+            ? 'No comparisons recorded. A diff is an optional argument on a capture, so none is recorded until a capture names an earlier one to compare against.'
+            : `No comparisons match ${asked.join(', ')}.`);
+        return 0;
+    }
+    for (const comparison of comparisons) {
+        options.streams.out([
+            comparison.at,
+            comparison.id,
+            comparison.changed ? 'CHANGED' : 'unchanged',
+            `${String(comparison.regions.length)} region(s)${comparison.truncated ? ' (truncated)' : ''}`,
+            `${String(comparison.changedPixels)} px (${asPercentage(comparison.changedRatio)})`,
+        ].join('  '));
+        options.streams.out(`    from ${comparison.sourceCaptureId} against ${comparison.targetCaptureId}, lease ${comparison.claimId}`);
+        // The three settings, on every row. This is the line tuning reads.
+        options.streams.out(`    settings: tolerance ${String(comparison.colourTolerance)}, minimum area ${String(comparison.minimumRegionArea)} px squared, at most ${String(comparison.maximumRegions)} regions`);
+        options.streams.out(`    overlay: ${comparison.overlayPath}`);
+    }
+    options.streams.out(`${String(comparisons.length)} comparison${comparisons.length === 1 ? '' : 's'}.`);
+    return 0;
+}