@nifrajs/cli 4.0.0 → 5.0.0

package/src/mcp-exec.ts

@@ -8,7 +8,7 @@
 
 import { type Dirent, realpathSync } from "node:fs"
 import { readdir, stat } from "node:fs/promises"
-import { relative, resolve } from "node:path"
+import { isAbsolute, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
 import {
@@ -24,7 +24,7 @@ import {
 import { collectContractProof } from "./contract-proof.ts"
 import { loadDocsCorpus } from "./docs-search.ts"
 import { loadExamplesCorpus } from "./examples.ts"
-import type { LoadAppOptions, LoadedApp } from "./load.ts"
+import type { AppLoader, IntrospectedApp, LoadAppOptions, LoadedApp } from "./load.ts"
 import {
   type CommandMcpToolOptions,
   dirError,
@@ -36,7 +36,9 @@ import {
   CHILD_INPUT_MAX_BYTES,
   CHILD_OUTPUT_MAX_BYTES,
   CHILD_TIMEOUT_MS,
+  OWN_PROCESS_GROUP,
   readBoundedStream,
+  signalProcessGroup,
   timeoutMessage,
   validateLocalPort,
 } from "./mcp-io.ts"
@@ -46,20 +48,29 @@ import { loadTypesCorpus } from "./types-search.ts"
 
 const CODEFRAME_SOURCE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|mdx)$/i
 
+type GatePaths = Pick<typeof import("node:path"), "isAbsolute" | "relative" | "resolve">
+
 /** The files a stack the caller supplies may show a codeframe from: project source, never a dotfile
- * or anything under a dot directory (`.env`, `.git/`, `.nifra/`). */
-function explainSourceGate(root: string): (file: string) => boolean {
+ * or anything under a dot directory (`.env`, `.git/`, `.nifra/`), and never a file outside the root -
+ * which on Windows includes one on another drive, where `relative` answers with an absolute path. */
+export function explainSourceGate(
+  root: string,
+  paths: GatePaths = { isAbsolute, relative, resolve },
+): (file: string) => boolean {
   // The codeframe reads a native realpath, which expands a Windows short name (`RUNNER~1`); the root
   // has to be spelled the same way or every file looks like it sits outside it.
-  let base = resolve(root)
+  let base = paths.resolve(root)
   try {
     base = realpathSync.native(base)
   } catch {}
-  return (file) =>
-    CODEFRAME_SOURCE.test(file) &&
-    !relative(base, file)
-      .split(/[\\/]/)
-      .some((segment) => segment.startsWith("."))
+  return (file) => {
+    const inside = paths.relative(base, file)
+    return (
+      CODEFRAME_SOURCE.test(file) &&
+      !paths.isAbsolute(inside) &&
+      !inside.split(/[\\/]/).some((segment) => segment.startsWith("."))
+    )
+  }
 }
 
 /** Path to a sibling child entry (`mcp-run` / `mcp-render` / `mcp-ws`), resolved next to this module (`.ts` in
@@ -74,7 +85,16 @@ 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
+  const pathFields = [
+    "config",
+    "out",
+    "lockfile",
+    "before",
+    "after",
+    "baseline",
+    "file",
+    "since",
+  ] as const
   const catalogEntry = entry ?? toCommandCatalogEntry(spec)
   return {
     name: commandMcpName(catalogEntry.name),
@@ -143,7 +163,7 @@ export function toMcpTool(
 
 export function catalogProjectTools(
   cwd: string,
-  loadAppCached: () => Promise<LoadedApp> = createCachedAppLoader(cwd),
+  loadAppCached: AppLoader = createCachedAppLoader(cwd),
 ): McpTool[] {
   return commandCatalog
     .filter((entry) => entry.transports.includes("mcp"))
@@ -156,11 +176,11 @@ export function catalogProjectTools(
 
 export function projectTools(
   cwd: string,
-  loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
+  loadAppCached: AppLoader = createCachedAppLoader(cwd),
 ): McpTool[] {
   const warmRun = createWarmHandler("mcp-run", cwd, "run")
   const warmRender = createWarmHandler("mcp-render", cwd, "render")
-  const catalogTools = catalogProjectTools(cwd, () => loadAppCached())
+  const catalogTools = catalogProjectTools(cwd, loadAppCached)
   const legacyTools: McpTool[] = [
     {
       name: "nifra_verify",
@@ -692,12 +712,13 @@ export async function spawnChild(
     stdin: "pipe",
     stdout: "pipe",
     stderr: "pipe",
+    detached: OWN_PROCESS_GROUP,
   })
   let killed = false
   const kill = (): void => {
     if (killed) return
     killed = true
-    proc.kill()
+    signalProcessGroup(proc, "SIGTERM")
   }
   const abort = (): void => kill()
   signal?.addEventListener("abort", abort, { once: true })
@@ -791,6 +812,16 @@ type PipeSubprocess = ReturnType<typeof Bun.spawn> & {
   readonly stderr: ReadableStream<Uint8Array>
 }
 
+const liveWarmWorkers = new Set<WarmWorker>()
+let warmWorkersClosed = false
+
+/** Stop every warm worker and start no more, once the MCP client has closed stdin. A live worker
+ * holds the process open, so the server would otherwise never exit. */
+export function closeWarmWorkers(): void {
+  warmWorkersClosed = true
+  for (const worker of liveWarmWorkers) worker.stop()
+}
+
 /** A persistent `mcp-run`/`mcp-render` `--worker` subprocess: the backend/web app is loaded ONCE and
  * reused across newline-delimited `{ id, input }` requests, replying `{ id, output }`. The same machinery
  * powers both `nifra_run warm` and `nifra_render warm` - `child` selects which engine, `label` shapes the
@@ -827,10 +858,12 @@ export class WarmWorker {
       stdout: "pipe",
       stderr: "pipe",
     }) as PipeSubprocess
+    liveWarmWorkers.add(this)
     void this.readStdout()
     void this.readStderr()
     void this.proc.exited.then((code) => {
       this.closed = true
+      liveWarmWorkers.delete(this)
       const err = new Error(
         `warm ${this.label} worker exited (${code})${this.stderrBuffer ? `:\n${this.stderrBuffer}` : ""}`,
       )
@@ -1025,8 +1058,10 @@ export function createWarmHandler(
   label: string,
 ): (input: unknown, signal?: AbortSignal) => Promise<string> {
   let worker: WarmWorker | undefined
+  const shuttingDown = `${label} cancelled: the MCP server is shutting down.`
   return async (input, signal) => {
     const fingerprint = await warmRunFingerprint(cwd)
+    if (warmWorkersClosed) return shuttingDown
     let current = worker
     if (current === undefined || current.fingerprint !== fingerprint) {
       current?.stop()
@@ -1044,6 +1079,7 @@ export function createWarmHandler(
         const reason = cancellationSuffix(signal)
         return `${label} cancelled${reason}.`
       }
+      if (warmWorkersClosed) return shuttingDown
       return spawnChild(child, cwd, input, label, signal)
     }
   }
@@ -1146,7 +1182,7 @@ export async function appFingerprint(cwd: string): Promise<string> {
 export function createCachedAppLoader(
   cwd: string,
   options: CachedAppLoaderOptions = {},
-): (outDirName?: string) => Promise<LoadedApp> {
+): AppLoader {
   const loadAppCached =
     options.loadApp ??
     (async (root: string, outDirName?: string, loadOptions?: LoadAppOptions) => {
@@ -1162,7 +1198,7 @@ export function createCachedAppLoader(
       }
     | undefined
 
-  return async (outDirName = "dist") => {
+  const whole = async (outDirName = "dist"): Promise<LoadedApp> => {
     const nextFingerprint = await fingerprint(cwd)
     if (
       cached !== undefined &&
@@ -1177,4 +1213,11 @@ export function createCachedAppLoader(
     cached = { outDirName, fingerprint: nextFingerprint, app }
     return app
   }
+  const backend = async (): Promise<IntrospectedApp> => {
+    const { hasAppConfig, loadBackendApp } = await import("./load.ts")
+    if (hasAppConfig(cwd)) return whole()
+    // The fingerprint names backend/app.ts, so an edit loads a fresh module and no edit reuses it.
+    return loadBackendApp(cwd, { importQuery: cacheToken(await fingerprint(cwd)) })
+  }
+  return Object.assign(whole, { backend })
 }

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 = "4.0.0"
+const VERSION = "5.0.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 =>

package/src/mcp-io.ts

@@ -16,6 +16,47 @@ 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.
+  }
+}
+
+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-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[]>()
 
@@ -308,6 +309,9 @@ 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)
 
     let activeTools: McpTool[]
     if (ctx.apps) {
@@ -418,6 +422,7 @@ export async function runMcpServer(
       send(rpcError(null, -32600, "MCP message exceeded the size limit"))
     }
   }
+  closeWarmWorkers()
 }
 
 function responseIdOf(message: JsonRpcResponse | JsonRpcNotification): string | number | null {