@ultimat3/cli 22.15.0 → 24.0.0

package/src/db-object-drift.ts

@@ -0,0 +1,30 @@
+// `x db migrate`'s second look at the database it just migrated: does it hold a trigger, function,
+// view, type or sequence that replaying the migrations does not create? `runMigrations` compares
+// tables against the snapshot and closes its connection; a snapshot records only what entities
+// declare, so everything else is asked here, against the catalog the schema dump was rendered from.
+
+import type { DriftDifference } from '@ultimat3/db';
+import type { CatalogDescription } from '@ultimat3/db/schema-dump';
+import { introspectCatalog, unexpectedObjects } from '@ultimat3/db/schema-dump';
+import { resolveServices } from './runtime-bindings';
+import { startQueue } from './runtime-queue';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The same boot `runMigrations` used, reopened: that function is `serve.ts`'s and is deliberately
+ * not wrapped, so the connection it held is gone by the time its report is in hand. Reopening an
+ * embedded database is a fraction of a second; `x db migrate` is not a hot path.
+ */
+export async function liveObjectDrift(
+  root: string,
+  env: Env,
+  expected: CatalogDescription,
+): Promise<readonly DriftDifference[]> {
+  const queue = await startQueue(resolveServices(root, env), undefined, env);
+  try {
+    return unexpectedObjects(await introspectCatalog({ client: queue.db }), expected);
+  } finally {
+    await queue.stop();
+  }
+}

package/src/db-replay-engine.ts

@@ -0,0 +1,115 @@
+// Which database the schema dump is replayed on, and that database, opened and thrown away. ONE
+// rule: the embedded database, unless the migrations create an extension it cannot link — then a
+// real Postgres, in a database this module creates and drops. Decided from the migrations and the
+// installed PGlite alone, never from which URL happens to be set, so a laptop and CI choose alike.
+
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import type { DbClient, LinkedExtensions, Migration } from '@ultimat3/db';
+import {
+  createPgliteClient,
+  createPostgresClient,
+  DbError,
+  linkPgliteExtensions,
+  raw,
+} from '@ultimat3/db';
+import { migrationExtensions } from './migration-extensions';
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/**
+ * Where a real Postgres is looked for, in order — the admin URL `@ultimat3/testing` already
+ * clones its template databases from (`template-db.ts`), so a CI that runs the `live` suite has
+ * it set and nothing new to configure.
+ */
+export const REPLAY_URL_ENVS = ['TEST_DATABASE_URL', 'DATABASE_URL'] as const;
+
+export type ReplayEngine =
+  | { readonly kind: 'embedded'; readonly extensions: readonly string[] }
+  | {
+      readonly kind: 'postgres';
+      readonly adminUrl: string;
+      /** The extensions that forced it, for the finding a missing URL becomes. */
+      readonly requires: readonly string[];
+    };
+
+/**
+ * The migrations need a server and none is named. `X_SCHEMA_DUMP_DRIFT`, because the dump cannot
+ * be produced or held; the cause names the extension, the fix the variable and the command.
+ */
+export function replayServerMissing(requires: readonly string[]): DbError {
+  const named = requires.map((name) => `"${name}"`).join(', ');
+  return new DbError({
+    code: 'X_SCHEMA_DUMP_DRIFT',
+    cause: `the migrations create extension ${named}, which the embedded database cannot link, so the schema dump is replayed on a real Postgres — and neither ${REPLAY_URL_ENVS.join(' nor ')} names one`,
+    fix: `${REPLAY_URL_ENVS[0]}=postgres://<user>:<password>@localhost:5432/postgres x db gen   # a server with that extension installed, and a role that may create a database`,
+    meta: { kind: 'engine-unavailable', extensions: [...requires] },
+  });
+}
+
+export type ExtensionLinker = (names: readonly string[]) => Promise<LinkedExtensions>;
+
+/** The rule. Throws `replayServerMissing` when it selects a server nobody named. */
+export async function chooseReplayEngine(
+  migrations: readonly Migration[],
+  env: Env,
+  link: ExtensionLinker = linkPgliteExtensions,
+): Promise<ReplayEngine> {
+  const extensions = migrationExtensions(migrations);
+  const { missing } = await link(extensions);
+  if (missing.length === 0) return { kind: 'embedded', extensions };
+  const adminUrl = REPLAY_URL_ENVS.map((name) => env[name]).find(
+    (value) => value !== undefined && value.length > 0,
+  );
+  if (adminUrl === undefined) throw replayServerMissing(missing);
+  return { kind: 'postgres', adminUrl, requires: missing };
+}
+
+/** Unique per call: two `x db gen` runs against one server must not share a scratch database. */
+const scratchName = (): string => `x_schema_dump_${process.pid}_${crypto.randomUUID().slice(0, 8)}`;
+
+async function withPostgresScratch<T>(
+  adminUrl: string,
+  work: (client: DbClient) => Promise<T>,
+): Promise<T> {
+  const database = scratchName();
+  const admin = createPostgresClient({ url: adminUrl });
+  try {
+    // `template0`: the server's `template1` may carry objects an operator put there, and they
+    // would be dumped as the app's.
+    await admin.execute(raw(`create database ${database} template template0`));
+    const target = new URL(adminUrl);
+    target.pathname = `/${database}`;
+    const client = createPostgresClient({ url: target.toString() });
+    try {
+      return await work(client);
+    } finally {
+      await client.close();
+      await admin.execute(raw(`drop database if exists ${database} with (force)`));
+    }
+  } finally {
+    await admin.close();
+  }
+}
+
+/**
+ * Run `work` against an empty scratch database on `engine`, and release it. The embedded one
+ * boots from the snapshot cache under `stateDir`, so only the first boot per PGlite version runs
+ * `initdb`.
+ */
+export async function withScratchDatabase<T>(
+  engine: ReplayEngine,
+  stateDir: string | undefined,
+  work: (client: DbClient) => Promise<T>,
+): Promise<T> {
+  if (engine.kind === 'postgres') return withPostgresScratch(engine.adminUrl, work);
+  const client = createPgliteClient({
+    extensions: engine.extensions,
+    ...(stateDir === undefined ? {} : { snapshotDir: join(stateDir, 'cache') }),
+  });
+  try {
+    return await work(client);
+  } finally {
+    await client.close();
+  }
+}

