@nifrajs/cli 2.14.1 → 3.1.0

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,

package/src/internal/reserved-segment-codemod.ts

@@ -0,0 +1,150 @@
+/**
+ * Codemod for reserved-segment collisions in typed-client call sites.
+ *
+ * A route segment spelling a reserved proxy key (`get`…`options`, `subscribe`, `ws`, `index`, `then`)
+ * cannot be reached by property access - the proxy resolves the reserved behavior first - so the client
+ * type resolves that child to `ReservedSegmentCollision<"seg">` and every `api.foo.delete.post()` in the
+ * project stops compiling at once. The fix is mechanical and identical at every site: call the parent
+ * node with the segment instead, `api.foo("delete").post()`. Doing that by hand across a codebase is
+ * pure toil, and it is toil the framework caused.
+ *
+ * The compiler is the site index. `tsc` already reports every broken access, and its message names the
+ * segment (`Property 'post' does not exist on type 'ReservedSegmentCollision<"delete">'`), so the
+ * rewrite needs no type graph of its own and cannot invent a site the compiler did not reject. That
+ * also disambiguates the one case a textual search could not: `.delete` as a real DELETE verb call is
+ * valid and never appears in this list.
+ *
+ * A site the scan cannot rewrite CONFIDENTLY is left alone and reported, never guessed at. Bracket
+ * access, a collision node stored in a variable and used elsewhere, and any shape where the text before
+ * the failing property is not `.<segment>` all fall into that bucket.
+ */
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+/** `path/to/file.ts(12,16): error TS2339: … 'ReservedSegmentCollision<"delete">'.` */
+const TSC_POSITION = /^(.+?)\((\d+),(\d+)\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/
+const COLLISION_TYPE = /ReservedSegmentCollision<"([^"]+)">/
+
+export interface CollisionSite {
+  readonly file: string
+  /** 1-based, as `tsc` reports them. */
+  readonly line: number
+  readonly column: number
+  /** The colliding path segment, read out of the type the compiler named. */
+  readonly segment: string
+}
+
+/** Every reserved-segment collision `tsc` reported, in the order it reported them. */
+export function parseCollisionSites(tscOutput: string): readonly CollisionSite[] {
+  const sites: CollisionSite[] = []
+  for (const raw of tscOutput.split("\n")) {
+    const position = TSC_POSITION.exec(raw.trim())
+    if (position === null) continue
+    const segment = COLLISION_TYPE.exec(position[4] as string)
+    if (segment === null) continue
+    sites.push({
+      file: position[1] as string,
+      line: Number(position[2]),
+      column: Number(position[3]),
+      segment: segment[1] as string,
+    })
+  }
+  return sites
+}
+
+/** Byte offset of a 1-based (line, column) in `source`, or undefined when it is past the end. */
+const offsetOf = (source: string, line: number, column: number): number | undefined => {
+  let offset = 0
+  for (let current = 1; current < line; current += 1) {
+    const next = source.indexOf("\n", offset)
+    if (next === -1) return undefined
+    offset = next + 1
+  }
+  const target = offset + column - 1
+  return target <= source.length ? target : undefined
+}
+
+const skipSpaceBack = (source: string, from: number): number => {
+  let index = from
+  while (index >= 0 && /\s/.test(source[index] as string)) index -= 1
+  return index
+}
+
+/**
+ * The span to replace for one site: the `.segment` immediately preceding the failing property access,
+ * which becomes `("segment")`. Undefined when the text does not have that shape - the caller reports
+ * those rather than rewriting something it did not recognise.
+ *
+ * The scan runs backwards over the whole source rather than one line, so a chain broken across lines
+ * (`api.foo\n  .delete\n  .post()`) rewrites the same as a chain on one line.
+ */
+export function collisionSpan(
+  source: string,
+  site: CollisionSite,
+): { readonly start: number; readonly end: number } | undefined {
+  const offset = offsetOf(source, site.line, site.column)
+  if (offset === undefined) return undefined
+
+  // Back over the dot that introduces the FAILING property (`.post` in `…delete.post`).
+  let index = skipSpaceBack(source, offset - 1)
+  if (source[index] !== ".") return undefined
+
+  // Back over the colliding segment itself.
+  index = skipSpaceBack(source, index - 1)
+  const segmentEnd = index
+  const segmentStart = segmentEnd - site.segment.length + 1
+  if (segmentStart < 0) return undefined
+  if (source.slice(segmentStart, segmentEnd + 1) !== site.segment) return undefined
+
+  // Back over the dot that introduces the segment. Anything else (bracket access, a bare identifier
+  // holding the node) is a shape this rewrite does not understand.
+  const dot = skipSpaceBack(source, segmentStart - 1)
+  if (source[dot] !== ".") return undefined
+
+  // Take any whitespace before that dot into the span too, so a chain broken across lines closes up
+  // (`api.jobs\n  .subscribe` becomes `api.jobs("subscribe")`) instead of leaving the call argument
+  // dangling on its own line.
+  return { start: skipSpaceBack(source, dot - 1) + 1, end: segmentEnd }
+}
+
+export interface FileRewrite {
+  readonly source: string
+  /** Sites in this file the scan declined to rewrite, so the caller can report them. */
+  readonly skipped: readonly CollisionSite[]
+}
+
+/**
+ * Apply every site belonging to one file. Spans are applied back to front so an earlier rewrite never
+ * shifts the offsets of one not yet applied, and a duplicate span (two failing properties resolving
+ * through the same access) is applied once.
+ */
+export function rewriteFile(source: string, sites: readonly CollisionSite[]): FileRewrite {
+  const skipped: CollisionSite[] = []
+  const spans: { start: number; end: number; segment: string }[] = []
+  for (const site of sites) {
+    const span = collisionSpan(source, site)
+    if (span === undefined) {
+      skipped.push(site)
+      continue
+    }
+    if (spans.some((other) => other.start === span.start && other.end === span.end)) continue
+    spans.push({ ...span, segment: site.segment })
+  }
+  let out = source
+  for (const span of [...spans].sort((a, b) => b.start - a.start)) {
+    out = `${out.slice(0, span.start)}("${span.segment}")${out.slice(span.end + 1)}`
+  }
+  return { source: out, skipped }
+}
+
+/** The project's own `tsc` binary, found upward from `root`. Never installs one. */
+export function resolveTscBin(root: string): string | undefined {
+  let dir = root
+  while (true) {
+    const candidate = join(dir, "node_modules", "typescript", "bin", "tsc")
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}

package/src/internal/typescript-import.ts

@@ -12,11 +12,37 @@
  * install does not pay for it.
  */
 
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+
 /** The slice of the compiler the SQL scanner uses. Structural, so the peer stays optional. */
 export type TypeScriptApi = typeof import("typescript")
 
 /**
- * Import the project's TypeScript, or `undefined` when it is not installed.
+ * Is this module actually the compiler, rather than something else published under the same name?
+ *
+ * The `typescript` package name also carries small non-compiler entry points (a version stub, for
+ * one), and a resolver that falls back to a global download cache can hand one of those back. They
+ * import cleanly and then explode on first use - `undefined is not an object (evaluating
+ * 'ts.ScriptKind.TSX')` deep inside a scan - which reads as a Nifra bug rather than as "the compiler
+ * we loaded is not a compiler". Checking the two members every caller needs turns that into a
+ * resolution miss, which the fallbacks below already know how to handle.
+ */
+function isCompiler(module: unknown): module is TypeScriptApi {
+  if (typeof module !== "object" || module === null) return false
+  const api = module as Partial<TypeScriptApi>
+  return typeof api.createSourceFile === "function" && api.ScriptKind !== undefined
+}
+
+/** Unwrap the CJS default interop wrapper, so both `import * as ts` shapes look the same. */
+function compilerOf(module: unknown): TypeScriptApi | undefined {
+  if (isCompiler(module)) return module
+  const wrapped = (module as { default?: unknown } | undefined)?.default
+  return isCompiler(wrapped) ? wrapped : undefined
+}
+
+/**
+ * Import TypeScript from the CLI's own dependency tree, or `undefined` when it is not installed.
  *
  * Only a RESOLUTION failure is absence. A compiler that resolves and then fails while evaluating is a
  * broken install, not a missing one, and telling that user to install what they already have sends
@@ -24,7 +50,7 @@ export type TypeScriptApi = typeof import("typescript")
  */
 export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
   try {
-    return (await import("typescript")) as TypeScriptApi
+    return compilerOf(await import("typescript"))
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause)
     if (/cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message)) return undefined
