@nifrajs/cli 3.3.0 → 4.0.0

package/src/doctor.ts

@@ -19,7 +19,7 @@
 import type { Dirent } from "node:fs"
 import { readdir, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
-import { dirname, join, relative, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import {
   collectIdentityParity,
   displayPath,
@@ -29,7 +29,9 @@ import {
   resolvedInstalledCopy,
 } from "@nifrajs/web/internal/parity"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
-import { detectToolingDrift, type ToolingDrift } from "./mcp-root.ts"
+import { collectStaleMcpPins, type StaleMcpPin } from "./init-agents.ts"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
+import { detectToolingDrift, syncMcpCommand, type ToolingDrift } from "./mcp-root.ts"
 import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
 import { type ResolvedTarget, resolveTarget } from "./port.ts"
 import { buildScriptName } from "./workspace-link.ts"
@@ -46,8 +48,10 @@ const BUILTINS: ReadonlySet<string> = new Set<string>([
 // import, and CJS require. Anchored with `(?<![.\w$])` so `myimport`/`.import`/`foorequire` never match.
 // Comments are stripped before these run (see stripComments) - else a doc-comment usage example would be
 // flagged as a real import.
+// The clause before `from` is spelled out rather than scanned lazily: a lazy scan restarts at every
+// `export const` line and is quadratic on a long module with no string literal.
 const IMPORT_PATTERNS: readonly RegExp[] = [
-  /(?<![.\w$])(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g,
+  /(?<![.\w$])(?:import|export)\b\s*(?:type\b\s*)?(?:[\w$]+\s*,?\s*)?(?:\*\s*(?:as\b\s*[\w$]+\s*)?|\{[^{}'"]*\}\s*)?from\s*['"]([^'"]+)['"]/g,
   /(?<![.\w$])import\s+['"]([^'"]+)['"]/g,
   /(?<![.\w$])import\s*\(\s*['"]([^'"]+)['"]/g,
   /(?<![.\w$])require\s*\(\s*['"]([^'"]+)['"]/g,
@@ -126,7 +130,7 @@ export function scanUndeclaredImports(
       out.push({ file, line, snippet: pkg })
     }
   }
-  return out.sort((a, b) => a.line - b.line || a.snippet.localeCompare(b.snippet))
+  return out.sort((a, b) => a.line - b.line || codeUnitOrder(a.snippet, b.snippet))
 }
 
 export interface DoctorFinding {
@@ -174,8 +178,16 @@ export interface DoctorResult {
    * supplied and the feature versions disagree. Computed by {@link detectToolingDrift}.
    */
   readonly toolingDrift?: ToolingDrift
+  /**
+   * Agent files whose MCP launch pins an `@nifrajs/cli` other than the one the project installs, so
+   * the agent's server answers for a release the code no longer builds with. Advisory (never folded
+   * into `ok`). Present only when at least one file is stale. Computed by {@link collectStaleMcpPins}.
+   */
+  readonly staleMcpPins?: { readonly target: string; readonly files: readonly StaleMcpPin[] }
   /** Static production-readiness evidence for the selected deploy target. */
   readonly readiness?: DoctorReadiness
+  /** The explicit source boundary used by the dependency scan. */
+  readonly scanScope?: DoctorScanScope
   /**
    * Which bundler this app's `dev`/`build` phases run on, read statically, plus the config hazards
    * that exist only because there are two. Absent when the directory is not a nifra app.
@@ -191,6 +203,12 @@ export interface DoctorResult {
   readonly skippedFixes?: readonly DoctorSkippedFix[]
 }
 
+export interface DoctorScanScope {
+  readonly kind: "standalone" | "workspace-production"
+  readonly includeTests: boolean
+  readonly excluded: readonly string[]
+}
+
 export type DoctorReadinessStatus = "configured" | "absent" | "not-applicable"
 
 export interface DoctorReadinessItem {
@@ -577,7 +595,7 @@ export async function collectStaleWorkspaceDists(
       if (worst !== undefined) findings.push(worst)
     }
   }
-  return findings.sort((a, b) => a.package.localeCompare(b.package))
+  return findings.sort((a, b) => codeUnitOrder(a.package, b.package))
 }
 
 interface ReadinessSource {
@@ -615,7 +633,7 @@ async function collectDoctorReadiness(
   await walkSource(cwd, (file, source) => {
     files.push({ file, source, code: codePositionMask(source) })
   })
-  const edgeTarget = /^(?:cf-pages|vercel|workers|edge|static)$/.test(resolved?.target ?? "")
+  const edgeTarget = /^(?:cloudflare|vercel|workers|edge|static)$/.test(resolved?.target ?? "")
   const configured = (
     id: DoctorReadinessItem["id"],
     label: string,
@@ -705,13 +723,27 @@ async function ancestorDependencySpec(cwd: string, name: string): Promise<string
     const pkg = await readJson(join(dir, "package.json"))
     if (pkg !== undefined) {
       const spec = dependencySpec(pkg, name)
-      if (spec !== undefined) return spec
+      if (spec !== undefined) return rebaseDependencySpec(spec, dir, cwd)
     }
     const parent = dirname(dir)
     if (parent === dir) return undefined
   }
 }
 
+/**
+ * A path spec (`file:packages/x`, `link:../x`, `./vendor/x.tgz`) resolves against the package.json
+ * that declares it, so a spec copied from an ancestor is re-pointed to the same target from `cwd`.
+ */
+function rebaseDependencySpec(spec: string, declaredIn: string, cwd: string): string {
+  const protocol = /^(?:file|link|portal):/.exec(spec)?.[0] ?? ""
+  const path = spec.slice(protocol.length)
+  const relativePath =
+    protocol === "" ? /^\.\.?(?:[\\/]|$)/.test(path) : !isAbsolute(path) && !path.startsWith("~")
+  if (!relativePath) return spec
+  const rebased = relative(cwd, resolve(declaredIn, path)).replaceAll("\\", "/")
+  return protocol + (rebased === ".." || rebased.startsWith("../") ? rebased : `./${rebased}`)
+}
+
 async function installedPackageSpec(cwd: string, name: string): Promise<string | undefined> {
   if (!isNpmPackageName(name)) return undefined
   const parts = name.split("/")
@@ -751,9 +783,29 @@ export async function collectDoctorResult(
   const scopes = await doctorPackageScopes(cwd, pkg)
 
   const findings: DoctorFinding[] = []
-  // `includeTests`: tests are part of the typechecked surface, so an import they declare nowhere is a
-  // real break. Excluding them is what let an undeclared `zod` in a `*.test.ts` pass doctor, pass a
-  // hoisted local `tsc`, and then fail CI on a clean install with `TS2307: Cannot find module 'zod'`.
+  // A standalone app owns its tests, so they remain in the declaration check. A workspace root owns
+  // the published package source while its root devDependencies intentionally own shared tests,
+  // benchmarks, and scaffold copy-surfaces. Keep that boundary explicit instead of reporting a
+  // monorepo-wide false failure or silently dropping files from the result.
+  const workspaceProduction = workspacePatterns(pkg).length > 0
+  const scanScope: DoctorScanScope = Object.freeze({
+    kind: workspaceProduction ? "workspace-production" : "standalone",
+    includeTests: !workspaceProduction,
+    excluded: workspaceProduction
+      ? Object.freeze([
+          "**/test/**",
+          "**/test-node/**",
+          "bench/**",
+          "packages/create-nifra/template*/**",
+        ])
+      : Object.freeze([]),
+  })
+  const workspaceSurface = (rel: string): boolean =>
+    workspaceProduction &&
+    (/(^|\/)(?:test|test-node)\//.test(rel) ||
+      rel === "bench" ||
+      rel.startsWith("bench/") ||
+      rel.startsWith("packages/create-nifra/template"))
   await walkSource(
     cwd,
     (rel, content) => {
@@ -762,9 +814,9 @@ export async function collectDoctorResult(
         findings.push({ file: f.file, line: f.line, package: f.snippet })
       }
     },
-    { includeTests: true },
+    { includeTests: scanScope.includeTests, ignore: workspaceSurface },
   )
-  findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
+  findings.sort((a, b) => codeUnitOrder(a.file, b.file) || a.line - b.line)
   const identity = await collectAllDuplicateInstalls(cwd, pkg)
   const duplicateInstalls = identity.duplicates
   const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
@@ -776,7 +828,8 @@ export async function collectDoctorResult(
   // pass its own version (e.g. the MCP server, which already annotates every result with the drift).
   const toolingDrift =
     opts.cliVersion !== undefined ? await detectToolingDrift(cwd, opts.cliVersion) : undefined
-  // `staleDists` and `toolingDrift` are advisory (see DoctorResult): they never fail `ok`.
+  const staleMcpPins = await collectStaleMcpPins(cwd).catch(() => undefined)
+  // `staleDists`, `toolingDrift` and `staleMcpPins` are advisory (see DoctorResult): they never fail `ok`.
   return {
     ok:
       findings.length === 0 &&
@@ -791,7 +844,9 @@ export async function collectDoctorResult(
     ...(identity.truncated ? { identityScanTruncated: true } : {}),
     staleDists,
     readiness,
+    scanScope,
     ...(toolingDrift !== undefined ? { toolingDrift } : {}),
+    ...(staleMcpPins !== undefined && staleMcpPins.files.length > 0 ? { staleMcpPins } : {}),
     ...(pipeline.ran ? { pipeline } : {}),
   }
 }
@@ -817,7 +872,7 @@ export async function applyDoctorAutoFix(
 
   const fixed: DoctorAppliedFix[] = []
   const skippedFixes: DoctorSkippedFix[] = []
-  for (const [root, names] of [...byRoot.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+  for (const [root, names] of [...byRoot.entries()].sort(([a], [b]) => codeUnitOrder(a, b))) {
     const pkgPath = join(root, "package.json")
     const pkg = await readJson(pkgPath)
     if (pkg === undefined) continue
@@ -922,6 +977,14 @@ export async function runDoctor(
       console.log(`      fix: ${f.fix}\n`)
     }
   }
+  if (result.scanScope !== undefined) {
+    console.log(
+      `• dependency scan scope: ${result.scanScope.kind} (${result.scanScope.includeTests ? "includes tests" : "production package source only"})`,
+    )
+    if (result.scanScope.excluded.length > 0)
+      console.log(`  excluded: ${result.scanScope.excluded.join(", ")}`)
+    console.log("")
+  }
   // Advisory, printed regardless of ok: a stale linked dist doesn't fail doctor, but silently eating
   // it costs an hour of misdiagnosis when the dev server 500s inside the package.
   if (result.staleDists.length > 0) {
@@ -963,10 +1026,28 @@ export async function runDoctor(
         "its types, checks, and docs may describe a different version than your code builds with.",
     )
     console.log(
-      "      fix: run the project's own CLI (`bunx --bun nifra doctor` from the project directory, " +
+      `      fix: \`${syncMcpCommand(drift.cli)}\` re-pins the project's MCP launch to the nifra it installs; ` +
+        "for the CLI itself, run the project's own (`bunx --bun nifra doctor` from the project directory, " +
         "or ./node_modules/.bin/nifra)\n",
     )
   }
+  // Advisory: the agent's MCP server is launched from these pins, so a stale one answers for an old
+  // release even when the CLI running doctor matches the project.
+  if (result.staleMcpPins !== undefined) {
+    const { target, files } = result.staleMcpPins
+    console.log(
+      `⚠ the MCP launch pins a nifra other than the project's ${target} - an agent's nifra server answers for that release:`,
+    )
+    for (const file of files)
+      console.log(`    ${file.path}: @nifrajs/cli@${file.pinned.join(", ")}`)
+    const command =
+      opts.cliVersion !== undefined
+        ? syncMcpCommand(opts.cliVersion)
+        : "nifra init-agents --sync-mcp"
+    console.log(
+      `      fix: \`${command}\` rewrites only the pinned version, then restart the agent\n`,
+    )
+  }
   if (result.ok) {
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
@@ -1007,6 +1088,8 @@ export async function runDoctor(
         console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
       }
       console.log(`      ${finding.explanation}`)
+      // A planted symlink is the cause no reinstall here can see, so it is named before the fix.
+      if (finding.provenance !== undefined) console.log(`      links: ${finding.provenance}`)
       // The shape of the split decides which fix can work, so it is printed above the fix itself.
       if (finding.topology !== undefined) console.log(`      topology: ${finding.topology}`)
       // Why a copy this directory never imports still counts. Without it, a workspace-wide answer

package/src/env-file.ts

@@ -15,7 +15,7 @@
  *   - A missing file is an error, never a silent no-op. `--env-file .env.prod` that quietly did nothing
  *     would make the command look like it verified an environment it never loaded.
  */
-import { readFile } from "node:fs/promises"
+import { readdir, readFile } from "node:fs/promises"
 import { resolve } from "node:path"
 
 const ENV_FILE_FLAG = "--env-file"
@@ -119,3 +119,80 @@ export async function applyEnvFiles(
   }
   return applied
 }
+
+/**
+ * Remove from `process.env` what Bun loaded from the `.env` files in `cwd` when this process started,
+ * keeping every variable the environment itself set. Returns the names removed. `nifra mcp` runs it
+ * first and, when anything was removed, serves from a `bun --no-env-file` copy of itself given the
+ * result: Bun hands the values it loaded to every subprocess whatever `process.env` says later. The
+ * server is long-lived and runs no project code, so it holds none of the project's `.env`; the project
+ * subprocesses it starts load those files again themselves.
+ *
+ * Bun applies the files under the environment (a variable already set wins) and expands `${NAME}`
+ * references, so Bun itself says which values came from a file: a subprocess with an empty
+ * environment reports what the files add to it, and a variable with that value is removed. A value that
+ * differs is asked again with the rest of the environment, for an expansion that read it; one that
+ * still differs was set by the environment, and stays.
+ */
+export async function forgetAutoLoadedEnv(cwd = process.cwd()): Promise<readonly string[]> {
+  const names = await readdir(cwd).catch(() => [])
+  if (!names.some((name) => name.startsWith(".env"))) return []
+  const mode = process.env.NODE_ENV
+  const fromFiles = await envFromFiles(cwd, mode === undefined ? {} : { NODE_ENV: mode })
+  const removed: string[] = []
+  const differing: string[] = []
+  for (const [name, value] of Object.entries(fromFiles)) {
+    if (name === "NODE_ENV" || process.env[name] === undefined) continue
+    if (process.env[name] === value) removed.push(name)
+    else differing.push(name)
+  }
+  if (differing.length > 0) {
+    const rest = { ...process.env }
+    for (const name of differing) delete rest[name]
+    const expanded = await envFromFiles(cwd, rest)
+    for (const name of differing) if (process.env[name] === expanded[name]) removed.push(name)
+  }
+  for (const name of removed) delete process.env[name]
+  return removed
+}
+
+/** What the `.env` files in `cwd` add to a Bun process started there with `env`. */
+async function envFromFiles(
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<Record<string, string>> {
+  // A child holds more than `env`: Windows copies PATH, SYSTEMROOT and a few more from the parent,
+  // and a bunfig preload can set others. A `--no-env-file` copy of the child holds those as well.
+  const [loaded, bare] = await Promise.all([
+    childEnv(cwd, env, []),
+    childEnv(cwd, env, ["--no-env-file"]),
+  ])
+  const added: Record<string, string> = {}
+  for (const [name, value] of Object.entries(loaded)) if (bare[name] !== value) added[name] = value
+  return added
+}
+
+/** What `process.env` holds in a Bun process started in `cwd` with `env` and the runtime `flags`. */
+async function childEnv(
+  cwd: string,
+  env: Record<string, string | undefined>,
+  flags: readonly string[],
+): Promise<Record<string, string>> {
+  const proc = Bun.spawn(
+    [process.execPath, ...flags, "-e", "process.stdout.write(JSON.stringify(process.env))"],
+    { cwd, env, stdin: "ignore", stdout: "pipe", stderr: "ignore" },
+  )
+  const [text] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return {}
+  }
+  if (typeof value !== "object" || value === null) return {}
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  )
+}

package/src/fix-recipes.ts

@@ -31,35 +31,27 @@ registerFixRecipe({
   description: "Replace a direct secret comparison with a length check and timing-safe comparison.",
   verify: "nifra check --lints-only",
   async apply(root, diagnostic) {
-    if (diagnostic.file === undefined || diagnostic.line === undefined) return []
+    if (diagnostic.file === undefined) return []
     const path = await resolveInsideProject(root, diagnostic.file)
     if (path === undefined) return []
-    const lines = (await readFile(path, "utf8")).split("\n")
-    const index = diagnostic.line - 1
-    const original = lines[index]
-    if (original === undefined || original.includes("@nifra-gate-reviewed")) return []
-    const comparison = /\b([A-Za-z_$][\w$]*)\s*(===|!==|==|!=)\s*([A-Za-z_$][\w$]*)/.exec(original)
-    if (comparison === null) return []
-    const left = comparison[1] as string
-    const operator = comparison[2] as string
-    const right = comparison[3] as string
-    const expression = `nifraTimingSafeEqual(${left}, ${right})`
-    const replacement = operator === "!==" || operator === "!=" ? `!${expression}` : expression
-    lines[index] = original.replace(comparison[0], replacement)
-    if (!lines.some((line) => line.includes("function nifraTimingSafeEqual"))) {
-      lines.unshift(
-        'import { timingSafeEqual } from "node:crypto"',
-        "",
-        "function nifraTimingSafeEqual(left: string, right: string): boolean {",
-        "  const leftBytes = Buffer.from(left)",
-        "  const rightBytes = Buffer.from(right)",
-        "  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes)",
-        "}",
-        "",
+    const { loadProjectTypeScript } = await import("./internal/typescript-import.ts")
+    const loaded = await loadProjectTypeScript(root)
+    if (loaded.unsupported !== undefined) throw loaded.unsupported
+    if (loaded.compiler === undefined)
+      throw new Error(
+        "[nifra] the timing-safe fix finds each comparison in the syntax tree, so it needs TypeScript - run `bun add -d typescript`, then rerun the fix",
       )
+    try {
+      const { rewriteSecretComparisons } = await import("./rules/security.ts")
+      const source = await readFile(path, "utf8")
+      // Every site in the file at once, so the rest of that file's diagnostics find nothing left.
+      const rewritten = rewriteSecretComparisons(loaded.compiler, diagnostic.file, source)
+      if (rewritten === source) return []
+      await writeFile(path, rewritten, "utf8")
+      return [diagnostic.file]
+    } finally {
+      await loaded.session?.close()
     }
-    await writeFile(path, lines.join("\n"), "utf8")
-    return [diagnostic.file]
   },
 })
 
@@ -101,7 +93,7 @@ registerFixRecipe({
     // Refusing is a result the caller has to see. Returning "changed nothing" made `nifra fix
     // --code NF-C010` a silent no-op on the only findings that produce it.
     if (!linked.ok) throw new Error(`[nifra] cannot rebuild ${packageName}: ${linked.reason}`)
-    const proc = Bun.spawn(["bun", "run", linked.buildScript], {
+    const proc = Bun.spawn([process.execPath, "run", linked.buildScript], {
       cwd: linked.dir,
       stdout: "ignore",
       stderr: "pipe",
@@ -117,6 +109,24 @@ registerFixRecipe({
   },
 })
 
+registerFixRecipe({
+  id: "imports.moved-export",
+  description: "Import a name that moved to a subpath from the module that now exports it.",
+  verify: "nifra check --lints-only",
+  async apply(root, diagnostic) {
+    if (diagnostic.file === undefined) return []
+    const path = await resolveInsideProject(root, diagnostic.file)
+    if (path === undefined) return []
+    const { rewriteMovedExports } = await import("./check-scan.ts")
+    const source = await readFile(path, "utf8")
+    // Rewrites every site in the file at once, so the rest of that file's diagnostics find nothing left.
+    const rewritten = rewriteMovedExports(source)
+    if (rewritten === source) return []
+    await writeFile(path, rewritten, "utf8")
+    return [diagnostic.file]
+  },
+})
+
 /**
  * How many typecheck passes the reserved-segment codemod will run. A nested collision
  * (`/api/delete/then`) only reveals its second site once the first is rewritten, so one pass is not
@@ -147,11 +157,14 @@ registerFixRecipe({
     const changed = new Set<string>()
     const skipped: string[] = []
     for (let pass = 0; pass < RESERVED_SEGMENT_PASSES; pass += 1) {
-      const proc = Bun.spawn(["bun", tscBin, "--noEmit", "--pretty", "false", "-p", tsconfig], {
-        cwd: root,
-        stdout: "pipe",
-        stderr: "pipe",
-      })
+      const proc = Bun.spawn(
+        [process.execPath, tscBin, "--noEmit", "--pretty", "false", "-p", tsconfig],
+        {
+          cwd: root,
+          stdout: "pipe",
+          stderr: "pipe",
+        },
+      )
       const [stdout, stderr] = await Promise.all([
         new Response(proc.stdout).text(),
         new Response(proc.stderr).text(),

package/src/frontend-guidance.ts

@@ -52,11 +52,11 @@ export const FRONTEND_GUIDANCE: readonly GuidanceEntry[] = [
     symptom:
       "A client component crashes at build or runtime with a missing Node built-in, a leaked secret, or 'module not found in the browser'.",
     cause:
-      "A server-only module (the DB, a secret, `node:*`, the backend file) is imported at the top level of a component, so the bundler tries to ship it to the browser.",
-    fix: "Move the access into a server-only `loader`/`action` and read the result in the component. Reach the backend through the typed `api` argument, never a top-level server-only import.",
+      "Browser code (a page, `frontend/` or `shared/`) imports backend code - `backend/`, a route's `.backend.ts` half, the DB, a secret, `node:*` - so the browser build refuses it.",
+    fix: "Move the access into the route's `.backend.ts` half (`loader`/`action` with `loaderOutput`/`actionOutput`) and read the result as `data` in the page. Reach the backend through the typed `api` argument; put code both sides need in `shared/`.",
     verify:
       "nifra_check - its transitive server-import scan flags the exact import chain into a client module.",
-    seeAlso: "loader action server-only import boundary",
+    seeAlso: "project structure route backend half import rules",
   },
   {
     id: "hydration-mismatch",
@@ -88,10 +88,10 @@ export const FRONTEND_GUIDANCE: readonly GuidanceEntry[] = [
       "Loader data is typed `any` in the page, or a hand-written interface silently drifts from what the loader actually returns.",
     cause:
       "The component types its props by hand instead of inferring them from the loader, so a change to the loader is not a type error at the use site.",
-    fix: "Type the page from the loader: `props: { data: LoaderData<typeof loader> }`. Call the backend through the typed `api` so the request/response shape is inferred, not restated.",
+    fix: 'Type the page from its generated route types: `import type { Route } from "./+types/<name>"` and `props: Route.ComponentProps`. Its `data` is the `loaderOutput` schema\'s type - what actually reaches the browser - while `LoaderData<typeof loader>` also types fields the schema strips. Call the backend through the typed `api` (`Route.LoaderArgs`) so the request/response shape is inferred, not restated.',
     verify:
       "nifra_context prints the exact loader shape and typed call form; nifra_check fails on drift.",
-    seeAlso: "LoaderData typed client loader inference",
+    seeAlso: "route types Route.ComponentProps loaderOutput typed client",
   },
   {
     id: "list-key",

package/src/i18n-check.ts

@@ -0,0 +1,179 @@
+/**
+ * `nifra i18n check [entry]` - runs `checkCatalogs()` from `@nifrajs/i18n/check` over an app's locale
+ * registry and catalogs. Unlike `nifra check`, this IMPORTS app code: the entry module, which exports
+ * `locales` (from `defineLocales`) and `catalogs` (by locale key: a catalog, or a function returning
+ * one or a promise of one, such as `() => import("./messages/fr.json")`), plus an optional `ignore`.
+ * The default entry is the first of {@link DEFAULT_ENTRIES} that exists.
+ */
+import { existsSync } from "node:fs"
+import { relative, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import type { MessageTree } from "@nifrajs/i18n"
+import type { CatalogCheckOptions, CatalogCheckResult, CatalogFinding } from "@nifrajs/i18n/check"
+
+export const DEFAULT_ENTRIES = [
+  "shared/i18n.ts",
+  "i18n.ts",
+  "lib/i18n.ts",
+  "src/i18n.ts",
+  "src/lib/i18n.ts",
+  "app/i18n.ts",
+] as const
+
+export interface I18nCheckOutput {
+  /** The entry module, relative to the project directory. */
+  readonly entry: string
+  readonly result: CatalogCheckResult
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object"
+
+/** A loaded module's default export when the value is a module namespace (`import("./fr.json")`). */
+const unwrapModule = (value: unknown): unknown =>
+  isObject(value) && Object.prototype.toString.call(value) === "[object Module]"
+    ? value.default
+    : value
+
+const isRegistry = (value: unknown): value is CatalogCheckOptions["locales"] =>
+  isObject(value) &&
+  typeof value.default === "string" &&
+  Array.isArray(value.all) &&
+  typeof value.get === "function" &&
+  typeof value.chain === "function"
+
+function resolveEntry(cwd: string, entry: string | undefined): string {
+  if (entry !== undefined) {
+    const path = resolve(cwd, entry)
+    if (!existsSync(path)) throw new Error(`i18n check: ${entry} does not exist`)
+    return path
+  }
+  for (const candidate of DEFAULT_ENTRIES) {
+    const path = resolve(cwd, candidate)
+    if (existsSync(path)) return path
+  }
+  throw new Error(
+    `i18n check: no entry module found (looked for ${DEFAULT_ENTRIES.join(", ")}). Pass one: nifra i18n check <entry>, a module exporting \`locales\` and \`catalogs\`.`,
+  )
+}
+
+/** Import the entry, load every catalog it names, and check them. */
+export async function runI18nCheck(
+  cwd: string,
+  options: { readonly entry?: string | undefined } = {},
+): Promise<I18nCheckOutput> {
+  const path = resolveEntry(cwd, options.entry)
+  const mod = (await import(pathToFileURL(path).href)) as Record<string, unknown>
+  const source = isObject(mod.default) && mod.locales === undefined ? mod.default : mod
+  const { locales, catalogs, ignore } = source
+  const entry = relative(cwd, path).replaceAll("\\", "/") || path
+  if (!isRegistry(locales)) {
+    throw new Error(
+      `i18n check: ${entry} must export \`locales\`, the registry defineLocales() returns`,
+    )
+  }
+  if (!isObject(catalogs)) {
+    throw new Error(
+      `i18n check: ${entry} must export \`catalogs\`, an object of catalogs by locale key`,
+    )
+  }
+  if (ignore !== undefined && !isObject(ignore)) {
+    throw new Error(`i18n check: \`ignore\` in ${entry} must be an object of key patterns by check`)
+  }
+  const loaded: Record<string, MessageTree | undefined> = {}
+  for (const key of Object.keys(catalogs)) {
+    let value = catalogs[key]
+    if (typeof value === "function") value = (value as () => unknown)()
+    loaded[key] = unwrapModule(await value) as MessageTree | undefined
+  }
+  // Loaded on use: the command catalog imports this module on every CLI start.
+  const { checkCatalogs } = await import("@nifrajs/i18n/check")
+  return {
+    entry,
+    result: checkCatalogs({
+      locales,
+      catalogs: loaded,
+      ignore: ignore as CatalogCheckOptions["ignore"],
+    }),
+  }
+}
+
+const MARK = { error: "✖", warning: "⚠", info: "•" } as const
+// Per-key findings that are lists rather than problems one by one: grouped per locale in the text.
+const GROUPED = new Set(["missing-key", "unused-key", "untranslated"])
+const SHOWN_KEYS = 6
+
+// Catalog keys and text reach the terminal: control and bidi-override characters print as escapes, so
+// a key can neither drive the terminal nor reorder what the line appears to say.
+const unprintable = (code: number): boolean =>
+  code <= 0x1f ||
+  (code >= 0x7f && code <= 0x9f) ||
+  code === 0x200e ||
+  code === 0x200f ||
+  (code >= 0x202a && code <= 0x202e) ||
+  (code >= 0x2066 && code <= 0x2069)
+const printable = (line: string): string => {
+  let out = ""
+  for (const char of line) {
+    const code = char.codePointAt(0) ?? 0
+    out += unprintable(code) ? `\\u${code.toString(16).padStart(4, "0")}` : char
+  }
+  return out
+}
+
+const percent = (share: number): string => `${(share * 100).toFixed(share === 1 ? 0 : 1)}%`
+
+/** The human report: a coverage table, then findings, grouped where they are key lists. */
+export function renderI18nCheck(out: I18nCheckOutput): readonly string[] {
+  const { result } = out
+  const lines = [`nifra i18n check - ${out.entry}`, ""]
+  const width = Math.max(6, ...result.coverage.map((row) => row.locale.length))
+  for (const row of result.coverage) {
+    const label = row.default ? "default" : row.draft ? "draft" : ""
+    const counts = row.default
+      ? `${row.total} messages`
+      : `${row.translated}/${row.total} (${percent(row.coverage)})${row.own === row.translated ? "" : `, ${row.own} own`}`
+    lines.push(`  ${row.locale.padEnd(width)}  ${label.padEnd(7)}  ${counts}`)
+  }
+  if (result.coverage.length > 0) lines.push("")
+
+  const groups = new Map<string, CatalogFinding[]>()
+  for (const finding of result.findings) {
+    if (!GROUPED.has(finding.code) || finding.key === undefined) {
+      lines.push(`${MARK[finding.severity]} ${finding.locale}  ${finding.code}: ${finding.message}`)
+      continue
+    }
+    const id = `${finding.severity}\u0000${finding.locale}\u0000${finding.code}`
+    const group = groups.get(id)
+    if (group === undefined) groups.set(id, [finding])
+    else group.push(finding)
+  }
+  for (const group of groups.values()) {
+    const first = group[0] as CatalogFinding
+    const keys = group.map((finding) => finding.key as string)
+    const shown = keys.slice(0, SHOWN_KEYS).join(", ")
+    const more = keys.length > SHOWN_KEYS ? `, +${keys.length - SHOWN_KEYS} more` : ""
+    lines.push(
+      `${MARK[first.severity]} ${first.locale}  ${first.code} (${keys.length}): ${shown}${more}`,
+    )
+  }
+
+  const count = (severity: CatalogFinding["severity"]): number =>
+    result.findings.filter((finding) => finding.severity === severity).length
+  const errors = count("error")
+  const warnings = count("warning")
+  if (result.findings.length > 0) lines.push("")
+  lines.push(
+    errors === 0 && warnings === 0
+      ? "✓ catalogs are complete and consistent"
+      : `${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}${errors === 0 ? " - pass --strict to fail on warnings" : ""}`,
+  )
+  return lines.map(printable)
+}
+
+/** Errors fail the run; with `strict`, warnings do too. Info never does. */
+export function i18nCheckPassed(out: I18nCheckOutput, strict: boolean): boolean {
+  return out.result.findings.every(
+    (finding) => finding.severity === "info" || (finding.severity === "warning" && !strict),
+  )
+}