@ultimat3/cli 5.0.0 → 6.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/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.

package/src/i18n-registration.ts

@@ -0,0 +1,130 @@
+// Every finding about an app's strings, and the one composition `x i18n check` and `x verify`'s
+// `i18n` step both report — two callers, one answer, so the command and the gate can never
+// disagree. The runtime half is here because nothing else could ask it: `i18n-audit.ts` compares
+// source against files on disk and was green for every string of a shipped app whose catalog
+// module nothing imported (issue #249).
+
+import type { Catalog, Extraction, ExtractReport, Locale } from '@ultimat3/i18n';
+import {
+  auditCatalogs,
+  catalogFor,
+  catalogMissingKeys,
+  catalogRegistrationGaps,
+  catalogsNeverRegistered,
+  catalogUnregistered,
+  registeredLocales,
+} from '@ultimat3/i18n';
+import { loadApp } from './app-load';
+import { auditApp } from './i18n-audit';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { catalogPath } from './templates/locales';
+
+/**
+ * What this check needs of a boot. The seam is injected so a fixture can be exactly "the app
+ * loaded and registered nothing" — the shipped shape of the bug — without a temp directory that
+ * can resolve `@ultimat3/*`. `loadApp` is the production value, and it is the same call
+ * `serveApp` makes: asking a different loader than the server uses would prove nothing.
+ */
+export type AppLoader = (root: string) => Promise<{
+  readonly findings: readonly Finding[];
+  readonly defaultLocale: string;
+}>;
+
+export interface RegistrationInput {
+  readonly root: string;
+  /** The catalogs on disk, parsed — `packages/i18n/catalogs/*.json`. */
+  readonly catalogs: Readonly<Record<Locale, Catalog>>;
+  readonly extraction: Extraction;
+  readonly ignoreUnused: readonly string[];
+  readonly load?: AppLoader;
+}
+
+export interface RegistrationReport {
+  readonly ok: boolean;
+  readonly findings: readonly Finding[];
+  /** Keys that would render a loud miss because registration never happened. */
+  readonly unregistered: number;
+  /** How many locales are affected — one row of the summary's "across N locale(s)". */
+  readonly locales: number;
+  /** Which shipped locales the registry cannot fully answer — the `registered` column's `no`. */
+  readonly unregisteredLocales: readonly Locale[];
+  /** Every locale the registry holds after the load, sorted. Empty is not possible in a real
+   * boot: the framework's own catalog is the base layer, so `['en']` is the floor. */
+  readonly registered: readonly Locale[];
+}
+
+/**
+ * The app ships nothing on disk, so there is no file to diff — the only evidence left is whether
+ * the keys source actually uses resolve. Audited through `auditCatalogs` rather than a fresh
+ * `hasOwn` loop, because a plural family is defined as `n_one`/`n_other` and a bare lookup of the
+ * stem `n` would report every plural in the app as unresolved.
+ */
+function unresolvedUsedKeys(input: RegistrationInput, locale: Locale): readonly string[] {
+  const report = auditCatalogs({
+    extraction: input.extraction,
+    catalogs: { [locale]: catalogFor(locale) },
+    ignoreUnused: input.ignoreUnused,
+  });
+  return report.locales[0]?.missing ?? [];
+}
+
+export async function checkRegistration(input: RegistrationInput): Promise<RegistrationReport> {
+  // Importing the app's modules IS the registration, in this process exactly as in the server's.
+  const app = await (input.load ?? loadApp)(input.root);
+
+  const gaps = catalogRegistrationGaps(input.catalogs);
+  const findings: Finding[] = gaps.map((gap) => ({
+    ...findingFrom(catalogUnregistered(gap)),
+    at: catalogPath(gap.locale),
+  }));
+  let unregistered = gaps.reduce((sum, gap) => sum + gap.missing.length, 0);
+  let locales = gaps.length;
+
+  if (Object.keys(input.catalogs).length === 0) {
+    const unresolved = unresolvedUsedKeys(input, app.defaultLocale);
+    if (unresolved.length > 0) {
+      findings.push(findingFrom(catalogsNeverRegistered(app.defaultLocale, unresolved)));
+      unregistered += unresolved.length;
+      locales += 1;
+    }
+  }
+
+  return {
+    ok: findings.length === 0,
+    // The load's own findings ride along ONLY when something is unregistered, and that condition is
+    // the whole value: a module that would not import registers nothing, so "packages/i18n/src/
+    // index.ts: SyntaxError" is the evidence for the gap above it. With every catalog registered, a
+    // broken route file is not this command's business and reporting it would be noise on a pass.
+    findings: findings.length === 0 ? findings : [...findings, ...app.findings],
+    unregistered,
+    locales,
+    unregisteredLocales: gaps.map((gap) => gap.locale),
+    registered: registeredLocales(),
+  };
+}
+
+/**
+ * The file half: a key source uses that a locale's catalog does not define. Built here rather than
+ * in `cmd-i18n.ts` because `x verify`'s `i18n` step reports 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
+    .filter((audit) => audit.missing.length > 0)
+    .map((audit) => ({
+      ...findingFrom(catalogMissingKeys(audit.locale, audit.missing)),
+      at: catalogPath(audit.locale),
+    }));
+}
+
+/**
+ * Both halves of one question — does every string this app renders resolve? — for a caller that
+ * wants the verdict and not the table. `x verify`'s `i18n` step is that caller; `cmd-i18n.ts`
+ * composes the same two pieces itself because it also renders per-locale rows.
+ */
+export async function catalogFindings(root: string): Promise<readonly Finding[]> {
+  const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
+  const registration = await checkRegistration({ root, catalogs, extraction, ignoreUnused });
+  return [...missingKeyFindings(report), ...registration.findings];
+}

