@ultimat3/admin 1.0.0

package/src/dev/data.ts

@@ -0,0 +1,344 @@
+// Every /_x panel reads from here, and every method is an introspection call — never a
+// bespoke query. That is what makes the dashboard and the MCP dev server the same facts in
+// two renderings: `--json` on a panel returns exactly what the panel drew.
+//
+// The framework introspection modules are reached through dynamic `import()` so the
+// production graph never statically references them: /_x must not cost the app path a byte.
+
+// Type-only, so it is erased: the introspection modules are still reached by dynamic
+// `import()` below and /_x stays out of the production graph.
+import type { JobState, StepStatus } from '@ultimat3/jobs';
+import type { AdminActor, AdminAuthz } from '../authz';
+import { DevSourceUnavailableError } from '../errors';
+import type {
+  CacheEdgeFact,
+  DevSources,
+  DriftFact,
+  InvalidationFact,
+  JobDefFact,
+  JobRunFact,
+  JobStepFact,
+  LiveQueryFact,
+  LiveSubscriberFact,
+  MailFact,
+  ManifestFact,
+  PolicyFact,
+  QueueFact,
+  RequestTrace,
+  RouteFact,
+  SqlResult,
+  TableFact,
+  TaskFact,
+} from './facts';
+
+const empty = async <T>(value: T): Promise<T> => value;
+
+/** Explicit fixtures. Tests and `x dev --offline` use this; it is not a fallback path. */
+export function staticDevSources(facts: Partial<DevSources> = {}): DevSources {
+  return {
+    routes: facts.routes ?? ((): Promise<readonly RouteFact[]> => empty([])),
+    traces: facts.traces ?? ((): Promise<readonly RequestTrace[]> => empty([])),
+    liveQueries: facts.liveQueries ?? ((): Promise<readonly LiveQueryFact[]> => empty([])),
+    subscribers: facts.subscribers ?? ((): Promise<readonly LiveSubscriberFact[]> => empty([])),
+    jobDefs: facts.jobDefs ?? ((): Promise<readonly JobDefFact[]> => empty([])),
+    queues: facts.queues ?? ((): Promise<readonly QueueFact[]> => empty([])),
+    jobRuns: facts.jobRuns ?? ((): Promise<readonly JobRunFact[]> => empty([])),
+    tasks: facts.tasks ?? ((): Promise<readonly TaskFact[]> => empty([])),
+    tables: facts.tables ?? ((): Promise<readonly TableFact[]> => empty([])),
+    drift: facts.drift ?? ((): Promise<readonly DriftFact[]> => empty([])),
+    runSql:
+      facts.runSql ?? ((): Promise<SqlResult> => empty({ columns: [], rows: [], elapsedMs: 0 })),
+    mail: facts.mail ?? ((): Promise<readonly MailFact[]> => empty([])),
+    cacheGraph: facts.cacheGraph ?? ((): Promise<readonly CacheEdgeFact[]> => empty([])),
+    invalidations: facts.invalidations ?? ((): Promise<readonly InvalidationFact[]> => empty([])),
+    policyMatrix: facts.policyMatrix ?? ((): Promise<readonly PolicyFact[]> => empty([])),
+    manifest:
+      facts.manifest ??
+      ((): Promise<ManifestFact> => empty({ emitted: null, committed: null, diff: [] })),
+  };
+}
+
+type Bag = Readonly<Record<string, unknown>>;
+
+const bagOf = (value: unknown): Bag =>
+  typeof value === 'object' && value !== null ? (value as Bag) : {};
+const str = (value: unknown, fallback = ''): string =>
+  typeof value === 'string' ? value : fallback;
+const numOf = (value: unknown, fallback = 0): number =>
+  typeof value === 'number' ? value : fallback;
+const listOf = (value: unknown): readonly unknown[] => (Array.isArray(value) ? value : []);
+const strings = (value: unknown): readonly string[] => listOf(value).map((item) => String(item));
+
+export interface DevSourceOptions {
+  /** The app's authz. The policy matrix is computed through it, never re-derived. */
+  readonly authz?: AdminAuthz;
+  /** Actors the matrix is computed for. `x dev --actor` supplies these. */
+  readonly actors?: readonly AdminActor[];
+  /**
+   * Facts no registry can produce on its own — request traces, caught mail, the read-only
+   * SQL tool, the committed manifest. Unwired ones throw X_NOT_IMPLEMENTED with the exact
+   * wiring line, rather than rendering an empty panel that reads as "nothing happened".
+   */
+  readonly hooks?: Partial<DevSources>;
+}
+
+const unavailable = (source: string, panel: string): DevSourceUnavailableError =>
+  new DevSourceUnavailableError({ source, panel });
+
+const unwired = <T>(source: string, panel: string): (() => Promise<T>) => {
+  // A rejected promise, never a synchronous throw: every caller's declared return type is
+  // `Promise<T>`, and panels like `panel-cache.ts` degrade with `sources.invalidations().catch(…)`.
+  // A synchronous throw fires while that expression is still being evaluated, before there is a
+  // promise for `.catch` to attach to, so it escapes the panel's own degradation entirely.
+  return (): Promise<T> => Promise.reject(unavailable(source, panel));
+};
+
+/** How many recent runs the jobs panel traces. A dev panel reads, it does not page. */
+const RUN_WINDOW = 50;
+
+/** `JobState` and `StepStatus` are the queue's vocabulary; the panel renders its own. */
+const RUN_STATUS: Readonly<Record<JobState, JobRunFact['status']>> = {
+  ready: 'running',
+  delayed: 'running',
+  running: 'running',
+  suspended: 'running',
+  done: 'ok',
+  failed: 'failed',
+  dead: 'dead',
+};
+
+const STEP_STATUS: Readonly<Record<StepStatus, JobStepFact['status']>> = {
+  completed: 'ok',
+  sleeping: 'sleeping',
+  waiting: 'pending',
+  failed: 'failed',
+};
+
+/**
+ * Registry output is read field by field: a registry that grows a field must not break the
+ * dev dashboard, and a registry that renames one should show a blank cell in /_x rather than
+ * crash the process an engineer is debugging with.
+ */
+export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
+  const hooks = opts.hooks ?? {};
+
+  const sources: DevSources = {
+    async routes(): Promise<readonly RouteFact[]> {
+      const { describeRoutes } = await import('@ultimat3/render');
+      return listOf(describeRoutes()).map((raw) => {
+        const route = bagOf(raw);
+        const budget = bagOf(route['budget']);
+        return {
+          path: str(route['path']),
+          render: str(route['render'], 'stream'),
+          offline: str(route['offline'], 'network-only'),
+          hydrate: str(route['hydrate'], 'idle'),
+          handler: str(route['handler'], str(route['file'])),
+          budget: {
+            ...(typeof budget['js'] === 'string' ? { js: budget['js'] } : {}),
+            ...(typeof budget['lcp'] === 'number' ? { lcp: budget['lcp'] } : {}),
+          },
+          revalidateTags: strings(bagOf(route['revalidate'])['tags']),
+          hasMeta: route['meta'] !== undefined,
+        };
+      });
+    },
+
+    traces: unwired<readonly RequestTrace[]>('traces', 'timeline'),
+
+    async liveQueries(): Promise<readonly LiveQueryFact[]> {
+      const { describeQueries } = await import('@ultimat3/query');
+      return listOf(describeQueries()).map((raw) => {
+        const query = bagOf(raw);
+        return {
+          name: str(query['name']),
+          live: query['live'] === true,
+          // `QueryDescriptor`'s permission field is named `capability`, not `policy` — this
+          // fact keeps its own field named `policy` (that is the /_x rendering, not the registry).
+          policy: str(query['capability']),
+          // `QueryDescriptor` carries no SQL text at all; this stays blank until the query
+          // registry actually describes one — never invent a value here.
+          sql: str(query['sql']),
+        };
+      });
+    },
+
+    subscribers: unwired<readonly LiveSubscriberFact[]>('subscribers', 'live'),
+
+    async jobDefs(): Promise<readonly JobDefFact[]> {
+      const { describeJobs } = await import('@ultimat3/jobs');
+      return listOf(describeJobs()).map((raw) => {
+        const job = bagOf(raw);
+        const retry = bagOf(job['retry']);
+        return {
+          name: str(job['name']),
+          queue: str(job['queue'], 'default'),
+          steps: strings(job['steps']),
+          retry: {
+            attempts: numOf(retry['attempts'], 1),
+            backoff: str(retry['backoff'], 'exponential'),
+          },
+          idempotent: job['idempotencyKey'] !== undefined,
+        };
+      });
+    },
+
+    async queues(): Promise<readonly QueueFact[]> {
+      const { inspectJobList, inspectQueues, jobDriver } = await import('@ultimat3/jobs');
+      const driver = jobDriver();
+      if (driver === undefined) throw unavailable('queues', 'jobs');
+      const report = await inspectQueues(driver);
+      // `stats()` counts states, and a failed job is one of them only until it is retried or
+      // dead-lettered; the honest count comes from the job list, which needs introspection.
+      const failed =
+        driver.introspect === undefined ? [] : await inspectJobList(driver, { state: 'failed' });
+      return report.queues.map((queue) => ({
+        name: queue.queue,
+        depth: queue.ready + queue.delayed,
+        running: queue.running,
+        failed: failed.filter((record) => record.queue === queue.queue).length,
+        deadLetter: queue.dead,
+      }));
+    },
+
+    async jobRuns(): Promise<readonly JobRunFact[]> {
+      const { inspectJob, inspectJobList, jobDriver } = await import('@ultimat3/jobs');
+      const driver = jobDriver();
+      if (driver === undefined) throw unavailable('jobRuns', 'jobs');
+      const records = await inspectJobList(driver, { limit: RUN_WINDOW });
+      // One trace per run, because the panel's whole question is "which step failed?" — a
+      // list row without its steps cannot answer it.
+      const traces = await Promise.all(records.map((record) => inspectJob(driver, record.id)));
+      return traces
+        .filter((trace): trace is NonNullable<typeof trace> => trace !== undefined)
+        .map((trace) => ({
+          id: trace.id,
+          job: trace.name,
+          queue: trace.queue,
+          status: RUN_STATUS[trace.state],
+          attempt: trace.attempt,
+          steps: trace.steps.map((step) => ({
+            name: step.name,
+            status: STEP_STATUS[step.status],
+            attempt: step.attempts,
+            durationMs: step.durationMs ?? 0,
+            error: step.error,
+          })),
+        }));
+    },
+
+    async tasks(): Promise<readonly TaskFact[]> {
+      const { inspectManifest } = await import('@ultimat3/jobs');
+      return inspectManifest().tasks.map((task) => ({
+        name: task.name,
+        cron: task.cron,
+        tz: task.tz,
+        nextRunAt: task.nextRun,
+      }));
+    },
+
+    async tables(): Promise<readonly TableFact[]> {
+      const { describeEntities } = await import('@ultimat3/entity');
+      return listOf(describeEntities()).map((raw) => {
+        const entity = bagOf(raw);
+        return {
+          name: str(entity['table'], str(entity['name'])),
+          // `EntityDescription.columns` is a LIST of physical columns — money is already two
+          // of them here. Reading it as a record produced a table whose columns were "0", "1".
+          columns: listOf(entity['columns']).map((rawColumn) => {
+            const column = bagOf(rawColumn);
+            return {
+              name: str(column['column'], str(column['property'], 'unknown')),
+              type: str(column['kind'], 'unknown'),
+              nullable: column['notNull'] !== true,
+            };
+          }),
+        };
+      });
+    },
+
+    async drift(): Promise<readonly DriftFact[]> {
+      const { describeEntities } = await import('@ultimat3/entity');
+      return listOf(describeEntities()).flatMap((raw) => {
+        const entity = bagOf(raw);
+        return listOf(entity['drift']).map((rawIssue) => {
+          const issue = bagOf(rawIssue);
+          return {
+            table: str(entity['table'], str(entity['name'])),
+            column: typeof issue['column'] === 'string' ? issue['column'] : null,
+            issue: str(issue['issue'], 'unknown'),
+          };
+        });
+      });
+    },
+
+    runSql: unwired<SqlResult>('runSql', 'db'),
+    mail: unwired<readonly MailFact[]>('mail', 'mail'),
+
+    /**
+     * The tag graph is read through `dependentsOf`, one entity tag at a time: the cache owns
+     * the graph, and /_x asking it per tag keeps the panel honest about what a real
+     * invalidation would reach.
+     */
+    async cacheGraph(): Promise<readonly CacheEdgeFact[]> {
+      const [{ dependentsOf }, { describeEntities }] = await Promise.all([
+        import('@ultimat3/cache'),
+        import('@ultimat3/entity'),
+      ]);
+      return listOf(describeEntities()).map((raw) => {
+        const name = str(bagOf(raw)['name']);
+        return {
+          tag: name,
+          dependents: listOf(dependentsOf([{ entity: name }])).map((rawDep) => {
+            const dep = bagOf(rawDep);
+            return { kind: str(dep['kind']), id: str(dep['id']) };
+          }),
+        };
+      });
+    },
+
+    invalidations: unwired<readonly InvalidationFact[]>('invalidations', 'cache'),
+
+    /**
+     * The matrix is the app's own authz answering, actor by actor and permission by
+     * permission. A panel that re-derived permissions would be a second authz system.
+     */
+    async policyMatrix(): Promise<readonly PolicyFact[]> {
+      const authz = opts.authz;
+      const actors = opts.actors ?? [];
+      if (authz === undefined || actors.length === 0) {
+        // Neither is a `hooks` entry — both are `DevSourceOptions` fields — so the rendered fix
+        // has to spell a real `defaultDevSources({ authz, actors })` call, not the default
+        // `hooks: { <source> }` phrasing (`{ authz + actors }` is not valid syntax).
+        throw new DevSourceUnavailableError({
+          source: 'authz + actors',
+          panel: 'policy',
+          wiring: '{ authz, actors }',
+        });
+      }
+      const { describeActions } = await import('@ultimat3/action');
+      // `ActionDescriptor`'s permission field is named `capability`, not `policy` — reading the
+      // latter answered '' for every action, so the matrix came back empty even when both
+      // `authz` and `actors` were wired correctly.
+      const permissions = [
+        ...new Set(listOf(describeActions()).map((raw) => str(bagOf(raw)['capability']))),
+      ].filter((permission) => permission !== '');
+
+      return actors.flatMap((actor) =>
+        permissions.map((permission) => {
+          const decision = authz.decide({ permission, actor });
+          return {
+            permission,
+            actorId: actor.id,
+            allowed: decision.allowed,
+            trace: decision.trace,
+          };
+        }),
+      );
+    },
+
+    manifest: unwired<ManifestFact>('manifest', 'manifest'),
+  };
+
+  return { ...sources, ...hooks };
+}

