@nifrajs/cli 0.1.0-alpha.1

package/dist/introspect.js

@@ -0,0 +1,243 @@
+/**
+ * Introspect a loaded nifra project into a Markdown brief — the API routes (`backend.routes()`), the
+ * page routes (`discoverRoutes`), and a conventions summary — for piping into an AI coding agent's
+ * prompt. Used by `nifra context` (stdout) and the `nifra mcp` server (a tool result), so an agent sees
+ * *this* project's actual surface, not just generic docs.
+ */
+import { discoverRoutes } from "@nifrajs/web/fs";
+/** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
+function backendRoutes(backend) {
+    if (backend && typeof backend.routes === "function") {
+        try {
+            return backend.routes();
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+/** The JSON Schema a `t`/Standard Schema carries (nifra's `t` is TypeBox-backed and exposes `.jsonSchema`),
+ * or `undefined` for a validator that doesn't expose one. This is the exact field-level contract. */
+function jsonSchemaOf(schema) {
+    if (schema && typeof schema === "object" && "jsonSchema" in schema) {
+        const js = schema.jsonSchema;
+        if (js !== undefined && js !== null)
+            return js;
+    }
+    return undefined;
+}
+/**
+ * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the
+ * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).
+ * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output
+ * is always faithful, just not always minimal.
+ */
+export function tsTypeOf(schema, depth = 0) {
+    if (typeof schema !== "object" || schema === null || depth > 6)
+        return JSON.stringify(schema);
+    const node = schema;
+    const union = (node.anyOf ?? node.oneOf);
+    if (Array.isArray(union))
+        return union.map((u) => tsTypeOf(u, depth + 1)).join(" | ");
+    if (Array.isArray(node.enum))
+        return node.enum.map((v) => JSON.stringify(v)).join(" | ");
+    if (node.const !== undefined)
+        return JSON.stringify(node.const);
+    switch (node.type) {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array": {
+            const item = tsTypeOf(node.items, depth + 1);
+            // Parenthesize unions so `(A | B)[]` reads as the array it is.
+            return item.includes(" | ") ? `(${item})[]` : `${item}[]`;
+        }
+        case "object": {
+            const props = node.properties;
+            if (props === undefined) {
+                return node.additionalProperties === undefined || node.additionalProperties === false
+                    ? "{}"
+                    : `Record<string, ${node.additionalProperties === true ? "unknown" : tsTypeOf(node.additionalProperties, depth + 1)}>`;
+            }
+            const required = new Set(Array.isArray(node.required) ? node.required : []);
+            const fields = Object.entries(props).map(([key, value]) => `${key}${required.has(key) ? "" : "?"}: ${tsTypeOf(value, depth + 1)}`);
+            return `{ ${fields.join(", ")} }`;
+        }
+        default:
+            return JSON.stringify(schema);
+    }
+}
+/** One route's request/response field shapes, indented under its line. Reads the declared schemas off the
+ * descriptor so an agent gets the exact input + output contract — not just "this route is validated". */
+function schemaLines(schema) {
+    const s = schema;
+    if (!s)
+        return [];
+    const out = [];
+    for (const key of ["query", "body", "response"]) {
+        const declared = s[key];
+        if (!declared)
+            continue;
+        const js = jsonSchemaOf(declared);
+        out.push(js
+            ? `    - ${key}: \`${tsTypeOf(js)}\``
+            : `    - ${key}: _(validated; shape not introspectable from this validator)_`);
+    }
+    return out;
+}
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * The typed-client call form for a route — the exact `client<typeof app>` proxy chain an agent should
+ * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
+ * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
+ * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
+ * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first —
+ * so the `{ query }` argument lands in the right slot for each.
+ */
+export function clientCall(method, path, schema) {
+    const s = schema;
+    const verb = method.toLowerCase();
+    const segs = path.split("/").filter((seg) => seg !== "");
+    let chain = "api";
+    if (segs.length === 0)
+        chain += ".index";
+    else
+        for (const seg of segs) {
+            if (seg.startsWith(":") || seg.startsWith("*")) {
+                const name = seg.replace(/^[:*]/, "") || "value";
+                chain += `({ ${name} })`;
+            }
+            else
+                chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`;
+        }
+    const isBodyVerb = verb === "post" || verb === "put" || verb === "patch";
+    let call;
+    if (isBodyVerb) {
+        // body is the 1st arg; if a route has a query but no body, the body slot must still be filled.
+        const bodyArg = s?.body ? "body" : s?.query ? "undefined" : "";
+        const opts = s?.query ? (bodyArg ? ", { query }" : "{ query }") : "";
+        call = `.${verb}(${bodyArg}${opts})`;
+    }
+    else {
+        call = `.${verb}(${s?.query ? "{ query }" : ""})`;
+    }
+    return `await ${chain}${call}`;
+}
+/** Markdown section listing the backend's API routes with their request + response field shapes. */
+export function apiRoutesSection(routes) {
+    if (routes.length === 0) {
+        return "## API routes\n\nNo `backend.ts` server routes found (this app may be frontend-only).";
+    }
+    const lines = [...routes]
+        .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+        .flatMap((r) => [
+        `- \`${r.method} ${r.path}\``,
+        ...schemaLines(r.schema),
+        `    - call: \`${clientCall(r.method, r.path, r.schema)}\` → \`{ ok, status, data, error }\``,
+    ]);
+    return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract — the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`;
+}
+/** Markdown section listing the file-routed pages (URL pattern → source file). */
+export function pageRoutesSection(manifest) {
+    if (!manifest || manifest.routes.length === 0) {
+        return "## Page routes\n\nNo file routes found under `routes/`.";
+    }
+    const lines = [...manifest.routes]
+        .sort((a, b) => a.pattern.localeCompare(b.pattern))
+        .map((r) => `- \`${r.pattern}\` → \`${r.file}\``);
+    return `## Page routes (routes/)\n\n${lines.join("\n")}`;
+}
+const CONVENTIONS = `## Conventions (summary)
+
+- **Backend:** \`server()\` from \`@nifrajs/core\`; returning a value sends JSON. Validate untrusted input with
+  a route schema (\`{ body, query, params }\` using \`t\` from \`@nifrajs/schema\` or any Standard Schema) and read
+  the typed \`c.body\` / \`c.query\` / \`c.params\` — never hand-parse.
+- **Response contract (no drift):** declare \`{ response: t.object({...}) }\` on a route to lock its output
+  shape — the handler is type-checked against it and the client sees exactly that shape. The contract above
+  is the single source of truth for both sides.
+- **Client — ALWAYS use this for API calls:** \`client<typeof app>(url)\` derives request inputs AND
+  \`res.data\` from the backend's route types, so the compiler catches any frontend/backend drift. Never
+  hand-roll \`fetch\` + ad-hoc response types for an internal API — that's exactly how screens drift. It
+  never throws: branch on \`res.ok ? res.data : res.error\`.
+- **Pages:** file-routed under \`routes/\`; \`loader\`/\`action\` are server-only but the module is also bundled
+  for the browser — **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
+  file; reach it via \`ctx.api\` / \`ctx.env\`.
+- \`app.fetch(Request)\` is the universal entry. Full reference: this repo's \`AGENTS.md\`, or \`llms-full.txt\`.`;
+/** Build the project brief (API routes + page routes + conventions) as Markdown — optionally
+ * narrowed by {@link ContextFilter} for cheap follow-up calls. */
+export function describeProject(app, filter) {
+    let manifest;
+    try {
+        manifest = discoverRoutes(app.routesDir);
+    }
+    catch {
+        // No (or unreadable) routes/ — the page-routes section reports that.
+    }
+    const prefix = filter?.path;
+    let routes = backendRoutes(app.backend);
+    let pages = manifest;
+    if (prefix !== undefined && prefix !== "") {
+        routes = routes.filter((r) => r.path.startsWith(prefix));
+        if (manifest !== undefined) {
+            pages = { ...manifest, routes: manifest.routes.filter((r) => r.pattern.startsWith(prefix)) };
+        }
+    }
+    const narrowed = filter?.kind !== undefined || (prefix !== undefined && prefix !== "");
+    const sections = [`# nifra project: ${app.cwd.slice(app.cwd.lastIndexOf("/") + 1)}`];
+    if (!narrowed) {
+        sections.push("A full-stack nifra app — Web-standard, one app on Bun, Node, Deno, and the edge.", 
+        // Point agents at the verified surface, not recalled APIs — nifra is young, so training data is the
+        // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
+        "> **Build against THIS surface + the verified tools — do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.");
+    }
+    if (filter?.kind !== "pages")
+        sections.push(apiRoutesSection(routes));
+    if (filter?.kind !== "api")
+        sections.push(pageRoutesSection(pages));
+    if (!narrowed)
+        sections.push(CONVENTIONS);
+    return sections.join("\n\n");
+}
+/**
+ * The backend's API routes as structured JSON — what the `nifra_routes` MCP tool returns, so an agent
+ * consumes the contract programmatically (`list_routes` / `get_route_schema`) instead of parsing the
+ * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
+ * same `call` form and TS-shaped contracts the Markdown brief shows.
+ */
+export function routesToJson(app, pathPrefix) {
+    const shape = (v) => {
+        if (!v)
+            return undefined;
+        const js = jsonSchemaOf(v);
+        return js ? tsTypeOf(js) : "(validated; shape not introspectable from this validator)";
+    };
+    let routes = backendRoutes(app.backend);
+    if (pathPrefix !== undefined && pathPrefix !== "") {
+        routes = routes.filter((r) => r.path.startsWith(pathPrefix));
+    }
+    return [...routes]
+        .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
+        .map((r) => {
+        const s = r.schema;
+        const body = shape(s?.body);
+        const query = shape(s?.query);
+        const response = shape(s?.response);
+        // Spread only the shapes that exist, so an unschematized route has no body/query/response key.
+        return {
+            method: r.method,
+            path: r.path,
+            call: clientCall(r.method, r.path, r.schema),
+            ...(body !== undefined && { body }),
+            ...(query !== undefined && { query }),
+            ...(response !== undefined && { response }),
+        };
+    });
+}
+//# sourceMappingURL=introspect.js.map

