browser-broker 0.1.0

package/dist/src/browser/discovery.js

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Reading the browser's own record of where it can be reached, and checking
+ * it before anybody attaches on the strength of it.
+ *
+ * ── Why the browser picks the port and not this service ─────────────────
+ *
+ * `SCHEMA.md` §1.2c: the browser is asked to listen on an **unspecified**
+ * port, so the operating system assigns a free one, and the browser writes
+ * the result into a file inside its own profile directory. Two properties
+ * follow, and both are the reason for the arrangement:
+ *
+ * - **No collision with anything else on the machine.** A fixed port is a
+ *   guess about what else is running, and the inward-isolation rule says this
+ *   service must start correctly on a host where unrelated things are already
+ *   listening.
+ * - **The record cannot drift from the identity it describes**, because it
+ *   lives inside the profile directory that *is* the identity (§1.2). A
+ *   record kept anywhere else is a second place the truth lives, and the two
+ *   go out of step the first time something exits badly.
+ *
+ * ── The property this module exists for: a claim, not a proof ───────────
+ *
+ * The record **survives the browser**. This was verified rather than assumed,
+ * and re-verified while building this row: after the process was killed
+ * outright the file was still present, still readable, and still naming a
+ * port that answered nothing.
+ *
+ * So {@link readDiscoveryRecord} returning a record means *a file said so*
+ * and nothing more. {@link verifyDiscoveryRecord} is what turns it into a
+ * fact, and it owes **two** checks rather than one:
+ *
+ * 1. **Liveness.** The endpoint answers. A file is not a process.
+ * 2. **Identity.** The browser's own identifier matches. **Ports are
+ *    reused** — a stale record plus an unrelated process that happened to be
+ *    given the same port reads as a successful match against the number
+ *    alone, and the service would attach to something it has no business
+ *    touching.
+ *
+ * A record that fails either check is stale: the browser is treated as not
+ * running, and whichever caller notices takes the launch race (§1.2a).
+ */
+/**
+ * The file the browser writes inside its profile directory.
+ *
+ * Named by the browser rather than chosen here, which is why it is a constant
+ * and not configuration: this service reads a file somebody else's code
+ * writes, so the name is a fact to be matched, not a preference to be set.
+ */
+export const PORT_FILE_NAME = 'DevToolsActivePort';
+/** Where a profile directory lives, given the configured root and a browser. */
+export function profileDirectory(profileRoot, browser) {
+    // The directory is the root plus the browser's own id, computed rather than
+    // stored: `SCHEMA.md` §1.2 keeps no `profile_dir` column, because storing
+    // one stores an absolute path the database already knows how to compute,
+    // and §1.7a's rule is that no absolute path is ever stored anywhere.
+    return path.join(profileRoot, browser);
+}
+/** The record file's path for a profile directory. */
+export function portFilePath(profileDir) {
+    return path.join(profileDir, PORT_FILE_NAME);
+}
+/**
+ * Parse the record file's contents.
+ *
+ * Returns `undefined` for anything that is not a well-formed record rather
+ * than throwing, because an unreadable or half-written record is *the browser
+ * is not reachable this way* — the same conclusion as an absent one — and a
+ * caller that has to tell a malformed file from a missing one in order to
+ * decide whether to launch has been handed a distinction that changes
+ * nothing. A truncated file is a real state: the browser writes it in two
+ * lines and a reader can arrive between them.
+ */
+export function parsePortFile(contents) {
+    const [portLine, wsPath] = contents.split('\n');
+    if (portLine === undefined || wsPath === undefined) {
+        return undefined;
+    }
+    const port = Number(portLine.trim());
+    // An empty string converts to zero and a partly-written line converts to a
+    // non-number, so both cases have to be excluded explicitly rather than by
+    // truthiness — zero is exactly what an unfinished write looks like.
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        return undefined;
+    }
+    // The identifier is the last segment of the per-browser debugging path.
+    const browserUuid = wsPath.trim().split('/').at(-1);
+    if (browserUuid === undefined || browserUuid === '') {
+        return undefined;
+    }
+    return { port, browserUuid };
+}
+/**
+ * Read the record a browser left in its profile directory.
+ *
+ * **The returned record deliberately carries no `browserUuid`.** The shape on
+ * the seam makes that field optional and says why: it is absent on a record
+ * that has been read off disk but not yet checked against a live browser,
+ * which is the ordinary state of one. The identifier read from the *file* is
+ * the browser's claim about itself; the identifier that matters is the one a
+ * live endpoint reports. Keeping the file's copy out of the record is what
+ * stops a later reader treating a value that came off disk as though it had
+ * been confirmed.
+ *
+ * The file's identifier is not discarded — {@link verifyDiscoveryRecord}
+ * takes it as the expectation to match against. It simply does not travel
+ * inside a type whose presence means *verified*.
+ */
+export function readDiscoveryRecord(profileDir) {
+    let contents;
+    try {
+        contents = fs.readFileSync(portFilePath(profileDir), 'utf8');
+    }
+    catch {
+        // Absent, unreadable, or a directory. Every one of them means the same
+        // thing to a caller: there is no record to attach on.
+        return undefined;
+    }
+    const parsed = parsePortFile(contents);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    return {
+        record: { endpoint: `http://127.0.0.1:${String(parsed.port)}` },
+        expectedUuid: parsed.browserUuid,
+    };
+}
+/**
+ * How long to wait for the endpoint to answer before calling it unreachable.
+ *
+ * This bounds **one request to a loopback address**, which either answers
+ * immediately or is not there — it is not the launch-readiness bound, which
+ * is row #55's open question (§1.2b) and is a different quantity entirely. A
+ * bound is needed at all because a port can be held by something that accepts
+ * a connection and never replies, and a verification step that inherits that
+ * hang stalls every caller instead of concluding the browser is not usable.
+ */
+export const ENDPOINT_TIMEOUT_MS = 2000;
+/**
+ * Check that the endpoint answers **and** that the browser behind it is the
+ * one the record described.
+ *
+ * Both checks, never one. Liveness alone attaches to whatever inherited the
+ * port; identity alone cannot be read without something answering.
+ */
+export async function verifyDiscoveryRecord(record, expectedUuid, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? ENDPOINT_TIMEOUT_MS;
+    // ── Why the bound is a ref'd timer and NOT `AbortSignal.timeout` ───────
+    //
+    // `AbortSignal.timeout` is the obvious way to bound a request, it reads as
+    // correct, and it **is** correct whenever something else is keeping the
+    // process alive — which is every test run. Its timer is **unref'd**, so it
+    // cannot on its own keep the event loop running.
+    //
+    // That is fatal here specifically. This service is a **short-lived spawn**
+    // (§1.0a): started by a caller, serves that session, exits with it. On the
+    // adopt path the whole design rests on, a caller that is only verifying a
+    // record has **no other outstanding ref'd work** — and against a port that
+    // accepts a connection and never replies, the only thing that could settle
+    // the request is a timer incapable of holding the loop open. The process
+    // therefore **exits without concluding**, silently and with a success code,
+    // rather than reporting `endpoint_unreachable`.
+    //
+    // Measured on the runtime the pipeline uses: with nothing else outstanding
+    // the abort never fires and the process exits; adding one unrelated ref'd
+    // timer to the byte-identical call makes it conclude correctly. That
+    // contrast is the mechanism — the bound was being enforced by luck.
+    //
+    // So the timer is **ref'd** (an ordinary `setTimeout`, which keeps the loop
+    // alive until it fires) and is **cleared in a `finally`**. Both halves are
+    // required: ref'd without clearing would trade a silent early exit for a
+    // guaranteed delay on every call that answered promptly.
+    const controller = new AbortController();
+    const bound = setTimeout(() => {
+        controller.abort(new Error(`the endpoint did not answer within ${String(timeoutMs)}ms`));
+    }, timeoutMs);
+    let payload;
+    try {
+        const response = await fetchImpl(`${record.endpoint}/json/version`, {
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                failure: 'endpoint_unreachable',
+                detail: `The endpoint answered with status ${String(response.status)} rather than a version document.`,
+            };
+        }
+        payload = (await response.json());
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failure: 'endpoint_unreachable',
+            detail: `The endpoint did not answer: ${error instanceof Error ? error.message : String(error)}. The record is a claim, not a proof — it survives the browser it describes.`,
+        };
+    }
+    finally {
+        // Cleared on every path out of the request, including the early returns
+        // above: a bound that outlived the thing it bounds would hold the process
+        // open for the rest of its window on every successful call.
+        clearTimeout(bound);
+    }
+    const url = payload.webSocketDebuggerUrl;
+    const actualUuid = typeof url === 'string' ? url.split('/').at(-1) : undefined;
+    if (actualUuid === undefined || actualUuid === '') {
+        return {
+            ok: false,
+            failure: 'identity_mismatch',
+            detail: 'The endpoint answered but reported no browser identifier, so there is nothing to match the record against.',
+        };
+    }
+    if (actualUuid !== expectedUuid) {
+        // The case this exists for: the recorded browser exited and an unrelated
+        // process was handed the same port. Matching the number alone would read
+        // as success and attach to a stranger.
+        return {
+            ok: false,
+            failure: 'identity_mismatch',
+            detail: 'The endpoint answered, but it is a different browser from the one the record describes. Ports are reused, so a matching port is not a matching browser.',
+        };
+    }
+    return { ok: true, record: { endpoint: record.endpoint, browserUuid: actualUuid } };
+}