package/src/db-schema-dump.ts

@@ -0,0 +1,150 @@
+// The app's schema dump — `packages/db/schema/` — produced, read and written. ONE producer: a
+// scratch database (`db-replay-engine.ts` says which) with the framework's tables applied and
+// every migration replayed, never the developer's own database. `x db gen`, `x db migrate` and the `drift` step all call it,
+// so the bytes the gate compares against are the bytes the commands wrote, on one engine.
+
+// why: Bun has no directory probe — `Bun.file().exists()` answers about a file.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import type { Migration } from '@ultimat3/db';
+import { migrate, raw } from '@ultimat3/db';
+import type {
+  CatalogDescription,
+  SchemaDumpDifference,
+  SchemaDumpFile,
+} from '@ultimat3/db/schema-dump';
+import {
+  introspectCatalog,
+  loadSchemaDump,
+  reloadDifferences,
+  renderSchemaDump,
+  schemaDumpDifferenceOf,
+} from '@ultimat3/db/schema-dump';
+import { chooseReplayEngine, withScratchDatabase } from './db-replay-engine';
+import { applyFrameworkSchema } from './framework-schema';
+import { resolveServices } from './runtime-bindings';
+
+/** Where the dump lives. App-root-relative, POSIX — beside `MIGRATIONS_DIR`, its one source. */
+export const SCHEMA_DUMP_DIR = 'packages/db/schema';
+
+export interface ReplayedSchema {
+  readonly catalog: CatalogDescription;
+  readonly files: readonly SchemaDumpFile[];
+  /** Empty when a database loaded from `files` renders `files` again. Always empty without `reload`. */
+  readonly reload: readonly SchemaDumpDifference[];
+}
+
+export interface ReplayOptions {
+  /** Also prove load equals replay: reset the schema, load the dump, render it again. */
+  readonly reload?: boolean | undefined;
+  /** The app's state directory (`.x/`), where the embedded scratch boot keeps its snapshot. */
+  readonly stateDir?: string | undefined;
+  /** Read for the server URL when the migrations cannot replay on the embedded database. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/**
+ * Framework tables first, then every migration — the order every real boot runs them in
+ * (`startQueue`, then `migrate`), so a migration's foreign key into `x_users` finds its target.
+ * The client is handed to each call and never installed as the ambient `db()`: this runs inside
+ * `x verify`, beside steps that own that accessor.
+ *
+ * The reload reuses the SAME database, emptied — a second scratch database is a second boot for a
+ * question `drop schema … cascade` answers as well. It is asked only of a dump that claims to be
+ * whole: one that lists objects in `unrendered.sql` has already said a database loaded from it is
+ * not the migrated one.
+ */
+export async function replaySchema(
+  migrations: readonly Migration[],
+  options: ReplayOptions = {},
+): Promise<ReplayedSchema> {
+  const engine = await chooseReplayEngine(migrations, options.env ?? Bun.env);
+  return withScratchDatabase(engine, options.stateDir, async (client) => {
+    await applyFrameworkSchema((statement) => client.execute(raw(statement)));
+    await migrate({ migrations, client });
+    const catalog = await introspectCatalog({ client });
+    const files = renderSchemaDump(catalog);
+    if (options.reload !== true || catalog.unrendered.length > 0) {
+      return { catalog, files, reload: [] };
+    }
+    await client.execute(raw('drop schema public cascade'));
+    await client.execute(raw('create schema public'));
+    try {
+      await loadSchemaDump({ client, files });
+    } catch (error) {
+      // A refusal to load is a verdict about the dump, not a failed replay: reported as the
+      // difference it is, so the caller's finding names the file rather than the engine.
+      const refused = schemaDumpDifferenceOf(error);
+      if (refused === undefined) throw error;
+      return { catalog, files, reload: [refused] };
+    }
+    const reloaded = renderSchemaDump(await introspectCatalog({ client }));
+    return { catalog, files, reload: reloadDifferences(files, reloaded) };
+  });
+}
+
+/** The replay for an app on disk: its own state directory, its command's environment. */
+export const replayFor = (
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  reload: boolean,
+): ((migrations: readonly Migration[]) => Promise<ReplayedSchema>) => {
+  return (migrations) =>
+    replaySchema(migrations, { reload, env, stateDir: resolveServices(root, env).stateDir });
+};
+
+export const hasSchemaDump = (root: string): boolean => existsSync(join(root, SCHEMA_DUMP_DIR));
+
+/** Every `.sql` under the dump directory, sorted by path — the shape `renderSchemaDump` answers in. */
+export async function readSchemaDump(root: string): Promise<readonly SchemaDumpFile[]> {
+  const dir = join(root, SCHEMA_DUMP_DIR);
+  if (!existsSync(dir)) return [];
+  const paths: string[] = [];
+  for await (const path of new Bun.Glob('**/*.sql').scan({ cwd: dir })) {
+    paths.push(path.replaceAll('\\', '/'));
+  }
+  paths.sort();
+  const files: SchemaDumpFile[] = [];
+  for (const path of paths) {
+    files.push({ path, content: await Bun.file(join(dir, path)).text() });
+  }
+  return files;
+}
+
+export interface SchemaDumpWrite {
+  /** App-root-relative paths whose bytes this call changed or created. */
+  readonly written: readonly string[];
+  /** Files the dump no longer produces, deleted. */
+  readonly removed: readonly string[];
+  /** Every file the dump holds after the write. */
+  readonly total: number;
+}
+
+/**
+ * Make the directory equal to `files`: write what differs, delete what nothing renders. A file
+ * whose bytes already match is left untouched, so an unchanged table keeps its mtime and a
+ * one-table migration is a one-file write.
+ */
+export async function writeSchemaDump(
+  root: string,
+  files: readonly SchemaDumpFile[],
+): Promise<SchemaDumpWrite> {
+  const dir = join(root, SCHEMA_DUMP_DIR);
+  const held = new Map((await readSchemaDump(root)).map((file) => [file.path, file.content]));
+  const written: string[] = [];
+  for (const file of files) {
+    if (held.get(file.path) === file.content) continue;
+    // `createPath` is Bun's default, spelled: a kind directory may not exist yet.
+    await Bun.write(join(dir, file.path), file.content, { createPath: true });
+    written.push(`${SCHEMA_DUMP_DIR}/${file.path}`);
+  }
+  const rendered = new Set(files.map((file) => file.path));
+  const removed: string[] = [];
+  for (const path of held.keys()) {
+    if (rendered.has(path)) continue;
+    await Bun.file(join(dir, path)).delete();
+    removed.push(`${SCHEMA_DUMP_DIR}/${path}`);
+  }
+  return { written, removed, total: files.length };
+}

package/src/db-schema-refresh.ts

@@ -0,0 +1,122 @@
+// The schema dump, regenerated on behalf of a command: `x db gen` and `x db migrate` both end by
+// making `packages/db/schema/` equal to what the migrations produce. Split from
+// `db-schema-dump.ts`, which replays and writes; this decides what a command REPORTS when the dump
+// was written, was already right, was not owed, or could not be produced — and holds the two
+// findings that are about the dump as a whole rather than about one file in it.
+
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import type { Migration } from '@ultimat3/db';
+import { PGLITE_MISSING } from '@ultimat3/db';
+import type { CatalogDescription } from '@ultimat3/db/schema-dump';
+import {
+  hasSchemaDump,
+  type ReplayedSchema,
+  replayFor,
+  SCHEMA_DUMP_DIR,
+  type SchemaDumpWrite,
+  writeSchemaDump,
+} from './db-schema-dump';
+import { MIGRATIONS_DIR, readMigrations } from './migrations';
+import type { Finding, JsonValue } from './output';
+import { findingFrom, isUltimateErrorShape } from './output';
+
+/**
+ * The migrations would not replay, so there is no dump to write and nothing to compare one with.
+ * A framework error keeps its own cause; the fix is replaced, because the engine's own (`set
+ * DATABASE_URL …`) answers a question nobody asked — this database is a scratch one booted here.
+ *
+ * Two causes are not about the migrations at all, and each keeps the fix that repairs it: a
+ * refusal this pipeline raised itself (`X_SCHEMA_DUMP_DRIFT` — no server for an extension the
+ * embedded database cannot link) arrives whole, and a missing optional peer gets the install,
+ * because `x db migrate` would succeed and teach nothing.
+ */
+export function replayFailure(error: unknown): Finding {
+  if (isUltimateErrorShape(error) && error.code === 'X_SCHEMA_DUMP_DRIFT') {
+    return { ...findingFrom(error), docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR };
+  }
+  const detail = isUltimateErrorShape(error) ? findingFrom(error).cause : renderThrowable(error);
+  const missing = detail.startsWith(PGLITE_MISSING);
+  return {
+    code: 'X_SCHEMA_DUMP_DRIFT',
+    cause: missing
+      ? `the schema dump is replayed on the embedded database and ${detail}`
+      : `the migrations do not replay on the scratch database, so the schema dump cannot be produced: ${detail}`,
+    fix: missing
+      ? // A literal, as `@ultimat3/db`'s own `PGLITE_FIX` is: a `fix:` splices nothing into its
+        // command position, and `db-schema-refresh.test.ts` holds it equal to `PGLITE_PACKAGE`.
+        'bun add -d @electric-sql/pglite   # then: x db gen'
+      : 'x db migrate --json   # applies the same migrations to the dev database; a statement refused there too is the one to repair — then: x db gen',
+    docs: ERROR_DOCS_URL,
+    at: missing ? SCHEMA_DUMP_DIR : MIGRATIONS_DIR,
+  };
+}
+
+/**
+ * The same finding, for a run of `x db gen` that DID write its migration before the dump failed.
+ * The exit code is 1 and the migration is on disk, and a reader who sees only the first fact
+ * generates a second migration for a schema that is already recorded. So the cause leads with
+ * the file that exists, and says what the next `x db gen` will and will not do.
+ */
+export const afterWrittenMigration = (finding: Finding, id: string): Finding => ({
+  ...finding,
+  cause: `migration ${id} WAS written to ${MIGRATIONS_DIR} and is not to be generated again; only the schema dump failed, and once that is repaired a bare x db gen writes the dump and no second migration — ${finding.cause}`,
+});
+
+/** An app with a migration and no dump directory: one finding, and no database booted to say so. */
+export const dumpNeverGenerated = (): Finding => ({
+  code: 'X_SCHEMA_DUMP_DRIFT',
+  cause: `${MIGRATIONS_DIR} holds migrations and ${SCHEMA_DUMP_DIR} does not exist: the schema dump was never generated`,
+  fix: 'x db gen',
+  docs: ERROR_DOCS_URL,
+  at: SCHEMA_DUMP_DIR,
+});
+
+export interface SchemaDumpRefresh extends SchemaDumpWrite {
+  /**
+   * `skipped` — no migration and no dump, so nothing is owed and no database is booted.
+   * `failed` — the migrations did not replay; `finding` says why, and the dump on disk is left
+   * exactly as it was.
+   */
+  readonly status: 'written' | 'unchanged' | 'skipped' | 'failed';
+  readonly finding?: Finding | undefined;
+  /** The replayed catalog, for a caller that compares a live database against it. */
+  readonly catalog?: CatalogDescription | undefined;
+}
+
+const NOTHING: SchemaDumpWrite = { written: [], removed: [], total: 0 };
+
+/**
+ * Regenerate the dump after `x db gen` or `x db migrate`. Never throws: a replay that fails is
+ * reported as the finding it is, after the migration the command was asked for is already written.
+ */
+export async function refreshSchemaDump(
+  root: string,
+  env: Readonly<Record<string, string | undefined>> = Bun.env,
+  // Injected so the reporting rules are testable without booting a database per case.
+  replay: (migrations: readonly Migration[]) => Promise<ReplayedSchema> = replayFor(
+    root,
+    env,
+    false,
+  ),
+): Promise<SchemaDumpRefresh> {
+  const migrations = await readMigrations(root);
+  if (migrations.length === 0 && !hasSchemaDump(root)) return { ...NOTHING, status: 'skipped' };
+  let replayed: ReplayedSchema;
+  try {
+    replayed = await replay(migrations);
+  } catch (error) {
+    return { ...NOTHING, status: 'failed', finding: replayFailure(error) };
+  }
+  const write = await writeSchemaDump(root, replayed.files);
+  const changed = write.written.length + write.removed.length > 0;
+  return { ...write, status: changed ? 'written' : 'unchanged', catalog: replayed.catalog };
+}
+
+/** The `--json` shape both commands report under `data.schemaDump`. */
+export const schemaDumpJson = (refresh: SchemaDumpRefresh): JsonValue => ({
+  directory: SCHEMA_DUMP_DIR,
+  status: refresh.status,
+  files: refresh.total,
+  written: [...refresh.written],
+  removed: [...refresh.removed],
+});

package/src/db-subscribes.ts

@@ -1,8 +1,9 @@
-// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL`, read off the
-// live queries' DECLARED `subscribes:` — and the refusal for a declared name no entity's table
-// matches. This tier is the only one holding both registries, so it is the only one that can ask.
+// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL` — the live
+// queries' DECLARED `subscribes:` plus the `records` tables of every channel with params — and the
+// refusal for a declared name no entity's table matches. Only this tier holds all the registries.
 
 import { UltimateError } from '@ultimat3/core';
+import { paramsChannelTables } from '@ultimat3/realtime/server';
 
 /**
  * The two fields this reads, and nothing else. Structurally satisfied by `QueryDescriptor` (whose
@@ -63,12 +64,19 @@ export class QuerySubscribesUnknownError extends UltimateError {
  * Every name is checked against `tables` BEFORE any of them is returned: a run that emitted the
  * good half and refused afterwards would leave an author with a migration that is right for one
  * table and silently absent for the other.
+ *
+ * `channelTables` defaults to what the declared channels need (`paramsChannelTables()`): a channel
+ * with params routes a DELETE to the topic the OLD row names, and under the default identity that
+ * image is the key alone — no topic, no `remove`, and members keep the deleted record. They are
+ * derived from entity projections rather than typed by an author, so one outside `tables` is
+ * dropped, not refused: there is no declaration to send anyone back to.
  */
 export function replicaIdentityTables(
   queries: readonly SubscribingQuery[],
   tables: ReadonlySet<string>,
+  channelTables: readonly string[] = paramsChannelTables(),
 ): readonly string[] {
-  const wanted = new Set<string>();
+  const wanted = new Set<string>(channelTables.filter((table) => tables.has(table)));
   for (const query of queries) {
     for (const table of query.subscribes ?? []) {
       if (!tables.has(table)) {

package/src/dev-dashboard-guard.ts

@@ -0,0 +1,76 @@
+// The doors in front of `/_x` that a browser can knock on. `x dev` binds loopback, but a page the
+// developer has open can still reach it: by DNS rebinding (a hostile name that resolves to
+// 127.0.0.1, read back same-origin) and by a cross-site request to the SQL panel.
+
+import { proveSameOrigin, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import type { UltimateRequest } from '@ultimat3/http';
+import { csrfBlocked, HttpError, json as jsonResponse, selfOrigin } from '@ultimat3/http';
+import { t } from '@ultimat3/schema';
+import { isLoopbackHostname } from './loopback-host';
+
+/** A `/_x` request named a Host that is not this machine. Never echoes the Host it was sent. */
+export class DevHostRefusedError extends UltimateError {
+  constructor(input: { devUrl: string }) {
+    super({
+      code: 'X_DEV_HOST_REFUSED',
+      cause:
+        'a /_x request named a Host that is not localhost, a *.localhost name or a loopback address — the shape of a DNS-rebinding page reading the dev dashboard',
+      fix: `curl -sS -H 'accept: application/json' ${renderFixShellArg(`${input.devUrl}/_x`, 'http://localhost:3000/_x')}`,
+    });
+  }
+}
+
+/** The Host as sent, else the one the URL was built from — Bun builds it from the header. */
+const hostnameOf = (request: UltimateRequest): string | undefined => {
+  const header = request.header('host') ?? request.url.host;
+  return URL.parse(`http://${header}`)?.hostname;
+};
+
+/**
+ * `421 Misdirected Request` for a Host that is not this machine, on every `/_x` route. The status
+ * says "not this server", which is the truth: a rebound name was never meant to reach it.
+ */
+export function hostRefusal(request: UltimateRequest, devUrl: string): Response | undefined {
+  const hostname = hostnameOf(request);
+  if (hostname !== undefined && isLoopbackHostname(hostname)) return undefined;
+  const error = new DevHostRefusedError({ devUrl });
+  return jsonResponse(
+    { ok: false, error: { code: error.code, cause: error.cause, fix: error.fix } },
+    { status: 421 },
+  );
+}
+
+/**
+ * A statement runs on a POST that came from this origin — core's `proveSameOrigin`, the rule the
+ * app's own writes and the sync upgrade answer to, asked HERE rather than left to the pipeline's
+ * CSRF stage: an app with `csrf: { mode: 'off' }` must not switch the dev database's door off with
+ * it. Neither header present is `curl`, as `checkCsrf` reads it: no page can drive that client.
+ */
+export function assertSameOrigin(request: UltimateRequest): void {
+  const origin = request.header('origin');
+  const secFetchSite = request.header('sec-fetch-site');
+  if (origin === null && secFetchSite === null) return;
+  const verdict = proveSameOrigin({
+    selfOrigins: [selfOrigin(request.url, request.ctx.https)],
+    origin,
+    secFetchSite,
+    listed: () => false,
+    listName: 'no list — /_x admits its own origin only',
+  });
+  if (!verdict.ok) throw csrfBlocked(request.pathname, verdict.reason, request.ctx.ip);
+}
+
+/** The SQL panel's one input, from a form or a JSON body — `request.body` parses either. */
+export const SQL_BODY = t.object({ sql: t.string });
+
+/**
+ * A statement on the query string is refused rather than run: a GET is what `<img src>` and a
+ * prefetch send cross-site with nobody's consent. The fix is the POST that does run it.
+ */
+export const sqlOnGet = (devUrl: string): HttpError =>
+  new HttpError({
+    code: 'X_METHOD_NOT_ALLOWED',
+    cause:
+      '/_x/db runs a statement on a same-origin POST only — a GET carrying ?sql= is what a cross-site page can send',
+    fix: `curl -sS -H 'accept: application/json' --data-urlencode 'sql=select 1' ${renderFixShellArg(`${devUrl}/_x/db`, 'http://localhost:3000/_x/db')}`,
+  });

package/src/dev-dashboard.ts

@@ -1,6 +1,6 @@
 // Mounting `@ultimat3/admin`'s `/_x` dashboard in the `x dev` process. The CLI contributes only
-// what no registry holds — a SQL runner on the live dev database, the caught outbox, the committed
-// manifest, and two panels of process facts — and projects the dashboard onto HTTP routes.
+// what no registry holds — the live dev database, the caught outbox, the committed manifest, and
+// two panels of process facts — and projects the dashboard onto HTTP routes behind a Host check.
 // A panel implemented here instead of in `admin` would be the second copy this seam exists to ban.
 
 import type {
@@ -14,7 +14,13 @@ import type {
   SqlResult,
   StatementLoopFact,
 } from '@ultimat3/admin/dev';
-import { DEV_BASE_PATH, DEV_PANELS, defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
+import {
+  DEV_BASE_PATH,
+  DEV_PANELS,
+  defaultDevSources,
+  devDashboard,
+  readOnlySql,
+} from '@ultimat3/admin/dev';
 import { recentInvalidations } from '@ultimat3/cache';
 import type { Role } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
@@ -24,6 +30,7 @@ import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
 import { appManifest, readAppManifest } from './app-manifest';
 import { appBoundaryFindings } from './boundary-findings';
+import { assertSameOrigin, hostRefusal, SQL_BODY, sqlOnGet } from './dev-dashboard-guard';
 import type { StatementLedger } from './dev-n-plus-one';
 import { devPolicyMatrix } from './dev-policy';
 import type { TraceRecorder } from './dev-traces';
@@ -53,24 +60,6 @@ export interface DevDashboardInput {
   readonly statements?: StatementLedger | undefined;
 }
 
-/**
- * Read-only is already enforced by `assertReadOnly` inside `dbPanel`, before `runSql` is ever
- * reached. A second gate here would be a second authz: two places to update when `x db psql
- * --write` changes what is allowed, and one of them would eventually disagree.
- */
-async function runSql(input: DevDashboardInput, sql: string): Promise<SqlResult> {
-  const started = performance.now();
-  const rows = await input.runtime.db.query<Readonly<Record<string, unknown>>>({
-    text: sql,
-    values: [],
-  });
-  const elapsedMs = Math.round(performance.now() - started);
-  // Columns come from the first row because the driver returns objects, not a described result
-  // set; no rows means no columns to name, which the panel renders as an empty grid.
-  const columns = Object.keys(rows[0] ?? {});
-  return { columns, rows: rows.map((row) => columns.map((column) => row[column])), elapsedMs };
-}
-
 /** `MailMessage.locale` is non-optional in `@ultimat3/mail`, so the panel never has to guess. */
 function mailFacts(outbox: MemoryMailDriver): readonly MailFact[] {
   return outbox.outbox().map((entry) => ({
@@ -137,9 +126,13 @@ export function devSources(input: DevDashboardInput): DevSources {
   // the messages are at the provider, so the hook is omitted rather than answered with `[]` —
   // an empty outbox claims nobody was mailed, which is a different and unearned answer.
   const outbox = isMemoryDriver(input.runtime.mail) ? input.runtime.mail : undefined;
+  // `dbPanel`'s `assertReadOnly` is the parse guard; `readOnlySql` is the server saying no — its own
+  // `BEGIN READ ONLY` that always rolls back, a statement timeout and a row ceiling. The plain
+  // `db.query` it replaces ran whatever the guard let through with the app's own credentials.
+  const runSql = readOnlySql(input.runtime.db);
   return defaultDevSources({
     hooks: {
-      runSql: (sql: string): Promise<SqlResult> => runSql(input, sql),
+      runSql: (sql: string): Promise<SqlResult> => runSql(sql),
       ...(outbox === undefined
         ? {}
         : { mail: (): Promise<readonly MailFact[]> => Promise.resolve(mailFacts(outbox)) }),
@@ -222,8 +215,13 @@ const notClaimed = (path: string): Response =>
     { status: 404 },
   );
 
-const devRoute = (path: string, name: string, handler: Route['handler']): Route => ({
-  method: 'GET',
+const devRoute = (
+  path: string,
+  name: string,
+  handler: Route['handler'],
+  method: 'GET' | 'POST' = 'GET',
+): Route => ({
+  method,
   path,
   // Public: /_x exists to be read without credentials by whatever drives the dev loop, and
   // `devDashboard` refuses to construct at all outside development.
@@ -232,9 +230,10 @@ const devRoute = (path: string, name: string, handler: Route['handler']): Route
 });
 
 /**
- * One route for the base path plus one per panel, because the router matches exact paths. The
- * dashboard is built once — its sources close over this process, and rebuilding per request would
- * re-run `assertDevOnly` on every hit for no new answer.
+ * One route for the base path plus one per panel, because the router matches exact paths, and a
+ * `POST` for the SQL panel — the only `/_x` read that runs something. The dashboard is built once
+ * — its sources close over this process, and rebuilding per request would re-run `assertDevOnly`
+ * on every hit for no new answer. Every route answers this machine's Host only.
  */
 export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
   const panels = devPanels(input);
@@ -245,13 +244,36 @@ export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
     ...(input.env === undefined ? {} : { env: input.env }),
   });
 
-  const handler = async (request: UltimateRequest): Promise<Response> =>
-    (await dashboard.handle(request.raw)) ?? notClaimed(request.pathname);
+  const sqlPath = `${DEV_BASE_PATH}/db`;
+  const handler = async (request: UltimateRequest): Promise<Response> => {
+    const devUrl = input.status().url;
+    const refused = hostRefusal(request, devUrl);
+    if (refused !== undefined) return refused;
+    if (request.pathname === sqlPath && request.url.searchParams.has('sql')) throw sqlOnGet(devUrl);
+    return (await dashboard.handle(request.raw)) ?? notClaimed(request.pathname);
+  };
+  // The statement moves from the body onto the panel's own parameter, server side: `dbPanel`
+  // reads `sql` off the query, and this is the one caller allowed to put it there.
+  const runStatement = async (request: UltimateRequest): Promise<Response> => {
+    const refused = hostRefusal(request, input.status().url);
+    if (refused !== undefined) return refused;
+    assertSameOrigin(request);
+    const { sql } = await request.body(SQL_BODY);
+    const target = new URL(request.url);
+    target.searchParams.set('sql', sql);
+    // A GET carries no body, so the body's own headers stay behind; `accept` and the rest ride.
+    const headers = new Headers(request.headers);
+    headers.delete('content-type');
+    headers.delete('content-length');
+    const forwarded = new Request(target, { headers });
+    return (await dashboard.handle(forwarded)) ?? notClaimed(request.pathname);
+  };
 
   return [
     devRoute(DEV_BASE_PATH, 'dev._x', handler),
     ...panels.map((panel) =>
       devRoute(`${DEV_BASE_PATH}/${panel.key}`, `dev._x.${panel.key}`, handler),
     ),
+    devRoute(sqlPath, 'dev._x.db.run', runStatement, 'POST'),
   ];
 }