@ultimat3/cli 23.0.0 → 25.0.0

package/src/cmd-doctor.ts

@@ -4,31 +4,22 @@
 
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
-import {
-  ENV_EXAMPLE_PATH,
-  ERROR_DOCS_URL,
-  tryResolveEnvironment,
-  usesDevCursorSecret,
-} from '@ultimat3/core';
-import {
-  checkDb,
-  createPostgresClient,
-  PGLITE_FIX,
-  PGLITE_MISSING,
-  PGLITE_PACKAGE,
-} from '@ultimat3/db';
-import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
+import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL } from '@ultimat3/core';
+import { checkDb, PGLITE_FIX, PGLITE_MISSING, PGLITE_PACKAGE, postgresClient } from '@ultimat3/db';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
-import { DEFAULT_DOCTOR_PORT, doctorSpec } from './cmd-doctor-spec';
+import { doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
+import { appUrlFindings } from './doctor-app-url';
+import { type AuthStorageFact, authStorageFindings, authStorageProbe } from './doctor-auth';
 import { coverageExcludesProbe, withCoverageExcludes } from './doctor-coverage';
 import { shippedGuardsProbe, withGuardListing } from './doctor-guards';
 import type { OfflineFallbackFact } from './doctor-offline';
 import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
 import type { SealedKeysFact } from './doctor-sealed';
 import { sealedKeyFindings, sealedKeysProbe } from './doctor-sealed';
-import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
+import { PORT_RANGE, portPairAfter, readIntFlag } from './flag-number';
+import { machineSecretFindings } from './framework-env';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -37,6 +28,8 @@ import type { ParsedArgs } from './parse';
 import { portFree } from './port-probe';
 import { syncPortFor } from './role-sync';
 import { checkMigrationDrift } from './schema-drift';
+import { portFromEnv } from './serve-env';
+import { quoteArg } from './shell-quote';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -49,17 +42,15 @@ export interface DoctorProbe {
   /** App root, or undefined when the command runs outside an app. */
   readonly root: string | undefined;
   readonly port: number;
-  /** True while cursors are signed with the key shipped in the published package. */
-  readonly devCursorSecret: boolean;
+  /** `APP_URL` as this environment declares it; `undefined` when unset. */
+  readonly appUrl: string | undefined;
   /**
-   * True while the local disk WOULD sign upload grants with the key shipped in the published
-   * package. Same semantics as `devCursorSecret`, environment only — an app that passes an
-   * explicit `signingSecret` in `app.config.ts` never consults the env var, so this can read true
-   * for an app that is fine. The finding is worded as a condition to check, not a certainty.
+   * The framework's own secrets this machine lacks — `framework-env.ts`'s
+   * `machineSecretFindings`, gated by `namedDeployed`: only an environment NAMED staging or
+   * production (an unnamed developer shell owes nothing; `x env check` is the fail-closed answer).
+   * The list's own `needed`/`unsafe` decide; doctor reports.
    */
-  readonly devStorageSecret: boolean;
-  /** True when this process believes it is serving real clients. */
-  readonly production: boolean;
+  readonly frameworkFindings: readonly Finding[];
   exists(relativePath: string): boolean;
   portFree(port: number): Promise<boolean>;
   /**
@@ -101,6 +92,11 @@ export interface DoctorProbe {
    * a retired key beside a sealed column means is `sealedKeyFindings`' pure rule.
    */
   sealedKeys(): Promise<SealedKeysFact>;
+  /**
+   * What an upgrade left in the auth tables for an operator to finish: unsealed second-factor
+   * secrets, and tables no release reads. Asked of an external database only.
+   */
+  authStorage(): Promise<AuthStorageFact>;
 }
 
 /** What `x doctor` reads about the embedded database, without opening it. */
@@ -181,7 +177,7 @@ async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
       finding(
         'X_PORT_IN_USE',
         `port ${entry.port} is already listening, and \`x dev --port ${probe.port}\` binds it for the ${entry.role} role`,
-        `x dev --port ${portPairAfter(probe.port)}`,
+        `x dev --port ${quoteArg(String(portPairAfter(probe.port)))}`,
       ),
     );
   }
@@ -221,42 +217,16 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
         // `.env.example` is the committed projection of `envSchema`, so the copy lands every
         // declared key with its default and blank secrets; `x env example` writes it where an app
         // has none, and `X_ENV_EXAMPLE_DRIFT` is what reports that.
