@nifrajs/cli 2.3.0 → 2.4.0

package/src/mcp-app-tool.ts

@@ -0,0 +1,86 @@
+/**
+ * The `nifra_examples_app` MCP tool: nifra's verified code examples as an MCP Apps widget. It returns the
+ * examples as `structuredContent`, rendered by the {@link examplesWidget} `ui://` widget in MCP Apps hosts
+ * (ChatGPT Apps, MCPJam, Goose); text-only hosts still get the example names as plain text. Part of the
+ * public docs-MCP tool set (served by `handleMcpHttp`), so every self-host gets it from one definition.
+ * `loadExamples` is injected, so the same tool reads the corpus from disk (CLI) or a cached fetch (edge).
+ */
+import { defineMcpTool, defineMcpWidget, type McpTool } from "@nifrajs/mcp"
+import type { Example } from "./examples.ts"
+
+/** The widget: renders `structuredContent.examples` as a filterable list of example cards. */
+export const examplesWidget = defineMcpWidget({
+  uri: "ui://nifra/examples",
+  name: "nifra examples",
+  description: "Interactive browser of verified, copy-pasteable nifra code examples.",
+  head: `<style>
+    :root { color-scheme: light dark; font: 14px/1.5 system-ui, sans-serif; }
+    body { margin: 0; padding: 16px; }
+    h1 { font-size: 16px; margin: 0 0 4px; }
+    #q { width: 100%; box-sizing: border-box; padding: 6px 10px; margin: 8px 0 14px; border-radius: 6px; border: 1px solid color-mix(in srgb, currentColor 25%, transparent); background: transparent; color: inherit; font: inherit; }
+    .card { border: 1px solid color-mix(in srgb, currentColor 15%, transparent); border-radius: 10px; padding: 10px 12px; margin-bottom: 10px; }
+    .topic { font-size: 12px; opacity: .6; }
+    .name { font-weight: 600; margin: 2px 0 6px; }
+    pre { margin: 0; padding: 8px 10px; border-radius: 6px; background: color-mix(in srgb, currentColor 8%, transparent); overflow-x: auto; font: 12px/1.5 ui-monospace, monospace; }
+  </style>`,
+  html: `
+    <h1>nifra examples</h1>
+    <input id="q" placeholder="Filter examples…" />
+    <div id="list"></div>
+    <script>
+      var ALL = [];
+      function esc(s){ return String(s).replace(/[&<>]/g, function(c){ return c==="&"?"&amp;":c==="<"?"&lt;":"&gt;"; }); }
+      function paint(items){
+        document.getElementById("list").innerHTML = items.map(function(e){
+          var code = e.code.length > 600 ? e.code.slice(0, 600) + "\\n…" : e.code;
+          return "<div class='card'><div class='topic'>" + esc(e.topic) + "</div><div class='name'>" + esc(e.name) +
+            "</div><pre>" + esc(code) + "</pre></div>";
+        }).join("") || "<p style='opacity:.6'>No matching examples.</p>";
+      }
+      function render(data){ ALL = (data && data.examples) || []; paint(ALL); }
+      mcpApp.onData(render);
+      document.getElementById("q").addEventListener("input", function(ev){
+        var q = ev.target.value.toLowerCase();
+        paint(ALL.filter(function(e){ return (e.topic + e.name + e.slug).toLowerCase().indexOf(q) !== -1; }));
+      });
+    </script>
+  `,
+})
+
+/** The widget-backed tool. `loadExamples` is injected (disk on the CLI, cached fetch on the edge). */
+export function examplesAppTool(loadExamples: () => Promise<Example[] | undefined>): McpTool {
+  return defineMcpTool({
+    name: "nifra_examples_app",
+    description:
+      "Browse nifra's verified code examples as an interactive, filterable list (MCP Apps widget). Pass query to pre-filter; the widget also filters client-side.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string", description: "Pre-filter examples by keyword." } },
+      additionalProperties: false,
+    },
+    widget: examplesWidget,
+    handler: async (args) => {
+      const all = (await loadExamples()) ?? []
+      const q = ((args.query as string) ?? "").toLowerCase()
+      const matched = (
+        q
+          ? all.filter((e) => `${e.topic} ${e.name} ${e.slug} ${e.code}`.toLowerCase().includes(q))
+          : all
+      ).slice(0, 30)
+      return {
+        text:
+          matched.length === 0
+            ? "No matching examples."
+            : `${matched.length} example(s): ${matched.map((e) => e.name).join(", ")}.`,
+        structuredContent: {
+          examples: matched.map((e) => ({
+            name: e.name,
+            topic: e.topic,
+            slug: e.slug,
+            code: e.code,
+          })),
+        },
+      }
+    },
+  })
+}