package/dist/src/browser/driver.js

@@ -0,0 +1,195 @@
+/**
+ * The seam between the service and whatever actually drives a browser.
+ *
+ * Everything in this file is types and constants. There is no automation
+ * library behind it yet and no runtime dependency added for it — row #20
+ * brings the real implementation, and rows #21 through #24, #53, #54 and #56
+ * fill in the operations declared here. What lands now is the shape those
+ * rows plug into, and a fake that satisfies it (`fake.ts`).
+ *
+ * ── Why the interface is worth its own row ──────────────────────────────
+ *
+ * `DECISIONS.md` §5: *a guard that returns "denied" after the tab already
+ * opened is worse than no guard*, because it reports a refusal that did not
+ * happen and everything downstream believes it. A rejection test that only
+ * asserts the response cannot tell those two apart. So the seam exists to be
+ * faked, and the fake exists to make *nothing happened* an assertable claim.
+ * That is why this row comes before the real driver rather than after it.
+ *
+ * ── What this shape enforces, and what it merely encourages ─────────────
+ *
+ * Worth stating exactly, in the manner `transaction.ts` states its own
+ * bypasses, because the difference is where a later row will get hurt:
+ *
+ * **Structural — the compiler refuses these.**
+ *
+ * - **A browser's *kind* is one of two, and there is no third.**
+ *   {@link BrowserKind} is a union of two string literals, and the store
+ *   enforces the same thing with a check constraint (schema step nine), so
+ *   the code that talks to browsers agrees with the database by
+ *   construction.
+ *
+ *   **What is not structural, said plainly rather than left to be
+ *   discovered:** the *number* of browsers. `DECISIONS.md` §13i makes the
+ *   configured browsers a bounded list per kind read from the environment,
+ *   and a set that is not known until a spawn starts cannot be a type. The
+ *   bound is enforced — by
+ *   `src/config/environment.ts`, which refuses a list over its cap and names
+ *   the entries — but **it is enforced at startup rather than by the
+ *   compiler**, and a reader who assumes otherwise will look for a guarantee
+ *   in the wrong place.
+ * - **No operation takes a list of tabs.** Every member of
+ *   {@link TabOperations} is singular, because a lease is one tab (§2.3) and
+ *   `SCHEMA.md` §3.1 puts it plainly: there was never more than one to list.
+ *   There is no plural close and no "close all my tabs" to write.
+ * - **A tab is closed through the handle for that tab.** {@link TabHandle} is
+ *   what {@link BrowserSession.openTab} returns, so closing one requires
+ *   already holding it.
+ *
+ * **Conventional — this shape makes the wrong thing awkward and nothing
+ * more.** Say so rather than implying otherwise:
+ *
+ * - **`browser_scoped.never` is not enforced here.** No method on
+ *   {@link BrowserSession} closes, kills, restarts or reaps a browser, so
+ *   there is no browser-scoped destructive call to reach for and adding one
+ *   would be a visible new method on a documented seam rather than an
+ *   argument slipped into an existing call. That is deliberately as far as it
+ *   goes: an implementation of this interface holds a live connection to a
+ *   browser, and nothing in a type signature can stop the module that holds
+ *   it from doing something else with it. `SCHEMA.md` §7.3 makes
+ *   `browser_scoped.never` a **build rule** for exactly that reason, and the
+ *   rule is checked against the agent surface, which this is not. Do not read
+ *   the absence of a close-browser method as the guarantee; it is the easy
+ *   path pointing the right way.
+ * - **Adoption is a protocol, not a constructor.** {@link BrowserDriver}
+ *   offers {@link BrowserDriver.attach} and {@link BrowserDriver.coldStart}
+ *   as separate calls because they are separate acts with different risks
+ *   (§1.2a), and nothing here forces a caller to try the first before the
+ *   second. Row #54 arbitrates which one a given caller performs, in the
+ *   store, in the same transaction that arbitrates claims. **The ordering
+ *   rule lives there, not in this file.**
+ * - **Nothing here keeps browser work out of the arbitration transaction.**
+ *   Every operation is `async`, and `SCHEMA.md` §2.4b's rule is that none of
+ *   them is reachable from inside a transaction. What makes that the path of
+ *   least resistance is `transaction.ts`'s `afterCommit`, which already takes
+ *   the collect-inside-act-outside shape; what makes it checkable is the
+ *   `arbitration.no_browser_io` build rule (§7.3). This file cannot do either
+ *   job, and a comment claiming it did would be the kind of false assurance
+ *   §7.3 exists to replace.
+ */
+/** Both kinds, in a fixed order, for anything that has to visit each. */
+export const BROWSER_KINDS = ['regular', 'private'];
+/**
+ * The browsers the default configuration names, in a fixed order.
+ *
+ * **The default set, never the permitted set.** Anything deciding what a
+ * particular installation actually has must read the configured lists or the
+ * store; this is what an installation that has set nothing runs, and it is
+ * what fixtures and the fake driver stand up when no configuration is in
+ * play. Reading it as the permitted set is the mistake this sentence exists
+ * to prevent.
+ */
+export const DEFAULT_BROWSER_IDS = ['regular', 'private'];
+/**
+ * **Which browser to claim, in one sentence** (`SCHEMA.md` §1.2, §3.2, row
+ * #66).
+ *
+ * ── Why this string exists, rather than the guidance being written twice ──
+ *
+ * §3.2 requires the same guidance in two places: **the tool's description
+ * text**, which is the only surface a calling agent reliably reads, and **the
+ * claim refusal**, because a caller re-reading a refusal is a caller
+ * re-making this decision. Two hand-written copies drift, and the copy that
+ * goes stale is the one nobody is looking at.
+ *
+ * ── Why the guidance is needed at all ───────────────────────────────────
+ *
+ * **Measured: 25 sessions seeded authentication into an isolated browser
+ * while the signed-in browser sat unused** — doing by hand, unreliably, the
+ * one thing that browser exists to provide. Nothing in this design assigns a
+ * kind of caller to a browser; it is a per-claim choice, and nothing told
+ * callers how to make it. **A capability nobody finds is worth what an absent
+ * capability is worth.**
+ *
+ * ── The caveat travels with it, and that is not optional ────────────────
+ *
+ * **Tabs in one browser share its cookie jar.** Two callers in the same
+ * browser are clean-room relative to every other browser and **relative to
+ * nothing else** — not to each other. That is right for reviewing an
+ * authenticated surface, where every caller wants the same identity and wants
+ * it to be the real one, and **wrong for exercising two identities at once in
+ * one browser**.
+ *
+ * Two identities at once is what a second configured browser is for
+ * (`DECISIONS.md` §13i), and the guidance says so rather than leaving it to
+ * be discovered from a test that mysteriously sees the wrong account.
+ *
+ * Stating the caveat in the same breath is the whole point: guidance that
+ * sent callers to the signed-in browser without it would trade one silent
+ * failure for another.
+ *
+ * ── The default makes this string carry more, not less ──────────────────
+ *
+ * `browser` is optional, and an unstated one resolves to the first signed-in
+ * browser (§3.2, `DECISIONS.md` §13i). **That is an argument for this text
+ * being more load-bearing rather than less**, and it is worth saying because
+ * the opposite reading is the tempting one. A caller that states nothing
+ * never sees the unknown-browser refusal, so the refusal stops being a place
+ * the caveat can reach it — and the default routes *more* traffic into one
+ * shared cookie jar, which is the exact condition the caveat is about. This
+ * is where a caller learns it or does not learn it at all.
+ *
+ * ── Kept short on purpose ───────────────────────────────────────────────
+ *
+ * §3.1: **surface area is a standing tax.** This text sits in a connected
+ * session's context on every turn, so it is the shortest wording that still
+ * carries the choice and its caveat. It is not an essay and must not become
+ * one.
+ */
+export const BROWSER_CHOICE_GUIDANCE = 'Omit this and you get the first signed-in browser, which is what most work wants. ' +
+    'Pass "private" for genuinely-fresh-visitor work — first-visit behaviour, an ' +
+    'undismissed banner, a consent prompt as a stranger sees it — or a configured ' +
+    'browser name to pick that one exactly. Tabs in one browser share its cookie jar, ' +
+    'so callers in the same browser are isolated from other browsers but not from each ' +
+    'other: for two identities at once, claim two differently-named browsers rather than ' +
+    'two tabs in one.';
+/** Every action, in the order §3.8 lists them, for a refusal that names them all. */
+export const PAGE_ACTIONS = [
+    'click',
+    'type',
+    'fill',
+    'press',
+    'select',
+    'hover',
+    'check',
+    'scroll',
+    'resize',
+    'emulate',
+    'dialog',
+    'fill_form',
+    'drag',
+];
+/**
+ * Every artefact a read can ask for, for a caller that has to enumerate them.
+ *
+ * Snapshot first because it is the default and the only load-bearing one
+ * (`SCHEMA.md` §3.9): every element reference `browser_act` takes comes from
+ * it, so a read that omitted it would be useless in the ordinary case.
+ */
+export const READ_ARTIFACTS = [
+    'snapshot',
+    'console',
+    'network',
+    'cookies',
+];
+/**
+ * Which artefacts are which. Written down so *"is this already being
+ * collected"* has a stable answer per artefact rather than being something to
+ * reason out each time somebody reads the default.
+ */
+export const ARTIFACT_COLLECTION = {
+    snapshot: 'generated',
+    console: 'accumulated',
+    network: 'accumulated',
+    cookies: 'live',
+};