@ultimat3/cli 21.0.0 → 22.0.0

package/src/cdp-errors.ts

@@ -1,56 +0,0 @@
-// One constructor per way the raw-CDP e2e browser refuses. Every cause quotes a value that came
-// out of a BROWSER or off a spawned process's stderr, so every one is rendered rather than
-// interpolated — the rule `e2e-errors.ts` already states.
-
-import { renderCauseValue, UltimateError } from '@ultimat3/core';
-
-/**
- * No browser to drive. This is the one an author meets first, so its fix names the two ways out:
- * point the driver at a binary, or accept that this machine cannot run the check.
- */
-export class CdpBrowserMissingError extends UltimateError {
-  constructor(input: { readonly tried: readonly string[] }) {
-    super({
-      code: 'X_CDP_BROWSER_MISSING',
-      cause: `no Chrome or Chromium executable was found — tried ${renderCauseValue(input.tried)}`,
-      fix: 'set CHROME_PATH to a Chrome or Chromium binary (GitHub-hosted ubuntu runners ship one at /usr/bin/google-chrome), or skip the browser-backed e2e suite by leaving it unset',
-    });
-  }
-}
-
-/** The binary ran and never announced an endpoint — a crash, a bad flag, or a sandbox refusal. */
-export class CdpLaunchFailedError extends UltimateError {
-  constructor(input: { readonly executable: string; readonly detail: string }) {
-    super({
-      code: 'X_CDP_LAUNCH_FAILED',
-      cause: `${renderCauseValue(input.executable)} did not announce a DevTools endpoint: ${renderCauseValue(input.detail)}`,
-      fix: 'run the same binary by hand with --headless=new --remote-debugging-port=0 and read its stderr; inside a container add --no-sandbox --disable-dev-shm-usage, which this launcher already passes',
-    });
-  }
-}
-
-/** A CDP call answered with an error frame, or the connection died under it. */
-export class CdpCallFailedError extends UltimateError {
-  constructor(input: { readonly method: string; readonly detail: string }) {
-    super({
-      code: 'X_CDP_CALL_FAILED',
-      cause: `the browser refused ${renderCauseValue(input.method)}: ${renderCauseValue(input.detail)}`,
-      fix: 'print what the page had: await page.evaluate(() => document.body.innerHTML) — a call that refuses the same way means the browser itself is gone, so read the launch above it',
-    });
-  }
-}
-
-/**
- * A call that never answered. Its own code rather than `X_TIMEOUT`, because the actionable half is
- * WHICH call: a hung `Page.navigate` is an app that never finishes responding, and a hung
- * `Runtime.evaluate` is an expression that never settles.
- */
-export class CdpTimeoutError extends UltimateError {
-  constructor(input: { readonly method: string; readonly timeoutMs: number }) {
-    super({
-      code: 'X_CDP_TIMEOUT',
-      cause: `${renderCauseValue(input.method)} did not answer inside ${String(input.timeoutMs)}ms`,
-      fix: 'raise timeoutMs on installE2eDriver({ timeoutMs }), or find the request the page is still waiting on — a navigation that never settles is an app that never finishes its response',
-    });
-  }
-}

package/src/cdp-launch.ts