package/dist/introspect.js.map

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

package/dist/load.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A plugin list — either an array, or a **thunk** that returns one (optionally async). Both forms are
+ * accepted; {@link resolvePlugins} normalizes them. The thunk is just a convenience for deferring a
+ * plugin's construction — it does NOT make a plugin edge-safe (Bun.build follows a dynamic `import()`
+ * even from an unused export, so a Vite/compiler import in an edge-bundled file fails regardless). Edge
+ * safety comes from WHERE the config lives: keep these fields in `nifra.config.ts` (CLI-only), not in
+ * the edge-imported `framework.ts`. See the module header.
+ */
+export type PluginsField = readonly unknown[] | (() => readonly unknown[] | Promise<readonly unknown[]>);
+/**
+ * The CLI's framework wiring — exported from `nifra.config.ts` (or `framework.ts` as a fallback).
+ * `create-nifra` generates it. Only `adapter` + `clientModule` are required; the plugin/condition
+ * fields are framework-specific extras (Vue/Svelte/Solid need them; React/Preact don't).
+ */
+export interface NifraFramework {
+    /** The render adapter, e.g. `reactAdapter` from `@nifrajs/web-react`. */
+    readonly adapter: unknown;
+    /** The client runtime module providing `mountRouter`, e.g. `"@nifrajs/web-react/client"`. */
+    readonly clientModule: string;
+    /** Vite plugins for `nifra dev`'s HMR, e.g. `[react()]` / `() => import("@vitejs/plugin-vue")…`. */
+    readonly vitePlugins?: PluginsField;
+    /** Bun build plugins that compile routes for the CLIENT bundle (`nifra build`), e.g.
+     * `[vueBunPlugin("dom")]`. React/Preact JSX is Bun-native → none. */
+    readonly clientPlugins?: PluginsField;
+    /** Bun runtime plugins that compile routes for SSR — `nifra dev` (Bun-native route import) and
+     * `nifra start` register them via `Bun.plugin`, e.g. `[vueBunPlugin("ssr")]`. React/Preact → none. */
+    readonly serverPlugins?: PluginsField;
+    /** Extra Bun.build / Vite resolve conditions, e.g. Solid's `["solid"]`. */
+    readonly conditions?: readonly string[];
+    /** Compile-time `define` replacements, e.g. Vue's `__VUE_*` flags. */
+    readonly define?: Readonly<Record<string, string>>;
+}
+/** Normalize a {@link PluginsField} (array | thunk | undefined) to a fresh array, awaiting a thunk. */
+export declare function resolvePlugins(field: PluginsField | undefined): Promise<unknown[]>;
+export interface LoadedApp {
+    readonly cwd: string;
+    readonly routesDir: string;
+    /** Build output dir (also where `nifra start` reads `manifest.json` + serves `/assets/*`). */
+    readonly outDir: string;
+    readonly framework: NifraFramework;
+    /** The `backend` export from `backend.ts`, or `undefined` if there's no `backend.ts`. */
+    readonly backend: unknown;
+}
+export interface LoadAppOptions {
+    /** Optional dynamic-import query used by long-lived MCP processes to bust Bun's module cache. */
+    readonly importQuery?: string;
+}
+/** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back to
+ * `framework.ts`. Throws a clear, actionable error if neither exists or the config is malformed. */
+export declare function loadApp(cwd: string, outDirName?: string, options?: LoadAppOptions): Promise<LoadedApp>;
+//# sourceMappingURL=load.d.ts.map

