@nifrajs/cli 2.2.0 → 2.4.0

package/src/mcp.ts

@@ -1,27 +1,33 @@
 /**
- * `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_learn`   - the guided, ordered path to build a nifra app end to end (create → deploy), each
+ *     step naming the tool that emits the correct artifact and how to verify it.
+ *   - `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.
+ *   - `nifra_explain` - resolve an error (pasted, or the dev server's last) into a structured
+ *     diagnostic: stable code, a codeframe in the user's source, and the recognised cause + fix.
+ *   - `nifra_inspect` - read the running dev server's recent request traces (method/path/status/
+ *     duration/ISR) from the DevTools plugin: what your requests ACTUALLY did, not a guess.
  *
  * 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).
  */
@@ -75,6 +81,67 @@ function childPath(name: "mcp-run" | "mcp-render" | "mcp-ws"): string {
  */
 const CHILD_TIMEOUT_MS = 30_000
 
+/** Local dev-tool reads are intentionally bounded: MCP runs in an agent process and must not hang on or
+ * buffer an unrelated loopback service just because a caller supplied its port. */
+export const LOCAL_TOOL_FETCH_TIMEOUT_MS = 2_000
+export const LOCAL_TOOL_MAX_RESPONSE_BYTES = 1_048_576
+
+/** 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
+    ? port
+    : undefined
+}
+
+/** Read a dev-tool response without allowing an untrusted localhost service to allocate unbounded memory. */
+export async function readBoundedResponse(
+  response: Response,
+  maxBytes = LOCAL_TOOL_MAX_RESPONSE_BYTES,
+): Promise<string> {
+  const declared = response.headers.get("content-length")
+  if (declared !== null) {
+    const length = Number(declared)
+    if (Number.isFinite(length) && length > maxBytes)
+      throw new Error("response exceeded the size limit")
+  }
+  if (response.body === null) return ""
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (value === undefined) continue
+      total += value.byteLength
+      if (total > maxBytes) {
+        await reader.cancel()
+        throw new Error("response exceeded the size limit")
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(bytes)
+}
+
+const notNifraResponse = (service: string): string =>
+  JSON.stringify(
+    {
+      code: "NIFRA_NOT_DEV_SERVER",
+      message: `The service on this port is not a Nifra ${service} endpoint.`,
+    },
+    null,
+    2,
+  )
+
 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 ` +
@@ -159,7 +226,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. */
@@ -217,7 +284,7 @@ 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}` : ""
@@ -297,7 +364,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",
@@ -616,7 +683,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.
@@ -630,7 +697,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,
   )
@@ -647,7 +714,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: {
@@ -668,10 +735,180 @@ export function projectTools(
         return describeProject(await loadAppCached(), filter)
       },
     },
+    {
+      name: "nifra_explain",
+      description:
+        "Turn a nifra error into a STRUCTURED diagnostic instead of eyeballing a stack trace: a stable `code`, the top frame in YOUR source, a codeframe around the offending line, and - when nifra recognises the failure - the plain-language `cause` + `fix` + docs anchor. Pass `error` (and `stack` if you have it, e.g. from nifra_run/nifra_test output or a failing build) to explain a specific failure; or pass `port` to fetch the running dev server's most recent SSR failure from `/__nifra/last-error`. Returns the same JSON the dev overlay renders.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          error: {
+            type: "string",
+            description:
+              "The error message to explain (copy it from nifra_run/nifra_test output or a failing build).",
+          },
+          stack: {
+            type: "string",
+            description:
+              "The error's stack trace, if you have it - enables the source codeframe and the top user frame.",
+          },
+          name: {
+            type: "string",
+            description:
+              "The error's class name (e.g. TypeError, SchemaError), if known - sharpens classification.",
+          },
+          port: {
+            type: "number",
+            description:
+              "Instead of a pasted error, fetch the running dev server's most recent SSR failure from this port.",
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const { error, stack, name, port } = args as {
+          error?: string
+          stack?: string
+          name?: string
+          port?: number
+        }
+        if (error !== undefined || stack !== undefined) {
+          const { buildDiagnostic } = await import("@nifrajs/web/diagnostic")
+          const e = new Error(error ?? "")
+          if (name !== undefined) e.name = name
+          if (stack !== undefined) e.stack = stack
+          return JSON.stringify(buildDiagnostic(e, { root: cwd }), null, 2)
+        }
+        if (port !== undefined) {
+          const validPort = validateLocalPort(port)
+          if (validPort === undefined) {
+            return JSON.stringify(
+              { code: "NIFRA_INVALID_PORT", message: "port must be an integer from 1 to 65535." },
+              null,
+              2,
+            )
+          }
+          const { LAST_ERROR_PATH } = await import("@nifrajs/web/diagnostic")
+          try {
+            const res = await fetch(`http://127.0.0.1:${validPort}${LAST_ERROR_PATH}`, {
+              signal: AbortSignal.timeout(LOCAL_TOOL_FETCH_TIMEOUT_MS),
+            })
+            if (res.headers.get("x-nifra-diagnostic") !== "true")
+              return notNifraResponse("diagnostic")
+            if (!res.ok) {
+              return JSON.stringify(
+                {
+                  code: "NIFRA_NONE",
+                  message: `dev server at :${validPort} returned ${res.status}`,
+                },
+                null,
+                2,
+              )
+            }
+            return await readBoundedResponse(res)
+          } catch (cause) {
+            return JSON.stringify(
+              {
+                code: "NIFRA_NONE",
+                message: `could not reach a nifra dev server at :${validPort} - ${cause instanceof Error ? cause.message : String(cause)}`,
+              },
+              null,
+              2,
+            )
+          }
+        }
+        return JSON.stringify(
+          {
+            code: "NIFRA_NONE",
+            message:
+              "Pass `error` (and `stack` if available) to explain a failure, or `port` to fetch the dev server's last error.",
+          },
+          null,
+          2,
+        )
+      },
+    },
+    {
+      name: "nifra_inspect",
+      description:
+        "Observe what your requests ACTUALLY did on the running dev server - the recent request traces the DevTools plugin records: `{ method, path, status, durationMs, isrStatus, bodyBytes }` per request. The read no other tool gives you: after nifra_run or a real browser request, call this to SEE the outcome (which route answered, the status, how long, ISR hit/miss) instead of guessing. Pass `port` (the running dev server); narrow with `path` (a path prefix) or `limit` (most recent N). Requires the app to mount `@nifrajs/web`'s `devtools()` plugin (which auto-enables in development).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          port: { type: "number", description: "The running dev server's port." },
+          path: { type: "string", description: "Only traces whose path starts with this prefix." },
+          limit: { type: "number", description: "Return only the most recent N traces." },
+        },
+        required: ["port"],
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const { port, path, limit } = args as { port?: number; path?: string; limit?: number }
+        if (port === undefined) {
+          return JSON.stringify(
+            {
+              events: [],
+              note: "Pass `port` - the running dev server whose request traces to read.",
+            },
+            null,
+            2,
+          )
+        }
+        try {
+          const validPort = validateLocalPort(port)
+          if (validPort === undefined) {
+            return JSON.stringify(
+              {
+                events: [],
+                code: "NIFRA_INVALID_PORT",
+                note: "port must be an integer from 1 to 65535.",
+              },
+              null,
+              2,
+            )
+          }
+          const url = new URL(`http://127.0.0.1:${validPort}/_nifra/devtools/state`)
+          if (path !== undefined) url.searchParams.set("path", path)
+          if (limit !== undefined) url.searchParams.set("limit", String(limit))
+          const res = await fetch(url, {
+            signal: AbortSignal.timeout(LOCAL_TOOL_FETCH_TIMEOUT_MS),
+          })
+          if (res.headers.get("x-nifra-devtools") !== "true") return notNifraResponse("DevTools")
+          if (res.status === 404) {
+            return JSON.stringify(
+              {
+                events: [],
+                note: "No DevTools endpoint on that server. Mount `devtools()` from @nifrajs/web and run in development.",
+              },
+              null,
+              2,
+            )
+          }
+          if (!res.ok) {
+            return JSON.stringify(
+              { events: [], note: `DevTools state returned ${res.status}.` },
+              null,
+              2,
+            )
+          }
+          return await readBoundedResponse(res)
+        } catch (cause) {
+          const validPort = validateLocalPort(port)
+          return JSON.stringify(
+            {
+              events: [],
+              note: `Could not reach a dev server at :${validPort ?? String(port)} - ${cause instanceof Error ? cause.message : String(cause)}`,
+            },
+            null,
+            2,
+          )
+        }
+      },
+    },
     {
       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: {
@@ -851,7 +1088,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: {
@@ -887,7 +1124,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: {
@@ -1086,7 +1323,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: {
@@ -1259,6 +1496,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
@@ -1270,24 +1555,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 }
@@ -1302,21 +1581,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

@@ -1,5 +1,5 @@
 /**
- * Pipeline separation guard — one bundler owns a phase, never two.
+ * 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