@@ -1,193 +0,0 @@
-// One responsibility: start a Chrome in this container and hand back its DevTools endpoint and the
-// way to stop it. The connection is `cdp-connection.ts` and the page surface `cdp-e2e-page.ts`.
-
-// why: Bun exposes no recursive-remove and no temp-root primitive, so the throwaway profile
-// directory this launcher must create and delete needs both.
-import { mkdtempSync, rmSync } from 'node:fs';
-// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
-import { tmpdir } from 'node:os';
-// why: Bun exposes no path-join primitive.
-import { join } from 'node:path';
-import type { CdpConnection } from './cdp-connection';
-import { cdpConnectOver } from './cdp-connection';
-import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
-import { pipeTransport } from './cdp-pipe';
-
-/**
- * Where a Chrome is, in the order worth trying. `CHROME_PATH` first because it is the operator's
- * answer and the only one that can be right on a machine none of the rest describes; the two
- * `/usr/bin` names after it are what GitHub-hosted `ubuntu-latest` ships, which is what lets the
- * browser-backed suite run in CI with **no download step and no new dependency**.
- */
-export const CHROME_PATH_ENV = 'CHROME_PATH';
-export const CHROME_CANDIDATES: readonly string[] = [
-  '/usr/bin/google-chrome',
-  '/usr/bin/google-chrome-stable',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-];
-
-/** The first candidate that exists, or `undefined`. An absent browser is a SKIP, never a failure. */
-export async function findChrome(
-  env: Readonly<Record<string, string | undefined>>,
-): Promise<string | undefined> {
-  const declared = env[CHROME_PATH_ENV];
-  const candidates = declared === undefined || declared === '' ? CHROME_CANDIDATES : [declared];
-  for (const candidate of candidates) {
-    if (await Bun.file(candidate).exists()) return candidate;
-  }
-  return undefined;
-}
-
-/**
- * The two flags a CONTAINER needs, regardless of which process launches Chrome: the sandbox needs
- * privileges CI (and an Ubuntu 23.10+ host with AppArmor's unprivileged-user-namespace restriction
- * — Chrome exits "No usable sandbox" there with neither) does not grant, and `/dev/shm` is 64 MB in
- * a default container, which crashes the renderer on any real page.
- *
- * Exported so `browser-launcher.ts`'s `appBrowser` — a DIFFERENT launch path, `puppeteer-core`'s
- * own `launch()` rather than the `Bun.spawn` below — passes the SAME two, rather than a second
- * list that agrees today and drifts the next time either changes. `x shot` had neither before this
- * export existed, so a box where `x verify`'s e2e gate ran green could not run `x shot` at all.
- */
-export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disable-dev-shm-usage'];
-
-/**
- * The flags, and every one of them earns its line.
- *
- * `--headless=new` is Chrome's own headless rather than the retired shim. `--remote-debugging-pipe`
- * is the wire (`cdp-pipe.ts` says why it is not the WebSocket): no port, so two suites on one
- * machine can never collide, and nothing but this process can drive the browser. A throwaway
- * `--user-data-dir` because a run sharing a profile with a real browser inherits its cookies and
- * locks its files.
- */
-export const chromeLaunchFlags = (profileDir: string): readonly string[] => [
-  '--headless=new',
-  '--remote-debugging-pipe',
-  `--user-data-dir=${profileDir}`,
-  ...CONTAINER_CHROME_ARGS,
-  '--disable-gpu',
-  // The cookie store's encryption key comes from the OS keyring, asked over D-Bus on the first
-  // cookie access — which is the first navigation. With no keyring answering, Chrome waits out the
-  // D-Bus timeout: measured 7-25 s on the first `Page.navigate` of every launch, against a 30 s CDP
-  // deadline, which is the intermittent `X_CDP_TIMEOUT` of a full e2e run. A throwaway profile has
-  // no secret worth a keyring. `puppeteer-core` passes both by default, so `x shot` never had this.
-  '--password-store=basic',
-  '--use-mock-keychain',
-  // Nothing here should reach the network on its own account, and a first-run bubble or an update
-  // check is a page load the test did not ask for.
-  '--no-first-run',
-  '--no-default-browser-check',
-  '--disable-extensions',
-  'about:blank',
-];
-
-export interface LaunchedBrowser {
-  /** The browser's own CDP connection, over its debugging pipe. Already answering. */
-  readonly connection: CdpConnection;
-  /** Idempotent: closes the connection, kills the process, deletes the profile. */
-  close(): void;
-}
-
-export interface LaunchOptions {
-  readonly executable: string;
-  /** How long Chrome has to answer its first call, and every call's deadline after that. */
-  readonly timeoutMs: number;
-}
-
-const STDERR_TAIL_CHARS = 4_000;
-
-/**
- * Read stderr to its end for the life of the process, keeping only a bounded tail. A pipe nobody
- * reads fills, and Chrome's next stderr write then blocks the thread making it — a browser that
- * stops answering mid-run for a reason no log shows. The tail is the launch-failure diagnostics:
- * a missing library, a sandbox refusal and a bad flag are all named there and nowhere else.
- */
-function stderrTail(stream: ReadableStream<Uint8Array>): {
-  readonly text: () => string;
-  /** Settles once the stream has ended — every byte the process wrote has been read. */
-  readonly drained: Promise<void>;
-} {
-  let text = '';
-  const drained = (async () => {
-    const decoder = new TextDecoder();
-    for await (const chunk of stream) {
-      text = (text + decoder.decode(chunk, { stream: true })).slice(-STDERR_TAIL_CHARS);
-    }
-  })().catch(() => undefined);
-  return { text: () => text, drained };
-}
-
-/**
- * How long a browser that failed its first call gets to finish dying, and its stderr to finish
- * draining, before the tail is read. The pipe ending and the stderr reader reaching the last line
- * are two unordered events; read at the first, the reason a browser died was reported as "printed
- * nothing". Bounded, because a WEDGED browser neither exits nor closes stderr.
- */
-const FAILURE_DRAIN_MS = 1_000;
-
-const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
-  Promise.race([work, Bun.sleep(ms)]);
-
-/**
- * Start Chrome on a throwaway profile and answer once it has answered one CDP call. With a pipe
- * there is no "DevTools listening" line to wait for — the first reply IS the readiness signal, and
- * a browser that dies or stays silent before it is `X_CDP_LAUNCH_FAILED` carrying its own stderr.
- */
-export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrowser> {
-  const profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
-  const child = Bun.spawn([options.executable, ...chromeLaunchFlags(profileDir)], {
-    // Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies and events.
-    stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
-  });
-  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
-  const [, , , toBrowser, fromBrowser] = child.stdio as unknown as readonly number[];
-  const sink = Bun.file(toBrowser ?? -1).writer();
-  const connection = cdpConnectOver(
-    pipeTransport({
-      write: (bytes) => {
-        sink.write(bytes);
-        void sink.flush();
-      },
-      read: Bun.file(fromBrowser ?? -1).stream(),
-      end: () => {
-        void Promise.resolve(sink.end()).catch(() => undefined);
-      },
-    }),
-    options.timeoutMs,
-  );
-  let closed = false;
-  const close = (): void => {
-    if (closed) return;
-    closed = true;
-    connection.close();
-    child.kill();
-    rmSync(profileDir, { recursive: true, force: true });
-  };
-  try {
-    await connection.send('Browser.getVersion');
-    return { connection, close };
-  } catch {
-    await within(FAILURE_DRAIN_MS, child.exited);
-    close();
-    await within(FAILURE_DRAIN_MS, tail.drained);
-    const seen = tail.text().trim();
-    throw new CdpLaunchFailedError({
-      executable: options.executable,
-      detail:
-        seen === ''
-          ? 'it answered no DevTools call and printed nothing before the deadline'
-          : seen.split('\n').slice(-3).join(' | '),
-    });
-  }
-}
-
-/** `findChrome` then `launchChrome`. Refuses by name when there is no browser to drive. */
-export async function launchFoundChrome(
-  env: Readonly<Record<string, string | undefined>>,
-  timeoutMs: number,
-): Promise<LaunchedBrowser> {
-  const executable = await findChrome(env);
-  if (executable === undefined) throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
-  return launchChrome({ executable, timeoutMs });
-}