package/dist/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAiBA;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,OAAO,EAAE,GAClB,CAAC,MAAM,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC,CAAA;AAE5D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,6FAA6F;IAC7F,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,oGAAoG;IACpG,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,CAAA;IACnC;yEACqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,YAAY,CAAA;IACrC;0GACsG;IACtG,QAAQ,CAAC,aAAa,CAAC,EAAE,YAAY,CAAA;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACnD;AAED,uGAAuG;AACvG,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAGxF;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAOD;oGACoG;AACpG,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,UAAU,SAAS,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,SAAS,CAAC,CA2CpB"}

package/dist/load.js

@@ -0,0 +1,70 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Zero-config app discovery. The CLI reads a few conventions from the project root:
+ *   - `routes/`         — the file-based routes (per `@nifrajs/web/fs`).
+ *   - `nifra.config.ts`  — the CLI's framework wiring (see {@link NifraFramework}); `framework.ts` is
+ *                         used as a fallback. One of the two is required.
+ *   - `backend.ts`      — exports `backend` (a `@nifrajs/core` server, the contract). Optional.
+ *
+ * Why two filenames: a multi-target app's edge entry (`_worker.ts`) imports `framework.ts` for the
+ * render adapter, so `framework.ts` must stay edge-bundlable — it can't reference Vite plugins or the
+ * SFC compiler (Bun would pull them into the `target:"browser"` worker and fail on `child_process`).
+ * `nifra.config.ts` holds that build/dev tooling instead: it's imported ONLY by this CLI (which runs on
+ * Bun), so its Vite plugin + SFC-compiler imports (`@vitejs/plugin-vue`, `@nifrajs/web-vue/plugin`) never
+ * reach the edge bundle. A simple single-target app with no edge build can put it all in `framework.ts`.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+/** Normalize a {@link PluginsField} (array | thunk | undefined) to a fresh array, awaiting a thunk. */
+export async function resolvePlugins(field) {
+    const value = typeof field === "function" ? await field() : field;
+    return value ? [...value] : [];
+}
+const isAdapter = (v) => typeof v === "object" && v !== null;
+const importWithQuery = (path, query) => import(__rewriteRelativeImportExtension(query === undefined || query === "" ? path : `${path}?${query}`));
+/** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back to
+ * `framework.ts`. Throws a clear, actionable error if neither exists or the config is malformed. */
+export async function loadApp(cwd, outDirName = "dist", options = {}) {
+    // nifra.config.ts is the CLI's config (it may import Vite plugins / the SFC compiler, which a
+    // multi-target app keeps OUT of the edge-imported framework.ts). framework.ts is the fallback for a
+    // simple single-target app that has no edge build.
+    const configFile = existsSync(resolve(cwd, "nifra.config.ts"))
+        ? "nifra.config.ts"
+        : "framework.ts";
+    const configPath = resolve(cwd, configFile);
+    if (!existsSync(configPath)) {
+        throw new Error(`[nifra] no nifra.config.ts or framework.ts found in ${cwd}.\n` +
+            "      nifra is zero-config but needs one of them exporting at least:\n" +
+            "        export const adapter = reactAdapter            // from @nifrajs/web-react\n" +
+            '        export const clientModule = "@nifrajs/web-react/client"\n' +
+            "      (create-nifra scaffolds this for you.)");
+    }
+    if (!existsSync(resolve(cwd, "routes"))) {
+        throw new Error(`[nifra] no routes/ directory in ${cwd} — nifra apps are file-routed under routes/.`);
+    }
+    const fw = (await importWithQuery(configPath, options.importQuery));
+    if (!isAdapter(fw.adapter) || typeof fw.clientModule !== "string") {
+        throw new Error(`[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`);
+    }
+    let backend;
+    const backendPath = resolve(cwd, "backend.ts");
+    if (existsSync(backendPath)) {
+        backend = (await importWithQuery(backendPath, options.importQuery))
+            .backend;
+    }
+    return {
+        cwd,
+        routesDir: resolve(cwd, "routes"),
+        outDir: resolve(cwd, outDirName),
+        framework: fw,
+        backend,
+    };
+}
+//# sourceMappingURL=load.js.map

