@nifrajs/cli 3.2.0 → 3.5.0

package/src/introspect.ts

@@ -7,74 +7,22 @@
 
 import { reservedKeyFor } from "@nifrajs/client"
 import {
-  type ProjectEvidenceSchema,
   type ProjectEvidenceSchemaPart,
   type ProjectEvidenceSnapshot,
+  reflectedRoutesFromEvidence,
   snapshotProjectEvidence,
 } from "@nifrajs/core/evidence"
-import type { ReflectedRoute, SchemaReflection } from "@nifrajs/core/reflection"
+import type { ReflectedRoute } from "@nifrajs/core/reflection"
 import type { Manifest } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { LoadedApp } from "./load.ts"
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
-export function backendRoutes(backend: unknown): ReflectedRoute[] {
+export function backendRoutes(backend: unknown): readonly ReflectedRoute[] {
   return reflectedRoutesFromEvidence(snapshotProjectEvidence(backend))
 }
 
-function schemaPartToReflection(
-  value: ProjectEvidenceSchemaPart | undefined,
-): SchemaReflection | undefined {
-  return value === undefined
-    ? undefined
-    : { standard: undefined, jsonSchema: value.jsonSchema, fields: value.fields }
-}
-
-function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): ReflectedRoute["schema"] {
-  if (schema === undefined) return undefined
-  const errors = Object.fromEntries(
-    Object.entries(schema.errors ?? {}).map(([status, value]) => [
-      status,
-      schemaPartToReflection(value) as SchemaReflection,
-    ]),
-  )
-  const headers = schemaPartToReflection(schema.headers)
-  const body = schemaPartToReflection(schema.body)
-  const query = schemaPartToReflection(schema.query)
-  const params = schemaPartToReflection(schema.params)
-  const response = schemaPartToReflection(schema.response)
-  const sse = schemaPartToReflection(schema.sse)
-  return {
-    ...(schema.bodyLimit !== undefined ? { bodyLimit: schema.bodyLimit } : {}),
-    ...(schema.bodyLimitReason !== undefined ? { bodyLimitReason: schema.bodyLimitReason } : {}),
-    ...(headers !== undefined ? { headers } : {}),
-    ...(body !== undefined ? { body } : {}),
-    ...(query !== undefined ? { query } : {}),
-    ...(params !== undefined ? { params } : {}),
-    ...(response !== undefined ? { response } : {}),
-    ...(Object.keys(errors).length > 0 ? { errors } : {}),
-    ...(sse !== undefined ? { sse } : {}),
-  }
-}
-
-/** Adapt the canonical token-only snapshot to the legacy reflection view used by Markdown helpers. */
-export function reflectedRoutesFromEvidence(evidence: ProjectEvidenceSnapshot): ReflectedRoute[] {
-  return evidence.routes.map((route) => {
-    const schema = schemaFromEvidence(route.schema)
-    return {
-      method: route.method,
-      path: route.path,
-      ...(schema !== undefined ? { schema } : {}),
-      ...(route.assurance !== undefined ? { assurance: route.assurance } : {}),
-      ...(route.capabilities !== undefined ? { capabilities: route.capabilities } : {}),
-      ...(route.family === true ? { family: true } : {}),
-      ...(route.classification !== undefined ? { classification: route.classification } : {}),
-      ...(route.tool !== undefined ? { tool: route.tool } : {}),
-    }
-  })
-}
-
 interface JsonSchemaNode {
   readonly type?: unknown
   readonly properties?: Record<string, unknown>

package/src/load.ts

@@ -14,6 +14,7 @@
  */
 import { existsSync } from "node:fs"
 import { isAbsolute, resolve } from "node:path"
+import type { CssLoadingMode } from "@nifrajs/web"
 import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
@@ -60,6 +61,10 @@ export interface NifraFramework {
   readonly publicDir?: string | false
   /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
   readonly publicEnvPrefix?: string
+  /** Vite production CSS output policy. `false` emits one aggregate stylesheet for the whole client. */
+  readonly cssCodeSplit?: boolean
+  /** Framework-owned SSR stylesheet activation. Deferred mode is intended for aggregate CSS. */
+  readonly cssLoading?: CssLoadingMode
 }
 
 /**

package/src/mcp-context.ts

@@ -7,9 +7,10 @@
 
 import { realpathSync } from "node:fs"
 import { readFile } from "node:fs/promises"
-import { basename, isAbsolute, relative, resolve, sep } from "node:path"
+import { basename, isAbsolute, relative, resolve } from "node:path"
 import type { LoadedApp } from "./load.ts"
 import { createCachedAppLoader } from "./mcp-exec.ts"
+import { resolveMcpProjectPath } from "./mcp-path.ts"
 import type { McpPrompt, McpResource, McpServerFeatures, McpTool } from "./mcp-protocol.ts"
 
 function openApiFormat(args: Record<string, unknown>): "json" | "yaml" {
@@ -31,11 +32,8 @@ async function readProjectFile(
   relativeFile: string,
   maxChars: number,
 ): Promise<string> {
-  const target = resolve(cwd, relativeFile)
-  const root = resolve(cwd)
-  if (target !== root && !target.startsWith(`${root}${sep}`)) {
-    throw new Error(`refusing to read outside project root: ${relativeFile}`)
-  }
+  const target = resolveMcpProjectPath(cwd, relativeFile)
+  if (target === null) throw new Error(`refusing to read outside project root: ${relativeFile}`)
   try {
     const text = await readFile(target, "utf8")
     return text.length <= maxChars

package/src/mcp-exec.ts

@@ -7,7 +7,7 @@
  */
 
 import { stat } from "node:fs/promises"
-import { resolve, sep } from "node:path"
+import { resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { Glob } from "bun"
 import {
@@ -30,6 +30,7 @@ import {
 } from "./mcp-context.ts"
 import { docsTools } from "./mcp-docs-tools.ts"
 import {
+  CHILD_INPUT_MAX_BYTES,
   CHILD_OUTPUT_MAX_BYTES,
   CHILD_TIMEOUT_MS,
   LOCAL_TOOL_FETCH_TIMEOUT_MS,
@@ -39,6 +40,7 @@ import {
   timeoutMessage,
   validateLocalPort,
 } from "./mcp-io.ts"
+import { mcpProjectPathError, resolveMcpProjectPath } from "./mcp-path.ts"
 import type { McpTool, McpToolContext } from "./mcp-protocol.ts"
 import { loadTypesCorpus } from "./types-search.ts"
 
@@ -54,6 +56,7 @@ export function toMcpTool(
   const entry = "run" in source ? undefined : source
   const { cwd } = options
   const loadAppCached = options.loadAppCached ?? createCachedAppLoader(cwd)
+  const pathFields = ["config", "out", "lockfile", "before", "after", "baseline", "file"] as const
   return {
     name: commandMcpName(entry?.name ?? spec.name),
     description: entry?.summary ?? spec.summary,
@@ -64,14 +67,28 @@ export function toMcpTool(
       if (dir !== undefined && typeof dir !== "string") return dirError(undefined)
       const target = resolveProjectDir(cwd, dir as string | undefined)
       if (target === null) return dirError(dir as string | undefined)
-      if (typeof raw.config === "string") {
-        const config = resolve(target, raw.config)
-        if (config !== target && !config.startsWith(`${target}${sep}`))
-          return JSON.stringify(
-            { ok: false, error: "config must stay inside the selected project directory" },
-            null,
-            2,
-          )
+      for (const field of pathFields) {
+        const value = raw[field]
+        if (typeof value !== "string") continue
+        const safe = resolveMcpProjectPath(target, value)
+        if (safe === null)
+          return JSON.stringify({ ok: false, error: mcpProjectPathError(field, value) }, null, 2)
+        raw[field] = safe
+      }
+      if (Array.isArray(raw.files)) {
+        const safeFiles: string[] = []
+        for (const value of raw.files) {
+          if (typeof value !== "string") continue
+          const safe = resolveMcpProjectPath(target, value)
+          if (safe === null)
+            return JSON.stringify(
+              { ok: false, error: mcpProjectPathError("files", value) },
+              null,
+              2,
+            )
+          safeFiles.push(safe)
+        }
+        raw.files = safeFiles
       }
       delete raw.dir
       let input: unknown
@@ -194,10 +211,21 @@ export function projectTools(
         if (baseline !== undefined && baseline.trim() === "") {
           return JSON.stringify({ ok: false, error: "baseline must not be empty" }, null, 2)
         }
+        const safeBaseline =
+          baseline === undefined ? undefined : resolveMcpProjectPath(target, baseline)
+        if (baseline !== undefined && safeBaseline === null) {
+          return JSON.stringify(
+            { ok: false, error: mcpProjectPathError("baseline", baseline) },
+            null,
+            2,
+          )
+        }
         try {
           return JSON.stringify(
             await collectContractProof(target, {
-              ...(baseline === undefined ? {} : { baselinePath: baseline }),
+              ...(safeBaseline === undefined || safeBaseline === null
+                ? {}
+                : { baselinePath: safeBaseline }),
               ...(raw.check === undefined ? {} : { check: raw.check === true }),
             }),
             null,
@@ -641,6 +669,15 @@ export async function spawnChild(
   signal?: AbortSignal,
 ): Promise<string> {
   if (signal?.aborted) return `${label} cancelled before it started.`
+  let encodedInput: string
+  try {
+    encodedInput = JSON.stringify(input)
+  } catch {
+    return `${label} input is not serializable.`
+  }
+  if (new TextEncoder().encode(encodedInput).byteLength > CHILD_INPUT_MAX_BYTES)
+    return `${label} input exceeded ${CHILD_INPUT_MAX_BYTES} bytes.`
+  if (signal?.aborted) return `${label} cancelled${cancellationSuffix(signal)}.`
   const proc = Bun.spawn(["bun", childPath(child), cwd], {
     stdin: "pipe",
     stdout: "pipe",
@@ -661,8 +698,11 @@ export async function spawnChild(
   }, CHILD_TIMEOUT_MS)
   let outputExceeded = false
   try {
-    proc.stdin.write(JSON.stringify(input))
-    await proc.stdin.end()
+    if (signal?.aborted) kill()
+    else {
+      proc.stdin.write(encodedInput)
+      await proc.stdin.end()
+    }
     const [out, err] = await Promise.all([
       readBoundedStream(proc.stdout, CHILD_OUTPUT_MAX_BYTES, () => {
         outputExceeded = true
@@ -675,7 +715,7 @@ export async function spawnChild(
     ])
     await proc.exited
     if (signal?.aborted) {
-      const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : ""
+      const reason = cancellationSuffix(signal)
       return `${label} cancelled${reason}.`
     }
     if (outputExceeded) {
@@ -696,6 +736,7 @@ const WARM_RUN_GLOB = new Glob("**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json}")
 const WARM_RUN_IGNORED =
   /(^|\/)(node_modules|dist(-[a-z0-9]+)?|build|\.nifra|\.git|\.wrangler|coverage)\//
 const WARM_RUN_EXTRA_FILES = ["bun.lock", "bun.lockb"] as const
+const MAX_WARM_PENDING = 64
 
 async function warmRunFingerprint(cwd: string): Promise<string> {
   const parts: string[] = []
@@ -743,6 +784,7 @@ export class WarmWorker {
     }
   >()
   private stdoutBuffer = ""
+  private stdoutBufferBytes = 0
   private stderrBuffer = ""
   private nextId = 0
   private closed = false
@@ -780,7 +822,18 @@ export class WarmWorker {
   async request(input: unknown, signal?: AbortSignal): Promise<string> {
     if (this.closed) throw new Error(`warm ${this.label} worker is closed`)
     if (signal?.aborted) return `${this.label} cancelled before it started.`
+    if (this.pending.size >= MAX_WARM_PENDING)
+      throw new Error(`warm ${this.label} worker request limit reached`)
     const id = ++this.nextId
+    let encodedInput: string
+    try {
+      encodedInput = JSON.stringify({ id, input })
+    } catch {
+      throw new Error(`warm ${this.label} input is not serializable`)
+    }
+    if (new TextEncoder().encode(encodedInput).byteLength > CHILD_INPUT_MAX_BYTES)
+      throw new Error(`warm ${this.label} input exceeded ${CHILD_INPUT_MAX_BYTES} bytes`)
+    if (signal?.aborted) return `${this.label} cancelled${cancellationSuffix(signal)}.`
     return new Promise((resolve, reject) => {
       const abort = (): void => {
         // Per-request cancel: drop just THIS id and resolve its cancellation. The worker is shared
@@ -789,7 +842,8 @@ export class WarmWorker {
         // cold rebuild. Leave it hot - `createWarmHandler` already replaces it on file change.
         this.pending.delete(id)
         clearTimeout(timer)
-        const reason = typeof signal?.reason === "string" ? `: ${signal.reason}` : ""
+        signal?.removeEventListener("abort", abort)
+        const reason = cancellationSuffix(signal)
         resolve(`${this.label} cancelled${reason}.`)
       }
       // Same backstop as the cold path: a worker wedged mid-request would otherwise leave this
@@ -807,8 +861,15 @@ export class WarmWorker {
       }
       signal?.addEventListener("abort", abort, { once: true })
       this.pending.set(id, { resolve, reject, cleanup })
+      // JSON serialization above can run user-defined `toJSON` hooks. Recheck after installing the
+      // listener and pending entry so an abort during that synchronous work cannot enqueue a request
+      // after cancellation, and so an already-aborted signal does not retain the listener.
+      if (signal?.aborted) {
+        abort()
+        return
+      }
       try {
-        this.proc.stdin.write(`${JSON.stringify({ id, input })}\n`)
+        this.proc.stdin.write(`${encodedInput}\n`)
       } catch (err) {
         this.pending.delete(id)
         cleanup()
@@ -831,8 +892,10 @@ export class WarmWorker {
         this.stop()
         return
       }
-      this.stdoutBuffer += decoder.decode(value, { stream: true })
-      if (this.stdoutBuffer.length > CHILD_OUTPUT_MAX_BYTES) {
+      const text = decoder.decode(value, { stream: true })
+      this.stdoutBuffer += text
+      this.stdoutBufferBytes += new TextEncoder().encode(text).byteLength
+      if (this.stdoutBufferBytes > CHILD_OUTPUT_MAX_BYTES) {
         this.stderrBuffer = boundedAppend(
           this.stderrBuffer,
           `warm ${this.label} worker stdout exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes\n`,
@@ -844,6 +907,7 @@ export class WarmWorker {
       while (nl !== -1) {
         const line = this.stdoutBuffer.slice(0, nl).trim()
         this.stdoutBuffer = this.stdoutBuffer.slice(nl + 1)
+        this.stdoutBufferBytes = new TextEncoder().encode(this.stdoutBuffer).byteLength
         nl = this.stdoutBuffer.indexOf("\n")
         if (line !== "") this.handleLine(line)
       }
@@ -861,25 +925,69 @@ export class WarmWorker {
   }
 
   private handleLine(line: string): void {
-    let message: { id?: unknown; output?: unknown }
+    let message: unknown
     try {
-      message = JSON.parse(line) as { id?: unknown; output?: unknown }
+      message = JSON.parse(line) as unknown
     } catch {
       this.stderrBuffer = boundedAppend(
         this.stderrBuffer,
         `invalid warm ${this.label} worker line: ${line}\n`,
       )
+      this.stop()
+      return
+    }
+    if (
+      message === null ||
+      typeof message !== "object" ||
+      Array.isArray(message) ||
+      typeof (message as { id?: unknown }).id !== "number" ||
+      !Number.isSafeInteger((message as { id: number }).id)
+    ) {
+      this.stderrBuffer = boundedAppend(
+        this.stderrBuffer,
+        `invalid warm ${this.label} worker response envelope\n`,
+      )
+      this.stop()
       return
     }
-    if (typeof message.id !== "number") return
-    const pending = this.pending.get(message.id)
+    const response = message as { id: number; output?: unknown }
+    const pending = this.pending.get(response.id)
     if (pending === undefined) return
-    this.pending.delete(message.id)
+    if (!Object.hasOwn(response, "output")) {
+      this.pending.delete(response.id)
+      pending.cleanup()
+      pending.reject(new Error(`warm ${this.label} worker response is malformed`))
+      this.stop()
+      return
+    }
+    let output: string
+    try {
+      output = JSON.stringify(response.output, null, 2)
+    } catch {
+      this.pending.delete(response.id)
+      pending.cleanup()
+      pending.reject(new Error(`warm ${this.label} worker response is not serializable`))
+      this.stop()
+      return
+    }
+    if (new TextEncoder().encode(output).byteLength > CHILD_OUTPUT_MAX_BYTES) {
+      this.pending.delete(response.id)
+      pending.cleanup()
+      pending.reject(new Error(`warm ${this.label} worker response exceeded the size limit`))
+      this.stop()
+      return
+    }
+    this.pending.delete(response.id)
     pending.cleanup()
-    pending.resolve(JSON.stringify(message.output, null, 2))
+    pending.resolve(output)
   }
 }
 
+function cancellationSuffix(signal: AbortSignal | undefined): string {
+  const reason = signal?.reason
+  return typeof reason === "string" && reason.length > 0 ? `: ${reason.slice(0, 512)}` : ""
+}
+
 /** A warm handler that reuses a hot {@link WarmWorker} across calls and falls back to a one-shot fresh
  * subprocess on any worker failure. Shared by `nifra_run` (`child: "mcp-run"`, `label: "run"`) and
  * `nifra_render` (`child: "mcp-render"`, `label: "render"`) - the only differences are the engine and the
@@ -892,17 +1000,21 @@ export function createWarmHandler(
   let worker: WarmWorker | undefined
   return async (input, signal) => {
     const fingerprint = await warmRunFingerprint(cwd)
-    if (worker === undefined || worker.fingerprint !== fingerprint) {
-      worker?.stop()
-      worker = new WarmWorker(child, cwd, fingerprint, label)
+    let current = worker
+    if (current === undefined || current.fingerprint !== fingerprint) {
+      current?.stop()
+      current = new WarmWorker(child, cwd, fingerprint, label)
+      worker = current
     }
     try {
-      return await worker.request(input, signal)
+      return await current.request(input, signal)
     } catch {
-      worker.stop()
-      worker = undefined
+      // A source change can replace the shared worker while this request is in flight. Only clear
+      // the slot if this request still owns it; an old request must never tear down the replacement.
+      current.stop()
+      if (worker === current) worker = undefined
       if (signal?.aborted) {
-        const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : ""
+        const reason = cancellationSuffix(signal)
         return `${label} cancelled${reason}.`
       }
       return spawnChild(child, cwd, input, label, signal)

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 = "3.2.0"
+const VERSION = "3.5.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 =>
@@ -69,6 +69,9 @@ export function handleMcpHttp(request: Request): Promise<Response> {
       instructions:
         "nifra's own documentation, runnable examples, and API types - for building with the nifra framework. Call nifra_docs / nifra_example / nifra_types / nifra_learn to learn it without a local checkout.",
     },
+    // This is the intentionally public, secret-free docs server. Other MCP mounts use the
+    // transport's same-origin default unless they explicitly opt into public cross-origin access.
+    allowAnyOrigin: true,
   })
 }
 

package/src/mcp-io.ts

@@ -8,6 +8,8 @@
 export const CHILD_TIMEOUT_MS = 30_000
 /** Maximum stdout or stderr retained from a project subprocess. The process is killed at the limit. */
 export const CHILD_OUTPUT_MAX_BYTES = 1_048_576
+/** Maximum serialized request sent to a project subprocess or warm worker. */
+export const CHILD_INPUT_MAX_BYTES = 4 * 1024 * 1024
 
 /** Local dev-tool reads are intentionally bounded: MCP runs in an agent process and must not hang on or
  * buffer an unrelated loopback service just because a caller supplied its port. */
@@ -81,6 +83,77 @@ export interface BoundedOutput {
   readonly truncated: boolean
 }
 
+export type BoundedLine =
+  | { readonly kind: "line"; readonly text: string }
+  | { readonly kind: "too-large" }
+
+function decodeLine(chunks: readonly Uint8Array[], totalBytes: number): string {
+  const bytes = new Uint8Array(totalBytes)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(bytes)
+}
+
+/** Read newline-delimited input without retaining a line larger than the configured byte budget. */
+export async function* readBoundedLines(
+  stream: ReadableStream<Uint8Array>,
+  maxBytes = CHILD_INPUT_MAX_BYTES,
+): AsyncGenerator<BoundedLine> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    throw new RangeError("maxBytes must be a positive safe integer")
+  const chunks: Uint8Array[] = []
+  let totalBytes = 0
+  let tooLarge = false
+  for await (const raw of stream) {
+    const value = raw as Uint8Array
+    let start = 0
+    while (start < value.byteLength) {
+      const newline = value.indexOf(0x0a, start)
+      const end = newline === -1 ? value.byteLength : newline
+      const segment = value.subarray(start, end)
+      if (!tooLarge) {
+        if (totalBytes + segment.byteLength > maxBytes) {
+          tooLarge = true
+          chunks.length = 0
+          totalBytes = 0
+        } else if (segment.byteLength > 0) {
+          chunks.push(segment)
+          totalBytes += segment.byteLength
+        }
+      }
+      if (newline === -1) break
+      if (tooLarge) yield { kind: "too-large" }
+      else yield { kind: "line", text: decodeLine(chunks, totalBytes) }
+      chunks.length = 0
+      totalBytes = 0
+      tooLarge = false
+      start = newline + 1
+    }
+  }
+  if (tooLarge) yield { kind: "too-large" }
+  else if (totalBytes > 0) yield { kind: "line", text: decodeLine(chunks, totalBytes) }
+}
+
+/** Serialize a JSON value only when its UTF-8 representation fits within the byte budget. */
+export function serializeBoundedJson(
+  value: unknown,
+  maxBytes: number,
+  space?: string | number,
+): string | undefined {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) return undefined
+  let text: string | undefined
+  try {
+    text = JSON.stringify(value, null, space)
+  } catch {
+    return undefined
+  }
+  if (text === undefined || new TextEncoder().encode(text).byteLength > maxBytes) return undefined
+  return text
+}
+
 /** Read child output incrementally and cancel as soon as the byte budget is crossed. */
 export async function readBoundedStream(
   stream: ReadableStream<Uint8Array>,

package/src/mcp-path.ts

@@ -0,0 +1,50 @@
+import { realpathSync } from "node:fs"
+import { basename, isAbsolute, relative, resolve } from "node:path"
+
+/**
+ * Resolve an MCP path without allowing lexical or symlink escapes from the selected project.
+ *
+ * MCP callers are not equivalent to a local CLI user: the selected checkout is their filesystem
+ * capability boundary. The nearest-existing-ancestor walk also supports output files that do not
+ * exist yet while still canonicalizing every existing path component.
+ */
+export function resolveMcpProjectPath(root: string, value: string): string | null {
+  if (value.length === 0 || isAbsolute(value)) return null
+
+  const lexicalRoot = resolve(root)
+  const target = resolve(lexicalRoot, value)
+  const lexicalRelative = relative(lexicalRoot, target)
+  if (lexicalRelative.startsWith("..") || isAbsolute(lexicalRelative)) return null
+
+  let canonicalRoot: string
+  try {
+    canonicalRoot = realpathSync(lexicalRoot)
+  } catch {
+    return null
+  }
+
+  let probe = target
+  const missing: string[] = []
+  while (true) {
+    try {
+      const canonicalProbe = realpathSync(probe)
+      const canonicalRelative = relative(canonicalRoot, canonicalProbe)
+      if (canonicalRelative.startsWith("..") || isAbsolute(canonicalRelative)) return null
+
+      const candidate = resolve(canonicalProbe, ...missing.reverse())
+      const candidateRelative = relative(canonicalRoot, candidate)
+      return candidateRelative.startsWith("..") || isAbsolute(candidateRelative) ? null : candidate
+    } catch (error) {
+      if (!(error && typeof error === "object" && (error as { code?: string }).code === "ENOENT"))
+        return null
+      const parent = resolve(probe, "..")
+      if (parent === probe) return null
+      missing.push(basename(probe))
+      probe = parent
+    }
+  }
+}
+
+export function mcpProjectPathError(label: string, value: string): string {
+  return `${label} must be a relative path inside the selected project directory: ${value}`
+}

package/src/mcp-reflect.ts

@@ -5,7 +5,8 @@
  * about stdio, HTTP, root trust, or project loading, so the reflection seam is independently testable.
  */
 
-import { type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
+import { reflectedRoutesFromEvidence, snapshotProjectEvidence } from "@nifrajs/core/evidence"
+import type { ReflectedRoute } from "@nifrajs/core/reflection"
 import type {
   McpPrompt,
   McpPromptMessage,
@@ -24,7 +25,7 @@ type ToolBackend = {
 export function extractBackendTools(backend: unknown): McpTool[] {
   const b = backend as ToolBackend | null
   if (!b || typeof b.routes !== "function") return []
-  const routes = reflectRoutes(b)
+  const routes = reflectedRoutesFromEvidence(snapshotProjectEvidence(b))
 
   return routes
     .filter(