package/src/island-bundle.ts

@@ -13,6 +13,7 @@ import {
   islandModuleId,
 } from '@ultimat3/render';
 import { IslandBuildFailedError } from './errors';
+import { solidJsxPlugin } from './solid-loader';
 
 /**
  * Where a chunk is served from, in `x dev`, in the container and in a static export — one base
@@ -78,6 +79,12 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       format: 'esm',
       splitting: false,
       minify: true,
+      // A build with no `plugins` is a build with no JSX transform: `Bun.plugin` installs into the
+      // RUNTIME's loader and `Bun.build` walks its own graph, so render's `.tsx` loader never sees
+      // an island. The app's tsconfig says `jsx: "preserve"`, which makes the bundler fall back to
+      // classic `React.createElement` — emitted into a browser chunk that imports no React, with
+      // `success: true` and no log. Every island shipped that way through five majors.
+      plugins: [solidJsxPlugin],
     });
   } catch (error) {
     throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });

package/src/mcp-errors.ts

@@ -91,6 +91,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_RUNTIME_DRIVER_SPLIT: 'x dev --json   # the boot names the driver the app installed twice',
   X_GENERATE_CONFLICT: 'x g route posts --force --json',
   X_PORT_IN_USE: 'x dev --port 3001 --json',
+  X_DEV_ALREADY_RUNNING:
+    'x dev --json   # after stopping the x dev that already owns this checkout',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
   // reachability and drift, and is already this table's answer for X_DB_STUDIO_FAILED.

package/src/messages.ts

@@ -72,6 +72,9 @@ const CATALOG = {
   'cli.dev.mail.external': 'mail=external({driver} via {detail})',
   'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
+  // A hard kill leaves the lock behind and that is normal, not a fault — worth one line so a
+  // reader knows why the boot paused, and never a finding.
+  'cli.dev.staleLock': 'cleared a stale dev.lock — the previous x dev did not shut down cleanly',
   'cli.dev.roles': '  roles {roles}',
   'cli.dev.panels': '  panels {panels}',
   'cli.dev.introspect': '  introspect {url}',

package/src/solid-loader.ts

@@ -0,0 +1,127 @@
+// The JSX transform every island chunk is built with: `.tsx` → Solid's COMPILED DOM output, run by
+// `babel-preset-solid` inside the island `Bun.build`'s own plugin. Solid's reactivity is a
+// COMPILE-time contract, which is why no runtime factory can stand in for the compiler here.
+
+/// <reference path="../types/babel-modules.d.ts" />
+// The reference is load-bearing, not decorative: @ultimat3/cli ships SOURCE, so an APP's
+// `tsc` compiles this file inside ITS program, where a `.d.ts` sitting in this directory is
+// not included and its `declare module` never applies. `tsc -b` proves it in this repo.
+import { transformAsync } from '@babel/core';
+import { contentHash } from '@ultimat3/render';
+import solidPreset from 'babel-preset-solid';
+import type { BunPlugin } from 'bun';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * `generate: 'dom'` because an island runs in a browser and nowhere else; `hydratable: false`
+ * because an island MOUNTS over server markup through its own `mount(el, props)` rather than
+ * resuming a Solid hydration tree — there is no `renderToString` pass on the other side of it, so
+ * hydration markers would be per-node bytes with no reader.
+ */
+const PRESET_OPTIONS = { generate: 'dom', hydratable: false } as const;
+
+/**
+ * The parser plugins, given DIRECTLY rather than through `@babel/plugin-syntax-typescript`. That
+ * plugin does nothing but push this same array, and Babel 8 deleted its `isTSX` option — so the
+ * documented spelling silently stops parsing JSX and every `<` becomes a type parameter. Given
+ * here the option surface is Babel's parser, which has never moved.
+ *
+ * Order is inert here and is NOT inert via `plugins:` — as plugin entries, the JSX one must precede
+ * the TypeScript one or `<button` parses as a type-parameter list. One more reason to say it once,
+ * here.
+ */
+const PARSER_PLUGINS = ['typescript', 'jsx'] as const;
+
+interface CacheEntry {
+  /** `contentHash` of the source the code was compiled from. */
+  readonly hash: string;
+  readonly code: string;
+}
+
+/**
+ * Keyed by PATH, not by content hash: `x dev` re-runs `buildIslands` on every change, and a map
+ * keyed by content would grow one entry per keystroke for the life of the process. One entry per
+ * island file is bounded by the island count, which is the only quantity that should bound it.
+ *
+ * It never hits inside a single `x build` — `discoverIslands` yields unique paths and `buildOne`
+ * runs once each. The dev loop is the whole reason it exists: Babel is ~8.7ms a file against
+ * `Bun.Transpiler`'s 0.07ms, so an app with twenty islands re-compiles nineteen unchanged files on
+ * every rebuild without this.
+ */
+const cache = new Map<string, CacheEntry>();
+
+/** Test seam: the cache is process-global because the dev server it serves is too. */
+export function clearIslandTransformCache(): void {
+  cache.clear();
+}
+
+/**
+ * `.tsx` source → Solid's compiled DOM expressions. Exported so the transform is testable as a
+ * function of its two inputs: the plugin below is the four lines of glue that hand it a file.
+ *
+ * The output is still TypeScript — Babel PARSES the annotations here and does not strip them,
+ * which is why the plugin declares `loader: 'ts'` and lets Bun remove them.
+ */
+export async function transformIslandTsx(source: string, path: string): Promise<string> {
+  const hash = contentHash(source);
+  const hit = cache.get(path);
+  if (hit !== undefined && hit.hash === hash) return hit.code;
+
+  // Babel installs its own `prepareStackTrace` on the first TRANSFORM — not on import, which is
+  // where this guard was first put — and leaving it installed makes `Error.captureStackTrace`
+  // strict for every unrelated module loaded later in the same process.
+  const saved = Error.prepareStackTrace;
+  let code: string | null | undefined;
+  try {
+    // `transformAsync` and never `transformFileAsync`: the latter is gated behind `@babel/core`'s
+    // `browser` export condition and throws "Transforming files is not supported in browsers"
+    // under `bun --conditions=browser`, which is the condition Solid work runs in.
+    const result = await transformAsync(source, {
+      filename: path,
+      // The app's own Babel config is not this transform's business, and an app that happens to
+      // have one must not change what its islands compile to.
+      babelrc: false,
+      configFile: false,
+      parserOpts: { plugins: [...PARSER_PLUGINS] },
+      presets: [[solidPreset, PRESET_OPTIONS]],
+    });
+    code = result?.code;
+  } finally {
+    Error.prepareStackTrace = saved;
+  }
+  // A parse error is NOT caught here: Babel's own message already names the file, the line and the
+  // column ("a.island.tsx: Unexpected token (2:23)"), and `buildOne` wraps whatever escapes in
+  // `X_BUILD_FAILED` naming the island. Re-wrapping it here would only bury that.
+  if (code == null) {
+    throw new IslandBuildFailedError({
+      file: path,
+      logs: 'the Solid JSX transform emitted no code',
+    });
+  }
+  cache.set(path, { hash, code });
+  return code;
+}
+
+/**
+ * The plugin `island-bundle.ts` hands `Bun.build`. It carries no state of its own, so one frozen
+ * descriptor serves every concurrent island build — `Bun.build` calls `setup` once per build with
+ * that build's own builder.
+ *
+ * `.tsx`, NOT `.island.tsx`. The narrow filter looks like axiom 6 and is the opposite of it: an
+ * island that imports a plain `.tsx` component — the most ordinary thing an author does, and what
+ * `x g resource` generates — would have that component compiled by nobody, and the app's
+ * `jsx: "preserve"` tsconfig turns it straight back into `React.createElement("span", …)` and
+ * `React is not defined`. Axiom 6 is already satisfied by GRAPH SEPARATION: this plugin runs
+ * inside the island build, whose graph only ever holds islands and what they import, and a page
+ * names its island by SPECIFIER and never imports one. So `.tsx` here already means exactly the
+ * set that ships to a browser — the filter never had to do that work.
+ */
+export const solidJsxPlugin: BunPlugin = {
+  name: 'ultimate-island-solid',
+  setup(build): void {
+    build.onLoad({ filter: /\.tsx$/ }, async ({ path }) => ({
+      contents: await transformIslandTsx(await Bun.file(path).text(), path),
+      loader: 'ts',
+    }));
+  },
+};