package/src/mcp-docs-tools.ts

@@ -1,5 +1,5 @@
 /**
- * The two project-INDEPENDENT MCP tools - `nifra_docs` + `nifra_example` - as a single factory shared
+ * The project-INDEPENDENT MCP tools - `nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` - 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
@@ -9,6 +9,7 @@
 
 import { renderDocsResult } from "./docs-search.ts"
 import { type Example, renderExamplesResult } from "./examples.ts"
+import { renderLearnResult } from "./learn.ts"
 import type { McpTool } from "./mcp-protocol.ts"
 import { renderTypesResult, type TypeEntry } from "./types-search.ts"
 
@@ -113,5 +114,21 @@ export function docsTools(
         return renderTypesResult(corpus, name, query, clamp(limit, 1, 8, 5), full === true)
       },
     },
+    {
+      name: "nifra_learn",
+      description:
+        "Walk the guided path to build a nifra app end to end - an ORDERED sequence (create → page route → loader → typed API → typed client → auth → background jobs → deploy), not the random-access search of nifra_docs/nifra_example. Call with no args for the step index; pass `step: N` for that step's goal, how to do it (which tool emits the correct artifact), and how to verify it. Use it when scaffolding a new app or learning nifra's flow - each step composes the other nifra_* tools.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          step: {
+            type: "number",
+            description: "1-based step number to expand (omit for the index).",
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => renderLearnResult((args as { step?: number }).step),
+    },
   ]
 }

package/src/mcp-http.ts

@@ -1,8 +1,9 @@
 /**
  * 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.
+ * (`nifra_docs`, `nifra_example`, `nifra_types`, `nifra_learn` + the `nifra_examples_app` MCP Apps widget)
+ * so any remote AI agent can learn nifra without a local checkout. They read the bundled corpus
+ * (llms-full.txt / examples.json / types.json shipped in this package) and ignore `cwd`, so they reuse the
+ * exact definitions from {@link projectTools} - one source, no drift.
  *
  * The transport itself (body cap, CORS, JSON-RPC dispatch) lives in `@nifrajs/mcp/http`; this module is
  * the docs-specific layer over it: it supplies the bundled corpus tools and the `nifra-docs` server info.
@@ -12,28 +13,37 @@
  */
 
 import { type McpHttpOptions, respondMcpHttp as respondMcpHttpCore } from "@nifrajs/mcp/http"
-import type { McpTool } from "@nifrajs/mcp/protocol"
+import { type McpTool, UI_MIME } from "@nifrajs/mcp/protocol"
 import { loadDocsCorpus } from "./docs-search.ts"
 import { loadExamplesCorpus } from "./examples.ts"
+import { examplesAppTool, examplesWidget } from "./mcp-app-tool.ts"
 import { docsTools } from "./mcp-docs-tools.ts"
 import { loadTypesCorpus } from "./types-search.ts"
 
 export type { McpHttpOptions } from "@nifrajs/mcp/http"
 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"`.
+// Re-exported so a self-host gets the corpus-injectable tool factories + the transport core from one
+// entry: `import { respondMcpHttp, docsTools, examplesAppTool } from "@nifrajs/cli/mcp"`.
+export { examplesAppTool, examplesWidget } from "./mcp-app-tool.ts"
 export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "2.3.0"
