@nifrajs/cli 3.3.0 → 4.0.0

package/src/mcp.ts

@@ -20,19 +20,32 @@
  *   - `nifra_levels`  - the cumulative verification ladder (L0 contract → L4 invariants): what the
  *     project actually proves, and why each level it misses does not hold.
  *   - `nifra_doctor`  - package.json dependency drift detector, with safe local-version auto-fix.
- *   - `nifra_explain` - resolve an error (pasted, or the dev server's last) into a structured
+ *   - `nifra_errors`  - the running dev server's errors (SSR, loader, API, build, browser, hydration,
+ *     crash), each a structured diagnostic tagged with its request; `since` cursors, stale flags.
+ *   - `nifra_logs`    - the dev server's console output, server and browser, tagged by request.
+ *   - `nifra_db_schema` / `nifra_db_query` / `nifra_db_role` - the development database declared as
+ *     `devDatabase` in nifra.config.ts: its schema, one read-only query (or plan) per call in a fresh
+ *     subprocess killed at the deadline, and the SQL for a read-only role. Separate tools, so a client
+ *     can allow reading the schema without allowing queries.
+ *   - `nifra_explain` - resolve an error (pasted, or the dev server's latest) into a structured
  *     diagnostic: stable code, a codeframe in the user's source, and the recognised cause + fix.
  *   - `nifra_inspect` - read the running dev server's recent request traces (method/path/status/
- *     duration/ISR) from the DevTools plugin: what your requests ACTUALLY did, not a guess.
+ *     duration/ISR/errors): what your requests ACTUALLY did, not a guess.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]` (or
  * `["mcp", "<dir>"]` to pin the project directory explicitly). The server does NOT silently trust its
  * spawn directory: the root is resolved via `./mcp-root.ts` (marker walk-up, the client's MCP `roots`,
  * fail-closed tools when no nifra project is found) and announced in `initialize` + on every project
- * tool result. The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
+ * tool result. A project that installs its own `@nifrajs/cli` at a different version gets the session
+ * handed to that CLI; when that is impossible the version-sensitive tools refuse rather than answer
+ * for the wrong release (see `./mcp-delegate.ts`). The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
  * standard MCP progress notifications and request cancellation - no SDK dependency, the same
  * minimal-surface choice as the rest of nifra. The pure dispatch lives in `./mcp-protocol.ts`; this
  * module is the I/O shell (stdin loop, tool wiring, the run subprocess).
+ *
+ * This process runs no project code and holds none of the project's `.env`: the config, the backend
+ * and everything they import run in a fresh subprocess per call (`./mcp-isolate.ts`), and a session
+ * whose process Bun started with `.env` values moves to a copy that never loads them (`./cli.ts`).
  */
 
 import { stat } from "node:fs/promises"
@@ -40,11 +53,14 @@ import { resolve } from "node:path"
 import { loadDocsCorpus } from "./docs-search.ts"
 import { loadExamplesCorpus } from "./examples.ts"
 import type { LoadedApp } from "./load.ts"
-import { detectMonorepo, loadMonorepoApps } from "./load.ts"
+import { loadMonorepoApps } from "./load.ts"
+import { delegateToProjectCli, refuseVersionSensitive } from "./mcp-delegate.ts"
 import { docsTools } from "./mcp-docs-tools.ts"
 import {
   createMcpProtocolState,
   handleRpc,
+  isJsonRpcRequest,
+  isJsonRpcResponse,
   type JsonRpcNotification,
   type JsonRpcRequest,
   type JsonRpcResponse,
@@ -54,11 +70,6 @@ import {
   type McpTool,
   rpcError,
 } from "./mcp-protocol.ts"
-import {
-  extractBackendPrompts,
-  extractBackendResources,
-  extractBackendTools,
-} from "./mcp-reflect.ts"
 import { loadTypesCorpus } from "./types-search.ts"
 
 export {
@@ -80,21 +91,31 @@ import {
   type ToolingDrift,
 } from "./mcp-root.ts"
 
-export type { BoundedOutput } from "./mcp-io.ts"
+export type { BoundedLine, BoundedOutput } from "./mcp-io.ts"
 export {
+  CHILD_INPUT_MAX_BYTES,
   CHILD_OUTPUT_MAX_BYTES,
   CHILD_TIMEOUT_MS,
   LOCAL_TOOL_FETCH_TIMEOUT_MS,
   LOCAL_TOOL_MAX_RESPONSE_BYTES,
   notNifraResponse,
+  readBoundedLines,
   readBoundedResponse,
   readBoundedStream,
+  serializeBoundedJson,
   timeoutMessage,
   validateLocalPort,
 } from "./mcp-io.ts"
 export { clientSupportsRoots, guardTools } from "./mcp-root.ts"
 
-import { createCachedAppLoader, projectTools } from "./mcp-exec.ts"
+import { projectTools } from "./mcp-exec.ts"
+import {
+  createAppSurface,
+  detectMonorepoIsolated,
+  type IsolatedSurface,
+  isolateResources,
+  isolateTools,
+} from "./mcp-isolate.ts"
 
 export type { CachedAppLoaderOptions } from "./mcp-exec.ts"
 export {
@@ -110,7 +131,7 @@ export {
   wsHandler,
 } from "./mcp-exec.ts"
 
-import { namespaceForApp, projectFeatures } from "./mcp-context.ts"
+import { namespaceForApp, projectPrompts, projectResources } from "./mcp-context.ts"
 
 export type { CommandMcpToolOptions } from "./mcp-context.ts"
 export {
@@ -122,76 +143,82 @@ export {
   resolveProjectDir,
 } from "./mcp-context.ts"
 
-async function backendFeatures(
-  loader: () => Promise<LoadedApp>,
-  base: McpServerFeatures,
-): Promise<McpServerFeatures> {
-  const resources = [...(base.resources ?? [])]
-  const prompts = [...(base.prompts ?? [])]
-  try {
-    const app = await loader()
-    resources.push(...extractBackendResources(app.backend))
-    prompts.push(...extractBackendPrompts(app.backend))
-  } catch {
-    // Not loadable here (no web config, or the config itself throws). The server still serves.
-  }
-  return { resources, prompts }
-}
+/**
+ * The loader the server builds its tool and resource lists with. It never loads: every handler that
+ * reaches the app runs in a project subprocess (`./mcp-isolate.ts`), so one that tried here fails.
+ */
+const noAppInServer = (): Promise<LoadedApp> =>
+  Promise.reject(
+    new Error("[nifra] the MCP server does not load the app; project code runs in a subprocess"),
+  )
+
+const isolatedToolsByDir = new Map<string, McpTool[]>()
 
 /**
- * The MCP tools the app itself declares via `app.tool(...)`, or none when the app cannot be loaded.
- *
- * Same reasoning as {@link backendFeatures}, on the hotter path: this ran on EVERY JSON-RPC message,
- * so an unloadable project failed `initialize` itself with a `-32603` and the session never opened.
- * An app's own tools are an extension of the built-in set, so their absence must not withdraw the
- * built-ins - a backend-only project still gets docs, examples, types, check, doctor, levels and test.
+ * The project's tools, each forwarded to a project subprocess unless it runs no project code. Built
+ * once per directory: `nifra_run`/`nifra_render` hold their warm worker in the tool, so a list rebuilt
+ * per message started a fresh worker for every `warm: true` call.
  */
-async function appDeclaredTools(loader: () => Promise<LoadedApp>): Promise<McpTool[]> {
-  try {
-    return extractBackendTools((await loader()).backend)
-  } catch {
-    return []
+function isolatedProjectTools(cwd: string): McpTool[] {
+  let tools = isolatedToolsByDir.get(cwd)
+  if (tools === undefined) {
+    tools = isolateTools(cwd, projectTools(cwd, noAppInServer))
+    isolatedToolsByDir.set(cwd, tools)
+  }
+  return tools
+}
+
+/** The project's resources and prompts, with the ones the app declares. */
+function appFeatures(cwd: string, surface: IsolatedSurface): McpServerFeatures {
+  return {
+    resources: [
+      ...isolateResources(cwd, projectResources(cwd, noAppInServer)),
+      ...surface.resources,
+    ],
+    prompts: [...projectPrompts(), ...surface.prompts],
   }
 }
 
 const ROOTS_REQUEST_ID = "nifra:roots/list"
+const MAX_STDIO_MESSAGE_BYTES = 8 * 1024 * 1024
+const STDIO_ENCODER = new TextEncoder()
+
+interface ProjectApp {
+  readonly name: string
+  readonly cwd: string
+  readonly surface: () => Promise<IsolatedSurface>
+}
 
 /** Everything derived from the project root - rebuilt wholesale when the root changes (adoption of a
  * client workspace root), so no per-tool state can keep pointing at the old directory. */
 interface ProjectContext {
-  readonly monorepo: Awaited<ReturnType<typeof detectMonorepo>>
+  /** A monorepo root's apps; `undefined` when the root is one app. */
+  readonly apps: readonly ProjectApp[] | undefined
   readonly features: McpServerFeatures
-  readonly loadAppCached: () => Promise<LoadedApp>
+  readonly surface: () => Promise<IsolatedSurface>
 }
 
 async function createProjectContext(root: string): Promise<ProjectContext> {
-  const monorepo = await detectMonorepo(root)
+  const monorepo = await detectMonorepoIsolated(root)
   if (monorepo) {
-    const appEntries = await loadMonorepoApps(root, monorepo)
+    const apps = (await loadMonorepoApps(root, monorepo)).map(
+      ({ name, cwd }): ProjectApp => ({ name, cwd, surface: createAppSurface(cwd) }),
+    )
     const allResources: McpResource[] = []
     const allPrompts: McpPrompt[] = []
-    for (const { name, cwd: appCwd } of appEntries) {
-      const loader = createCachedAppLoader(appCwd)
-      const ns = namespaceForApp(
-        name,
-        [],
-        await backendFeatures(loader, projectFeatures(appCwd, loader)),
-      )
+    for (const { name, cwd: appCwd, surface } of apps) {
+      const ns = namespaceForApp(name, [], appFeatures(appCwd, await surface()))
       allResources.push(...(ns.features.resources ?? []))
       allPrompts.push(...(ns.features.prompts ?? []))
     }
     return {
-      monorepo,
+      apps,
       features: { resources: allResources, prompts: allPrompts },
-      loadAppCached: createCachedAppLoader(root),
+      surface: createAppSurface(root),
     }
   }
-  const loadAppCached = createCachedAppLoader(root)
-  return {
-    monorepo,
-    features: await backendFeatures(loadAppCached, projectFeatures(root, loadAppCached)),
-    loadAppCached,
-  }
+  const surface = createAppSurface(root)
+  return { apps: undefined, features: appFeatures(root, await surface()), surface }
 }
 
 /**
@@ -210,22 +237,49 @@ export async function runMcpServer(
     throw new Error(`nifra mcp: directory not found: ${requested}`)
   }
   let rootState = await resolveRootState(requested, explicitDir !== undefined)
+  if (rootState.isProject) {
+    // Before anything reads stdin: a hand-off child inherits the descriptor and owns the session.
+    const exitCode = await delegateToProjectCli({
+      cwd,
+      root: rootState.root,
+      version,
+      args: explicitDir === undefined ? [] : [requested],
+    })
+    if (exitCode !== undefined) {
+      process.exitCode = exitCode
+      return
+    }
+  }
   let ctx = await createProjectContext(rootState.root)
   let drift: ToolingDrift | undefined = await detectToolingDrift(rootState.root, version)
   const serverInfo = { name: "nifra", version }
   const state = createMcpProtocolState()
   const send = (message: JsonRpcResponse | JsonRpcNotification): void => {
-    process.stdout.write(`${JSON.stringify(message)}\n`)
+    let encoded: string
+    try {
+      encoded = JSON.stringify(message)
+    } catch {
+      encoded = JSON.stringify(
+        rpcError(responseIdOf(message), -32603, "MCP response is not serializable"),
+      )
+    }
+    if (STDIO_ENCODER.encode(encoded).byteLength > MAX_STDIO_MESSAGE_BYTES)
+      encoded = JSON.stringify(
+        rpcError(responseIdOf(message), -32603, "MCP response exceeded the size limit"),
+      )
+    process.stdout.write(`${encoded}\n`)
   }
   let rootsSupported = false
+  let rootsRequestPending = false
   const requestRoots = (): void => {
-    if (!rootsSupported) return
+    if (!rootsSupported || rootsRequestPending) return
+    rootsRequestPending = true
     process.stdout.write(
       `${JSON.stringify({ jsonrpc: "2.0", id: ROOTS_REQUEST_ID, method: "roots/list" })}\n`,
     )
   }
-  const onRootsAnswer = async (message: JsonRpcRequest): Promise<void> => {
-    const result = (message as { result?: unknown }).result
+  const onRootsAnswer = async (message: JsonRpcResponse): Promise<void> => {
+    const result = "result" in message ? message.result : undefined
     // An error response (or a malformed one) carries no roots: keep the current state - the absence
     // of workspace data is not a mismatch, and never a reason to move the root.
     if (result === undefined) return
@@ -241,35 +295,42 @@ export async function runMcpServer(
   // must see the adopted root, even though dispatches themselves run concurrently.
   let rootsUpdate: Promise<void> = Promise.resolve()
 
+  const dispatchRootsAnswer = (message: JsonRpcResponse): void => {
+    // The roots answer is a response to a request initiated by this server, not a client RPC request.
+    // Serialize adoption with normal dispatch so a following request cannot observe a half-updated root.
+    if (!rootsRequestPending) return
+    rootsRequestPending = false
+    rootsUpdate = onRootsAnswer(message).catch(() => {})
+  }
+
   const dispatch = async (message: JsonRpcRequest): Promise<void> => {
-    // The client's answer to OUR `roots/list` request - a response (id, no method), which the pure
-    // dispatch would reject as an unknown method. Intercept it before handleRpc ever sees it.
-    if (message.method === undefined && message.id === ROOTS_REQUEST_ID) {
-      // Swallow failures: a bad answer must not poison the chain and 500 every later dispatch.
-      rootsUpdate = onRootsAnswer(message).catch(() => {})
-      await rootsUpdate
-      return
-    }
     await rootsUpdate
     if (message.method === "initialize") {
       rootsSupported = clientSupportsRoots(message.params)
     }
 
     let activeTools: McpTool[]
-    if (ctx.monorepo) {
-      const appEntries = await loadMonorepoApps(rootState.root, ctx.monorepo)
+    if (ctx.apps) {
       const allTools: McpTool[] = []
-      for (const { name, cwd: appCwd } of appEntries) {
-        const loader = createCachedAppLoader(appCwd)
-        const tools = [...projectTools(appCwd, loader), ...(await appDeclaredTools(loader))]
+      for (const { name, cwd: appCwd, surface } of ctx.apps) {
+        const tools = [
+          ...refuseVersionSensitive(isolatedProjectTools(appCwd), drift),
+          ...(await surface()).tools,
+        ]
         const ns = namespaceForApp(name, tools, { resources: [], prompts: [] })
         allTools.push(...ns.tools)
       }
-      activeTools = [...docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus), ...allTools]
+      activeTools = [
+        ...refuseVersionSensitive(
+          docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus),
+          drift,
+        ),
+        ...allTools,
+      ]
     } else {
       activeTools = [
-        ...projectTools(rootState.root, ctx.loadAppCached),
-        ...(await appDeclaredTools(ctx.loadAppCached)),
+        ...refuseVersionSensitive(isolatedProjectTools(rootState.root), drift),
+        ...(await ctx.surface()).tools,
       ]
     }
     const verdict = await rootVerdict(rootState)
@@ -287,6 +348,8 @@ export async function runMcpServer(
     const response = await handleRpc(message, activeTools, serverInfo, features, {
       state,
       sendNotification: send,
+      // The stdio caller is the developer's own agent: a failure it cannot read it cannot fix.
+      exposeToolErrors: true,
     })
     if (response) send(response)
     // Ask for the client's workspace roots once the handshake completes, and again whenever the
@@ -301,25 +364,64 @@ export async function runMcpServer(
 
   const decoder = new TextDecoder()
   let buffer = ""
+  let bufferBytes = 0
+  let discardingOversized = false
+  const processLine = (rawLine: string): void => {
+    const line = rawLine.trim()
+    if (line === "") return
+    if (STDIO_ENCODER.encode(rawLine).byteLength > MAX_STDIO_MESSAGE_BYTES) {
+      send(rpcError(null, -32600, "MCP message exceeded the size limit"))
+      return
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(line) as unknown
+    } catch {
+      send(rpcError(null, -32700, "parse error"))
+      return
+    }
+    if (isJsonRpcRequest(parsed)) {
+      void dispatch(parsed).catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err)
+        send(rpcError(parsed.id ?? null, -32603, msg))
+      })
+    } else if (isJsonRpcResponse(parsed) && parsed.id === ROOTS_REQUEST_ID) {
+      dispatchRootsAnswer(parsed)
+    } else {
+      // Do not let null, arrays, scalars, responses for unknown ids, or malformed envelopes reach the
+      // dispatch shell. In particular, reading `.id` from a hostile `null` must never crash the loop.
+      send(rpcError(null, -32600, "Invalid Request"))
+    }
+  }
   for await (const chunk of Bun.stdin.stream()) {
-    buffer += decoder.decode(chunk as Uint8Array, { stream: true })
+    let text = decoder.decode(chunk as Uint8Array, { stream: true })
+    if (discardingOversized) {
+      const newline = text.indexOf("\n")
+      if (newline === -1) continue
+      text = text.slice(newline + 1)
+      discardingOversized = false
+    }
+    buffer += text
+    bufferBytes += STDIO_ENCODER.encode(text).byteLength
     let nl = buffer.indexOf("\n")
     while (nl !== -1) {
-      const line = buffer.slice(0, nl).trim()
+      const line = buffer.slice(0, nl)
       buffer = buffer.slice(nl + 1)
+      bufferBytes = Math.max(0, bufferBytes - STDIO_ENCODER.encode(line).byteLength - 1)
       nl = buffer.indexOf("\n")
-      if (line === "") continue
-      let message: JsonRpcRequest
-      try {
-        message = JSON.parse(line)
-      } catch {
-        send(rpcError(null, -32700, "parse error"))
-        continue
-      }
-      void dispatch(message).catch((err) => {
-        const msg = err instanceof Error ? err.message : String(err)
-        send(rpcError(message.id ?? null, -32603, msg))
-      })
+      processLine(line)
+    }
+    if (bufferBytes > MAX_STDIO_MESSAGE_BYTES) {
+      buffer = ""
+      bufferBytes = 0
+      discardingOversized = true
+      send(rpcError(null, -32600, "MCP message exceeded the size limit"))
     }
   }
 }
+
+function responseIdOf(message: JsonRpcResponse | JsonRpcNotification): string | number | null {
+  if (!("id" in message)) return null
+  const id = message.id
+  return id === null || typeof id === "string" || typeof id === "number" ? id : null
+}