package/src/dev/facts.ts

@@ -0,0 +1,180 @@
+// The facts a /_x panel may read: one shape per introspection call. Kept apart from the
+// sources that produce them so a panel imports the shape it renders and nothing else.
+
+export interface RouteFact {
+  readonly path: string;
+  readonly render: string;
+  readonly offline: string;
+  readonly hydrate: string;
+  readonly handler: string;
+  readonly budget: { readonly js?: string; readonly lcp?: number };
+  readonly revalidateTags: readonly string[];
+  readonly hasMeta: boolean;
+}
+
+/**
+ * `http` is the request span itself — the root every other span hangs off. Without it the flame
+ * has no depth-0 row to nest under, and a host would have to file the request under one of the
+ * things it contains.
+ */
+export type SpanKind = 'http' | 'sql' | 'cache' | 'action' | 'policy' | 'job' | 'render';
+
+export interface TimelineSpan {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly kind: SpanKind;
+  readonly name: string;
+  readonly startMs: number;
+  readonly durationMs: number;
+  readonly detail: string;
+}
+
+export interface RequestTrace {
+  readonly requestId: string;
+  readonly method: string;
+  readonly path: string;
+  readonly status: number;
+  readonly startedAt: string;
+  readonly totalMs: number;
+  readonly spans: readonly TimelineSpan[];
+}
+
+export interface LiveSubscriberFact {
+  readonly id: string;
+  readonly query: string;
+  readonly actorId: string;
+  readonly matched: boolean;
+  /** The matcher's decision, line by line. The whole point of the panel. */
+  readonly trace: readonly string[];
+  readonly rows: number;
+  readonly lastDeliveryAt: string | null;
+}
+
+export interface LiveQueryFact {
+  readonly name: string;
+  readonly live: boolean;
+  readonly policy: string;
+  readonly sql: string;
+}
+
+export interface JobDefFact {
+  readonly name: string;
+  readonly queue: string;
+  readonly steps: readonly string[];
+  readonly retry: { readonly attempts: number; readonly backoff: string };
+  readonly idempotent: boolean;
+}
+
+export interface QueueFact {
+  readonly name: string;
+  readonly depth: number;
+  readonly running: number;
+  readonly failed: number;
+  readonly deadLetter: number;
+}
+
+export interface JobStepFact {
+  readonly name: string;
+  readonly status: 'ok' | 'running' | 'failed' | 'sleeping' | 'pending';
+  readonly attempt: number;
+  readonly durationMs: number;
+  readonly error: string | null;
+}
+
+export interface JobRunFact {
+  readonly id: string;
+  readonly job: string;
+  readonly queue: string;
+  readonly status: 'ok' | 'running' | 'failed' | 'dead';
+  readonly attempt: number;
+  readonly steps: readonly JobStepFact[];
+}
+
+export interface TaskFact {
+  readonly name: string;
+  readonly cron: string;
+  readonly tz: string;
+  readonly nextRunAt: string | null;
+}
+
+export interface ColumnFact {
+  readonly name: string;
+  readonly type: string;
+  readonly nullable: boolean;
+}
+
+export interface TableFact {
+  readonly name: string;
+  readonly columns: readonly ColumnFact[];
+}
+
+export interface DriftFact {
+  readonly table: string;
+  readonly column: string | null;
+  readonly issue: string;
+}
+
+export interface SqlResult {
+  readonly columns: readonly string[];
+  readonly rows: readonly (readonly unknown[])[];
+  readonly elapsedMs: number;
+}
+
+export interface MailFact {
+  readonly id: string;
+  readonly to: string;
+  readonly subject: string;
+  readonly locale: string;
+  readonly html: string;
+  readonly text: string;
+  readonly sentAt: string;
+}
+
+export interface CacheEdgeFact {
+  readonly tag: string;
+  readonly dependents: readonly { readonly kind: string; readonly id: string }[];
+}
+
+export interface InvalidationFact {
+  readonly at: string;
+  readonly tags: readonly string[];
+  readonly busted: readonly string[];
+  readonly source: string;
+}
+
+export interface PolicyFact {
+  readonly permission: string;
+  readonly actorId: string;
+  readonly allowed: boolean;
+  readonly trace: readonly string[];
+}
+
+export interface ManifestFact {
+  readonly emitted: unknown;
+  readonly committed: unknown;
+  readonly diff: readonly {
+    readonly path: string;
+    readonly emitted: unknown;
+    readonly committed: unknown;
+  }[];
+}
+
+/** The whole introspection surface /_x is allowed to read. Nothing else is in scope. */
+export interface DevSources {
+  routes(): Promise<readonly RouteFact[]>;
+  traces(): Promise<readonly RequestTrace[]>;
+  liveQueries(): Promise<readonly LiveQueryFact[]>;
+  subscribers(): Promise<readonly LiveSubscriberFact[]>;
+  jobDefs(): Promise<readonly JobDefFact[]>;
+  queues(): Promise<readonly QueueFact[]>;
+  jobRuns(): Promise<readonly JobRunFact[]>;
+  tasks(): Promise<readonly TaskFact[]>;
+  tables(): Promise<readonly TableFact[]>;
+  drift(): Promise<readonly DriftFact[]>;
+  runSql(sql: string): Promise<SqlResult>;
+  mail(): Promise<readonly MailFact[]>;
+  cacheGraph(): Promise<readonly CacheEdgeFact[]>;
+  invalidations(): Promise<readonly InvalidationFact[]>;
+  policyMatrix(): Promise<readonly PolicyFact[]>;
+  manifest(): Promise<ManifestFact>;
+}

