@ultimat3/cli 22.15.0 → 24.0.0

package/src/dev-lock.ts

@@ -18,6 +18,7 @@ import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync
 import { join } from 'node:path';
 import { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
+import { portPairAfter } from './flag-number';
 import { quoteArg } from './shell-quote';
 
 /** Where the running dev server records itself, inside the state directory it already owns. */
@@ -220,12 +221,6 @@ export class DevPortInUseError extends UltimateError {
   }
 }
 
-/**
- * The next port to suggest. Never `port + 1` at the top of the range — 65536 is not a port, and a
- * `fix:` that cannot run is the failure this whole module exists to end.
- */
-export const suggestPort = (port: number): number => (port >= 65535 ? port - 1 : port + 1);
-
 /**
  * Is anything listening? A successful bind-then-close is the only answer that does not lie.
  *
@@ -379,7 +374,9 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
     release();
     throw new DevPortInUseError({
       port: input.port,
-      suggestion: suggestPort(input.port),
+      // `portPairAfter`, never `port + 1`: `x dev` binds a PAIR, so the holder is most often
+      // another `x dev` whose sync role already sits on `port + 1`.
+      suggestion: portPairAfter(input.port),
       holder: await (input.holder ?? portHolder)(input.port),
     });
   }

package/src/dev-route-table.ts

@@ -21,6 +21,7 @@ import type { PageSpeculation } from './page-speculation';
 import { loadSpeculation, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
+import { adminMountRoutes } from './runtime-admin';
 import { assetRoutes } from './runtime-assets';
 import { appRoutes } from './runtime-render';
 import { servedStorage, storageRoutes } from './runtime-storage';
@@ -150,6 +151,14 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...sync.routes,
     ...navigation.routes,
     ...pagePostRoutes(),
+    // The app's generated admin, when it declared one (`defineAdmin`): every screen under its base
+    // path, served through the same document builder as the pages below. Nothing for an app with
+    // no admin — the registry is asked, the package is not imported.
+    ...adminMountRoutes({
+      buildId: input.buildId,
+      themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
+    }),
     ...appRoutes({
       buildId: input.buildId,
       ...(input.isr === undefined ? {} : { isr: input.isr }),

package/src/dispatch.ts

@@ -6,9 +6,9 @@ import { isAbsolute, resolve } from 'node:path';
 import { setLogStream } from '@ultimat3/core';
 import { requireAppRoot, requireBunVersion } from './app-root';
 import { createHelpCommand } from './cmd-help';
-import { plannedCommandFor } from './cmd-planned';
+import { plannedCommandError, plannedCommandFor } from './cmd-planned';
 import type { CommandContext } from './command';
-import { CliNotImplementedError, UnknownCommandError } from './errors';
+import { UnknownCommandError } from './errors';
 import type { Runner } from './exec';
 import { exec } from './exec';
 import type { CommandResult } from './output';
@@ -91,10 +91,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     // X_NOT_IMPLEMENTED with a runnable fix. Substituted here rather than in `parse.ts`, which is
     // pure and knows nothing about what a command means; the precedent is the help swap below.
     const planned = plannedCommandFor(commandFor(options.argv[0] ?? '')?.spec.name);
-    const failure =
-      planned === undefined
-        ? error
-        : new CliNotImplementedError({ feature: `x ${planned.name}`, fix: planned.fix });
+    const failure = planned === undefined ? error : plannedCommandError(planned);
     // `wantsJson`, not `includes('--json')`: a typo'd flag or a typo'd command is exactly the case
     // an agent hits while always passing `-j`, and the short form rendered prose it then parsed.
     const result = errorResult(planned?.name ?? 'x', failure);

package/src/doctor-app-url.ts

@@ -0,0 +1,39 @@
+// `x doctor`'s APP_URL rule, pure: a set APP_URL must be an origin a browser can match, and a
+// loopback one must name the port `x dev` serves on — OAuth's redirect, absolute links and the sync
+// node's admitted origin all read it, and a laptop origin on another port reaches another server.
+
+import { ERROR_DOCS_URL, renderFixShellArg } from '@ultimat3/core';
+import { isLoopbackHostname } from './loopback-host';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { syncOriginsFrom } from './sync-url';
+
+/**
+ * Unset is no finding: `x dev` serves without one, and a production build warns on its own
+ * (`originWarning`). A public origin is not judged against the dev port — that is the deploy's
+ * address, not this machine's. The parse is the sync boot's own (`syncOriginsFrom`), so doctor
+ * refuses exactly the values the boot would.
+ */
+export function appUrlFindings(raw: string | undefined, port: number): readonly Finding[] {
+  let origins: readonly string[];
+  try {
+    origins = syncOriginsFrom({ APP_URL: raw });
+  } catch (error) {
+    return [findingFrom(error)];
+  }
+  const origin = origins[0];
+  if (origin === undefined) return [];
+  const url = new URL(origin);
+  if (!isLoopbackHostname(url.hostname)) return [];
+  const declared = url.port === '' ? (url.protocol === 'https:' ? 443 : 80) : Number(url.port);
+  if (declared === port) return [];
+  const wanted = `${url.protocol}//${url.hostname}:${String(port)}`;
+  return [
+    {
+      code: 'X_APP_URL_PORT_MISMATCH',
+      cause: `APP_URL is ${origin}, but x dev serves this app on port ${String(port)} — OAuth redirects, absolute links and the sync origin would point at another server`,
+      fix: `export APP_URL=${renderFixShellArg(wanted, 'http://localhost:3000')}`,
+      docs: ERROR_DOCS_URL,
+    },
+  ];
+}