package/dist/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":";;;;;;;;AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAsCnC,uGAAuG;AACvG,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAA+B;IAClE,MAAM,KAAK,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;IACjE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAChC,CAAC;AAiBD,MAAM,SAAS,GAAG,CAAC,CAAU,EAAW,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAA;AAE9E,MAAM,eAAe,GAAG,CAAC,IAAY,EAAE,KAAyB,EAAoB,EAAE,CACpF,MAAM,kCAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE,EAAC,CAAA;AAEzE;oGACoG;AACpG,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAW,EACX,UAAU,GAAG,MAAM,EACnB,UAA0B,EAAE;IAE5B,8FAA8F;IAC9F,oGAAoG;IACpG,mDAAmD;IACnD,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;QAC5D,CAAC,CAAC,iBAAiB;QACnB,CAAC,CAAC,cAAc,CAAA;IAClB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAA;IAC3C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,uDAAuD,GAAG,KAAK;YAC7D,wEAAwE;YACxE,qFAAqF;YACrF,mEAAmE;YACnE,8CAA8C,CACjD,CAAA;IACH,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,mCAAmC,GAAG,8CAA8C,CACrF,CAAA;IACH,CAAC;IACD,MAAM,EAAE,GAAG,CAAC,MAAM,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,WAAW,CAAC,CAA4B,CAAA;IAC9F,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CACb,WAAW,UAAU,qFAAqF,CAC3G,CAAA;IACH,CAAC;IAED,IAAI,OAAgB,CAAA;IACpB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;IAC9C,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5B,OAAO,GAAI,CAAC,MAAM,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,CAA2B;aAC3F,OAAO,CAAA;IACZ,CAAC;IAED,OAAO;QACL,GAAG;QACH,SAAS,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC;QACjC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC;QAChC,SAAS,EAAE,EAAoB;QAC/B,OAAO;KACR,CAAA;AACH,CAAC"}

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

