@ultimat3/cli 5.0.1 → 7.0.0

package/src/generate-write.ts

@@ -0,0 +1,229 @@
+// From a generator's file list to the disk: one entry per path, catalogs merged rather than
+// clobbered, and nothing written at all if any file would conflict. Split from `cmd-generate.ts`,
+// 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.
+import { existsSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { GenerateJsonInvalidError, ScaffoldPathEscapeError } from './errors';
+import { mergeJsonDeep } from './json-merge';
+import type { Finding } from './output';
+import type { GeneratedFile } from './templates';
+
+/** `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()];
+}
+
+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: [] };
+}

package/src/gh-target.ts

@@ -0,0 +1,118 @@
+// Which repository, which pull request, which branch — the three facts `x pr` and `x ci` both
+// need before they can ask GitHub anything, resolved once here so the two commands can never
+// disagree about what "this checkout" means.
+
+import { UltimateError } from '@ultimat3/core';
+import { t } from '@ultimat3/schema';
+import { BadFlagError } from './errors';
+import type { GhHost } from './gh';
+import { GhFailedError, ghJson } from './gh';
+
+/** `owner/name`, split once so a caller never re-splits it and never re-joins it wrong. */
+export interface GhRepo {
+  readonly owner: string;
+  readonly name: string;
+  /** The `owner/name` spelling, which is what `--repo` takes and what every render prints. */
+  readonly slug: string;
+}
+
+/**
+ * A repository name is `[A-Za-z0-9._-]+` on both sides of one slash. Refused here rather than by
+ * GitHub, because `--repo` is the one field a caller types by hand: `--repo ultimate` reaches the
+ * API as an owner with no name and comes back `Could not resolve to a Repository`, which reads as
+ * "that repository is gone" rather than "that is not a repository reference".
+ */
+const SLUG = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+const REPO_VIEW = t.object({ nameWithOwner: t.string });
+
+/** No pull request for the branch this checkout is on. A number the caller knows closes it. */
+export class PrNotFoundError extends UltimateError {
+  constructor(input: { detail: string }) {
+    super({
+      code: 'X_PR_NOT_FOUND',
+      cause: `GitHub reports no pull request for this checkout: ${input.detail}`,
+      fix: 'x pr review --pr 241 --json   # or open one first with: gh pr create',
+    });
+  }
+}
+
+/**
+ * The repository this command is about. `--repo` when given, otherwise `gh repo view`, which
+ * resolves the same remote `gh pr` and `gh run` resolve — asking git for the remote here would be
+ * a second answer to a question gh already owns.
+ */
+export async function resolveRepo(
+  host: GhHost,
+  command: string,
+  flag: string | undefined,
+): Promise<GhRepo> {
+  if (flag !== undefined) {
+    if (!SLUG.test(flag)) {
+      throw new BadFlagError({
+        flag: 'repo',
+        command,
+        reason: `"${flag}" is not an owner/name repository reference`,
+        fix: `x ${command} --repo developerz-ai/ultimate --json`,
+      });
+    }
+    return repoOf(flag);
+  }
+  const viewed = await ghJson(host, ['repo', 'view', '--json', 'nameWithOwner'], REPO_VIEW, {
+    label: 'gh repo view',
+    fix: `x ${command} --repo developerz-ai/ultimate --json`,
+  });
+  return repoOf(viewed.nameWithOwner);
+}
+
+function repoOf(slug: string): GhRepo {
+  const [owner = '', name = ''] = slug.split('/');
+  return { owner, name, slug };
+}
+
+const PR_VIEW = t.object({ number: t.number });
+
+/**
+ * The pull request for the current branch. gh exits non-zero when there is none, with a message
+ * that names the branch — so the refusal keeps gh's own sentence and adds the remedy gh has no
+ * opinion about: name the number, or open the PR.
+ */
+export async function resolvePrNumber(host: GhHost, repo: GhRepo): Promise<number> {
+  try {
+    const viewed = await ghJson(
+      host,
+      ['pr', 'view', '--repo', repo.slug, '--json', 'number'],
+      PR_VIEW,
+      { label: 'gh pr view', fix: 'x pr review --pr 241 --json' },
+    );
+    return viewed.number;
+  } catch (error) {
+    if (error instanceof GhFailedError) throw new PrNotFoundError({ detail: error.cause });
+    throw error;
+  }
+}
+
+/**
+ * The branch this checkout is on, from git rather than from gh: gh has no "current branch"
+ * question, only commands that answer one for you. A detached HEAD answers `HEAD`, which matches
+ * no branch on GitHub — the caller's own "no run for this branch" refusal names `--branch`, so a
+ * second refusal here would only move the same instruction one step earlier.
+ *
+ * Spawn failures are deliberately NOT caught: `exec.ts` refuses a missing program with a fix that
+ * already names `git`, and re-labelling that as a GitHub problem would send the reader to the
+ * wrong install.
+ */
+export async function currentBranch(host: GhHost): Promise<string> {
+  const result = await host.runner(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: host.cwd,
+  });
+  if (!result.ok) {
+    throw new GhFailedError({
+      label: 'git rev-parse --abbrev-ref HEAD',
+      code: result.code,
+      detail: result.stderr.split('\n')[0]?.trim() ?? '',
+      fix: 'x ci --branch main --json',
+    });
+  }
+  return result.stdout.trim();
+}

