@nifrajs/cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/introspect.ts

@@ -18,7 +18,7 @@ interface RouteDesc {
 }
 
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
-function backendRoutes(backend: unknown): RouteDesc[] {
+export function backendRoutes(backend: unknown): RouteDesc[] {
   if (backend && typeof (backend as { routes?: unknown }).routes === "function") {
     try {
       return (backend as { routes(): RouteDesc[] }).routes()
@@ -167,6 +167,20 @@ export function apiRoutesSection(routes: readonly RouteDesc[]): string {
   return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract — the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`
 }
 
+/** Compact API-routes INDEX for the no-arg `nifra_context` call — `METHOD path` per route, WITHOUT the
+ * body/query/response shapes or the per-route `call` line. Bounds the first-call payload on a big backend:
+ * an agent gets the full route list (so it knows what's mounted) plus a pointer to fetch any route's full
+ * contract via the `path`/`kind` slice, instead of every schema up front. */
+export function apiRoutesIndexSection(routes: readonly RouteDesc[]): string {
+  if (routes.length === 0) {
+    return "## API routes (backend.ts)\n\nNo `backend.ts` server routes found (this app may be frontend-only)."
+  }
+  const lines = [...routes]
+    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+    .map((r) => `- \`${r.method} ${r.path}\``)
+  return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form — or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
+}
+
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
 export function pageRoutesSection(manifest: Manifest | undefined): string {
   if (!manifest || manifest.routes.length === 0) {
@@ -203,8 +217,14 @@ export interface ContextFilter {
   readonly kind?: "api" | "pages"
 }
 
-/** Build the project brief (API routes + page routes + conventions) as Markdown — optionally
- * narrowed by {@link ContextFilter} for cheap follow-up calls. */
+/**
+ * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** — the route list (API
+ * routes as `METHOD path`, page routes as `pattern → file`) + conventions + a pointer to fetch full
+ * contracts via the slice — so learning a big project is cheap, not a full-surface schema dump. Passing a
+ * {@link ContextFilter} (`path` prefix and/or `kind`) returns the narrowed, FULL detail (per-route
+ * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
+ * already has it from the index call).
+ */
 export function describeProject(app: LoadedApp, filter?: ContextFilter): string {
   let manifest: Manifest | undefined
   try {
@@ -221,19 +241,24 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
       pages = { ...manifest, routes: manifest.routes.filter((r) => r.pattern.startsWith(prefix)) }
     }
   }
-  const narrowed = filter?.kind !== undefined || (prefix !== undefined && prefix !== "")
+  // No `path` and no `kind` → the first-call index (compact route list, no per-route schemas). Any filter
+  // → the narrowed full-detail slice (schemas + call form), unchanged.
+  const isIndex = filter?.kind === undefined && (prefix === undefined || prefix === "")
   const sections: string[] = [`# nifra project: ${app.cwd.slice(app.cwd.lastIndexOf("/") + 1)}`]
-  if (!narrowed) {
+  if (isIndex) {
     sections.push(
-      "A full-stack nifra app — Web-standard, one app on Bun, Node, Deno, and the edge.",
+      "A full-stack nifra app — Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
       // Point agents at the verified surface, not recalled APIs — nifra is young, so training data is the
       // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
       "> **Build against THIS surface + the verified tools — do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
     )
   }
-  if (filter?.kind !== "pages") sections.push(apiRoutesSection(routes))
+  if (filter?.kind !== "pages") {
+    // Index → compact `METHOD path` list; a slice → the full schema + call-form detail.
+    sections.push(isIndex ? apiRoutesIndexSection(routes) : apiRoutesSection(routes))
+  }
   if (filter?.kind !== "api") sections.push(pageRoutesSection(pages))
-  if (!narrowed) sections.push(CONVENTIONS)
+  if (isIndex) sections.push(CONVENTIONS)
   return sections.join("\n\n")
 }
 
@@ -282,3 +307,178 @@ export function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[] {
       }
     })
 }
+
+// ===================================================================================================
+// `nifra routes [--json]` — the focused, uniform view of every route the app serves, with methods.
+//
+// `nifra context` lists page routes + API routes for an agent's prompt (Markdown, with schemas).
+// `nifra routes` answers a different question: "what does this app actually serve, and with which
+// methods?" — so an agent sees instantly that `POST /api/explain` is (or isn't) mounted, instead of
+// discovering it via a 405. It marks which backend routes are AUTO-MOUNTED under the page router's
+// `apiPrefix` (default `/api`), and `--json` makes it machine-consumable. The table-building +
+// rendering are pure (no fs / no module loads), so they're unit-tested; the cwd gathering is the thin
+// async wrapper `describeRoutes`.
+// ===================================================================================================
+
+/** The kind of route: a file-routed `page` (SSR/SSG) or a backend `api` (HTTP handler). */
+export type RouteKind = "page" | "api"
+
+/** One row of the unified route table. */
+export interface RouteTableEntry {
+  readonly kind: RouteKind
+  /** The URL pattern (page: `/blog/:slug`; api: `/api/users`). */
+  readonly path: string
+  /** Methods this route serves, sorted (page: `GET`, plus `POST` when it has an `action`). */
+  readonly methods: readonly string[]
+  /** Source file (page only — the route module path relative to `routes/`). */
+  readonly file?: string
+  /** True when this API route is auto-mounted under the page router's `apiPrefix` (so it's reachable
+   * through the same web app, no hand-wired `if (pathname.startsWith("/api/"))`). Pages are never
+   * auto-mounted (they ARE the page router); only API routes carry this flag. */
+  readonly autoMounted?: boolean
+}
+
+/** A page route + whether its module exports an `action` (→ it also serves POST). The caller resolves
+ * `hasAction` (a module load); kept out of the pure builder so the builder needs no fs. */
+export interface PageRouteInput {
+  readonly pattern: string
+  readonly file: string
+  readonly hasAction: boolean
+}
+
+export interface RouteTableInput {
+  readonly pages: readonly PageRouteInput[]
+  readonly api: readonly RouteDesc[]
+  /** The page router's `apiPrefix` (default `/api`); an API route at/under it is auto-mounted. `""`
+   * disables the auto-mount, so no API route is marked auto-mounted. */
+  readonly apiPrefix?: string
+}
+
+/** True when `path` is at or under `prefix` as a path segment boundary (`/api` matches `/api` and
+ * `/api/x`, but not `/apiary`). An empty prefix matches nothing (auto-mount disabled). */
+function isUnderPrefix(path: string, prefix: string): boolean {
+  if (prefix === "") return false
+  return path === prefix || path.startsWith(`${prefix}/`)
+}
+
+/**
+ * Build the unified, sorted route table from page routes + backend API routes. Pure — the caller
+ * supplies page `hasAction` (resolved via a module load) and the API descriptors (`backend.routes()`).
+ * Page routes serve `GET` (+ `POST` when they export an `action`); API routes carry their declared
+ * method, and are flagged `autoMounted` when at/under `apiPrefix`. Sorted by path, then kind, then the
+ * joined methods, for stable output.
+ */
+export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
+  const apiPrefix = input.apiPrefix ?? "/api"
+  const rows: RouteTableEntry[] = []
+  for (const page of input.pages) {
+    const methods = page.hasAction ? ["GET", "POST"] : ["GET"]
+    rows.push({ kind: "page", path: page.pattern, methods, file: page.file })
+  }
+  // Collapse API routes that share a path into one row with all its methods (a REST resource).
+  const byPath = new Map<string, { methods: Set<string>; autoMounted: boolean }>()
+  for (const r of input.api) {
+    const existing = byPath.get(r.path)
+    if (existing === undefined) {
+      byPath.set(r.path, {
+        methods: new Set([r.method.toUpperCase()]),
+        autoMounted: isUnderPrefix(r.path, apiPrefix),
+      })
+    } else existing.methods.add(r.method.toUpperCase())
+  }
+  for (const [path, info] of byPath) {
+    rows.push({
+      kind: "api",
+      path,
+      methods: [...info.methods].sort(),
+      autoMounted: info.autoMounted,
+    })
+  }
+  return rows.sort(
+    (a, b) =>
+      a.path.localeCompare(b.path) ||
+      a.kind.localeCompare(b.kind) ||
+      a.methods.join(",").localeCompare(b.methods.join(",")),
+  )
+}
+
+/** Render the route table as a terse aligned text table (the `nifra routes` default output). Pure. */
+export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
+  if (rows.length === 0)
+    return "No routes found (no `routes/` pages and no `backend.ts` API routes)."
+  const display = rows.map((r) => ({
+    methods: r.methods.join(", "),
+    kind: r.kind,
+    path: r.kind === "api" && r.autoMounted ? `${r.path}  (auto-mounted)` : r.path,
+  }))
+  const methodW = Math.max("METHOD".length, ...display.map((d) => d.methods.length))
+  const kindW = Math.max("KIND".length, ...display.map((d) => d.kind.length))
+  const padEnd = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - s.length))
+  const line = (methods: string, kind: string, path: string): string =>
+    `${padEnd(methods, methodW)}  ${padEnd(kind, kindW)}  ${path}`
+  return [
+    line("METHOD", "KIND", "PATH"),
+    ...display.map((d) => line(d.methods, d.kind, d.path)),
+  ].join("\n")
+}
+
+/** One JSON row for `nifra routes --json` (the agent-facing, stable shape). */
+export interface RouteJsonRow {
+  readonly kind: RouteKind
+  readonly path: string
+  readonly methods: readonly string[]
+  readonly file?: string
+  readonly autoMounted?: boolean
+}
+
+/** The route table as a JSON document for `--json` (agents). Stable keys; `file`/`autoMounted` present
+ * only where meaningful (file on pages, autoMounted on API routes). */
+export function routeTableToJson(rows: readonly RouteTableEntry[]): {
+  readonly routes: readonly RouteJsonRow[]
+} {
+  return {
+    routes: rows.map((r) => ({
+      kind: r.kind,
+      path: r.path,
+      methods: r.methods,
+      ...(r.file !== undefined ? { file: r.file } : {}),
+      ...(r.kind === "api" ? { autoMounted: r.autoMounted === true } : {}),
+    })),
+  }
+}
+
+/** A route module that may export an `action` (→ the page serves POST). */
+interface MaybeActionModule {
+  readonly action?: unknown
+}
+
+/**
+ * Gather + render the unified route table for `nifra routes`. Discovers page routes (`discoverRoutes`),
+ * loads each module to detect an `action` export (→ POST), reads the backend's API routes, then renders
+ * text (default) or JSON (`--json`). The page-route load mirrors what SSR would do; a load failure
+ * degrades to GET-only for that route (never throws the whole command).
+ */
+export async function describeRoutes(
+  app: LoadedApp,
+  opts: { readonly json?: boolean } = {},
+): Promise<string> {
+  let manifest: Manifest | undefined
+  try {
+    manifest = discoverRoutes(app.routesDir)
+  } catch {
+    // No (or unreadable) routes/ — fall through with no pages; the table still shows API routes.
+  }
+  const pages: PageRouteInput[] = []
+  for (const route of manifest?.routes ?? []) {
+    let hasAction = false
+    try {
+      const mod = (await route.load()) as MaybeActionModule
+      hasAction = typeof mod.action === "function"
+    } catch {
+      // A route that can't be loaded at introspection time (e.g. a server-only import) → GET-only.
+    }
+    pages.push({ pattern: route.pattern, file: route.file, hasAction })
+  }
+  const rows = buildRouteTable({ pages, api: backendRoutes(app.backend) })
+  return opts.json ? JSON.stringify(routeTableToJson(rows), null, 2) : renderRouteTable(rows)
+}

