@ultimat3/cli 29.3.2 → 30.0.0

package/src/generate-sign-in.ts

@@ -0,0 +1,250 @@
+// `x g sign-in --password | --oidc <provider>`: the shape's files written through the one writer
+// (`writeFiles` — a second run conflicts and writes nothing), then the edits outside them: the
+// actions listed in the API index, `app.config.ts`'s `signInPath` and env keys, and — for OIDC —
+// the authenticator swap that drops `x new`'s development viewer, only over `x new`'s own bytes.
+
+import { ERROR_DOCS_URL, stringField } from '@ultimat3/core';
+import { indexBindingFindings } from './api-registration';
+import { generateSpec } from './cmd-generate-spec';
+import type { CommandContext } from './command';
+import { invocationOf } from './command';
+import { EXERCISE_FILE, exerciseWithEntries, signInExerciseEntries } from './exercise-registration';
+import { localiseCatalogs, namedOrAppLocales } from './generate-catalog-locales';
+import { appDisk, plannedDisk } from './generate-disk';
+import { generate } from './generate-files';
+import { followUpEdits } from './generate-follow-ups';
+import { formatWritten } from './generate-format-written';
+import { APP_CONFIG, type SignInEnvKey, signInConfigEdit } from './generate-sign-in-config';
+import { appManifestIfAny, existingArtifacts } from './generate-sign-in-manifest';
+import { readSignInMode, type SignInMode, signInLabel } from './generate-sign-in-mode';
+import { planWrites, writeFiles } from './generate-write';
+import { resolveDbModule } from './handle-registration';
+import { resolveCatalogModule } from './i18n-audit';
+import { reproducedFlags } from './invocation-flags';
+import { msg } from './messages';
+import type { CommandResult, Finding } from './output';
+import { flagBool, flagList } from './parse';
+import { names, resolveLocales } from './templates';
+import { authFiles } from './templates/scaffold-auth';
+import { DEV_ACTOR_FILES, signedInAuthenticatorFiles } from './templates/sign-in-authenticator';
+import { oidcEnvPrefix } from './templates/sign-in-oidc';
+import { SIGN_IN_PATH } from './templates/sign-in-shared';
+
+/** The env keys an OIDC sign-in adds to `envSchema`; `SESSION_SECRET` and `APP_URL` exist already. */
+export const oidcEnvKeys = (provider: string): readonly SignInEnvKey[] => {
+  const prefix = oidcEnvPrefix(provider);
+  return [
+    { key: `${prefix}_ISSUER`, type: 'url', description: `The ${provider} OpenID Connect issuer.` },
+    { key: `${prefix}_CLIENT_ID`, description: `The client id ${provider} issued this app.` },
+    {
+      key: `${prefix}_CLIENT_SECRET`,
+      secret: true,
+      description: `The client secret ${provider} issued this app.`,
+    },
+  ];
+};
+
+/**
+ * The app's slug, as `x new` named it: the root `package.json`'s `name`. A manifest that does not
+ * parse names nothing, which is the conservative answer: no scaffold to compare against, so every
+ * file on disk reads as edited and the swap becomes a finding rather than a throw.
+ */
+export async function appName(root: string): Promise<string | undefined> {
+  const text = await appDisk(root).read('package.json');
+  if (text === undefined) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  return stringField(parsed, 'name');
+}
+
+export interface AuthenticatorSwap {
+  /** The files written over `x new`'s, and the ones deleted, when every one was still `x new`'s. */
+  readonly replace: readonly { readonly path: string; readonly contents: string }[];
+  readonly remove: readonly string[];
+  readonly findings: readonly Finding[];
+}
+
+/** Whether `x new`'s authenticator and development viewer are on disk exactly as it wrote them. */
+export async function planAuthenticatorSwap(root: string): Promise<AuthenticatorSwap> {
+  const name = await appName(root);
+  const scaffold = new Map(
+    name === undefined ? [] : authFiles(names(name)).map((file) => [file.path, file.contents]),
+  );
+  const swapped = signedInAuthenticatorFiles();
+  const paths = [...swapped.map((file) => file.path), ...DEV_ACTOR_FILES];
+  const disk = appDisk(root);
+  const edited: string[] = [];
+  for (const path of paths) {
+    const now = await disk.read(path);
+    if (now !== undefined && now !== scaffold.get(path)) edited.push(path);
+  }
+  if (edited.length > 0) {
+    return {
+      replace: [],
+      remove: [],
+      findings: [
+        {
+          code: 'X_GENERATE_CONFLICT',
+          cause: `${edited.join(', ')} ${edited.length === 1 ? 'is' : 'are'} no longer what x new wrote, so the development viewer was left in place rather than overwritten`,
+          fix: 'rm apps/web/app/auth/dev-actor.ts apps/web/app/auth/dev-actor.test.ts   # then answer null in apps/web/app/auth/authenticator.ts where it called devAuthenticate(request)',
+          docs: ERROR_DOCS_URL,
+          at: edited[0] ?? '',
+        },
+      ],
+    };
+  }
+  return {
+    replace: swapped.map((file) => ({ path: file.path, contents: String(file.contents) })),
+    remove: [...DEV_ACTOR_FILES],
+    findings: [],
+  };
+}
+
+export async function runSignIn(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const mode: SignInMode = readSignInMode(ctx.args);
+  const label = signInLabel(mode);
+  const catalogModule = await resolveCatalogModule(root);
+  const dbModule = await resolveDbModule(root);
+  // Every catalog the app keeps, as every other generator seeds them: `en` alone renders ⟦key⟧
+  // for a reader of any other locale the app ships.
+  const locales = resolveLocales(await namedOrAppLocales(root, flagList(ctx.args, 'locales')));
+  const files = await localiseCatalogs(
+    root,
+    generate({
+      kind: 'sign-in',
+      name: label,
+      signIn: mode,
+      locales,
+      ...(catalogModule === undefined ? {} : { catalogModule }),
+    }),
+  );
+  const flags = reproducedFlags(generateSpec, ctx.args);
+  const invocation = [invocationOf(ctx, 'g'), 'sign-in', ...flags].join(' ');
+  const force = flagBool(ctx.args, 'force');
+  const swap =
+    mode.kind === 'oidc'
+      ? await planAuthenticatorSwap(root)
+      : { replace: [], remove: [], findings: [] };
+  const configSource = await appDisk(root).read(APP_CONFIG);
+  const config = signInConfigEdit(
+    configSource ?? '',
+    SIGN_IN_PATH,
+    mode.kind === 'oidc' ? oidcEnvKeys(mode.provider) : [],
+  );
+  // An app with no `app.config.ts` has no `signInPath` to declare: nothing to edit, nothing owed.
+  const configFindings = configSource === undefined ? [] : config.findings;
+  const configEdited = configSource !== undefined && config.contents !== configSource;
+  // The three actions are listed in the API index under their file names, so an app already
+  // binding `createSession` there is refused before anything lands — `cmd-generate.ts`'s preflight.
+  const bindings = await indexBindingFindings(
+    root,
+    files.map((file) => file.path),
+    `${invocation}   # after renaming what apps/web/api/index.ts already binds under that name`,
+  );
+
+  // The pass's half: what the written actions cannot run as generated, turned off with a reason.
+  const exerciseSource = await appDisk(root).read(EXERCISE_FILE);
+  const exerciseContents = exerciseWithEntries(
+    exerciseSource,
+    signInExerciseEntries(files.map((file) => file.path)),
+  );
+  const exerciseEdited = exerciseContents !== exerciseSource;
+
+  if (flagBool(ctx.args, 'dry-run')) {
+    const plan = await planWrites(root, files, force, invocation, label);
+    const planned = new Map(
+      files.flatMap((file) =>
+        plan.written.includes(file.path) && typeof file.contents === 'string'
+          ? [[file.path, file.contents] as const]
+          : [],
+      ),
+    );
+    const refused = [...plan.conflicts, ...bindings];
+    const follow =
+      refused.length > 0
+        ? { edited: [], findings: [] }
+        : await followUpEdits(root, plan.written, dbModule, plannedDisk(root, planned));
+    const findings = [...refused, ...follow.findings, ...swap.findings, ...configFindings];
+    const touched =
+      refused.length > 0
+        ? []
+        : [
+            ...new Set([
+              ...plan.written,
+              ...follow.edited,
+              ...swap.replace.map((file) => file.path),
+              ...(configEdited ? [APP_CONFIG] : []),
+              ...(exerciseEdited ? [EXERCISE_FILE] : []),
+            ]),
+          ];
+    const removed = refused.length > 0 ? [] : [...swap.remove];
+    return {
+      ok: findings.length === 0,
+      command: 'g',
+      summary: msg('cli.generate.planned', { count: touched.length, kind: 'sign-in', name: label }),
+      data: {
+        files: touched,
+        removed,
+        // What a real run re-projects after it writes, named as `x g`'s other dry runs name them.
+        ...(touched.length === 0 ? {} : { refreshes: [...(await existingArtifacts(root))] }),
+        dryRun: true,
+      },
+      lines: fileLines(touched, removed),
+      findings,
+    };
+  }
+
+  const report =
+    bindings.length > 0
+      ? { written: [], conflicts: bindings }
+      : await writeFiles(root, files, force, invocation, label);
+  if (report.conflicts.length > 0) {
+    return {
+      ok: false,
+      command: 'g',
+      summary: msg('cli.generate.wrote', { count: 0, kind: 'sign-in', name: label }),
+      data: { files: [] },
+      findings: report.conflicts,
+    };
+  }
+  const disk = appDisk(root);
+  for (const file of swap.replace) await disk.write(file.path, file.contents);
+  for (const path of swap.remove) {
+    const file = Bun.file(`${root}/${path}`);
+    if (await file.exists()) await file.delete();
+  }
+  if (configEdited) await disk.write(APP_CONFIG, config.contents);
+  if (exerciseEdited) await disk.write(EXERCISE_FILE, exerciseContents);
+  const follow = await followUpEdits(root, report.written, dbModule, disk);
+  await formatWritten(root, report.written, ctx.runner);
+  const refreshed = await appManifestIfAny(root);
+  const written = [
+    ...new Set([
+      ...report.written,
+      ...swap.replace.map((file) => file.path),
+      ...(configEdited ? [APP_CONFIG] : []),
+      ...(exerciseEdited ? [EXERCISE_FILE] : []),
+      ...follow.edited,
+      ...refreshed.written,
+    ]),
+  ];
+  const findings = [...follow.findings, ...swap.findings, ...configFindings, ...refreshed.findings];
+  return {
+    ok: findings.length === 0,
+    command: 'g',
+    summary: msg('cli.generate.wrote', { count: written.length, kind: 'sign-in', name: label }),
+    data: { files: written, removed: [...swap.remove] },
+    lines: fileLines(written, swap.remove),
+    findings,
+  };
+}
+
+/** One `+` line per file written, then one `-` per file deleted: a deletion is never "added". */
+const fileLines = (added: readonly string[], removed: readonly string[]): readonly string[] => [
+  ...added.map((path) => msg('cli.file.added', { path })),
+  ...removed.map((path) => msg('cli.file.removed', { path })),
+];