package/src/gh.ts

@@ -0,0 +1,204 @@
+// The one seam between the CLI and the `gh` binary. Every GitHub call is built here and spawned
+// through the injected `Runner`, so a test asserts the exact argv with no network and no `gh`
+// installed — and the four ways this shell-out fails (no binary, no credentials, a non-zero exit,
+// an answer that will not parse) each get one code and one executable fix instead of a stack trace.
+
+import { renderThrowable, singleLine, UltimateError } from '@ultimat3/core';
+import type { AnySchema, InferOutput } from '@ultimat3/schema';
+import { formatPath } from '@ultimat3/schema';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+
+/** What a gh call needs from a `CommandContext`, and nothing more — so a test passes two fields. */
+export interface GhHost {
+  readonly runner: Runner;
+  readonly cwd: string;
+}
+
+export interface GhOptions {
+  /**
+   * A short name for this call. Every refusal is titled with it rather than with the argv,
+   * because a GraphQL document pasted into a `cause:` is a page of text where a reader needs a
+   * sentence.
+   */
+  readonly label: string;
+  /**
+   * The caller's remedy, and REQUIRED: the seam knows a call failed and never what the operator
+   * was trying to do, so a generic fix here would be axiom 4 inverted at the one boundary every
+   * GitHub call crosses. Making it a field of the options is what turns "state a remedy" into a
+   * build error rather than a convention.
+   */
+  readonly fix: string;
+}
+
+/** The one binary this file spawns. Named once, so every argv assertion has a single source. */
+export const GH_BIN = 'gh';
+
+/**
+ * No `gh` on PATH. `exec.ts` already refuses a missing program with `X_CLI_UNEXPECTED`, and that
+ * code's fix names the binary — but "the CLI itself failed" is the wrong sentence for a machine
+ * that simply has no GitHub client, and `gh auth login` is not reachable from it.
+ */
+export class GhUnavailableError extends UltimateError {
+  constructor(input: { cwd: string; detail: string }) {
+    super({
+      code: 'X_GH_UNAVAILABLE',
+      cause: `the GitHub CLI could not be run from ${input.cwd}: ${input.detail}`,
+      fix: 'install the GitHub CLI from https://cli.github.com, then run: gh auth login',
+    });
+  }
+}
+
+/** `gh` is installed and holds no usable credentials for this host. One command closes it. */
+export class GhNotAuthenticatedError extends UltimateError {
+  constructor(input: { label: string; detail: string }) {
+    super({
+      code: 'X_GH_NOT_AUTHENTICATED',
+      cause: `${input.label} was refused by GitHub: ${input.detail}`,
+      fix: 'gh auth login',
+    });
+  }
+}
+
+/** Any other non-zero exit — a bad id, a repository that is not there, a rate limit. */
+export class GhFailedError extends UltimateError {
+  constructor(input: { label: string; code: number; detail: string; fix: string }) {
+    super({
+      code: 'X_GH_COMMAND_FAILED',
+      cause: `${input.label} exited ${input.code}: ${input.detail}`,
+      fix: input.fix,
+    });
+  }
+}
+
+/**
+ * `gh` answered, and the answer is not the shape this command reads. A cast would carry the
+ * mismatch into the render and print `undefined` at whichever field moved; the parse refuses at
+ * the boundary instead, which is the only place the argv that produced it is still known.
+ */
+export class GhResponseInvalidError extends UltimateError {
+  constructor(input: { label: string; detail: string; fix: string }) {
+    super({
+      code: 'X_GH_RESPONSE_INVALID',
+      cause: `${input.label} answered something this command cannot read: ${input.detail}`,
+      fix: input.fix,
+    });
+  }
+}
+
+/**
+ * The spellings `gh` uses when the token is the problem. Matched against its own output rather
+ * than against an exit code, because every one of these exits 1 exactly like a typo'd id does —
+ * and the two have different remedies.
+ */
+const UNAUTHENTICATED =
+  /not logged in|gh auth login|HTTP 401|Bad credentials|GH_TOKEN|GITHUB_TOKEN|authentication/i;
+
+/** The first line a human would read, escaped and bounded — a `cause:` is one line by contract. */
+export function ghDetail(result: ExecResult): string {
+  const merged = execOutput(result);
+  const first = merged.split('\n').find((line) => line.trim().length > 0) ?? '';
+  const text = singleLine(first.trim().replace(/^gh:\s*/, ''));
+  return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+
+/**
+ * One `gh` invocation, refused four ways. A spawn failure is mapped rather than rethrown: it is
+ * the "no GitHub CLI on this machine" case, and `exec.ts`'s own refusal cannot offer `gh auth
+ * login` as the next step.
+ */
+export async function runGh(
+  host: GhHost,
+  args: readonly string[],
+  options: GhOptions,
+): Promise<ExecResult> {
+  let result: ExecResult;
+  try {
+    result = await host.runner([GH_BIN, ...args], { cwd: host.cwd });
+  } catch (error) {
+    // Never interpolated: the thrown value is genuinely unknown here (Bun raises `ENOENT` for a
+    // missing program and `EACCES` for an unrunnable one), which is what `bun run error-render`
+    // refuses to see reach a `cause:` through `${…}`.
+    throw new GhUnavailableError({ cwd: host.cwd, detail: renderThrowable(error) });
+  }
+  if (result.ok) return result;
+  const detail = ghDetail(result);
+  if (UNAUTHENTICATED.test(detail)) {
+    throw new GhNotAuthenticatedError({ label: options.label, detail });
+  }
+  throw new GhFailedError({ label: options.label, code: result.code, detail, fix: options.fix });
+}
+
+/**
+ * `gh --json`, parsed rather than cast. The response is untrusted input — a different `gh`
+ * version, a proxy that answered HTML, a field GitHub renamed — so it goes through the schema the
+ * caller declared and a mismatch is a coded refusal naming the call that produced it.
+ */
+export async function ghJson<S extends AnySchema>(
+  host: GhHost,
+  args: readonly string[],
+  schema: S,
+  options: GhOptions,
+): Promise<InferOutput<S>> {
+  const result = await runGh(host, args, options);
+  let payload: unknown;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new GhResponseInvalidError({
+      label: options.label,
+      detail: renderThrowable(error),
+      fix: options.fix,
+    });
+  }
+  const parsed = schema.safeParse(payload);
+  if (parsed.issues !== undefined) {
+    const first = parsed.issues[0];
+    // `formatPath` is the schema package's own renderer for an issue path — a second spelling of
+    // `items[0].price` here would be a field name that does not match the one every other
+    // validation failure in the framework prints.
+    throw new GhResponseInvalidError({
+      label: options.label,
+      detail:
+        first === undefined
+          ? 'the response matched no field this command declares'
+          : `${formatPath(first.path)} ${first.message}`.trim(),
+      fix: options.fix,
+    });
+  }
+  return parsed.value as InferOutput<S>;
+}
+
+/**
+ * A GraphQL call, and the two `gh` field flags are not interchangeable — the type of the variable
+ * decides which one is correct, so the type of the value decides here.
+ *
+ * A **string** rides as `-f`, never `-F`: `-F` reads `@file` as "load this from disk", so a review
+ * reply whose body begins with an `@` would post the contents of a local file. A **number** has to
+ * ride as `-F`, because `-f` sends every value as a GraphQL `String` and a `$n:Int!` parameter
+ * refuses one (measured: `gh api graphql … -f n=238` against `Int!` is a `variableNotUsed`/type
+ * error, `-F n=238` succeeds). `-F` is safe for a number precisely because a number can never
+ * spell `@file`.
+ *
+ * The caller's schema describes the WHOLE envelope (`{ data: … }`) rather than its inside: gh
+ * exits non-zero whenever the response carries `errors`, so a partial answer never reaches here,
+ * and a caller that spells out the envelope keeps every nullable GitHub returns visible.
+ */
+export async function ghGraphql<S extends AnySchema>(
+  host: GhHost,
+  document: string,
+  variables: Readonly<Record<string, string | number>>,
+  schema: S,
+  options: GhOptions,
+): Promise<InferOutput<S>> {
+  const args = [
+    'api',
+    'graphql',
+    '-f',
+    `query=${document}`,
+    ...Object.entries(variables).flatMap(([name, value]) =>
+      typeof value === 'number' ? ['-F', `${name}=${value}`] : ['-f', `${name}=${value}`],
+    ),
+  ];
+  return ghJson(host, args, schema, options);
+}

