@nifrajs/cli 2.13.0 → 3.1.0

package/src/contracts.ts

@@ -41,8 +41,7 @@ async function sha256(value: string): Promise<string> {
   return [...digest].map((item) => item.toString(16).padStart(2, "0")).join("")
 }
 
-function schemaValue(route: ReflectedRoute, side: "request" | "response"): unknown {
-  const schema = route.schema
+function schemaValue(schema: ReflectedRoute["schema"], side: "request" | "response"): unknown {
   if (schema === undefined) return {}
   if (side === "request") {
     return {
@@ -64,11 +63,28 @@ function schemaValue(route: ReflectedRoute, side: "request" | "response"): unkno
 }
 
 export async function digestRoute(route: ReflectedRoute): Promise<ContractDigest> {
-  const request = JSON.stringify(canonical(schemaValue(route, "request")))
-  const response = JSON.stringify(canonical(schemaValue(route, "response")))
+  const request = JSON.stringify(canonical(schemaValue(route.schema, "request")))
+  const response = JSON.stringify(canonical(schemaValue(route.schema, "response")))
   return { request: await sha256(request), response: await sha256(response) }
 }
 
+/** The digest a route with NO declared schema produces on both sides - `sha256("{}")`. A lock whose
+ * every route hashes to this is guarding nothing: drift detection can only ever compare empty schema to
+ * empty schema. Computed through the same canonical/stringify path as {@link digestRoute} so it tracks
+ * that path rather than a hard-coded literal. */
+export async function emptySchemaDigest(): Promise<string> {
+  return sha256(JSON.stringify(canonical(schemaValue(undefined, "request"))))
+}
+
+/** Whether every route in `lock` hashes to the empty-schema digest (so no route declares a schema). An
+ * empty `routes` map is NOT vacuous in this sense - there is no route whose contract went unguarded. */
+export async function isVacuousLock(lock: ContractsLock): Promise<boolean> {
+  const digests = Object.values(lock.routes)
+  if (digests.length === 0) return false
+  const empty = await emptySchemaDigest()
+  return digests.every((d) => d.request === empty && d.response === empty)
+}
+
 export async function buildContractsLock(source: unknown): Promise<ContractsLock> {
   const routes = Object.fromEntries(
     await Promise.all(
@@ -131,11 +147,16 @@ export function parseContractsLock(value: unknown): ContractsLock {
 export async function checkContractsLock(
   cwd: string,
   file = DEFAULT_CONTRACTS_LOCK,
-): Promise<{ present: boolean; diagnostics: Array<{ route?: string; message: string }> }> {
+): Promise<{
+  present: boolean
+  vacuous: boolean
+  diagnostics: Array<{ route?: string; message: string }>
+}> {
   const path = resolve(cwd, file)
-  if (!existsSync(path)) return { present: false, diagnostics: [] }
+  if (!existsSync(path)) return { present: false, vacuous: false, diagnostics: [] }
   const parsed = parseContractsLock(JSON.parse(await Bun.file(path).text()))
   const current = await buildContractsLock(await loadBackend(cwd))
+  const vacuous = await isVacuousLock(current)
   const diagnostics: Array<{ route?: string; message: string }> = []
   const keys = new Set([...Object.keys(parsed.routes), ...Object.keys(current.routes)])
   for (const key of [...keys].sort()) {
@@ -153,5 +174,5 @@ export async function checkContractsLock(
       })
     }
   }
-  return { present: true, diagnostics }
+  return { present: true, vacuous, diagnostics }
 }

package/src/doctor.ts

@@ -25,11 +25,14 @@ import {
   displayPath,
   type IdentityParityCopy,
   type IdentityParityFinding,
+  identityParityBasis,
   resolvedInstalledCopy,
 } from "@nifrajs/web/internal/parity"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
+import { detectToolingDrift, 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"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
 // own `bun` module. `node:`/`bun:`-prefixed specifiers are filtered in packageOf by prefix.
@@ -140,10 +143,37 @@ export interface DoctorResult {
   readonly findings: readonly DoctorFinding[]
   /** Packages that resolve to more than one physical install across this workspace. */
   readonly duplicateInstalls: readonly DuplicateInstallFinding[]
+  /**
+   * Duplicate installs the app declared single-copy (`"nifra": { "singleCopy": [...] }`), which nifra
+   * collapses to one copy at resolve time. Reported so the topology stays visible, never folded into
+   * `ok`: the copies exist on disk but cannot both load. Absent on an older result shape.
+   */
+  readonly deduplicatedInstalls?: readonly DuplicateInstallFinding[]
+  /**
+   * Which tree the identity scan actually looked at, in the same words the build/dev preflight uses.
+   * Both run the same seam now; printing the basis is what lets a reader confirm that instead of
+   * having to trust it. Absent on an older result shape.
+   */
+  readonly identityBasis?: string
+  /**
+   * The identity scan stopped at the workspace-enumeration cap, so "no duplicates" means "none in the
+   * part that was scanned". Never folded into `ok` - a huge workspace is not a defect - but it is
+   * always printed, because an unqualified clean bill from a partial scan is the failure mode this
+   * whole report exists to avoid.
+   */
+  readonly identityScanTruncated?: boolean
   /** Workspace-linked deps whose `default`-condition artifact lags their `bun`-condition source.
    * Advisory (never folded into `ok`): while actively editing a linked package its dist is always
    * momentarily behind - the finding matters when a dev server starts against it. */
   readonly staleDists: readonly StaleDistFinding[]
+  /**
+   * The running CLI is a different feature version than the `@nifrajs/cli` (or `@nifrajs/core`) the
+   * project installs. Advisory (never folded into `ok`): a stale global/bunx binary answering about a
+   * project it does not match is an environment problem, not a defect in the project - but every
+   * answer it gives (types, checks, docs) reads as authoritative. Present only when `cliVersion` was
+   * supplied and the feature versions disagree. Computed by {@link detectToolingDrift}.
+   */
+  readonly toolingDrift?: ToolingDrift
   /** Static production-readiness evidence for the selected deploy target. */
   readonly readiness?: DoctorReadiness
   /**
@@ -351,18 +381,52 @@ export async function collectDuplicateInstalls(
   cwd: string,
   rootPackage: Record<string, unknown>,
 ): Promise<DuplicateInstallFinding[]> {
-  const result = await collectIdentityParity(cwd, rootPackage, { useWorkspaceRoot: true })
-  return result.findings.map(
-    (finding): DuplicateInstallFinding => ({
-      ...finding,
-      copies: finding.copies.map((copy): DuplicateInstallCopy => ({ ...copy })),
-    }),
-  )
+  return (await collectAllDuplicateInstalls(cwd, rootPackage)).duplicates
+}
+
+const asDuplicateInstall = (finding: IdentityParityFinding): DuplicateInstallFinding => ({
+  ...finding,
+  copies: finding.copies.map((copy): DuplicateInstallCopy => ({ ...copy })),
+})
+
+/**
+ * Both halves of the identity scan: what still breaks, and what a declaration already collapses -
+ * plus the basis they were decided on.
+ *
+ * The basis travels with the findings because doctor and the build/dev preflight answer the same
+ * question, and a reader who gets two answers needs to see which tree each one looked at. They now
+ * scan identically (one shared seam, one workspace resolution), so the line is corroboration rather
+ * than an excuse - and it is the only way a TRUNCATED scan can be told apart from a clean one.
+ */
+export async function collectAllDuplicateInstalls(
+  cwd: string,
+  rootPackage: Record<string, unknown>,
+): Promise<{
+  readonly duplicates: DuplicateInstallFinding[]
+  readonly deduplicated: DuplicateInstallFinding[]
+  readonly basis: string
+  readonly truncated: boolean
+}> {
+  const result = await collectIdentityParity(cwd, rootPackage)
+  return {
+    duplicates: result.findings.map(asDuplicateInstall),
+    deduplicated: result.deduplicated.map(asDuplicateInstall),
+    basis: identityParityBasis(result),
+    truncated: result.truncated,
+  }
 }
 
 /** A workspace-linked dependency whose build artifact is older than its source. */
 export interface StaleDistFinding {
   readonly package: string
+  /** Where the linked package actually lives, relative to the doctor root when possible. A workspace
+   * link routinely points into a SIBLING repo, so "rebuild it" is not actionable without the path -
+   * this is the directory the rebuild runs in. */
+  readonly packageDir: string
+  /** The package's own build script name (`scripts.build` etc.), or `undefined` when it declares none -
+   * then the rebuild cannot be automated and the report says so instead of suggesting a command that
+   * would fail. */
+  readonly buildScript: string | undefined
   /** The `default`-condition artifact (what Vite's SSR runner, vitest, and node consumers load),
    * relative to the doctor root when possible. `missing: true` means it was never built at all. */
   readonly distFile: string
@@ -473,6 +537,8 @@ export async function collectStaleWorkspaceDists(
           newest = candidate
       }
       if (newest === undefined) continue
+      const packageDir = displayPath(cwd, copy.path)
+      const buildScript = buildScriptName(meta)
       // Report the package once, anchored on its stalest (or missing) artifact.
       let worst: StaleDistFinding | undefined
       for (const pair of pairs) {
@@ -482,6 +548,8 @@ export async function collectStaleWorkspaceDists(
           distStat === undefined
             ? {
                 package: name,
+                packageDir,
+                buildScript,
                 distFile: displayPath(cwd, distPath),
                 missing: true,
                 sourceFile: displayPath(cwd, newest.file),
@@ -490,6 +558,8 @@ export async function collectStaleWorkspaceDists(
             : distStat.mtimeMs < newest.mtimeMs
               ? {
                   package: name,
+                  packageDir,
+                  buildScript,
                   distFile: displayPath(cwd, distPath),
                   missing: false,
                   sourceFile: displayPath(cwd, newest.file),
@@ -672,7 +742,7 @@ async function inferDependencyFix(
 /** Run doctor against the project at `cwd`: diff source imports vs declared deps. */
 export async function collectDoctorResult(
   cwd: string,
-  opts: { readonly target?: string; readonly strict?: boolean } = {},
+  opts: { readonly target?: string; readonly strict?: boolean; readonly cliVersion?: string } = {},
 ): Promise<DoctorResult> {
   const pkg = await readJson(join(cwd, "package.json"))
   if (pkg === undefined)
@@ -695,12 +765,18 @@ export async function collectDoctorResult(
     { includeTests: true },
   )
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
-  const duplicateInstalls = await collectDuplicateInstalls(cwd, pkg)
+  const identity = await collectAllDuplicateInstalls(cwd, pkg)
+  const duplicateInstalls = identity.duplicates
   const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
   const pipeline = await collectPipelineReport(cwd)
   const pipelineErrors = pipeline.findings.filter((f) => f.severity === "error")
   const readiness = await collectDoctorReadiness(cwd, opts)
-  // `staleDists` is advisory (see DoctorResult): it never fails `ok`.
+  // A stale binary answering about a project it does not match is an environment condition, so like
+  // `staleDists` it is reported but never folded into `ok`. Skipped entirely when the caller did not
+  // 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`.
   return {
     ok:
       findings.length === 0 &&
@@ -710,8 +786,12 @@ export async function collectDoctorResult(
     ran: true,
     findings,
     duplicateInstalls,
+    deduplicatedInstalls: identity.deduplicated,
+    identityBasis: identity.basis,
+    ...(identity.truncated ? { identityScanTruncated: true } : {}),
     staleDists,
     readiness,
+    ...(toolingDrift !== undefined ? { toolingDrift } : {}),
     ...(pipeline.ran ? { pipeline } : {}),
   }
 }
@@ -719,7 +799,7 @@ export async function collectDoctorResult(
 /** Safely add undeclared imports to package.json when the version can be inferred without network I/O. */
 export async function applyDoctorAutoFix(
   cwd: string,
-  opts: { readonly target?: string; readonly strict?: boolean } = {},
+  opts: { readonly target?: string; readonly strict?: boolean; readonly cliVersion?: string } = {},
 ): Promise<DoctorResult> {
   const before = await collectDoctorResult(cwd, opts)
   if (!before.ran || before.findings.length === 0) return before
@@ -798,6 +878,8 @@ export async function runDoctor(
     readonly autoFix?: boolean
     readonly strict?: boolean
     readonly target?: string
+    /** The running CLI's own version, so doctor can flag a binary that mismatches the project. */
+    readonly cliVersion?: string
   } = {},
 ): Promise<boolean> {
   const result = opts.autoFix
@@ -872,10 +954,31 @@ export async function runDoctor(
     }
     console.log("")
   }
+  // Advisory, printed regardless of ok: the binary answering is a different feature version than the
+  // one the project builds with, so its types/checks/docs describe a surface the code does not have.
+  if (result.toolingDrift !== undefined) {
+    const drift = result.toolingDrift
+    console.log(
+      `⚠ this CLI is nifra ${drift.cli}, but the project installs ${drift.package} ${drift.project} - ` +
+        "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, " +
+        "or ./node_modules/.bin/nifra)\n",
+    )
+  }
   if (result.ok) {
     console.log(
       "✓ every imported package is declared and identity-sensitive installs are deduplicated",
     )
+    if (result.identityBasis !== undefined) console.log(`  identity scan: ${result.identityBasis}`)
+    // A partial scan that prints a bare ✓ is a lie by omission - the packages past the cap were never
+    // looked at, and the reader has no way to know that from the tick alone.
+    if (result.identityScanTruncated === true) {
+      console.log(
+        "  ! the identity scan was truncated, so this is not a clean bill for the whole workspace",
+      )
+    }
     return true
   }
   // Group by package so the fix ("add X to dependencies") is stated once with its import sites.
@@ -896,15 +999,34 @@ export async function runDoctor(
     console.log(
       `${byPkg.size > 0 ? "\n" : ""}✗ identity-sensitive packages resolve to multiple physical copies:\n`,
     )
+    if (result.identityBasis !== undefined) console.log(`  scan: ${result.identityBasis}\n`)
     for (const finding of result.duplicateInstalls) {
-      console.log(`  ${finding.package}`)
+      console.log(`  ${finding.package} [${finding.cause}]`)
+      console.log(`      versions: ${finding.versions.join(", ")}`)
       for (const copy of finding.copies) {
         console.log(`      ${copy.version} at ${copy.path} ← ${copy.importers.join(", ")}`)
       }
       console.log(`      ${finding.explanation}`)
+      // 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
+      // read from inside one app looks like the tool checking the wrong project.
+      if (finding.scope !== undefined) console.log(`      scope: ${finding.scope}`)
       console.log(`      fix: ${finding.remediation}`)
     }
   }
+  // Not a failure and not silence: the copies are real, and whoever reads this report needs to know
+  // the graph is held together by a declaration rather than by the install.
+  if (result.deduplicatedInstalls !== undefined && result.deduplicatedInstalls.length > 0) {
+    console.log("\n• identity-sensitive packages deduplicated by declaration:\n")
+    for (const finding of result.deduplicatedInstalls) {
+      console.log(`  ${finding.package} @ ${finding.versions.join(", ")}`)
+      for (const copy of finding.copies) {
+        console.log(`      ${copy.path} ← ${copy.importers.join(", ")}`)
+      }
+      console.log(`      ${finding.remediation}`)
+    }
+  }
   if (result.readiness?.strict === true && result.readiness.ok === false) {
     console.log("\n✗ production readiness is incomplete under --strict")
   }

package/src/env-file.ts

@@ -0,0 +1,121 @@
+/**
+ * `--env-file <path>` for every `nifra` command.
+ *
+ * Most nifra commands (`check`, `assure`, `levels`, `routes`, `capabilities`, `manifest`, `contracts`,
+ * `openapi`, `types`) reflect a project by IMPORTING it, and a production-grade app validates its
+ * environment at module scope. Without the app's environment those commands do not report a gate
+ * failure - the app's own validator kills the process before nifra reaches its first check, and the
+ * only output is the app's `FATAL: invalid environment` with nothing tying it to the command that was
+ * run. This flag supplies that environment the same way `bun --env-file` / `node --env-file` do, so a
+ * project whose env lives in an uncommitted `.env.local` stays checkable.
+ *
+ * Two deliberate rules:
+ *   - A variable already present in `process.env` WINS. The shell (and CI's secret store) is the more
+ *     explicit source; a checked-in defaults file must never shadow it.
+ *   - 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 { resolve } from "node:path"
+
+const ENV_FILE_FLAG = "--env-file"
+
+/**
+ * A `KEY=VALUE` line. `export ` is tolerated so a file that is also `source`-able works. The key is
+ * POSIX-shaped on purpose: it keeps a stray `- foo` bullet or a YAML `key: value` line from being read
+ * as an assignment when the wrong file is passed.
+ */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/
+
+/** Strip one layer of matching quotes; a double-quoted value also expands `\n`, `\r`, `\t` and `\"`. */
+function unquote(raw: string): string {
+  const value = raw.trim()
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value
+      .slice(1, -1)
+      .replace(/\\([nrt"\\])/g, (_, char: string) =>
+        char === "n" ? "\n" : char === "r" ? "\r" : char === "t" ? "\t" : char,
+      )
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1)
+  // Unquoted: an inline ` #` starts a comment, matching every dotenv reader. A `#` with no leading
+  // space is part of the value (URLs and generated secrets contain one).
+  const comment = value.search(/\s#/)
+  return (comment === -1 ? value : value.slice(0, comment)).trim()
+}
+
+/** Parse dotenv text into a plain record. Later assignments to the same key win, as in a shell. */
+export function parseEnvFile(text: string): Record<string, string> {
+  const values: Record<string, string> = {}
+  for (const line of text.split(/\r?\n/)) {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue
+    const match = ASSIGNMENT.exec(line)
+    if (match === null) continue
+    values[match[1] as string] = unquote(match[2] as string)
+  }
+  return values
+}
+
+/**
+ * Pull every `--env-file <path>` / `--env-file=<path>` out of `argv`, leaving the rest for the command
+ * parser (which rejects options it does not know). Repeatable; later files override earlier ones, the
+ * same precedence `node --env-file` uses.
+ */
+export function takeEnvFileFlags(argv: readonly string[]): {
+  readonly argv: readonly string[]
+  readonly files: readonly string[]
+} {
+  const rest: string[] = []
+  const files: string[] = []
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index] as string
+    if (token === ENV_FILE_FLAG) {
+      const value = argv[index + 1]
+      if (value === undefined || value.startsWith("-")) {
+        throw new Error(`[nifra] ${ENV_FILE_FLAG} needs a path, e.g. ${ENV_FILE_FLAG} .env.local`)
+      }
+      files.push(value)
+      index++
+      continue
+    }
+    if (token.startsWith(`${ENV_FILE_FLAG}=`)) {
+      const value = token.slice(ENV_FILE_FLAG.length + 1)
+      if (value === "") {
+        throw new Error(`[nifra] ${ENV_FILE_FLAG} needs a path, e.g. ${ENV_FILE_FLAG}=.env.local`)
+      }
+      files.push(value)
+      continue
+    }
+    rest.push(token)
+  }
+  return { argv: rest, files }
+}
+
+/**
+ * Read each file in order and merge it into `process.env`, never overwriting a variable the process
+ * already has. Returns the resolved paths that were applied so a command can say what it loaded.
+ */
+export async function applyEnvFiles(
+  cwd: string,
+  files: readonly string[],
+): Promise<readonly string[]> {
+  const applied: string[] = []
+  const merged: Record<string, string> = {}
+  for (const file of files) {
+    const path = resolve(cwd, file)
+    let text: string
+    try {
+      text = await readFile(path, "utf8")
+    } catch {
+      throw new Error(`[nifra] --env-file not found or unreadable: ${path}`)
+    }
+    // Files merge left to right, so a later `--env-file` overrides an earlier one; the merged result
+    // is applied afterwards so that precedence never depends on which file happened to define a key.
+    Object.assign(merged, parseEnvFile(text))
+    applied.push(path)
+  }
+  for (const [key, value] of Object.entries(merged)) {
+    if (process.env[key] === undefined) process.env[key] = value
+  }
+  return applied
+}

package/src/fix-recipes.ts

@@ -1,8 +1,8 @@
-import { existsSync } from "node:fs"
 import { readFile, writeFile } from "node:fs/promises"
 import { join } from "node:path"
 import type { Diagnostic } from "./diagnostics.ts"
 import { resolveInsideProject } from "./project-path.ts"
+import { resolveWorkspaceLinkedPackage } from "./workspace-link.ts"
 
 export interface FixRecipe {
   readonly id: string
@@ -91,29 +91,115 @@ registerFixRecipe({
   verify: "nifra doctor --json",
   async apply(root, diagnostic) {
     const packageName = diagnostic.evidence?.[0]
-    if (packageName === undefined || !/^@?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)?$/.test(packageName))
-      return []
-    // The segment regex above admits "." and "..", which would resolve outside node_modules.
-    if (packageName.split("/").some((segment) => segment === "." || segment === "..")) return []
-    const packageDir = await resolveInsideProject(root, join("node_modules", packageName))
-    if (packageDir === undefined) return []
-    const packageJson = await resolveInsideProject(
-      root,
-      join("node_modules", packageName, "package.json"),
-    )
-    if (packageJson === undefined || !existsSync(packageJson)) return []
-    const proc = Bun.spawn(["bun", "run", "build"], {
-      cwd: packageDir,
+    if (packageName === undefined) return []
+    // Resolved from the NAME through the project's own node_modules chain, not from any path carried
+    // by the diagnostic. A workspace link points outside the project by definition - that escape is
+    // what makes the artifact able to go stale - so `resolveInsideProject` would reject every package
+    // this diagnostic can ever name. `resolveWorkspaceLinkedPackage` states its own rules instead:
+    // reachable through the project's install, not a registry tarball, and declaring its own build.
+    const linked = await resolveWorkspaceLinkedPackage(root, packageName)
+    // 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], {
+      cwd: linked.dir,
       stdout: "ignore",
       stderr: "pipe",
     })
     const error = await new Response(proc.stderr).text()
     const exitCode = await proc.exited
-    if (exitCode !== 0) throw new Error(error.trim() || `build failed for ${packageName}`)
+    if (exitCode !== 0) {
+      throw new Error(
+        `[nifra] \`bun run ${linked.buildScript}\` failed in ${linked.dir}: ${error.trim() || `exit code ${exitCode}`}`,
+      )
+    }
     return [diagnostic.evidence?.[1] ?? packageName]
   },
 })
 
+/**
+ * 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
+ * always enough - but each pass is a full `tsc`, so this converges or stops rather than looping.
+ */
+const RESERVED_SEGMENT_PASSES = 3
+
+registerFixRecipe({
+  id: "client.reserved-segment",
+  description:
+    "Rewrite typed-client call sites broken by a reserved-named route segment to the call spelling.",
+  verify: "tsc --noEmit",
+  async apply(root) {
+    const { parseCollisionSites, resolveTscBin, rewriteFile } = await import(
+      "./internal/reserved-segment-codemod.ts"
+    )
+    const tsconfig = join(root, "tsconfig.json")
+    if (!(await Bun.file(tsconfig).exists()))
+      throw new Error(
+        "[nifra] no tsconfig.json here - the reserved-segment codemod reads the compiler's own list of broken call sites, so it needs a typecheckable project",
+      )
+    const tscBin = resolveTscBin(root)
+    if (tscBin === undefined)
+      throw new Error(
+        "[nifra] no `typescript` install found from this directory upward - run `bun add -d typescript`, then rerun the fix",
+      )
+
+    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 [stdout, stderr] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ])
+      await proc.exited
+      const sites = parseCollisionSites(`${stdout}${stderr}`)
+      if (sites.length === 0) break
+
+      const byFile = new Map<string, (typeof sites)[number][]>()
+      for (const site of sites) {
+        const existing = byFile.get(site.file)
+        if (existing === undefined) byFile.set(site.file, [site])
+        else existing.push(site)
+      }
+
+      let wrote = false
+      skipped.length = 0
+      for (const [file, fileSites] of byFile) {
+        // Resolved through the project boundary: the compiler reports paths from its own rootDir, and
+        // a rewrite must never escape the project it was invoked in.
+        const path = await resolveInsideProject(root, file)
+        if (path === undefined) continue
+        const source = await readFile(path, "utf8")
+        const result = rewriteFile(source, fileSites)
+        for (const site of result.skipped) skipped.push(`${file}:${site.line}:${site.column}`)
+        if (result.source === source) continue
+        await writeFile(path, result.source, "utf8")
+        changed.add(file)
+        wrote = true
+      }
+      // Nothing rewritten this pass means the remaining sites are all shapes the codemod declines to
+      // touch. Another `tsc` would report the same list, so stop instead of burning the budget.
+      if (!wrote) break
+    }
+
+    if (skipped.length > 0) {
+      const rewritten =
+        changed.size === 0
+          ? "no site was rewritten"
+          : `rewrote ${changed.size} file${changed.size === 1 ? "" : "s"}`
+      throw new Error(
+        `[nifra] ${rewritten}; ${skipped.length} reserved-segment site${skipped.length === 1 ? "" : "s"} need${skipped.length === 1 ? "s" : ""} a manual edit (the collision is not reached by a plain \`.segment\` property access there): ${skipped.join(", ")}`,
+      )
+    }
+    return [...changed]
+  },
+})
+
 export async function applyDiagnosticRecipe(
   root: string,
   diagnostic: Diagnostic,