package/src/cdp-offline-script.ts

@@ -1,73 +0,0 @@
-// One responsibility: `navigator.onLine` reads `false` from a document's FIRST script while the
-// session's offline switch is thrown, and reads `true` again — with the `online` event a page
-// reconnects on — when it goes back. `Network.emulateNetworkConditions` cuts the NETWORK for a
-// document created under the switch but, measured on Chrome 150, never tells it so: a reload under
-// the switch read `navigator.onLine === true` at its first script every time, COOP or not, still
-// read `true` a second later, and got no `online` event when the switch went back.
-// `Network.overrideNetworkState` changed nothing. The dummy's page boot asks at its first script
-// and replayed its outbox with a real POST under the cut (`offline-like.e2e.test.ts`, two attempts).
-//
-// The override is an OWN property on `navigator`, so the real getter on `Navigator.prototype` is one
-// `delete` away. A document Chrome DID tell (it saw `offline`) gets Chrome's own `online` event on
-// restore; one it never told gets one from `RESTORE_ONLINE`, so a page reconnects exactly once.
-
-import type { CdpResult } from './cdp-connection';
-
-type Send = (
-  method: string,
-  params: Record<string, unknown>,
-  session: string,
-) => Promise<CdpResult>;
-
-/** Runs before the page's own scripts, in every document a page session creates while cut. */
-export const OFFLINE_FIRST_SCRIPT = `(() => {
-  let told = false;
-  Object.defineProperty(navigator, 'onLine', { configurable: true, get: () => false });
-  addEventListener('offline', () => { told = true; });
-  addEventListener('online', () => { delete navigator.onLine; }, { once: true });
-  Object.defineProperty(window, '__xRestoreOnLine', { configurable: true, value: () => {
-    if (!Object.getOwnPropertyDescriptor(navigator, 'onLine')) return;
-    delete navigator.onLine;
-    if (!told) dispatchEvent(new Event('online'));
-  } });
-})();`;
-
-/** Evaluated in every open page when the switch goes back: a no-op in a document never cut. */
-export const RESTORE_ONLINE = `window.__xRestoreOnLine?.()`;
-
-export interface OfflineScripts {
-  /** Register the script on one page session; answers once the browser has it. */
-  add(session: string): Promise<unknown>;
-  /** Unregister it from one page session, if it holds it, and restore the open document. */
-  remove(session: string): Promise<unknown>;
-}
-
-const field = (from: unknown, key: string): string | undefined => {
-  const value =
-    typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
-  return typeof value === 'string' ? value : undefined;
-};
-
-/** Per-session registration, keyed by the identifier the browser hands back. */
-export function offlineScripts(send: Send): OfflineScripts {
-  const held = new Map<string, string>();
-  return {
-    async add(session) {
-      const answer = await send(
-        'Page.addScriptToEvaluateOnNewDocument',
-        { source: OFFLINE_FIRST_SCRIPT },
-        session,
-      );
-      const identifier = field(answer.result, 'identifier');
-      if (identifier !== undefined) held.set(session, identifier);
-      return answer;
-    },
-    async remove(session) {
-      const identifier = held.get(session);
-      if (identifier === undefined) return undefined;
-      held.delete(session);
-      await send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, session);
-      return send('Runtime.evaluate', { expression: RESTORE_ONLINE }, session);
-    },
-  };
-}

