@ultimat3/cli 5.0.1 → 7.0.0

package/src/cmd-dev.ts

@@ -23,10 +23,11 @@ import type { CliCommand, CommandContext } from './command';
 import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
 import { appRoutes } from './dev-render';
 import type { RunningRoles } from './dev-roles';
-import { DEV_ROLES, selectRoles, startRoles } from './dev-roles';
+import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 import type { RunningServices } from './dev-runtime';
 import { cdnLabel, describeCdn, describeMail, mailLabel, startServices } from './dev-runtime';
 import type { DevServices } from './dev-services';
@@ -295,6 +296,20 @@ export const devCommand: CliCommand = {
       DEFAULT_PORT,
     );
     const roles = selectRoles(flagString(ctx.args, 'role'));
+    // BEFORE anything boots. Both failures this catches were reachable and both reported the wrong
+    // thing: a taken port surfaced as X_CLI_UNEXPECTED wrapping "Is port 3000 in use?" with a `fix:`
+    // naming `x doctor`, and a second `x dev` on one checkout died later on X_DB_UNAVAILABLE whose
+    // `fix:` named `x dev`. Neither is discoverable from the message; both are trivial once the
+    // preflight has the state directory and the port in front of it.
+    const services = resolveServices(root, ctx.env);
+    const { clearedStale } = await preflight({
+      stateDir: services.stateDir,
+      port,
+      // The address the web role will actually bind, never a wider one: probing `0.0.0.0` would
+      // refuse a boot that a neighbour on one LAN interface does not actually block.
+      hostname: DEV_BINDING.hostname,
+      embeddedDb: services.db.mode === 'embedded',
+    });
     const server = await startDev({
       root,
       port,
@@ -344,13 +359,23 @@ export const devCommand: CliCommand = {
         panels: [...server.panels],
       },
       lines: [
+        // A hard kill leaves the lock behind; clearing it is normal and worth one line, never a
+        // finding. First, because it happened before anything else this run reports.
+        ...(clearedStale ? [msg('cli.dev.staleLock')] : []),
         msg('cli.dev.roles', { roles: server.roles.join(', ') }),
         msg('cli.dev.panels', { panels: server.panels.join(', ') }),
         msg('cli.dev.manifest', { path: join(root, MANIFEST_FILENAME) }),
         msg('cli.dev.introspect', { url: `${server.url}/_x` }),
       ],
     };
+    await writeLock(services.stateDir, {
+      pid: process.pid,
+      port,
+      url: server.url,
+      startedAt: new Date().toISOString(),
+    });
     if (ctx.args.flags.get('once') === true) {
+      clearLock(services.stateDir);
       await server.stop();
       return result;
     }
@@ -358,6 +383,14 @@ export const devCommand: CliCommand = {
     // `/_x` stays reachable. Ctrl-C drains the web role through core's phases first and releases
     // the embedded Postgres, the worker and the watcher after — a hard kill leaves the PGlite
     // directory locked by a process that no longer exists.
-    return { ...result, hold: holdUntilShutdown('dev', () => server.stop()) };
+    return {
+      ...result,
+      hold: holdUntilShutdown('dev', async () => {
+        // The lock first: a stop() that throws must not leave a file claiming this pid still owns
+        // the directory, because the next boot would then refuse for a process that is gone.
+        clearLock(services.stateDir);
+        await server.stop();
+      }),
+    };
   },
 };

package/src/cmd-generate.ts

@@ -2,365 +2,29 @@
 // emits a TODO has moved the work, not done it; every file this writes typechecks, and every
 // primitive arrives with the test that pins its distant invariants (policy, idempotency, budget).
 
-// `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 { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { appManifest, writeAppManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import {
-  CliNotImplementedError,
-  GenerateJsonInvalidError,
-  ScaffoldPathEscapeError,
-} from './errors';
-// Re-exported below: `GENERATORS` and `Generator` are imported from this module by the tests, the
-// scaffold fixture and `src/index.ts`, and moving where they are declared must not move where they
-// are read from.
-import type { Generator } from './generate-kinds';
-import {
-  assertSurfaceSupported,
-  GENERATORS,
-  readKind,
-  readName,
-  readSurface,
-} from './generate-kinds';
-import { mergeJsonDeep } from './json-merge';
+import { generate } from './generate-files';
+import { GENERATORS, readKind, readName, readSurface } from './generate-kinds';
+import { containedPath, writeFiles } from './generate-write';
+import { resolveCatalogModule } from './i18n-audit';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
-import type { GeneratedFile, Surface } from './templates';
-import {
-  actionFiles,
-  adminPageFiles,
-  backfillFiles,
-  CATALOG_ROOT,
-  entityFiles,
-  guardFiles,
-  i18nIndex,
-  islandFiles,
-  jobFiles,
-  kebab,
-  policyFiles,
-  queryFiles,
-  resolveLocales,
-  resourceFiles,
-  routeFiles,
-  taskFiles,
-} from './templates';
+import { CATALOG_ROOT, i18nIndex, resolveLocales } from './templates';
 