@@ -32,6 +58,33 @@ export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
   }
 }
 
+/**
+ * Find the project's compiler the way module resolution would: `node_modules/typescript` in `root`,
+ * then each parent directory up to the filesystem root - the same walk the typecheck gate uses to
+ * find `tsc`, so both gates agree on which compiler the project has.
+ *
+ * The walk is deliberate, not a fallback for a missing resolver. `Bun.resolveSync` memoizes a
+ * specifier for the life of the process AND auto-installs from the global download cache when the
+ * project has none, so a long-lived process (the MCP server) that first resolved `typescript` before
+ * `bun install` kept handing back that cache entry afterwards - the typecheck went phantom until the
+ * server was restarted. A filesystem probe is re-answered every call, so an install that lands
+ * mid-session is picked up on the next scan.
+ */
+function resolveProjectTypeScript(root: string): string | undefined {
+  let dir = root
+  while (true) {
+    const pkg = join(dir, "node_modules", "typescript")
+    // `lib/typescript.js` is the compiler entry across every published major; probing it directly
+    // (rather than importing the directory) keeps a package whose main entry is a stub out of play.
+    const entry = join(pkg, "lib", "typescript.js")
+    if (existsSync(entry)) return entry
+    if (existsSync(join(pkg, "package.json"))) return pkg
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
 /**
  * Import TypeScript resolved from the PROJECT root first, falling back to the CLI's own dependency
  * tree. A bare `import("typescript")` resolves relative to this file - the CLI's install - so a
@@ -41,16 +94,13 @@ export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
  * the CLI was installed - the same cwd-invariance the typecheck gate's tsc resolution has.
  */
 export async function importProjectTypeScript(root: string): Promise<TypeScriptApi | undefined> {
-  let resolved: string
-  try {
-    resolved = Bun.resolveSync("typescript", root)
-  } catch {
-    // Unresolvable from the project (not installed there, or a non-Bun host without resolveSync):
-    // fall back to the CLI's own tree, which keeps the previous behavior as the floor.
-    return importTypeScript()
-  }
+  const resolved = resolveProjectTypeScript(root)
+  // Not installed in the project (or installed without a compiler entry): fall back to the CLI's own
+  // tree, which keeps the previous behavior as the floor.
+  if (resolved === undefined) return importTypeScript()
   try {
-    return (await import(resolved)) as TypeScriptApi
+    const compiler = compilerOf(await import(resolved))
+    return compiler ?? (await importTypeScript())
   } catch (cause) {
     // Same contract as importTypeScript: a compiler that RESOLVES and then fails evaluating is a
     // broken install, not a missing one - rethrow rather than silently checking with another copy.

package/src/introspect.ts

@@ -5,6 +5,7 @@
  * *this* project's actual surface, not just generic docs.
  */
 
+import { reservedKeyFor } from "@nifrajs/client"
 import {
   type ProjectEvidenceSchema,
   type ProjectEvidenceSchemaPart,
@@ -153,6 +154,24 @@ function schemaLines(schema: ReflectedRoute["schema"]): string[] {
 
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
+/**
+ * The typed-client proxy chain for a path, without the terminal verb call. Shared by `clientCall`
+ * and the `nifra routes` collision annotation so both teach exactly one spelling.
+ */
+function clientChain(path: string): string {
+  const segs = path.split("/").filter((seg) => seg !== "")
+  if (segs.length === 0) return "api.index"
+  let chain = "api"
+  for (const seg of segs) {
+    if (seg.startsWith(":") || seg.startsWith("*")) {
+      const name = seg.replace(/^[:*]/, "") || "value"
+      chain += `({ ${name} })`
+    } else if (reservedKeyFor(seg) !== undefined) chain += `(${JSON.stringify(seg)})`
+    else chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
+  }
+  return chain
+}
+
 /**
  * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
@@ -160,20 +179,16 @@ const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
  * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
  * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
+ *
+ * A segment spelling a reserved proxy key (`delete`, `subscribe`, `then`, ...) is emitted as a call on
+ * the parent node instead - and NOT as bracket access, which does not help: the proxy intercepts the
+ * key however it is spelled. Emitting `.delete` here would hand an agent a chain that resolves the
+ * DELETE verb and silently requests the wrong path.
  */
 export function clientCall(method: string, path: string, schema: unknown): string {
   const s = schema as { body?: unknown; query?: unknown } | undefined
   const verb = method.toLowerCase()
-  const segs = path.split("/").filter((seg) => seg !== "")
-  let chain = "api"
-  if (segs.length === 0) chain += ".index"
-  else
-    for (const seg of segs) {
-      if (seg.startsWith(":") || seg.startsWith("*")) {
-        const name = seg.replace(/^[:*]/, "") || "value"
-        chain += `({ ${name} })`
-      } else chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
-    }
+  const chain = clientChain(path)
   const isBodyVerb = verb === "post" || verb === "put" || verb === "patch"
   let call: string
   if (isBodyVerb) {
@@ -460,6 +475,27 @@ export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
   )
 }
 
+/**
+ * The typed-client spelling for a route path, and the reserved key it collides with when one of its
+ * static segments cannot be reached by property access.
+ *
+ * This is where a dev meets the reserved set EARLIEST: `nifra routes` is what you run while the
+ * route is being written, long before a typed client call site exists to break. The reserved names
+ * are deliberately unguessable from the outside (`then` and `index` especially - they exist so the
+ * proxy stays await-safe and can address `/`), so the route table names the collision and shows the
+ * spelling that reaches the route, rather than leaving it to be discovered by a failing build.
+ */
+export function clientSpellingFor(
+  path: string,
+): { readonly spelling: string; readonly reserved: string } | undefined {
+  for (const segment of path.split("/")) {
+    if (segment === "") continue
+    const reserved = reservedKeyFor(segment)
+    if (reserved !== undefined) return { spelling: clientChain(path), reserved }
+  }
+  return undefined
+}
+
 /** Render the route table as a terse aligned text table (the `nifra routes` default output). Pure. */
 export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
   if (rows.length === 0)
@@ -468,16 +504,29 @@ export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
     methods: r.methods.join(", "),
     kind: r.kind,
     path: r.kind === "api" && r.autoMounted ? `${r.path}  (auto-mounted)` : r.path,
+    client: clientSpellingFor(r.path),
   }))
   const methodW = Math.max("METHOD".length, ...display.map((d) => d.methods.length))
   const kindW = Math.max("KIND".length, ...display.map((d) => d.kind.length))
   const padEnd = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - s.length))
   const line = (methods: string, kind: string, path: string): string =>
     `${padEnd(methods, methodW)}  ${padEnd(kind, kindW)}  ${path}`
-  return [
+  const table = [
     line("METHOD", "KIND", "PATH"),
-    ...display.map((d) => line(d.methods, d.kind, d.path)),
-  ].join("\n")
+    ...display.flatMap((d) =>
+      d.client === undefined
+        ? [line(d.methods, d.kind, d.path)]
+        : [
+            line(d.methods, d.kind, d.path),
+            line(
+              "",
+              "",
+              `  -> '${d.client.reserved}' is a reserved typed-client key; reach this route as \`${d.client.spelling}\``,
+            ),
+          ],
+    ),
+  ]
+  return table.join("\n")
 }
 
 /** One JSON row for `nifra routes --json` (the agent-facing, stable shape). */
