browser-broker 0.1.0

package/dist/src/cli/reconcile-command.js

@@ -0,0 +1,137 @@
+import { DEFAULT_BROWSER_IDS } from "../browser/driver.js";
+import { append } from "../service/events.js";
+import { applyReconciliation, decideReconciliation, readRecordedTabs, } from "../service/reconcile.js";
+import { COMMAND_EXIT, parseFlags } from "./operations-commands.js";
+/** Timestamps are spelled one way in this store. */
+function now() {
+    return new Date().toISOString();
+}
+function isBrowserId(value, browsers) {
+    return browsers.includes(value);
+}
+/**
+ * Run one reconciliation against one browser.
+ *
+ * **One browser per invocation, named explicitly.** There is no `--all`, and
+ * the absence is deliberate in the direction §3.13 keeps pointing: the more
+ * of the installation one command touches, the worse a mistake in it is. A
+ * person who wants both runs it twice and reads two reports.
+ */
+export async function runReconcileCommand(rest, options) {
+    const flags = parseFlags(rest);
+    const named = rest.find((word) => !word.startsWith('--'));
+    const browser = typeof flags.browser === 'string' ? flags.browser : named;
+    const browsers = options.browsers ?? DEFAULT_BROWSER_IDS;
+    if (browser === undefined) {
+        options.streams.err(`broker reconcile needs to be told which browser: ${browsers.join(' or ')}. It asks that browser what it has open, closes pages no live lease owns, and settles rows whose pages are gone.`);
+        return COMMAND_EXIT.malformed;
+    }
+    if (!isBrowserId(browser, browsers)) {
+        options.streams.err(`There is no browser named ${JSON.stringify(browser)}. This service manages ${browsers.join(' and ')}.`);
+        return COMMAND_EXIT.malformed;
+    }
+    if (options.session === undefined) {
+        // Refused rather than reported as a clean run. A reconciliation with no
+        // browser to ask would find every recorded page absent and settle every
+        // live lease on that browser — the most destructive possible outcome,
+        // arrived at by asking nothing.
+        options.streams.err('refused (browser.unreachable): reconciliation has to ask a live browser what it has open, and no browser connection was available to this command.');
+        return COMMAND_EXIT.refused;
+    }
+    // ── 1. What the store holds ───────────────────────────────────────────
+    const recorded = readRecordedTabs(options.db, browser);
+    // ── 2. What the browser says. The asking, in the open, outside every
+    //       transaction (§2.4b). The keeper tab is not in this list, because
+    //       `listTabs` excludes it (§3.15) — which is what stops the next line
+    //       deciding the browser's own life-support page is unowned.
+    const session = await options.session(browser);
+    const pages = await session.listTabs();
+    // ── 3. Deciding. Pure: two lists in, a plan out, no handle held.
+    const plan = decideReconciliation(pages, recorded);
+    // ── 4. Writing. A database handle and no session.
+    const at = now();
+    applyReconciliation(options.db, plan.vanishedTabs, at);
+    for (const tab of plan.vanishedTabs) {
+        // §1.6: one row per decision, and this is a decision — a lease was ended
+        // by something that was neither the caller nor the clock. `cli` rather
+        // than `internal` because a person ran this (§4.3).
+        append(options.db, {
+            kind: 'claim_revoked',
+            outcome: 'allow',
+            adapter: 'cli',
+            claimId: tab.claimId,
+            tabId: tab.tabId,
+            browserId: browser,
+            // No driver name in the detail. §1.4 keeps it out of anything a caller
+            // reads, and the ledger is read back by `broker events`.
+            detail: { reason: 'tab_not_open_in_browser', reconciledAt: at },
+        });
+    }
+    // ── 5. Closing. Browser work, last, and best effort (§2.4b): a page that
+    //       will not close is a leaked page, and the run still succeeded at
+    //       everything else it did.
+    let closed = 0;
+    let closeFailures = 0;
+    for (const page of plan.unownedPages) {
+        try {
+            await session.closeTab({ browser, driverTabId: page.driverTabId });
+            closed += 1;
+        }
+        catch {
+            // Swallowed, and counted. The count is what makes this visible without
+            // naming the page — a driver name is never printed (§1.4).
+            closeFailures += 1;
+        }
+    }
+    const report = {
+        pagesSeen: pages.length,
+        settled: plan.vanishedTabs.map((tab) => tab.tabId),
+        closed,
+        closeFailures,
+        skippedOpening: plan.skippedOpening.length,
+    };
+    if (options.json) {
+        options.streams.out(JSON.stringify({
+            browser,
+            pages_seen: report.pagesSeen,
+            settled: report.settled,
+            closed: report.closed,
+            close_failures: report.closeFailures,
+            skipped_opening: report.skippedOpening,
+        }));
+        return COMMAND_EXIT.accepted;
+    }
+    for (const line of formatReconciliation(browser, report)) {
+        options.streams.out(line);
+    }
+    return COMMAND_EXIT.accepted;
+}
+/**
+ * The report a person reads.
+ *
+ * **Every line is a count or an opaque identifier**, which is §1.4's rule
+ * made true by there being nothing else available to print: the report type
+ * carries no driver name, so this function could not print one if it tried.
+ */
+export function formatReconciliation(browser, report) {
+    const lines = [
+        `reconciled: ${browser}`,
+        `pages open, not counting the keeper: ${String(report.pagesSeen)}`,
+        `pages closed because no live lease owned them: ${String(report.closed)}`,
+        `leases ended because their page was gone: ${String(report.settled.length)}`,
+    ];
+    for (const tabId of report.settled) {
+        lines.push(`  tab ${tabId}`);
+    }
+    if (report.closeFailures > 0) {
+        // §2.4b: a leaked page, not a leaked lease. Said in those terms so the
+        // reader knows what it costs — memory, and not budget.
+        lines.push(`${String(report.closeFailures)} page(s) would not close. That is a leaked page and not a leaked lease: the budget is unaffected, and \`broker doctor\` reports them.`);
+    }
+    if (report.skippedOpening > 0) {
+        // Said on the run it happened on, because the alternative is a person
+        // reading "0 closed" and concluding there was nothing to close.
+        lines.push(`${String(report.skippedOpening)} tab(s) are still being opened, so nothing was closed on this run — a page seen now may belong to one of them. Run again once they have settled.`);
+    }
+    return lines;
+}

