@nifrajs/cli 0.1.0-alpha.1

package/src/introspect.ts

@@ -0,0 +1,284 @@
+/**
+ * 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 type { Manifest } from "@nifrajs/web"
+import { discoverRoutes } from "@nifrajs/web/fs"
+import type { LoadedApp } from "./load.ts"
+
+/** Structural view of a `@nifrajs/core` route descriptor — declared locally so the CLI needs no type
+ * dependency on core. `app.routes()` returns these. */
+interface RouteDesc {
+  readonly method: string
+  readonly path: string
+  readonly schema?: unknown
+}
+
+/** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
+function backendRoutes(backend: unknown): RouteDesc[] {
+  if (backend && typeof (backend as { routes?: unknown }).routes === "function") {
+    try {
+      return (backend as { routes(): RouteDesc[] }).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: unknown): unknown {
+  if (schema && typeof schema === "object" && "jsonSchema" in schema) {
+    const js = (schema as { jsonSchema?: unknown }).jsonSchema
+    if (js !== undefined && js !== null) return js
+  }
+  return undefined
+}
+
+interface JsonSchemaNode {
+  readonly type?: unknown
+  readonly properties?: Record<string, unknown>
+  readonly required?: unknown
+  readonly items?: unknown
+  readonly additionalProperties?: unknown
+  readonly anyOf?: unknown
+  readonly oneOf?: unknown
+  readonly enum?: unknown
+  readonly const?: unknown
+}
+
+/**
+ * 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: unknown, depth = 0): string {
+  if (typeof schema !== "object" || schema === null || depth > 6) return JSON.stringify(schema)
+  const node = schema as JsonSchemaNode
+  const union = (node.anyOf ?? node.oneOf) as unknown[] | undefined
+  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 as string[]) : [])
+      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: unknown): string[] {
+  const s = schema as { body?: unknown; query?: unknown; response?: unknown } | undefined
+  if (!s) return []
+  const out: string[] = []
+  for (const key of ["query", "body", "response"] as const) {
+    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: string, path: string, schema: unknown): string {
+  const s = schema as { body?: unknown; query?: unknown } | undefined
+  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: string
+  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: readonly RouteDesc[]): string {
+  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: Manifest | undefined): string {
+  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\`.`
+
+/** Optional narrowing for {@link describeProject} — a path prefix and/or one section. A filtered
+ * brief omits the conventions block (the agent already has it from its first full call), so
+ * follow-up calls cost a fraction of the tokens. */
+export interface ContextFilter {
+  readonly path?: string
+  readonly kind?: "api" | "pages"
+}
+
+/** Build the project brief (API routes + page routes + conventions) as Markdown — optionally
+ * narrowed by {@link ContextFilter} for cheap follow-up calls. */
+export function describeProject(app: LoadedApp, filter?: ContextFilter): string {
+  let manifest: Manifest | undefined
+  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: string[] = [`# 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")
+}
+
+/** One API route as structured JSON: method, path, the exact typed-client call form, and compact
+ * TS-shaped request/response contracts (present only when the route declares the schema). */
+export interface RouteJson {
+  readonly method: string
+  readonly path: string
+  readonly call: string
+  readonly body?: string
+  readonly query?: string
+  readonly response?: string
+}
+
+/**
+ * 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: LoadedApp, pathPrefix?: string): RouteJson[] {
+  const shape = (v: unknown): string | undefined => {
+    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 as { body?: unknown; query?: unknown; response?: unknown } | undefined
+      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 }),
+      }
+    })
+}

package/src/load.ts

@@ -0,0 +1,129 @@
+/**
+ * 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"
+
+/**
+ * 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 async function resolvePlugins(field: PluginsField | undefined): Promise<unknown[]> {
+  const value = typeof field === "function" ? await field() : field
+  return value ? [...value] : []
+}
+
+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
+}
+
+const isAdapter = (v: unknown): boolean => typeof v === "object" && v !== null
+
+const importWithQuery = (path: string, query: string | undefined): Promise<unknown> =>
+  import(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: string,
+  outDirName = "dist",
+  options: LoadAppOptions = {},
+): Promise<LoadedApp> {
+  // 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)) as Partial<NifraFramework>
+  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: unknown
+  const backendPath = resolve(cwd, "backend.ts")
+  if (existsSync(backendPath)) {
+    backend = ((await importWithQuery(backendPath, options.importQuery)) as { backend?: unknown })
+      .backend
+  }
+
+  return {
+    cwd,
+    routesDir: resolve(cwd, "routes"),
+    outDir: resolve(cwd, outDirName),
+    framework: fw as NifraFramework,
+    backend,
+  }
+}

package/src/mcp-docs-tools.ts

@@ -0,0 +1,72 @@
+/**
+ * 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.ts"
+import { type Example, renderExamplesResult } from "./examples.ts"
+import type { McpTool } from "./mcp-protocol.ts"
+
+const clamp = (n: number | undefined, lo: number, hi: number, dflt: number): number =>
+  Math.min(Math.max(typeof n === "number" ? n : dflt, lo), hi)
+
+/** Build `nifra_docs` + `nifra_example` over injected corpus loaders. */
+export function docsTools(
+  loadDocs: () => Promise<string | undefined>,
+  loadExamples: () => Promise<Example[] | undefined>,
+): McpTool[] {
+  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 as { query?: string; limit?: number }
+        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 as { query?: string; limit?: number }
+        return renderExamplesResult(corpus, query, clamp(limit, 1, 5, 3))
+      },
+    },
+  ]
+}

package/src/mcp-http.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { loadDocsCorpus } from "./docs-search.ts"
+import { loadExamplesCorpus } from "./examples.ts"
+import { docsTools } from "./mcp-docs-tools.ts"
+import { handleRpc, type JsonRpcRequest, type McpTool, rpcError } from "./mcp-protocol.ts"
+
+export type { Example } from "./examples.ts"
+// Re-exported so a self-host (e.g. a Cloudflare-Pages `/mcp` worker route) gets the corpus-injectable
+// tool factory + the transport core from one entry: `import { respondMcpHttp, docsTools } from "@nifrajs/cli/mcp"`.
+export { docsTools } from "./mcp-docs-tools.ts"
+
+const VERSION = "0.1.0-alpha.1"
+const SERVER_INFO = { name: "nifra-docs", version: VERSION }
+
+const CORS: Record<string, string> = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "POST, GET, OPTIONS",
+  "access-control-allow-headers": "content-type",
+}
+
+const DEFAULT_MAX_BODY_BYTES = 1_000_000
+const TEXT_DECODER = new TextDecoder()
+
+export interface McpHttpOptions {
+  /** Maximum JSON-RPC request body size in bytes. Default 1 MB. */
+  readonly maxBodyBytes?: number
+}
+
+function parseContentLength(value: string): number | undefined {
+  if (value.length === 0) return undefined
+  let length = 0
+  for (let i = 0; i < value.length; i++) {
+    const digit = value.charCodeAt(i) - 48
+    if (digit < 0 || digit > 9) return undefined
+    length = length * 10 + digit
+    if (length > Number.MAX_SAFE_INTEGER) return Number.POSITIVE_INFINITY
+  }
+  return length
+}
+
+async function readJsonBounded(
+  request: Request,
+  maxBytes: number,
+): Promise<{ ok: true; value: unknown } | { ok: false; status: 400 | 413 }> {
+  const declared = request.headers.get("content-length")
+  if (declared !== null) {
+    const length = parseContentLength(declared)
+    if (length === undefined) return { ok: false, status: 400 }
+    if (length > maxBytes) return { ok: false, status: 413 }
+  }
+
+  const body = request.body
+  if (body === null) return { ok: false, status: 400 }
+
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.byteLength
+    if (total > maxBytes) {
+      await reader.cancel()
+      return { ok: false, status: 413 }
+    }
+    chunks.push(value)
+  }
+
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  try {
+    return { ok: true, value: JSON.parse(TEXT_DECODER.decode(bytes)) as unknown }
+  } catch {
+    return { ok: false, status: 400 }
+  }
+}
+
+/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */
+export function publicDocsTools(): McpTool[] {
+  return docsTools(loadDocsCorpus, loadExamplesCorpus)
+}
+
+/**
+ * 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 async function respondMcpHttp(
+  request: Request,
+  tools: McpTool[],
+  options: McpHttpOptions = {},
+): Promise<Response> {
+  if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS })
+  if (request.method === "GET") {
+    return new Response(
+      "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example.",
+      { headers: { "content-type": "text/plain; charset=utf-8", ...CORS } },
+    )
+  }
+  if (request.method !== "POST") {
+    return new Response("method not allowed", {
+      status: 405,
+      headers: { allow: "POST, GET", ...CORS },
+    })
+  }
+  const parsed = await readJsonBounded(request, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES)
+  if (!parsed.ok) {
+    if (parsed.status === 413) {
+      return Response.json(rpcError(null, -32000, "payload too large"), {
+        status: 413,
+        headers: CORS,
+      })
+    }
+    return Response.json(rpcError(null, -32700, "parse error"), { status: 400, headers: CORS })
+  }
+  const message = parsed.value as JsonRpcRequest
+  const response = await handleRpc(message, tools, SERVER_INFO, {}, { signal: request.signal })
+  // A notification (no id) yields null — acknowledge with 204, no body.
+  if (response === null) return new Response(null, { status: 204, headers: CORS })
+  return Response.json(response, { headers: CORS })
+}
+
+/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */
+export function handleMcpHttp(request: Request): Promise<Response> {
+  return respondMcpHttp(request, publicDocsTools())
+}
+
+/**
+ * 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).
+ */
+export default {
+  port: typeof Bun !== "undefined" ? Number(Bun.env.PORT ?? 8787) : 8787,
+  fetch: handleMcpHttp,
+}