package/src/mcp-render.ts

@@ -19,12 +19,10 @@ import { loadApp, resolvePlugins } from "./load.ts"
 const errString = (err: unknown): string =>
   err instanceof Error ? `${err.name}: ${err.message}` : String(err)
 
-export async function renderPages(
-  cwd: string,
-  requests: unknown,
-): Promise<{ results: unknown } | { error: string }> {
-  if (!Array.isArray(requests)) return { error: "expected { requests: [...] }" }
-
+/** 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 }> {
   let app: Awaited<ReturnType<typeof loadApp>>
   try {
     app = await loadApp(cwd, "dist")
@@ -43,30 +41,127 @@ export async function renderPages(
     return { error: errString(err) }
   }
 
-  let webApp: AppLike
   try {
-    webApp = createWebApp({
+    const webApp = createWebApp({
       // The adapter is validated by loadApp; cast at the seam (same as the CLI's `asAdapter`).
       adapter: app.framework.adapter as RenderAdapter,
       manifest: discoverRoutes(app.routesDir),
       clientEntry: "/_nifra-render-only.js", // placeholder; SSR HTML does not need the built client
       ...(app.backend !== undefined ? { api: inProcessClient(app.backend as never) } : {}),
     }) as unknown as AppLike
+    return { app: webApp }
   } catch (err) {
     return { error: errString(err) }
   }
+}
+
+export async function renderPages(
+  cwd: string,
+  requests: unknown,
+): Promise<{ results: unknown } | { error: string }> {
+  if (!Array.isArray(requests)) return { error: "expected { requests: [...] }" }
+
+  const built = await buildWebApp(cwd)
+  if ("error" in built) return built
 
   try {
-    return { results: await runApp(webApp, requests as Parameters<typeof runApp>[1]) }
+    return { results: await runApp(built.app, requests as Parameters<typeof runApp>[1]) }
   } catch (err) {
     return { error: errString(err) }
   }
 }
 
-// Child-process entry: read `{ requests }` from stdin, SSR, print JSON. Guarded so importing this
-// module in a test does not execute it.
+interface RenderWorkerMessage {
+  readonly id?: unknown
+  readonly input?: { readonly requests?: unknown }
+}
+
+/** Send console output to stderr so it never corrupts the newline-delimited JSON-RPC on stdout (mirrors
+ * `mcp-run`'s worker). A loader that logs would otherwise inject noise into a response line. */
+function redirectConsoleToStderr(): void {
+  const write = (level: string, args: unknown[]): void => {
+    Bun.stderr.write(`[${level}] ${args.map((arg) => String(arg)).join(" ")}\n`)
+  }
+  console.debug = (...args: unknown[]) => write("debug", args)
+  console.info = (...args: unknown[]) => write("info", args)
+  console.log = (...args: unknown[]) => write("log", args)
+  console.warn = (...args: unknown[]) => write("warn", args)
+  console.error = (...args: unknown[]) => write("error", args)
+}
+
+/**
+ * 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
+ * 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> {
+  redirectConsoleToStderr()
+  // Build once; the same `{ error }` is returned for every request if the build failed, so an agent sees
+  // the actionable message and the parent restarts the worker on the next file change.
+  const built = await buildWebApp(cwd)
+  const decoder = new TextDecoder()
+  let buffer = ""
+  const send = (id: unknown, output: unknown): void => {
+    process.stdout.write(`${JSON.stringify({ id, output })}\n`)
+  }
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk as Uint8Array, { stream: true })
+    let nl = buffer.indexOf("\n")
+    while (nl !== -1) {
+      const line = buffer.slice(0, nl).trim()
+      buffer = buffer.slice(nl + 1)
+      nl = buffer.indexOf("\n")
+      if (line === "") continue
+
+      let message: RenderWorkerMessage
+      try {
+        message = JSON.parse(line) as RenderWorkerMessage
+      } catch {
+        send(null, { error: "invalid worker input: expected JSON line" })
+        continue
+      }
+      const requests = message.input?.requests
+      if (!Array.isArray(requests)) {
+        send(message.id, { error: "expected { requests: [...] }" })
+        continue
+      }
+      if ("error" in built) {
+        send(message.id, built)
+        continue
+      }
+      try {
+        send(message.id, {
+          results: await runApp(built.app, requests as Parameters<typeof runApp>[1]),
+        })
+      } catch (err) {
+        send(message.id, { error: errString(err) })
+      }
+    }
+  }
+}
+
+// Child-process entry: read `{ requests }` from stdin, SSR, print JSON. `--worker` runs the persistent
+// warm loop instead. Guarded so importing this module in a test does not execute it.
 if (import.meta.main) {
   const cwd = process.argv[2] ?? process.cwd()
+  // 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
+  // surfaces later as a load error rather than crashing the child here.
+  if (cwd !== process.cwd()) {
+    try {
+      process.chdir(cwd)
+    } catch {
+      // Leave cwd as-is; loadApp(cwd) below uses the explicit `cwd` arg and will report an actionable
+      // error if the directory is unusable. The adapter then falls back to its bundled react-dom.
+    }
+  }
+  if (process.argv.includes("--worker")) {
+    await runWorker(cwd)
+    process.exit(0)
+  }
   let output: unknown
   try {
     const { requests } = JSON.parse(await Bun.stdin.text()) as { requests: unknown }

package/src/mcp.ts

@@ -119,7 +119,12 @@ type PipeSubprocess = ReturnType<typeof Bun.spawn> & {
   readonly stderr: ReadableStream<Uint8Array>
 }
 
-class WarmRunWorker {
+/** 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
+ * 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. */
+class WarmWorker {
   private readonly proc: PipeSubprocess
   private readonly pending = new Map<
     number,
@@ -135,10 +140,12 @@ class WarmRunWorker {
   private closed = false
 
   constructor(
+    child: "mcp-run" | "mcp-render",
     cwd: string,
     readonly fingerprint: string,
+    private readonly label: string,
   ) {
-    this.proc = Bun.spawn(["bun", childPath("mcp-run"), cwd, "--worker"], {
+    this.proc = Bun.spawn(["bun", childPath(child), cwd, "--worker"], {
       stdin: "pipe",
       stdout: "pipe",
       stderr: "pipe",
@@ -148,7 +155,7 @@ class WarmRunWorker {
     void this.proc.exited.then((code) => {
       this.closed = true
       const err = new Error(
-        `warm run worker exited (${code})${this.stderrBuffer ? `:\n${this.stderrBuffer}` : ""}`,
+        `warm ${this.label} worker exited (${code})${this.stderrBuffer ? `:\n${this.stderrBuffer}` : ""}`,
       )
       for (const pending of this.pending.values()) {
         pending.cleanup()
@@ -163,15 +170,15 @@ class WarmRunWorker {
   }
 
   async request(input: unknown, signal?: AbortSignal): Promise<string> {
-    if (this.closed) throw new Error("warm run worker is closed")
-    if (signal?.aborted) return "run cancelled before it started."
+    if (this.closed) throw new Error(`warm ${this.label} worker is closed`)
+    if (signal?.aborted) return `${this.label} cancelled before it started.`
     const id = ++this.nextId
     return new Promise((resolve, reject) => {
       const abort = (): void => {
         this.pending.delete(id)
         this.stop()
         const reason = typeof signal?.reason === "string" ? `: ${signal.reason}` : ""
-        resolve(`run cancelled${reason}.`)
+        resolve(`${this.label} cancelled${reason}.`)
       }
       const cleanup = (): void => signal?.removeEventListener("abort", abort)
       signal?.addEventListener("abort", abort, { once: true })
@@ -218,7 +225,10 @@ class WarmRunWorker {
     try {
       message = JSON.parse(line) as { id?: unknown; output?: unknown }
     } catch {
-      this.stderrBuffer = boundedAppend(this.stderrBuffer, `invalid warm worker line: ${line}\n`)
+      this.stderrBuffer = boundedAppend(
+        this.stderrBuffer,
+        `invalid warm ${this.label} worker line: ${line}\n`,
+      )
       return
     }
     if (typeof message.id !== "number") return
@@ -230,15 +240,21 @@ class WarmRunWorker {
   }
 }
 
-function createWarmRunHandler(
+/** 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
+ * message label, so there's a single source for the reuse + auto-restart-on-file-change logic. */
+function createWarmHandler(
+  child: "mcp-run" | "mcp-render",
   cwd: string,
+  label: string,
 ): (input: unknown, signal?: AbortSignal) => Promise<string> {
-  let worker: WarmRunWorker | undefined
+  let worker: WarmWorker | undefined
   return async (input, signal) => {
     const fingerprint = await warmRunFingerprint(cwd)
     if (worker === undefined || worker.fingerprint !== fingerprint) {
       worker?.stop()
-      worker = new WarmRunWorker(cwd, fingerprint)
+      worker = new WarmWorker(child, cwd, fingerprint, label)
     }
     try {
       return await worker.request(input, signal)
@@ -247,9 +263,9 @@ function createWarmRunHandler(
       worker = undefined
       if (signal?.aborted) {
         const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : ""
-        return `run cancelled${reason}.`
+        return `${label} cancelled${reason}.`
       }
-      return spawnChild("mcp-run", cwd, input, "run", signal)
+      return spawnChild(child, cwd, input, label, signal)
     }
   }
 }
@@ -273,17 +289,25 @@ async function runHandler(
   return spawnChild("mcp-run", cwd, input, "run", context.signal)
 }
 
-/** The `nifra_render` handler: SSR page routes through the project's CURRENT web app, return the HTML. */
+/** The `nifra_render` handler: SSR page routes through the project's CURRENT web app, return the HTML.
+ * By default a fresh subprocess loads the current code each call; `warm:true` reuses a hot worker (like
+ * `nifra_run`) that auto-restarts when a source file changes. */
 async function renderHandler(
   cwd: string,
   args: Record<string, unknown>,
   context: McpToolContext,
+  warmRender: (input: unknown, signal?: AbortSignal) => Promise<string>,
 ): Promise<string> {
   const requests = Array.isArray(args.requests) ? args.requests : []
   if (requests.length === 0) {
     return 'No requests provided. Pass { "requests": [{ "path": "/..." }] }.'
   }
-  return spawnChild("mcp-render", cwd, { requests }, "render", context.signal)
+  const input = { requests }
+  if ((args as { warm?: boolean }).warm === true) {
+    context.reportProgress(0.2, 1)
+    return warmRender(input, context.signal)
+  }
+  return spawnChild("mcp-render", cwd, input, "render", context.signal)
 }
 
 /** The `nifra_ws` handler: verify WebSocket routes through a fresh app subprocess. */
@@ -386,7 +410,8 @@ async function openApiHandler(
   loadAppCached: (outDirName?: string) => Promise<LoadedApp>,
 ): Promise<string> {
   const { renderOpenApi } = await import("./openapi-tool.ts")
-  return renderOpenApi(await loadAppCached(), openApiFormat(args))
+  const pathPrefix = typeof args.path === "string" ? args.path : undefined
+  return renderOpenApi(await loadAppCached(), openApiFormat(args), pathPrefix)
 }
 
 async function readProjectFile(
@@ -540,12 +565,13 @@ export function projectTools(
   cwd: string,
   loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
 ): McpTool[] {
-  const warmRun = createWarmRunHandler(cwd)
+  const warmRun = createWarmHandler("mcp-run", cwd, "run")
+  const warmRender = createWarmHandler("mcp-render", cwd, "render")
   return [
     {
       name: "nifra_context",
       description:
-        "Get this nifra project's surface: API routes (backend.ts) with compact TypeScript-shaped contracts, page routes (routes/), and the framework conventions. Call it once unfiltered to learn the project; afterwards pass `path` (a route prefix like /api/orders) and/or `kind` (api|pages) for a cheap, narrow slice instead of the full dump.",
+        "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: {
@@ -589,7 +615,7 @@ export function projectTools(
     {
       name: "nifra_openapi",
       description:
-        'Return this project\'s backend OpenAPI 3.1 document generated from backend.ts route schemas via @nifrajs/schema. Use `format:"json"` for machine edits (default) or `format:"yaml"` for humans. Frontend-only apps return a valid empty paths object.',
+        'Return this project\'s backend OpenAPI 3.1 document generated from backend.ts route schemas via @nifrajs/schema. Use `format:"json"` for machine edits (default) or `format:"yaml"` for humans. Pass `path` (a route prefix like /api/orders, mirroring nifra_routes) to narrow a large backend to operations under that prefix instead of the whole document. Frontend-only apps return a valid empty paths object.',
       inputSchema: {
         type: "object",
         properties: {
@@ -598,6 +624,11 @@ export function projectTools(
             enum: ["json", "yaml"],
             description: "Output format (default: json).",
           },
+          path: {
+            type: "string",
+            description:
+              "Only operations whose path starts with this prefix (omit for the whole document).",
+          },
         },
         additionalProperties: false,
       },
@@ -641,7 +672,7 @@ export function projectTools(
     {
       name: "nifra_render",
       description:
-        "SSR a page route (routes/) through this project's CURRENT web app and return { status, headers, body: the rendered HTML }. The page half of nifra_run: use it to verify a page renders and its loader ran after an edit. No build needed (a placeholder client entry is used; the SSR HTML renders regardless). Each request: { path, headers? }. Re-loaded in a fresh process each call.",
+        "SSR a page route (routes/) through this project's CURRENT web app and return { status, headers, body: the rendered HTML }. The page half of nifra_run: use it to verify a page renders and its loader ran after an edit. No build needed (a placeholder client entry is used; the SSR HTML renders regardless). Each request: { path, headers? }. By default re-loaded in a fresh process each call; pass warm:true to reuse a hot worker while source files are unchanged (it restarts automatically when files change), mirroring nifra_run.",
       inputSchema: {
         type: "object",
         properties: {
@@ -656,11 +687,16 @@ export function projectTools(
               required: ["path"],
             },
           },
+          warm: {
+            type: "boolean",
+            description:
+              "Reuse a hot web-app worker while source files are unchanged. Default false for maximum isolation.",
+          },
         },
         required: ["requests"],
         additionalProperties: false,
       },
-      handler: (args, context) => renderHandler(cwd, args, context),
+      handler: (args, context) => renderHandler(cwd, args, context, warmRender),
     },
     {
       name: "nifra_ws",

package/src/openapi-tool.ts

@@ -41,11 +41,31 @@ function toYaml(value: unknown, depth = 0): string {
     .join("\n")
 }
 
-/** 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. */
-export function renderOpenApi(app: LoadedApp, format: OpenApiFormat): 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 —
+ * 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),
+ * the trimmed document still references those names, and recomputing the exact reachable subset isn't
+ * worth the risk of emitting a `$ref` with no target.
+ */
+export function renderOpenApi(app: LoadedApp, format: OpenApiFormat, pathPrefix?: string): string {
   const title = `${basename(app.cwd)} API`
   const input = hasRoutesMethod(app.backend) ? app.backend : {}
-  const document = toOpenAPI(input, { title, version: "1.0.0" })
+  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.
+  const document =
+    pathPrefix !== undefined && pathPrefix !== ""
+      ? {
+          ...generated,
+          paths: Object.fromEntries(
+            Object.entries(generated.paths).filter(([path]) => path.startsWith(pathPrefix)),
+          ),
+        }
+      : generated
   return format === "yaml" ? toYaml(document) : JSON.stringify(document, null, 2)
 }