package/dist/src/cli/sign-in.js

@@ -0,0 +1,134 @@
+import path from 'node:path';
+import { profileDirectory } from "../browser/discovery.js";
+import { SIGNABLE_BROWSER } from "../service/operations/sign-in.js";
+/**
+ * `broker login` — the words a person reads while they are signing in.
+ *
+ * ── Why the prose is a module and not a template literal in the handler ──
+ *
+ * This is the **one command whose output is the product**. Every other
+ * command reports what happened; this one asks a person to do something, and
+ * if they do the wrong thing there is no error to read — a sign-in performed
+ * against the wrong profile succeeds, looks identical, and is discarded. So
+ * the text is here, in one place, where it can be asserted by a test rather
+ * than reviewed by eye.
+ *
+ * What each line has to carry, and why each is load-bearing:
+ *
+ * - **Which window is theirs.** A person with several browser windows open
+ *   needs to know which one this opened, and the answer is "the one that just
+ *   appeared" only for as long as they are looking at the screen.
+ * - **That closing it ends the step.** Otherwise they leave it open, and the
+ *   command that would confirm the sign-in refuses because a browser is still
+ *   running against the profile.
+ * - **That it is a real sign-in against a real site.** Nothing here is a
+ *   sandbox: what they type goes to whoever they are signing in to, exactly as
+ *   it would in their own browser.
+ * - **That nothing here records what they type.** Said plainly because the
+ *   opposite is a reasonable assumption about a tool that opened the window,
+ *   and a person who assumes it might reasonably decline to use it.
+ */
+/** The heading, so the window and the terminal are unambiguously paired. */
+export const SIGN_IN_HEADING = 'A browser window is open for you to sign in.';
+/**
+ * What a person does, in order.
+ *
+ * Numbered rather than prose because it is a procedure someone follows while
+ * looking at something else.
+ */
+export function signInInstructions(browser, profileRelativePath) {
+    return [
+        SIGN_IN_HEADING,
+        '',
+        `  1. Switch to the browser window that just opened. It is the ${browser} browser,`,
+        `     running against the profile at ${profileRelativePath} under the configured`,
+        '     profile root — which is the profile every caller will share.',
+        '  2. Go to whichever site you want this service to be signed in to, and sign in',
+        '     normally. This is a real browser and a real sign-in: what you type goes to',
+        '     that site exactly as it would in your own browser.',
+        '  3. Close the window when you are done. Closing it is what ends this step.',
+        '',
+        'While this is happening the browser is not serving callers. Anything that asks',
+        'for it is told a person is signing in and to try again shortly; anything already',
+        'waiting in the queue keeps its place and its timer.',
+        '',
+        'Nothing here records what you type. The sign-in is written into the browser’s',
+        'own profile directory by the browser itself — this service never sees a',
+        'credential, and stores nothing about one anywhere.',
+    ];
+}
+/** What a person is told once the window has closed and the browser is back. */
+export function signInCompletion(browser, queueDepth) {
+    const lines = [
+        `The window has closed and the ${browser} browser is serving again.`,
+        '',
+        'Confirm the sign-in took with:',
+        '',
+        '    broker doctor',
+        '',
+        'It reports whether the profile carries a session, without opening a browser.',
+    ];
+    if (queueDepth > 0) {
+        lines.push('', `${String(queueDepth)} caller(s) were queued while you signed in and kept their places.`);
+    }
+    return lines;
+}
+/**
+ * The absolute profile directory the browser is launched against.
+ *
+ * ── Never the default profile, and never a temporary one ────────────────
+ *
+ * `launch.explicit_profile_dir` (§7.2) is a launch-time refusal, but by the
+ * time it fires the caller has already decided which directory it meant. This
+ * is where that decision is made, and it is made **from the configured
+ * profile root by the same function the setup handshake uses**
+ * (`profileDirectory`) rather than by joining a path here.
+ *
+ * That matters more than it looks: a sign-in against a directory that is one
+ * character different from the one callers use is the failure this command
+ * exists to prevent, and it is undetectable afterwards — the person signs in
+ * successfully, the browser writes a real session to a real directory, and
+ * every caller attaches to a different one and sees a signed-out browser. So
+ * there is deliberately no second spelling of where a profile lives.
+ */
+export function signInProfileDirectory(profileRoot, browser) {
+    return profileDirectory(profileRoot, browser);
+}
+/**
+ * What to say when no browser is running to hand over.
+ *
+ * ── The honest seam, stated rather than papered over ────────────────────
+ *
+ * §5.5.1 says *"nothing is stopped and nothing is relaunched"*, and that is
+ * written for the arrangement where the signed-in browser is already up:
+ * *"the window is already there"*. This command therefore claims the browser
+ * and hands over the window that exists.
+ *
+ * When none exists, it starts one — and that is the whole of what this
+ * command launches. It is a cold start of the browser a person is about to
+ * sign into, which is the case §5.5.1's own step 3 describes as *"hands the
+ * person the window"*: there has to be a window. What it does **not** do is
+ * take a lease, open a tab, or drive anything, because none of those is a
+ * person signing in.
+ */
+export const NO_BROWSER_NOTE = 'No browser was running against this profile, so one was started for you to sign into.';
+/**
+ * A hint for the collision case, which is the one that fails least legibly.
+ *
+ * Measured, and the reason `coldStartDetached` asserts rather than infers: a
+ * second browser started against a profile already in use **hands its address
+ * to the first**, opening no endpoint of its own. The launch
+ * refuses on that, and this is what the refusal is worth saying alongside it —
+ * because the thing a person should do about it is not obvious from a message
+ * about endpoints.
+ */
+export const COLLISION_HINT = 'A browser is already running against this profile. That may be a window you or ' +
+    'something else opened earlier — find it and use it to sign in, or close it and ' +
+    'run this again. Two browsers cannot share one profile directory: the second ' +
+    'silently hands its address to the first and opens nothing.';
+/** Where the profile is, relative to the root, for a message (§1.7a). */
+export function relativeProfilePath(profileRoot, browser) {
+    return path.relative(profileRoot, profileDirectory(profileRoot, browser)) || browser;
+}
+/** The browser this command signs into when none is named. */
+export const DEFAULT_SIGN_IN_BROWSER = SIGNABLE_BROWSER;

