@nifrajs/cli 2.14.1 → 3.2.0

package/dist/mcp-context.js

@@ -0,0 +1,215 @@
+/**
+ * Project context and trust-local utilities for the MCP server.
+ *
+ * Resources, prompts, path scoping, and monorepo namespacing are independent of the JSON-RPC loop and
+ * of backend reflection. App loading is injected through the shared cached loader seam.
+ */
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { createCachedAppLoader } from "./mcp-exec.js";
+function openApiFormat(args) {
+    const format = args.format;
+    return format === "yaml" ? "yaml" : "json";
+}
+export async function openApiHandler(args, loadAppCached) {
+    const { renderOpenApiWithTypes } = await import("./openapi-tool.js");
+    const pathPrefix = typeof args.path === "string" ? args.path : undefined;
+    return renderOpenApiWithTypes(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. */
+export 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 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.
+ */
+//# sourceMappingURL=mcp-context.js.map

package/dist/mcp-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-context.js","sourceRoot":"","sources":["../src/mcp-context.ts"],"names":[],"mappings":"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"}

package/dist/mcp-docs-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-docs-tools.d.ts","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,OAAO,EAAwB,MAAM,eAAe,CAAA;AAElE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAKrE,yFAAyF;AACzF,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,EAC3C,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,EAClD,SAAS,EAAE,MAAM,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,GAChD,OAAO,EAAE,CA+HX"}
+{"version":3,"file":"mcp-docs-tools.d.ts","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,KAAK,OAAO,EAAwB,MAAM,eAAe,CAAA;AAGlE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAKrE,yFAAyF;AACzF,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,EAC3C,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,EAClD,SAAS,EAAE,MAAM,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,GAChD,OAAO,EAAE,CAmKX"}

package/dist/mcp-docs-tools.js

@@ -8,6 +8,7 @@
  */
 import { renderDocsResult } from "./docs-search.js";
 import { renderExamplesResult } from "./examples.js";
+import { renderFrontendResult } from "./frontend-guidance.js";
 import { renderLearnResult } from "./learn.js";
 import { renderTypesResult } from "./types-search.js";
 const clamp = (n, lo, hi, dflt) => Math.min(Math.max(typeof n === "number" ? n : dflt, lo), hi);
@@ -126,6 +127,36 @@ export function docsTools(loadDocs, loadExamples, loadTypes) {
             },
             handler: async (args) => renderLearnResult(args.step),
         },
+        {
+            name: "nifra_frontend",
+            annotations: {
+                title: "Frontend footgun guidance",
+                readOnlyHint: true,
+                openWorldHint: false,
+            },
+            description: 'Diagnose a CLIENT-SIDE nifra problem by symptom, across every adapter (React/Preact/Solid/Vue/Svelte/vanilla). Returns the cause, the concrete fix, and how to verify it. Covers the nifra SEAM (a server-only import leaking into a client component, a hydration mismatch, a duplicated framework runtime, loader-data typing) - where it points at the nifra_* tool that fixes and checks it - and the per-framework reactivity-loss idioms (Vue ref, Solid props, Svelte runes, React effect deps), where it points at that framework\'s own ESLint plugin. Call with no args for the index; pass `symptom` (e.g. "hydration mismatch", "value stopped updating") and/or `adapter` to filter. Use this when a rendered page misbehaves and nifra_check is green (check owns the static seam; this owns the rest).',
+            inputSchema: {
+                type: "object",
+                properties: {
+                    symptom: {
+                        type: "string",
+                        maxLength: 256,
+                        description: "What you observe (omit for the index).",
+                    },
+                    adapter: {
+                        type: "string",
+                        enum: ["react", "preact", "solid", "vue", "svelte", "vanilla"],
+                        description: "Filter to one adapter's entries (plus the adapter-independent seam entries).",
+                    },
+                    limit: { type: "number", description: "Max entries to return (default 3, max 5)." },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const { symptom, adapter, limit } = args;
+                return renderFrontendResult({ symptom, adapter, limit: clamp(limit, 1, 5, 3) });
+            },
+        },
     ];
 }
 //# sourceMappingURL=mcp-docs-tools.js.map

package/dist/mcp-docs-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-docs-tools.js","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp-docs-tools.js","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"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"}

package/dist/mcp-exec.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared project-tool execution for stdio, run, and render.
+ *
+ * This module owns child-process limits, warm-worker lifecycle, source fingerprinting, and cached app
+ * loading. It has no JSON-RPC transport or root-trust policy, so those seams remain independently
+ * replaceable.
+ */
+import { type CommandCatalogEntry, type CommandSpec } from "./command-catalog.js";
+import type { LoadAppOptions, LoadedApp } from "./load.js";
+import { type CommandMcpToolOptions } from "./mcp-context.js";
+import type { McpTool, McpToolContext } from "./mcp-protocol.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. */
+export declare function toMcpTool(source: CommandSpec<unknown, unknown> | CommandCatalogEntry, options: CommandMcpToolOptions): McpTool;
+export declare function catalogProjectTools(cwd: string, loadAppCached?: () => Promise<LoadedApp>): McpTool[];
+export declare function projectTools(cwd: string, loadAppCached?: (outDirName?: string) => Promise<LoadedApp>): McpTool[];
+/** 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.
+ */
+export declare function spawnChild(child: "mcp-run" | "mcp-render" | "mcp-ws", cwd: string, input: unknown, label: string, signal?: AbortSignal): Promise<string>;
+/** 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 declare class WarmWorker {
+    readonly fingerprint: string;
+    private readonly label;
+    private readonly proc;
+    private readonly pending;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private nextId;
+    private closed;
+    constructor(child: "mcp-run" | "mcp-render", cwd: string, fingerprint: string, label: string);
+    stop(): void;
+    request(input: unknown, signal?: AbortSignal): Promise<string>;
+    private readStdout;
+    private readStderr;
+    private handleLine;
+}
+/** 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. */
+export declare function createWarmHandler(child: "mcp-run" | "mcp-render", cwd: string, label: string): (input: unknown, signal?: AbortSignal) => Promise<string>;
+/** The `nifra_run` handler: run requests through the project's CURRENT backend, return structured results. */
+export declare function runHandler(cwd: string, args: Record<string, unknown>, context: McpToolContext, warmRun: (input: unknown, signal?: AbortSignal) => Promise<string>): Promise<string>;
+/** 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. */
+export declare function renderHandler(cwd: string, args: Record<string, unknown>, context: McpToolContext, warmRender: (input: unknown, signal?: AbortSignal) => Promise<string>): Promise<string>;
+/** The `nifra_ws` handler: verify WebSocket routes through a fresh app subprocess. */
+export declare function wsHandler(cwd: string, args: Record<string, unknown>, context: McpToolContext): Promise<string>;
+type LoadAppForCache = (cwd: string, outDirName?: string, options?: LoadAppOptions) => Promise<LoadedApp>;
+export interface CachedAppLoaderOptions {
+    readonly loadApp?: LoadAppForCache;
+    readonly fingerprint?: (cwd: string) => Promise<string>;
+}
+/** Cache LoadedApp inside one MCP server process, invalidating when config/backend mtimes change. */
+export declare function createCachedAppLoader(cwd: string, options?: CachedAppLoaderOptions): (outDirName?: string) => Promise<LoadedApp>;
+export {};
+//# sourceMappingURL=mcp-exec.d.ts.map

package/dist/mcp-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-exec.d.ts","sourceRoot":"","sources":["../src/mcp-exec.ts"],"names":[],"mappings":"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"}