@ultimat3/cli 12.0.0 → 14.0.0

package/src/e2e-selection.ts

@@ -0,0 +1,182 @@
+// 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/error-catalog.ts

@@ -30,6 +30,7 @@ export const CATALOG_PACKAGES = [
   '@ultimat3/manifest',
   '@ultimat3/mcp',
   '@ultimat3/money',
+  '@ultimat3/notify',
   '@ultimat3/policy',
   '@ultimat3/pwa',
   '@ultimat3/query',

package/src/error-codes.ts

@@ -49,6 +49,10 @@ export const CLI_OWNED_ERROR_CODES = [
   // reading — the hole that let `scripts/` hold seven type errors under a green gate.
   'X_PACKAGE_UNREFERENCED',
   'X_RELEASE_VERSION_SKEW',
+  // The framework's own tables, refused by name rather than by the driver's rejection: a raw
+  // `permission denied for schema public` says which statement failed and neither which framework
+  // table it was creating nor which package wants it.
+  'X_FRAMEWORK_SCHEMA_FAILED',
   'X_STORAGE_UNWRITABLE',
   'X_STORAGE_SECRET_DEV',
   'X_MANIFEST_STALE',
@@ -88,6 +92,22 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_GENERATE_CONFLICT',
   'X_PORT_IN_USE',
   'X_DB_GEN_FAILED',
+  // The two directions of the drift a hash cannot see, and they are two repairs. The `drift` step
+  // compared a schema-source HASH to a `.hash` sidecar and never read what the migration recorded,
+  // so nine declared CHECK constraints that had never reached any database were green for as long
+  // as nobody edited the schema. `UNMIGRATED` means the entities declare it and no migration
+  // carries it — the database will never get it. `UNDECLARED` means a migration recorded it and
+  // nothing in source declares it any more. One code over both would hand two readers one wrong
+  // edit, which is the reason `X_ERROR_FIX_PATH_MISSING` is not `X_ERROR_FIX_INVALID` either.
+  'X_DB_SCHEMA_UNMIGRATED',
+  'X_DB_SCHEMA_UNDECLARED',
+  // The third thing the `drift` step asks, and the one no declaration-based check can answer: SQL
+  // in a committed migration that `x db gen` could never have written, which a squash discards in
+  // silence because a regenerated sidecar equals the declaration by construction. CLI-owned rather
+  // than `@ultimat3/db`'s — that package classifies the statements and deliberately declares no
+  // code, because the only remedy available for all of them is a line in the migration file, and
+  // where that file lives is this package's fact.
+  'X_MIGRATION_UNGENERATABLE',
   'X_DB_MIGRATE_FAILED',
   'X_DB_BRANCH_FAILED',
   'X_DB_STUDIO_FAILED',
@@ -128,6 +148,16 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
   'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
   'X_SHOT_ISLAND_MISSING',
+  // The browser-backed e2e driver — `e2e-driver.ts` and the three modules under it. Owned by the
+  // CLI because the ADAPTER is: `@ultimat3/testing` declares `PageLike` and may not import a
+  // browser, `@ultimat3/scraping` owns the browser and may not import the harness, and neither
+  // package can name a failure that only exists where the two meet.
+  'X_E2E_EVALUATE_UNSUPPORTED',
+  'X_E2E_EVALUATE_CAPTURED',
+  'X_E2E_EVALUATE_THREW',
+  'X_E2E_LOCATOR_EMPTY',
+  'X_E2E_LOCATOR_AMBIGUOUS',
+  'X_E2E_SERVICE_WORKER_ABSENT',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
@@ -198,6 +228,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ERROR_CODE_UNDOCUMENTED: 'a shipped error code has no row in the error reference',
   X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
   X_ERROR_CODE_UNRESOLVED: 'an error code is written as a name this repository cannot resolve',
+  X_FRAMEWORK_SCHEMA_FAILED: 'a framework table could not be created at boot',
   X_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
   X_STORAGE_SECRET_DEV: 'upload grants would be signed with the shipped development key',
   X_CLI_UNEXPECTED: 'the CLI itself failed',
@@ -224,6 +255,9 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_GENERATE_CONFLICT: 'a generator would overwrite a file',
   X_PORT_IN_USE: 'the dev port is taken',
   X_DB_GEN_FAILED: 'x db gen failed',
+  X_DB_SCHEMA_UNMIGRATED: 'an entity declaration no migration recorded',
+  X_DB_SCHEMA_UNDECLARED: 'a migration records schema no entity declares',
+  X_MIGRATION_UNGENERATABLE: 'this migration holds SQL no declaration carries and does not say so',
   X_DB_MIGRATE_FAILED: 'x db migrate failed',
   X_DB_BRANCH_FAILED: 'an x db branch step failed',
   X_DB_STUDIO_FAILED: 'x db studio failed',
@@ -245,6 +279,12 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',
   X_SHOT_ISLAND_MISSING: 'a declared island picture is not on disk',
+  X_E2E_EVALUATE_UNSUPPORTED: 'a page.evaluate() closure cannot be sent into the browser',
+  X_E2E_EVALUATE_CAPTURED: 'a page.evaluate() closure named a binding the page does not have',
+  X_E2E_EVALUATE_THREW: 'an expression an e2e page ran threw inside the browser',
+  X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
+  X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
+  X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',

package/src/framework-schema.ts

@@ -0,0 +1,152 @@
+// The framework's OWN tables, as one table: which package declares each, which relations it
+// creates, and the DDL. One list, read by the one applier, so "installed in dev and not in
+// production" is not a state this framework can be in — `startQueue` is on every boot path there
+// is, `ROLE=migrate` included.
+//
+// A framework table an app has to install by hand is a table that will be missing in production on
+// the one code path that needs it, and it surfaces as a Postgres `42P01` from inside a worker.
+
+import { SQL_AUDIT_TABLE, SQL_IDEMPOTENCY_TABLE } from '@ultimat3/action';
+import { AUTH_TABLE_NAMES, AUTH_TABLES, SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
+import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
+import { SQL_JOBS_TABLE } from '@ultimat3/jobs';
+import { SQL_NOTIFY_DELIVERIES_TABLE, SQL_NOTIFY_INBOX_TABLE } from '@ultimat3/notify';
+import { FrameworkSchemaFailedError } from './schema-errors';
+
+export interface FrameworkSchema {
+  /** The package whose source declares the DDL — where to look when a column is wrong. */
+  readonly pkg: string;
+  /**
+   * Every relation this entry creates. Read by the refusal below, so an operator learns which
+   * tables were being installed rather than only which statement failed — and pinned against the
+   * DDL text by `framework-schema.test.ts`, so a row cannot claim a table its SQL never creates.
+   */
+  readonly tables: readonly string[];
+  /** One or more statements each; `;` separates. */
+  readonly ddl: readonly string[];
+}
+
+/**
+ * Applied unconditionally, whether or not this boot installs a store behind it.
+ *
+ * `create table if not exists` on an unused table costs one round trip at boot. The alternative
+ * costs a request: a store installed later must never be the thing that discovers the schema was
+ * never applied, and several of these are installed AFTER this runs — `defineAuth` builds its
+ * limiter when the app's modules import, and `setNotifyStores` is an app's boot line.
+ *
+ * Ordered so a foreign key never precedes its target. Only `AUTH_TABLES` has any, and they are
+ * internal to that entry, which is why it ships as an ordered list rather than one string.
+ */
+export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
+  Object.freeze({
+    pkg: '@ultimat3/jobs',
+    tables: Object.freeze([
+      'x_jobs',
+      'x_job_steps',
+      'x_backfills',
+      'x_outbox',
+      'x_scheduler_state',
+      'x_scheduler_leader',
+      'x_job_leases',
+      'x_job_events',
+    ]),
+    ddl: Object.freeze([SQL_JOBS_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/action',
+    tables: Object.freeze(['x_idempotency']),
+    ddl: Object.freeze([SQL_IDEMPOTENCY_TABLE]),
+  }),
+  // The DDL only, and deliberately NO `setAuditSink`: there is no default audit sink on purpose,
+  // so `X_AUDIT_SINK_MISSING` keeps firing at boot for an app that declares `audit: true` and
+  // installs none.
+  Object.freeze({
+    pkg: '@ultimat3/action',
+    tables: Object.freeze(['x_audit']),
+    ddl: Object.freeze([SQL_AUDIT_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/http',
+    tables: Object.freeze(['x_rate_limit']),
+    ddl: Object.freeze([SQL_RATE_LIMIT_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/auth',
+    tables: Object.freeze(['x_auth_failures', 'x_auth_lockouts']),
+    ddl: Object.freeze([SQL_AUTH_LIMIT_TABLES]),
+  }),
+  /**
+   * The five tables `BuiltinAdapter` reads, and the oldest hole in this list.
+   *
+   * `packages/auth/src/tables.ts` exports them "so an app can paste them into a migration", and
+   * nothing in the framework has ever applied them — while `x db gen` diffs `describeEntities()`
+   * and these are not `entity()` declarations, so neither half was a file anybody could
+   * hand-write. `examples/dummy/CLAUDE.md` records the consequence in its own words: nobody can
+   * hold a session in the reference app. Applied here on exactly the rule the rate-limit and audit
+   * rows already follow.
+   *
+   * `AUTH_TABLE_NAMES` rather than five literals: @ultimat3/auth already publishes the list, and a
+   * second copy is a second thing to keep right when a table is added.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/auth',
+    tables: AUTH_TABLE_NAMES,
+    ddl: AUTH_TABLES,
+  }),
+  /**
+   * The delivery ledger is what stops a replayed notifier job sending twice, and it is the entry
+   * whose absence is least visible: without the table the ledger's first `claim` raises `42P01`
+   * from inside a worker, which reads as a dead-lettered notification rather than as a missing
+   * schema. Installed whether or not this boot calls `setNotifyStores`, for the same reason as
+   * every row above it — that call is an APP's boot line and runs after this one.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze(['x_notify_deliveries']),
+    ddl: Object.freeze([SQL_NOTIFY_DELIVERIES_TABLE]),
+  }),
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze(['x_notify_inbox']),
+    ddl: Object.freeze([SQL_NOTIFY_INBOX_TABLE]),
+  }),
+]);
+
+/** Every relation this boot creates, flattened. */
+export const frameworkTableNames = (): readonly string[] =>
+  FRAMEWORK_SCHEMA.flatMap((entry) => [...entry.tables]);
+
+/**
+ * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL is
+ * applied statement by statement. Safe to split on `;`: every constant is fixed, with no semicolon
+ * inside a literal, and each package's own SQL test is where that stays true.
+ */
+export const schemaStatements = (ddl: readonly string[]): readonly string[] =>
+  ddl.flatMap((text) => text.split(';')).filter((statement) => statement.trim().length > 0);
+
+/** One statement, executed. The caller owns the connection; this file owns no database import. */
+export type SchemaExecutor = (statement: string) => Promise<unknown>;
+
+/**
+ * Apply every entry, in order, and answer what was created.
+ *
+ * The refusal is the point of the `pkg`/`tables` columns: a raw `permission denied for schema
+ * public` names neither the framework table it was creating nor the package that wants it, and a
+ * boot failure is read by an operator who has no source tree open.
+ */
+export async function applyFrameworkSchema(execute: SchemaExecutor): Promise<readonly string[]> {
+  for (const entry of FRAMEWORK_SCHEMA) {
+    for (const statement of schemaStatements(entry.ddl)) {
+      try {
+        await execute(statement);
+      } catch (error) {
+        throw new FrameworkSchemaFailedError({
+          pkg: entry.pkg,
+          tables: entry.tables,
+          cause: error,
+        });
+      }
+    }
+  }
+  return frameworkTableNames();
+}

package/src/index.ts

@@ -113,6 +113,33 @@ export {
   schemaHash,
   writeSchemaHash,
 } from './drift';
+// The browser-backed e2e driver. `installE2eDriver` is the ONE entry point an app's test preload
+// calls; everything below it is exported because the adapter's own pieces are what a driver author
+// re-uses, and a deep import into `src/` would make each of them a compatibility promise anyway.
+export type { E2eDriverOptions } from './e2e-driver';
+export { e2eFixtures, installE2eDriver } from './e2e-driver';
+export {
+  E2eEvaluateCapturedError,
+  E2eEvaluateThrewError,
+  E2eEvaluateUnsupportedError,
+  E2eLocatorAmbiguousError,
+  E2eLocatorEmptyError,
+  E2eServiceWorkerAbsentError,
+} from './e2e-errors';
+export type { EvaluablePage } from './e2e-evaluate';
+export { closureSource, evaluateClosure, evaluateExpression } from './e2e-evaluate';
+export type { LocatablePage } from './e2e-locator';
+export { e2eLocator, resetLocatorMarks } from './e2e-locator';
+export type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
+export { DEFAULT_E2E_TIMEOUT_MS, DEFAULT_SERVICE_WORKER_TIMEOUT_MS, e2ePage } from './e2e-page';
+export type { E2eResolution, E2eSelection } from './e2e-selection';
+export {
+  MARK_ATTRIBUTE,
+  markSelector,
+  selectionCall,
+  selectionExpression,
+  unmarkExpression,
+} from './e2e-selection';
 export type { ErrorCatalog } from './error-catalog';
 export {
   buildErrorCatalog,
@@ -196,6 +223,15 @@ export type { FixHelper, FixScan } from './fix-scan';
 export { scanFixes, scanFixHelpers, scanFixSites } from './fix-scan';
 export type { DeclaredFlag } from './flag-reads';
 export { checkFlagReads, declaredFlags, readsFlag } from './flag-reads';
+export type { FrameworkSchema, SchemaExecutor } from './framework-schema';
+// The framework's own tables, as data. Exported so `scripts/` can read the applier's list without
+// re-deriving it — the shape a ratchet over declared-but-never-applied DDL needs.
+export {
+  applyFrameworkSchema,
+  FRAMEWORK_SCHEMA,
+  frameworkTableNames,
+  schemaStatements,
+} from './framework-schema';
 export type { Guard } from './guards';
 export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
 // The island bundler, and only its entry point. An island is the one module Ultimate ships to a
@@ -239,6 +275,12 @@ export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from
 export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
+export type { SchemaDifference, SchemaDirection, SchemaPart } from './schema-diff';
+export { diffDeclaredSchema } from './schema-diff';
+// The drift a hash cannot see, and the composition both the gate step and `x doctor` read.
+export type { DeclaredEntities } from './schema-drift';
+export { checkMigrationDrift, checkSnapshotDrift } from './schema-drift';
+export { FrameworkSchemaFailedError } from './schema-errors';
 export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
 export {
   CONTAINER_BINDING,

package/src/mcp-errors.ts

@@ -64,6 +64,20 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x help shot --json   # the cause lists every request the state must answer under routes',
   X_SHOT_ISLAND_MISSING:
     'x help shot --json   # every absent picture carries its own named refusal in the run above',
+  // The six e2e-driver codes. Every one of them is raised inside a running suite, so the runnable
+  // half is the command that re-runs that suite — the cause already names the closure, the locator
+  // call or the budget, and no `x` command can edit a test for its author.
+  X_E2E_EVALUATE_UNSUPPORTED:
+    'x test e2e --json   # the cause quotes the closure; page.evaluate takes a zero-parameter arrow',
+  X_E2E_EVALUATE_CAPTURED:
+    'x test e2e --json   # the fix line names the binding to inline into the closure',
+  X_E2E_EVALUATE_THREW:
+    'x dev --json   # then run the expression the cause quotes in the browser console; the throw is the page\u2019s',
+  X_E2E_LOCATOR_EMPTY:
+    'x test e2e --json   # the fix line carries the toBeVisible() assertion to await first',
+  X_E2E_LOCATOR_AMBIGUOUS:
+    'x test e2e --json   # the fix line carries the same call with .first() on it',
+  X_E2E_SERVICE_WORKER_ABSENT: 'x build --target static --json',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',
@@ -96,6 +110,9 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_RELEASE_VERSION_SKEW: 'bun run scripts/release.ts --bump patch --dry-run --json',
   // Two real remedies and the command cannot know which one this deployment wants, so it names
   // the one that inspects the binding rather than guessing between a volume and a bucket.
+  // `x db migrate --json` and not `x doctor`: this fires from inside `startQueue`, so the command
+  // that re-runs exactly the failing step is the migrate role, and it reports what it applied.
+  X_FRAMEWORK_SCHEMA_FAILED: 'x db migrate --json',
   X_STORAGE_UNWRITABLE: 'x doctor --json',
   X_STORAGE_SECRET_DEV: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
   X_MANIFEST_STALE: 'x manifest --json',
@@ -139,6 +156,18 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
   // reachability and drift, and is already this table's answer for X_DB_STUDIO_FAILED.
   X_DB_GEN_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
+  // Both directions resolve through the same command, and the CAUSE is what differs: one names a
+  // declaration the migrations never carried, the other one they carry and nothing declares. The
+  // narrowing is deliberately not a second command — there is only one generator.
+  X_DB_SCHEMA_UNMIGRATED:
+    'x db gen "add the declaration the cause names" --json   # then x db migrate --json',
+  X_DB_SCHEMA_UNDECLARED:
+    'x db gen "drop the declaration the cause names" --json   # or re-declare it on the entity',
+  // Not `x db gen`: regenerating is exactly what DISCARDS these statements, so the one command
+  // that must not be offered here is the one every other db code answers with. The gate is what
+  // reproduces the finding, and the finding names the file and the header line to add.
+  X_MIGRATION_UNGENERATABLE:
+    'x verify --only drift --json   # then add the `-- ungeneratable: <n>` header line the finding names',
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',