+const VERSION = "2.4.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
-const DOCS_HEALTH =
-  "nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."
+// Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
+const docsHealth = (tools: McpTool[]): string =>
+  `nifra docs MCP - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: ${tools
+    .map((tool) => tool.name)
+    .join(", ")}.`
 
-/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */
+/** The project-independent tools, reading the package's bundled corpus from disk (CLI use): the text
+ * docs tools plus the `nifra_examples_app` MCP Apps widget tool. */
 export function publicDocsTools(): McpTool[] {
-  return docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus)
+  return [
+    ...docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus),
+    examplesAppTool(loadExamplesCorpus),
+  ]
 }
 
 /**
@@ -46,12 +56,15 @@ export function respondMcpHttp(
   tools: McpTool[],
   options: McpHttpOptions = {},
 ): Promise<Response> {
-  return respondMcpHttpCore(request, tools, SERVER_INFO, { health: DOCS_HEALTH, ...options })
+  return respondMcpHttpCore(request, tools, SERVER_INFO, { health: docsHealth(tools), ...options })
 }
 
-/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */
+/** The CLI HTTP handler: serves the disk-backed corpus tools + registers the examples widget's `ui://`
+ * resource so MCP Apps hosts can render `nifra_examples_app`. (`nifra docs-mcp` / `bun run` this file.) */
 export function handleMcpHttp(request: Request): Promise<Response> {
-  return respondMcpHttp(request, publicDocsTools())
+  return respondMcpHttp(request, publicDocsTools(), {
+    features: { resources: [examplesWidget.resource], ui: { mimeTypes: [UI_MIME] } },
+  })
 }
 
 /**

package/src/mcp.ts

@@ -12,12 +12,18 @@
  *   - `nifra_docs`    - keyword-search the framework docs; returns only the matching sections.
  *   - `nifra_example` - a verified, copy-pasteable snippet for a task (typechecked against the live API,
  *     so it can't hallucinate a drifted nifra API).
+ *   - `nifra_learn`   - the guided, ordered path to build a nifra app end to end (create → deploy), each
+ *     step naming the tool that emits the correct artifact and how to verify it.
  *   - `nifra_scaffold`- map a URL path to the correct `routes/` file + a contract-correct page stub.
  *   - `nifra_check`   - the drift gate (typecheck + lints, each with a structured fix), for an agent to fix against.
  *   - `nifra_assure`  - route classification + enforcement-evidence gate.
  *   - `nifra_levels`  - the cumulative verification ladder (L0 contract → L4 invariants): what the
  *     project actually proves, and why each level it misses does not hold.
  *   - `nifra_doctor`  - package.json dependency drift detector, with safe local-version auto-fix.
+ *   - `nifra_explain` - resolve an error (pasted, or the dev server's last) into a structured
+ *     diagnostic: stable code, a codeframe in the user's source, and the recognised cause + fix.
+ *   - `nifra_inspect` - read the running dev server's recent request traces (method/path/status/
+ *     duration/ISR) from the DevTools plugin: what your requests ACTUALLY did, not a guess.
  *
  * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
  * project root. The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
@@ -75,6 +81,67 @@ function childPath(name: "mcp-run" | "mcp-render" | "mcp-ws"): string {
  */
 const CHILD_TIMEOUT_MS = 30_000
 
+/** 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: unknown): number | undefined {
+  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: Response,
+  maxBytes = LOCAL_TOOL_MAX_RESPONSE_BYTES,
+): Promise<string> {
+  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: Uint8Array[] = []
+  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: string): string =>
+  JSON.stringify(
+    {
+      code: "NIFRA_NOT_DEV_SERVER",
+      message: `The service on this port is not a Nifra ${service} endpoint.`,
+    },
+    null,
+    2,
+  )
+
 const timeoutMessage = (label: string, ms: number): string =>
   `${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 ` +
@@ -668,6 +735,176 @@ export function projectTools(
         return describeProject(await loadAppCached(), filter)
       },
     },
+    {
+      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 as {
+          error?: string
+          stack?: string
+          name?: string
+          port?: number
+        }
+        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 as { port?: number; path?: string; limit?: number }
+        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_routes",
       description: