@nifrajs/cli 4.0.2 → 5.1.0

package/src/mcp-io.ts

@@ -16,6 +16,80 @@ export const CHILD_INPUT_MAX_BYTES = 4 * 1024 * 1024
 export const LOCAL_TOOL_FETCH_TIMEOUT_MS = 2_000
 export const LOCAL_TOOL_MAX_RESPONSE_BYTES = 1_048_576
 
+/**
+ * On POSIX a bounded child is spawned `detached`, leading its own process group, so stopping it
+ * reaches every process it started. Otherwise a grandchild still holding the pipes keeps the read,
+ * and the tool call, open past its timeout.
+ */
+export const OWN_PROCESS_GROUP = process.platform !== "win32"
+
+/** Signal a child spawned with `detached: OWN_PROCESS_GROUP`: its whole group on POSIX. */
+export function signalProcessGroup(
+  proc: { readonly pid: number; kill(signal?: NodeJS.Signals): void },
+  signal: NodeJS.Signals,
+): void {
+  try {
+    if (OWN_PROCESS_GROUP) process.kill(-proc.pid, signal)
+    else proc.kill(signal)
+  } catch {
+    // The group has already exited.
+  }
+}
+
+/** How long a stopped child gets to exit after SIGTERM before it is sent SIGKILL. */
+export const KILL_GRACE_MS = 2_000
+
+/** Stopping a child: `stop` sends SIGTERM, `dispose` drops the SIGKILL still pending once it is done. */
+export interface EscalatingStop {
+  readonly stop: () => void
+  readonly dispose: () => void
+}
+
+/**
+ * Stop a child with SIGTERM, then SIGKILL once `graceMs` passes. Project code can catch SIGTERM
+ * (a graceful-shutdown hook waiting on a hung request), and a child that never exits keeps its
+ * caller waiting and outlives it. `send` delivers one signal to the child or its group.
+ */
+export function escalatingStop(
+  send: (signal: NodeJS.Signals) => void,
+  graceMs: number = KILL_GRACE_MS,
+): EscalatingStop {
+  let escalation: ReturnType<typeof setTimeout> | undefined
+  let disposed = false
+  return {
+    stop: () => {
+      if (disposed) return
+      send("SIGTERM")
+      escalation ??= setTimeout(() => send("SIGKILL"), graceMs)
+    },
+    dispose: () => {
+      disposed = true
+      clearTimeout(escalation)
+    },
+  }
+}
+
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const
+
+/**
+ * A child in its own group no longer gets the Ctrl+C the terminal sends its parent: on SIGINT,
+ * SIGTERM or SIGHUP run `stop`, then let this process take the signal as it would have. Returns the
+ * function that removes the listeners.
+ */
+export function forwardTerminalSignals(stop: () => void): () => void {
+  if (!OWN_PROCESS_GROUP) return () => {}
+  const remove = (): void => {
+    for (const name of FORWARDED_SIGNALS) process.off(name, forward)
+  }
+  const forward = (signal: NodeJS.Signals): void => {
+    stop()
+    remove()
+    process.kill(process.pid, signal)
+  }
+  for (const name of FORWARDED_SIGNALS) process.on(name, forward)
+  return remove
+}
+
 /** Accept only a concrete TCP port. Port 0 (bind-any-free-port) is not a valid read target. */
 export function validateLocalPort(port: unknown): number | undefined {
   return typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65_535

package/src/mcp-isolate.ts

@@ -13,7 +13,13 @@ import { fileURLToPath } from "node:url"
 import { CONFIG_FILE } from "./app-files.ts"
 import type { NifraMonorepoConfig } from "./load.ts"
 import { appFingerprint } from "./mcp-exec.ts"
-import { CHILD_TIMEOUT_MS, readBoundedLines, readBoundedStream } from "./mcp-io.ts"
+import {
+  CHILD_TIMEOUT_MS,
+  OWN_PROCESS_GROUP,
+  readBoundedLines,
+  readBoundedStream,
+  signalProcessGroup,
+} from "./mcp-io.ts"
 import type {
   AppSurface,
   ProjectChildAnswer,
@@ -121,6 +127,7 @@ export async function askProjectChild(
       stdin: "pipe",
       stdout: "pipe",
       stderr: "pipe",
+      detached: OWN_PROCESS_GROUP,
     })
   } catch (error) {
     return failed(
@@ -131,7 +138,7 @@ export async function askProjectChild(
   const stop = (reason: "timeout" | "cancel"): void => {
     if (stopped !== undefined) return
     stopped = reason
-    proc.kill("SIGKILL")
+    signalProcessGroup(proc, "SIGKILL")
   }
   const timer = timeoutMs === undefined ? undefined : setTimeout(() => stop("timeout"), timeoutMs)
   const onAbort = (): void => stop("cancel")

package/src/mcp-path.ts

@@ -1,12 +1,14 @@
 import { realpathSync } from "node:fs"
-import { basename, isAbsolute, relative, resolve } from "node:path"
+import { isAbsolute, relative, resolve } from "node:path"
+import { writeTargetOf } from "./project-path.ts"
 
 /**
  * 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.
+ * exist yet while still canonicalizing every existing path component, and a dangling symlink is
+ * judged by where it points.
  */
 export function resolveMcpProjectPath(root: string, value: string): string | null {
   if (value.length === 0 || isAbsolute(value)) return null
@@ -23,26 +25,10 @@ export function resolveMcpProjectPath(root: string, value: string): string | nul
     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
-    }
-  }
+  const candidate = writeTargetOf(target)
+  if (candidate === undefined) return null
+  const candidateRelative = relative(canonicalRoot, candidate)
+  return candidateRelative.startsWith("..") || isAbsolute(candidateRelative) ? null : candidate
 }
 
 export function mcpProjectPathError(label: string, value: string): string {

package/src/mcp-project-child.ts

@@ -67,7 +67,7 @@ export async function answerProjectRequest(
     }
     const loadAppCached = createCachedAppLoader(cwd)
     const backend = (): Promise<unknown> =>
-      loadAppCached().then(
+      loadAppCached.backend().then(
         (app) => app.backend,
         () => undefined,
       )

package/src/mcp-root.ts

@@ -17,7 +17,7 @@
  * Everything here is pure state + fs probes; the I/O wiring lives in `./mcp.ts`.
  */
 
-import { readFile } from "node:fs/promises"
+import { readdir, readFile, stat } from "node:fs/promises"
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 
@@ -46,6 +46,8 @@ const MAX_ROOT_PATH_LENGTH = 4_096
 /** Workspace members probed per workspace root. A monorepo larger than this is pointed at explicitly
  * (`nifra mcp <dir>`) rather than scanned on every server start. */
 const MAX_WORKSPACE_MEMBERS = 256
+/** Directories one workspace probe may read while matching member patterns. */
+const MAX_WORKSPACE_DIRECTORIES = 4_096
 
 /** A directory is a nifra project when its `package.json` depends on any `@nifrajs/*` package, or it
  * is a `nifra.config.ts` monorepo root. Backend-only projects (no web config, no `routes/`) count -
@@ -102,6 +104,57 @@ async function workspacePatterns(dir: string): Promise<readonly string[] | null>
   )
 }
 
+/**
+ * The directories under `dir` that `pattern` matches and that hold a `package.json`, in name order. A
+ * walk rather than a glob scan: a `**` pattern would otherwise descend every `node_modules` below it,
+ * where a member never lives. It starts at the pattern's literal prefix, stops at the pattern's depth
+ * unless it has a `**`, skips dot directories, and draws on one directory budget for the whole probe.
+ */
+async function workspaceMatches(
+  dir: string,
+  pattern: string,
+  budget: { directories: number },
+): Promise<string[]> {
+  const segments = pattern
+    .replace(/^\.\//, "")
+    .replace(/\/+$/, "")
+    .split("/")
+    .filter((segment) => segment !== "" && segment !== ".")
+  const firstGlob = segments.findIndex((segment) => /[*?[{]/.test(segment))
+  const prefix = firstGlob === -1 ? segments : segments.slice(0, firstGlob)
+  const depth = segments.includes("**") ? Number.POSITIVE_INFINITY : segments.length
+  const glob = new Bun.Glob(segments.join("/"))
+  const found: string[] = []
+  const queue: { readonly path: string; readonly depth: number }[] = [
+    { path: prefix.join("/"), depth: prefix.length },
+  ]
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    if (budget.directories <= 0) break
+    budget.directories -= 1
+    const absolute = join(dir, next.path)
+    if (next.path !== "" && glob.match(next.path) && (await isFile(join(absolute, "package.json"))))
+      found.push(next.path)
+    if (next.depth >= depth) continue
+    const entries = await readdir(absolute, { withFileTypes: true }).catch(() => [])
+    const names = entries
+      .filter(
+        (entry) =>
+          entry.isDirectory() && entry.name !== "node_modules" && !entry.name.startsWith("."),
+      )
+      .map((entry) => entry.name)
+      .sort()
+    for (const name of names) {
+      queue.push({ path: next.path === "" ? name : `${next.path}/${name}`, depth: next.depth + 1 })
+    }
+  }
+  return found
+}
+
+const isFile = (path: string): Promise<boolean> =>
+  stat(path)
+    .then((info) => info.isFile())
+    .catch(() => false)
+
 /**
  * The nifra projects among `dir`'s package-manager workspace members, in declaration order. Empty when
  * `dir` declares no `workspaces`. A member is a directory a pattern matches that holds a `package.json`;
@@ -111,15 +164,12 @@ export async function workspaceProjects(dir: string): Promise<string[]> {
   const patterns = await workspacePatterns(dir)
   if (patterns === null) return []
   const members = new Set<string>()
-  let probed = 0
+  const budget = { directories: MAX_WORKSPACE_DIRECTORIES }
   for (const pattern of patterns) {
-    const glob = new Bun.Glob(`${pattern.replace(/\/+$/, "")}/package.json`)
-    for await (const match of glob.scan({ cwd: dir, onlyFiles: true })) {
-      if (match.split(/[\\/]/).includes("node_modules")) continue
-      if (++probed > MAX_WORKSPACE_MEMBERS) break
-      members.add(dirname(join(dir, match)))
+    for (const member of await workspaceMatches(dir, pattern, budget)) {
+      if (members.size === MAX_WORKSPACE_MEMBERS) break
+      members.add(join(dir, member))
     }
-    if (probed > MAX_WORKSPACE_MEMBERS) break
   }
   const projects: string[] = []
   for (const member of members) if (await isNifraProjectDir(member)) projects.push(member)

package/src/mcp-ws.ts

@@ -21,7 +21,7 @@ interface RunningServerLike {
 }
 
 interface ListenableApp {
-  listen(port: number): RunningServerLike
+  listen(port: number, options: { readonly hostname: string }): RunningServerLike
 }
 
 interface NormalizedInput {
@@ -206,7 +206,9 @@ export async function runWebSocket(
   let running: RunningServerLike | undefined
   let socket: WebSocket | undefined
   try {
-    running = app.listen(0)
+    // Loopback only: the project's backend, with its environment loaded, must not be reachable
+    // from the network for the length of a verification.
+    running = app.listen(0, { hostname: "127.0.0.1" })
     const url = `ws://127.0.0.1:${running.port}${normalized.path}`
     socket = new WebSocket(url)
     socket.binaryType = "arraybuffer"

package/src/mcp.ts

@@ -52,7 +52,7 @@ import { stat } from "node:fs/promises"
 import { resolve } from "node:path"
 import { loadDocsCorpus } from "./docs-search.ts"
 import { loadExamplesCorpus } from "./examples.ts"
-import type { LoadedApp } from "./load.ts"
+import type { AppLoader } from "./load.ts"
 import { loadMonorepoApps } from "./load.ts"
 import { delegateToProjectCli, refuseVersionSensitive } from "./mcp-delegate.ts"
 import { docsTools } from "./mcp-docs-tools.ts"
@@ -108,7 +108,7 @@ export {
 } from "./mcp-io.ts"
 export { clientSupportsRoots, guardTools } from "./mcp-root.ts"
 
-import { projectTools } from "./mcp-exec.ts"
+import { closeWarmWorkers, projectTools } from "./mcp-exec.ts"
 import {
   createAppSurface,
   detectMonorepoIsolated,
@@ -147,10 +147,11 @@ export {
  * 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> =>
+const refuseApp = (): Promise<never> =>
   Promise.reject(
     new Error("[nifra] the MCP server does not load the app; project code runs in a subprocess"),
   )
+const noAppInServer: AppLoader = Object.assign(refuseApp, { backend: refuseApp })
 
 const isolatedToolsByDir = new Map<string, McpTool[]>()
 
@@ -180,6 +181,13 @@ function appFeatures(cwd: string, surface: IsolatedSurface): McpServerFeatures {
 }
 
 const ROOTS_REQUEST_ID = "nifra:roots/list"
+/** Messages whose answer reads nothing the app declares: the handshake is never held up by its import. */
+const ANSWERED_WITHOUT_THE_APP: ReadonlySet<string> = new Set([
+  "initialize",
+  "ping",
+  "notifications/initialized",
+  "notifications/roots/list_changed",
+])
 const MAX_STDIO_MESSAGE_BYTES = 8 * 1024 * 1024
 const STDIO_ENCODER = new TextEncoder()
 
@@ -206,8 +214,12 @@ async function createProjectContext(root: string): Promise<ProjectContext> {
     )
     const allResources: McpResource[] = []
     const allPrompts: McpPrompt[] = []
-    for (const { name, cwd: appCwd, surface } of apps) {
-      const ns = namespaceForApp(name, [], appFeatures(appCwd, await surface()))
+    // Each app loads in its own subprocess, so they load side by side.
+    const loaded = await Promise.all(
+      apps.map(async (app) => ({ app, surface: await app.surface() })),
+    )
+    for (const { app, surface } of loaded) {
+      const ns = namespaceForApp(app.name, [], appFeatures(app.cwd, surface))
       allResources.push(...(ns.features.resources ?? []))
       allPrompts.push(...(ns.features.prompts ?? []))
     }
@@ -250,7 +262,9 @@ export async function runMcpServer(
       return
     }
   }
-  let ctx = await createProjectContext(rootState.root)
+  // Loaded in the background: the app's import can take seconds, and the handshake needs none of it.
+  let ctx = createProjectContext(rootState.root)
+  ctx.catch(() => {})
   let drift: ToolingDrift | undefined = await detectToolingDrift(rootState.root, version)
   const serverInfo = { name: "nifra", version }
   const state = createMcpProtocolState()
@@ -285,7 +299,8 @@ export async function runMcpServer(
     if (result === undefined) return
     const next = await applyClientRoots(rootState, pathsFromRootsResult(result))
     if (next.root !== rootState.root) {
-      ctx = await createProjectContext(next.root)
+      ctx = createProjectContext(next.root)
+      ctx.catch(() => {})
       drift = await detectToolingDrift(next.root, version)
     }
     rootState = next
@@ -308,16 +323,42 @@ export async function runMcpServer(
     if (message.method === "initialize") {
       rootsSupported = clientSupportsRoots(message.params)
     }
+    // An install during the session changes the nifra the project builds with, and this process keeps
+    // the code it started with: re-read the installed version per call so no answer is for a stale one.
+    if (message.method === "tools/call") drift = await detectToolingDrift(rootState.root, version)
 
+    const method = message.method ?? ""
+    if (ANSWERED_WITHOUT_THE_APP.has(method)) {
+      const response = await handleRpc(
+        message,
+        [],
+        serverInfo,
+        {
+          resources: projectResources(rootState.root, noAppInServer),
+          prompts: projectPrompts(),
+          instructions: rootInstructions(rootState, drift),
+        },
+        { state, sendNotification: send, exposeToolErrors: true },
+      )
+      if (response) send(response)
+      // Ask for the client's workspace roots once the handshake completes, and again whenever the
+      // client says they changed. The answer comes back through the interception above.
+      if (method.startsWith("notifications/")) requestRoots()
+      return
+    }
+    const project = await ctx
     let activeTools: McpTool[]
-    if (ctx.apps) {
+    if (project.apps) {
+      const loaded = await Promise.all(
+        project.apps.map(async (app) => ({ app, surface: await app.surface() })),
+      )
       const allTools: McpTool[] = []
-      for (const { name, cwd: appCwd, surface } of ctx.apps) {
+      for (const { app, surface } of loaded) {
         const tools = [
-          ...refuseVersionSensitive(isolatedProjectTools(appCwd), drift),
-          ...(await surface()).tools,
+          ...refuseVersionSensitive(isolatedProjectTools(app.cwd), drift),
+          ...surface.tools,
         ]
-        const ns = namespaceForApp(name, tools, { resources: [], prompts: [] })
+        const ns = namespaceForApp(app.name, tools, { resources: [], prompts: [] })
         allTools.push(...ns.tools)
       }
       activeTools = [
@@ -330,7 +371,7 @@ export async function runMcpServer(
     } else {
       activeTools = [
         ...refuseVersionSensitive(isolatedProjectTools(rootState.root), drift),
-        ...(await ctx.surface()).tools,
+        ...(await project.surface()).tools,
       ]
     }
     const verdict = await rootVerdict(rootState)
@@ -342,7 +383,7 @@ export async function runMcpServer(
     )
 
     const features: McpServerFeatures = {
-      ...ctx.features,
+      ...project.features,
       instructions: rootInstructions(rootState, drift),
     }
     const response = await handleRpc(message, activeTools, serverInfo, features, {
@@ -352,14 +393,6 @@ export async function runMcpServer(
       exposeToolErrors: true,
     })
     if (response) send(response)
-    // Ask for the client's workspace roots once the handshake completes, and again whenever the
-    // client says they changed. The answer comes back through the interception above.
-    if (
-      message.method === "notifications/initialized" ||
-      message.method === "notifications/roots/list_changed"
-    ) {
-      requestRoots()
-    }
   }
 
   const decoder = new TextDecoder()
@@ -418,6 +451,7 @@ export async function runMcpServer(
       send(rpcError(null, -32600, "MCP message exceeded the size limit"))
     }
   }
+  closeWarmWorkers()
 }
 
 function responseIdOf(message: JsonRpcResponse | JsonRpcNotification): string | number | null {