@@ -0,0 +1,13 @@
+/**
+ * The two project-INDEPENDENT MCP tools — `nifra_docs` + `nifra_example` — as a single factory shared
+ * by every transport: the project stdio server ({@link projectTools}), the CLI HTTP server
+ * (`nifra docs-mcp`), and the site's Cloudflare-Pages worker (`/mcp`). The corpus source is injected as
+ * loaders, so the SAME tool definitions work whether the corpus comes from disk (`Bun.file`, on the
+ * CLI) or a cached same-origin fetch (on the edge, no filesystem). One source → the tools can never be
+ * described differently across surfaces.
+ */
+import { type Example } from "./examples.js";
+import type { McpTool } from "./mcp-protocol.js";
+/** Build `nifra_docs` + `nifra_example` over injected corpus loaders. */
+export declare function docsTools(loadDocs: () => Promise<string | undefined>, loadExamples: () => Promise<Example[] | undefined>): McpTool[];
+//# sourceMappingURL=mcp-docs-tools.d.ts.map

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

@@ -0,0 +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;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAKhD,yEAAyE;AACzE,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,EAC3C,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,GACjD,OAAO,EAAE,CAmDX"}

package/dist/mcp-docs-tools.js

@@ -0,0 +1,63 @@
+/**
+ * The two project-INDEPENDENT MCP tools — `nifra_docs` + `nifra_example` — as a single factory shared
+ * by every transport: the project stdio server ({@link projectTools}), the CLI HTTP server
+ * (`nifra docs-mcp`), and the site's Cloudflare-Pages worker (`/mcp`). The corpus source is injected as
+ * loaders, so the SAME tool definitions work whether the corpus comes from disk (`Bun.file`, on the
+ * CLI) or a cached same-origin fetch (on the edge, no filesystem). One source → the tools can never be
+ * described differently across surfaces.
+ */
+import { renderDocsResult } from "./docs-search.js";
+import { renderExamplesResult } from "./examples.js";
+const clamp = (n, lo, hi, dflt) => Math.min(Math.max(typeof n === "number" ? n : dflt, lo), hi);
+/** Build `nifra_docs` + `nifra_example` over injected corpus loaders. */
+export function docsTools(loadDocs, loadExamples) {
+    return [
+        {
+            name: "nifra_docs",
+            description: 'Search nifra\'s framework documentation and get back ONLY the matching sections — auth, uploads, ISR, WebSockets, loaders, deployment, anything. Call with no query for the cheap section index; pass query (e.g. "isr revalidate") for the top matching sections. Use this instead of reading llms-full.txt (~150 KB) whole.',
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Keywords to match against doc sections (omit for the index).",
+                    },
+                    limit: { type: "number", description: "Max sections to return (default 3, max 5)." },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const corpus = await loadDocs();
+                if (corpus === undefined) {
+                    return "docs corpus missing — run `bun run gen:llms` in the nifra repo (published builds ship it).";
+                }
+                const { query, limit } = args;
+                return renderDocsResult(corpus, query, clamp(limit, 1, 5, 3));
+            },
+        },
+        {
+            name: "nifra_example",
+            description: 'Get a VERIFIED, copy-pasteable nifra code example for a task — auth route, file upload, ISR page, loader/action, typed client, SSE, deployment, etc. Every snippet is typechecked against the installed nifra version, so it compiles as-is. PREFER THIS over writing nifra code from memory (training data drifts). Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "What you want an example of (omit for the index).",
+                    },
+                    limit: { type: "number", description: "Max examples to return (default 3, max 5)." },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const corpus = await loadExamples();
+                if (corpus === undefined) {
+                    return "examples corpus missing — run `bun run gen:llms` in the nifra repo (published builds ship it).";
+                }
+                const { query, limit } = args;
+                return renderExamplesResult(corpus, query, clamp(limit, 1, 5, 3));
+            },
+        },
+    ];
+}
+//# sourceMappingURL=mcp-docs-tools.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-docs-tools.js","sourceRoot":"","sources":["../src/mcp-docs-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAgB,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAGlE,MAAM,KAAK,GAAG,CAAC,CAAqB,EAAE,EAAU,EAAE,EAAU,EAAE,IAAY,EAAU,EAAE,CACpF,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AAE9D,yEAAyE;AACzE,MAAM,UAAU,SAAS,CACvB,QAA2C,EAC3C,YAAkD;IAElD,OAAO;QACL;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EACT,+TAA+T;YACjU,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,8DAA8D;qBAC5E;oBACD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4CAA4C,EAAE;iBACrF;gBACD,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACtB,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAA;gBAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,OAAO,4FAA4F,CAAA;gBACrG,CAAC;gBACD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAA0C,CAAA;gBACnE,OAAO,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;YAC/D,CAAC;SACF;QACD;YACE,IAAI,EAAE,eAAe;YACrB,WAAW,EACT,ubAAub;YACzb,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,mDAAmD;qBACjE;oBACD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4CAA4C,EAAE;iBACrF;gBACD,oBAAoB,EAAE,KAAK;aAC5B;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBACtB,MAAM,MAAM,GAAG,MAAM,YAAY,EAAE,CAAA;gBACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,OAAO,gGAAgG,CAAA;gBACzG,CAAC;gBACD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAA0C,CAAA;gBACnE,OAAO,oBAAoB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;YACnE,CAAC;SACF;KACF,CAAA;AACH,CAAC"}

