@nifrajs/cli 3.3.0 → 4.0.0

package/dist/mcp-exec.js

@@ -5,18 +5,36 @@
  * loading. It has no JSON-RPC transport or root-trust policy, so those seams remain independently
  * replaceable.
  */
-import { stat } from "node:fs/promises";
-import { resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Glob } from "bun";
-import { commandCatalog, commandMcpName, findCommandSpec, } from "./command-catalog.js";
+import { BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.js";
+import { commandCatalog, commandMcpInputSchema, commandMcpName, findCommandSpec, toCommandCatalogEntry, } from "./command-catalog.js";
 import { collectContractProof } from "./contract-proof.js";
 import { loadDocsCorpus } from "./docs-search.js";
 import { loadExamplesCorpus } from "./examples.js";
 import { dirError, openApiHandler, resolveProjectDir, } from "./mcp-context.js";
 import { docsTools } from "./mcp-docs-tools.js";
-import { CHILD_OUTPUT_MAX_BYTES, CHILD_TIMEOUT_MS, LOCAL_TOOL_FETCH_TIMEOUT_MS, notNifraResponse, readBoundedResponse, readBoundedStream, timeoutMessage, validateLocalPort, } from "./mcp-io.js";
+import { CHILD_INPUT_MAX_BYTES, CHILD_OUTPUT_MAX_BYTES, CHILD_TIMEOUT_MS, readBoundedStream, timeoutMessage, validateLocalPort, } from "./mcp-io.js";
+import { mcpProjectPathError, resolveMcpProjectPath } from "./mcp-path.js";
 import { loadTypesCorpus } from "./types-search.js";
+const CODEFRAME_SOURCE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|mdx)$/i;
+/** The files a stack the caller supplies may show a codeframe from: project source, never a dotfile
+ * or anything under a dot directory (`.env`, `.git/`, `.nifra/`). */
+function explainSourceGate(root) {
+    // The codeframe reads a native realpath, which expands a Windows short name (`RUNNER~1`); the root
+    // has to be spelled the same way or every file looks like it sits outside it.
+    let base = resolve(root);
+    try {
+        base = realpathSync.native(base);
+    }
+    catch { }
+    return (file) => CODEFRAME_SOURCE.test(file) &&
+        !relative(base, file)
+            .split(/[\\/]/)
+            .some((segment) => segment.startsWith("."));
+}
 /** Path to a sibling child entry (`mcp-run` / `mcp-render` / `mcp-ws`), resolved next to this module (`.ts` in
  * dev, `.js` once built). Each runs in a FRESH subprocess per call so the project's current code loads. */
 export function toMcpTool(source, options) {
@@ -26,22 +44,44 @@ export function toMcpTool(source, options) {
     const entry = "run" in source ? undefined : source;
     const { cwd } = options;
     const loadAppCached = options.loadAppCached ?? createCachedAppLoader(cwd);
+    const pathFields = ["config", "out", "lockfile", "before", "after", "baseline", "file"];
+    const catalogEntry = entry ?? toCommandCatalogEntry(spec);
     return {
-        name: commandMcpName(entry?.name ?? spec.name),
-        description: entry?.summary ?? spec.summary,
-        inputSchema: entry?.inputSchema ?? spec.input.jsonSchema,
+        name: commandMcpName(catalogEntry.name),
+        description: catalogEntry.summary,
+        inputSchema: commandMcpInputSchema(catalogEntry),
         handler: async (args, context) => {
             const raw = { ...args };
+            for (const field of catalogEntry.cliOnlyFields) {
+                if (raw[field] !== undefined)
+                    return JSON.stringify({ ok: false, error: `${field} is available only from the nifra CLI` }, null, 2);
+            }
             const dir = raw.dir;
             if (dir !== undefined && typeof dir !== "string")
                 return dirError(undefined);
             const target = resolveProjectDir(cwd, dir);
             if (target === null)
                 return dirError(dir);
-            if (typeof raw.config === "string") {
-                const config = resolve(target, raw.config);
-                if (config !== target && !config.startsWith(`${target}${sep}`))
-                    return JSON.stringify({ ok: false, error: "config must stay inside the selected project directory" }, null, 2);
+            for (const field of pathFields) {
+                const value = raw[field];
+                if (typeof value !== "string")
+                    continue;
+                const safe = resolveMcpProjectPath(target, value);
+                if (safe === null)
+                    return JSON.stringify({ ok: false, error: mcpProjectPathError(field, value) }, null, 2);
+                raw[field] = safe;
+            }
+            if (Array.isArray(raw.files)) {
+                const safeFiles = [];
+                for (const value of raw.files) {
+                    if (typeof value !== "string")
+                        continue;
+                    const safe = resolveMcpProjectPath(target, value);
+                    if (safe === null)
+                        return JSON.stringify({ ok: false, error: mcpProjectPathError("files", value) }, null, 2);
+                    safeFiles.push(safe);
+                }
+                raw.files = safeFiles;
             }
             delete raw.dir;
             let input;
@@ -80,7 +120,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
     const legacyTools = [
         {
             name: "nifra_verify",
-            description: "Run the shared repository verification plan. Set release=true for the full release plan; the response preserves the declarative gate order and each gate's remediation.",
+            description: "Run the shared repository verification plan. Set release=true for the full release plan; the response preserves the declarative gate order and each gate's remediation. A gate whose script the project's package.json does not declare is reported as undeclared and not run; the result passes when every gate that ran passed.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -149,9 +189,15 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                 if (baseline !== undefined && baseline.trim() === "") {
                     return JSON.stringify({ ok: false, error: "baseline must not be empty" }, null, 2);
                 }
+                const safeBaseline = baseline === undefined ? undefined : resolveMcpProjectPath(target, baseline);
+                if (baseline !== undefined && safeBaseline === null) {
+                    return JSON.stringify({ ok: false, error: mcpProjectPathError("baseline", baseline) }, null, 2);
+                }
                 try {
                     return JSON.stringify(await collectContractProof(target, {
-                        ...(baseline === undefined ? {} : { baselinePath: baseline }),
+                        ...(safeBaseline === undefined || safeBaseline === null
+                            ? {}
+                            : { baselinePath: safeBaseline }),
                         ...(raw.check === undefined ? {} : { check: raw.check === true }),
                     }), null, 2);
                 }
@@ -162,7 +208,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
         },
         {
             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.",
+            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. With no `error`, returns the running dev server's most recent error of any kind (SSR, loader, API, build, browser, hydration) with its request id - the server is found automatically; `port`/`dir` pick one when several run. nifra_errors lists them all. Returns the same JSON the dev overlay renders.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -180,13 +226,17 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                     },
                     port: {
                         type: "number",
-                        description: "Instead of a pasted error, fetch the running dev server's most recent SSR failure from this port.",
+                        description: "The dev server's port, when the workspace runs several. Optional: the project's `nifra dev` server is found automatically.",
+                    },
+                    dir: {
+                        type: "string",
+                        description: "The app directory, when the workspace runs more than one dev server.",
                     },
                 },
                 additionalProperties: false,
             },
-            handler: async (args) => {
-                const { error, stack, name, port } = args;
+            handler: async (args, context) => {
+                const { error, stack, name, port, dir } = args;
                 if (error !== undefined || stack !== undefined) {
                     const { buildDiagnostic } = await import("@nifrajs/web/diagnostic");
                     const e = new Error(error ?? "");
@@ -194,104 +244,78 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                         e.name = name;
                     if (stack !== undefined)
                         e.stack = stack;
-                    return JSON.stringify(buildDiagnostic(e, { root: cwd }), null, 2);
+                    return JSON.stringify(buildDiagnostic(e, { root: cwd, showSource: explainSourceGate(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);
-                    }
+                const target = resolveProjectDir(cwd, dir);
+                if (target === null)
+                    return dirError(dir);
+                if (port !== undefined && validateLocalPort(port) === undefined) {
+                    return JSON.stringify({ code: "NIFRA_INVALID_PORT", message: "port must be an integer from 1 to 65535." }, null, 2);
+                }
+                const { explainLatest } = await import("./dev-feed-tool.js");
+                try {
+                    return JSON.stringify(await explainLatest(target, port, context.signal), null, 2);
+                }
+                catch (cause) {
+                    return JSON.stringify({
+                        code: "NIFRA_NONE",
+                        message: `could not read the dev server's errors - ${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).",
+            description: "Observe what your requests ACTUALLY did on the running dev server: one trace per request, `{ requestId, method, path, status, durationMs, bytes, isr, errorIds, logCount }`. After nifra_run or a real browser request, call this to SEE the outcome (the status, how long, ISR hit/miss, whether it logged or failed) instead of guessing; pass a trace's `requestId` to nifra_errors/nifra_logs for what that request failed with or printed. Every `nifra dev` server keeps these traces and is found automatically; `port`/`dir` pick one when several run. Narrow with `path` (a path prefix), `requestId`, `since` (a cursor from an earlier call) or `limit` (most recent N). An explicit `port` this project did not start falls back to the `@nifrajs/devtools` plugin's traces.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    port: { type: "number", description: "The running dev server's port." },
+                    port: {
+                        type: "number",
+                        description: "The dev server's port. Optional: the project's server is found automatically.",
+                    },
                     path: { type: "string", description: "Only traces whose path starts with this prefix." },
+                    requestId: { type: "string", description: "Only the trace with this request id." },
+                    since: {
+                        type: "number",
+                        description: "Only traces after this cursor (the `cursor` an earlier call returned).",
+                    },
                     limit: { type: "number", description: "Return only the most recent N traces." },
+                    dir: {
+                        type: "string",
+                        description: "The app directory, when the workspace runs more than one dev server.",
+                    },
                 },
-                required: ["port"],
                 additionalProperties: false,
             },
-            handler: async (args) => {
-                const { port, path, limit } = args;
-                if (port === undefined) {
+            handler: async (args, context) => {
+                const { port, path, requestId, since, limit, dir } = args;
+                const target = resolveProjectDir(cwd, dir);
+                if (target === null)
+                    return dirError(dir);
+                if (port !== undefined && validateLocalPort(port) === undefined) {
                     return JSON.stringify({
-                        events: [],
-                        note: "Pass `port` - the running dev server whose request traces to read.",
+                        requests: [],
+                        code: "NIFRA_INVALID_PORT",
+                        note: "port must be an integer from 1 to 65535.",
                     }, null, 2);
                 }
+                const { inspectRequests } = await import("./dev-feed-tool.js");
                 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);
+                    const result = await inspectRequests(target, { port, path, requestId, since, limit }, context.signal);
+                    return JSON.stringify(result, null, 2);
                 }
                 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)}`,
+                        requests: [],
+                        note: `Could not read the dev server's request traces - ${cause instanceof Error ? cause.message : String(cause)}`,
                     }, null, 2);
                 }
             },
         },
         {
             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. 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.',
+            description: 'Return this project\'s backend OpenAPI 3.1 document generated from backend/app.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: {
@@ -311,7 +335,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
         },
         {
             name: "nifra_run",
-            description: "Run HTTP requests through this project's backend and return structured results (status, headers, parsed body, and any thrown error). Use it to verify code after editing: by default the backend is 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. Each request: { method?, path, body?, headers? }.",
+            description: "Run HTTP requests through this project's backend and return structured results: status, headers, parsed body, `logs` (what the handler printed, per request, secrets redacted) and `errors` (a Diagnostic with codeframe, cause and fix for a thrown error or the unhandled error behind a bare 500). Use it to verify code after editing: by default the backend is 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. Each request: { method?, path, body?, headers? }.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -330,7 +354,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                     },
                     entry: {
                         type: "string",
-                        description: "Backend entry file (default: backend.ts | app.ts).",
+                        description: "Backend entry file (default: backend/app.ts | app.ts).",
                     },
                     warm: {
                         type: "boolean",
@@ -394,7 +418,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                     },
                     entry: {
                         type: "string",
-                        description: "Backend entry file (default: backend.ts | app.ts).",
+                        description: "Backend entry file (default: backend/app.ts | app.ts).",
                     },
                 },
                 required: ["path"],
@@ -410,7 +434,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                 properties: {
                     pattern: {
                         type: "string",
-                        description: "Optional test file/path pattern passed as an argv item to `bun test`.",
+                        description: "Optional test file/path pattern inside the project, passed as an argv item to `bun test`.",
                     },
                     timeoutMs: {
                         type: "number",
@@ -437,7 +461,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
         ...docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus),
         {
             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).',
+            description: 'Map a URL path to the CORRECT routes/ files and get a contract-correct route pair: the page and its .backend.ts half (loader + output schema). 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 both files + the route contract + stubs (the page is ready-to-write for react/preact/solid/vanilla; for vue/svelte use nifra_example for the page body).',
             inputSchema: {
                 type: "object",
                 properties: {
@@ -447,7 +471,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                     },
                     write: {
                         type: "boolean",
-                        description: "When true, create the file if a verified ready-to-write stub exists. Refuses overwrite.",
+                        description: "When true, create both files if a verified ready-to-write page stub exists. Refuses overwrite.",
                     },
                     variant: {
                         type: "string",
@@ -470,7 +494,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                     return renderScaffold(path, framework, flavour);
                 const result = await writeScaffoldRoute(cwd, path, framework, flavour);
                 const status = result.written
-                    ? `Written: \`${result.file}\``
+                    ? `Written: \`${result.file}\` and \`${result.backend.file}\``
                     : `Not written: ${result.reason ?? "no write performed"}`;
                 return `${status}\n\n${renderScaffold(path, framework, flavour)}`;
             },
@@ -486,13 +510,13 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                 },
                 additionalProperties: false,
             },
-            handler: async (args) => {
+            handler: async (args, context) => {
                 const opts = args;
                 const target = resolveProjectDir(cwd, opts.dir);
                 if (target === null)
                     return dirError(opts.dir);
                 const { runHydrationAssurance } = await import("./assure-hydration.js");
-                return JSON.stringify(await runHydrationAssurance(target, { interact: opts.interact === true }), null, 2);
+                return JSON.stringify(await runHydrationAssurance(target, { interact: opts.interact === true }, { signal: context.signal }), null, 2);
             },
         },
     ];
@@ -517,7 +541,21 @@ function childPath(name) {
 export async function spawnChild(child, cwd, input, label, signal) {
     if (signal?.aborted)
         return `${label} cancelled before it started.`;
-    const proc = Bun.spawn(["bun", childPath(child), cwd], {
+    let encodedInput;
+    try {
+        encodedInput = JSON.stringify(input);
+    }
+    catch {
+        return `${label} input is not serializable.`;
+    }
+    if (new TextEncoder().encode(encodedInput).byteLength > CHILD_INPUT_MAX_BYTES)
+        return `${label} input exceeded ${CHILD_INPUT_MAX_BYTES} bytes.`;
+    if (signal?.aborted)
+        return `${label} cancelled${cancellationSuffix(signal)}.`;
+    const proc = Bun.spawn([process.execPath, childPath(child), cwd], {
+        cwd,
+        // Explicit: without `env`, Bun passes the environment it started with, missing `--env-file` values.
+        env: process.env,
         stdin: "pipe",
         stdout: "pipe",
         stderr: "pipe",
@@ -538,8 +576,12 @@ export async function spawnChild(child, cwd, input, label, signal) {
     }, CHILD_TIMEOUT_MS);
     let outputExceeded = false;
     try {
-        proc.stdin.write(JSON.stringify(input));
-        await proc.stdin.end();
+        if (signal?.aborted)
+            kill();
+        else {
+            proc.stdin.write(encodedInput);
+            await proc.stdin.end();
+        }
         const [out, err] = await Promise.all([
             readBoundedStream(proc.stdout, CHILD_OUTPUT_MAX_BYTES, () => {
                 outputExceeded = true;
@@ -552,7 +594,7 @@ export async function spawnChild(child, cwd, input, label, signal) {
         ]);
         await proc.exited;
         if (signal?.aborted) {
-            const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : "";
+            const reason = cancellationSuffix(signal);
             return `${label} cancelled${reason}.`;
         }
         if (outputExceeded) {
@@ -570,24 +612,42 @@ export async function spawnChild(child, cwd, input, label, signal) {
         signal?.removeEventListener("abort", abort);
     }
 }
-const WARM_RUN_GLOB = new Glob("**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,json}");
-const WARM_RUN_IGNORED = /(^|\/)(node_modules|dist(-[a-z0-9]+)?|build|\.nifra|\.git|\.wrangler|coverage)\//;
+const WARM_RUN_SOURCE = /\.(?:[cm]?[jt]sx?|json)$/;
+// Pruned while walking, not filtered after: a scan that descends into node_modules on every warm call
+// costs more than the cold start the worker saves.
+const WARM_RUN_SKIPPED_DIR = /^(?:\..*|node_modules|dist(?:-[a-z0-9]+)?|build|coverage)$/;
 const WARM_RUN_EXTRA_FILES = ["bun.lock", "bun.lockb"];
+const MAX_WARM_PENDING = 64;
 async function warmRunFingerprint(cwd) {
     const parts = [];
-    for await (const rawRel of WARM_RUN_GLOB.scan({ cwd, dot: false })) {
-        const rel = rawRel.replaceAll("\\", "/");
-        if (WARM_RUN_IGNORED.test(rel))
-            continue;
+    const walk = async (dir) => {
+        let entries;
         try {
-            const s = await stat(resolve(cwd, rel));
-            if (s.isFile())
-                parts.push(`${rel}:${s.mtimeMs}:${s.size}`);
+            entries = await readdir(resolve(cwd, dir), { withFileTypes: true });
         }
         catch {
-            // A file can disappear while an agent is editing. The next call will rescan the settled tree.
+            return;
         }
-    }
+        for (const entry of entries) {
+            const rel = dir === "" ? entry.name : `${dir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (!WARM_RUN_SKIPPED_DIR.test(entry.name))
+                    await walk(rel);
+                continue;
+            }
+            if (entry.name.startsWith(".") || !WARM_RUN_SOURCE.test(entry.name))
+                continue;
+            try {
+                const s = await stat(resolve(cwd, rel));
+                if (s.isFile())
+                    parts.push(`${rel}:${s.mtimeMs}:${s.size}`);
+            }
+            catch {
+                // A file can disappear while an agent is editing. The next call will rescan the settled tree.
+            }
+        }
+    };
+    await walk("");
     for (const rel of WARM_RUN_EXTRA_FILES) {
         parts.push(`${rel}:${await fileFingerprint(resolve(cwd, rel))}`);
     }
@@ -609,13 +669,17 @@ export class WarmWorker {
     proc;
     pending = new Map();
     stdoutBuffer = "";
+    stdoutBufferBytes = 0;
     stderrBuffer = "";
     nextId = 0;
     closed = false;
     constructor(child, cwd, fingerprint, label) {
         this.fingerprint = fingerprint;
         this.label = label;
-        this.proc = Bun.spawn(["bun", childPath(child), cwd, "--worker"], {
+        this.proc = Bun.spawn([process.execPath, childPath(child), cwd, "--worker"], {
+            cwd,
+            // Explicit: without `env`, Bun passes the environment it started with, missing `--env-file` values.
+            env: process.env,
             stdin: "pipe",
             stdout: "pipe",
             stderr: "pipe",
@@ -641,7 +705,20 @@ export class WarmWorker {
             throw new Error(`warm ${this.label} worker is closed`);
         if (signal?.aborted)
             return `${this.label} cancelled before it started.`;
+        if (this.pending.size >= MAX_WARM_PENDING)
+            throw new Error(`warm ${this.label} worker request limit reached`);
         const id = ++this.nextId;
+        let encodedInput;
+        try {
+            encodedInput = JSON.stringify({ id, input });
+        }
+        catch {
+            throw new Error(`warm ${this.label} input is not serializable`);
+        }
+        if (new TextEncoder().encode(encodedInput).byteLength > CHILD_INPUT_MAX_BYTES)
+            throw new Error(`warm ${this.label} input exceeded ${CHILD_INPUT_MAX_BYTES} bytes`);
+        if (signal?.aborted)
+            return `${this.label} cancelled${cancellationSuffix(signal)}.`;
         return new Promise((resolve, reject) => {
             const abort = () => {
                 // Per-request cancel: drop just THIS id and resolve its cancellation. The worker is shared
@@ -650,7 +727,8 @@ export class WarmWorker {
                 // 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}` : "";
+                signal?.removeEventListener("abort", abort);
+                const reason = cancellationSuffix(signal);
                 resolve(`${this.label} cancelled${reason}.`);
             };
             // Same backstop as the cold path: a worker wedged mid-request would otherwise leave this
@@ -669,8 +747,15 @@ export class WarmWorker {
             };
             signal?.addEventListener("abort", abort, { once: true });
             this.pending.set(id, { resolve, reject, cleanup });
+            // JSON serialization above can run user-defined `toJSON` hooks. Recheck after installing the
+            // listener and pending entry so an abort during that synchronous work cannot enqueue a request
+            // after cancellation, and so an already-aborted signal does not retain the listener.
+            if (signal?.aborted) {
+                abort();
+                return;
+            }
             try {
-                this.proc.stdin.write(`${JSON.stringify({ id, input })}\n`);
+                this.proc.stdin.write(`${encodedInput}\n`);
             }
             catch (err) {
                 this.pending.delete(id);
@@ -691,8 +776,10 @@ export class WarmWorker {
                 this.stop();
                 return;
             }
-            this.stdoutBuffer += decoder.decode(value, { stream: true });
-            if (this.stdoutBuffer.length > CHILD_OUTPUT_MAX_BYTES) {
+            const text = decoder.decode(value, { stream: true });
+            this.stdoutBuffer += text;
+            this.stdoutBufferBytes += new TextEncoder().encode(text).byteLength;
+            if (this.stdoutBufferBytes > CHILD_OUTPUT_MAX_BYTES) {
                 this.stderrBuffer = boundedAppend(this.stderrBuffer, `warm ${this.label} worker stdout exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes\n`);
                 this.stop();
                 return;
@@ -701,6 +788,7 @@ export class WarmWorker {
             while (nl !== -1) {
                 const line = this.stdoutBuffer.slice(0, nl).trim();
                 this.stdoutBuffer = this.stdoutBuffer.slice(nl + 1);
+                this.stdoutBufferBytes = new TextEncoder().encode(this.stdoutBuffer).byteLength;
                 nl = this.stdoutBuffer.indexOf("\n");
                 if (line !== "")
                     this.handleLine(line);
@@ -724,18 +812,56 @@ export class WarmWorker {
         }
         catch {
             this.stderrBuffer = boundedAppend(this.stderrBuffer, `invalid warm ${this.label} worker line: ${line}\n`);
+            this.stop();
             return;
         }
-        if (typeof message.id !== "number")
+        if (message === null ||
+            typeof message !== "object" ||
+            Array.isArray(message) ||
+            typeof message.id !== "number" ||
+            !Number.isSafeInteger(message.id)) {
+            this.stderrBuffer = boundedAppend(this.stderrBuffer, `invalid warm ${this.label} worker response envelope\n`);
+            this.stop();
             return;
-        const pending = this.pending.get(message.id);
+        }
+        const response = message;
+        const pending = this.pending.get(response.id);
         if (pending === undefined)
             return;
-        this.pending.delete(message.id);
+        if (!Object.hasOwn(response, "output")) {
+            this.pending.delete(response.id);
+            pending.cleanup();
+            pending.reject(new Error(`warm ${this.label} worker response is malformed`));
+            this.stop();
+            return;
+        }
+        let output;
+        try {
+            output = JSON.stringify(response.output, null, 2);
+        }
+        catch {
+            this.pending.delete(response.id);
+            pending.cleanup();
+            pending.reject(new Error(`warm ${this.label} worker response is not serializable`));
+            this.stop();
+            return;
+        }
+        if (new TextEncoder().encode(output).byteLength > CHILD_OUTPUT_MAX_BYTES) {
+            this.pending.delete(response.id);
+            pending.cleanup();
+            pending.reject(new Error(`warm ${this.label} worker response exceeded the size limit`));
+            this.stop();
+            return;
+        }
+        this.pending.delete(response.id);
         pending.cleanup();
-        pending.resolve(JSON.stringify(message.output, null, 2));
+        pending.resolve(output);
     }
 }
+function cancellationSuffix(signal) {
+    const reason = signal?.reason;
+    return typeof reason === "string" && reason.length > 0 ? `: ${reason.slice(0, 512)}` : "";
+}
 /** 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
@@ -744,18 +870,23 @@ export function createWarmHandler(child, cwd, label) {
     let worker;
     return async (input, signal) => {
         const fingerprint = await warmRunFingerprint(cwd);
-        if (worker === undefined || worker.fingerprint !== fingerprint) {
-            worker?.stop();
-            worker = new WarmWorker(child, cwd, fingerprint, label);
+        let current = worker;
+        if (current === undefined || current.fingerprint !== fingerprint) {
+            current?.stop();
+            current = new WarmWorker(child, cwd, fingerprint, label);
+            worker = current;
         }
         try {
-            return await worker.request(input, signal);
+            return await current.request(input, signal);
         }
         catch {
-            worker.stop();
-            worker = undefined;
+            // A source change can replace the shared worker while this request is in flight. Only clear
+            // the slot if this request still owns it; an old request must never tear down the replacement.
+            current.stop();
+            if (worker === current)
+                worker = undefined;
             if (signal?.aborted) {
-                const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : "";
+                const reason = cancellationSuffix(signal);
                 return `${label} cancelled${reason}.`;
             }
             return spawnChild(child, cwd, input, label, signal);
@@ -794,7 +925,7 @@ export async function renderHandler(cwd, args, context, warmRender) {
 export async function wsHandler(cwd, args, context) {
     return spawnChild("mcp-ws", cwd, args, "websocket", context.signal);
 }
-const APP_FINGERPRINT_FILES = ["nifra.config.ts", "framework.ts", "backend.ts"];
+const APP_FINGERPRINT_FILES = [CONFIG_FILE, FRAMEWORK_FILE, BACKEND_APP_FILE];
 function cacheToken(input) {
     let hash = 2166136261;
     for (let i = 0; i < input.length; i++) {
@@ -815,7 +946,8 @@ async function fileFingerprint(path) {
         throw err;
     }
 }
-async function appFingerprint(cwd) {
+/** `mtime:size` of the app's config, framework and backend entry files: what notices an edit. */
+export async function appFingerprint(cwd) {
     return (await Promise.all(APP_FINGERPRINT_FILES.map(async (file) => `${file}:${await fileFingerprint(resolve(cwd, file))}`))).join("|");
 }
 /** Cache LoadedApp inside one MCP server process, invalidating when config/backend mtimes change. */