package/src/cdp-pipe.ts

@@ -1,77 +0,0 @@
-// One responsibility: CDP over the pipe `--remote-debugging-pipe` opens — Chrome reads commands on
-// its fd 3 and writes replies and events on its fd 4, each message one JSON text ended by a NUL
-// byte. This is the e2e driver's wire; the WebSocket in `cdp-connection.ts` is for a remote browser.
-//
-// Why a pipe rather than the WebSocket Chrome also offers: Bun 1.4.0's WebSocket client handed
-// `onmessage` text spliced from several frames under the dummy's `offline-feed` load — 64
-// unparseable frames in one run, one of them a `Runtime.evaluate` reply that then waited out its
-// 30 s deadline. A frame nobody can parse has no `id`, so no layer above can even tell which call
-// it lost. A pipe is bytes and a delimiter, read here, and nothing in between.
-
-import type { CdpTransport } from './cdp-connection';
-
-/** The two ends a transport needs: a sink for whole messages, and the byte stream Chrome writes. */
-export interface PipeEnds {
-  /** Write these bytes to Chrome's fd 3, in order. */
-  readonly write: (bytes: Uint8Array) => void;
-  /** Chrome's fd 4. */
-  readonly read: ReadableStream<Uint8Array>;
-  /** Release the write end — Chrome treats its fd 3 closing as the client going away. */
-  readonly end: () => void;
-}
-
-const NUL = 0;
-
-/** Concatenate two byte arrays; the reader only ever holds the unterminated tail. */
-const join = (a: Uint8Array, b: Uint8Array): Uint8Array => {
-  if (a.length === 0) return b;
-  const out = new Uint8Array(a.length + b.length);
-  out.set(a);
-  out.set(b, a.length);
-  return out;
-};
-
-export function pipeTransport(ends: PipeEnds): CdpTransport {
-  const encoder = new TextEncoder();
-  let closed = false;
-  const reader = ends.read.getReader();
-  return {
-    send(text: string): void {
-      if (closed) return;
-      const body = encoder.encode(text);
-      const framed = new Uint8Array(body.length + 1);
-      framed.set(body);
-      framed[body.length] = NUL;
-      ends.write(framed);
-    },
-    close(): void {
-      if (closed) return;
-      closed = true;
-      ends.end();
-      void reader.cancel().catch(() => undefined);
-    },
-    listen(handlers): void {
-      void (async () => {
-        // Split on BYTES, decoded per message: a multi-byte character may straddle two reads, and
-        // decoding each read on its own would corrupt it — the failure this file exists to end.
-        const decoder = new TextDecoder();
-        let tail: Uint8Array = new Uint8Array(0);
-        try {
-          for (;;) {
-            const { value, done } = await reader.read();
-            if (done) break;
-            tail = join(tail, value);
-            for (let at = tail.indexOf(NUL); at !== -1; at = tail.indexOf(NUL)) {
-              handlers.message(decoder.decode(tail.subarray(0, at)));
-              tail = tail.subarray(at + 1);
-            }
-          }
-        } catch {
-          // A read that fails is a pipe that is gone — reported as the close it is, below.
-        }
-        closed = true;
-        handlers.closed('the browser closed the CDP pipe');
-      })();
-    },
-  };
-}