+// One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
+// fixture reach the kinds, the pure file list and the writer through this module, and a second path
+// to any of them would be the ambiguity axiom 1 forbids.
+export type { GenerateOptions } from './generate-files';
+export { generate } from './generate-files';
 export type { Generator } from './generate-kinds';
 export { GENERATORS } from './generate-kinds';
-
-export interface GenerateOptions {
-  readonly kind: Generator;
-  readonly name: string;
-  readonly feature?: string;
-  readonly surface?: Surface;
-  readonly live?: boolean;
-  /** `resource` only: also emit the per-entity admin override. */
-  readonly admin?: boolean;
-  /** Every locale a generated i18n catalog entry ships for. Defaults to `['en']`. */
-  readonly locales?: readonly string[];
-  /**
-   * `island` and `admin:page`: the directory the generated files land in. Named rather than
-   * derived, because neither destination is derivable — `X_ISLAND_INVALID`'s cause already holds
-   * the path a page's `src` resolved to, and an app's admin is wherever its `defineAdmin` is.
-   */
-  readonly at?: string;
-  /** `admin:page` only: the permission the page's own work needs, on top of `admin:read`. */
-  readonly permission?: string;
-}
-
-const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
-  site: 'apps/web/site',
-  app: 'apps/web/app',
-};
-
-/** `undefined` when `text` does not parse as a JSON object — the one shape every catalog, whether
- * generated or hand-edited on disk, must hold. */
-function parseJsonObject(text: string): Record<string, unknown> | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return undefined;
-  }
-  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
-    ? (parsed as Record<string, unknown>)
-    : undefined;
-}
-
-/** Deterministic catalog bytes: sorted keys, 2-space indent, trailing newline — a diff shows only
- * the keys a run actually changed, never a reordering. */
-function prettyJson(value: Record<string, unknown>): string {
-  const sorted = Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)));
-  return `${JSON.stringify(sorted, null, 2)}\n`;
-}
-
-/**
- * Two generators can legitimately produce the same shared file. A plain file (errors.ts) keeps
- * first-write-wins; a `merge: 'json'` catalog instead merges every contributor's keys into one
- * file — `resourceFiles` and `routeFiles` both target the same locale's catalog, and a plain
- * overwrite would drop whichever generator ran first. Later entries fill keys the earlier one
- * lacks; the first occurrence wins a clash, the same rule `writeFiles` applies against the copy
- * already on disk. Exported so `x new` (`cmd-new.ts`) and the scaffold fixture resolve a shared
- * catalog the identical way — one merge rule, not three hand-copied ones.
- *
- * A `merge: 'json'` file's `contents` are the generator's own output, not user data — one that
- * fails to parse as a JSON object is a bug in the template that produced it, so it throws here
- * rather than being silently treated as `{}` and merged into (or written as) a catalog with
- * attribution to nobody. `writeFiles`/`mergeJsonFile` never see a malformed *generated* payload in
- * practice: every production caller (`generate()` below, `cmd-new.ts`'s `planNewApp()`, the
- * scaffold fixture) runs its file list through this function first.
- */
-export function dedupe(files: readonly GeneratedFile[]): readonly GeneratedFile[] {
-  const seen = new Map<string, GeneratedFile>();
-  for (const file of files) {
-    if (file.merge === 'json' && parseJsonObject(file.contents) === undefined) {
-      throw new GenerateJsonInvalidError({ path: file.path });
-    }
-    const prior = seen.get(file.path);
-    if (prior === undefined) {
-      seen.set(file.path, file);
-    } else if (prior.merge === 'json' && file.merge === 'json') {
-      // Both sides already proved parseable above — the fallback only guards a future change to
-      // that invariant, it never fires today. Deep: two generators contributing to one nested
-      // catalog share top-level keys (`app`, `admin`), and a shallow spread drops one of them.
-      const later = parseJsonObject(file.contents) ?? {};
-      const earlier = parseJsonObject(prior.contents) ?? {};
-      const { merged } = mergeJsonDeep(earlier, later);
-      seen.set(file.path, { ...prior, contents: prettyJson(merged) });
-    }
-    // else: not mergeable — first write wins, exactly as it always has.
-  }
-  return [...seen.values()];
-}
-
-/**
- * Pure: returns the files a generator would write. `x g` writes them, the generator test asserts
- * on them, and nothing has to run a filesystem to review what a generator produces.
- */
-export function generate(options: GenerateOptions): readonly GeneratedFile[] {
-  const surface: Surface = options.surface ?? 'app';
-  assertSurfaceSupported(options.kind, surface, options.name);
-  const surfaceDir = DEFAULT_SURFACE_DIR[surface];
-  const feature = options.feature ?? options.name;
-  const target = { surfaceDir, feature };
-  switch (options.kind) {
-    case 'resource':
-      return dedupe(
-        resourceFiles(options.name, {
-          ...target,
-          admin: options.admin === true,
-          ...(options.locales === undefined ? {} : { locales: options.locales }),
-        }),
-      );
-    case 'action':
-      return dedupe(actionFiles(options.name, target));
-    case 'mutator':
-      return dedupe(actionFiles(options.name, { ...target, mutator: true }));
-    case 'backfill':
-      return dedupe(backfillFiles(options.name, target));
-    case 'entity':
-      return dedupe(entityFiles(options.name, target));
-    case 'policy':
-      return dedupe(policyFiles(options.name, target));
-    case 'query':
-      return dedupe(queryFiles(options.name, { ...target, live: options.live === true }));
-    case 'job':
-      return dedupe(jobFiles(options.name, target));
-    case 'task':
-      return dedupe(taskFiles(options.name, target));
-    case 'island':
-      return dedupe(islandFiles(options.name, { dir: options.at ?? `${surfaceDir}/${feature}` }));
-    // No `--at`, no surface, no feature: `guards/` is the one directory the gate discovers, and a
-    // guard that lived anywhere else would need an app-side registration to be found.
-    case 'guard':
-      return dedupe(guardFiles(options.name));
-    case 'admin:page':
-      // A default permission, never none: an empty list is `X_ADMIN_PAGE_UNGUARDED` on sight.
-      return dedupe(
-        adminPageFiles(options.name, {
-          permission: options.permission ?? `${kebab(options.name)}:read`,
-          // The same `--at` `island` takes: an app's admin is wherever its `defineAdmin` is.
-          ...(options.at === undefined ? {} : { dir: options.at }),
-          ...(options.locales === undefined ? {} : { locales: options.locales }),
-        }),
-      );
-    case 'route':
-      // `--locales` reaches the route generator too: its catalog entry is the route's title and
-      // description, and a locale asked for on the command line is a locale that gets a file.
-      return dedupe(
-        routeFiles(options.name, {
-          surface,
-          ...(options.locales === undefined ? {} : { locales: options.locales }),
-        }),
-      );
-    default:
-      throw new CliNotImplementedError({
-        feature: `generator "${String(options.kind)}"`,
-        fix: `x g ${GENERATORS.join('|')}`,
-      });
-  }
-}
-
-export interface WriteReport {
-  readonly written: readonly string[];
-  readonly conflicts: readonly Finding[];
-}
-
-/**
- * `GeneratedFile.path` is documented as relative-POSIX, not enforced as it: `join` would happily
- * walk out of the app on a `..` segment or ignore the root entirely on an absolute path. Proven
- * before the write, once per file, because after the write there is nothing left to prove.
- */
-export function containedPath(root: string, path: string): string {
-  const base = resolve(root);
-  const target = resolve(base, path);
-  if (target !== base && !target.startsWith(`${base}${sep}`))
-    // The default `fix` names the scaffold gate's own test, which repairs nothing for someone
-    // running `x g`: the fix here is the generate command, re-run as a dry run.
-    throw new ScaffoldPathEscapeError({
-      path,
-      dir: base,
-      // Command first, the caveat behind a `#`: the line runs verbatim and the shell drops the
-      // rest. `x g <kind> <name>` pasted into bash is a redirect, not a command.
-      fix: `x g resource posts --dry-run   # name every file relative to the app root, no ".." segment`,
-    });
-  return target;
-}
-
-/**
- * A `merge: 'json'` catalog is never a conflict on existence and never subject to `--force`: an
- * existing key on disk always wins, because it may hold a human translation, and only genuinely
- * new keys are added — so a second, third… generator run keeps growing the same file instead of
- * fighting over it. A file that exists but does not parse as a JSON object cannot be merged into
- * without risking silent data loss, so that alone is reported rather than clobbered or thrown past.
- *
- * Typed to the `merge: 'json'` variant alone, not the general `GeneratedFile` union: a
- * byte-carrying file has no `contents: string` to merge, and this is what stops one from ever
- * reaching `parseJsonObject` even if a future caller forgets the `file.merge === 'json'` guard
- * its one call site already applies.
- */
-async function planJsonMerge(
-  file: Extract<GeneratedFile, { merge: 'json' }>,
-  absolute: string,
-): Promise<WritePlan> {
-  const generated = parseJsonObject(file.contents) ?? {};
-  if (!existsSync(absolute))
-    return { kind: 'write', file, absolute, contents: prettyJson(generated) };
-  const existing = parseJsonObject(await Bun.file(absolute).text());
-  if (existing === undefined) {
-    return {
-      kind: 'conflict',
-      finding: {
-        code: 'X_GENERATE_CONFLICT',
-        cause: `${file.path} exists but is not a JSON object, so its keys cannot be merged`,
-        fix: `edit ${file.path} by hand until it parses as a JSON object, or delete it and re-run x g`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
-        at: file.path,
-      },
-    };
-  }
-  // An existing key wins because it may hold a human translation; only the new keys are added.
-  // Deep, so a nested catalog gains `site.blog.title` without losing the rest of `site`.
-  const { merged, gained } = mergeJsonDeep(existing, generated);
-  // Every key the generator wants is already there — leave the file untouched and unclaimed.
-  if (!gained) return { kind: 'skip' };
-  return { kind: 'write', file, absolute, contents: prettyJson(merged) };
-}
-
-/**
- * What one generated file would do, decided without doing it. The merge case computes its own
- * bytes here rather than at the write, so the two passes below cannot disagree about a file.
- */
-type WritePlan =
-  | {
-      readonly kind: 'write';
-      readonly file: GeneratedFile;
-      readonly absolute: string;
-      readonly contents: string | Uint8Array;
-    }
-  | { readonly kind: 'skip' }
-  | { readonly kind: 'conflict'; readonly finding: Finding };
-
-function planFile(
-  file: GeneratedFile,
-  absolute: string,
-  force: boolean,
-  invocation: string,
-): 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
-  // overwritten, `--force` included. `--force` is about the primitive the author named; clobbering
-  // `policy.ts` to regenerate one action would delete every rule they wrote. Regenerating a slice
-  // module is `x g entity|policy`.
-  if (file.merge === 'if-absent') {
-    return existsSync(absolute)
-      ? { kind: 'skip' }
-      : { kind: 'write', file, absolute, contents: file.contents };
-  }
-  if (!force && existsSync(absolute)) {
-    return {
-      kind: 'conflict',
-      finding: {
-        code: 'X_GENERATE_CONFLICT',
-        cause: `${file.path} already exists`,
-        // 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`,
-        docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
-        at: file.path,
-      },
-    };
-  }
-  return { kind: 'write', file, absolute, contents: file.contents };
-}
-
-/**
- * Never clobbers, and never half-writes. A generator that overwrites is a generator nobody runs
- * twice; a generator that lands four of seven files and then reports a conflict is worse, because
- * the next run conflicts on the files the failed one wrote.
- *
- * Two passes, and the split is the point: the first decides — containment, existence, whether a
- * catalog can be merged into — and touches nothing, the second writes only when the first found
- * no conflict at all. Containment was already proven up front and the rest was not.
- */
-export async function writeFiles(
-  root: string,
-  files: readonly GeneratedFile[],
-  force: boolean,
-  /**
-   * The command line that produced these files, so a conflict's `fix:` can hand it back with
-   * `--force` on the end. Optional for a caller assembling files itself; the fallback is the
-   * shape, not a runnable line, and every generator path supplies the real one.
-   */
-  invocation = 'x g <kind> <name>',
-): Promise<WriteReport> {
-  const plans: WritePlan[] = [];
-  for (const file of files) {
-    const absolute = containedPath(root, file.path);
-    plans.push(
-      file.merge === 'json'
-        ? await planJsonMerge(file, absolute)
-        : planFile(file, absolute, force, invocation),
-    );
-  }
-  const conflicts = plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
-  if (conflicts.length > 0) return { written: [], conflicts };
-
-  const written: string[] = [];
-  for (const plan of plans) {
-    if (plan.kind !== 'write') continue;
-    // Bun.write creates missing parent directories, so a generator never needs an mkdir step.
-    await Bun.write(plan.absolute, plan.contents);
-    written.push(plan.file.path);
-  }
-  return { written, conflicts: [] };
-}
+export type { WriteReport } from './generate-write';
+export { dedupe, writeFiles } from './generate-write';
 
 const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
 