package/dist/mcp-http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The PUBLIC nifra docs MCP — Streamable-HTTP transport exposing the project-INDEPENDENT tools
+ * (`nifra_docs` + `nifra_example`) so any remote AI agent can learn nifra without a local checkout.
+ * Both tools read the bundled corpus (llms-full.txt / examples.json shipped in this package) and ignore
+ * `cwd`, so they reuse the exact definitions from {@link projectTools} — one source, no drift.
+ *
+ * {@link handleMcpHttp} is a plain Web `fetch` handler, so it self-hosts ANYWHERE Bun runs — the
+ * simplest path is `nifra docs-mcp` on a VPS behind a reverse proxy (Caddy/nginx + TLS), where the
+ * bundled corpus reads straight from disk (`Bun.file`). `export default { port, fetch }` also lets
+ * `bun run mcp-http.ts` serve it directly, and the same handler runs on Cloudflare/Vercel edge — only
+ * there must you inline the two corpus files as string imports (a Worker has no filesystem). The
+ * dispatch is the shared, transport-agnostic {@link handleRpc}.
+ */
+import { type McpTool } from "./mcp-protocol.js";
+export type { Example } from "./examples.js";
+export { docsTools } from "./mcp-docs-tools.js";
+export interface McpHttpOptions {
+    /** Maximum JSON-RPC request body size in bytes. Default 1 MB. */
+    readonly maxBodyBytes?: number;
+}
+/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */
+export declare function publicDocsTools(): McpTool[];
+/**
+ * The transport core, shared by every HTTP host (CLI `docs-mcp`, the site's edge worker): handle one
+ * MCP request against the given `tools`. POST a JSON-RPC body → JSON-RPC response; GET is a health page;
+ * OPTIONS is the CORS preflight. Never throws — a bad body becomes a JSON-RPC parse error. Pass the
+ * tools so each host supplies its own corpus source (disk vs cached fetch) behind identical defs.
+ */
+export declare function respondMcpHttp(request: Request, tools: McpTool[], options?: McpHttpOptions): Promise<Response>;
+/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */
+export declare function handleMcpHttp(request: Request): Promise<Response>;
+/**
+ * Worker/edge + local entry. `export default { fetch }` is the universal server shape: Cloudflare /
+ * Vercel edge / Deno deploy use `fetch` (and ignore `port`); `bun run mcp-http.ts` auto-serves it on
+ * `port` (PORT env, default 8787) — Bun serves a module's default-exported server, so NO manual
+ * `Bun.serve` here (that would double-bind the port).
+ */
+declare const _default: {
+    port: number;
+    fetch: typeof handleMcpHttp;
+};
+export default _default;
+//# sourceMappingURL=mcp-http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-http.d.ts","sourceRoot":"","sources":["../src/mcp-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAkC,KAAK,OAAO,EAAY,MAAM,mBAAmB,CAAA;AAE1F,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAG5C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAc/C,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAuDD,mGAAmG;AACnG,wBAAgB,eAAe,IAAI,OAAO,EAAE,CAE3C;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CA6BnB;AAED,2GAA2G;AAC3G,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEjE;AAED;;;;;GAKG;;;;;AACH,wBAGC"}