@nifrajs/cli 2.13.0 → 3.1.0

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/load.ts

@@ -13,7 +13,7 @@
  * reach the edge bundle. A simple single-target app with no edge build can put it all in `framework.ts`.
  */
 import { existsSync } from "node:fs"
-import { resolve } from "node:path"
+import { isAbsolute, resolve } from "node:path"
 import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
@@ -210,11 +210,30 @@ export async function loadApp(
   // resolved to absolute here. It is embedded verbatim as an import specifier in the generated client
   // entry, and `nifra dev` and `nifra build` write that entry into DIFFERENT directories - so a relative
   // specifier would resolve against different bases and load in one phase but not the other. A bare or
-  // package specifier (`@nifrajs/web-react/client`) is location-independent and passes through unchanged.
-  const clientModule =
-    fw.clientModule.startsWith("./") || fw.clientModule.startsWith("../")
-      ? resolve(cwd, fw.clientModule)
-      : fw.clientModule
+  // package specifier (`@nifrajs/web-react/client`) or an already-absolute path is location-independent
+  // and passes through unchanged.
+  let clientModule: string
+  if (fw.clientModule.startsWith("./") || fw.clientModule.startsWith("../")) {
+    clientModule = resolve(cwd, fw.clientModule)
+  } else {
+    // A specifier that is neither `./`-relative, scoped (`@…`), nor absolute is read as a BARE PACKAGE
+    // specifier - resolved against `node_modules`, not `cwd`. If a real local file sits at that path
+    // (a `./` was forgotten: `src/client.tsx` instead of `./src/client.tsx`), the bundler would ignore
+    // the file, fail to find a package, and surface an opaque "cannot resolve" deep in the build. Reject
+    // it here with the one-character fix rather than letting it fail silently.
+    if (
+      !isAbsolute(fw.clientModule) &&
+      !fw.clientModule.startsWith("@") &&
+      existsSync(resolve(cwd, fw.clientModule))
+    ) {
+      throw new Error(
+        `[nifra] clientModule "${fw.clientModule}" has no "./" prefix, so it is read as a bare package ` +
+          `specifier - but a local file exists at that path. Prefix it with "./" (e.g. ` +
+          `"./${fw.clientModule}") so \`nifra dev\` and \`nifra build\` resolve the same local entry.`,
+      )
+    }
+    clientModule = fw.clientModule
+  }
   const [vitePlugins, clientPlugins, serverPlugins] = await Promise.all([
     resolvePlugins(fw.vitePlugins),
     resolvePlugins(fw.clientPlugins),

package/src/manifest-tool.ts

@@ -5,6 +5,7 @@ import { resolve } from "node:path"
 import {
   buildNifraManifest,
   diffNifraManifests,
+  type NifraManifest,
   type NifraManifestDiff,
   parseNifraManifest,
   serializeNifraManifest,
@@ -38,11 +39,18 @@ export function formatManifestDiff(diff: NifraManifestDiff): string {
   return lines.join("\n")
 }
 
-/** Build only after both assurance layers pass, then optionally create an operator-signed sidecar. */
-export async function runManifestEmit(
+export interface ManifestEmitCommandResult {
+  readonly ok: boolean
+  readonly path: string
+  readonly manifest?: NifraManifest
+  readonly signaturePath?: string
+}
+
+/** Emit the manifest without printing. This is the execution seam used by all adapters. */
+export async function collectManifestEmit(
   cwd: string,
   options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
-): Promise<boolean> {
+): Promise<ManifestEmitCommandResult> {
   const verification = await collectProjectVerification(cwd, {
     ...(options.config !== undefined ? { config: options.config } : {}),
   })
@@ -58,9 +66,9 @@ export async function runManifestEmit(
   if (assurance === undefined) {
     throw new Error("[nifra] assurance evaluation was unavailable for manifest emission")
   }
+  const path = resolve(cwd, options.out ?? config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
   if (!assurance.ok || (capabilityProject !== undefined && !capabilityProject.report.ok)) {
-    console.error("[nifra] refusing to emit a manifest from failing assurance")
-    return false
+    return { ok: false, path }
   }
   const manifest = await buildNifraManifest({
     source: config.source,
@@ -68,9 +76,9 @@ export async function runManifestEmit(
     assurance,
     ...(capabilityProject !== undefined ? { capabilities: capabilityProject.report } : {}),
   })
-  const path = resolve(cwd, options.out ?? config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
   await Bun.write(path, `${serializeNifraManifest(manifest)}\n`)
 
+  let signaturePath: string | undefined
   if (options.sign !== undefined) {
     if (config.manifest?.signer === undefined) {
       throw new Error(
@@ -79,29 +87,52 @@ export async function runManifestEmit(
     }
     const signer = await config.manifest.signer(options.sign)
     const signature = await signNifraManifest(manifest, signer)
-    await Bun.write(`${path}.sig`, `${serializeNifraManifestSignature(signature)}\n`)
+    signaturePath = `${path}.sig`
+    await Bun.write(signaturePath, `${serializeNifraManifestSignature(signature)}\n`)
+  }
+  return { ok: true, path, manifest, ...(signaturePath === undefined ? {} : { signaturePath }) }
+}
+
+/** Build only after both assurance layers pass, then optionally create an operator-signed sidecar. */
+export async function runManifestEmit(
+  cwd: string,
+  options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
+): Promise<boolean> {
+  const result = await collectManifestEmit(cwd, options)
+  if (!result.ok) {
+    console.error("[nifra] refusing to emit a manifest from failing assurance")
+    return false
   }
   console.log(
-    `[nifra] wrote manifest to ${path}${options.sign === undefined ? "" : ` and ${path}.sig`}`,
+    `[nifra] wrote manifest to ${result.path}${result.signaturePath === undefined ? "" : ` and ${result.signaturePath}`}`,
   )
   return true
 }
 
 /** Diff two already-emitted, hash-verified artifacts. Suitable for deploy promotion gates. */
-export async function runManifestDiff(
+export async function collectManifestDiff(
   cwd: string,
   beforePath: string,
   afterPath: string,
-  options: { readonly json?: boolean } = {},
-): Promise<boolean> {
+): Promise<NifraManifestDiff> {
   const before = resolve(cwd, beforePath)
   const after = resolve(cwd, afterPath)
   if (!existsSync(before)) throw new Error(`[nifra] manifest not found: ${before}`)
   if (!existsSync(after)) throw new Error(`[nifra] manifest not found: ${after}`)
-  const diff = diffNifraManifests(
+  return diffNifraManifests(
     await parseNifraManifest(await Bun.file(before).text(), before),
     await parseNifraManifest(await Bun.file(after).text(), after),
   )
+}
+
+/** Diff two already-emitted, hash-verified artifacts and print the result. */
+export async function runManifestDiff(
+  cwd: string,
+  beforePath: string,
+  afterPath: string,
+  options: { readonly json?: boolean } = {},
+): Promise<boolean> {
+  const diff = await collectManifestDiff(cwd, beforePath, afterPath)
   console.log(
     options.json === true
       ? JSON.stringify({ hasBreaking: diff.hasBreaking, changes: diff.changes }, null, 2)

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.13.0"
+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 =>