@nifrajs/cli 2.1.0 → 2.3.0

package/src/mcp-http.ts

@@ -1,13 +1,13 @@
 /**
- * The PUBLIC nifra docs MCP — Streamable-HTTP transport exposing the project-INDEPENDENT tools
+ * The PUBLIC nifra docs MCP - Streamable-HTTP transport exposing the project-INDEPENDENT tools
  * (`nifra_docs` + `nifra_example`) so any remote AI agent can learn nifra without a local checkout.
  * Both tools read the bundled corpus (llms-full.txt / examples.json shipped in this package) and ignore
- * `cwd`, so they reuse the exact definitions from {@link projectTools} — one source, no drift.
+ * `cwd`, so they reuse the exact definitions from {@link projectTools} - one source, no drift.
  *
  * The transport itself (body cap, CORS, JSON-RPC dispatch) lives in `@nifrajs/mcp/http`; this module is
  * the docs-specific layer over it: it supplies the bundled corpus tools and the `nifra-docs` server info.
- * {@link handleMcpHttp} self-hosts ANYWHERE Bun runs — the simplest path is `nifra docs-mcp` on a VPS; the
- * same handler runs on Cloudflare/Vercel edge (there inline the corpus as string imports — a Worker has no
+ * {@link handleMcpHttp} self-hosts ANYWHERE Bun runs - the simplest path is `nifra docs-mcp` on a VPS; the
+ * same handler runs on Cloudflare/Vercel edge (there inline the corpus as string imports - a Worker has no
  * filesystem). `export default { port, fetch }` also lets `bun run mcp-http.ts` serve it directly.
  */
 