package/src/templates/admin-page.ts

@@ -23,11 +23,50 @@ export interface AdminPageOptions {
    */
   readonly dir?: string;
   readonly locales?: readonly string[];
+  /**
+   * The app's own catalog module — `@<app>/i18n`, read off `packages/i18n/package.json` by
+   * `resolveCatalogModule`. Absent only for an app that ships no such package.
+   */
+  readonly catalogModule?: string;
 }
 
 const titleKeyFor = (name: string): string => `admin.${name}.title`;
 
-const pageSource = (name: string, permission: string, dir: string): string => {
+/**
+ * The generated page reaches strings through the APP's catalog module — the one that calls
+ * `defineCatalogs()` — so a page that renders a string depends on the module that registers them.
+ * `t` from `@ultimat3/i18n` renders while depending on nothing, which is how a shipped app served
+ * every string as a loud miss with a green gate (issue #249). An app with no catalog module keeps
+ * the framework import: emitting one that cannot resolve is worse than the wrong idiom.
+ */
+const catalogImport = (module: string | undefined): string =>
+  module === undefined
+    ? "import { t } from '@ultimat3/i18n';"
+    : `import { useT } from '${module}';`;
+
+/**
+ * The two imports, in the order biome's organize-imports wants — which DEPENDS on the app's scope
+ * and cannot be hardcoded either way. An app catalog (`@myapp/i18n`) sorts BEFORE
+ * `@ultimat3/admin`; the fallback `@ultimat3/i18n` sorts AFTER it. Emitting one fixed order makes
+ * every generated admin page a lint error in exactly one of the two cases, and each case is
+ * covered by a different job — the fallback by `templates`' own linter test, the app-scoped one
+ * only by `scaffold-smoke`, which runs the generators against a real scaffold.
+ */
+const pageImports = (module: string | undefined): string =>
+  [`import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`, catalogImport(module)]
+    .sort((a, b) => (a.slice(a.indexOf("'")) < b.slice(b.indexOf("'")) ? -1 : 1))
+    .join('\n');
+
+/** `useT()` is per render, so the component binds it in its own body. */
+const translatorBinding = (module: string | undefined): string =>
+  module === undefined ? '' : '\n  const t = useT();\n';
+
+const pageSource = (
+  name: string,
+  permission: string,
+  dir: string,
+  module: string | undefined,
+): string => {
   const Name = pascal(name);
   const declaration = camel(name);
   return `// Admin page: /${name}. An ORDINARY component — there is no \`defineRoute\` here, deliberately:
@@ -39,10 +78,9 @@ const pageSource = (name: string, permission: string, dir: string): string => {
 //   import { ${declaration}Page } from './${name}';
 //   defineAdmin({ …, pages: […, ${declaration}Page] })
 
-import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';
-import { t } from '@ultimat3/i18n';
+${pageImports(module)}
 
-export function ${Name}Page(props: AdminPageProps) {
+export function ${Name}Page(props: AdminPageProps) {${translatorBinding(module)}
   return (
     <section>
       <h1>{t('${titleKeyFor(name)}')}</h1>
@@ -92,7 +130,10 @@ export function adminPageFiles(
   // Trailing slashes trimmed exactly as `islandFiles` does — one `--at`, one normalization.
   const dir = (options.dir ?? DEFAULT_ADMIN_PAGE_DIR).replace(/\/+$/, '');
   return [
-    { path: `${dir}/${name}.tsx`, contents: pageSource(name, options.permission, dir) },
+    {
+      path: `${dir}/${name}.tsx`,
+      contents: pageSource(name, options.permission, dir, options.catalogModule),
+    },
     { path: `${dir}/${name}.test.ts`, contents: pageTest(name, options.permission) },
     ...resolveLocales(options.locales).map((locale) => ({
       path: catalogPath(locale),