@ultimat3/cli 21.0.0 → 22.0.0

package/src/e2e-preload.ts

@@ -1,64 +0,0 @@
-// The e2e step's own preload: when the gate names an app root (`ULTIMATE_E2E_ROOT`, set by
-// `verify-e2e.ts`), spawn that app on a throwaway database, open ONE browser, install it as the
-// `page` fixture and the `e2eTest` driver, register `deploy.newBuild()` as a restart of the app on
-// its own port, and hand both to any test that asks `e2eBrowser()` / `e2eApp()`.
-
-import { afterAll, beforeEach } from 'bun:test';
-import type { E2eBrowser } from './cdp-browser';
-import { openE2eBrowser } from './cdp-browser';
-import { startE2eApp } from './e2e-app';
-import { E2E_ROOT_ENV, e2eBrowser, publishE2eRun, republishE2eBrowser } from './e2e-browser-handle';
-import { installE2eDriver } from './e2e-driver';
-import type { E2eBrowserPage } from './e2e-page';
-import { answersWithin } from './e2e-probe';
-
-/** How long a live browser gets to answer `1` before it is declared hung and relaunched. */
-const PROBE_MS = 5_000;
-
-const root = Bun.env[E2E_ROOT_ENV];
-if (root !== undefined && root !== '') {
-  const app = await startE2eApp({ root });
-  let builds = 0;
-  // A deploy leaves the browser holding the OLD build's state: a SharedWorker whose socket went
-  // down with the restart and is now deep in its reconnect backoff, and tabs rendered by the old
-  // build. The test that deployed asserts on exactly that; the NEXT test must not inherit it.
-  let deployed = false;
-  const newBuild = async (): Promise<void> => {
-    deployed = true;
-    builds += 1;
-    await app.restart({ BUILD_ID: `e2e-build-${String(builds)}-${String(Date.now())}` });
-  };
-  // `openE2eBrowser`, never the `IfAvailable` door: the step only names a root after finding one.
-  let browser: E2eBrowser = await openE2eBrowser();
-  publishE2eRun({ browser, app });
-  // Installed ONCE, over a page that delegates to whichever browser is current: an `e2eTest` body
-  // is bound to its fixtures when the file DEFINES it, so reinstalling on a relaunch would leave
-  // every test defined before it driving a closed browser.
-  const current: E2eBrowserPage = {
-    url: () => browser.page.url(),
-    goto: (url, options) => browser.page.goto(url, options),
-    evaluate: (expression) => browser.page.evaluate(expression),
-    click: (selector) => browser.page.click(selector),
-    offline: (enabled) => browser.page.offline(enabled),
-  };
-  const uninstall = installE2eDriver({ page: current, baseUrl: app.base, newBuild });
-
-  // A browser that stopped answering takes every later suite down with it, one call deadline per
-  // call (run 8). So each test starts with a short probe, and a browser that fails it — or one a
-  // deploy ran under — is closed and relaunched: the app is untouched, and the test gets a fresh
-  // profile, a fresh SharedWorker and a fresh tab on the same origin.
-  beforeEach(async () => {
-    const alive = !deployed && (await answersWithin(e2eBrowser().page, PROBE_MS));
-    if (alive) return;
-    deployed = false;
-    browser.close();
-    browser = await openE2eBrowser();
-    republishE2eBrowser(browser);
-  });
-
-  afterAll(async () => {
-    uninstall();
-    browser.close();
-    await app.stop();
-  });
-}

package/src/e2e-probe.ts