package/src/dev/index.ts

@@ -0,0 +1,47 @@
+// The `/_x` dev dashboard's own door, reached as `@ultimat3/admin/dev`.
+//
+// A separate door from the package root on purpose: the CLI's only job here is to MOUNT `/_x`,
+// so it must never pull `src/*`'s production Solid component tree into every `x dev` process.
+
+export { type DevSourceOptions, defaultDevSources, staticDevSources } from './data';
+export type {
+  CacheEdgeFact,
+  ColumnFact,
+  DevSources,
+  DriftFact,
+  InvalidationFact,
+  JobDefFact,
+  JobRunFact,
+  JobStepFact,
+  LiveQueryFact,
+  LiveSubscriberFact,
+  MailFact,
+  ManifestFact,
+  PolicyFact,
+  QueueFact,
+  RequestTrace,
+  RouteFact,
+  SpanKind,
+  SqlResult,
+  TableFact,
+  TaskFact,
+  TimelineSpan,
+} from './facts';
+export { type DevPanel, type PanelPayload, panelPayload } from './panel';
+export { type CachePanelData, cachePanel } from './panel-cache';
+export { assertReadOnly, type DbPanelData, dbPanel } from './panel-db';
+export { type JobsPanelData, jobsPanel } from './panel-jobs';
+export { type LivePanelData, livePanel } from './panel-live';
+export { type MailPanelData, mailPanel } from './panel-mail';
+export { type ManifestPanelData, manifestPanel } from './panel-manifest';
+export { type PolicyPanelData, policyPanel } from './panel-policy';
+export { type RoutesPanelData, routesPanel } from './panel-routes';
+export { type TimelinePanelData, timelinePanel } from './panel-timeline';
+export {
+  assertDevOnly,
+  DEV_BASE_PATH,
+  DEV_PANELS,
+  type DevDashboard,
+  type DevDashboardOptions,
+  devDashboard,
+} from './server';

