@nifrajs/cli 3.1.0 → 3.2.0

package/dist/mcp.js

@@ -34,1194 +34,23 @@
  * 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).
  */
-import { realpathSync } from "node:fs";
-import { readFile, stat } from "node:fs/promises";
-import { basename, isAbsolute, relative, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-import { reflectRoutes } from "@nifrajs/core/reflection";
-import { Glob } from "bun";
-import { commandCatalog, commandMcpName, findCommandSpec, } from "./command-catalog.js";
-import { collectContractProof } from "./contract-proof.js";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
 import { loadDocsCorpus } from "./docs-search.js";
 import { loadExamplesCorpus } from "./examples.js";
 import { detectMonorepo, loadMonorepoApps } from "./load.js";
 import { docsTools } from "./mcp-docs-tools.js";
 import { createMcpProtocolState, handleRpc, rpcError, } from "./mcp-protocol.js";
-import { applyClientRoots, detectToolingDrift, driftNote, pathsFromRootsResult, resolveRootState, rootInstructions, rootVerdict, } from "./mcp-root.js";
+import { extractBackendPrompts, extractBackendResources, extractBackendTools, } from "./mcp-reflect.js";
 import { loadTypesCorpus } from "./types-search.js";
-/** 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. */
-function childPath(name) {
-    return fileURLToPath(new URL(import.meta.url)).replace(/mcp\.(ts|js)$/, `${name}.$1`);
-}
-/** Spawn `bun <child> <cwd>`, pipe `input` to its stdin, return its stdout (or a stderr-backed error). */
-/**
- * How long a child gets before it is killed.
- *
- * A child loads the app, which runs its module side effects - a database pool, a Redis client, a
- * metrics interval. Any of those keeps the child's event loop alive after the work is done, and the
- * parent is sitting in `await proc.exited`. The children now exit explicitly, so this is the backstop
- * rather than the fix: without it a single wedged child blocks an agent indefinitely, and the caller
- * has no way to tell "still working" from "never returning".
- *
- * Generous enough for a cold start that compiles route modules, short enough that a hang is reported
- * within one attention span rather than after minutes of polling.
- */
-const CHILD_TIMEOUT_MS = 30_000;
-/** Maximum stdout or stderr retained from a project subprocess. The process is killed at the limit. */
-export const CHILD_OUTPUT_MAX_BYTES = 1_048_576;
-/** 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) {
-    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, maxBytes = LOCAL_TOOL_MAX_RESPONSE_BYTES) {
-    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 = [];
-    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) => JSON.stringify({
-    code: "NIFRA_NOT_DEV_SERVER",
-    message: `The service on this port is not a Nifra ${service} endpoint.`,
-}, null, 2);
-const timeoutMessage = (label, ms) => `${label} timed out after ${ms / 1000}s and was terminated.\n` +
-    `The app was loaded but the process did not finish. Most often this is a module-level side effect ` +
-    `that keeps the event loop alive (a database pool, a Redis client, an interval) opened during import ` +
-    `rather than lazily. Check for top-level connections in the app entry or anything it imports.`;
-/** Read child output incrementally and cancel as soon as the byte budget is crossed. */
-export async function readBoundedStream(stream, maxBytes = CHILD_OUTPUT_MAX_BYTES, onLimit) {
-    const reader = stream.getReader();
-    const decoder = new TextDecoder();
-    const chunks = [];
-    let totalBytes = 0;
-    try {
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done) {
-                chunks.push(decoder.decode());
-                return { text: chunks.join(""), truncated: false };
-            }
-            if (value === undefined)
-                continue;
-            const remaining = maxBytes - totalBytes;
-            if (remaining <= 0 || value.byteLength > remaining) {
-                if (remaining > 0) {
-                    chunks.push(decoder.decode(value.subarray(0, remaining), { stream: true }));
-                    chunks.push(decoder.decode());
-                }
-                await reader.cancel();
-                onLimit?.();
-                return { text: chunks.join(""), truncated: true };
-            }
-            totalBytes += value.byteLength;
-            chunks.push(decoder.decode(value, { stream: true }));
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-}
-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], {
-        stdin: "pipe",
-        stdout: "pipe",
-        stderr: "pipe",
-    });
-    let killed = false;
-    const kill = () => {
-        if (killed)
-            return;
-        killed = true;
-        proc.kill();
-    };
-    const abort = () => kill();
-    signal?.addEventListener("abort", abort, { once: true });
-    let timedOut = false;
-    const timer = setTimeout(() => {
-        timedOut = true;
-        kill();
-    }, CHILD_TIMEOUT_MS);
-    let outputExceeded = false;
-    try {
-        proc.stdin.write(JSON.stringify(input));
-        await proc.stdin.end();
-        const [out, err] = await Promise.all([
-            readBoundedStream(proc.stdout, CHILD_OUTPUT_MAX_BYTES, () => {
-                outputExceeded = true;
-                kill();
-            }),
-            readBoundedStream(proc.stderr, CHILD_OUTPUT_MAX_BYTES, () => {
-                outputExceeded = true;
-                kill();
-            }),
-        ]);
-        await proc.exited;
-        if (signal?.aborted) {
-            const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : "";
-            return `${label} cancelled${reason}.`;
-        }
-        if (outputExceeded) {
-            return `${label} output exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes and was terminated.`;
-        }
-        // A killed child may still have flushed a complete result before the timer fired; prefer real
-        // output over the timeout message so a slow-but-successful render is not reported as a failure.
-        const text = out.text.trim();
-        if (timedOut && text === "")
-            return timeoutMessage(label, CHILD_TIMEOUT_MS);
-        return text || `${label} failed:\n${err.text.trim() || "(no output)"}`;
-    }
-    finally {
-        clearTimeout(timer);
-        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_EXTRA_FILES = ["bun.lock", "bun.lockb"];
-async function warmRunFingerprint(cwd) {
-    const parts = [];
-    for await (const rel of WARM_RUN_GLOB.scan({ cwd, dot: false })) {
-        if (WARM_RUN_IGNORED.test(rel))
-            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.
-        }
-    }
-    for (const rel of WARM_RUN_EXTRA_FILES) {
-        parts.push(`${rel}:${await fileFingerprint(resolve(cwd, rel))}`);
-    }
-    return cacheToken(parts.sort().join("|"));
-}
-function boundedAppend(current, next, max = 12_000) {
-    const combined = `${current}${next}`;
-    return combined.length <= max ? combined : combined.slice(combined.length - max);
-}
-/** 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. Exported for the
- * concurrency test that proves a single per-request cancel doesn't tear down the shared worker. */
-export class WarmWorker {
-    fingerprint;
-    label;
-    proc;
-    pending = new Map();
-    stdoutBuffer = "";
-    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"], {
-            stdin: "pipe",
-            stdout: "pipe",
-            stderr: "pipe",
-        });
-        void this.readStdout();
-        void this.readStderr();
-        void this.proc.exited.then((code) => {
-            this.closed = true;
-            const err = new Error(`warm ${this.label} worker exited (${code})${this.stderrBuffer ? `:\n${this.stderrBuffer}` : ""}`);
-            for (const pending of this.pending.values()) {
-                pending.cleanup();
-                pending.reject(err);
-            }
-            this.pending.clear();
-        });
-    }
-    stop() {
-        if (!this.closed)
-            this.proc.kill();
-    }
-    async request(input, signal) {
-        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 = () => {
-                // 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.
-                this.pending.delete(id);
-                clearTimeout(timer);
-                const reason = typeof signal?.reason === "string" ? `: ${signal.reason}` : "";
-                resolve(`${this.label} cancelled${reason}.`);
-            };
-            // Same backstop as the cold path: a worker wedged mid-request would otherwise leave this
-            // promise unsettled forever. Drop the id and replace the worker - unlike a per-request cancel,
-            // a timeout means the worker itself is suspect, so the next call should start from a fresh one.
-            const timer = setTimeout(() => {
-                if (!this.pending.delete(id))
-                    return;
-                signal?.removeEventListener("abort", abort);
-                this.stop();
-                resolve(timeoutMessage(this.label, CHILD_TIMEOUT_MS));
-            }, CHILD_TIMEOUT_MS);
-            const cleanup = () => {
-                clearTimeout(timer);
-                signal?.removeEventListener("abort", abort);
-            };
-            signal?.addEventListener("abort", abort, { once: true });
-            this.pending.set(id, { resolve, reject, cleanup });
-            try {
-                this.proc.stdin.write(`${JSON.stringify({ id, input })}\n`);
-            }
-            catch (err) {
-                this.pending.delete(id);
-                cleanup();
-                reject(err instanceof Error ? err : new Error(String(err)));
-            }
-        });
-    }
-    async readStdout() {
-        const decoder = new TextDecoder();
-        const reader = this.proc.stdout.getReader();
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            if (value !== undefined && value.byteLength > CHILD_OUTPUT_MAX_BYTES) {
-                this.stderrBuffer = boundedAppend(this.stderrBuffer, `warm ${this.label} worker stdout exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes\n`);
-                this.stop();
-                return;
-            }
-            this.stdoutBuffer += decoder.decode(value, { stream: true });
-            if (this.stdoutBuffer.length > CHILD_OUTPUT_MAX_BYTES) {
-                this.stderrBuffer = boundedAppend(this.stderrBuffer, `warm ${this.label} worker stdout exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes\n`);
-                this.stop();
-                return;
-            }
-            let nl = this.stdoutBuffer.indexOf("\n");
-            while (nl !== -1) {
-                const line = this.stdoutBuffer.slice(0, nl).trim();
-                this.stdoutBuffer = this.stdoutBuffer.slice(nl + 1);
-                nl = this.stdoutBuffer.indexOf("\n");
-                if (line !== "")
-                    this.handleLine(line);
-            }
-        }
-    }
-    async readStderr() {
-        const decoder = new TextDecoder();
-        const reader = this.proc.stderr.getReader();
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            this.stderrBuffer = boundedAppend(this.stderrBuffer, decoder.decode(value, { stream: true }));
-        }
-    }
-    handleLine(line) {
-        let message;
-        try {
-            message = JSON.parse(line);
-        }
-        catch {
-            this.stderrBuffer = boundedAppend(this.stderrBuffer, `invalid warm ${this.label} worker line: ${line}\n`);
-            return;
-        }
-        if (typeof message.id !== "number")
-            return;
-        const pending = this.pending.get(message.id);
-        if (pending === undefined)
-            return;
-        this.pending.delete(message.id);
-        pending.cleanup();
-        pending.resolve(JSON.stringify(message.output, null, 2));
-    }
-}
-/** 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, 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);
-        }
-        try {
-            return await worker.request(input, signal);
-        }
-        catch {
-            worker.stop();
-            worker = undefined;
-            if (signal?.aborted) {
-                const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : "";
-                return `${label} cancelled${reason}.`;
-            }
-            return spawnChild(child, cwd, input, label, signal);
-        }
-    };
-}
-/** The `nifra_run` handler: run requests through the project's CURRENT backend, return structured results. */
-async function runHandler(cwd, args, context, warmRun) {
-    const requests = Array.isArray(args.requests) ? args.requests : [];
-    if (requests.length === 0) {
-        return 'No requests provided. Pass { "requests": [{ "path": "/..." }] }.';
-    }
-    const input = { requests, entry: args.entry };
-    if (args.warm === true) {
-        context.reportProgress(0.2, 1);
-        return warmRun(input, context.signal);
-    }
-    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.
- * 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, args, context, warmRender) {
-    const requests = Array.isArray(args.requests) ? args.requests : [];
-    if (requests.length === 0) {
-        return 'No requests provided. Pass { "requests": [{ "path": "/..." }] }.';
-    }
-    const input = { requests };
-    if (args.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. */
-async function wsHandler(cwd, args, context) {
-    return spawnChild("mcp-ws", cwd, args, "websocket", context.signal);
-}
-function openApiFormat(args) {
-    const format = args.format;
-    return format === "yaml" ? "yaml" : "json";
-}
-const APP_FINGERPRINT_FILES = ["nifra.config.ts", "framework.ts", "backend.ts"];
-function cacheToken(input) {
-    let hash = 2166136261;
-    for (let i = 0; i < input.length; i++) {
-        hash ^= input.charCodeAt(i);
-        hash = Math.imul(hash, 16777619);
-    }
-    return `mcp=${(hash >>> 0).toString(36)}`;
-}
-async function fileFingerprint(path) {
-    try {
-        const s = await stat(path);
-        return `${s.mtimeMs}:${s.size}`;
-    }
-    catch (err) {
-        if (err && typeof err === "object" && err.code === "ENOENT") {
-            return "missing";
-        }
-        throw err;
-    }
-}
-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. */
-export function createCachedAppLoader(cwd, options = {}) {
-    const loadAppCached = options.loadApp ??
-        (async (root, outDirName, loadOptions) => {
-            const mod = await import("./load.js");
-            return mod.loadApp(root, outDirName, loadOptions);
-        });
-    const fingerprint = options.fingerprint ?? appFingerprint;
-    let cached;
-    return async (outDirName = "dist") => {
-        const nextFingerprint = await fingerprint(cwd);
-        if (cached !== undefined &&
-            cached.outDirName === outDirName &&
-            cached.fingerprint === nextFingerprint) {
-            return cached.app;
-        }
-        const app = await loadAppCached(cwd, outDirName, {
-            importQuery: cacheToken(nextFingerprint),
-        });
-        cached = { outDirName, fingerprint: nextFingerprint, app };
-        return app;
-    };
-}
-async function openApiHandler(args, loadAppCached) {
-    const { renderOpenApi } = await import("./openapi-tool.js");
-    const pathPrefix = typeof args.path === "string" ? args.path : undefined;
-    return renderOpenApi(await loadAppCached(), openApiFormat(args), pathPrefix);
-}
-async function readProjectFile(cwd, relativeFile, maxChars) {
-    const target = resolve(cwd, relativeFile);
-    const root = resolve(cwd);
-    if (target !== root && !target.startsWith(`${root}${sep}`)) {
-        throw new Error(`refusing to read outside project root: ${relativeFile}`);
-    }
-    try {
-        const text = await readFile(target, "utf8");
-        return text.length <= maxChars
-            ? text
-            : `${text.slice(0, maxChars)}\n…(trimmed; read ${relativeFile} directly for the rest)`;
-    }
-    catch (err) {
-        if (err && typeof err === "object" && err.code === "ENOENT") {
-            return `No ${relativeFile} found in ${basename(cwd)}.`;
-        }
-        throw err;
-    }
-}
-function promptText(text) {
-    return [{ role: "user", content: { type: "text", text } }];
-}
-export function projectResources(cwd, loadAppCached = createCachedAppLoader(cwd)) {
-    return [
-        {
-            uri: "nifra://routes",
-            name: "API routes",
-            description: "Structured API routes with typed-client calls and compact request/response shapes.",
-            mimeType: "application/json",
-            read: async () => {
-                const { routesToJson } = await import("./introspect.js");
-                return { text: JSON.stringify(routesToJson(await loadAppCached()), null, 2) };
-            },
-        },
-        {
-            uri: "nifra://openapi",
-            name: "OpenAPI 3.1",
-            description: "OpenAPI document generated from backend.ts using @nifrajs/schema.",
-            mimeType: "application/json",
-            read: async () => ({ text: await openApiHandler({ format: "json" }, loadAppCached) }),
-        },
-        {
-            uri: "nifra://package-json",
-            name: "package.json",
-            description: "Project package metadata and scripts.",
-            mimeType: "application/json",
-            read: async () => ({ text: await readProjectFile(cwd, "package.json", 40_000) }),
-        },
-        {
-            uri: "nifra://agents-md",
-            name: "AGENTS.md",
-            description: "Repository-specific agent instructions if the project has them.",
-            mimeType: "text/markdown",
-            read: async () => ({ text: await readProjectFile(cwd, "AGENTS.md", 40_000) }),
-        },
-    ];
-}
-export function projectPrompts() {
-    return [
-        {
-            name: "nifra_new_route",
-            description: "Implement a new file route with the right routes/ filename, examples, and checks.",
-            arguments: [
-                { name: "path", description: 'URL path, e.g. "/users/:id".', required: true },
-                { name: "goal", description: "What the page should do.", required: false },
-            ],
-            handler: async (args) => promptText([
-                `Create a nifra page route for ${JSON.stringify(args.path ?? "/new-route")}.`,
-                args.goal ? `Goal: ${String(args.goal)}` : undefined,
-                'Use `nifra_context` with `{ kind: "pages" }`, then `nifra_scaffold` for the exact file path.',
-                "If the stub is not writable for this framework, call `nifra_example` for a verified page/loader example before editing.",
-                "Verify with `nifra_render` for the route and finish with `nifra_check`.",
-            ]
-                .filter(Boolean)
-                .join("\n")),
-        },
-        {
-            name: "nifra_add_endpoint",
-            description: "Add or update a backend endpoint with schemas, typed-client usage, and verification.",
-            arguments: [
-                { name: "method", description: "HTTP method.", required: true },
-                { name: "path", description: 'API path, e.g. "/users/:id".', required: true },
-                { name: "goal", description: "What the endpoint should do.", required: false },
-            ],
-            handler: async (args) => promptText([
-                `Add a nifra backend endpoint: ${String(args.method ?? "GET").toUpperCase()} ${String(args.path ?? "/api")}.`,
-                args.goal ? `Goal: ${String(args.goal)}` : undefined,
-                "Read `nifra://routes` or call `nifra_routes` first so the new route fits the existing API shape.",
-                "Use route schemas for untrusted body/query input and declare `response` when the frontend consumes the shape.",
-                "Verify behavior with `nifra_run`, then run `nifra_check` and `nifra_test` for the touched area.",
-            ]
-                .filter(Boolean)
-                .join("\n")),
-        },
-        {
-            name: "nifra_debug_drift",
-            description: "Debug frontend/backend contract drift using the typed client and checker output.",
-            arguments: [
-                { name: "symptom", description: "The error or behavior to investigate.", required: false },
-            ],
-            handler: async (args) => promptText([
-                "Debug nifra contract drift.",
-                args.symptom ? `Symptom: ${String(args.symptom)}` : undefined,
-                "Start with `nifra_check`; use each diagnostic as the source of truth.",
-                "Read `nifra://routes` for the exact typed-client calls and compact body/query/response shapes.",
-                "Prefer `client<typeof app>` over hand-rolled internal `fetch`. Verify fixed endpoints with `nifra_run`.",
-            ]
-                .filter(Boolean)
-                .join("\n")),
-        },
-    ];
-}
-export function projectFeatures(cwd, loadAppCached = createCachedAppLoader(cwd)) {
-    return { resources: projectResources(cwd, loadAppCached), prompts: projectPrompts() };
-}
-/**
- * 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.
- */
-export function resolveProjectDir(root, dir) {
-    if (dir === undefined || dir === "")
-        return root;
-    const target = resolve(root, dir);
-    let canonicalRoot;
-    try {
-        canonicalRoot = realpathSync(root);
-    }
-    catch {
-        const lexical = relative(root, target);
-        return lexical === "" || (!lexical.startsWith("..") && !isAbsolute(lexical)) ? target : null;
-    }
-    let probe = target;
-    const missing = [];
-    while (true) {
-        try {
-            const canonicalProbe = realpathSync(probe);
-            const rel = relative(canonicalRoot, canonicalProbe);
-            if (rel.startsWith("..") || isAbsolute(rel))
-                return null;
-            return missing.length === 0 ? canonicalProbe : resolve(canonicalProbe, ...missing.reverse());
-        }
-        catch {
-            const parent = resolve(probe, "..");
-            if (parent === probe)
-                return null;
-            // `basename`, not a slice past `parent`: when `parent` is the filesystem root its trailing
-            // separator is part of it, so `parent.length + 1` eats the first character of the segment and
-            // the path gets rebuilt wrong.
-            missing.push(basename(probe));
-            probe = parent;
-        }
-    }
-}
-/** Consistent error string for a `dir` that escapes the project root. */
-function dirError(dir) {
-    return JSON.stringify({ ok: false, error: `dir must be a subdirectory of the project root - "${dir}" escapes it.` }, null, 2);
-}
-/** Adapt one executable catalog spec to its MCP descriptor and project-scoped handler. */
-export function toMcpTool(source, options) {
-    const spec = "run" in source ? source : findCommandSpec(source.name);
-    if (spec === undefined)
-        throw new Error(`missing command spec for ${source.name}`);
-    const entry = "run" in source ? undefined : source;
-    const { cwd } = options;
-    const loadAppCached = options.loadAppCached ?? createCachedAppLoader(cwd);
-    return {
-        name: commandMcpName(entry?.name ?? spec.name),
-        description: entry?.summary ?? spec.summary,
-        inputSchema: entry?.inputSchema ?? spec.input.jsonSchema,
-        handler: async (args, context) => {
-            const raw = { ...args };
-            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);
-            }
-            delete raw.dir;
-            let input;
-            try {
-                input = spec.input.parse(raw);
-            }
-            catch (error) {
-                return JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }, null, 2);
-            }
-            const commandContext = {
-                cwd: target,
-                signal: context.signal,
-                progress: () => context.reportProgress?.(0.5, 1),
-                ...(target === cwd ? { loadApp: loadAppCached } : {}),
-            };
-            const output = await spec.run(input, commandContext);
-            const value = spec.json?.(output, input) ?? output;
-            return typeof value === "string" ? value : JSON.stringify(value, null, 2);
-        },
-    };
-}
-export function catalogProjectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
-    return commandCatalog
-        .filter((entry) => entry.transports.includes("mcp"))
-        .map((entry) => {
-        const spec = findCommandSpec(entry.name);
-        if (spec === undefined)
-            throw new Error(`missing command spec for ${entry.name}`);
-        return toMcpTool(spec, { cwd, loadAppCached });
-    });
-}
-export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
-    const warmRun = createWarmHandler("mcp-run", cwd, "run");
-    const warmRender = createWarmHandler("mcp-render", cwd, "render");
-    const catalogTools = catalogProjectTools(cwd, () => loadAppCached());
-    const legacyTools = [
-        {
-            name: "nifra_contract_proof",
-            description: "Compare the current route contract with its snapshot and join each changed route to its route-assurance and capability evidence. Returns hasBreaking as the gate. The typed-contract check is lazy and runs only when check is true.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    baseline: {
-                        type: "string",
-                        description: "Snapshot path relative to the selected project directory. Defaults to api-snapshot.json.",
-                    },
-                    check: {
-                        type: "boolean",
-                        description: "Also run the typed-contract check. Default false to keep the diff lazy.",
-                    },
-                    dir: {
-                        type: "string",
-                        description: "Project subdirectory to inspect.",
-                    },
-                },
-                additionalProperties: false,
-            },
-            handler: async (args) => {
-                const raw = args;
-                if (raw.dir !== undefined && typeof raw.dir !== "string") {
-                    return JSON.stringify({ ok: false, error: "dir must be a string" }, null, 2);
-                }
-                if (raw.baseline !== undefined && typeof raw.baseline !== "string") {
-                    return JSON.stringify({ ok: false, error: "baseline must be a string" }, null, 2);
-                }
-                const dir = raw.dir;
-                const baseline = raw.baseline;
-                const target = resolveProjectDir(cwd, dir);
-                if (target === null)
-                    return dirError(dir);
-                if (baseline !== undefined && baseline.trim() === "") {
-                    return JSON.stringify({ ok: false, error: "baseline must not be empty" }, null, 2);
-                }
-                try {
-                    return JSON.stringify(await collectContractProof(target, {
-                        ...(baseline === undefined ? {} : { baselinePath: baseline }),
-                        ...(raw.check === undefined ? {} : { check: raw.check === true }),
-                    }), null, 2);
-                }
-                catch (error) {
-                    return JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }, null, 2);
-                }
-            },
-        },
-        {
-            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;
-                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;
-                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_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.',
-            inputSchema: {
-                type: "object",
-                properties: {
-                    format: {
-                        type: "string",
-                        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,
-            },
-            handler: (args) => openApiHandler(args, loadAppCached),
-        },
-        {
-            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? }.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    requests: {
-                        type: "array",
-                        items: {
-                            type: "object",
-                            properties: {
-                                method: { type: "string" },
-                                path: { type: "string" },
-                                body: {},
-                                headers: { type: "object" },
-                            },
-                            required: ["path"],
-                        },
-                    },
-                    entry: {
-                        type: "string",
-                        description: "Backend entry file (default: backend.ts | app.ts).",
-                    },
-                    warm: {
-                        type: "boolean",
-                        description: "Reuse a hot backend worker while source files are unchanged. Default false for maximum isolation.",
-                    },
-                },
-                required: ["requests"],
-                additionalProperties: false,
-            },
-            handler: (args, context) => runHandler(cwd, args, context, warmRun),
-        },
-        {
-            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? }. 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: {
-                    requests: {
-                        type: "array",
-                        items: {
-                            type: "object",
-                            properties: {
-                                path: { type: "string" },
-                                headers: { type: "object" },
-                            },
-                            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, warmRender),
-        },
-        {
-            name: "nifra_ws",
-            description: 'Verify a WebSocket route against this project by starting the backend on an ephemeral localhost port, opening a real Bun WebSocket, sending string frames, and returning structured evidence: { ok, opened, sent, received, close?, error? }. Use after adding or editing app.ws() routes. Pass path including query, e.g. "/chat?token=secret". By default expects one message when no messages are sent, or one response per sent message; set expectMessages:0 to verify connect-only routes.',
-            inputSchema: {
-                type: "object",
-                properties: {
-                    path: {
-                        type: "string",
-                        description: 'App-local WebSocket path, optionally with query, e.g. "/chat?token=secret".',
-                    },
-                    messages: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "String frames to send after the socket opens (max 50).",
-                    },
-                    expectMessages: {
-                        type: "number",
-                        description: "How many inbound messages must be observed before success (default: messages.length, or 1 with no sent messages; max 50).",
-                    },
-                    timeoutMs: {
-                        type: "number",
-                        description: "Bounded verification timeout in milliseconds (default 3000, max 30000).",
-                    },
-                    entry: {
-                        type: "string",
-                        description: "Backend entry file (default: backend.ts | app.ts).",
-                    },
-                },
-                required: ["path"],
-                additionalProperties: false,
-            },
-            handler: (args, context) => wsHandler(cwd, args, context),
-        },
-        {
-            name: "nifra_test",
-            description: "Run `bun test` for this project and return bounded structured results: { ok, command, durationMs, exitCode, timedOut, summary, stdout, stderr }. Pass `pattern` to narrow to a test file/path; pass `timeoutMs` (default 30000, max 300000). Use after editing code, alongside nifra_run/nifra_render for behavioral checks.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    pattern: {
-                        type: "string",
-                        description: "Optional test file/path pattern passed as an argv item to `bun test`.",
-                    },
-                    timeoutMs: {
-                        type: "number",
-                        description: "Timeout in milliseconds (default 30000, max 300000).",
-                    },
-                    dir: {
-                        type: "string",
-                        description: 'Run the tests in this subdirectory (relative to the project root), e.g. "app". Use it when the MCP server\'s root is a monorepo but you want to test just one app. Default: the project root.',
-                    },
-                },
-                additionalProperties: false,
-            },
-            handler: async (args, context) => {
-                const { collectTestResult } = await import("./test-tool.js");
-                const opts = args;
-                const target = resolveProjectDir(cwd, opts.dir);
-                if (target === null)
-                    return dirError(opts.dir);
-                return JSON.stringify(await collectTestResult(target, args, { signal: context.signal }), null, 2);
-            },
-        },
-        // nifra_docs + nifra_example are project-independent (corpus-backed); the shared factory keeps their
-        // definitions identical to the CLI HTTP server and the site's edge worker.
-        ...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).',
-            inputSchema: {
-                type: "object",
-                properties: {
-                    path: {
-                        type: "string",
-                        description: 'The URL path for the new page route, e.g. "/users/:id" or "/blog/*slug".',
-                    },
-                    write: {
-                        type: "boolean",
-                        description: "When true, create the file if a verified ready-to-write stub exists. Refuses overwrite.",
-                    },
-                },
-                required: ["path"],
-                additionalProperties: false,
-            },
-            handler: async (args) => {
-                const { path, write } = args;
-                if (typeof path !== "string" || path.length === 0)
-                    return "scaffold: `path` is required.";
-                const { frameworkFromClientModule, renderScaffold, writeScaffoldRoute } = await import("./scaffold.js");
-                const app = await loadAppCached();
-                const framework = frameworkFromClientModule(app.framework.clientModule);
-                if (write !== true)
-                    return renderScaffold(path, framework);
-                const result = await writeScaffoldRoute(cwd, path, framework);
-                const status = result.written
-                    ? `Written: \`${result.file}\``
-                    : `Not written: ${result.reason ?? "no write performed"}`;
-                return `${status}\n\n${renderScaffold(path, framework)}`;
-            },
-        },
-        {
-            name: "nifra_hydrate",
-            description: "Run the hydration assurance gate and return stable NF-H diagnostics.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    dir: { type: "string", description: "Project subdirectory to inspect." },
-                    interact: { type: "boolean", description: "Run declared hydration probes." },
-                },
-                additionalProperties: false,
-            },
-            handler: async (args) => {
-                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 [...catalogTools, ...legacyTools];
-}
-/** Extract tools registered via .tool() routes on the Nifra backend. Exported for the test that proves a
- * `server().tool()` route surfaces in `tools/list` and executes through `tools/call`. */
-export function extractBackendTools(backend) {
-    const b = backend;
-    if (!b || typeof b.routes !== "function")
-        return [];
-    const routes = reflectRoutes(b);
-    return routes
-        .filter((r) => r.schema !== undefined && r.tool !== undefined)
-        .map((r) => {
-        const toolInfo = r.tool;
-        const s = r.schema;
-        return {
-            name: toolInfo.name,
-            description: toolInfo.description,
-            inputSchema: (s.body?.jsonSchema ?? {
-                type: "object",
-                properties: {},
-            }),
-            ...(toolInfo.annotations !== undefined ? { annotations: toolInfo.annotations } : {}),
-            handler: async (args) => {
-                const res = await b.fetch(new Request(`http://localhost/_nifra/tool/${toolInfo.name}`, {
-                    method: "POST",
-                    headers: { "content-type": "application/json" },
-                    body: JSON.stringify(args),
-                }));
-                if (!res.ok) {
-                    const text = await res.text();
-                    throw new Error(`Tool execution failed (${res.status}): ${text}`);
-                }
-                const body = await res.json();
-                if (typeof body === "string")
-                    return body;
-                if (body && typeof body === "object") {
-                    if ("content" in body || "structuredContent" in body) {
-                        return body;
-                    }
-                    return {
-                        content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
-                        structuredContent: body,
-                    };
-                }
-                return String(body);
-            },
-        };
-    });
-}
-/** Extract MCP resources registered via `.resource()` on the Nifra backend. Exported for the surfacing test. */
-export function extractBackendResources(backend) {
-    const b = backend;
-    if (!b || typeof b.mcpResources !== "function")
-        return [];
-    let list;
-    try {
-        list = b.mcpResources();
-    }
-    catch {
-        return [];
-    }
-    return list.map((r) => ({
-        uri: r.uri,
-        name: r.name,
-        ...(r.description !== undefined ? { description: r.description } : {}),
-        ...(r.mimeType !== undefined ? { mimeType: r.mimeType } : {}),
-        read: async () => {
-            const out = await r.read();
-            if (typeof out === "string")
-                return { text: out };
-            const o = out;
-            return o.mimeType !== undefined ? { text: o.text, mimeType: o.mimeType } : { text: o.text };
-        },
-    }));
-}
-/** Extract MCP prompts registered via `.prompt()` on the Nifra backend. Exported for the surfacing test. */
-export function extractBackendPrompts(backend) {
-    const b = backend;
-    if (!b || typeof b.mcpPrompts !== "function")
-        return [];
-    let list;
-    try {
-        list = b.mcpPrompts();
-    }
-    catch {
-        return [];
-    }
-    return list.map((p) => ({
-        name: p.name,
-        description: p.description,
-        ...(p.arguments !== undefined ? { arguments: p.arguments } : {}),
-        handler: async (args) => (await p.handler(args)),
-    }));
-}
-/** Prefix every tool name and resource URI for a named app in a monorepo. */
-function namespaceForApp(name, tools, features) {
-    const prefix = `nifra_${name}_`;
-    const namespacedTools = tools.map((t) => ({
-        ...t,
-        name: t.name.startsWith("nifra_") ? t.name.replace(/^nifra_/, prefix) : `${name}_${t.name}`,
-    }));
-    const namespacedResources = (features.resources ?? []).map((r) => ({
-        ...r,
-        uri: r.uri.replace(/^nifra:\/\//, `nifra://${name}/`),
-    }));
-    const namespacedPrompts = (features.prompts ?? []).map((p) => ({
-        ...p,
-        name: p.name.replace(/^nifra_/, prefix),
-    }));
-    return {
-        tools: namespacedTools,
-        features: { resources: namespacedResources, prompts: namespacedPrompts },
-    };
-}
-/**
- * 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.
- */
+export { extractBackendPrompts, extractBackendResources, extractBackendTools, } from "./mcp-reflect.js";
+import { applyClientRoots, clientSupportsRoots, detectToolingDrift, driftNote, guardTools, pathsFromRootsResult, resolveRootState, rootInstructions, rootVerdict, } from "./mcp-root.js";
+export { CHILD_OUTPUT_MAX_BYTES, CHILD_TIMEOUT_MS, LOCAL_TOOL_FETCH_TIMEOUT_MS, LOCAL_TOOL_MAX_RESPONSE_BYTES, notNifraResponse, readBoundedResponse, readBoundedStream, timeoutMessage, validateLocalPort, } from "./mcp-io.js";
+export { clientSupportsRoots, guardTools } from "./mcp-root.js";
+import { createCachedAppLoader, projectTools } from "./mcp-exec.js";
+export { catalogProjectTools, createCachedAppLoader, createWarmHandler, projectTools, renderHandler, runHandler, spawnChild, toMcpTool, WarmWorker, wsHandler, } from "./mcp-exec.js";
+import { namespaceForApp, projectFeatures } from "./mcp-context.js";
+export { dirError, namespaceForApp, projectFeatures, projectPrompts, projectResources, resolveProjectDir, } from "./mcp-context.js";
 async function backendFeatures(loader, base) {
     const resources = [...(base.resources ?? [])];
     const prompts = [...(base.prompts ?? [])];
@@ -1251,12 +80,6 @@ async function appDeclaredTools(loader) {
         return [];
     }
 }
-/** Tool names that never touch the project - they serve the bundled docs/examples/types corpus, so
- * they stay available (and unstamped) whatever the root state is. */
-const PROJECT_FREE_TOOLS = new Set(["nifra_docs", "nifra_example", "nifra_types", "nifra_learn"]);
-/** The id of this server's own `roots/list` request to the client. A fixed, namespaced string: the
- * server only ever has one roots request in flight, and no response to a CLIENT-initiated request can
- * carry it (clients pick their own ids; this one is recognisably ours). */
 const ROOTS_REQUEST_ID = "nifra:roots/list";
 async function createProjectContext(root) {
     const monorepo = await detectMonorepo(root);
@@ -1283,50 +106,11 @@ async function createProjectContext(root) {
         loadAppCached,
     };
 }
-/**
- * Wrap every project-scoped tool with the root guard: a bad root ({@link rootVerdict} `blocked`) makes
- * the tool refuse with the remediation message instead of answering about whatever directory the
- * server happened to start in; a good root stamps the result with `[nifra] project root: …` so the
- * agent (and the human reading its transcript) can see WHICH project answered. Docs tools pass
- * through untouched - they serve the bundled corpus, not the project.
- */
-export function guardTools(tools, verdict) {
-    return tools.map((tool) => {
-        if (PROJECT_FREE_TOOLS.has(tool.name))
-            return tool;
-        return {
-            ...tool,
-            handler: async (args, context) => {
-                if (verdict.blocked !== undefined) {
-                    return { content: [{ type: "text", text: verdict.blocked }], isError: true };
-                }
-                const result = await tool.handler(args, context);
-                const note = { type: "text", text: verdict.note };
-                if (typeof result === "string") {
-                    return { content: [{ type: "text", text: result }, note] };
-                }
-                return { ...result, content: [...(result.content ?? []), note] };
-            },
-        };
-    });
-}
-/** Whether the client's `initialize` params declare the `roots` capability - the precondition for
- * this server sending it a `roots/list` request. */
-export function clientSupportsRoots(params) {
-    const capabilities = params?.capabilities;
-    if (typeof capabilities !== "object" || capabilities === null)
-        return false;
-    const roots = capabilities.roots;
-    return typeof roots === "object" && roots !== null;
-}
 /**
  * Run the stdio MCP server: read newline-delimited JSON-RPC from stdin, write responses to stdout.
  *
- * The project root is resolved defensively rather than assumed (`./mcp-root.ts`): explicit
- * `nifra mcp <dir>` beats a cwd guess, a cwd guess walks up to the nearest nifra marker, the client's
- * MCP `roots` (requested after the handshake, re-requested on `roots/list_changed`) can correct an
- * unambiguous wrong guess, and anything still unresolved fails closed per tool call. The effective
- * root is announced in the `initialize` instructions and stamped on every project tool result.
+ * Root resolution, trust, and project-tool execution are delegated to their own seams; this function
+ * owns only the stdio lifecycle and JSON-RPC dispatch loop.
  */
 export async function runMcpServer(cwd, version, explicitDir) {
     const requested = explicitDir !== undefined ? resolve(cwd, explicitDir) : cwd;
@@ -1335,9 +119,6 @@ export async function runMcpServer(cwd, version, explicitDir) {
     }
     let rootState = await resolveRootState(requested, explicitDir !== undefined);
     let ctx = await createProjectContext(rootState.root);
-    // The CLI answering may not be the nifra the project builds with (a globally installed server, a
-    // stale agent config). Recomputed whenever the root moves, since a different project can install a
-    // different version.
     let drift = await detectToolingDrift(rootState.root, version);
     const serverInfo = { name: "nifra", version };
     const state = createMcpProtocolState();