@nifrajs/cli 4.0.2 → 5.1.0

package/src/load.ts

@@ -40,6 +40,12 @@ export type PluginsField =
  * don't).
  */
 export interface NifraFramework {
+  /** Optional coordinated Vite 8 component graph. Tooling stays in nifra.config.ts. */
+  readonly componentPipeline?: Omit<
+    import("@nifrajs/web/server-components/build").ComponentPipelineOptions,
+    "root" | "outDir" | "port" | "plugins"
+  >
+  readonly serverComponents?: CreateWebAppOptions["serverComponents"]
   /** The render adapter, e.g. `reactAdapter` from `@nifrajs/web-react`. */
   readonly adapter: unknown
   /** The client runtime module providing `mountRouter`, e.g. `"@nifrajs/web-react/client"`. */
@@ -72,8 +78,11 @@ export interface NifraFramework {
    * targets use the socket peer either way. */
   readonly clientIp?: "platform"
   /** `nifra dev` settings. `indicator: false` turns the in-page issues badge off for every run
-   * (`nifra dev --no-indicator` does it for one); browser errors still reach `nifra errors`. */
-  readonly dev?: { readonly indicator?: boolean }
+   * (`nifra dev --no-indicator` does it for one); browser errors still reach `nifra errors`.
+   * `allowedHosts` lists host names the Bun dev server answers besides loopback ones; it refuses
+   * every other `Host` so a DNS-rebound page cannot read it. The Vite pipeline uses Vite's own
+   * `server.allowedHosts`. */
+  readonly dev?: { readonly indicator?: boolean; readonly allowedHosts?: readonly string[] }
   /** Static files directory. Defaults to `<app>/public`; `false` disables it. */
   readonly publicDir?: string | false
   /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
@@ -85,9 +94,9 @@ export interface NifraFramework {
   readonly cssCodeSplit?: boolean
   /** Framework-owned SSR stylesheet activation. Deferred mode is intended for aggregate CSS. */
   readonly cssLoading?: CssLoadingMode
-  /** Path `backend/app.ts`'s backend is served at (default `"/api"`; `""` turns the mount off). A
-   * page file under it can never render, so the app refuses to start and `nifra build` refuses to
-   * build.
+  /** Path `backend/app.ts`'s backend is served at over HTTP, such as `"/api"`; unset or `""`, it is
+   * not mounted. A page file under it can never render, so the app refuses to start and `nifra build`
+   * refuses to build.
    *
    * The fields from here down reach the generated server entry, so like `use` they MUST be exported
    * from `backend/framework.ts` (re-export them from `nifra.config.ts` when both exist). */
@@ -106,7 +115,14 @@ export interface NifraFramework {
 
 /** The {@link NifraFramework} fields forwarded to `createWebApp` and imported by the generated server
  * entry, in one list so every command that builds the app forwards the same set. */
-export const FRAMEWORK_WEB_OPTIONS = ["apiPrefix", "apiStrip", "mounts", "csp", "nonce"] as const
+export const FRAMEWORK_WEB_OPTIONS = [
+  "apiPrefix",
+  "apiStrip",
+  "mounts",
+  "csp",
+  "nonce",
+  "serverComponents",
+] as const
 export type FrameworkWebOption = (typeof FRAMEWORK_WEB_OPTIONS)[number]
 
 /** Refuse a forwarded field of the wrong shape at load, naming the field, rather than letting it fail
@@ -115,6 +131,24 @@ function assertFrameworkWebOptions(fw: Partial<NifraFramework>, configFile: stri
   const wrong = (field: string, expected: string): never => {
     throw new Error(`[nifra] ${configFile}: \`${field}\` must be ${expected}.`)
   }
+  if (fw.componentPipeline !== undefined) {
+    const pipeline = fw.componentPipeline
+    if (
+      typeof pipeline !== "object" ||
+      pipeline === null ||
+      !["react", "vue", "svelte", "solid", "preact"].includes(pipeline.adapter) ||
+      typeof pipeline.entries !== "object" ||
+      pipeline.entries === null ||
+      typeof pipeline.entries.client !== "string" ||
+      typeof pipeline.entries.ssr !== "string" ||
+      (pipeline.adapter === "react" && typeof pipeline.entries.rsc !== "string") ||
+      (pipeline.adapter !== "react" && pipeline.entries.rsc !== undefined)
+    )
+      wrong(
+        "componentPipeline",
+        "an adapter plus existing client/ssr entries and a React-only rsc entry",
+      )
+  }
   if (fw.apiPrefix !== undefined && typeof fw.apiPrefix !== "string") {
     wrong("apiPrefix", 'a path string such as "/api", or "" to turn the backend mount off')
   }
@@ -143,6 +177,13 @@ function assertFrameworkWebOptions(fw: Partial<NifraFramework>, configFile: stri
     const indicator: unknown = Reflect.get(fw.dev, "indicator")
     if (indicator !== undefined && typeof indicator !== "boolean")
       wrong("dev.indicator", "a boolean")
+    const allowedHosts: unknown = Reflect.get(fw.dev, "allowedHosts")
+    if (
+      allowedHosts !== undefined &&
+      (!Array.isArray(allowedHosts) ||
+        allowedHosts.some((host) => typeof host !== "string" || host.trim() === ""))
+    )
+      wrong("dev.allowedHosts", 'an array of host names such as ["app.test"]')
   }
 }
 
@@ -198,6 +239,23 @@ export interface LoadedApp {
   readonly backend: unknown
 }
 
+/** An API-only app as the backend readers see it: `backend/app.ts` and no web config. */
+export interface BackendOnlyApp {
+  readonly cwd: string
+  readonly backend: unknown
+  readonly framework?: undefined
+}
+
+/** What the backend readers (routes, context, hooks, OpenAPI, the app's MCP surface) load. */
+export type IntrospectedApp = LoadedApp | BackendOnlyApp
+
+/** How a command reaches the app. The MCP server hands out one whose calls both refuse. */
+export interface AppLoader {
+  (outDirName?: string): Promise<LoadedApp>
+  /** The whole app with a web config, else `backend/app.ts` alone. */
+  readonly backend: () => Promise<IntrospectedApp>
+}
+
 export interface LoadAppOptions {
   /** Optional dynamic-import query used by long-lived MCP processes to bust Bun's module cache. */
   readonly importQuery?: string
@@ -258,22 +316,24 @@ const isAdapter = (v: unknown): boolean => typeof v === "object" && v !== null
 const importWithQuery = (path: string, query: string | undefined): Promise<unknown> =>
   import(query === undefined || query === "" ? path : `${path}?${query}`)
 
+/** Whether `cwd` has a web config file, the one thing that makes it more than its backend. */
+export const hasAppConfig = (cwd: string): boolean =>
+  existsSync(resolve(cwd, CONFIG_FILE)) || existsSync(resolve(cwd, FRAMEWORK_FILE))
+
 /**
- * What reads only the backend (`nifra openapi`): the whole app when it has a web config, else
- * `backend/app.ts` alone, so an API-only app needs no adapter to describe its routes.
+ * What reads only the backend: the whole app when it has a web config, else `backend/app.ts`
+ * alone, so an API-only app needs no adapter for its routes, context, hooks or OpenAPI document.
  */
 export async function loadBackendApp(
   cwd: string,
   options: LoadAppOptions = {},
-): Promise<Pick<LoadedApp, "cwd" | "backend">> {
-  if (existsSync(resolve(cwd, CONFIG_FILE)) || existsSync(resolve(cwd, FRAMEWORK_FILE))) {
-    return loadApp(cwd, "dist", options)
-  }
+): Promise<IntrospectedApp> {
+  if (hasAppConfig(cwd)) return loadApp(cwd, "dist", options)
   assertCurrentLayout(cwd)
   const backendPath = resolve(cwd, BACKEND_APP_FILE)
   if (!existsSync(backendPath)) {
     throw new Error(
-      `[nifra] no ${BACKEND_APP_FILE} in ${cwd}: the OpenAPI document describes its routes`,
+      `[nifra] no ${CONFIG_FILE}, ${FRAMEWORK_FILE} or ${BACKEND_APP_FILE} in ${cwd}: a web app needs its config, an API-only app its ${BACKEND_APP_FILE}`,
     )
   }
   const backend = (
@@ -282,9 +342,31 @@ export async function loadBackendApp(
   return { cwd, backend }
 }
 
+/** The fields the generated server entry imports from backend/framework.ts. */
+const SERVER_OPTIONS = [...FRAMEWORK_WEB_OPTIONS, "use"] as const
+
+/**
+ * `config` with each server option it leaves unset taken from backend/framework.ts, so `nifra dev` and
+ * the server entry `nifra build` generates read one value without nifra.config.ts re-exporting it.
+ */
+async function withServerOptions(
+  config: Partial<NifraFramework>,
+  frameworkPath: string,
+  importQuery: string | undefined,
+): Promise<Partial<NifraFramework>> {
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a config module, read like nifra.config.ts; every web option taken from it is validated below.
+  const framework = (await importWithQuery(frameworkPath, importQuery)) as Partial<NifraFramework>
+  const taken: Record<string, unknown> = {}
+  for (const name of SERVER_OPTIONS) {
+    if (config[name] === undefined && framework[name] !== undefined) taken[name] = framework[name]
+  }
+  assertFrameworkWebOptions(taken, FRAMEWORK_FILE)
+  return { ...config, ...taken }
+}
+
 /** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back
- * to
- * `backend/framework.ts`. Throws a clear, actionable error if neither exists or the config is
+ * to `backend/framework.ts`; with both, a server option nifra.config.ts leaves unset comes from
+ * backend/framework.ts. Throws a clear, actionable error if neither exists or the config is
  * malformed. */
 export async function loadApp(
   cwd: string,
@@ -303,7 +385,11 @@ export async function loadApp(
         "      nifra is zero-config but needs one of them exporting at least:\n" +
         "        export const adapter = reactAdapter            // from @nifrajs/web-react\n" +
         '        export const clientModule = "@nifrajs/web-react/client"\n' +
-        "      (create-nifra scaffolds this for you.)",
+        "      (create-nifra scaffolds this for you.)" +
+        (existsSync(resolve(cwd, BACKEND_APP_FILE))
+          ? `\n      With ${BACKEND_APP_FILE} and no web config this is an API-only app: \`nifra routes\`,\n` +
+            "      `nifra context`, `nifra openapi` and `nifra mcp` read its backend; pages need the config."
+          : ""),
     )
   }
   if (!existsSync(resolve(cwd, "routes"))) {
@@ -311,7 +397,11 @@ export async function loadApp(
       `[nifra] no routes/ directory in ${cwd} - nifra apps are file-routed under routes/.`,
     )
   }
-  const fw = (await importWithQuery(configPath, options.importQuery)) as Partial<NifraFramework>
+  const loaded = (await importWithQuery(configPath, options.importQuery)) as Partial<NifraFramework>
+  const fw =
+    configFile === CONFIG_FILE && existsSync(resolve(cwd, FRAMEWORK_FILE))
+      ? await withServerOptions(loaded, resolve(cwd, FRAMEWORK_FILE), options.importQuery)
+      : loaded
   if (!isAdapter(fw.adapter) || typeof fw.clientModule !== "string") {
     throw new Error(
       `[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`,

package/src/mcp-context.ts

@@ -8,10 +8,11 @@
 import { realpathSync } from "node:fs"
 import { readFile } from "node:fs/promises"
 import { basename, isAbsolute, relative, resolve } from "node:path"
-import type { LoadedApp } from "./load.ts"
+import type { AppLoader } 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"
+import { writeTargetOf } from "./project-path.ts"
 
 function openApiFormat(args: Record<string, unknown>): "json" | "yaml" {
   const format = args.format
@@ -20,11 +21,11 @@ function openApiFormat(args: Record<string, unknown>): "json" | "yaml" {
 
 export async function openApiHandler(
   args: Record<string, unknown>,
-  loadAppCached: (outDirName?: string) => Promise<LoadedApp>,
+  loadAppCached: AppLoader,
 ): Promise<string> {
   const { renderOpenApiWithTypes } = await import("./openapi-tool.ts")
   const pathPrefix = typeof args.path === "string" ? args.path : undefined
-  return renderOpenApiWithTypes(await loadAppCached(), openApiFormat(args), pathPrefix)
+  return renderOpenApiWithTypes(await loadAppCached.backend(), openApiFormat(args), pathPrefix)
 }
 
 async function readProjectFile(
@@ -57,7 +58,7 @@ function promptText(
 
 export function projectResources(
   cwd: string,
-  loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
+  loadAppCached: AppLoader = createCachedAppLoader(cwd),
 ): McpResource[] {
   return [
     {
@@ -68,7 +69,7 @@ export function projectResources(
       mimeType: "application/json",
       read: async () => {
         const { routesToJson } = await import("./introspect.ts")
-        return { text: JSON.stringify(routesToJson(await loadAppCached()), null, 2) }
+        return { text: JSON.stringify(routesToJson(await loadAppCached.backend()), null, 2) }
       },
     },
     {
@@ -165,7 +166,7 @@ export function projectPrompts(): McpPrompt[] {
 
 export function projectFeatures(
   cwd: string,
-  loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
+  loadAppCached: AppLoader = createCachedAppLoader(cwd),
 ): McpServerFeatures {
   return { resources: projectResources(cwd, loadAppCached), prompts: projectPrompts() }
 }
@@ -186,24 +187,10 @@ export function resolveProjectDir(root: string, dir: string | undefined): string
     const lexical = relative(root, target)
     return lexical === "" || (!lexical.startsWith("..") && !isAbsolute(lexical)) ? target : null
   }
-  let probe = target
-  const missing: string[] = []
-  while (true) {
-    try {
-      const canonicalProbe = realpathSync(probe)
-      const rel = relative(canonicalRoot, canonicalProbe)
-      if (rel.startsWith("..") || isAbsolute(rel)) return null
-      return missing.length === 0 ? canonicalProbe : resolve(canonicalProbe, ...missing.reverse())
-    } catch {
-      const parent = resolve(probe, "..")
-      if (parent === probe) return null
-      // `basename`, not a slice past `parent`: when `parent` is the filesystem root its trailing
-      // separator is part of it, so `parent.length + 1` eats the first character of the segment and
-      // the path gets rebuilt wrong.
-      missing.push(basename(probe))
-      probe = parent
-    }
-  }
+  const canonical = writeTargetOf(target)
+  if (canonical === undefined) return null
+  const rel = relative(canonicalRoot, canonical)
+  return rel.startsWith("..") || isAbsolute(rel) ? null : canonical
 }
 
 /** Consistent error string for a `dir` that escapes the project root. */
@@ -218,7 +205,7 @@ export function dirError(dir: string | undefined): string {
 /** Build the project-scoped tools for `cwd`. */
 export interface CommandMcpToolOptions {
   readonly cwd: string
-  readonly loadAppCached?: () => Promise<LoadedApp>
+  readonly loadAppCached?: AppLoader
 }
 
 /** Adapt one executable catalog spec to its MCP descriptor and project-scoped handler. */

package/src/mcp-delegate.ts

@@ -6,7 +6,7 @@
  * answer still reads as authoritative. So the server settles the version before it serves:
  *
  *   1. The project installs its own `@nifrajs/cli` at a different version: hand the whole session to
- *      that CLI (`node_modules/.bin/nifra mcp`, stdio inherited) and step aside.
+ *      that CLI (its `bin` script, run by this Bun with `--no-env-file`, stdio inherited) and step aside.
  *   2. Handing off is impossible (no project CLI, a missing bin, or this process IS the hand-off and
  *      the versions still disagree): serve, but the version-sensitive tools refuse with the fix
  *      instead of answering for the wrong release.
@@ -31,27 +31,37 @@ export const VERSION_SENSITIVE_TOOLS: ReadonlySet<string> = new Set([
   "nifra_contracts",
 ])
 
-/** The project's own CLI: its version and, when the install linked one, its bin. */
+/** The project's own CLI: its version and, when it is on disk, the script its `bin` names. */
 export interface ProjectCli {
   readonly version: string
   readonly bin?: string
 }
 
-const BIN_NAME = process.platform === "win32" ? "nifra.exe" : "nifra"
 const MAX_ANCESTOR_DIRS = 8
 
+function binScript(bin: unknown): string | undefined {
+  if (typeof bin === "string") return bin
+  if (typeof bin !== "object" || bin === null) return undefined
+  const named: unknown = Reflect.get(bin, "nifra")
+  return typeof named === "string" ? named : undefined
+}
+
 /** The nearest `@nifrajs/cli` install at or above `root` (a monorepo app hoists to the repo root). */
 export async function findProjectCli(root: string): Promise<ProjectCli | undefined> {
   let dir = root
   for (let depth = 0; depth < MAX_ANCESTOR_DIRS; depth++) {
-    const modules = join(dir, "node_modules")
+    const pkg = join(dir, "node_modules", "@nifrajs", "cli")
     try {
-      const meta = JSON.parse(
-        await readFile(join(modules, "@nifrajs", "cli", "package.json"), "utf8"),
-      ) as { version?: unknown }
+      const meta = JSON.parse(await readFile(join(pkg, "package.json"), "utf8")) as {
+        version?: unknown
+        bin?: unknown
+      }
       if (typeof meta.version === "string" && meta.version.length > 0) {
-        const bin = join(modules, ".bin", BIN_NAME)
-        return existsSync(bin) ? { version: meta.version, bin } : { version: meta.version }
+        const script = binScript(meta.bin)
+        const bin = script === undefined ? undefined : join(pkg, script)
+        return bin !== undefined && existsSync(bin)
+          ? { version: meta.version, bin }
+          : { version: meta.version }
       }
     } catch {
       // Not installed at this level - keep walking up.
@@ -79,7 +89,9 @@ export async function delegateToProjectCli(options: {
   const cli = await findProjectCli(options.root)
   if (cli === undefined || cli.version === options.version || cli.bin === undefined)
     return undefined
-  return handOffSession([cli.bin, "mcp", ...options.args], {
+  // Not the `.bin` shim: its `bun` would load the project's `.env`, and the inherited
+  // NIFRA_MCP_WITHOUT_ENV_FILES then tells that CLI the values are already gone.
+  return handOffSession([process.execPath, "--no-env-file", cli.bin, "mcp", ...options.args], {
     cwd: options.cwd,
     env: { ...process.env, [MCP_DELEGATED_ENV]: "1" },
     announce: `[nifra] mcp: this CLI is ${options.version}; the project installs @nifrajs/cli ${cli.version} - serving this session from ${cli.bin}`,

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,11 @@ import {
   CHILD_INPUT_MAX_BYTES,
   CHILD_OUTPUT_MAX_BYTES,
   CHILD_TIMEOUT_MS,
+  type EscalatingStop,
+  escalatingStop,
+  OWN_PROCESS_GROUP,
   readBoundedStream,
+  signalProcessGroup,
   timeoutMessage,
   validateLocalPort,
 } from "./mcp-io.ts"
@@ -46,20 +50,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 +87,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 +165,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 +178,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 +714,14 @@ export async function spawnChild(
     stdin: "pipe",
     stdout: "pipe",
     stderr: "pipe",
+    detached: OWN_PROCESS_GROUP,
   })
+  const stopper = escalatingStop((name) => signalProcessGroup(proc, name))
   let killed = false
   const kill = (): void => {
     if (killed) return
     killed = true
-    proc.kill()
+    stopper.stop()
   }
   const abort = (): void => kill()
   signal?.addEventListener("abort", abort, { once: true })
@@ -738,6 +762,7 @@ export async function spawnChild(
     return text || `${label} failed:\n${err.text.trim() || "(no output)"}`
   } finally {
     clearTimeout(timer)
+    stopper.dispose()
     signal?.removeEventListener("abort", abort)
   }
 }
@@ -791,6 +816,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
@@ -807,6 +842,7 @@ export class WarmWorker {
       readonly cleanup: () => void
     }
   >()
+  private readonly stopper: EscalatingStop
   private stdoutBuffer = ""
   private stdoutBufferBytes = 0
   private stderrBuffer = ""
@@ -827,10 +863,14 @@ export class WarmWorker {
       stdout: "pipe",
       stderr: "pipe",
     }) as PipeSubprocess
+    this.stopper = escalatingStop((name) => this.proc.kill(name))
+    liveWarmWorkers.add(this)
     void this.readStdout()
     void this.readStderr()
     void this.proc.exited.then((code) => {
       this.closed = true
+      this.stopper.dispose()
+      liveWarmWorkers.delete(this)
       const err = new Error(
         `warm ${this.label} worker exited (${code})${this.stderrBuffer ? `:\n${this.stderrBuffer}` : ""}`,
       )
@@ -843,7 +883,7 @@ export class WarmWorker {
   }
 
   stop(): void {
-    if (!this.closed) this.proc.kill()
+    if (!this.closed) this.stopper.stop()
   }
 
   async request(input: unknown, signal?: AbortSignal): Promise<string> {
@@ -1025,8 +1065,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 +1086,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 +1189,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 +1205,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 +1220,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.2"
+const VERSION = "5.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 =>