@@ -1,23 +0,0 @@
-// Is the browser still answering? One cheap `evaluate('1')` raced against a short budget — the
-// question the e2e preload asks before every test, because a hung browser otherwise costs every
-// later suite one full CDP deadline per call (run 8) instead of one relaunch.
-
-/** `true` when the page evaluated `1` within `ms`; a rejection or a stall is `false`, never a throw. */
-export async function answersWithin(
-  page: { evaluate(expression: string): Promise<unknown> },
-  ms: number,
-): Promise<boolean> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const stalled = new Promise<false>((resolve) => {
-    timer = setTimeout(() => resolve(false), ms);
-  });
-  const answered = page.evaluate('1').then(
-    () => true,
-    () => false,
-  );
-  try {
-    return await Promise.race([answered, stalled]);
-  } finally {
-    clearTimeout(timer);
-  }
-}

package/src/e2e-selection.ts

@@ -1,182 +0,0 @@
-// What an e2e locator SELECTS, as a value, plus the one in-page expression that resolves it.
-// `locator`/`getByRole`/`getByText` are lazy handles, so the selection has to survive as data
-// until something asks a question about it — and only then does it become a string the browser
-// can run.
-
-/** Where the driver parks its click target. Removed again as soon as the click has been made. */
-export const MARK_ATTRIBUTE = 'data-x-e2e';
-
-/** One selection, exactly as the test spelled it. `first` is `.first()`, applied at resolve time. */
-export type E2eSelection =
-  | { readonly kind: 'css'; readonly selector: string; readonly first: boolean }
-  | {
-      readonly kind: 'role';
-      readonly role: string;
-      readonly name?: string | undefined;
-      readonly level?: number | undefined;
-      readonly first: boolean;
-    }
-  | { readonly kind: 'text'; readonly text: string; readonly first: boolean };
-
-/**
- * What the page answers for one selection. `count` is how many elements matched AFTER `first`
- * narrowed it, `visible` is about the first match alone, and `marked` says the click target now
- * carries `MARK_ATTRIBUTE` — three facts in one round trip, because a locator that asked twice
- * could be answered about two different renders.
- */
-export interface E2eResolution {
-  readonly count: number;
-  readonly visible: boolean;
-  readonly marked: boolean;
-}
-
-/**
- * The elements that carry a role IMPLICITLY, so `getByRole('button')` finds a `<button>` that
- * never wrote the attribute. A `Map` and not an object literal: the key is a role a test typed,
- * and a computed read of a `Record` answers `Object.prototype` members — the defect
- * `bun run proto-index` exists for.
- *
- * Deliberately not the whole of WAI-ARIA. A role absent from this table still resolves through
- * its explicit `[role="…"]` attribute, which is why an unknown role is not refused: refusing
- * `role="feed"` because a table in the framework is short would be the framework deciding an app's
- * markup is wrong.
- */
-const IMPLICIT_ROLE_ELEMENTS = new Map<string, readonly string[]>([
-  ['banner', ['header']],
-  ['button', ['button', 'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]']],
-  ['checkbox', ['input[type="checkbox"]']],
-  ['combobox', ['select']],
-  ['contentinfo', ['footer']],
-  ['dialog', ['dialog']],
-  ['form', ['form']],
-  ['heading', ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']],
-  ['img', ['img']],
-  ['link', ['a[href]']],
-  ['list', ['ul', 'ol']],
-  ['listitem', ['li']],
-  ['main', ['main']],
-  ['navigation', ['nav']],
-  ['option', ['option']],
-  ['radio', ['input[type="radio"]']],
-  ['table', ['table']],
-  ['textbox', ['input[type="text"]', 'input[type="email"]', 'input[type="search"]', 'textarea']],
-]);
-
-/** Elements whose text is markup rather than page copy — `getByText` must never land on one. */
-const TEXT_SKIP_TAGS = ['SCRIPT', 'STYLE', 'HEAD', 'TITLE', 'META', 'LINK', 'NOSCRIPT'];
-
-/** A CSS attribute selector takes a double-quoted string, which is what `JSON.stringify` writes. */
-const roleSelector = (role: string): string =>
-  [`[role=${JSON.stringify(role)}]`, ...(IMPLICIT_ROLE_ELEMENTS.get(role) ?? [])].join(',');
-
-/**
- * The call a test wrote, rebuilt from the selection. Every refusal below quotes it, because
- * "an e2e locator matched nothing" names no line of the test file and this does.
- */
-export function selectionCall(selection: E2eSelection): string {
-  const tail = selection.first ? '.first()' : '';
-  if (selection.kind === 'css') return `page.locator(${JSON.stringify(selection.selector)})${tail}`;
-  if (selection.kind === 'text') return `page.getByText(${JSON.stringify(selection.text)})${tail}`;
-  const options = [
-    ...(selection.name === undefined ? [] : [`name: ${JSON.stringify(selection.name)}`]),
-    ...(selection.level === undefined ? [] : [`level: ${String(selection.level)}`]),
-  ];
-  const role = JSON.stringify(selection.role);
-  const suffix = options.length === 0 ? '' : `, { ${options.join(', ')} }`;
-  return `page.getByRole(${role}${suffix})${tail}`;
-}
-
-/**
- * The candidate list, as a JS expression evaluating to an array of elements.
- *
- * `getByRole` and `getByText` are not CSS and cannot be: a role is implicit in a tag name, an
- * accessible name comes off four different attributes before it comes off the text, and
- * `getByText` has to pick the INNERMOST element that contains the string. So the union selector
- * is only the cheap first pass and every rule after it runs in JS, in the page.
- */
-function candidateSource(selection: E2eSelection): string {
-  if (selection.kind === 'css') return `all(${JSON.stringify(selection.selector)})`;
-  if (selection.kind === 'text') {
-    const needle = JSON.stringify(selection.text.replace(/\s+/g, ' ').trim().toLowerCase());
-    // Innermost FIRST and the skip list second, in that order. Reversed, `<html>` becomes the
-    // innermost survivor of a page whose only copy of the string is inside a `<script>` — the
-    // ancestor inherits the match its own excluded child made, which is worse than not filtering
-    // at all: it reports one match, at the document root, for text no reader can see.
-    return `innermost(all('*').filter((el) => norm(el.textContent).toLowerCase().indexOf(${needle}) !== -1)).filter((el) => ${JSON.stringify(TEXT_SKIP_TAGS)}.indexOf(el.tagName) === -1)`;
-  }
-  const byRole = `all(${JSON.stringify(roleSelector(selection.role))}).filter((el) => { const own = el.getAttribute('role'); return own === null || norm(own).toLowerCase() === ${JSON.stringify(selection.role.toLowerCase())}; })`;
-  const byLevel =
-    selection.level === undefined
-      ? byRole
-      : `${byRole}.filter((el) => level(el) === ${String(selection.level)})`;
-  return selection.name === undefined
-    ? byLevel
-    : `${byLevel}.filter((el) => accName(el).toLowerCase() === ${JSON.stringify(selection.name.replace(/\s+/g, ' ').trim().toLowerCase())})`;
-}
-
-/**
- * The helpers the candidate source above calls, defined once inside the IIFE.
- *
- * `visible` is `display`/`visibility`/`opacity`, which is character for character what
- * `@ultimat3/scraping`'s `snapshotExpression` computes for `ElementSnapshot.visible`. That is a
- * COPY and it is the wrong shape: `ScrapeTarget.query()` already answers a snapshot per element
- * and `ScrapeFrame` does not expose it, so this driver cannot reach the framework's one definition
- * of visible without an edit to `packages/scraping/src/page.ts`. Mirrored deliberately rather than
- * invented, so the two cannot disagree about a page until that edit lands.
- */
-const HELPERS = `
-  const norm = (s) => (s || '').replace(/\\s+/g, ' ').trim();
-  const all = (sel) => Array.prototype.slice.call(document.querySelectorAll(sel));
-  const innermost = (found) => found.filter((el) => !found.some((other) => other !== el && el.contains(other)));
-  const level = (el) => {
-    const aria = el.getAttribute('aria-level');
-    if (aria !== null) return Number(aria);
-    const tag = el.tagName.toLowerCase();
-    return /^h[1-6]$/.test(tag) ? Number(tag.slice(1)) : undefined;
-  };
-  const accName = (el) => {
-    const label = el.getAttribute('aria-label');
-    if (label !== null && norm(label) !== '') return norm(label);
-    const by = el.getAttribute('aria-labelledby');
-    if (by !== null) {
-      const parts = norm(by).split(' ').map((id) => document.getElementById(id)).filter((n) => n).map((n) => norm(n.textContent));
-      if (norm(parts.join(' ')) !== '') return norm(parts.join(' '));
-    }
-    const tag = el.tagName.toLowerCase();
-    if (tag === 'input') { const v = el.getAttribute('value'); if (v !== null && norm(v) !== '') return norm(v); }
-    if (tag === 'img') { const a = el.getAttribute('alt'); if (a !== null) return norm(a); }
-    const text = norm(el.textContent);
-    if (text !== '') return text;
-    const title = el.getAttribute('title');
-    return title !== null ? norm(title) : '';
-  };`;
-
-/**
- * Returns JSON TEXT rather than an object, the same bargain `cdp-snapshot.ts` makes: a CDP round
- * trip serialises the answer anyway, and a string has ONE deserialiser — a schema parse — instead
- * of an implicit one inside the browser library plus a cast on this side.
- */
-export function selectionExpression(selection: E2eSelection, mark?: string): string {
-  const marker = mark === undefined ? 'null' : JSON.stringify(mark);
-  return `(() => {${HELPERS}
-  const found = ${candidateSource(selection)};
-  const matches = ${selection.first ? 'found.slice(0, 1)' : 'found'};
-  const el = matches[0];
-  let visible = false;
-  if (el) {
-    const style = getComputedStyle(el);
-    visible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
-  }
-  const mark = ${marker};
-  let marked = false;
-  if (mark !== null && el) { el.setAttribute(${JSON.stringify(MARK_ATTRIBUTE)}, mark); marked = true; }
-  return JSON.stringify({ count: matches.length, visible: visible, marked: marked });
-})()`;
-}
-
-/** The CSS the marked element answers to — what `ScrapePage.click` is handed once one is marked. */
-export const markSelector = (mark: string): string => `[${MARK_ATTRIBUTE}=${JSON.stringify(mark)}]`;
-
-/** Undo. Best effort by design: a click that navigated took the whole document with it. */
-export const unmarkExpression = (mark: string): string =>
-  `(() => { const el = document.querySelector(${JSON.stringify(markSelector(mark))}); if (el) el.removeAttribute(${JSON.stringify(MARK_ATTRIBUTE)}); return JSON.stringify(true); })()`;

package/src/e2e-spawn.ts

@@ -1,169 +0,0 @@
-// The e2e app's PROCESS half: spawn it on a free port, wait for `/readyz`, restart it on the same
-// port as a deploy, stop it. Split from `e2e-app.ts`, which owns the DATABASE half (the throwaway
-// state directory, the reset and the seed), so this half runs against any root with an entry —
-// which is what lets a unit test drive it without a Postgres.
-
-// why: the readiness poll must not go through `globalThis.fetch` — inside `bun test` the testing
-// preload SEALS it, and the app's `/readyz` would be refused as egress. `node:http` is not sealed.
-import { get } from 'node:http';
-// why: Bun exposes no path API — the CLI's own bin is joined, not concatenated.
-import { join } from 'node:path';
-import { assert } from '@ultimat3/core';
-import { E2eAppFailedError } from './e2e-errors';
-
-/** `x dev` (sync included), or the production entry `apps/web/server.ts` under `ROLE=web`. */
-export type E2eAppMode = 'dev' | 'serve';
-
-/** The CLI this process IS — never a global `x`, which may be a different version of the framework. */
-export const X_BIN = join(import.meta.dir, 'bin.ts');
-const POLL_MS = 250;
-
-export interface SpawnedE2eApp {
-  /** `http://localhost:<port>`, no trailing slash. */
-  readonly base: string;
-  /** Kill the process. Idempotent. */
-  stop(): Promise<void>;
-  /** Kill it and start it again on the SAME port, with `env` added — a deploy. Refused after `stop()`. */
-  restart(env?: Readonly<Record<string, string>>): Promise<void>;
-}
-
-export interface SpawnE2eAppOptions {
-  readonly root: string;
-  readonly mode: E2eAppMode;
-  /** Every spawn's environment, on top of this process's minus `NODE_ENV`. */
-  readonly env: Readonly<Record<string, string>>;
-  /** Already screened finite by the caller. */
-  readonly readyTimeoutMs: number;
-}
-
-/** A port nothing holds right now, asked of the OS and handed to the child. */
-const freePort = (): number => {
-  const probe = Bun.serve({ port: 0, fetch: () => new Response() });
-  const port = probe.port ?? 0;
-  probe.stop(true);
-  return port;
-};
-
-/**
- * This process's environment minus what makes the child a TEST process. Spawned from `bun test`,
- * `NODE_ENV=test` rode along and the app resolved its environment as `test` — so a development-only
- * seam (the demo viewer an app installs instead of a sign-in route) was off and every page 401'd.
- * The app under e2e is a development app unless the caller's `env` says otherwise.
- */
-export const inherited = (): Record<string, string | undefined> => {
-  const { NODE_ENV: _node, ...rest } = Bun.env;
-  return { ...rest, ULTIMATE_ENV: 'development' };
-};
-
-export const refuse = (step: string, output: string): E2eAppFailedError =>
-  new E2eAppFailedError({ step, output });
-
-/** Spawn the app and answer once `/readyz` does; refuses with the app's own output tail. */
-export async function spawnE2eApp(options: SpawnE2eAppOptions): Promise<SpawnedE2eApp> {
-  const deadline = options.readyTimeoutMs;
-  const port = freePort();
-  // Its own scrape port too: every role opens one, the default is a fixed 9090, and a second app —
-  // or a developer's `x dev` — already holding it is an app that dies at boot with X_PORT_IN_USE.
-  const metricsPort = freePort();
-  const base = `http://localhost:${String(port)}`;
-  const command =
-    options.mode === 'serve'
-      ? ['bun', 'apps/web/server.ts']
-      : ['bun', X_BIN, 'dev', '--port', String(port)];
-  const spawnApp = (extra: Readonly<Record<string, string>>) =>
-    Bun.spawn(command, {
-      cwd: options.root,
-      env: {
-        ...inherited(),
-        ...options.env,
-        METRICS_PORT: String(metricsPort),
-        // The origin the app is actually reachable at. A page that renders a typed client builds
-        // its absolute URLs from it, and without it `/feed` answered 500 with X_ENV_MISSING APP_URL.
-        APP_URL: base,
-        ...(options.mode === 'serve' ? { ROLE: 'web', PORT: String(port) } : {}),
-        ...extra,
-      },
-      stdout: 'pipe',
-      stderr: 'pipe',
-    });
-  const ready = async (child: ReturnType<typeof spawnApp>, tail: () => string): Promise<void> => {
-    for (let waited = 0; waited < deadline; waited += POLL_MS) {
-      if (child.exitCode !== null) break;
-      if (await answersOk(`${base}/readyz`)) return;
-      await Bun.sleep(POLL_MS);
-    }
-    child.kill();
-    await child.exited;
-    throw refuse(`${command.join(' ')} never answered ${base}/readyz`, tail());
-  };
-
-  let child = spawnApp({});
-  // Drained from the start and kept bounded: an app's log is unbounded, and a pipe nobody reads
-  // fills its buffer and blocks the child on its next write — an app that "never got ready".
-  let tail = drainTail(child.stdout, child.stderr);
-  let stopped = false;
-  const stop = async (): Promise<void> => {
-    if (stopped) return;
-    stopped = true;
-    child.kill();
-    await child.exited;
-  };
-  try {
-    await ready(child, tail);
-  } catch (error) {
-    await stop();
-    throw error;
-  }
-  return {
-    base,
-    stop,
-    async restart(next: Readonly<Record<string, string>> = {}): Promise<void> {
-      // `stop()` is final. A child respawned here would be one no later `stop()` kills — the flag
-      // already says done — and `startE2eApp` has deleted the state directory it would boot on.
-      assert(
-        !stopped,
-        'restart() was called on an e2e app that was already stopped, so there is no app to deploy over',
-        'startE2eApp({ root }) again for a fresh app — restart() is for an app that is still running',
-      );
-      // The same port and the same state directory — a deploy, not a second app: a tab already
-      // open on `base` sees the new build on its next request, and the data it wrote is still there.
-      child.kill();
-      await child.exited;
-      child = spawnApp(next);
-      tail = drainTail(child.stdout, child.stderr);
-      await ready(child, tail);
-    },
-  };
-}
-
-const TAIL_CHARS = 16_000;
-
-/** Read both streams to their end in the background; answer the last `TAIL_CHARS` of either. */
-function drainTail(...streams: readonly ReadableStream<Uint8Array>[]): () => string {
-  let text = '';
-  for (const stream of streams) {
-    void (async () => {
-      const decoder = new TextDecoder();
-      for await (const chunk of stream) {
-        text = (text + decoder.decode(chunk, { stream: true })).slice(-TAIL_CHARS);
-      }
-    })().catch(() => undefined);
-  }
-  return () => text;
-}
-
-/** One GET, answered as "2xx or not" — never a throw, and never through the sealed `fetch`. */
-function answersOk(url: string): Promise<boolean> {
-  return new Promise((resolve) => {
-    const request = get(url, (response) => {
-      response.resume();
-      const status = response.statusCode ?? 0;
-      resolve(status >= 200 && status < 300);
-    });
-    request.on('error', () => resolve(false));
-    request.setTimeout(POLL_MS * 4, () => {
-      request.destroy();
-      resolve(false);
-    });
-  });
-}

package/src/measurement-actor.ts

@@ -1,26 +0,0 @@
-// The actor a route is rendered AS when the render exists only to be weighed. `app/` pages are
-// authed by construction: a `load` that calls a policy-guarded query denies an anonymous actor with
-// `X_UNAUTHENTICATED`, so under the anonymous build context every authed page was reported
-// `X_BUDGET_UNMEASURED` and a real app could not pass the `budgets` step (measured 2026-09-05).
-// Weighing bytes needs no data authority — the rendered document is discarded — so this actor holds
-// every permission. It is handed ONLY to the weigh-and-discard branch of `prerender.ts`, never to
-// `renderStatic`: a `site/` artifact is published to everyone, and a guarded query inside its `load`
-// must keep failing the build rather than rendering another actor's rows into a file.
-
-import type { Actor } from '@ultimat3/core';
-
-/** The id every trace and log line under a measurement render carries, so it is recognisable. */
-export const MEASUREMENT_ACTOR_ID = 'x-build-measure';
-
-/**
- * `kind: 'service'` and not `'user'`: an app's own `requireMember()`-style helper that resolves a
- * user to a row has nothing to resolve here, and the honest kind says so. `'*'` is the grant
- * `actorHas` reads as everything — the same spelling a role map uses for a superuser.
- */
-export const measurementActor = (): Actor => ({
-  kind: 'service',
-  id: MEASUREMENT_ACTOR_ID,
-  roles: [],
-  scopes: [],
-  permissions: ['*'],
-});