package/src/e2e-app.ts

@@ -1,103 +0,0 @@
-// The app an e2e suite drives, spawned on a THROWAWAY state directory: its own embedded database,
-// its own disk, its own dev lock, created per call and removed on `stop()`. Never the developer's
-// `.x/pgdata` — resetting that from a test run destroys the data an `x dev` beside it is using.
-// This file is the DATABASE half; spawning, readiness and the restart are `e2e-spawn.ts`'s.
-
-// why: Bun ships no temp-directory primitive or recursive remove; `tmpdir()` is node:os's alone.
-import { mkdtemp, rm } from 'node:fs/promises';
-// why: Bun exposes no tmpdir() — only node:os answers the platform temp root.
-import { tmpdir } from 'node:os';
-// why: Bun exposes no path API — the state dir is joined, not concatenated.
-import { join } from 'node:path';
-import { finiteCount } from '@ultimat3/core';
-import type { E2eAppMode } from './e2e-spawn';
-import { inherited, refuse, spawnE2eApp, X_BIN } from './e2e-spawn';
-
-export type { E2eAppMode } from './e2e-spawn';
-
-export interface StartE2eAppOptions {
-  /** The app root — the directory holding `app.config.ts`. */
-  readonly root: string;
-  readonly mode?: E2eAppMode | undefined;
-  /**
-   * The arguments after `x db seed`, or `false` for no seeding. Default `['--tier', 'dev']`: every
-   * dev-tier seed, which is what a developer's own `x dev` starts from.
-   */
-  readonly seed?: readonly string[] | false | undefined;
-  /** Extra environment for every process — the reset, the seed and the app. */
-  readonly env?: Readonly<Record<string, string>> | undefined;
-  /** How long the app may take to answer `/readyz`. */
-  readonly readyTimeoutMs?: number | undefined;
-}
-
-export interface E2eApp {
-  /** `http://localhost:<port>`, no trailing slash. */
-  readonly base: string;
-  /** The throwaway `.x` this app runs on — the one directory a test may inspect or corrupt. */
-  readonly stateDir: string;
-  /** Kill the app and delete its state directory. Idempotent. */
-  stop(): Promise<void>;
-  /**
-   * Stop the app and start it again on the SAME port and state directory, with `env` added — a
-   * deploy. `{ BUILD_ID: 'b2' }` is a new build the open tabs have not seen (`deploy.newBuild()`).
-   */
-  restart(env?: Readonly<Record<string, string>>): Promise<void>;
-}
-
-const DEFAULT_READY_TIMEOUT_MS = 90_000;
-
-function x(args: readonly string[], root: string, env: Record<string, string>): void {
-  const run = Bun.spawnSync(['bun', X_BIN, ...args], {
-    cwd: root,
-    env: { ...inherited(), ...env },
-    stdout: 'pipe',
-    stderr: 'pipe',
-  });
-  if (run.exitCode !== 0) {
-    throw refuse(`x ${args.join(' ')}`, `${run.stdout.toString()}${run.stderr.toString()}`);
-  }
-}
-
-/**
- * Reset and seed a fresh state directory, then spawn the app on a free port and wait for `/readyz`.
- * The reset runs against the throwaway directory, so it is a first migration, never a data loss.
- */
-export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp> {
-  // Screened FIRST, before a directory or a process exists: `waited < NaN` is false, so a NaN budget would never poll and report a dead app.
-  const deadline = finiteCount(
-    'startE2eApp',
-    'readyTimeoutMs',
-    options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
-  );
-  const stateDir = await mkdtemp(join(tmpdir(), 'ultimate-e2e-'));
-  const env: Record<string, string> = { ...options.env, ULTIMATE_STATE_DIR: stateDir };
-  const cleanup = (): Promise<void> => rm(stateDir, { recursive: true, force: true });
-  try {
-    x(['db', 'reset'], options.root, env);
-    const seed = options.seed ?? ['--tier', 'dev'];
-    if (seed !== false) x(['db', 'seed', ...seed], options.root, env);
-  } catch (error) {
-    await cleanup();
-    throw error;
-  }
-  try {
-    const spawned = await spawnE2eApp({
-      root: options.root,
-      mode: options.mode ?? 'dev',
-      env,
-      readyTimeoutMs: deadline,
-    });
-    return {
-      base: spawned.base,
-      stateDir,
-      restart: (next) => spawned.restart(next),
-      async stop(): Promise<void> {
-        await spawned.stop();
-        await cleanup();
-      },
-    };
-  } catch (error) {
-    await cleanup();
-    throw error;
-  }
-}