-        `cp ${ENV_EXAMPLE_PATH} ${ENV_DEVELOPMENT}`,
+        `cp ${quoteArg(ENV_EXAMPLE_PATH)} ${quoteArg(ENV_DEVELOPMENT)}`,
         ENV_DEVELOPMENT,
       ),
     );
   }
-  // Production only, and the gate is the point: every development environment signs with the
-  // shipped key on purpose — that is what lets `x dev` page with no configuration — so an
-  // unconditional finding would make `x doctor` red for every developer on day one and teach the
-  // reader to skim past the report. The key is a defect only where cursors reach real clients,
-  // who can read it out of the published package and forge a page position.
-  // Sits here because it costs two env reads and a comparison — cheaper than binding a port.
-  if (probe.production && probe.devCursorSecret) {
-    findings.push(
-      finding(
-        'X_CURSOR_SECRET_DEV',
-        'cursors are signed with the shipped development key, so a client can forge a page position',
-        'export ULTIMATE_CURSOR_SECRET="$(openssl rand -hex 32)"',
-      ),
-    );
-  }
-  // The storage twin of the cursor key above, and the more expensive one to get wrong: the
-  // published string mints a signed `PUT` for any key with any `maxBytes` and `contentType`, and
-  // `acceptSignedUpload` trusts the signed constraints over the app's own `uploadPolicy`.
-  // Production only, for the reason the cursor check gives — every dev environment signs with the
-  // shipped key on purpose. `@ultimat3/storage` refuses this at construction; `x doctor` is what
-  // reports it before a deploy reaches the refusal.
-  if (probe.production && probe.devStorageSecret) {
-    findings.push(
-      finding(
-        'X_STORAGE_SECRET_DEV',
-        `${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`,
-        'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
-      ),
-    );
-  }
+  // Silent in development and on a shell naming no environment; reported where this machine names
+  // a deploy. One list, one wording (`framework-env.ts`, #679).
+  findings.push(...probe.frameworkFindings);
   findings.push(...(await portFindings(probe)));
+  findings.push(...appUrlFindings(probe.appUrl, probe.port));
   // `@ultimat3/pwa`'s own codes, not CLI twins of them. `X_PWA_NO_ICON_SOURCE` and
   // `X_PWA_NO_FALLBACK` used to be declared here for the same two conditions the package already
   // names — two codes for one condition, one of them registered by nobody, so `x errors explain`
@@ -293,20 +263,28 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   findings.push(...(await probe.snapshots()));
   // Sealed columns against the key ring: no key at all, or a rotation whose re-seal is pending.
   findings.push(...sealedKeyFindings(await probe.sealedKeys()));
+  findings.push(...authStorageFindings(await probe.authStorage()));
   return findings;
 }
 
 /**
- * The port to TEST, and the one place `x doctor` reads it. `PORT_RANGE.min` is 0 because `x dev
- * --port 0` means "let the kernel pick"; here 0 means nothing, and `Bun.serve({ port: 0 })` always
- * succeeds — so the port check could not fail, which is worse than not running it.
+ * The port to TEST, and the one place `x doctor` reads it: `devPortFor`'s order — `--port`, then
+ * `PORT` (`portFromEnv`, the one reader of it), then 3000 — so the probe answers about the port
+ * `x dev` will bind. It probed 3000 under `PORT=4000` while dev bound 4000 and 4001. `PORT_RANGE.min`
+ * is 0 because `x dev --port 0` means "let the kernel pick"; here 0 means nothing, and
+ * `Bun.serve({ port: 0 })` always succeeds — so the port check could not fail.
  */