package/dist/src/cli/telemetry.js

@@ -0,0 +1,222 @@
+import { readCaptureDiffActivity, readCaptureRollup, readMostDiffedTargets, } from "../operations/telemetry.js";
+export const CAPTURES_USAGE = [
+    'broker captures — what pictures cost, and what diffs did.',
+    '',
+    'Usage:',
+    '  broker captures [--since <t>] [--until <t>] [--lease <id>] [--json]',
+    '  broker captures --capture <id> [--limit <n>] [--json]',
+    '  broker captures --targets [--limit <n>] [--json]',
+    '',
+    'The window is half-open: --since includes its instant, --until excludes it,',
+    'so two adjacent windows partition the captures rather than sharing one.',
+    '  --since <t>     captures taken at or after this timestamp',
+    '  --until <t>     captures taken strictly before this timestamp',
+    '  --lease <id>    only captures taken under this lease',
+    '  --capture <id>  instead: what diffs ran from and against one capture',
+    '  --targets       instead: which captures are most diffed against',
+    '  --limit <n>     at most this many rows, where a listing is returned',
+    '  --json          one JSON document, for something reading rather than someone',
+].join('\n');
+const WINDOW_FLAGS = {
+    '--since': 'since',
+    '--until': 'until',
+    '--lease': 'claimId',
+};
+/**
+ * Parse the arguments after `captures`.
+ *
+ * **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 three modes are mutually exclusive and saying so is the point.**
+ * `--capture` asks about one picture's diffs and `--targets` asks which
+ * pictures get diffed against; neither takes a window. Silently ignoring a
+ * window passed beside one of them would print a number labelled with a
+ * restriction that was never applied, which is the specific way a telemetry
+ * read gets believed when it should not be.
+ */
+export function parseCapturesArguments(argv) {
+    const window = {};
+    let captureId;
+    let targets = false;
+    let limit;
+    let json = false;
+    for (let at = 0; at < argv.length; at += 1) {
+        const argument = argv[at] ?? '';
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (argument === '--targets') {
+            targets = true;
+            continue;
+        }
+        if (argument === '--limit') {
+            const raw = argv[at + 1];
+            if (raw === undefined) {
+                return { ok: false, message: '--limit needs a number.' };
+            }
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed)) {
+                return { ok: false, message: `--limit needs a number, not ${raw}.` };
+            }
+            limit = parsed;
+            at += 1;
+            continue;
+        }
+        if (argument === '--capture') {
+            const raw = argv[at + 1];
+            if (raw === undefined) {
+                return { ok: false, message: '--capture needs a capture identifier.' };
+            }
+            captureId = raw;
+            at += 1;
+            continue;
+        }
+        const field = WINDOW_FLAGS[argument];
+        if (field !== undefined) {
+            const raw = argv[at + 1];
+            if (raw === undefined) {
+                return { ok: false, message: `${argument} needs a value.` };
+            }
+            window[field] = raw;
+            at += 1;
+            continue;
+        }
+        return { ok: false, message: `Unrecognised option: ${argument}` };
+    }
+    const hasWindow = window.since !== undefined || window.until !== undefined || window.claimId !== undefined;
+    if (captureId !== undefined && targets) {
+        return { ok: false, message: '--capture and --targets ask different questions; pick one.' };
+    }
+    if (captureId !== undefined && hasWindow) {
+        return {
+            ok: false,
+            message: '--capture asks about one capture, so it takes no window.',
+        };
+    }
+    if (targets && hasWindow) {
+        return {
+            ok: false,
+            message: '--targets asks across every comparison, so it takes no window.',
+        };
+    }
+    if (captureId !== undefined) {
+        return { ok: true, mode: 'capture', captureId, limit, json };
+    }
+    if (targets) {
+        return { ok: true, mode: 'targets', limit, json };
+    }
+    return { ok: true, mode: 'rollup', window, json };
+}
+/** A count and its share of a total, where a bare count invites the wrong reading. */
+function share(part, whole) {
+    if (whole === 0) {
+        return '0';
+    }
+    return `${String(part)} (${String(Math.round((part / whole) * 100))}%)`;
+}
+function renderGroups(label, groups) {
+    if (groups.length === 0) {
+        return [];
+    }
+    return [
+        `${label}:`,
+        ...groups.map((group) => `  ${group.group.padEnd(10)} ${String(group.captures).padStart(5)} captures  ` +
+            `${String(group.bytes).padStart(10)} bytes  ` +
+            `${String(group.estimatedTokens).padStart(9)} est. tokens`),
+    ];
+}
+function renderOutcomes(label, outcomes) {
+    if (outcomes.comparisons === 0) {
+        return [`${label}: none.`];
+    }
+    return [
+        `${label}: ${String(outcomes.comparisons)} comparisons, ` +
+            `${share(outcomes.changed, outcomes.comparisons)} found a change, ` +
+            `${String(outcomes.truncated)} truncated.`,
+        ...outcomes.settings.map((use) => `  tolerance ${String(use.colourTolerance)}, ` +
+            `min area ${String(use.minimumRegionArea)}, ` +
+            `max regions ${String(use.maximumRegions)}: ` +
+            `${String(use.comparisons)} comparisons, ${String(use.changed)} changed`),
+    ];
+}
+/**
+ * Run `broker captures`.
+ *
+ * Returns an exit code rather than exiting, so the dispatcher owns the process
+ * and a test can drive this in the same way the parity suite drives the rest of
+ * the command surface.
+ */
+export function runCaptures(rest, options) {
+    if (rest.includes('--help')) {
+        options.streams.out(CAPTURES_USAGE);
+        return 0;
+    }
+    const parsed = parseCapturesArguments(rest);
+    if (!parsed.ok) {
+        options.streams.err(parsed.message);
+        options.streams.err(CAPTURES_USAGE);
+        return 2;
+    }
+    if (parsed.mode === 'capture') {
+        const activity = readCaptureDiffActivity(options.db, parsed.captureId, parsed.limit);
+        if (parsed.json) {
+            options.streams.out(JSON.stringify(activity));
+            return 0;
+        }
+        options.streams.out(`Capture ${activity.captureId}`);
+        for (const line of renderOutcomes('  Diffs run FROM it', activity.asSource)) {
+            options.streams.out(line);
+        }
+        for (const line of renderOutcomes('  Diffs run AGAINST it', activity.asTarget)) {
+            options.streams.out(line);
+        }
+        return 0;
+    }
+    if (parsed.mode === 'targets') {
+        const rows = readMostDiffedTargets(options.db, parsed.limit);
+        if (parsed.json) {
+            options.streams.out(JSON.stringify({ targets: rows }));
+            return 0;
+        }
+        if (rows.length === 0) {
+            options.streams.out('No comparisons recorded.');
+            return 0;
+        }
+        options.streams.out('Most diffed against — a baseline in behaviour, not in the schema:');
+        for (const row of rows) {
+            options.streams.out(`  ${row.captureId}  ${String(row.comparisons)} comparisons, ` +
+                `${String(row.changed)} changed  ${row.url ?? '(capture row gone)'}`);
+        }
+        return 0;
+    }
+    const rollup = readCaptureRollup(options.db, parsed.window);
+    if (parsed.json) {
+        options.streams.out(JSON.stringify(rollup));
+        return 0;
+    }
+    if (rollup.total.captures === 0) {
+        options.streams.out('No captures in this window.');
+        return 0;
+    }
+    const total = rollup.total;
+    options.streams.out(`${String(total.captures)} captures, ${String(total.bytes)} bytes, ` +
+        `${String(total.estimatedTokens)} estimated tokens.`);
+    options.streams.out(`${share(total.downscaled, total.captures)} were downscaled; ` +
+        `${share(total.warned, total.captures)} carried the accounting warning.`);
+    for (const line of renderGroups('By tier', rollup.byTier)) {
+        options.streams.out(line);
+    }
+    for (const line of renderGroups('By kind', rollup.byKind)) {
+        options.streams.out(line);
+    }
+    if (rollup.escalationReasons.length > 0) {
+        options.streams.out('Why callers escalated, as written:');
+        for (const reason of rollup.escalationReasons) {
+            options.streams.out(`  ${reason.takenAt}  ${reason.reason}`);
+        }
+    }
+    return 0;
+}