package/src/e2e-browser-handle.ts

@@ -1,55 +0,0 @@
-// The browser and the app the e2e step opened, reachable from a test file: `e2eBrowser()` and
-// `e2eApp()`. On `globalThis` under one `Symbol.for` key, because the preload and a test may each
-// hold their own copy of this module — the page-client handle's reason, one runtime over.
-
-import type { E2eBrowser } from './cdp-browser';
-import { CdpBrowserMissingError } from './cdp-errors';
-import { CHROME_CANDIDATES } from './cdp-launch';
-import type { E2eApp } from './e2e-app';
-
-/** Set by the e2e step to the app root; the preload spawns that app and opens a browser. */
-export const E2E_ROOT_ENV = 'ULTIMATE_E2E_ROOT';
-
-interface E2eRun {
-  browser: E2eBrowser;
-  readonly app: E2eApp;
-}
-
-const KEY = Symbol.for('ultimate.e2e.run');
-
-export function publishE2eRun(run: E2eRun): void {
-  Object.defineProperty(globalThis, KEY, { value: run, configurable: true });
-}
-
-const current = (): E2eRun | undefined => Reflect.get(globalThis, KEY) as E2eRun | undefined;
-
-/** Swap in a relaunched browser — the app stays; only the dead browser is replaced. */
-export function republishE2eBrowser(browser: E2eBrowser): void {
-  const run = current();
-  if (run !== undefined) run.browser = browser;
-}
-
-const missing = (): CdpBrowserMissingError =>
-  new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
-
-/**
- * The run's browser: `page`, and `session` for a second tab, an init script, the socket and request
- * log and the offline switch for every worker. Refuses by name outside an e2e run that found one.
- */
-export function e2eBrowser(): E2eBrowser {
-  const run = current();
-  if (run === undefined) throw missing();
-  return run.browser;
-}
-
-/** The app the run spawned: `base`, `stateDir`, and `restart({ BUILD_ID })` — a deploy. */
-export function e2eApp(): E2eApp {
-  const run = current();
-  if (run === undefined) throw missing();
-  return run.app;
-}
-
-/** The spawned app's origin, or `undefined` outside an e2e run. */
-export function e2eBaseUrl(): string | undefined {
-  return current()?.app.base;
-}

package/src/e2e-dom-fixture.ts