package/src/doctor-auth.ts

@@ -0,0 +1,95 @@
+// `x doctor`'s auth-storage checks: what an upgrade leaves in the database for an operator to
+// finish — second-factor secrets written before they were sealed, and a framework table no
+// release reads any more. Reaching the server is `authStorageProbe`, deciding is
+// `authStorageFindings` — the split `doctor-sealed.ts` makes.
+
+import { BuiltinAdapter, countUnsealedMfaSecrets } from '@ultimat3/auth';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { createPostgresClient, raw } from '@ultimat3/db';
+import type { Finding } from './output';
+
+/**
+ * Framework tables an earlier release created and none reads now, each with the command that
+ * removes it. The boot never drops one: a replica still on the previous release may be using it
+ * for the length of a rolling deploy. A whole literal per table — nothing is spliced into a fix.
+ */
+type RetiredTable = 'x_auth_failures';
+
+// A Map, not an object: a table name is looked up by key, and an object answers `constructor`.
+const RETIRED_TABLE_FIXES: ReadonlyMap<RetiredTable, string> = new Map([
+  [
+    'x_auth_failures',
+    `psql "$DATABASE_URL" -c 'drop table if exists x_auth_failures'   # once every replica runs this release`,
+  ],
+]);
+
+export const RETIRED_FRAMEWORK_TABLES: readonly RetiredTable[] = Object.freeze([
+  ...RETIRED_TABLE_FIXES.keys(),
+]);
+
+export interface AuthStorageFact {
+  /** `x_users` rows holding an `mfa_secret` that is not sealed. */
+  readonly unsealedMfaSecrets: number;
+  /** Which of `RETIRED_FRAMEWORK_TABLES` are still present. */
+  readonly retiredTables: readonly RetiredTable[];
+}
+
+/** What a database that was not asked — embedded, or unreachable — answers: nothing to report. */
+export const NO_AUTH_STORAGE_FACT: AuthStorageFact = Object.freeze({
+  unsealedMfaSecrets: 0,
+  retiredTables: Object.freeze([]),
+});
+
+/** The rule, pure. */
+export function authStorageFindings(fact: AuthStorageFact): readonly Finding[] {
+  const findings: Finding[] = [];
+  if (fact.unsealedMfaSecrets > 0) {
+    findings.push({
+      code: 'X_MFA_SECRET_UNSEALED',
+      cause: `${fact.unsealedMfaSecrets} user(s) hold a second-factor secret that is not sealed; the framework never reads a plaintext secret, so each of them is refused at the second factor until it is sealed`,
+      fix: 'x auth seal-mfa --json',
+      docs: ERROR_DOCS_URL,
+    });
+  }
+  for (const table of fact.retiredTables) {
+    const fix = RETIRED_TABLE_FIXES.get(table);
+    if (fix === undefined) continue;
+    findings.push({
+      code: 'X_FRAMEWORK_TABLE_ORPHANED',
+      cause: `${table} is still in the database and no release reads it any more; the boot does not drop it, because a replica on the previous release may still be writing to it during a rolling deploy`,
+      fix,
+      docs: ERROR_DOCS_URL,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Asks an EXTERNAL database only — `probeDatabase`'s own rule: opening the embedded one boots
+ * PGlite and takes the single-writer lock the next command needs. A server that does not answer
+ * is `database()`'s finding to make, so every failure here is "nothing to report".
+ */
+export async function authStorageProbe(url: string | undefined): Promise<AuthStorageFact> {
+  if (url === undefined || url.trim() === '') return NO_AUTH_STORAGE_FACT;
+  const client = createPostgresClient({ url, applicationName: 'x-doctor' });
+  try {
+    const present = async (table: string): Promise<boolean> => {
+      const rows = await client.query<{ readonly present: boolean }>(
+        raw(`select to_regclass('public.${table}') is not null as present`),
+      );
+      return rows[0]?.present === true;
+    };
+    const retiredTables: RetiredTable[] = [];
+    for (const table of RETIRED_FRAMEWORK_TABLES) {
+      if (await present(table)) retiredTables.push(table);
+    }
+    const unsealedMfaSecrets = (await present('x_users'))
+      ? await countUnsealedMfaSecrets({ adapter: new BuiltinAdapter(client) })
+      : 0;
+    return { unsealedMfaSecrets, retiredTables };
+  } catch {
+    return NO_AUTH_STORAGE_FACT;
+  } finally {
+    await client.close();
+  }
+}

package/src/doctor-coverage.ts

@@ -0,0 +1,39 @@
+// `x doctor`'s coverage listing: every file the app's coverage floor does not see, and the reason
+// `x.verify.json` gives for each. A LISTING, never a finding: an `exclude` with its `why` is a
+// decision the app made in a committed file — printing it is what keeps the decision in view, and
+// a red `x doctor` over it would be the framework overruling what it asked to be written down.
+
+import type { CoverageExclude } from './coverage-floor';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { readVerifyFloor } from './verify-floor';
+
+/** The I/O half: the excludes this app's `x.verify.json` states. None when it states no floor. */
+export async function coverageExcludesProbe(root: string): Promise<readonly CoverageExclude[]> {
+  return (await readVerifyFloor(root))?.coverage?.exclude ?? [];
+}
+
+/**
+ * The listing, on a result `x doctor` already decided: `data.coverage.exclude` for a machine, one
+ * line per entry for a person. `ok`, the summary and the findings are returned as they came.
+ */
+export function withCoverageExcludes(
+  result: CommandResult,
+  exclude: readonly CoverageExclude[],
+): CommandResult {
+  const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
+  const listed: JsonValue = exclude.map(({ glob, why }) => ({ glob, why }));
+  return {
+    ...result,
+    data: { ...(data as Record<string, JsonValue>), coverage: { exclude: listed } },
+    ...(exclude.length === 0
+      ? {}
+      : {
+          lines: [
+            ...(result.lines ?? []),
+            msg('cli.doctor.coverageExclude', { count: exclude.length }),
+            ...exclude.map(({ glob, why }) => `  ${glob} — ${why}`),
+          ],
+        }),
+  };
+}

package/src/doctor-guards.ts

@@ -0,0 +1,54 @@
+// `x doctor`'s guard listing: the guards the framework ships that this app's `guards/` does not
+// hold, each with the command that adds it. A LISTING, never a finding: every shipped guard says
+// "delete this file to drop the rule", so an app without one may have decided — and a red
+// `x doctor` over a decision would be the framework overruling the convention it handed over.
+
+import { GUARD_DIR, guardPaths } from './guards';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { SHIPPED_GUARD_NAMES } from './templates/scaffold-guards';
+
+export interface MissingGuard {
+  readonly name: string;
+  /** The command that writes it, with its test. Then `x verify` says what it finds. */
+  readonly add: string;
+}
+
+/** The rule, pure: which shipped names have no file among the guards an app holds. */
+export function missingShippedGuards(present: readonly string[]): readonly MissingGuard[] {
+  const held = new Set(present.map((path) => path.replace(/\.tsx?$/, '')));
+  return SHIPPED_GUARD_NAMES.filter((name) => !held.has(`${GUARD_DIR}/${name}`)).map((name) => ({
+    name,
+    add: `x g guard ${name}`,
+  }));
+}
+
+/** The I/O half: the same enumeration the `boundaries` step runs, so the two cannot disagree. */
+export async function shippedGuardsProbe(root: string): Promise<readonly MissingGuard[]> {
+  return missingShippedGuards(await guardPaths(root));
+}
+
+/**
+ * The listing, on a result `x doctor` already decided: `data.guards.missing` for a machine, one
+ * line per command for a person. `ok`, the summary and the findings are returned as they came.
+ */
+export function withGuardListing(
+  result: CommandResult,
+  missing: readonly MissingGuard[],
+): CommandResult {
+  const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
+  const listed: JsonValue = missing.map(({ name, add }) => ({ name, add }));
+  return {
+    ...result,
+    data: { ...(data as Record<string, JsonValue>), guards: { missing: listed } },
+    ...(missing.length === 0
+      ? {}
+      : {
+          lines: [
+            ...(result.lines ?? []),
+            msg('cli.doctor.guards', { count: missing.length }),
+            ...missing.map(({ add }) => `  ${add}`),
+          ],
+        }),
+  };
+}

package/src/doctor-sealed.ts

@@ -0,0 +1,132 @@
+// `x doctor`'s sealed-column checks: the columns the app declared `.sealed()`, against the master
+// keys this environment declares. Its own file for `doctor-offline.ts`'s reason — answering needs
+// the app's entities and the committed secrets, and `cmd-doctor.ts`'s job is the probe. The split
+// is the same too: reaching the disk is `sealedKeysProbe`, deciding is `sealedKeyFindings`.
+
+import {
+  ERROR_DOCS_URL,
+  findMasterKey,
+  readSecretsFile,
+  SECRETS_RETIRED_KEYS_ENV,
+  sealKeyIds,
+  secretsFileExists,
+} from '@ultimat3/core';
+import { registeredEntities, sealedFields } from '@ultimat3/entity';
+import { loadApp } from './app-load';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+export interface SealedColumnFact {
+  readonly entity: string;
+  /** Property key, as the entity declares it. */
+  readonly column: string;
+  readonly lookup: boolean;
+}
+
+export interface SealedKeysFact {
+  /**
+   * Every sealed column the app declares, or `undefined` when the app would not load — a short
+   * registry reads as "no sealed columns", which is the false green `appEntities` exists to refuse.
+   */
+  readonly columns: readonly SealedColumnFact[] | undefined;
+  /** The key ids in force, or `undefined` when no usable master key was found. */
+  readonly keys: { readonly current: string; readonly retired: readonly string[] } | undefined;
+}
+
+const named = (columns: readonly SealedColumnFact[]): string =>
+  columns.map((one) => `${one.entity}.${one.column}`).join(', ');
+
+/**
+ * The rule, pure. Two conditions, and an app with no sealed column is judged by neither.
+ *
+ * No key: every write to a sealed column is `X_SEAL_KEY_MISSING` — core's own code and its own
+ * fix, reported here before the first request finds out.
+ *
+ * A retired key still declared: a rotation whose re-seal has not finished. That is a live-system
+ * state and not a fault, but it has a cost that ends only when someone acts — a `lookup` column
+ * matches through `in (…)` over every key and its `.unique()` holds per key — so it is a finding
+ * until the retired key is dropped.
+ */
+export function sealedKeyFindings(fact: SealedKeysFact): readonly Finding[] {
+  const columns = fact.columns;
+  if (columns === undefined || columns.length === 0) return [];
+  if (fact.keys === undefined) {
+    return [
+      {
+        code: 'X_SEAL_KEY_MISSING',
+        cause: `${named(columns)} ${columns.length === 1 ? 'is' : 'are'} sealed and this environment has no usable master key, so every write to ${columns.length === 1 ? 'it' : 'them'} is refused`,
+        fix: 'x secrets init   # or, where the key already exists: export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"',
+        docs: ERROR_DOCS_URL,
+      },
+    ];
+  }
+  const [oldest] = fact.keys.retired;
+  if (oldest === undefined) return [];
+  const lookups = columns.filter((one) => one.lookup);
+  const weakened =
+    lookups.length === 0
+      ? ''
+      : ` — ${named(lookups)} ${lookups.length === 1 ? 'is a lookup column' : 'are lookup columns'}, so until then equality reads through in (…) over every key and .unique() holds per key`;
+  return [
+    {
+      code: 'X_SEAL_RESEAL_PENDING',
+      cause: `${named(columns)} may still hold values sealed under retired master key(s) ${fact.keys.retired.join(', ')}: a rotation whose re-seal has not finished${weakened}`,
+      // The id is 16 hex characters computed here from a key, never text read from a file.
+      fix: `x secrets rotate --drop ${quoteArg(oldest)} --json   # AFTER a backfill() has rewritten every row — update(id, { column: row.column }) seals under the current key`,
+      docs: ERROR_DOCS_URL,
+    },
+  ];
+}
+
+/**
+ * The retired ring as a booted process would see it: the real environment first, the committed
+ * file second — `installSecrets()`'s own order, without installing anything into this process.
+ */
+async function retiredRing(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<string | undefined> {
+  const declared = env[SECRETS_RETIRED_KEYS_ENV];
+  if (declared !== undefined && declared !== '') return declared;
+  const key = findMasterKey(root, { ...env });
+  if (key === undefined || !secretsFileExists(root)) return undefined;
+  return (await readSecretsFile(root, key))[SECRETS_RETIRED_KEYS_ENV];
+}
+
+/** The app's sealed columns, or `undefined` when it would not load. */
+export type DeclaredSealedColumns = (
+  root: string,
+) => Promise<readonly SealedColumnFact[] | undefined>;
+
+/** `appEntities`' rule (`schema-drift.ts`): a registry short one module is not "none declared". */
+const appSealedColumns: DeclaredSealedColumns = async (root) => {
+  const app = await loadApp(root);
+  if (app.findings.length > 0) return undefined;
+  return registeredEntities().flatMap((entry) =>
+    // `core` is absent on a hand-registered entry, which declares no columns to seal.
+    (entry.core === undefined ? [] : sealedFields(entry.core)).map((field) => ({
+      entity: entry.name,
+      column: field.property,
+      lookup: field.lookup,
+    })),
+  );
+};
+
+export async function sealedKeysProbe(
+  root: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  declared: DeclaredSealedColumns = appSealedColumns,
+): Promise<SealedKeysFact> {
+  const columns = await declared(root);
+  // No sealed column means no question about keys, and no reason to open the secrets file.
+  if (columns === undefined || columns.length === 0) return { columns, keys: undefined };
+  try {
+    const ring = await retiredRing(root, env);
+    const source = { ...env, ...(ring === undefined ? {} : { [SECRETS_RETIRED_KEYS_ENV]: ring }) };
+    return { columns, keys: await sealKeyIds({ root, env: source }) };
+  } catch {
+    // Whatever refused — no key, a malformed one, a secrets file this key does not open — the
+    // answer for a sealed column is the same: there is no key ring to seal under.
+    return { columns, keys: undefined };
+  }
+}

package/src/document-graph.ts

@@ -0,0 +1,82 @@
+// Whether importing an app module would bring a DOCUMENT module into this process: a component
+// (`.tsx`) or a stylesheet. A role that renders nothing asks this before each import
+// (`role-load.ts`), so a worker never compiles the app's Sass or evaluates its pages to learn that
+// they register no job.
+
+import { resolvedImports } from './module-imports';
+import { hasPathSegment } from './path-segments';
+
+/** A component or a stylesheet: what only a process that renders documents evaluates. */
+const DOCUMENT = /\.(?:[jt]sx|s[ac]ss|css)$/;
+
+export const isDocumentModule = (path: string): boolean => DOCUMENT.test(path);
+
+/** An installed framework package, under either linker: `…/node_modules/@ultimat3/<pkg>/…`. */
+const FRAMEWORK_SCOPE = '/node_modules/@ultimat3/';
+
+export interface DocumentGraph {
+  /**
+   * True when importing `absolute` would evaluate a document module this process has not already
+   * loaded. Errs toward `false`: a specifier that will not resolve and a file that will not parse
+   * contribute no edge, so the caller imports the module and the import itself reports the fault.
+   */
+  reachesDocument(absolute: string): Promise<boolean>;
+}
+
+/**
+ * `loaded` answers whether a module is already in this process — a module the API index imported
+ * costs nothing more, whatever it reaches, so the walk stops there. Injected, so a test decides it.
+ */
+export function createDocumentGraph(loaded: (absolute: string) => boolean): DocumentGraph {
+  const edges = new Map<string, readonly string[]>();
+  const verdicts = new Map<string, boolean>();
+
+  /**
+   * The files importing `path` evaluates, when the walk follows them: the app's own modules and
+   * the framework's — `@ultimat3/ui` is a barrel of components, and an app module importing it
+   * brings every one of them and their Sass. A third-party package is not walked: it ships no
+   * component this framework's loader compiles. A lazy import's target is no edge at all.
+   */
+  async function importsOf(path: string): Promise<readonly string[]> {
+    const known = edges.get(path);
+    if (known !== undefined) return known;
+    // Unreadable: no edge, and the caller's own import is what reports it.
+    const source = await Bun.file(path)
+      .text()
+      .catch(() => '');
+    const found = resolvedImports(path, source, 'evaluated').filter(
+      (target) => !hasPathSegment(target, 'node_modules') || target.includes(FRAMEWORK_SCOPE),
+    );
+    edges.set(path, found);
+    return found;
+  }
+
+  return {
+    async reachesDocument(absolute: string): Promise<boolean> {
+      const known = verdicts.get(absolute);
+      if (known !== undefined) return known;
+      // The whole reachable set, never a per-node recursion: inside an import cycle a node's own
+      // answer depends on one still being computed, and a `false` memoised there is wrong.
+      const seen = new Set<string>();
+      const stack = [absolute];
+      let reaches = false;
+      while (stack.length > 0 && !reaches) {
+        const path = stack.pop();
+        if (path === undefined || seen.has(path)) continue;
+        seen.add(path);
+        if (verdicts.get(path) === true || (isDocumentModule(path) && !loaded(path))) {
+          reaches = true;
+          break;
+        }
+        // Already here, or already cleared: nothing below it is new to this process.
+        if (isDocumentModule(path) || loaded(path) || verdicts.get(path) === false) continue;
+        stack.push(...(await importsOf(path)));
+      }
+      // A clean walk clears everything it visited — each one's reachable set is inside this one's.
+      // A walk that found a document proves it for the start alone.
+      if (reaches) verdicts.set(absolute, true);
+      else for (const path of seen) verdicts.set(path, false);
+      return reaches;
+    },
+  };
+}

package/src/drift-replica-identity.ts

@@ -0,0 +1,42 @@
+// Single responsibility: which declared tables the drift step expects a migration to have made
+// `REPLICA IDENTITY FULL` — the same set `x db gen` emits the ALTER for (`replicaIdentityTables`),
+// or that command's own refusal as a finding. A tier-3 fact no entity carries, so no source hash
+// moves when a channel with params is added over a table that already exists.
+
+import { describeQueries } from '@ultimat3/query';
+import { QuerySubscribesUnknownError, replicaIdentityTables } from './db-subscribes';
+import { MIGRATIONS_DIR } from './migrations';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** The tables needing FULL, given the tables the app's entities declare. Injected for tests. */
+export type ReplicaIdentityWanted = (tables: ReadonlySet<string>) => readonly string[];
+
+/**
+ * The app's own answer: its live queries' `subscribes:` plus every params channel's `records`
+ * tables, read off the registries `loadApp` filled. One function with `db-generate.ts`, so the gate
+ * can never expect an identity the generator would not grant, or miss one it would.
+ */
+export const appReplicaIdentity: ReplicaIdentityWanted = (tables) =>
+  replicaIdentityTables(describeQueries(), tables);
+
+export type WantedIdentity =
+  | { readonly tables: ReadonlySet<string> }
+  | { readonly finding: Finding };
+
+/**
+ * `x db gen` refuses a `subscribes:` name no entity declares (`X_QUERY_SUBSCRIBES_UNKNOWN`), and the
+ * gate reports the same refusal rather than letting it escape the step: every other throw is a
+ * defect in this process and is rethrown as one.
+ */
+export function wantedReplicaIdentity(
+  wanted: ReplicaIdentityWanted,
+  tables: ReadonlySet<string>,
+): WantedIdentity {
+  try {
+    return { tables: new Set(wanted(tables)) };
+  } catch (error) {
+    if (!(error instanceof QuerySubscribesUnknownError)) throw error;
+    return { finding: { ...findingFrom(error), at: MIGRATIONS_DIR } };
+  }
+}

package/src/error-catalog.ts

@@ -46,21 +46,18 @@ export const CATALOG_PACKAGES = [
 ] as const;
 
 /**
- * The packages the catalog may import WITHOUT `@ultimat3/cli` declaring them. `admin` and `ui`
- * reach for a JSX runtime an app has and a bare CLI process does not, so a hard dependency would
- * make the CLI uninstallable where the codes are merely absent today. `scraping` is an app's own
- * choice since 22.0.0: `x shot` drives Chrome over raw CDP and imports nothing from it, so its codes
+ * The packages the catalog may import WITHOUT `@ultimat3/cli` declaring them — never one it does
+ * declare (`error-catalog.test.ts`), which is why `admin` is not here: `x dev` imports it and
+ * `package.json` depends on it. `ui` reaches the CLI only as `admin`'s own dependency, so an
+ * installer that keeps transitive packages private reports its codes `unavailable` rather than
+ * the CLI declaring a package no command imports. `scraping` is an app's own choice since 22.0.0: `x shot` drives Chrome over raw CDP and imports nothing from it, so its codes
  * answer where the app installed it and are reported `unavailable` where it did not. Every other
  * entry above is a real runtime import and must be a declared dependency — `error-catalog.test.ts`
  * holds the list to exactly that, because an undeclared one resolves through workspace symlinks
  * here and through nothing in an installed app, where `x errors explain X_FLAG_EXPIRED` then
  * refuses a code the wiki promises.
  */
-export const CATALOG_OPTIONAL_HOSTS: readonly string[] = [
-  '@ultimat3/admin',
-  '@ultimat3/scraping',
-  '@ultimat3/ui',
-];
+export const CATALOG_OPTIONAL_HOSTS: readonly string[] = ['@ultimat3/scraping', '@ultimat3/ui'];
 
 export interface ErrorCatalog {
   /** Packages whose codes are now registered. */