@ultimat3/cli 23.0.0 → 25.0.0

package/src/exec.ts

@@ -32,6 +32,12 @@ export interface ExecOptions {
    */
   readonly env?: Readonly<Record<string, string | undefined>>;
   readonly stdin?: string;
+  /**
+   * Told the child's pid the moment it exists. A gate step's deadline records it here
+   * (`verify-deadline.ts`): on Windows no process's environment is readable, so the tag sweep
+   * finds nothing and the pid recorded at spawn is the only handle on what the step started.
+   */
+  readonly onSpawn?: (pid: number) => void;
 }
 
 export type Runner = (command: readonly string[], options: ExecOptions) => Promise<ExecResult>;
@@ -112,6 +118,8 @@ export const exec: Runner = async (command, options) => {
     });
   }
   const proc = spawnOrRefuse([head, ...rest], options);
+  // Outside the refusal: a throwing observer is the caller's bug, never "could not run".
+  options.onSpawn?.(proc.pid);
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),

package/src/favicon.ts

@@ -7,7 +7,7 @@
 // it against the root is string work no `Bun.file` overload does — the same necessity
 // `runtime-assets.ts` records for `ICON_SOURCE`.
 import { join } from 'node:path';
-import { createRaster, encodeImage } from '@ultimat3/core';
+import { blankRaster, encodeImage } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 
@@ -47,7 +47,7 @@ const FAVICON_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
  * is a third rung under a mechanism that has exactly two.
  */
 export function defaultFavicon(): Uint8Array {
-  const raster = createRaster(DEFAULT_SIZE, DEFAULT_SIZE, 'favicon');
+  const raster = blankRaster(DEFAULT_SIZE, DEFAULT_SIZE, 'favicon');
   const { pixels } = raster;
   for (let i = 0; i < pixels.length; i += 4) {
     pixels[i] = MARK_LEVEL;

package/src/fix-command.ts

@@ -91,7 +91,15 @@ export interface FixCitation {
  * names two commands (`x db migrate, then confirm with x db query "…" --json`), and charging the
  * second command's flags to the first would report a finding on the wrong half of the sentence.
  */
-export function fixCitations(fix: string): readonly FixCitation[] {
+/**
+ * The repo's in-repo spelling of the CLI, `bun run x -- <command>`, read as the citation it is —
+ * `x <command>` — so a fix written the way CLAUDE.md prescribes is resolved, not skipped.
+ */
+export const asXCitation = (text: string): string =>
+  text.replace(/(^|[\s;|&("'`])bun\s+run\s+x\s+--(?=\s)/g, '$1x');
+
+export function fixCitations(written: string): readonly FixCitation[] {
+  const fix = asXCitation(written);
   const matches = [...fix.matchAll(CITATION)].filter((match) => match[1] !== undefined);
   return matches.map((match, index) => {
     const start = match.index + match[0].length;

package/src/framework-env.ts

@@ -0,0 +1,148 @@
+// Single responsibility: the keys the FRAMEWORK refuses to boot without once deployed — the one
+// list `.env.example`, `x env check` and `x doctor` all read. An app's `envSchema` names its own
+// variables; these are the framework's, and a deploy contract that omits them crash-loops every
+// role one key at a time (#679).
+
+import type { EnvSchema } from '@ultimat3/core';
+import {
+  CURSOR_SECRET_FIX,
+  CURSOR_SECRET_KEY,
+  devSecretsRefused,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  renderEnvExample,
+  tryResolveEnvironment,
+  usesDevCursorSecret,
+} from '@ultimat3/core';
+import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
+import type { Finding } from './output';
+import { storageIsExternal } from './runtime-bindings';
+
+type EnvTable = Readonly<Record<string, string | undefined>>;
+
+/**
+ * Does a process booting on `env` refuse the shipped development secrets? Core's
+ * `devSecretsRefused` — the boot's own rule, which fails closed: a table naming no environment is
+ * production. The ONE predicate `x env check` and `x doctor` gate on, so neither can call green an
+ * environment the boot refuses. Throws `X_ENVIRONMENT_INVALID` on an unknown `ULTIMATE_ENV`.
+ */
+export const deployed = (env: EnvTable): boolean => devSecretsRefused({ env });
+
+/**
+ * Does `env` NAME a deployed environment — `ULTIMATE_ENV`, else `NODE_ENV`, resolving to
+ * `staging` or `production`? `x doctor`'s gate, and deliberately not `deployed`: the two commands
+ * answer different questions. `x env check` asks what a deployed boot does with a table, and the
+ * boot fails closed, so an unnamed table is a deploy there. `x doctor` asks about THIS machine,
+ * and a developer shell that names nothing is not a deploy — reporting the shipped keys there would
+ * put two findings in front of every developer on day one. An unknown `ULTIMATE_ENV` names
+ * nothing (`tryResolveEnvironment`): the boot refuses it first, and doctor must not crash on it.
+ */
+export const namedDeployed = (env: EnvTable): boolean => {
+  const environment = tryResolveEnvironment({ env });
+  return environment === 'staging' || environment === 'production';
+};
+
+/** One framework secret: what refuses without it, when it is needed, and the command that mints one. */
+export interface FrameworkSecret {
+  readonly key: string;
+  /** The diagnostic code `x doctor` and `x env check` report it under. */
+  readonly code: 'X_CURSOR_SECRET_DEV' | 'X_STORAGE_SECRET_DEV';
+  /** Why the framework needs it, one line, rendered into `.env.example`. */
+  readonly why: string;
+  /** When the key is needed at all, if not always — rendered beside `why`. */
+  readonly condition?: string;
+  readonly cause: string;
+  /** Pasted into a shell, so it is a literal command and never a paraphrase. */
+  readonly fix: string;
+  /** False when this deploy's shape never reads the key (object storage configured). */
+  needed(env: EnvTable): boolean;
+  /** True while the table would leave the process signing with the shipped development key. */
+  unsafe(env: EnvTable): boolean;
+}
+
+/** In declaration order — the order `.env.example` renders them in. */
+export const FRAMEWORK_SECRETS: readonly FrameworkSecret[] = [
+  {
+    key: CURSOR_SECRET_KEY,
+    code: 'X_CURSOR_SECRET_DEV',
+    why: 'Signs pagination cursors. Unset, every role refuses to boot (X_CURSOR_SECRET_DEV).',
+    cause:
+      'cursors are signed with the shipped development key, so a client can forge a page position',
+    // Core's, verbatim: the boot's own refusal prints this line for this code.
+    fix: CURSOR_SECRET_FIX,
+    needed: () => true,
+    unsafe: (env) => usesDevCursorSecret({ env }),
+  },
+  {
+    key: STORAGE_SIGNING_SECRET_KEY,
+    code: 'X_STORAGE_SECRET_DEV',
+    why: 'Signs upload grants on the embedded disk. Unset, every role refuses to boot (X_ENV_MISSING).',
+    condition: 'Not read when S3_ENDPOINT and S3_BUCKET select object storage.',
+    cause: `${STORAGE_SIGNING_SECRET_KEY} is unset or holds the shipped development key, so a local-disk deploy would accept forged upload grants that override its own uploadPolicy`,
+    fix: `export ${STORAGE_SIGNING_SECRET_KEY}="$(openssl rand -hex 32)"`,
+    // The boot's own storage choice (`runtime-bindings.ts`), never restated. NOT "the app declares
+    // no storage": the boot builds its disk before any app module loads, and an app reaches it
+    // through a bare `disk()` with no `defineStorage` of its own
+    // (`examples/dummy/apps/web/app/orgs/avatar.ts`), so there is no declaration to read.
+    needed: (env) => !storageIsExternal(env),
+    unsafe: (env) => usesDevStorageSecret({ env }),
+  },
+];
+
+/** The doctor/check finding for one secret — one wording per condition, wherever it is reported. */
+export function frameworkSecretFinding(secret: FrameworkSecret): Finding {
+  return { code: secret.code, cause: secret.cause, fix: secret.fix, docs: ERROR_DOCS_URL };
+}
+
+/** Every secret this table's deploy shape needs and lacks, ungated. */
+const owedFindings = (env: EnvTable, skip: ReadonlySet<string>): readonly Finding[] =>
+  FRAMEWORK_SECRETS.filter(
+    (secret) => !skip.has(secret.key) && secret.needed(env) && secret.unsafe(env),
+  ).map((secret) => ({ ...frameworkSecretFinding(secret), at: ENV_EXAMPLE_PATH }));
+
+/**
+ * `x env check`'s: what a process booting on this table would refuse — gated by `deployed`, the
+ * boot's rule, so an unnamed table owes what production owes. `skip` names keys the caller already
+ * reported under another code, so one key is one finding. Throws `X_ENVIRONMENT_INVALID` on an
+ * unknown `ULTIMATE_ENV`, as the boot does.
+ */
+export function frameworkSecretFindings(
+  env: EnvTable,
+  skip: ReadonlySet<string> = new Set(),
+): readonly Finding[] {
+  return deployed(env) ? owedFindings(env, skip) : [];
+}
+
+/** `x doctor`'s: the same list and wording, gated by `namedDeployed` — this machine, as named. */
+export function machineSecretFindings(env: EnvTable): readonly Finding[] {
+  return namedDeployed(env) ? owedFindings(env, new Set()) : [];
+}
+
+/**
+ * The framework's section of `.env.example`, after the app's own. A key the app's schema already
+ * declares is skipped: one key, one line, and the app's declaration is the one it validates.
+ * Blank values only — these are secrets, and this file is committed.
+ */
+function frameworkSection(schema: EnvSchema): string {
+  const owed = FRAMEWORK_SECRETS.filter((secret) => !Object.hasOwn(schema, secret.key));
+  if (owed.length === 0) return '';
+  const lines = [
+    '',
+    '# --- Framework ---------------------------------------------------------------',
+    '# Required outside development/test, whatever envSchema declares. Generate each with',
+    '# `openssl rand -hex 32`; `x env check` and `x doctor` report one that is missing.',
+  ];
+  for (const secret of owed) {
+    lines.push('', `# ${secret.why}`);
+    if (secret.condition !== undefined) lines.push(`# ${secret.condition}`);
+    lines.push('# required when deployed · string · secret', `${secret.key}=`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * The bytes `.env.example` must hold: the app's declaration, then the framework's keys. The ONE
+ * renderer `x env example`, the drift gate and `x new` share, so the three cannot disagree.
+ */
+export const appEnvExample = (schema: EnvSchema): string =>
+  `${renderEnvExample(schema)}${frameworkSection(schema)}`;

package/src/framework-schema-apply.ts

@@ -0,0 +1,78 @@
+// The two ways a boot meets the framework schema (plan 101, s1-con #5): `applyLockedSchema` runs the
+// DDL in ONE transaction behind the migration advisory lock with a bounded `lock_timeout`, then
+// stamps the build; `verifySchema` runs no DDL and refuses a database this build was never applied
+// to. Which boot takes which is `runtime-queue.ts`'s `SchemaMode`.
+
+import { frameworkVersion, logger } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import {
+  literal,
+  MIGRATION_LOCK_KEY,
+  MIGRATION_LOCK_WAIT_MS,
+  poolProfileFor,
+  raw,
+  withTransaction,
+} from '@ultimat3/db';
+import { applyFrameworkSchema } from './framework-schema';
+import {
+  FrameworkSchemaUnappliedError,
+  frameworkSchemaHash,
+  nextStamp,
+  parseStamp,
+  STAMP_RELATION,
+  type StampEntry,
+  stampVerdict,
+} from './framework-schema-stamp';
+
+const thisBuild = (): StampEntry => ({
+  version: frameworkVersion(),
+  schema: frameworkSchemaHash(),
+});
+
+/** The stamp as the catalog holds it; `null` when the relation or its comment is absent. */
+async function readStamp(client: DbClient): Promise<string | null> {
+  const rows = await client.query<{ readonly stamp: string | null }>(
+    raw(`select obj_description(to_regclass('${STAMP_RELATION}'), 'pg_class') as stamp`),
+  );
+  return rows[0]?.stamp ?? null;
+}
+
+/**
+ * The migration lock, not a lock of its own: a second migrator — another `ROLE=migrate` pod, an
+ * `x db migrate` — waits behind this one instead of racing its `create table`s into `23505`. A
+ * transaction-scoped lock (`pg_advisory_xact_lock`), so no pinned session: COMMIT releases it.
+ *
+ * Two `lock_timeout`s: the lock wait is the migrator's own (`MIGRATION_LOCK_WAIT_MS`), and every
+ * DDL statement after it is the migrate pool's (`poolProfileFor('migrate')`), so an `alter table`
+ * behind an open transaction fails in seconds rather than queueing every enqueue behind it.
+ */
+export async function applyLockedSchema(client: DbClient): Promise<void> {
+  await withTransaction(
+    async (tx) => {
+      await tx.execute(raw(`set local lock_timeout = ${Math.round(MIGRATION_LOCK_WAIT_MS)}`));
+      await tx.execute(raw(`select pg_advisory_xact_lock(${MIGRATION_LOCK_KEY})`));
+      const ddlTimeoutMs = Math.round(poolProfileFor('migrate').lockTimeoutMs);
+      await tx.execute(raw(`set local lock_timeout = ${ddlTimeoutMs}`));
+      await applyFrameworkSchema((statement) => tx.execute(raw(statement)));
+      const stamp = nextStamp(await readStamp(tx), thisBuild());
+      await tx.execute(raw(`comment on table ${STAMP_RELATION} is ${literal(stamp).text}`));
+    },
+    { client },
+  );
+}
+
+/**
+ * One catalog read. A build absent from the stamp is refused with the command that applies it; a
+ * fleet straddling a major is reported once and served — refusing it would crash-loop the old pods
+ * of every rolling deploy across a breaking release.
+ */
+export async function verifySchema(client: DbClient): Promise<void> {
+  const mine = thisBuild();
+  const verdict = stampVerdict(parseStamp(await readStamp(client)), mine);
+  if (!verdict.applied) throw new FrameworkSchemaUnappliedError({ mine, newest: verdict.newest });
+  if (verdict.skew === undefined) return;
+  logger.warn('ultimate framework major skew', {
+    cause: `this process runs ${mine.version} and the database's framework schema was last applied by ${verdict.skew.version}: a fleet across a major boundary is mid-rollout or half rolled back`,
+    fix: 'kubectl rollout status deployment --selector app.kubernetes.io/component=web',
+  });
+}

package/src/framework-schema-stamp.ts

@@ -0,0 +1,96 @@
+// Which builds have applied the framework schema to this database: a stamp `ROLE=migrate` leaves
+// in `x_jobs`' table comment, and the verdict a serving role reads from it instead of running DDL
+// itself (plan 101, s1-con #5). Pure: the statements live in `framework-schema-apply.ts`.
+
+import { UltimateError } from '@ultimat3/core';
+import { FRAMEWORK_SCHEMA } from './framework-schema';
+
+/**
+ * The relation that carries the stamp. A comment, not a table: a new framework table moves every
+ * app's committed schema dump (`packages/db/schema/framework/`), and a comment is in none of them.
+ */
+export const STAMP_RELATION = 'x_jobs';
+
+/** The first line of a stamp — what tells it apart from a comment someone else wrote. */
+const STAMP_HEADER = 'ultimate-framework-schema';
+
+/** Enough for a rolling deploy and its rollback, small enough to stay one readable comment. */
+const STAMP_KEEP = 16;
+
+export interface StampEntry {
+  readonly version: string;
+  readonly schema: string;
+}
+
+/** This build's DDL, as one short hash: two builds with the same DDL are the same schema. */
+export function frameworkSchemaHash(): string {
+  const hasher = new Bun.CryptoHasher('sha256');
+  for (const entry of FRAMEWORK_SCHEMA) for (const ddl of entry.ddl) hasher.update(ddl);
+  return hasher.digest('hex').slice(0, 16);
+}
+
+/** Every build a stamp records, newest first. Anything that is not a stamp records none. */
+export function parseStamp(comment: string | null | undefined): readonly StampEntry[] {
+  if (typeof comment !== 'string') return [];
+  const [header, ...lines] = comment.split('\n');
+  if (header !== STAMP_HEADER) return [];
+  return lines.flatMap((line) => {
+    const [version, schema] = line.trim().split(' ');
+    return version !== undefined &&
+      /^[0-9A-Za-z.+-]{1,64}$/.test(version) &&
+      schema !== undefined &&
+      /^[0-9a-f]{16}$/.test(schema)
+      ? [{ version, schema }]
+      : [];
+  });
+}
+
+/** The stamp after `mine` applied: it first, every other build kept, the oldest dropped. */
+export function nextStamp(previous: string | null | undefined, mine: StampEntry): string {
+  const kept = parseStamp(previous).filter((entry) => entry.schema !== mine.schema);
+  const entries = [mine, ...kept].slice(0, STAMP_KEEP);
+  return [STAMP_HEADER, ...entries.map((entry) => `${entry.version} ${entry.schema}`)].join('\n');
+}
+
+const majorOf = (version: string): string => version.split('.')[0] ?? version;
+
+export type StampVerdict =
+  | { readonly applied: true; readonly skew?: StampEntry }
+  | { readonly applied: false; readonly newest?: StampEntry };
+
+/**
+ * Applied when this build's hash is anywhere in the stamp: an old pod restarting mid-rollout finds
+ * its own build there, behind the new one. `skew` is the newest build when its MAJOR differs from
+ * this process's — a fleet straddling a breaking release, which a boot reports and never refuses.
+ */
+export function stampVerdict(entries: readonly StampEntry[], mine: StampEntry): StampVerdict {
+  const newest = entries[0];
+  if (!entries.some((entry) => entry.schema === mine.schema)) {
+    return newest === undefined ? { applied: false } : { applied: false, newest };
+  }
+  return newest !== undefined && majorOf(newest.version) !== majorOf(mine.version)
+    ? { applied: true, skew: newest }
+    : { applied: true };
+}
+
+/** A serving role over a database its build's framework tables were never applied to. */
+export class FrameworkSchemaUnappliedError extends UltimateError {
+  constructor(input: { readonly mine: StampEntry; readonly newest: StampEntry | undefined }) {
+    super({
+      code: 'X_FRAMEWORK_SCHEMA_UNAPPLIED',
+      cause:
+        `this build (${input.mine.version}, framework schema ${input.mine.schema}) has not been applied ` +
+        `to this database — ${
+          input.newest === undefined
+            ? `${STAMP_RELATION} carries no stamp, so no ROLE=migrate of this release ran`
+            : `the newest applied build is ${input.newest.version} (${input.newest.schema})`
+        }. A serving role verifies and never runs DDL: the migrate step must run first`,
+      fix: 'x db migrate',
+      meta: {
+        version: input.mine.version,
+        schema: input.mine.schema,
+        ...(input.newest === undefined ? {} : { newest: { ...input.newest } }),
+      },
+    });
+  }
+}

package/src/framework-schema.ts

@@ -11,7 +11,12 @@ import { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from '@ultimat3/admin/schema
 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 { MCP_CONFIRMATIONS_TABLE, SQL_MCP_CONFIRMATIONS_TABLE } from '@ultimat3/mcp/schema';
+import {
+  SQL_NOTIFY_DELIVERIES_TABLE,
+  SQL_NOTIFY_DIGESTS_TABLE,
+  SQL_NOTIFY_INBOX_TABLE,
+} from '@ultimat3/notify';
 import { FrameworkSchemaFailedError } from './schema-errors';
 
 export interface FrameworkSchema {
@@ -76,11 +81,11 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
   }),
   Object.freeze({
     pkg: '@ultimat3/auth',
-    tables: Object.freeze(['x_auth_failures', 'x_auth_lockouts']),
+    tables: Object.freeze(['x_auth_lockouts']),
     ddl: Object.freeze([SQL_AUTH_LIMIT_TABLES]),
   }),
   /**
-   * The five tables `BuiltinAdapter` reads, and the oldest hole in this list.
+   * The five tables `PostgresAuthAdapter` reads, and the oldest hole in this list.
    *
    * Until this row nothing applied them, in dev or in production: they are not `entity()`
    * declarations, so `x db gen` never saw them, and an app was left to paste per-table exports
@@ -113,6 +118,13 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze(['x_notify_inbox']),
     ddl: Object.freeze([SQL_NOTIFY_INBOX_TABLE]),
   }),
+  // `postgresDigestStore`'s windows. Installed whether or not the app picks that store, for the
+  // reason every notify row is: `setNotifyStores` is the app's boot line and runs after this one.
+  Object.freeze({
+    pkg: '@ultimat3/notify',
+    tables: Object.freeze(['x_notify_digests']),
+    ddl: Object.freeze([SQL_NOTIFY_DIGESTS_TABLE]),
+  }),
   /**
    * The admin's durable audit trail — what `postgresAuditLog()` writes and every detail page's
    * history card reads. Without this row an app that chose the durable log met `42P01` on the
@@ -124,6 +136,16 @@ export const FRAMEWORK_SCHEMA: readonly FrameworkSchema[] = Object.freeze([
     tables: Object.freeze([ADMIN_AUDIT_TABLE]),
     ddl: Object.freeze([SQL_ADMIN_AUDIT_TABLE]),
   }),
+  /**
+   * `mcpConfirmations`' pending rows — what `postgresConfirmationStore()` reads and writes. Without
+   * this row the first gated `tools/call` met `42P01`. Through `@ultimat3/mcp/schema`, a leaf
+   * module that imports nothing, for the admin row's reason: no MCP server on a worker's path.
+   */
+  Object.freeze({
+    pkg: '@ultimat3/mcp',
+    tables: Object.freeze([MCP_CONFIRMATIONS_TABLE]),
+    ddl: Object.freeze([SQL_MCP_CONFIRMATIONS_TABLE]),
+  }),
 ]);
 
 /** Every relation this boot creates, flattened. */

package/src/generate-catalog-locales.ts

@@ -0,0 +1,79 @@
+// The catalogs a generator emits, made true for every locale they target. A template speaks the
+// default locale only, so its strings are copied MARKED into every other locale — the seed
+// `x i18n add` and `x i18n sync` write — and a locale the app has no catalog for yet is refused
+// with `x i18n add <locale>`, the one command that starts a catalog holding every existing key.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { type Catalog, loadCatalog } from '@ultimat3/i18n';
+import { loadAppCatalogs } from '@ultimat3/i18n/app-catalogs';
+import { BadFlagError } from './errors';
+import { resolveDefaultLocale, seedCatalog, serializeCatalog } from './i18n-audit';
+import { catalogLocales } from './i18n-index';
+import type { GeneratedFile } from './templates';
+import { CATALOG_ROOT, catalogPath } from './templates';
+
+/** The locale a `merge: 'json'` file is the catalog of, or `undefined` for any other file. */
+const localeOf = (file: GeneratedFile): string | undefined => {
+  if (file.merge !== 'json') return undefined;
+  const prefix = `${CATALOG_ROOT}/`;
+  if (!file.path.startsWith(prefix) || !file.path.endsWith('.json')) return undefined;
+  const stem = file.path.slice(prefix.length, -'.json'.length);
+  return stem.includes('/') ? undefined : stem;
+};
+
+/**
+ * The catalogs' declared default (`defineCatalogs({ default })`), or `undefined` when the app has no
+ * catalog module or it will not load — `x g` is not the command that refuses an app over it: the
+ * manifest load after the write reports that, with its own fix.
+ */
+async function declaredDefault(root: string): Promise<string | undefined> {
+  try {
+    return (await loadAppCatalogs(root))?.defaultLocale;
+  } catch {
+    return undefined;
+  }
+}
+
+const asLocaleSet = (locales: readonly string[]): Readonly<Record<string, Catalog>> =>
+  Object.fromEntries(locales.map((locale) => [locale, {}]));
+
+/**
+ * `files` with every non-default catalog's values marked. The default is resolved by
+ * `x i18n add`'s own rule (`resolveDefaultLocale`) over the catalogs on disk, and — in an app with
+ * none yet — over the catalogs this run starts, so a first `--locales en,es` writes `en` bare and
+ * `es` marked, both holding the same keys.
+ *
+ * Refuses, before anything is planned to disk, a non-default locale with no catalog in an app that
+ * HAS catalogs: a file started here would hold this generator's keys and none of the app's, which
+ * the scaffold's "every locale has the same keys" test and `x i18n check` both answer red.
+ */
+export async function localiseCatalogs(
+  root: string,
+  files: readonly GeneratedFile[],
+): Promise<readonly GeneratedFile[]> {
+  const targeted = [...new Set(files.flatMap((file) => localeOf(file) ?? []))];
+  if (targeted.length === 0) return files;
+  const onDisk = await catalogLocales(root);
+  const declared = await declaredDefault(root);
+  const fallback =
+    resolveDefaultLocale(declared, asLocaleSet(onDisk)) ??
+    resolveDefaultLocale(declared, asLocaleSet(targeted));
+  if (onDisk.length > 0) {
+    const absent = targeted.find((locale) => locale !== fallback && !onDisk.includes(locale));
+    if (absent !== undefined) {
+      throw new BadFlagError({
+        flag: 'locales',
+        command: 'g',
+        reason: `no catalog for "${absent}" at ${catalogPath(absent)}, and one started by a generator would hold only its own keys`,
+        fix: `x i18n add ${renderFixShellArg(absent, '<locale>')}`,
+      });
+    }
+  }
+  return files.map((file) => {
+    const locale = localeOf(file);
+    if (file.merge !== 'json' || locale === undefined || locale === fallback) return file;
+    if (fallback === undefined) return file;
+    const generated: unknown = JSON.parse(file.contents);
+    return { ...file, contents: serializeCatalog(seedCatalog(loadCatalog(generated))) };
+  });
+}

package/src/generate-files.ts

@@ -2,7 +2,8 @@
 // `cmd-generate.ts` so a generator's output can be asserted on — by the generator tests, the
 // scaffold fixture and `x new` — without a command line, an app root or a filesystem.
 
-import { BadFlagError, CliNotImplementedError } from './errors';
+import { NotImplementedError } from '@ultimat3/core';
+import { BadFlagError } from './errors';
 import type { Generator } from './generate-kinds';
 import { assertLiveSupported, assertSurfaceSupported, GENERATORS } from './generate-kinds';
 import { dedupe } from './generate-write';
@@ -233,8 +234,8 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         }),
       );
     default:
-      throw new CliNotImplementedError({
-        feature: `generator "${String(options.kind)}"`,
+      throw new NotImplementedError({
+        cause: `generator "${String(options.kind)}" is not implemented in this build`,
         fix: `x g ${GENERATORS.join('|')}`,
       });
   }

package/src/generate-kinds.ts

@@ -137,10 +137,28 @@ export function readName(raw: string | undefined, kind: Generator): string {
   // directory that serves it. Every other generator's name is one directory segment.
   if (kind === 'route') return readRoutePath(raw);
   refusePath(raw, 'name', kind);
+  refuseNonAscii(raw, kind);
   refuseBadIdentifier(raw, kind);
+  // A plural name is refused on the PLAN (`generate-plural.ts`): which kinds pluralise it into a
+  // table is a fact about the files they write, not a list kept here.
   return raw;
 }
 
+/**
+ * Every derived spelling keeps `[a-zA-Z0-9]` and drops the rest as a separator, so a letter
+ * outside ASCII vanished: `x g entity Über` wrote `ber`. Refused, with the name folded to ASCII.
+ */
+function refuseNonAscii(raw: string, kind: Generator): void {
+  if (!/[^\p{ASCII}]/u.test(raw)) return;
+  const folded = kebab(raw.normalize('NFKD').replace(/[^\p{ASCII}]/gu, ''));
+  throw new BadFlagError({
+    flag: 'name',
+    command: `g ${kind}`,
+    reason: `"${raw}" holds a letter outside ASCII, and every file, identifier and table name the generator derives from it keeps ASCII letters and digits only`,
+    fix: folded === '' ? exampleFor(kind) : ['x g', kind, folded].join(' '),
+  });
+}
+
 /** A static segment, or `[param]` / `[...rest]` — the directory convention `x routes` reads. */
 const ROUTE_SEGMENT = /^(?:[A-Za-z0-9][A-Za-z0-9_-]*|\[(?:\.\.\.)?[A-Za-z][A-Za-z0-9_-]*\])$/;
 

package/src/generate-plural.ts

@@ -0,0 +1,50 @@
+// A plural slice name pluralised again into a table: `x g resource posts` declared
+// `entity('postses')`, and `x g query top-posts` — whose plan writes the slice's missing
+// `entity.ts` — printed `create top_postses`. Decided on the planned files, so every generator
+// that writes an entity is covered the day it starts to, and none that writes none is judged.
+
+import { BadFlagError } from './errors';
+import type { Generator } from './generate-kinds';
+import type { GeneratedFile } from './templates';
+import { kebab, names, singularOf } from './templates/naming';
+
+/** The slice directory of every `entity.ts` this plan would actually write. */
+function writtenEntitySlices(
+  files: readonly GeneratedFile[],
+  exists: (path: string) => boolean,
+): readonly string[] {
+  return files.flatMap((file) => {
+    if (!file.path.endsWith('/entity.ts')) return [];
+    // A slice module is written only when the slice lacks it: an `entity.ts` already on disk
+    // declares whatever table its author chose, and this run adds no table at all.
+    if (file.merge === 'if-absent' && exists(file.path)) return [];
+    return [file.path.split('/').at(-2) ?? ''];
+  });
+}
+
+/**
+ * Refuses a plan that writes an `entity.ts` into a slice whose name is already plural. The fix
+ * names the singular where the plural came from: the generator's name, or `--feature`.
+ */
+export function refusePluralTable(
+  files: readonly GeneratedFile[],
+  kind: Generator,
+  name: string,
+  feature: string | undefined,
+  exists: (path: string) => boolean,
+): void {
+  for (const slice of writtenEntitySlices(files, exists)) {
+    const singular = singularOf(slice);
+    if (singular === undefined) continue;
+    const fromFeature = feature !== undefined && kebab(feature) === slice;
+    const word = fromFeature ? feature : name;
+    throw new BadFlagError({
+      flag: fromFeature ? 'feature' : 'name',
+      command: `g ${kind}`,
+      reason: `"${word}" is already plural, and the entity this run writes pluralises it again for its table — "${names(slice).table}"`,
+      fix: fromFeature
+        ? ['x g', kind, name, '--feature', singular].join(' ')
+        : ['x g', kind, singular].join(' '),
+    });
+  }
+}