package/src/generate-write.ts

@@ -3,14 +3,17 @@
 // which decides WHICH files a generator emits — this file decides what happens to them, and `x new`
 // and the scaffold fixture assemble their own lists and land them through exactly these rules.
 
-// `resolve`/`sep` and not `join`: only resolving the assembled path can prove it stayed inside the
-// app root, and `node:path` is the only API that resolves one. `node:fs` for the exists check.
+// why: `resolve`/`sep` and not `join`: only resolving the assembled path can prove it stayed
+// inside the app root, and `node:path` is the only API that resolves one. `node:fs` for the exists
+// check.
 import { existsSync } from 'node:fs';
-import { resolve, sep } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { commentSafe } from './comment-safe';
 import { GenerateJsonInvalidError, ScaffoldPathEscapeError } from './errors';
 import { mergeJsonDeep, mergeJsonInPlace, sortJsonDeep } from './json-merge';
 import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
 import type { GeneratedFile } from './templates';
 
 /** `undefined` when `text` does not parse as a JSON object — the one shape every catalog, whether
@@ -164,11 +167,40 @@ type WritePlan =
   | { readonly kind: 'skip' }
   | { readonly kind: 'conflict'; readonly finding: Finding };
 
+/**
+ * The author's rules live in a slice's `entity.ts` and `policy.ts`: `--force` as the first thing
+ * offered deleted them, when an existing slice almost always means the next primitive belongs in it.
+ */
+const conflictFix = (
+  path: string,
+  absolute: string,
+  invocation: string,
+  name: string | undefined,
+): string => {
+  const [slice, module] = path.split('/').slice(-2);
+  // The caller's own name, never `<name>`: a placeholder pasted into a shell is a redirect. With no
+  // name to hand back, the one line that needs none.
+  if (
+    slice === undefined ||
+    name === undefined ||
+    (module !== 'entity.ts' && module !== 'policy.ts')
+  )
+    return `${invocation} --force   # overwrites ${path}, or pass a different name`;
+  const into = `--feature ${quoteArg(slice)}`;
+  const named = quoteArg(name);
+  // A read needs the slice's table (X_FEATURE_REQUIRED), so it is offered only beside one.
+  const read = existsSync(join(dirname(absolute), 'entity.ts'))
+    ? `or x g query ${named} ${into}`
+    : `a read needs x g entity ${quoteArg(slice)} first`;
+  return `x g action ${named} ${into}   # ${read}: ${commentSafe(path)} is the author's`;
+};
+
 function planFile(
   file: GeneratedFile,
   absolute: string,
   force: boolean,
   invocation: string,
+  name: string | undefined,
 ): WritePlan {
   // A foundation file belongs to the slice, not to the generator that needs it: several generators
   // emit the same `repo.ts`, so an existing one is the author's — never a conflict, and never
@@ -189,7 +221,7 @@ function planFile(
         // The caller's own invocation, not `x g <kind>`: `x g --force` is X_CLI_UNKNOWN_COMMAND
         // when run, and a `fix:` is copied and pasted verbatim. Same construction as
         // `generate-kinds.ts`'s `assertSurfaceSupported`.
-        fix: `${invocation} --force   # overwrites ${file.path}, or pass a different name`,
+        fix: conflictFix(file.path, absolute, invocation, name),
         docs: ERROR_DOCS_URL,
         at: file.path,
       },
@@ -204,6 +236,7 @@ async function planAll(
   files: readonly GeneratedFile[],
   force: boolean,
   invocation: string,
+  name: string | undefined,
 ): Promise<readonly WritePlan[]> {
   const plans: WritePlan[] = [];
   for (const file of files) {
@@ -211,7 +244,7 @@ async function planAll(
     plans.push(
       file.merge === 'json'
         ? await planJsonMerge(file, absolute)
-        : planFile(file, absolute, force, invocation),
+        : planFile(file, absolute, force, invocation, name),
     );
   }
   return plans;
@@ -230,8 +263,10 @@ export async function planWrites(
   files: readonly GeneratedFile[],
   force: boolean,
   invocation = 'x g <kind> <name>',
+  /** The name the caller gave, handed back in a conflict's fix; absent, that fix names none. */
+  name?: string,
 ): Promise<WriteReport> {
-  const plans = await planAll(root, files, force, invocation);
+  const plans = await planAll(root, files, force, invocation, name);
   const conflicts = conflictsOf(plans);
   if (conflicts.length > 0) return { written: [], conflicts };
   return {
@@ -259,8 +294,10 @@ export async function writeFiles(
    * shape, not a runnable line, and every generator path supplies the real one.
    */
   invocation = 'x g <kind> <name>',
+  /** `planWrites`' `name`. */
+  name?: string,
 ): Promise<WriteReport> {
-  const plans = await planAll(root, files, force, invocation);
+  const plans = await planAll(root, files, force, invocation, name);
   const conflicts = conflictsOf(plans);
   if (conflicts.length > 0) return { written: [], conflicts };
 

package/src/hand-rolled-socket.ts

@@ -0,0 +1,72 @@
+// An app's own websocket upgrade, made a build error: `deviceSocket()` is the one way an app serves
+// a long-lived socket, and a hand-rolled `server.upgrade(` or `Bun.serve({ websocket })` skips the
+// token check before the handshake, the per-actor cap, the beat, the frame limit and the drain.
+// Pure over the `boundaries` step's one read; masked, so a comment or a string never matches.
+
+import { ERROR_DOCS_URL, maskLiterals } from '@ultimat3/core';
+import type { SourceFile } from './app-boundaries';
+import { commentSafe } from './comment-safe';
+import type { Finding } from './output';
+
+/** `Bun.serve(` — its argument is read for a `websocket` key. */
+const SERVE = /\bBun\s*\.\s*serve\s*\(/g;
+/** A `websocket` KEY in an object literal: `websocket: x`, or the shorthand `{ websocket }`. */
+const WEBSOCKET_KEY = /\bwebsocket\s*[:,}]/;
+/**
+ * Bun's upgrade, by the names its two halves carry: the server (`server.upgrade(`, `srv.upgrade(`)
+ * or the request it takes (`x.upgrade(request`). `plans.upgrade(org)` is somebody's business.
+ */
+const UPGRADE = /\b(?:server|srv)\s*\.\s*upgrade\s*\(|\.\s*upgrade\s*\(\s*(?:req|request)\b/g;
+/** An inline handler set — `websocket: {` — whatever server it is handed to. */
+const HANDLERS = /\bwebsocket\s*:\s*\{/g;
+
+/** The index closing the `(` at `open`, or the end of the text. Exact over `maskLiterals` output. */
+function closeOf(masked: string, open: number): number {
+  let depth = 0;
+  for (let index = open; index < masked.length; index += 1) {
+    if (masked[index] === '(') depth += 1;
+    else if (masked[index] === ')') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return masked.length;
+}
+
+/** Where each hand-rolled upgrade starts, as an offset into `masked`. */
+function handRolledAt(masked: string): readonly number[] {
+  const at: number[] = [];
+  for (const match of masked.matchAll(SERVE)) {
+    const open = match.index + match[0].length - 1;
+    if (WEBSOCKET_KEY.test(masked.slice(open, closeOf(masked, open)))) at.push(match.index);
+  }
+  for (const pattern of [UPGRADE, HANDLERS]) {
+    for (const match of masked.matchAll(pattern)) at.push(match.index);
+  }
+  return at;
+}
+
+/** 1-based line of `offset`; `maskLiterals` keeps every newline, so the count is the source's. */
+const lineOf = (masked: string, offset: number): number =>
+  masked.slice(0, offset).split('\n').length;
+
+/** One `X_SOCKET_HAND_ROLLED` per app file that serves a socket itself, at its first line. */
+export function handRolledSocketFindings(files: readonly SourceFile[]): readonly Finding[] {
+  return files.flatMap(({ path, source }): Finding[] => {
+    if (!source.includes('upgrade') && !source.includes('websocket')) return [];
+    const masked = maskLiterals(source);
+    const first = Math.min(...handRolledAt(masked));
+    if (!Number.isFinite(first)) return [];
+    const line = lineOf(masked, first);
+    return [
+      {
+        code: 'X_SOCKET_HAND_ROLLED',
+        cause: `${path}:${String(line)} upgrades a websocket itself, so the token check before the handshake, the per-actor cap, the heartbeat, the frame limit and the drain are the app's to remember — and the boot never serves it on the web listener`,
+        fix: `x verify --only boundaries --json   # in ${commentSafe(path)}, delete the upgrade and declare the socket: export const link = deviceSocket({ path, resolveToken, onFrame }) from @ultimat3/realtime/server`,
+        docs: ERROR_DOCS_URL,
+        at: path,
+        meta: { line },
+      },
+    ];
+  });
+}

package/src/i18n-app-key-shapes.ts

@@ -0,0 +1,29 @@
+// Every shape in an app's source whose literal is a catalog key. Here and not in `@ultimat3/i18n`:
+// tier 1 must not name `blocks` or `defineMail`, and this package already sits over both. Passed by
+// `scanSource` only, so the framework's own catalog scan (`scripts/lib/i18n-scan.ts`) keeps its
+// callees: `mail.*` lives in `mail/src/catalog.ts`, not in `catalogs/en.json`.
+
+import type { ExtractOptions } from '@ultimat3/i18n';
+
+export const APP_KEY_SHAPES = {
+  callees: [
+    't',
+    '$t',
+    'translate',
+    // The key is the first argument of each (`mail/src/blocks.ts`). `divider` takes none.
+    // `i18n-app-key-shapes.test.ts` reads `blocks` itself, so a new block reds until listed here.
+    'blocks.heading',
+    'blocks.paragraph',
+    'blocks.button',
+    'blocks.callout',
+    'blocks.detail',
+  ],
+  properties: [
+    // A push payload's and an admin screen's keys. Unambiguous anywhere: nothing else is `*Key`.
+    { name: 'titleKey' },
+    { name: 'bodyKey' },
+    // `subject:` alone is also a column, a form field and a schema member.
+    // The bare name, not `defineMail(`: `defineMail<{ total: string }>({` is the usual spelling.
+    { name: 'subject', whenFileContains: 'defineMail' },
+  ],
+} as const satisfies ExtractOptions;

package/src/i18n-audit.ts

@@ -19,13 +19,15 @@ import {
   missingFrom,
   nestCatalog,
 } from '@ultimat3/i18n';
+import { APP_KEY_SHAPES } from './i18n-app-key-shapes';
 import { isLoudMiss, loudMiss } from './i18n-registration';
 import { posixRelative } from './posix-path';
 import { eachSourceFile, isTest } from './source-files';
 import { CATALOG_ROOT, catalogPath } from './templates/locales';
 
 /**
- * Every `t()` call the app's own source makes. `source-files.ts` (`eachSourceFile`) is the one
+ * Every key the app's own source names: a `t()` call, a mail block or subject, a push payload
+ * (`APP_KEY_SHAPES`). `source-files.ts` (`eachSourceFile`) is the one
  * glob set every text-scanning gate step already shares (`errors`, `filesize`) — a second glob
  * here would mean this command and `x verify` disagree on what "the app's source" is. Test files
  * are excluded: a fixture's `t('fixture.key')` is not a gap the shipped catalogs owe an answer to.
@@ -40,7 +42,10 @@ export async function scanSource(root: string): Promise<Extraction> {
   for await (const file of eachSourceFile(root)) {
     if (!isTest(file) && !isGuard(file)) files.push(file);
   }
-  const extraction = await extractFromFiles(files.map((file) => join(root, file)));
+  const extraction = await extractFromFiles(
+    files.map((file) => join(root, file)),
+    APP_KEY_SHAPES,
+  );
   const toRelative = (file: string): string => posixRelative(root, file);
   return {
     usages: extraction.usages.map((usage) => ({ ...usage, file: toRelative(usage.file) })),
@@ -115,7 +120,9 @@ export async function auditApp(root: string): Promise<AuditFacts> {
   const [extraction, catalogs] = await Promise.all([scanSource(root), loadCatalogs(root)]);
   const ignoreUnused = runtimeKeyPatterns(extraction);
   return {
-    report: auditCatalogs({ extraction, catalogs, ignoreUnused }),
+    // `reference` is what sees a key no static shape names: `t(\`plans.\${x}\`)` reads the same
+    // catalog in every locale, so a key `en` holds alone is a raw key on another locale's page.
+    report: auditCatalogs({ extraction, catalogs, ignoreUnused, reference: DEFAULT_LOCALE }),
     catalogs,
     extraction,
     ignoreUnused,

package/src/i18n-registration.ts

@@ -15,6 +15,7 @@ import {
   catalogRegistrationGaps,
   catalogsNeverRegistered,
   catalogUnregistered,
+  familyIncomplete,
   pluralVariantsOf,
   registeredLocales,
 } from '@ultimat3/i18n';
@@ -26,6 +27,7 @@ import type { DuplicateProbe } from './duplicate-packages';
 import { duplicateCause, duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import { auditApp } from './i18n-audit';
 import { localeParityFindings } from './i18n-locale-parity';
+import { mailPreviewFindings } from './mail-preview-findings';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { CATALOG_ROOT, catalogPath } from './templates/locales';
@@ -105,7 +107,7 @@ export async function checkRegistration(input: RegistrationInput): Promise<Regis
       duplicate === undefined
         ? { ...finding, ...unregisteredFix(gap.locale, index), at: catalogPath(gap.locale) }
         : // The registry's own fix names a source edit — move the `defineCatalogs()` call — that an
-          // agent following it performs on a file that is already right (ai-maxxing, 2026-09-05).
+          // agent following it performs on a file that is already right (one adopter, 2026-09-05).
           // With a duplicate on disk the cause IS the install, so the finding says so and the fix
           // is the one the duplicate carries.
           {
@@ -261,7 +263,9 @@ export function withPlaceholdersMissing(
   const locales = report.locales.map((audit) => {
     const catalog = catalogs[audit.locale] ?? {};
     const known = new Set(audit.missing);
-    const placeheld = report.used.filter(
+    // `required`, not `used`: `x i18n sync` seeds a reference-only key as a marker too, and a marker
+    // that closed the finding would put `⟦…⟧` on the page under a green gate.
+    const placeheld = report.required.filter(
       (key) => !known.has(key) && answersWithPlaceholder(catalog, key),
     );
     if (placeheld.length === 0) return audit;
@@ -276,12 +280,21 @@ export function withPlaceholdersMissing(
  * the same finding, and a second construction of it is two renderers of one fact waiting to drift.
  */
 export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
-  return report.locales
+  const missing = report.locales
     .filter((audit) => audit.missing.length > 0)
     .map((audit) => ({
       ...findingFrom(catalogMissingKeys(audit.locale, audit.missing)),
       at: catalogPath(audit.locale),
     }));
+  // A select or ordinal family with no `_other` renders `⟦key⟧` for every value it does not name:
+  // the same loud miss, one family wide, so the same gate refuses it.
+  const incomplete = report.locales
+    .filter((audit) => audit.incomplete.length > 0)
+    .map((audit) => ({
+      ...findingFrom(familyIncomplete(audit.locale, audit.incomplete)),
+      at: catalogPath(audit.locale),
+    }));
+  return [...missing, ...incomplete];
 }
 
 /**
@@ -300,5 +313,7 @@ export async function catalogFindings(root: string): Promise<readonly Finding[]>
     ...missingKeyFindings(withPlaceholdersMissing(report, catalogs)),
     ...registration.findings,
     ...localeParityFindings(catalogs),
+    // The app is loaded by the audit above, so every `defineMail({ preview })` is registered.
+    ...mailPreviewFindings(Object.keys(catalogs)),
   ];
 }

package/src/index.ts

@@ -113,6 +113,8 @@ export { renderJobTable } from './jobs-table';
 export { msg } from './messages';
 export { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
 export { parseMigrationSql, readMigrations } from './migrations';
+export type { NewShape } from './new-shapes';
+export { NEW_SHAPES } from './new-shapes';
 export type { CommandResult, Finding, JsonValue } from './output';
 export { exitCodeFor, findingFrom, render, renderFinding, renderHuman } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';

package/src/island-bundle.ts

@@ -36,7 +36,7 @@ import {
   realtimeIslandEntry,
   realtimeKind,
 } from './island-realtime';
-import type { IslandRealtime } from './island-realtime-state';
+import { appPersistsRecords, type IslandRealtime } from './island-realtime-state';
 import type { Runtimes } from './island-runtime';
 import { loadingRuntime, mergeBuilds, runtimeBuilder, runtimeShared } from './island-runtime';
 import { solidDedupePlugin } from './island-solid-dedupe';
@@ -130,7 +130,7 @@ export async function discoverIslands(root: string): Promise<readonly string[]>
 /**
  * One `Bun.build` over `files`. With `splitting`, a module two of them import becomes one shared
  * chunk, fetched once by a page that renders both — a page rendering two islands that shared an
- * upload helper downloaded it twice without (notificado.co, 2026-09-29: 55.5 kB for ~34 kB of
+ * upload helper downloaded it twice without (one adopter, 2026-09-29: 55.5 kB for ~34 kB of
  * code). Without, `files` is one island and its chunk is self-contained. Either way a route's cost
  * is the graph walk `measureDocumentJs` does off the emitted files.
  */
@@ -144,9 +144,10 @@ async function buildAll(
   // Inside the refusal: the realtime probe PARSES the island's graph, and a file that will not
   // parse rejected with a raw `AggregateError: Failed to scan imports` — out of the web boot, with
   // no code, no file and no fix — before `Bun.build` ever ran to raise the one below.
+  const persists = appPersistsRecords();
   const realtime = await Promise.all(
     files.map((file) =>
-      realtimeKind(root, file).catch((error: unknown) => {
+      realtimeKind(root, file, persists).catch((error: unknown) => {
         throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
       }),
     ),