-export const doctorPort = (args: ParsedArgs): number =>
-  intFlagOr(
-    args,
-    { name: 'port', command: 'doctor', ...PORT_RANGE, min: 1, example: 'x doctor --port 3000' },
-    DEFAULT_DOCTOR_PORT,
-  );
+export const doctorPort = (
+  args: ParsedArgs,
+  env: Readonly<Record<string, string | undefined>>,
+): number =>
+  readIntFlag(args, {
+    name: 'port',
+    command: 'doctor',
+    ...PORT_RANGE,
+    min: 1,
+    example: 'x doctor --port 3000',
+  }) ?? portFromEnv(env);
 
 /**
  * `DATABASE_URL` as BOTH halves of the database question read it: unset and blank are one case.
@@ -357,7 +335,7 @@ const installedAbove = (dir: string, specifier: string): boolean => {
  */
 async function probeDatabase(url: string | undefined): Promise<Finding | null> {
   if (externalUrl(url) === undefined) return null;
-  const client = createPostgresClient({ url, applicationName: 'x-doctor' });
+  const client = postgresClient({ url, applicationName: 'x-doctor' });
   try {
     const report = await checkDb(client);
     if (report.ok) return null;
@@ -375,22 +353,20 @@ async function probeDatabase(url: string | undefined): Promise<Finding | null> {
   }
 }
 
-export function probeFor(cwd: string, bunVersion: string, port: number): DoctorProbe {
+export function probeFor(
+  cwd: string,
+  bunVersion: string,
+  port: number,
+  // The environment `doctorPort` read `PORT` from, so `APP_URL` is judged against the same one.
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): DoctorProbe {
   const root = findAppRoot(cwd)?.dir;
   return {
     bunVersion,
     root,
     port,
-    devCursorSecret: usesDevCursorSecret(),
-    devStorageSecret: usesDevStorageSecret(),
-    // `ULTIMATE_ENV`, through core — the one key that says which deploy this is, with `NODE_ENV`
-    // as its documented fallback. This read `X_ENV ?? NODE_ENV`, a spelling nothing else in the
-    // repo reads, so a deploy declaring production the framework's own way was told it was not
-    // production and skipped both secret findings; and the `??` short-circuited, so any non-empty
-    // `X_ENV` shadowed a real `NODE_ENV=production` too. The non-throwing variant because
-    // `ULTIMATE_ENV` is not in the env schema — nothing validates it at boot, and a diagnostic
-    // that crashes on a typo is the one thing worse than a diagnostic that misses.
-    production: tryResolveEnvironment() === 'production',
+    appUrl: env['APP_URL'],
+    frameworkFindings: machineSecretFindings(env),
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
     database: () => probeDatabase(process.env['DATABASE_URL']),
@@ -408,14 +384,15 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
       root === undefined ? { fallback: null, routes: undefined } : offlineFallbackProbe(root),
     sealedKeys: async () =>
       root === undefined ? { columns: undefined, keys: undefined } : sealedKeysProbe(root),
+    authStorage: () => authStorageProbe(process.env['DATABASE_URL']),
   };
 }
 
 export const doctorCommand: CliCommand = {
   spec: doctorSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const port = doctorPort(ctx.args);
-    const probe = probeFor(ctx.cwd, ctx.bunVersion, port);
+    const port = doctorPort(ctx.args, ctx.env);
+    const probe = probeFor(ctx.cwd, ctx.bunVersion, port, ctx.env);
     const findings = await runDoctor(probe);
     const listed = withGuardListing(
       {

package/src/cmd-env.ts

@@ -4,15 +4,40 @@
 
 // Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
 import { join } from 'node:path';
-import { checkEnv, ENV_EXAMPLE_PATH, ERROR_DOCS_URL, maskedEnvValues } from '@ultimat3/core';
+import {
+  checkEnv,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  maskedEnvValues,
+  UltimateError,
+} from '@ultimat3/core';
 import { envExampleFor, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
 import { envSpec } from './cmd-env-spec';
 import type { CliCommand, CommandContext } from './command';
-import { EnvSchemaMissingError } from './errors';
+import { frameworkSecretFindings } from './framework-env';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 
+/**
+ * `x env` was run in an app whose `app.config.ts` exports no `envSchema`. Not a silent success:
+ * writing a `.env.example` with no variables in it, or reporting "0 declared variables, all
+ * present", both read as a working environment declaration to whoever runs the command next.
+ *
+ * `X_CONFIG_INVALID` is core's code for "a configuration this process cannot boot on — env or
+ * `app.config.ts`", which is exactly this; the CLI names it in `CLI_BORROWED_ERROR_CODES` rather
+ * than minting a synonym.
+ */
+export class EnvSchemaMissingError extends UltimateError {
+  constructor(input: { subcommand: string }) {
+    super({
+      code: 'X_CONFIG_INVALID',
+      cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
+      fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
+    });
+  }
+}
+
 /**
  * Every subcommand needs the declaration, and an app without one is a usage error rather than an
  * empty success: `x env example` writing a two-comment file would look like it worked.
@@ -43,33 +68,47 @@ async function writeExample(ctx: CommandContext): Promise<CommandResult> {
 }
 
 /**
- * The values are read from the real process environment, and only ever printed through
- * `maskedEnvValues` — `checkEnv().values` holds the actual secrets because `defineEnv()` has to
+ * The values are read from the environment the command was handed (`ctx.env`, the process's own
+ * in `bin.ts`) — one table for the app's keys and the framework's — and only ever printed through
+ * `maskedEnvValues`: `checkEnv().values` holds the actual secrets because `defineEnv()` has to
  * return them, and a `--json` report is the last place a DSN should appear in full.
+ *
+ * The framework's deploy-required secrets (`framework-env.ts`) are asked exactly where the boot
+ * refuses them — outside development/test, and where no environment is named at all — so `ULTIMATE_ENV=production x env check` answers what
+ * the first deployed boot would, instead of each role crash-looping on one key at a time (#679).
  */
 async function checkProcessEnv(ctx: CommandContext): Promise<CommandResult> {
   const { schema } = await requireSchema(ctx.cwd, 'check');
-  const report = checkEnv(schema);
+  const report = checkEnv(schema, { env: ctx.env });
   const total = Object.keys(schema).length;
-  const findings: readonly Finding[] = report.issues.map((issue) => ({
-    code: 'X_ENV_MISSING',
-    cause: `${issue.key} is ${issue.reason} (expected ${issue.expected})`,
-    fix: issue.fix,
-    docs: ERROR_DOCS_URL,
-    at: ENV_EXAMPLE_PATH,
-  }));
+  // A key the app's own declaration already reported is one finding, not two.
+  const reported = new Set(report.issues.map((issue) => issue.key));
+  // Gated by `deployed()` inside — the boot's own rule, so a table naming no environment is
+  // checked as the production process it boots as.
+  const framework = frameworkSecretFindings(ctx.env, reported);
+  const findings: readonly Finding[] = [
+    ...report.issues.map((issue) => ({
+      code: 'X_ENV_MISSING',
+      cause: `${issue.key} is ${issue.reason} (expected ${issue.expected})`,
+      fix: issue.fix,
+      docs: ERROR_DOCS_URL,
+      at: ENV_EXAMPLE_PATH,
+    })),
+    ...framework,
+  ];
+  const ok = findings.length === 0;
   return {
-    ok: report.ok,
+    ok,
     command: 'env',
-    summary: report.ok
+    summary: ok
       ? msg('cli.env.checked', { count: total })
-      : msg('cli.env.invalid', { count: report.issues.length, total }),
+      : msg('cli.env.invalid', { count: findings.length, total }),
     findings,
     data: {
       variables: total,
       values: maskedEnvValues(schema, report.values) as JsonValue,
     },
-    exitCode: report.ok ? 0 : 1,
+    exitCode: ok ? 0 : 1,
   };
 }
 

package/src/cmd-generate.ts

@@ -5,20 +5,23 @@
 import { existsSync } from 'node:fs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { registerAdminResources } from './admin-registration';
-import { registerGeneratedPrimitives } from './api-registration';
+import { indexBindingFindings, registerGeneratedPrimitives } from './api-registration';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
 import { generateSpec } from './cmd-generate-spec';
 import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
+import { localiseCatalogs } from './generate-catalog-locales';
 import { assertFeatureExists } from './generate-feature';
 import { generate, sliceDir } from './generate-files';
 import { ungrantedByGenerator } from './generate-grant-findings';
 import { grantGeneratedPermissions } from './generate-grants';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
-import { containedPath, writeFiles } from './generate-write';
+import { refusePluralTable } from './generate-plural';
+import { refuseShadowedTypes, refuseShadowedValues } from './generate-shadow';
+import { containedPath, planWrites, writeFiles } from './generate-write';
 import { declareGeneratedImports } from './generated-imports';
 import { registerGeneratedEntities, resolveDbModule } from './handle-registration';
 import { resolveCatalogModule } from './i18n-audit';
@@ -28,6 +31,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
 import { quoteArg } from './shell-quote';
+import type { GeneratedFile } from './templates';
 import { kebab, names, resolveLocales } from './templates';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
@@ -40,6 +44,24 @@ export { GENERATORS } from './generate-kinds';
 export type { WriteReport } from './generate-write';
 export { dedupe, writeFiles } from './generate-write';
 
+/**
+ * Names to suggest when the API index already holds the requested one, in order: the feature's
+ * prefix, the kind's suffix, then that suffix numbered — kebab output, so each pastes into a shell
+ * as one argument. The caller re-plans each and offers the first the index does not hold either.
+ */
+const freeNames = (
+  kind: Generator,
+  name: string,
+  feature: string | undefined,
+): readonly string[] => {
+  const suffixed = `${kebab(name)}-${kind.split(':').at(-1) ?? kind}`;
+  return [
+    ...(feature === undefined ? [] : [`${kebab(feature)}-${kebab(name)}`]),
+    suffixed,
+    ...Array.from({ length: 8 }, (_unused, index) => `${suffixed}-${index + 2}`),
+  ];
+};
+
 export const generateCommand: CliCommand = {
   spec: generateSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -72,41 +94,76 @@ export const generateCommand: CliCommand = {
     // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
     const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
     const sliceRepo = await readSliceFile(root, kind, slice, 'repo.ts');
-    const files = generate({
-      kind,
-      name,
-      ...(featureFlag === undefined ? {} : { feature: featureFlag }),
-      ...(sliceErrors === undefined ? {} : { sliceErrors }),
-      ...(sliceEntity === undefined ? {} : { sliceEntity }),
-      ...(sliceRepo === undefined ? {} : { sliceRepo }),
-      ...(at === undefined ? {} : { at }),
-      ...(permission === undefined ? {} : { permission }),
-      surface,
-      live: flagBool(ctx.args, 'live'),
-      admin: flagBool(ctx.args, 'admin'),
-      locales,
-      ...(catalogModule === undefined ? {} : { catalogModule }),
-      ...(dbModule === undefined ? {} : { dbModule }),
-      shell,
-    });
+    const planFor = (planned: string) =>
+      generate({
+        kind,
+        name: planned,
+        ...(featureFlag === undefined ? {} : { feature: featureFlag }),
+        ...(sliceErrors === undefined ? {} : { sliceErrors }),
+        ...(sliceEntity === undefined ? {} : { sliceEntity }),
+        ...(sliceRepo === undefined ? {} : { sliceRepo }),
+        ...(at === undefined ? {} : { at }),
+        ...(permission === undefined ? {} : { permission }),
+        surface,
+        live: flagBool(ctx.args, 'live'),
+        admin: flagBool(ctx.args, 'admin'),
+        locales,
+        ...(catalogModule === undefined ? {} : { catalogModule }),
+        ...(dbModule === undefined ? {} : { dbModule }),
+        shell,
+      });
+    // A non-default locale's strings arrive marked, and a locale with no catalog yet is refused
+    // with `x i18n add <locale>` — before a dry run answers, so it answers the same files.
+    const files = await localiseCatalogs(root, planFor(name));
+    // On the planned files, before a dry run answers or anything lands: a name whose type spelling
+    // the emitted code also uses as a global is a slice that does not compile.
+    refuseShadowedTypes(files, kind, name);
+    // And one whose binding a planned file both imports and declares (`x g job job`).
+    refuseShadowedValues(files, kind, name);
+    // And a plural slice name that an `entity.ts` this run writes would pluralise again.
+    refusePluralTable(files, kind, name, featureFlag, (path) =>
+      existsSync(containedPath(root, path)),
+    );
+    // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
+    // a second slice beside the one that conflicted.
+    const flags = reproducedFlags(generateCommand.spec, ctx.args);
+    const invocation = [invocationOf(ctx, 'g'), kind, quoteArg(name), ...flags].join(' ');
+    // A module the API index would list under a name it already holds: refused before anything is
+    // written, with the same run under a name that is free — re-planned and re-checked, so the
+    // suggestion is never itself a conflict.
+    const pathsOf = (planned: readonly GeneratedFile[]) => planned.map((file) => file.path);
+    const held = await indexBindingFindings(root, pathsOf(files), '');
+    let bindings: readonly Finding[] = [];
+    if (held.length > 0) {
+      let free = freeNames(kind, name, featureFlag).at(-1) ?? name;
+      for (const candidate of freeNames(kind, name, featureFlag)) {
+        if ((await indexBindingFindings(root, pathsOf(planFor(candidate)), '')).length > 0)
+          continue;
+        free = candidate;
+        break;
+      }
+      const renamed = [invocationOf(ctx, 'g'), kind, quoteArg(free), ...flags].join(' ');
+      bindings = held.map((finding) => ({ ...finding, fix: renamed }));
+    }
+    const force = flagBool(ctx.args, 'force');
     if (flagBool(ctx.args, 'dry-run')) {
+      // The write plan, never the bare file list: what the real run would write, skip and refuse.
+      const plan = await planWrites(root, files, force, invocation);
+      const findings = [...plan.conflicts, ...bindings];
+      const planned = findings.length === 0 ? plan.written : [];
       return {
-        ok: true,
+        ok: findings.length === 0,
         command: 'g',
-        summary: msg('cli.generate.planned', { count: files.length, kind, name }),
-        data: { files: files.map((file) => file.path), dryRun: true },
-        lines: files.map((file) => msg('cli.file.added', { path: file.path })),
+        summary: msg('cli.generate.planned', { count: planned.length, kind, name }),
+        data: { files: planned, dryRun: true },
+        lines: planned.map((file) => msg('cli.file.added', { path: file })),
+        findings,
       };
     }
-    // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
-    // a second slice beside the one that conflicted.
-    const invocation = [
-      invocationOf(ctx, 'g'),
-      kind,
-      quoteArg(name),
-      ...reproducedFlags(generateCommand.spec, ctx.args),
-    ].join(' ');
-    const report = await writeFiles(root, files, flagBool(ctx.args, 'force'), invocation);
+    const report =
+      bindings.length > 0
+        ? { written: [], conflicts: bindings }
+        : await writeFiles(root, files, force, invocation);
     // The three edits a generated primitive needs outside its own slice, performed rather than
     // left as findings: a declared permission granted to a role, a job listed in `defineApi`, and
     // an entity added to the typed handle its `repo.ts` reads through. Before the manifest load

package/src/cmd-help.ts

@@ -2,7 +2,9 @@
 // never describe a flag that does not exist. Built as a factory over the spec list to keep the
 // registry acyclic.
 
+import { nearestName } from '@ultimat3/core';
 import type { CliCommand, CommandContext } from './command';
+import { UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import type { CommandSpec, FlagSpec } from './parse';
@@ -18,17 +20,28 @@ const flagLine = (flag: FlagSpec): string => {
  * The one resolution of a topic, read by both renderers. `--json` filtered on `spec.name === topic`
  * of its own, so the two disagreed about exactly the inputs a caller is least sure of: `x help
  * generate --json` answered `[]` — "that command does not exist" — while the page beside it printed
- * `g`, and `x help nosuch --json` answered `[]` while the page printed the whole catalogue.
+ * `g`. A topic naming no command is refused, as `x <topic>` itself is: answering the catalogue
+ * with exit 0 read as that command's usage to a caller that never compared the names.
  */
 const specFor = (
   specs: readonly CommandSpec[],
   topic: string | undefined,
-): CommandSpec | undefined =>
-  topic === undefined
-    ? undefined
-    : specs.find((entry) => entry.name === topic || (entry.aliases ?? []).includes(topic));
+): CommandSpec | undefined => {
+  if (topic === undefined) return undefined;
+  const found = specs.find(
+    (entry) => entry.name === topic || (entry.aliases ?? []).includes(topic),
+  );
+  if (found !== undefined) return found;
+  const names = specs.map((entry) => entry.name);
+  const nearest = nearestName(topic, [...names, ...specs.flatMap((entry) => entry.aliases ?? [])]);
+  throw new UnknownCommandError({
+    path: `help ${topic}`,
+    known: names,
+    suggestion: nearest === undefined ? 'help' : `help ${nearest}`,
+  });
+};
 
-/** What `--json` reports: the one resolved command, or — as the human render does — all of them. */
+/** What `--json` reports: the one resolved command, or — with no topic — all of them. */
 export function helpTopic(
   specs: readonly CommandSpec[],
   topic: string | undefined,

package/src/cmd-i18n.ts

@@ -185,7 +185,7 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   const path = catalogPath(locale);
   const app = await loadApp(root);
   const catalogs = await loadCatalogs(root);
-  const from = resolveDefaultLocale(app.defaultLocale, catalogs);
+  const from = resolveDefaultLocale(app.locales.defaultLocale, catalogs);
   const seeded = seedCatalog(from === undefined ? {} : (catalogs[from] ?? {}));
   await writeNewCatalog(join(root, path), locale, serializeCatalog(seeded));
   // The second half of adding a locale, and without it this command SHIPPED A RED GATE: the file
@@ -196,14 +196,15 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const keys = catalogKeys(seeded).length;
+  // The catalog is on disk either way, but a finding fails the run: a `packages/i18n/src/index.ts`
+  // that would not import is why `from` may be the framework's `en` instead of the app's own
+  // default, and an index the locale could not be registered in is a red `i18n` gate step.
+  const findings = [...indexFindings, ...app.findings];
   return {
-    // The catalog is on disk, so the command did what it was asked. `loadApp`'s findings ride along
-    // rather than flip that: a `packages/i18n/src/index.ts` that would not import is why `from` may
-    // be the framework's `en` instead of the app's own default, and silence there is the bug.
-    ok: true,
+    ok: findings.length === 0,
     command: 'i18n',
     summary: msg('cli.i18n.added', { locale, keys, from: from ?? locale }),
-    findings: [...indexFindings, ...app.findings],
+    findings,
     // `registered` is false only for an app with no `packages/i18n` at all — a fact a caller has
     // to be able to read, because it is the one case where the locale is on disk and unselectable.
     data: { locale, from: from ?? locale, keys, path, registered },
@@ -258,13 +259,15 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
   }
 
   const app = await loadApp(root);
-  const from = resolveDefaultLocale(app.defaultLocale, catalogs);
+  const from = resolveDefaultLocale(app.locales.defaultLocale, catalogs);
   // `from === locale` is the default locale asked to sync itself, and `undefined` is an app with
   // no resolvable default at all — one branch, because both have no catalog to merge from.
+  // A real merge copies the default locale's strings MARKED (`seedCatalog`, as `x i18n add` does):
+  // copied bare they rendered English to every `fr` reader under a green gate.
   const seeded = from === undefined || from === locale;
   const source = seeded
     ? placeholderCatalog(await untranslatedKeys(root, catalogs, locale))
-    : (catalogs[from] ?? {});
+    : seedCatalog(catalogs[from] ?? {});
   const { merged, added } = syncCatalog(target, source);
   if (added.length > 0) await Bun.write(join(root, catalogPath(locale)), serializeCatalog(merged));
   // Unconditional, and not only when keys moved: a catalog that reached disk some other way — a
@@ -274,16 +277,16 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
   const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const total = catalogKeys(merged).length;
+  // Same as `runAdd`: the merge landed, and a finding still fails the run.
+  const findings = [...indexFindings, ...app.findings];
   return {
-    // Same as `runAdd`: the merge landed, and `loadApp`'s findings say whether `from` is the app's
-    // own default or the framework's fallback standing in for an i18n module that would not import.
-    ok: true,
+    ok: findings.length === 0,
     command: 'i18n',
     summary: msg('cli.i18n.synced', { locale, from: from ?? locale, added: added.length, total }),
     // The keys themselves, raw — `runCheck` lists gaps the same way, because a key is a value an
-    // author copies and never prose the catalog owns.
-    lines: seeded ? added.map((key) => `  ${key}`) : [],
-    findings: [...indexFindings, ...app.findings],
+    // author copies and never prose the catalog owns. Every added key is one a human still owes.
+    lines: added.map((key) => `  ${key}`),
+    findings,
     data: {
       locale,
       from: from ?? locale,
@@ -291,9 +294,10 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
       total,
       path: catalogPath(locale),
       registered,
-      // Which of `added` still need a human. Empty on a real merge, where every value is a real
-      // string copied from the default locale — `--json` must be able to tell the two apart.
-      placeholders: seeded ? added : [],
+      // Which of `added` still need a human: all of them. `⟦key⟧` where there was no catalog to
+      // copy from, `⟦<default string>⟧` on a real merge — both are what `x i18n check` counts as
+      // missing until replaced, so `--json` never reports a copy as a translation.
+      placeholders: added,
     },
   };
 }