browser-broker 0.1.0

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

@@ -0,0 +1,401 @@
+import fs from 'node:fs';
+import { browserIsRunning, RealBrowserDriver, modeFor } from "../browser/real.js";
+import { DEFAULT_BROWSER_IDS } from "../browser/driver.js";
+import { BrokerError } from "../errors.js";
+import { SIGNABLE_BROWSER } from "../service/operations/sign-in.js";
+import { runSetupHandshake } from "../browser/setup.js";
+import { COLLISION_HINT, NO_BROWSER_NOTE, relativeProfilePath, signInCompletion, signInInstructions, signInProfileDirectory, } from "./sign-in.js";
+/**
+ * `broker login` — open the signed-in browser for a person, and wait.
+ *
+ * ── What this command is, in one sentence ───────────────────────────────
+ *
+ * It is the **only** part of this design a person has to perform by hand, and
+ * everything about its shape follows from that: it takes no lease, spends no
+ * tab budget, drives nothing, and its entire output is instructions.
+ *
+ * ── The four steps, and which of them are refusals ──────────────────────
+ *
+ * `SCHEMA.md` §5.5.1 gives the sequence and this file performs it in order:
+ *
+ * 1. **Claim the browser through the service** — which is where the refusals
+ *    live: a live lease holding a tab, the private browser, a sign-in already
+ *    in progress. None of them is checked here, deliberately: they are facts
+ *    about leases and lease liveness is derived inside the arbitration
+ *    transaction (§2.4). A check made in this file would read rows the sweep
+ *    had not reconciled.
+ * 2. **Get them a window**, against the configured profile.
+ * 3. **Wait**, while they sign in.
+ * 4. **Give the browser back** on every path out of the command, and on an
+ *    interruption — by a signal handler, because a `finally` does not run on
+ *    a signal. What that does and does not cover is stated exactly at step
+ *    four's own comment below; the short version is that a handler covers the
+ *    deaths that let a process run code and nothing else, so the store also
+ *    records who holds a sign-in and a later `broker login` reclaims one whose
+ *    process is gone.
+ *
+ * ── Why the profile is asserted rather than trusted ─────────────────────
+ *
+ * **Measured, and it is the failure this command exists to prevent.** A
+ * second browser launched against a profile directory already in use does not
+ * report a lock error: it **hands its address to the browser already holding
+ * the profile**, with nothing on the error stream and no endpoint of its own.
+ * A launcher waiting on its own endpoint therefore waits for something that
+ * will never appear. (The losing process does not exit on its own either;
+ * `launch.ts` ends it by the identifier it spawned.)
+ *
+ * And the obvious guard does not work: the single-instance lock file a POSIX
+ * system leaves in a profile directory **does not exist on Windows**, so a
+ * cross-platform check for it does not report *no lock* there — it **always
+ * passes**. A guard that cannot fail on one platform is worse than no guard.
+ *
+ * So this file makes **no** negative inference. It asks `browserIsRunning`,
+ * which verifies an endpoint answers *and* identifies itself as the expected
+ * browser, and when it starts one it goes through `coldStart`, whose contract
+ * is that success is an endpoint that answered — never a command that exited.
+ * The positive assertion is the whole mechanism; there is no path here that
+ * concludes a browser is available because nothing said otherwise.
+ *
+ * ── Why the profile is never recreated ──────────────────────────────────
+ *
+ * `runSetupHandshake` is called rather than respelled, and that is not
+ * economy: it is the one implementation of **setup may create, and may never
+ * destroy** (`setup.profile_never_destroyed`, §7.2). The profile holds a
+ * sign-in a person put there by hand, and a second implementation of
+ * "establish a profile" is exactly where the branch that clears a directory
+ * because it looks unfamiliar would eventually be written.
+ */
+/** How the person's window is watched for, and how often. */
+export const CLOSE_POLL_INTERVAL_MS = 1_000;
+/**
+ * The signals a person's interruption arrives as.
+ *
+ * `SIGINT` is Ctrl-C, which is the one that matters: it is how anybody stops
+ * a command that is sitting there waiting, and it is the keystroke that used
+ * to strand the browser. `SIGTERM` is the ordinary polite termination — what
+ * a supervisor, a shell logout or a `taskkill` without `/F` sends.
+ *
+ * **`SIGKILL` is deliberately absent and cannot be added.** It is not
+ * deliverable to a handler by design, which is precisely why the recovery
+ * path in `service/signin-recovery.ts` exists rather than this list being
+ * extended until it feels complete.
+ */
+export const INTERRUPT_SIGNALS = ['SIGINT', 'SIGTERM'];
+/**
+ * The real one: process signal handlers, and an exit once the browser is back.
+ *
+ * ── Why this exits rather than letting the process continue ─────────────
+ *
+ * Installing a handler for `SIGINT` **takes over the default disposition**: a
+ * process carrying one runs the handler and carries on waiting rather than
+ * ending, which from a person's side is a command that has stopped responding
+ * to Ctrl-C. That would trade one bad outcome for another, so the handler does
+ * the work and then ends the process itself.
+ *
+ * The exit code is the conventional `128 + signal number`, which is what a
+ * shell reports for a process killed by that signal — so a script watching
+ * this command sees what it saw before rather than a new number to learn.
+ */
+export function realInterruptHandling() {
+    return {
+        install: (onInterrupt) => {
+            const registered = INTERRUPT_SIGNALS.map((signal) => {
+                const listener = () => {
+                    onInterrupt(signal);
+                };
+                process.on(signal, listener);
+                return { signal, listener };
+            });
+            return () => {
+                for (const { signal, listener } of registered) {
+                    process.off(signal, listener);
+                }
+            };
+        },
+    };
+}
+/** `128 + n`, the exit code a shell reports for a death by signal. */
+export const SIGNAL_EXIT_CODES = {
+    SIGINT: 130,
+    SIGTERM: 143,
+};
+/**
+ * The exit code when an interruption was caught and the browser could **not**
+ * be given back.
+ *
+ * Distinct from the signal codes on purpose: those say "this process was
+ * interrupted", which is ordinary and is what a script expects. This one says
+ * the interruption was handled and the cleanup it exists to perform failed, so
+ * something is left behind — a different fact, and one a script watching this
+ * command should be able to tell apart without parsing English.
+ */
+export const EXIT_INTERRUPT_INCOMPLETE = 70;
+/**
+ * The real window: a headed browser against the configured profile.
+ *
+ * It attaches to one that is already running and starts one otherwise, which
+ * is the arrangement §5.5.1 describes — *"nothing is stopped and nothing is
+ * relaunched"*, because relaunching is a chance to lose the very thing being
+ * protected.
+ */
+export function realSignInWindow(options = {}) {
+    const driver = new RealBrowserDriver(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl });
+    return {
+        open: async (request) => {
+            if (request.alreadyRunning) {
+                const record = await browserIsRunning(request.profileDirectory, options);
+                if (record === undefined) {
+                    // The record stopped checking out between the caller's look and
+                    // this one. Treated as not running rather than as an error, because
+                    // that is exactly what a stale record means (§1.2c).
+                    const session = await driver.coldStart({
+                        browser: request.browser,
+                        profileDirectory: request.profileDirectory,
+                        mode: modeFor(request.browser),
+                    });
+                    return finishOpen(session, true);
+                }
+                const session = await driver.attach(request.browser, record);
+                // Attaching is non-destructive and the browser was not started here,
+                // so the person is being handed a window that already existed.
+                return finishOpen(session, false);
+            }
+            const session = await driver.coldStart({
+                browser: request.browser,
+                profileDirectory: request.profileDirectory,
+                mode: modeFor(request.browser),
+            });
+            return finishOpen(session, true);
+        },
+        waitForClose: async (request) => {
+            // **Watched by asking the endpoint, not by watching the process.** A
+            // process identifier can be reused, and a browser that is exiting holds
+            // its identifier for a moment after its window has gone. The endpoint
+            // answering with the expected identity is the same positive test
+            // everything else here uses, and its *absence* is the only negative
+            // conclusion this file draws — which is sound in this direction: an
+            // endpoint that does not answer is not serving anybody.
+            for (;;) {
+                const record = await browserIsRunning(request.profileDirectory, options);
+                if (record === undefined) {
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, CLOSE_POLL_INTERVAL_MS));
+            }
+        },
+    };
+}
+/**
+ * Release this process's connection and report the browser's identifier.
+ *
+ * **Detaching is not closing.** Measured (`real.ts`): attaching and detaching
+ * are non-destructive to tabs and cookies, and the browser is adopted rather
+ * than owned — so letting go of the connection leaves the person's window
+ * exactly where it was, which is the point. This process must not be holding
+ * a connection while a person drives the window, because this process is
+ * going to exit.
+ */
+async function finishOpen(session, startedIt) {
+    const { pid } = session.describe();
+    await session.detach();
+    return { pid, startedIt };
+}
+/**
+ * Run the command.
+ *
+ * Returns an exit code rather than calling out to the process, like every
+ * other command here, so the whole of it is reachable from a test.
+ */
+export async function runLoginCommand(options) {
+    const { broker, environment, streams, json } = options;
+    const requested = options.browser ?? SIGNABLE_BROWSER;
+    // Establish the profile **before** claiming the browser, because a claim
+    // that succeeded and then failed to find a profile would leave the browser
+    // in `signing-in` over a directory that was never there. It creates what is
+    // absent and leaves alone what is present — never recreating one that
+    // exists, which is the whole of `setup.profile_never_destroyed`.
+    await runSetupHandshake(options.store, environment.profileRoot, {
+        browsers: [...environment.regularBrowsers, ...environment.privateBrowsers],
+    });
+    // Step 1. Every refusal is the service's; this route adds none of its own.
+    //
+    // **The owner is recorded as part of taking the claim**, so a sign-in is
+    // never held by a process the store cannot name. See step eight of the
+    // schema for why this is the command's identifier rather than the browser's.
+    const began = await broker.begin_sign_in({
+        browser: requested,
+        ownerPid: options.ownerPid ?? process.pid,
+    });
+    const browser = began.browser;
+    const profileDir = signInProfileDirectory(environment.profileRoot, browser);
+    // ── The interruption handler, installed as soon as there is something to
+    //    give back and not one line earlier ──────────────────────────────────
+    //
+    // **Ordering is the whole correctness argument here.** Installed before the
+    // claim, it could fire when there is no claim to release and would call
+    // `end_sign_in` against a browser that is not signing in — which the service
+    // refuses, so a person interrupting an early failure would be handed a
+    // confusing refusal on their way out. Installed after the window opens, a
+    // Ctrl-C during the launch — which is a slow step and therefore a likely
+    // moment to press it — would strand exactly the state this is here to
+    // prevent.
+    //
+    // So it goes immediately after the claim is taken and immediately before
+    // anything slow, and it is removed in the `finally` so a completed command
+    // leaves no listener behind.
+    const handling = options.interrupts ?? { install: () => () => { } };
+    const endProcess = options.exit ?? ((code) => process.exit(code));
+    let interrupted = false;
+    const remove = handling.install((signal) => {
+        // **Re-entrancy matters more than it looks.** A person who presses Ctrl-C
+        // and sees nothing happen immediately presses it again, and a second run
+        // through here would call `end_sign_in` twice — the second against a
+        // browser already given back, which refuses. Latching means the extra
+        // presses are ignored rather than producing a refusal on the way out.
+        if (interrupted) {
+            return;
+        }
+        interrupted = true;
+        streams.err('');
+        streams.err(`Interrupted. Giving the ${browser} browser back before exiting — it would otherwise refuse every caller until somebody intervened.`);
+        void (async () => {
+            let code = SIGNAL_EXIT_CODES[signal];
+            try {
+                await broker.end_sign_in({ browser });
+                streams.err(`The ${browser} browser is serving again.`);
+            }
+            catch (error) {
+                // Reported, and it changes the exit code: a person whose browser was
+                // **not** given back needs to know that the thing this message
+                // promised did not happen. Exiting zero-shaped here would be the same
+                // class of defect as the comment that used to claim a `finally`
+                // covered a signal.
+                streams.err(`The browser could not be returned to service: ${error instanceof Error ? error.message : String(error)}`);
+                streams.err('It is recorded as signing-in and this process is about to exit. The next `broker login` will reclaim it, because the sign-in records which process was holding it.');
+                code = EXIT_INTERRUPT_INCOMPLETE;
+            }
+            endProcess(code);
+        })();
+    });
+    const signals = { dispose: remove };
+    let opened;
+    try {
+        const window = options.window ?? realSignInWindow();
+        // Asked positively, and the answer is used only in the direction where it
+        // is meaningful: a verified record means a browser is there to attach to.
+        // A missing one means *this call could not verify one*, which is why the
+        // branch it leads to starts a browser and asserts an endpoint rather than
+        // assuming the profile is free.
+        const running = await browserIsRunning(profileDir);
+        opened = await window.open({
+            browser,
+            profileDirectory: profileDir,
+            alreadyRunning: running !== undefined,
+        });
+        const relative = relativeProfilePath(environment.profileRoot, browser);
+        if (json) {
+            // One document, and the human text goes to the error stream (§5.6).
+            streams.out(JSON.stringify({
+                outcome: 'accepted',
+                value: {
+                    browser,
+                    state: began.state,
+                    profileRelativePath: relative,
+                    startedBrowser: opened.startedIt,
+                    pid: opened.pid,
+                },
+            }));
+            for (const line of signInInstructions(browser, relative)) {
+                streams.err(line);
+            }
+        }
+        else {
+            if (opened.startedIt) {
+                streams.out(NO_BROWSER_NOTE);
+                streams.out('');
+            }
+            for (const line of signInInstructions(browser, relative)) {
+                streams.out(line);
+            }
+        }
+        // Step 3. The person signs in. Nothing happens here until they close it.
+        await window.waitForClose({ profileDirectory: profileDir, pid: opened.pid });
+    }
+    finally {
+        // ── Step 4, and what this `finally` actually guarantees ─────────────
+        //
+        // A browser left in `signing-in` refuses **every** caller with a message
+        // about a person who has walked away, so the browser is given back on
+        // every path out of here — a normal completion and a refusal from the
+        // window alike.
+        //
+        // **It does not cover an interruption, and it never did.** A `finally`
+        // is ordinary control flow: the runtime unwinds to it when a call
+        // returns or throws. A signal is not either of those, and with no
+        // handler installed the default disposition for `SIGINT` terminates the
+        // process without unwinding anything — so this block does not run, and
+        // before the handler below existed a Ctrl-C left the browser
+        // unrecoverable. That is why the handler is installed rather than being
+        // relied upon from here, and it is why the store records an owner as
+        // well: a handler cannot run on `SIGKILL` or on a power cut.
+        signals.dispose();
+        // **Nothing is given back twice.** When the handler ran it has already
+        // called `end_sign_in`, and calling it again would hit the service's own
+        // refusal for ending a sign-in that never began — turning a clean
+        // interruption into an error message on the way out. The handler owns the
+        // release from the moment it fires, and this block owns every other path.
+        //
+        // Written as a condition around the work rather than as an early `return`,
+        // deliberately: a `return` inside a `finally` **discards an exception the
+        // `try` was throwing**, so the one shape that reads most naturally here is
+        // the one that would silently swallow a genuine launch failure.
+        if (!interrupted) {
+            try {
+                const ended = await broker.end_sign_in({ browser });
+                if (!json) {
+                    streams.out('');
+                    for (const line of signInCompletion(browser, ended.queueDepth)) {
+                        streams.out(line);
+                    }
+                }
+                else {
+                    streams.err(`The ${browser} browser is serving again.`);
+                }
+            }
+            catch (error) {
+                // Reported rather than swallowed and never allowed to replace the
+                // original failure: if this is running because something above threw,
+                // that is the thing the person needs to read.
+                streams.err(`The browser could not be returned to service: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    return 0;
+}
+/**
+ * Turn a launch refusal into something a person can act on.
+ *
+ * The launch's own message is accurate and is about endpoints; this adds what
+ * to *do*, which is the part a person needs and the part a message about
+ * endpoints cannot supply.
+ */
+export function explainLoginFailure(error) {
+    if (error instanceof BrokerError && error.message.includes('already running against this')) {
+        return `${error.message}\n\n${COLLISION_HINT}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Whether a profile directory exists at all, for the caller that wants to
+ * report rather than create.
+ */
+export function profileExists(profileRoot, browser) {
+    try {
+        return fs.statSync(signInProfileDirectory(profileRoot, browser)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** The browsers this command will answer for, for a usage message. */
+export const LOGIN_BROWSERS = DEFAULT_BROWSER_IDS;

package/dist/src/cli/operations-commands.js

@@ -0,0 +1,186 @@
+import { resolveAutomationProbe } from "../browser/automation-probe.js";
+import { runDoctor, formatReport } from "../doctor/report.js";
+import { EXIT } from "./adapter.js";
+import { readLedger } from "../operations/ledger.js";
+import { writeSnapshot } from "../report/snapshot.js";
+/**
+ * Exit codes, chosen so situations wanting opposite responses are
+ * distinguishable without parsing anything (§5.6).
+ *
+ * Re-exported from the adapter that owns them rather than restated, so there
+ * is one set of numbers in this build and no second copy to drift. The
+ * re-export exists because these three commands are not adapter operations —
+ * they have no service call behind them — and importing the adapter's own
+ * constant is how they stay in step with the route that does.
+ */
+export const COMMAND_EXIT = EXIT;
+/** `--name value` and `--name=value`, plus bare `--flag`. */
+export function parseFlags(rest) {
+    const parsed = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const word = rest[index];
+        if (word === undefined || !word.startsWith('--')) {
+            continue;
+        }
+        const body = word.slice(2);
+        const equals = body.indexOf('=');
+        if (equals !== -1) {
+            parsed[body.slice(0, equals)] = body.slice(equals + 1);
+            continue;
+        }
+        const next = rest[index + 1];
+        if (next === undefined || next.startsWith('--')) {
+            parsed[body] = true;
+            continue;
+        }
+        parsed[body] = next;
+        index += 1;
+    }
+    return parsed;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asNumber(value) {
+    const text = asString(value);
+    if (text === undefined) {
+        return undefined;
+    }
+    const parsed = Number(text);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * `broker snapshot --out <path>`.
+ *
+ * **No browser connection is supplied by this route**, and that is stated
+ * rather than hidden: the command line does not attach to a browser, so every
+ * address in the document it writes reads as `unreachable` with a note giving
+ * the single reason. The row that brings the real driver is the row that
+ * passes a source through. §4.2a's requirement is about what the document
+ * says when a browser does not answer, and this route satisfies it in the
+ * most literal way available — it asks nothing and says so, rather than
+ * leaving a blank.
+ */
+export async function runSnapshotCommand(rest, options) {
+    const flags = parseFlags(rest);
+    const outputPath = asString(flags.out) ?? asString(flags.output) ?? asString(flags.path);
+    if (outputPath === undefined) {
+        options.streams.err('broker snapshot needs somewhere to write: --out <path>. It writes one self-contained HTML file and exits.');
+        return COMMAND_EXIT.malformed;
+    }
+    const result = await writeSnapshot(options.db, {
+        outputPath,
+        eventLimit: asNumber(flags.events),
+        feedbackLimit: asNumber(flags.feedback),
+        version: options.version,
+    });
+    if (options.json) {
+        options.streams.out(JSON.stringify({
+            path: result.path,
+            bytes: result.bytes,
+            at: result.at,
+            tabs_asked: result.tabsAsked,
+            tabs_unreachable: result.tabsUnreachable,
+        }));
+    }
+    else {
+        options.streams.out(`snapshot: ${result.path}`);
+        options.streams.out(`taken at: ${result.at}`);
+        // Said on every run, not only when something is wrong. §4.1's rule is
+        // that the document must not be mistaken for a window, and the person
+        // most likely to make that mistake is the one who just generated it.
+        options.streams.out('This is a photograph, not a window: it does not refresh. Generate another to see the current picture.');
+        if (result.tabsUnreachable > 0) {
+            options.streams.out(`${String(result.tabsUnreachable)} of ${String(result.tabsAsked + result.tabsUnreachable)} tab address(es) could not be read and are shown as unreachable.`);
+        }
+    }
+    return COMMAND_EXIT.accepted;
+}
+/**
+ * `broker doctor`.
+ *
+ * **Reports and changes nothing** (§5.5), and exits with a distinct code on
+ * any failure, so it is usable exactly where a readiness check would have
+ * been used. The full list is on the output stream in both modes — the
+ * machine-readable one is one document, per §5.6.
+ */
+export function runDoctorCommand(options) {
+    // **The configured budget is passed, and until it was, the check could not
+    // fail.** `checkTabBudget` compares the stored value against this process's
+    // own; with nothing supplied it reported `unknown` regardless of what the
+    // store held. The only callers ever passing it were the doctor's own tests,
+    // which is why the gap survived — see `operations/status.ts` for the other
+    // half of the same failure.
+    //
+    // **The automation probe is passed the same way, for the same reason.**
+    // `checkAutomation` compares what it is told against nothing on its own;
+    // with no probe supplied it reported `unknown` regardless of whether a
+    // browser binary was actually resolvable. The only callers ever passing
+    // one were the doctor's own tests — see `resolveAutomationProbe` in
+    // `browser/automation-probe.ts` for the real answer this call site now
+    // supplies by default.
+    const report = runDoctor(options.environment, options.db, {
+        configuredTabBudget: options.environment.tabBudget,
+        automation: options.automationProbe ?? resolveAutomationProbe(),
+    });
+    if (options.json) {
+        options.streams.out(JSON.stringify({
+            store: report.storeLocation,
+            exit_code: report.exitCode,
+            checks: report.checks.map((check) => ({
+                id: check.id,
+                group: check.group,
+                status: check.status,
+                detail: check.detail,
+                remedy: check.remedy,
+            })),
+        }));
+    }
+    else {
+        for (const line of formatReport(report)) {
+            options.streams.out(line);
+        }
+    }
+    return report.exitCode;
+}
+/**
+ * `broker events` — a slice of the ledger (`MILESTONES.md` #47).
+ *
+ * Sliced by kind, outcome and rule, with the cursor the counter primary key
+ * already provides (§1.6). Every filter is a bound parameter; nothing a
+ * caller types reaches the SQL text.
+ */
+export function runEventsCommand(rest, options) {
+    const flags = parseFlags(rest);
+    const query = {
+        kinds: asString(flags.kind)?.split(',') ?? undefined,
+        outcome: asString(flags.outcome),
+        guard: asString(flags.guard),
+        sessionId: asString(flags['session-id']),
+        claimId: asString(flags['claim-id']),
+        since: asNumber(flags.since),
+        before: asNumber(flags.before),
+        limit: asNumber(flags.limit),
+        order: flags.since === undefined ? 'newest' : 'oldest',
+    };
+    const slice = readLedger(options.db, query);
+    if (options.json) {
+        options.streams.out(JSON.stringify({
+            entries: slice.entries,
+            cursor: slice.cursor,
+            total: slice.total,
+        }));
+        return COMMAND_EXIT.accepted;
+    }
+    if (slice.entries.length === 0) {
+        options.streams.out('No ledger entries match.');
+        return COMMAND_EXIT.accepted;
+    }
+    for (const entry of slice.entries) {
+        const guard = entry.guard === null ? '' : ` guard=${entry.guard}`;
+        const session = entry.sessionId === null ? '' : ` session=${entry.sessionId}`;
+        options.streams.out(`#${String(entry.id)} ${entry.at} ${entry.kind} ${entry.outcome} via=${entry.adapter}${guard}${session}`);
+    }
+    options.streams.out(`${String(slice.entries.length)} of ${String(slice.total)} matching entries.${slice.cursor === null ? '' : ` Read on with --since ${String(slice.cursor)}.`}`);
+    return COMMAND_EXIT.accepted;
+}