package/src/dev/panel-cache.ts

@@ -0,0 +1,47 @@
+// Panel: Cache.
+// Kills: "why is this page still stale?" — the tag graph, and the invalidation log showing
+// what busted what.
+
+import type { CacheEdgeFact, InvalidationFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface CachePanelData {
+  readonly graph: readonly CacheEdgeFact[];
+  readonly invalidations: readonly InvalidationFact[];
+  /** Tags nothing depends on: an `invalidates: [tag.x]` that can never bust anything. */
+  readonly orphanTags: readonly string[];
+  /** Dependents per kind — cache keys vs ISR routes vs CDN paths vs live queries. */
+  readonly byKind: Readonly<Record<string, number>>;
+  /** Dependents the log shows actually being busted. The rest are still holding. */
+  readonly bustedRecently: readonly string[];
+  readonly note: string | null;
+}
+
+export const cachePanel: DevPanel<CachePanelData> = {
+  key: 'cache',
+  titleKey: 'dev.panel.cache',
+  question: 'what invalidated what — and why is this still stale?',
+  async data(sources): Promise<CachePanelData> {
+    const graph = await sources.cacheGraph();
+    // The invalidation log needs a running process that has served a write; the graph alone
+    // is still worth showing.
+    const invalidations = await sources
+      .invalidations()
+      .catch((): readonly InvalidationFact[] => []);
+
+    const busted = new Set(invalidations.flatMap((event) => event.busted));
+    const byKind: Record<string, number> = {};
+    for (const edge of graph) {
+      for (const dep of edge.dependents) byKind[dep.kind] = (byKind[dep.kind] ?? 0) + 1;
+    }
+
+    return {
+      graph,
+      invalidations,
+      orphanTags: graph.filter((edge) => edge.dependents.length === 0).map((edge) => edge.tag),
+      byKind,
+      bustedRecently: [...busted].sort(),
+      note: invalidations.length === 0 ? 'dev.cache.no-invalidations-yet' : null,
+    };
+  },
+};

package/src/dev/panel-db.ts

@@ -0,0 +1,59 @@
+// Panel: DB.
+// Kills: "what is actually in the table, and does it match the migrations?" — psql in a tab,
+// read-only by default, plus the schema diff against the migration history.
+
+import type { DriftFact, SqlResult, TableFact } from './facts';
+import type { DevPanel } from './panel';
+
+export interface DbPanelData {
+  readonly tables: readonly TableFact[];
+  readonly drift: readonly DriftFact[];
+  readonly sql: string | null;
+  readonly result: SqlResult | null;
+  /** Set when a statement was refused; the panel shows it instead of a result grid. */
+  readonly refused: string | null;
+  readonly readOnly: boolean;
+}
+
+const WRITE_STATEMENT =
+  /\b(insert|update|delete|drop|alter|truncate|create|grant|revoke|copy|vacuum)\b/i;
+
+/**
+ * Read-only is enforced here, not just in the UI: /_x runs with the developer's own DB
+ * credentials, so "the textarea only sends SELECTs" would be the whole safety story.
+ * `x db psql --write` is the deliberate way out.
+ */
+export function assertReadOnly(sql: string): string | null {
+  const stripped = sql.replace(/--[^\n]*/g, ' ').trim();
+  if (stripped === '') return null;
+  if (WRITE_STATEMENT.test(stripped)) {
+    return `refused: the /_x DB panel is read-only. Run it with: x db psql --write`;
+  }
+  if (!/^(select|with|explain|show|table)\b/i.test(stripped)) {
+    return 'refused: only SELECT / WITH / EXPLAIN / SHOW / TABLE statements run here';
+  }
+  return null;
+}
+
+export const dbPanel: DevPanel<DbPanelData> = {
+  key: 'db',
+  titleKey: 'dev.panel.db',
+  question: 'what is in the table, and does the schema match the migrations?',
+  async data(sources, params): Promise<DbPanelData> {
+    const [tables, drift] = await Promise.all([sources.tables(), sources.drift()]);
+    const sql = params.get('sql');
+    if (sql === null || sql.trim() === '') {
+      return { tables, drift, sql: null, result: null, refused: null, readOnly: true };
+    }
+
+    const refused = assertReadOnly(sql);
+    return {
+      tables,
+      drift,
+      sql,
+      result: refused === null ? await sources.runSql(sql) : null,
+      refused,
+      readOnly: true,
+    };
+  },
+};