@@ -1,117 +0,0 @@
-// A document small enough to hold in a test and real enough to RUN the driver's own in-page
-// expressions. Without it every claim about `getByRole` and `getByText` would be an assertion
-// about a string, and a string that never executes cannot be wrong about a page.
-//
-// Its own file, the pattern `dev-roles-fixture.ts` and `policy-fixture.ts` already set here.
-
-/** One element. `attrs` is data, so every read of it goes through `Object.hasOwn` below. */
-export interface FakeE2eElement {
-  readonly tag: string;
-  readonly attrs: Readonly<Record<string, string>>;
-  readonly text?: string;
-  readonly children?: readonly FakeE2eElement[];
-  /** What `getComputedStyle` answers. Absent is the browser's own default — visible. */
-  readonly style?: { display?: string; visibility?: string; opacity?: string };
-}
-
-interface Node {
-  tagName: string;
-  textContent: string;
-  readonly attributes: Record<string, string>;
-  readonly descendants: Node[];
-  readonly style: { display: string; visibility: string; opacity: string };
-  getAttribute(name: string): string | null;
-  setAttribute(name: string, value: string): void;
-  removeAttribute(name: string): void;
-  contains(other: Node): boolean;
-}
-
-const textOf = (element: FakeE2eElement): string =>
-  [element.text ?? '', ...(element.children ?? []).map(textOf)]
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-function build(element: FakeE2eElement): Node {
-  const attributes: Record<string, string> = { ...element.attrs };
-  const children = (element.children ?? []).map(build);
-  const descendants = children.flatMap((child) => [child, ...child.descendants]);
-  const node: Node = {
-    tagName: element.tag.toUpperCase(),
-    textContent: textOf(element),
-    attributes,
-    descendants,
-    style: {
-      display: element.style?.display ?? 'block',
-      visibility: element.style?.visibility ?? 'visible',
-      opacity: element.style?.opacity ?? '1',
-    },
-    getAttribute: (name) => (Object.hasOwn(attributes, name) ? (attributes[name] as string) : null),
-    setAttribute: (name, value) => {
-      attributes[name] = value;
-    },
-    removeAttribute: (name) => {
-      delete attributes[name];
-    },
-    contains: (other) => descendants.includes(other),
-  };
-  return node;
-}
-
-/** `tag`, `*`, `[attr]`, `[attr="value"]` and any combination — every shape this driver emits. */
-const SIMPLE = /^([a-zA-Z0-9*]*)((?:\[[^\]]*\])*)$/;
-
-function matchesSimple(node: Node, selector: string): boolean {
-  const parsed = SIMPLE.exec(selector.trim());
-  if (parsed === null) return false;
-  const tag = parsed[1] ?? '';
-  if (tag !== '' && tag !== '*' && tag.toUpperCase() !== node.tagName) return false;
-  for (const clause of (parsed[2] ?? '').matchAll(/\[([^\]=]+)(?:=("[^"]*"|[^\]]*))?\]/g)) {
-    const name = (clause[1] ?? '').trim();
-    const held = node.getAttribute(name);
-    if (held === null) return false;
-    const raw = clause[2];
-    if (raw !== undefined && held !== raw.replace(/^"|"$/g, '')) return false;
-  }
-  return true;
-}
-
-const matches = (node: Node, selector: string): boolean =>
-  selector.split(',').some((part) => part.trim() !== '' && matchesSimple(node, part));
-
-/**
- * The globals a driver expression names, bound to one tree. `getComputedStyle` and `document` are
- * handed in as arguments rather than assigned to `globalThis`: a test that installed a fake
- * `document` on the process would leak it into every later file in the run.
- */
-export function fakeE2eDocument(root: FakeE2eElement): Readonly<Record<string, unknown>> {
-  const rootNode = build(root);
-  const all = [rootNode, ...rootNode.descendants];
-  return {
-    document: {
-      querySelectorAll: (selector: string): Node[] => all.filter((node) => matches(node, selector)),
-      querySelector: (selector: string): Node | null =>
-        all.find((node) => matches(node, selector)) ?? null,
-      getElementById: (id: string): Node | null =>
-        all.find((node) => node.getAttribute('id') === id) ?? null,
-    },
-    getComputedStyle: (node: Node) => node.style,
-  };
-}
-
-/**
- * Run an expression the driver built, in THIS process, against a stubbed global scope.
- *
- * `new Function` and not `eval`: the body evaluates with no access to this module's scope, so a
- * name the expression does not receive as a parameter is genuinely free — which is exactly the
- * `ReferenceError` a captured closure produces in a real browser, and the thing the evaluate
- * wrapper has to be proved against.
- */
-export async function runInFakePage(
-  expression: string,
-  globals: Readonly<Record<string, unknown>> = {},
-): Promise<unknown> {
-  const names = Object.keys(globals);
-  const body = new Function(...names, `return (${expression});`) as (...args: unknown[]) => unknown;
-  return await body(...names.map((name) => globals[name]));
-}