@@ -425,6 +89,9 @@ export const generateCommand: CliCommand = {
     const locales = resolveLocales(flagList(ctx.args, 'locales'));
     const at = flagString(ctx.args, 'at');
     const permission = flagString(ctx.args, 'permission');
+    // Read before a file is planned, like the flags above: which module a generated component
+    // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
+    const catalogModule = await resolveCatalogModule(root);
     const files = generate({
       kind,
       name,
@@ -435,6 +102,7 @@ export const generateCommand: CliCommand = {
       live: flagBool(ctx.args, 'live'),
       admin: flagBool(ctx.args, 'admin'),
       locales,
+      ...(catalogModule === undefined ? {} : { catalogModule }),
     });
     if (flagBool(ctx.args, 'dry-run')) {
       return {

package/src/cmd-i18n.ts

@@ -8,7 +8,7 @@
 // would, and `node:path` because Bun exposes no path API to build what either of them takes.
 import { type FileHandle, mkdir, open } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { catalogKeys, catalogMissingKeys } from '@ultimat3/i18n';
+import { catalogKeys } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -21,9 +21,9 @@ import {
   serializeCatalog,
   syncCatalog,
 } from './i18n-audit';
+import { checkRegistration, missingKeyFindings } from './i18n-registration';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
-import { findingFrom } from './output';
 import { renderTable } from './table';
 import { catalogPath, resolveLocales } from './templates/locales';
 
@@ -102,21 +102,24 @@ function resolveOneLocale(ctx: CommandContext, sub: string): string {
 }
 
 async function runCheck(root: string): Promise<CommandResult> {
-  const { report, catalogs } = await auditApp(root);
-
-  const findings: Finding[] = report.locales
-    .filter((audit) => audit.missing.length > 0)
-    .map((audit) => ({
-      ...findingFrom(catalogMissingKeys(audit.locale, audit.missing)),
-      at: catalogPath(audit.locale),
-    }));
-
-  const header = ['locale', 'keys', 'missing', 'unused'];
+  const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
+  // The runtime question, asked after the file question and never instead of it: a catalog can be
+  // complete on disk, used everywhere in source, and reach no registry at all (issue #249).
+  const registration = await checkRegistration({ root, catalogs, extraction, ignoreUnused });
+
+  const findings: Finding[] = [...missingKeyFindings(report), ...registration.findings];
+
+  // Whether the LOCALE has a catalog is the wrong question — the framework's own `en` is always
+  // registered, so a locale-presence column reads `yes` for an app whose every key is a loud miss.
+  // The column answers the key-level one: does the registry hold what this file defines?
+  const unregistered = new Set(registration.unregisteredLocales);
+  const header = ['locale', 'keys', 'missing', 'unused', 'registered'];
   const rows = report.locales.map((audit) => [
     audit.locale,
     String(catalogKeys(catalogs[audit.locale] ?? {}).length),
     String(audit.missing.length),
     String(audit.unused.length),
+    unregistered.has(audit.locale) ? 'no' : 'yes',
   ]);
   const lines = renderTable(header, rows).map((line) => `  ${line}`);
 
@@ -135,13 +138,26 @@ async function runCheck(root: string): Promise<CommandResult> {
     }
   }
 
-  const gapLocales = report.locales.filter((audit) => audit.missing.length > 0).length;
-  const missingTotal = report.locales.reduce((sum, audit) => sum + audit.missing.length, 0);
-  const summary = report.ok
+  // A key that renders a loud miss counts once, whichever half of the check found it: a missing
+  // catalog entry and an entry no registry holds are the same `⟦key⟧` on the same page.
+  const gapLocales =
+    report.locales.filter((audit) => audit.missing.length > 0).length + registration.locales;
+  const missingTotal =
+    report.locales.reduce((sum, audit) => sum + audit.missing.length, 0) +
+    registration.unregistered;
+  const ok = report.ok && registration.ok;
+  const summary = ok
     ? msg('cli.i18n.ok', { locales: report.locales.length, keys: report.used.length })
     : msg('cli.i18n.gaps', { missing: missingTotal, locales: gapLocales });
 
-  return { ok: report.ok, command: 'i18n', summary, lines, findings, data: asJson(report) };
+  return {
+    ok,
+    command: 'i18n',
+    summary,
+    lines,
+    findings,
+    data: { ...asJson(report), ok, registered: [...registration.registered] },
+  };
 }
 
 async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult> {