@@ -487,21 +536,33 @@ export interface RouteJsonRow {
   readonly methods: readonly string[]
   readonly file?: string
   readonly autoMounted?: boolean
+  /** The reserved typed-client key a static segment of this path collides with, when one does. */
+  readonly reservedKey?: string
+  /** The typed-client call spelling that reaches this route, present only alongside `reservedKey`. */
+  readonly clientSpelling?: string
 }
 
 /** The route table as a JSON document for `--json` (agents). Stable keys; `file`/`autoMounted` present
- * only where meaningful (file on pages, autoMounted on API routes). */
+ * only where meaningful (file on pages, autoMounted on API routes). A colliding row additionally
+ * carries `reservedKey`/`clientSpelling` so an agent writing client code from this table never has to
+ * infer the closed set of reserved names - the one thing about it nobody can guess. */
 export function routeTableToJson(rows: readonly RouteTableEntry[]): {
   readonly routes: readonly RouteJsonRow[]
 } {
   return {
-    routes: rows.map((r) => ({
-      kind: r.kind,
-      path: r.path,
-      methods: r.methods,
-      ...(r.file !== undefined ? { file: r.file } : {}),
-      ...(r.kind === "api" ? { autoMounted: r.autoMounted === true } : {}),
-    })),
+    routes: rows.map((r) => {
+      const client = clientSpellingFor(r.path)
+      return {
+        kind: r.kind,
+        path: r.path,
+        methods: r.methods,
+        ...(r.file !== undefined ? { file: r.file } : {}),
+        ...(r.kind === "api" ? { autoMounted: r.autoMounted === true } : {}),
+        ...(client === undefined
+          ? {}
+          : { reservedKey: client.reserved, clientSpelling: client.spelling }),
+      }
+    }),
   }
 }
 

package/src/mcp-http.ts

@@ -29,7 +29,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "2.14.1"
+const VERSION = "3.1.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>