@@ -26,10 +26,10 @@ 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 = "2.1.0"
+const VERSION = "2.3.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 const DOCS_HEALTH =
-  "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."
+  "nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."
 
 /** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */
 export function publicDocsTools(): McpTool[] {
@@ -57,7 +57,7 @@ export function handleMcpHttp(request: Request): Promise<Response> {
 /**
  * Worker/edge + local entry. `export default { fetch }` is the universal server shape: Cloudflare /
  * Vercel edge / Deno deploy use `fetch` (and ignore `port`); `bun run mcp-http.ts` auto-serves it on
- * `port` (PORT env, default 8787) — Bun serves a module's default-exported server, so NO manual
+ * `port` (PORT env, default 8787) - Bun serves a module's default-exported server, so NO manual
  * `Bun.serve` here (that would double-bind the port).
  */
 export default {

package/src/mcp-protocol.ts

@@ -1,7 +1,7 @@
 /**
  * The MCP JSON-RPC dispatch now lives in `@nifrajs/mcp` (shared with nifra apps that expose their own
- * MCP server / MCP Apps widgets). This module is a thin re-export so the CLI's existing imports — and
- * the `@nifrajs/cli/mcp` self-host surface — keep resolving here unchanged.
+ * MCP server / MCP Apps widgets). This module is a thin re-export so the CLI's existing imports - and
+ * the `@nifrajs/cli/mcp` self-host surface - keep resolving here unchanged.
  */
 
 export * from "@nifrajs/mcp/protocol"

package/src/mcp-render.ts

@@ -1,12 +1,12 @@
 /**
- * The `nifra_render` engine + its child-process entry — the page half of `nifra_run`. Where `nifra_run`
+ * The `nifra_render` engine + its child-process entry - the page half of `nifra_run`. Where `nifra_run`
  * runs requests through the BACKEND, this SSRs page routes through the WEB app (`createWebApp`), so an
  * agent can verify a page renders and its loader ran after an edit. Spawned fresh per call (`bun
  * mcp-render.ts <cwd>`) so the project's CURRENT route/loader code is loaded.
  *
- * No build required: a placeholder `clientEntry` is injected (the SSR HTML renders regardless — the
+ * No build required: a placeholder `clientEntry` is injected (the SSR HTML renders regardless - the
  * client bundle only matters for hydration in the browser, not for "did this page render server-side").
- * {@link renderPages} never throws — every failure (no config, a loader error, a render throw) becomes
+ * {@link renderPages} never throws - every failure (no config, a loader error, a render throw) becomes
  * `{ error }` so the agent gets the actionable message.
  */
 
@@ -19,7 +19,7 @@ import { loadApp, resolvePlugins } from "./load.ts"
 const errString = (err: unknown): string =>
   err instanceof Error ? `${err.name}: ${err.message}` : String(err)
 
-/** Load the project, register its SSR plugins, and build the SSR `createWebApp` once — the cost the warm
+/** Load the project, register its SSR plugins, and build the SSR `createWebApp` once - the cost the warm
  * worker amortizes across calls. Never throws (every failure → `{ error }`). Factored out of
  * {@link renderPages} so the cold path (fresh process per call) and the warm worker share one builder. */
 async function buildWebApp(cwd: string): Promise<{ app: AppLike } | { error: string }> {
@@ -92,7 +92,7 @@ function redirectConsoleToStderr(): void {
 /**
  * Warm-worker loop (`--worker`): build the web app ONCE, then SSR each `{ id, input: { requests } }` line
  * against that hot app and reply `{ id, output }`. The parent (`mcp.ts`'s warm-render handler) spawns this,
- * fingerprints the source tree, and restarts the worker when a file changes — so warm reuse never serves a
+ * fingerprints the source tree, and restarts the worker when a file changes - so warm reuse never serves a
  * stale render. Mirrors `mcp-run.ts`'s worker (single backend entry → no per-call entry key needed here).
  */
 async function runWorker(cwd: string): Promise<void> {
@@ -148,7 +148,7 @@ if (import.meta.main) {
   // The parent (mcp.ts) spawns `bun mcp-render.ts <cwd>` WITHOUT setting the subprocess `cwd` option, so
   // this process inherits the MCP server's working dir, not the app's. SSR resolves `react-dom/server`
   // from `process.cwd()` to share ONE React core with the app's route components (the dual-React fix in
-  // @nifrajs/web-react) — so we must chdir to the app root before any render. Best-effort: a bad path
+  // @nifrajs/web-react) - so we must chdir to the app root before any render. Best-effort: a bad path
   // surfaces later as a load error rather than crashing the child here.
   if (cwd !== process.cwd()) {
     try {
@@ -169,5 +169,13 @@ if (import.meta.main) {
   } catch {
     output = { error: "invalid input: expected JSON { requests: [...] }" }
   }
-  process.stdout.write(JSON.stringify(output, null, 2))
+  await Bun.write(Bun.stdout, JSON.stringify(output, null, 2))
+  // Exit explicitly, exactly as the `--worker` branch above already does.
+  //
+  // Loading the app runs its module side effects, and a real app opens things: a database pool, a
+  // Redis client, a metrics interval. Any one of those keeps the event loop alive, so falling off
+  // the end of this module never terminates the process - and the parent is sitting in
+  // `await proc.exited`. The render itself finished; there is nothing left to wait for, and this
+  // process is single-use. `Bun.write` above is awaited so the output is flushed before we exit.
+  process.exit(0)
 }

package/src/mcp-run.ts

@@ -1,6 +1,6 @@
 /**
  * The `nifra_run` engine + its child-process entry. The MCP server spawns this file fresh on every
- * `nifra_run` call (`bun mcp-run.ts <cwd>`) so the project's CURRENT backend code is loaded — picking
+ * `nifra_run` call (`bun mcp-run.ts <cwd>`) so the project's CURRENT backend code is loaded - picking
  * up the agent's latest edits. {@link runBackend} is the pure-ish core (resolve entry → import → run),
  * exported so it's unit-testable in-process; the entry below wires it to stdin/stdout.
  */
@@ -48,7 +48,7 @@ export async function loadBackend(
 
 /**
  * Resolve the backend entry under `cwd`, import it, and run `requests` through its exported app. Never
- * throws — every failure (missing/invalid entry, import/compile/runtime error) becomes `{ error }`, so
+ * throws - every failure (missing/invalid entry, import/compile/runtime error) becomes `{ error }`, so
  * the caller (and the agent) always gets actionable output. An import error here IS the failure the
  * agent needs to see and fix.
  */

package/src/mcp.ts

@@ -1,27 +1,27 @@
 /**
- * `nifra mcp` — a Model Context Protocol server (stdio) that lets a coding agent (Claude, Cursor, …)
+ * `nifra mcp` - a Model Context Protocol server (stdio) that lets a coding agent (Claude, Cursor, …)
  * act on a nifra project, not just read about it:
  *
- *   - `nifra_context` — this project's API routes + page routes + conventions (see {@link describeProject}).
- *   - `nifra_run`     — run HTTP requests through the project's backend and return structured results
+ *   - `nifra_context` - this project's API routes + page routes + conventions (see {@link describeProject}).
+ *   - `nifra_run`     - run HTTP requests through the project's backend and return structured results
  *     (status, body, errors). The write → run → see-the-failure → fix loop, powered by `@nifrajs/runner`.
  *     Each call runs the backend in a FRESH subprocess, so it reflects the agent's latest edits.
- *   - `nifra_render`  — SSR a page route through the project's web app; returns the rendered HTML (the
+ *   - `nifra_render`  - SSR a page route through the project's web app; returns the rendered HTML (the
  *     page half of `nifra_run`). Fresh subprocess per call; no build needed.
- *   - `nifra_ws`      — verify a WebSocket route with a real Bun WebSocket round-trip.
- *   - `nifra_docs`    — keyword-search the framework docs; returns only the matching sections.
- *   - `nifra_example` — a verified, copy-pasteable snippet for a task (typechecked against the live API,
+ *   - `nifra_ws`      - verify a WebSocket route with a real Bun WebSocket round-trip.
+ *   - `nifra_docs`    - keyword-search the framework docs; returns only the matching sections.
+ *   - `nifra_example` - a verified, copy-pasteable snippet for a task (typechecked against the live API,
  *     so it can't hallucinate a drifted nifra API).
- *   - `nifra_scaffold`— map a URL path to the correct `routes/` file + a contract-correct page stub.
- *   - `nifra_check`   — the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
- *   - `nifra_assure`  — route classification + enforcement-evidence gate.
+ *   - `nifra_scaffold`- map a URL path to the correct `routes/` file + a contract-correct page stub.
+ *   - `nifra_check`   - the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
+ *   - `nifra_assure`  - route classification + enforcement-evidence gate.
  *   - `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_doctor`  - package.json dependency drift detector, with safe local-version auto-fix.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
  * project root. 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
+ * 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).
  */
@@ -61,6 +61,26 @@ function childPath(name: "mcp-run" | "mcp-render" | "mcp-ws"): string {
 }
 
 /** Spawn `bun <child> <cwd>`, pipe `input` to its stdin, return its stdout (or a stderr-backed error). */
+/**
+ * How long a child gets before it is killed.
+ *
+ * A child loads the app, which runs its module side effects - a database pool, a Redis client, a
+ * metrics interval. Any of those keeps the child's event loop alive after the work is done, and the
+ * parent is sitting in `await proc.exited`. The children now exit explicitly, so this is the backstop
+ * rather than the fix: without it a single wedged child blocks an agent indefinitely, and the caller
+ * has no way to tell "still working" from "never returning".
+ *
+ * Generous enough for a cold start that compiles route modules, short enough that a hang is reported
+ * within one attention span rather than after minutes of polling.
+ */
+const CHILD_TIMEOUT_MS = 30_000
+
+const timeoutMessage = (label: string, ms: number): string =>
+  `${label} timed out after ${ms / 1000}s and was terminated.\n` +
+  `The app was loaded but the process did not finish. Most often this is a module-level side effect ` +
+  `that keeps the event loop alive (a database pool, a Redis client, an interval) opened during import ` +
+  `rather than lazily. Check for top-level connections in the app entry or anything it imports.`
+
 async function spawnChild(
   child: "mcp-run" | "mcp-render" | "mcp-ws",
   cwd: string,
@@ -76,6 +96,11 @@ async function spawnChild(
   })
   const abort = (): void => proc.kill()
   signal?.addEventListener("abort", abort, { once: true })
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    proc.kill()
+  }, CHILD_TIMEOUT_MS)
   try {
     proc.stdin.write(JSON.stringify(input))
     await proc.stdin.end()
@@ -88,8 +113,13 @@ async function spawnChild(
       const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : ""
       return `${label} cancelled${reason}.`
     }
-    return out.trim() || `${label} failed:\n${err.trim() || "(no output)"}`
+    // A killed child may still have flushed a complete result before the timer fired; prefer real
+    // output over the timeout message so a slow-but-successful render is not reported as a failure.
+    const text = out.trim()
+    if (timedOut && text === "") return timeoutMessage(label, CHILD_TIMEOUT_MS)
+    return text || `${label} failed:\n${err.trim() || "(no output)"}`
   } finally {
+    clearTimeout(timer)
     signal?.removeEventListener("abort", abort)
   }
 }
@@ -129,7 +159,7 @@ type PipeSubprocess = ReturnType<typeof Bun.spawn> & {
 
 /** 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
+ * powers both `nifra_run warm` and `nifra_render warm` - `child` selects which engine, `label` shapes the
  * cancellation message. The owning handler ({@link createWarmHandler}) fingerprints the source tree and
  * replaces the worker when a file changes, so warm reuse never serves a stale result. Exported for the
  * concurrency test that proves a single per-request cancel doesn't tear down the shared worker. */
@@ -187,12 +217,25 @@ export class WarmWorker {
         // Per-request cancel: drop just THIS id and resolve its cancellation. The worker is shared
         // across concurrent requests (`pending` is id-keyed for exactly this reason), so killing the
         // process here would reject every OTHER in-flight request via the `exited` handler and force a
-        // cold rebuild. Leave it hot — `createWarmHandler` already replaces it on file change.
+        // 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}` : ""
         resolve(`${this.label} cancelled${reason}.`)
       }
-      const cleanup = (): void => signal?.removeEventListener("abort", abort)
+      // Same backstop as the cold path: a worker wedged mid-request would otherwise leave this
+      // promise unsettled forever. Drop the id and replace the worker - unlike a per-request cancel,
+      // a timeout means the worker itself is suspect, so the next call should start from a fresh one.
+      const timer = setTimeout(() => {
+        if (!this.pending.delete(id)) return
+        signal?.removeEventListener("abort", abort)
+        this.stop()
+        resolve(timeoutMessage(this.label, CHILD_TIMEOUT_MS))
+      }, CHILD_TIMEOUT_MS)
+      const cleanup = (): void => {
+        clearTimeout(timer)
+        signal?.removeEventListener("abort", abort)
+      }
       signal?.addEventListener("abort", abort, { once: true })
       this.pending.set(id, { resolve, reject, cleanup })
       try {
@@ -254,7 +297,7 @@ export class WarmWorker {
 
 /** 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
+ * `nifra_render` (`child: "mcp-render"`, `label: "render"`) - the only differences are the engine and the
  * message label, so there's a single source for the reuse + auto-restart-on-file-change logic. */
 function createWarmHandler(
   child: "mcp-run" | "mcp-render",
@@ -573,7 +616,7 @@ export function projectFeatures(
 }
 
 /**
- * Resolve an optional `dir` tool argument — a subdirectory of the project root the caller wants to scope a
+ * Resolve an optional `dir` tool argument - a subdirectory of the project root the caller wants to scope a
  * check/test to (e.g. `nifra check` on `app/` when the MCP server's root is a monorepo). Returns the
  * absolute target, or `null` if `dir` escapes the root (a path-traversal guard: no `..` out, no absolute
  * path elsewhere). `undefined`/empty → the root itself.
@@ -587,7 +630,7 @@ export function resolveProjectDir(root: string, dir: string | undefined): string
 /** Consistent error string for a `dir` that escapes the project root. */
 function dirError(dir: string | undefined): string {
   return JSON.stringify(
-    { ok: false, error: `dir must be a subdirectory of the project root — "${dir}" escapes it.` },
+    { ok: false, error: `dir must be a subdirectory of the project root - "${dir}" escapes it.` },
     null,
     2,
   )
@@ -604,7 +647,7 @@ export function projectTools(
     {
       name: "nifra_context",
       description:
-        "Get this nifra project's surface. Call it once UNFILTERED for a tight INDEX: the route list (API routes as `METHOD path`, page routes as `pattern → file`) + framework conventions + a pointer — cheap even on a big app, no per-route schema dump. Then pass `path` (a route prefix like /api/orders) and/or `kind` (api|pages) to fetch the FULL contract for that slice (body/query/response TS shapes + the exact typed-client call form).",
+        "Get this nifra project's surface. Call it once UNFILTERED for a tight INDEX: the route list (API routes as `METHOD path`, page routes as `pattern → file`) + framework conventions + a pointer - cheap even on a big app, no per-route schema dump. Then pass `path` (a route prefix like /api/orders) and/or `kind` (api|pages) to fetch the FULL contract for that slice (body/query/response TS shapes + the exact typed-client call form).",
       inputSchema: {
         type: "object",
         properties: {
@@ -628,7 +671,7 @@ export function projectTools(
     {
       name: "nifra_routes",
       description:
-        "List this project's API routes as STRUCTURED JSON — each `{ method, path, call, body?, query?, response? }`, where `call` is the exact typed-client call form and the shapes are compact TS-typed contracts. For programmatic use (list_routes / get_route_schema) instead of parsing the nifra_context Markdown. No args = every route; pass `path` (a path or prefix like /api/orders) to narrow to those routes.",
+        "List this project's API routes as STRUCTURED JSON - each `{ method, path, call, body?, query?, response? }`, where `call` is the exact typed-client call form and the shapes are compact TS-typed contracts. For programmatic use (list_routes / get_route_schema) instead of parsing the nifra_context Markdown. No args = every route; pass `path` (a path or prefix like /api/orders) to narrow to those routes.",
       inputSchema: {
         type: "object",
         properties: {
@@ -808,7 +851,7 @@ export function projectTools(
     {
       name: "nifra_scaffold",
       description:
-        'Map a URL path to the CORRECT routes/ file and get a contract-correct page stub. Agents routinely place file routes wrong — this applies the convention for you: ":id"/"[id]" → [id], "*rest" → [...rest], "/" → index. Pass path (e.g. "/users/:id"). Returns the file to create + the route-module contract (loader/action/meta/default) + a stub (ready-to-write for react/preact/solid; path+contract for vue/svelte/vanilla — use nifra_example for those bodies).',
+        'Map a URL path to the CORRECT routes/ file and get a contract-correct page stub. Agents routinely place file routes wrong - this applies the convention for you: ":id"/"[id]" → [id], "*rest" → [...rest], "/" → index. Pass path (e.g. "/users/:id"). Returns the file to create + the route-module contract (loader/action/meta/default) + a stub (ready-to-write for react/preact/solid; path+contract for vue/svelte/vanilla - use nifra_example for those bodies).',
       inputSchema: {
         type: "object",
         properties: {
@@ -844,7 +887,7 @@ export function projectTools(
     {
       name: "nifra_check",
       description:
-        'Run the project\'s drift gate and return a structured result { ok, typecheck, diagnostics[] }: typecheck (the frontend↔backend contract), plus lints for hand-rolled fetch() to your own API, untyped client("…") calls missing <typeof app>, and server-only imports in routes/. Pass lintsOnly:true for a near-instant lint pass while iterating; run the full gate (default) to confirm the work is done — fix every diagnostic before finishing.',
+        'Run the project\'s drift gate and return a structured result { ok, typecheck, diagnostics[] }: typecheck (the frontend↔backend contract), plus lints for hand-rolled fetch() to your own API, untyped client("…") calls missing <typeof app>, and server-only imports in routes/. Pass lintsOnly:true for a near-instant lint pass while iterating; run the full gate (default) to confirm the work is done - fix every diagnostic before finishing.',
       inputSchema: {
         type: "object",
         properties: {
@@ -1043,7 +1086,7 @@ export function projectTools(
     {
       name: "nifra_doctor",
       description:
-        "Check this project for packages imported in source but NOT declared in package.json — the Bun-workspace trap where an import resolves at runtime (hoisting/workspace) so tests pass and `bun install` says no changes, yet tsc fails and a fresh/standalone install can't resolve it. Returns { ok, ran, findings[], fixed?, skippedFixes? }. Pass autoFix:true to update package.json only when the dependency version can be inferred locally from an ancestor package.json or installed package metadata; otherwise the tool returns the exact bun add command to run.",
+        "Check this project for packages imported in source but NOT declared in package.json - the Bun-workspace trap where an import resolves at runtime (hoisting/workspace) so tests pass and `bun install` says no changes, yet tsc fails and a fresh/standalone install can't resolve it. Returns { ok, ran, findings[], fixed?, skippedFixes? }. Pass autoFix:true to update package.json only when the dependency version can be inferred locally from an ancestor package.json or installed package metadata; otherwise the tool returns the exact bun add command to run.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1216,6 +1259,54 @@ function namespaceForApp(
   }
 }
 
+/**
+ * Merge the backend-derived resources/prompts into `base` - and keep a project that cannot be loaded
+ * from deciding whether the server starts at all.
+ *
+ * Resources and prompts are OPTIONAL capabilities extracted from the app's backend, so this load is a
+ * best-effort enrichment. It was awaited unguarded, which made it a hard boot requirement: `loadApp`
+ * needs a web config (`adapter` + `clientModule`) and a `routes/` directory, and a backend-only
+ * project - the shape `create-nifra`'s DEFAULT template produces - has neither. On those projects the
+ * throw escaped before the JSON-RPC loop began, so the server wrote nothing and exited. `nifra
+ * init-agents` would happily register an `.mcp.json` pointing at a server that could never start, and
+ * every tool went with it, including the twelve that never touch the app (docs, examples, types,
+ * check, doctor, levels, test).
+ *
+ * Degrading costs only the backend resources/prompts. Tools that genuinely need the app still fail,
+ * but per call, with their own message - which is a diagnosis instead of a silence.
+ */
+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 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.
+ */
+async function appDeclaredTools(loader: () => Promise<LoadedApp>): Promise<McpTool[]> {
+  try {
+    return extractBackendTools((await loader()).backend)
+  } catch {
+    return []
+  }
+}
+
 /** Run the stdio MCP server: read newline-delimited JSON-RPC from stdin, write responses to stdout. */
 export async function runMcpServer(cwd: string, version: string): Promise<void> {
   let features: McpServerFeatures
@@ -1227,24 +1318,18 @@ export async function runMcpServer(cwd: string, version: string): Promise<void>
     const allPrompts: McpPrompt[] = []
     for (const { name, cwd: appCwd } of appEntries) {
       const loader = createCachedAppLoader(appCwd)
-      const app = await loader()
-      const base = projectFeatures(appCwd, loader)
-      const ns = namespaceForApp(name, [], {
-        resources: [...(base.resources ?? []), ...extractBackendResources(app.backend)],
-        prompts: [...(base.prompts ?? []), ...extractBackendPrompts(app.backend)],
-      })
+      const ns = namespaceForApp(
+        name,
+        [],
+        await backendFeatures(loader, projectFeatures(appCwd, loader)),
+      )
       allResources.push(...(ns.features.resources ?? []))
       allPrompts.push(...(ns.features.prompts ?? []))
     }
     features = { resources: allResources, prompts: allPrompts }
   } else {
     const loadAppCached = createCachedAppLoader(cwd)
-    const base = projectFeatures(cwd, loadAppCached)
-    const app = await loadAppCached()
-    features = {
-      resources: [...(base.resources ?? []), ...extractBackendResources(app.backend)],
-      prompts: [...(base.prompts ?? []), ...extractBackendPrompts(app.backend)],
-    }
+    features = await backendFeatures(loadAppCached, projectFeatures(cwd, loadAppCached))
   }
   const loadAppCached = createCachedAppLoader(cwd)
   const serverInfo = { name: "nifra", version }
@@ -1259,21 +1344,16 @@ export async function runMcpServer(cwd: string, version: string): Promise<void>
       const allTools: McpTool[] = []
       for (const { name, cwd: appCwd } of appEntries) {
         const loader = createCachedAppLoader(appCwd)
-        const app = await loader()
-        const baseTools = projectTools(appCwd, loader)
-        const backendTools = extractBackendTools(app.backend)
-        const ns = namespaceForApp(name, [...baseTools, ...backendTools], {
-          resources: [],
-          prompts: [],
-        })
+        const tools = [...projectTools(appCwd, loader), ...(await appDeclaredTools(loader))]
+        const ns = namespaceForApp(name, tools, { resources: [], prompts: [] })
         allTools.push(...ns.tools)
       }
       activeTools = [...docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus), ...allTools]
     } else {
-      const app = await loadAppCached()
-      const baseTools = projectTools(cwd, loadAppCached)
-      const backendTools = extractBackendTools(app.backend)
-      activeTools = [...baseTools, ...backendTools]
+      activeTools = [
+        ...projectTools(cwd, loadAppCached),
+        ...(await appDeclaredTools(loadAppCached)),
+      ]
     }
 
     const response = await handleRpc(message, activeTools, serverInfo, features, {

package/src/openapi-tool.ts

@@ -45,7 +45,7 @@ function toYaml(value: unknown, depth = 0): string {
  * Render a project's backend as OpenAPI 3.1. Frontend-only apps get a valid empty document, which is
  * easier for agents and API tooling to handle than a tool error.
  *
- * `pathPrefix` narrows the document to operations whose (OpenAPI-templated) path starts with the prefix —
+ * `pathPrefix` narrows the document to operations whose (OpenAPI-templated) path starts with the prefix -
  * mirroring `nifra_routes`'s `path` filter so a large backend needn't return the whole document. The keys
  * are templated (`/users/{id}`), so a prefix up to the first param (`/api/orders`) matches `/api/orders`
  * and `/api/orders/{id}` alike. `components.schemas` is left intact: it's keyed by schema name (not path),
@@ -57,7 +57,7 @@ export function renderOpenApi(app: LoadedApp, format: OpenApiFormat, pathPrefix?
   const input = hasRoutesMethod(app.backend) ? app.backend : {}
   const generated = toOpenAPI(input, { title, version: "1.0.0" })
   // Narrow to operations under the prefix, rebuilding the doc (its `paths` is readonly). `components`
-  // stays — see the doc comment for why the schema set isn't recomputed.
+  // stays - see the doc comment for why the schema set isn't recomputed.
   const document =
     pathPrefix !== undefined && pathPrefix !== ""
       ? {

package/src/pipeline-guard.ts

@@ -0,0 +1,186 @@
+/**
+ * Pipeline separation guard - one bundler owns a phase, never two.
+ *
+ * nifra supports both Vite and Bun, and the config keeps them in separate slots: `vitePlugins` for
+ * the Vite pipeline, `clientPlugins`/`serverPlugins` for the Bun one. Nothing enforces the split, so
+ * a plugin lands in the wrong slot and is silently ignored - a Vite plugin in `clientPlugins` is
+ * handed to `Bun.build`, which has no `transform` hook to call, so the transform simply never runs
+ * and the build succeeds.
+ *
+ * That failure mode is the whole reason for this file. nifra's expensive bugs are not caused by Vite
+ * or by Bun; they are caused by two toolchains disagreeing about one module. Dual-React is that, the
+ * dedupe plugins are patches for that, and a `resolve.alias` that never reaches SSR is that. Mixing
+ * is the defect - choice is not - so the separation has to be checked rather than documented.
+ *
+ * Detection is by hook shape, which is what each bundler actually dispatches on:
+ *   - a Bun plugin has `setup(build)`
+ *   - a Rollup/Vite plugin has `resolveId` / `load` / `transform` / `config` / `configResolved` /
+ *     `transformIndexHtml` and no `setup`
+ *
+ * Deliberately conservative: a plugin that matches neither shape is left alone rather than guessed
+ * at. A guard that fires on correct config is a guard people turn off.
+ */
+
+/** Which pipeline a slot belongs to. */
+export type PipelineSlot = "vitePlugins" | "clientPlugins" | "serverPlugins"
+
+export interface PipelineMismatch {
+  readonly slot: PipelineSlot
+  /** The plugin's `name`, or a positional label when it has none. */
+  readonly plugin: string
+  /** The pipeline the slot feeds. */
+  readonly expected: "vite" | "bun"
+  /** The pipeline the plugin's hooks say it belongs to. */
+  readonly actual: "vite" | "bun"
+  readonly fix: string
+}
+
+const ROLLUP_HOOKS = [
+  "resolveId",
+  "load",
+  "transform",
+  "config",
+  "configResolved",
+  "configureServer",
+  "transformIndexHtml",
+  "generateBundle",
+  "renderChunk",
+] as const
+
+/** Classify a plugin by the hooks it exposes, or `undefined` when its shape says nothing. */
+function classify(plugin: unknown): "vite" | "bun" | undefined {
+  if (typeof plugin !== "object" || plugin === null) return undefined
+  const record = plugin as Record<string, unknown>
+  // `setup` is Bun's only entry point, so its presence is decisive even alongside other keys.
+  if (typeof record.setup === "function") return "bun"
+  if (ROLLUP_HOOKS.some((hook) => typeof record[hook] === "function")) return "vite"
+  return undefined
+}
+
+const SLOT_PIPELINE: Readonly<Record<PipelineSlot, "vite" | "bun">> = {
+  vitePlugins: "vite",
+  clientPlugins: "bun",
+  serverPlugins: "bun",
+}
+
+const MOVE_TO: Readonly<Record<"vite" | "bun", string>> = {
+  vite: "`vitePlugins`",
+  bun: "`clientPlugins` (client bundle) or `serverPlugins` (SSR)",
+}
+
+/**
+ * Check one slot's resolved plugin list. Pure: takes the already-resolved array so a thunk-valued
+ * field is awaited by the caller, and so this stays testable without loading a project.
+ */
+export function checkPipelineSlot(
+  slot: PipelineSlot,
+  plugins: readonly unknown[],
+): PipelineMismatch[] {
+  const expected = SLOT_PIPELINE[slot]
+  const out: PipelineMismatch[] = []
+  for (let i = 0; i < plugins.length; i++) {
+    const plugin = plugins[i]
+    const actual = classify(plugin)
+    if (actual === undefined || actual === expected) continue
+    const named = (plugin as { name?: unknown }).name
+    const label = typeof named === "string" && named !== "" ? named : `${slot}[${i}]`
+    out.push({
+      slot,
+      plugin: label,
+      expected,
+      actual,
+      fix:
+        actual === "vite"
+          ? `"${label}" is a Vite/Rollup plugin (it defines Rollup hooks, not \`setup\`) but sits in \`${slot}\`, which feeds Bun.build. Bun never calls those hooks, so the transform silently does not run. Move it to ${MOVE_TO.vite}.`
+          : `"${label}" is a Bun plugin (it defines \`setup\`) but sits in \`${slot}\`, which feeds Vite. Vite never calls \`setup\`, so the transform silently does not run. Move it to ${MOVE_TO.bun}.`,
+    })
+  }
+  return out
+}
+
+/** Check every slot of a resolved framework config. */
+export function checkPipelineSeparation(slots: {
+  readonly vitePlugins?: readonly unknown[]
+  readonly clientPlugins?: readonly unknown[]
+  readonly serverPlugins?: readonly unknown[]
+}): PipelineMismatch[] {
+  return [
+    ...checkPipelineSlot("vitePlugins", slots.vitePlugins ?? []),
+    ...checkPipelineSlot("clientPlugins", slots.clientPlugins ?? []),
+    ...checkPipelineSlot("serverPlugins", slots.serverPlugins ?? []),
+  ]
+}
+
+/** Which bundler a build runs on. */
+export type BuildPipeline = "bun" | "vite"
+
+export interface PipelineDecision {
+  readonly pipeline: BuildPipeline
+  /**
+   * Why this pipeline, for the `nifra build` log line - so an auto-selected Vite build never looks
+   * like the user got the default. `undefined` when the choice was the plain default or was forced.
+   */
+  readonly reason?: string
+}
+
+/** The plugin slots a decision reads, already resolved. */
+export interface PipelineSlots {
+  readonly vitePlugins?: readonly unknown[]
+  readonly clientPlugins?: readonly unknown[]
+  readonly serverPlugins?: readonly unknown[]
+}
+
+const pluginNames = (plugins: readonly unknown[]): string =>
+  plugins
+    .map((plugin, i) => {
+      const named = (plugin as { name?: unknown }).name
+      return typeof named === "string" && named !== "" ? named : `vitePlugins[${i}]`
+    })
+    .join(", ")
+
+/**
+ * Pick the bundler for `nifra build`, per app rather than per global default.
+ *
+ * The phase defaults are deliberately asymmetric - `nifra dev` is Vite (for the plugin ecosystem, and
+ * because Bun's DEV-server bundler cannot compile CSS Modules), `nifra build` is Bun (faster and
+ * Bun-native). For an app with no transforms that asymmetry is free: there is nothing to disagree about.
+ * For an app whose ONLY transforms are Vite plugins it is not. Those plugins run in dev and are then
+ * dropped by the Bun build - `buildForTarget` reads `clientPlugins`/`serverPlugins`, never `vitePlugins`
+ * - so the build succeeds, the output looks plausible, and the transform simply did not happen. That is
+ * the same failure {@link checkPipelineSeparation} exists to prevent, reached by crossing PHASES instead
+ * of slots, and the slot check cannot see it because the plugins are correctly placed.
+ *
+ * So the default follows the app: Vite plugins with no Bun counterpart means the app has exactly one
+ * pipeline that can build it, and that is the one used. An app declaring BOTH has supplied the Bun
+ * equivalent on purpose - nothing is dropped - so the fast Bun default stands.
+ *
+ * `forced` is `--vite` / `--bun` and always wins, except for the one combination that silently discards
+ * work, which throws instead. Refusing rather than warning matches the slot guard: a build that succeeds
+ * and omits the transform is worse than one that stops and says so.
+ */
+export function chooseBuildPipeline(
+  slots: PipelineSlots,
+  forced?: BuildPipeline,
+): PipelineDecision {
+  const vitePlugins = slots.vitePlugins ?? []
+  const bunPlugins = [...(slots.clientPlugins ?? []), ...(slots.serverPlugins ?? [])]
+  const viteOnly = vitePlugins.length > 0 && bunPlugins.length === 0
+
+  if (forced === "bun" && viteOnly) {
+    throw new Error(
+      "[nifra] `nifra build --bun` would silently drop this app's only transforms. `vitePlugins` are " +
+        "read by the Vite build; the Bun build reads `clientPlugins`/`serverPlugins`, so these would " +
+        "never run and the output would look plausible without them.\n" +
+        `  Would be dropped: ${pluginNames(vitePlugins)}\n` +
+        "  Drop the flag to build with Vite, or add the Bun equivalents to `clientPlugins`/`serverPlugins`.",
+    )
+  }
+  if (forced !== undefined) return { pipeline: forced }
+  if (viteOnly) {
+    return {
+      pipeline: "vite",
+      reason: `auto: this app's only transforms are \`vitePlugins\` (${pluginNames(vitePlugins)}), which the Bun build cannot run`,
+    }
+  }
+  return { pipeline: "bun" }
+}