package/src/i18n-audit.ts

@@ -79,6 +79,11 @@ export async function loadCatalogs(root: string): Promise<Readonly<Record<Locale
 export interface AuditFacts {
   readonly report: ExtractReport;
   readonly catalogs: Readonly<Record<Locale, Catalog>>;
+  /** The raw scan, carried so the runtime half can re-audit against the REGISTRY rather than
+   * against the files — same keys, same plural rules, a different question. */
+  readonly extraction: Extraction;
+  /** The `prefix*` patterns derived from dynamic calls, carried for the same reason. */
+  readonly ignoreUnused: readonly string[];
 }
 
 /** The static head of a template literal, up to its first interpolation. */
@@ -105,7 +110,12 @@ export function runtimeKeyPatterns(extraction: Extraction): readonly string[] {
 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 }), catalogs };
+  return {
+    report: auditCatalogs({ extraction, catalogs, ignoreUnused }),
+    catalogs,
+    extraction,
+    ignoreUnused,
+  };
 }
 
 /**
@@ -130,6 +140,34 @@ export function resolveDefaultLocale(
   return locales.length === 1 ? locales[0] : undefined;
 }
 
+/** Where an app's catalog module declares its own package name. */
+const I18N_PACKAGE_JSON = 'packages/i18n/package.json';
+
+/**
+ * The specifier a generated page imports `useT()` from — `@<app>/i18n`, read off the app's own
+ * manifest rather than derived from a directory name, because the package name is the only thing
+ * a TypeScript import can actually resolve.
+ *
+ * `undefined` when the app ships no catalog package, and every generator falls back to `t` from
+ * `@ultimat3/i18n` there: emitting an import that cannot resolve trades a wrong idiom for a file
+ * that does not compile. A manifest that will not parse, or names nothing, answers the same way —
+ * this is a generator convenience, and refusing to scaffold over it would be the wrong verdict.
+ */
+export async function resolveCatalogModule(root: string): Promise<string | undefined> {
+  const path = join(root, I18N_PACKAGE_JSON);
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed: unknown = await Bun.file(path).json();
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    const name = (parsed as { name?: unknown }).name;
+    return typeof name === 'string' && name.length > 0 ? name : undefined;
+  } catch {
+    // Deliberately silent: `x g route` writing a page is not the command that should refuse an
+    // app over a malformed manifest, and `bun install` already does.
+    return undefined;
+  }
+}
+
 /**
  * A sorted copy of `catalog`. Every write below goes through this, so a later `sync` (or a second
  * `add`) diffs only the keys that actually changed, never a reshuffle.