@nifrajs/cli 0.1.0-alpha.1

package/src/mcp-protocol.ts

@@ -0,0 +1,326 @@
+/**
+ * The pure MCP (Model Context Protocol) JSON-RPC dispatch — no I/O, no `Bun.*`, no side effects, so it
+ * unit-tests cleanly. {@link runMcpServer} in `./mcp.ts` wires this to stdin/stdout; the tools are
+ * injected, so the protocol logic is exercised without spawning or reading streams.
+ */
+
+export const PROTOCOL_VERSION = "2024-11-05"
+
+type RequestId = string | number
+type JsonRpcId = RequestId | null
+type ProgressToken = string | number
+
+export interface McpToolContext {
+  readonly signal: AbortSignal
+  readonly requestId: JsonRpcId
+  readonly progressToken?: ProgressToken
+  readonly reportProgress: (progress: number, total?: number) => void
+}
+
+/** A tool the agent can call. `handler` returns the text shown to the agent. */
+export interface McpTool {
+  readonly name: string
+  readonly description: string
+  readonly inputSchema: Record<string, unknown>
+  readonly handler: (args: Record<string, unknown>, context: McpToolContext) => Promise<string>
+}
+
+export interface McpResource {
+  readonly uri: string
+  readonly name: string
+  readonly description?: string
+  readonly mimeType?: string
+  readonly read: () => Promise<{ readonly text: string; readonly mimeType?: string }>
+}
+
+export interface McpPromptMessage {
+  readonly role: "user" | "assistant"
+  readonly content: { readonly type: "text"; readonly text: string }
+}
+
+export interface McpPrompt {
+  readonly name: string
+  readonly description: string
+  readonly arguments?: readonly {
+    readonly name: string
+    readonly description?: string
+    readonly required?: boolean
+  }[]
+  readonly handler: (args: Record<string, unknown>) => Promise<readonly McpPromptMessage[]>
+}
+
+export interface McpServerFeatures {
+  readonly resources?: readonly McpResource[]
+  readonly prompts?: readonly McpPrompt[]
+}
+
+export interface JsonRpcRequest {
+  readonly jsonrpc?: string
+  readonly id?: JsonRpcId
+  readonly method?: string
+  readonly params?: Record<string, unknown>
+}
+
+export interface JsonRpcNotification {
+  readonly jsonrpc: "2.0"
+  readonly method: string
+  readonly params?: Record<string, unknown>
+}
+
+export type JsonRpcResponse =
+  | { jsonrpc: "2.0"; id: JsonRpcId; result: unknown }
+  | { jsonrpc: "2.0"; id: JsonRpcId; error: { code: number; message: string } }
+
+export const rpcResult = (id: JsonRpcId, value: unknown): JsonRpcResponse => ({
+  jsonrpc: "2.0",
+  id,
+  result: value,
+})
+export const rpcError = (id: JsonRpcId, code: number, message: string): JsonRpcResponse => ({
+  jsonrpc: "2.0",
+  id,
+  error: { code, message },
+})
+
+export interface McpProtocolState {
+  readonly activeRequests: Map<string, AbortController>
+}
+
+export interface McpProtocolOptions {
+  readonly state?: McpProtocolState
+  readonly signal?: AbortSignal
+  readonly sendNotification?: (notification: JsonRpcNotification) => void
+}
+
+export function createMcpProtocolState(): McpProtocolState {
+  return { activeRequests: new Map() }
+}
+
+function requestKey(id: unknown): string | undefined {
+  if (typeof id === "string") return `s:${id}`
+  return typeof id === "number" && Number.isFinite(id) ? `n:${id}` : undefined
+}
+
+function progressTokenOf(params: Record<string, unknown> | undefined): ProgressToken | undefined {
+  const meta = params?._meta
+  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return undefined
+  const token = (meta as Record<string, unknown>).progressToken
+  return typeof token === "string" || (typeof token === "number" && Number.isFinite(token))
+    ? token
+    : undefined
+}
+
+function cancellationReason(params: Record<string, unknown> | undefined): string | undefined {
+  const reason = params?.reason
+  return typeof reason === "string" && reason.length > 0 ? reason : undefined
+}
+
+function linkAbortSignal(parent: AbortSignal | undefined, child: AbortController): () => void {
+  if (parent === undefined) return () => {}
+  if (parent.aborted) {
+    child.abort(parent.reason)
+    return () => {}
+  }
+  const abort = (): void => child.abort(parent.reason)
+  parent.addEventListener("abort", abort, { once: true })
+  return () => parent.removeEventListener("abort", abort)
+}
+
+function abortMessage(signal: AbortSignal): string {
+  const reason = signal.reason
+  if (typeof reason === "string" && reason.length > 0) return `Cancelled: ${reason}`
+  return "Cancelled"
+}
+
+function compactDescription(description: string): string {
+  const text = description.replace(/\s+/g, " ").trim()
+  const sentenceEnd = text.search(/[.!?](?:\s|$)/)
+  const sentence = sentenceEnd === -1 ? text : text.slice(0, sentenceEnd + 1)
+  if (sentence.length <= 120) return sentence
+  return `${sentence.slice(0, 117).trimEnd()}...`
+}
+
+/**
+ * Dispatch one JSON-RPC message against the given tools. Returns the response, or `null` for a
+ * notification (no reply). Tool errors are reported in-band (`isError`) so the agent can react to them.
+ */
+export async function handleRpc(
+  message: JsonRpcRequest,
+  tools: readonly McpTool[],
+  serverInfo: { name: string; version: string },
+  features: McpServerFeatures = {},
+  options: McpProtocolOptions = {},
+): Promise<JsonRpcResponse | null> {
+  const { id, method, params } = message
+  const isNotification = id === undefined
+  const rid = id ?? null
+  const resources = features.resources ?? []
+  const prompts = features.prompts ?? []
+  const state = options.state ?? createMcpProtocolState()
+
+  switch (method) {
+    case "initialize":
+      return rpcResult(rid, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {
+          tools: {},
+          ...(resources.length > 0 ? { resources: {} } : {}),
+          ...(prompts.length > 0 ? { prompts: {} } : {}),
+        },
+        serverInfo,
+      })
+    case "notifications/initialized":
+      return null
+    case "notifications/cancelled": {
+      const key = requestKey(params?.requestId)
+      if (key !== undefined) state.activeRequests.get(key)?.abort(cancellationReason(params))
+      return null
+    }
+    case "ping":
+      return rpcResult(rid, {})
+    case "tools/list":
+      return rpcResult(
+        rid,
+        params?.compact === true
+          ? {
+              tools: tools.map((t) => ({
+                name: t.name,
+                description: compactDescription(t.description),
+              })),
+            }
+          : {
+              tools: tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+              })),
+            },
+      )
+    case "tools/describe": {
+      const name = params?.name
+      const tool = tools.find((t) => t.name === name)
+      if (!tool) return rpcError(rid, -32602, `unknown tool: ${String(name)}`)
+      return rpcResult(rid, {
+        tool: {
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        },
+      })
+    }
+    case "tools/call": {
+      const name = params?.name
+      const tool = tools.find((t) => t.name === name)
+      if (!tool) return rpcError(rid, -32602, `unknown tool: ${String(name)}`)
+      const args = (params?.arguments as Record<string, unknown>) ?? {}
+      const controller = new AbortController()
+      const key = requestKey(id)
+      const cleanupAbort = linkAbortSignal(options.signal, controller)
+      if (key !== undefined) state.activeRequests.set(key, controller)
+      const progressToken = progressTokenOf(params)
+      let lastProgress = Number.NEGATIVE_INFINITY
+      const reportProgress = (progress: number, total?: number): void => {
+        if (
+          progressToken === undefined ||
+          !Number.isFinite(progress) ||
+          progress <= lastProgress ||
+          (total !== undefined && !Number.isFinite(total))
+        ) {
+          return
+        }
+        lastProgress = progress
+        options.sendNotification?.({
+          jsonrpc: "2.0",
+          method: "notifications/progress",
+          params: {
+            progressToken,
+            progress,
+            ...(total !== undefined ? { total } : {}),
+          },
+        })
+      }
+      try {
+        reportProgress(0, 1)
+        if (controller.signal.aborted) throw new DOMException("cancelled", "AbortError")
+        const text = await tool.handler(args, {
+          signal: controller.signal,
+          requestId: rid,
+          ...(progressToken !== undefined ? { progressToken } : {}),
+          reportProgress,
+        })
+        if (controller.signal.aborted) throw new DOMException("cancelled", "AbortError")
+        reportProgress(1, 1)
+        return rpcResult(rid, { content: [{ type: "text", text }] })
+      } catch (err) {
+        if (controller.signal.aborted) {
+          return rpcResult(rid, {
+            content: [{ type: "text", text: abortMessage(controller.signal) }],
+            isError: true,
+          })
+        }
+        const msg = err instanceof Error ? err.message : String(err)
+        return rpcResult(rid, { content: [{ type: "text", text: `Error: ${msg}` }], isError: true })
+      } finally {
+        cleanupAbort()
+        if (key !== undefined && state.activeRequests.get(key) === controller) {
+          state.activeRequests.delete(key)
+        }
+      }
+    }
+    case "resources/list":
+      return rpcResult(rid, {
+        resources: resources.map((r) => ({
+          uri: r.uri,
+          name: r.name,
+          ...(r.description !== undefined ? { description: r.description } : {}),
+          ...(r.mimeType !== undefined ? { mimeType: r.mimeType } : {}),
+        })),
+      })
+    case "resources/read": {
+      const uri = params?.uri
+      const resource = resources.find((r) => r.uri === uri)
+      if (!resource) return rpcError(rid, -32602, `unknown resource: ${String(uri)}`)
+      try {
+        const content = await resource.read()
+        return rpcResult(rid, {
+          contents: [
+            {
+              uri: resource.uri,
+              mimeType: content.mimeType ?? resource.mimeType ?? "text/plain",
+              text: content.text,
+            },
+          ],
+        })
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        return rpcError(rid, -32000, msg)
+      }
+    }
+    case "prompts/list":
+      return rpcResult(rid, {
+        prompts: prompts.map((p) => ({
+          name: p.name,
+          description: p.description,
+          ...(p.arguments !== undefined ? { arguments: p.arguments } : {}),
+        })),
+      })
+    case "prompts/get": {
+      const name = params?.name
+      const prompt = prompts.find((p) => p.name === name)
+      if (!prompt) return rpcError(rid, -32602, `unknown prompt: ${String(name)}`)
+      const args = (params?.arguments as Record<string, unknown>) ?? {}
+      try {
+        return rpcResult(rid, {
+          description: prompt.description,
+          messages: await prompt.handler(args),
+        })
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        return rpcError(rid, -32000, msg)
+      }
+    }
+    default:
+      if (isNotification) return null
+      return rpcError(rid, -32601, `method not found: ${String(method)}`)
+  }
+}

package/src/mcp-render.ts

@@ -0,0 +1,78 @@
+/**
+ * The `nifra_render` engine + its child-process entry — the page half of `nifra_run`. Where `nifra_run`
+ * runs requests through the BACKEND, this SSRs page routes through the WEB app (`createWebApp`), so an
+ * agent can verify a page renders and its loader ran after an edit. Spawned fresh per call (`bun
+ * mcp-render.ts <cwd>`) so the project's CURRENT route/loader code is loaded.
+ *
+ * No build required: a placeholder `clientEntry` is injected (the SSR HTML renders regardless — the
+ * client bundle only matters for hydration in the browser, not for "did this page render server-side").
+ * {@link renderPages} never throws — every failure (no config, a loader error, a render throw) becomes
+ * `{ error }` so the agent gets the actionable message.
+ */
+
+import { inProcessClient } from "@nifrajs/client"
+import { type AppLike, runApp } from "@nifrajs/runner"
+import { createWebApp, type RenderAdapter } from "@nifrajs/web"
+import { discoverRoutes } from "@nifrajs/web/fs"
+import { loadApp, resolvePlugins } from "./load.ts"
+
+const errString = (err: unknown): string =>
+  err instanceof Error ? `${err.name}: ${err.message}` : String(err)
+
+export async function renderPages(
+  cwd: string,
+  requests: unknown,
+): Promise<{ results: unknown } | { error: string }> {
+  if (!Array.isArray(requests)) return { error: "expected { requests: [...] }" }
+
+  let app: Awaited<ReturnType<typeof loadApp>>
+  try {
+    app = await loadApp(cwd, "dist")
+  } catch (err) {
+    return { error: errString(err) }
+  }
+
+  // Register the framework's SSR Bun plugins so `.vue`/`.svelte`/Solid route files compile on import
+  // (React/Preact JSX is Bun-native → none). Mirrors `nifra start`.
+  try {
+    const { plugin } = await import("bun")
+    for (const p of await resolvePlugins(app.framework.serverPlugins)) {
+      plugin(p as Parameters<typeof plugin>[0])
+    }
+  } catch (err) {
+    return { error: errString(err) }
+  }
+
+  let webApp: AppLike
+  try {
+    webApp = createWebApp({
+      // The adapter is validated by loadApp; cast at the seam (same as the CLI's `asAdapter`).
+      adapter: app.framework.adapter as RenderAdapter,
+      manifest: discoverRoutes(app.routesDir),
+      clientEntry: "/_nifra-render-only.js", // placeholder; SSR HTML does not need the built client
+      ...(app.backend !== undefined ? { api: inProcessClient(app.backend as never) } : {}),
+    }) as unknown as AppLike
+  } catch (err) {
+    return { error: errString(err) }
+  }
+
+  try {
+    return { results: await runApp(webApp, requests as Parameters<typeof runApp>[1]) }
+  } catch (err) {
+    return { error: errString(err) }
+  }
+}
+
+// Child-process entry: read `{ requests }` from stdin, SSR, print JSON. Guarded so importing this
+// module in a test does not execute it.
+if (import.meta.main) {
+  const cwd = process.argv[2] ?? process.cwd()
+  let output: unknown
+  try {
+    const { requests } = JSON.parse(await Bun.stdin.text()) as { requests: unknown }
+    output = await renderPages(cwd, requests)
+  } catch {
+    output = { error: "invalid input: expected JSON { requests: [...] }" }
+  }
+  process.stdout.write(JSON.stringify(output, null, 2))
+}

package/src/mcp-run.ts

@@ -0,0 +1,153 @@
+/**
+ * The `nifra_run` engine + its child-process entry. The MCP server spawns this file fresh on every
+ * `nifra_run` call (`bun mcp-run.ts <cwd>`) so the project's CURRENT backend code is loaded — picking
+ * up the agent's latest edits. {@link runBackend} is the pure-ish core (resolve entry → import → run),
+ * exported so it's unit-testable in-process; the entry below wires it to stdin/stdout.
+ */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { type AppLike, runApp } from "@nifrajs/runner"
+
+const ENTRY_CANDIDATES = ["backend.ts", "app.ts", "src/backend.ts", "src/app.ts"]
+
+const errString = (err: unknown): string =>
+  err instanceof Error ? `${err.name}: ${err.message}` : String(err)
+
+export async function loadBackend(
+  cwd: string,
+  entry?: string,
+): Promise<{ app: AppLike } | { error: string }> {
+  const candidates = entry && entry.length > 0 ? [entry] : ENTRY_CANDIDATES
+  const found = candidates.map((c) => resolve(cwd, c)).find((p) => existsSync(p))
+  if (!found) {
+    return { error: `no backend entry found in ${cwd} (looked for ${candidates.join(", ")})` }
+  }
+
+  let mod: Record<string, unknown>
+  try {
+    mod = (await import(pathToFileURL(found).href)) as Record<string, unknown>
+  } catch (err) {
+    return { error: errString(err) }
+  }
+  const app = (mod.app ?? mod.backend ?? mod.default) as AppLike | undefined
+  if (!app || typeof app.fetch !== "function") {
+    return {
+      error: `${found} does not export a nifra app (expected \`app\`, \`backend\`, or default).`,
+    }
+  }
+  return { app }
+}
+
+/**
+ * Resolve the backend entry under `cwd`, import it, and run `requests` through its exported app. Never
+ * throws — every failure (missing/invalid entry, import/compile/runtime error) becomes `{ error }`, so
+ * the caller (and the agent) always gets actionable output. An import error here IS the failure the
+ * agent needs to see and fix.
+ */
+export async function runBackend(
+  cwd: string,
+  requests: unknown,
+  entry?: string,
+): Promise<{ results: unknown } | { error: string }> {
+  if (!Array.isArray(requests)) return { error: "expected { requests: [...] }" }
+
+  const loaded = await loadBackend(cwd, entry)
+  if ("error" in loaded) return loaded
+
+  try {
+    return { results: await runApp(loaded.app, requests as Parameters<typeof runApp>[1]) }
+  } catch (err) {
+    return { error: errString(err) }
+  }
+}
+
+interface WorkerMessage {
+  readonly id?: unknown
+  readonly input?: { readonly requests?: unknown; readonly entry?: string }
+}
+
+function redirectConsoleToStderr(): void {
+  const write = (level: string, args: unknown[]): void => {
+    Bun.stderr.write(`[${level}] ${args.map((arg) => String(arg)).join(" ")}\n`)
+  }
+  console.debug = (...args: unknown[]) => write("debug", args)
+  console.info = (...args: unknown[]) => write("info", args)
+  console.log = (...args: unknown[]) => write("log", args)
+  console.warn = (...args: unknown[]) => write("warn", args)
+  console.error = (...args: unknown[]) => write("error", args)
+}
+
+async function runWorker(cwd: string): Promise<void> {
+  redirectConsoleToStderr()
+  const apps = new Map<string, Promise<{ app: AppLike } | { error: string }>>()
+  const decoder = new TextDecoder()
+  let buffer = ""
+  const send = (id: unknown, output: unknown): void => {
+    process.stdout.write(`${JSON.stringify({ id, output })}\n`)
+  }
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += decoder.decode(chunk as Uint8Array, { stream: true })
+    let nl = buffer.indexOf("\n")
+    while (nl !== -1) {
+      const line = buffer.slice(0, nl).trim()
+      buffer = buffer.slice(nl + 1)
+      nl = buffer.indexOf("\n")
+      if (line === "") continue
+
+      let message: WorkerMessage
+      try {
+        message = JSON.parse(line) as WorkerMessage
+      } catch {
+        send(null, { error: "invalid worker input: expected JSON line" })
+        continue
+      }
+      const requests = message.input?.requests
+      const entry = message.input?.entry
+      if (!Array.isArray(requests)) {
+        send(message.id, { error: "expected { requests: [...] }" })
+        continue
+      }
+      const key = entry ?? ""
+      let loaded = apps.get(key)
+      if (loaded === undefined) {
+        loaded = loadBackend(cwd, entry)
+        apps.set(key, loaded)
+      }
+      const app = await loaded
+      if ("error" in app) {
+        send(message.id, app)
+        continue
+      }
+      try {
+        send(message.id, {
+          results: await runApp(app.app, requests as Parameters<typeof runApp>[1]),
+        })
+      } catch (err) {
+        send(message.id, { error: errString(err) })
+      }
+    }
+  }
+}
+
+// Child-process entry: read `{ requests, entry? }` from stdin, run, print JSON to stdout. Guarded so
+// this only executes when run directly (not when imported by a test).
+if (import.meta.main) {
+  const cwd = process.argv[2] ?? process.cwd()
+  if (process.argv.includes("--worker")) {
+    await runWorker(cwd)
+    process.exit(0)
+  }
+  let output: unknown
+  try {
+    const { requests, entry } = JSON.parse(await Bun.stdin.text()) as {
+      requests: unknown
+      entry?: string
+    }
+    output = await runBackend(cwd, requests, entry)
+  } catch {
+    output = { error: "invalid input: expected JSON { requests: [...] }" }
+  }
+  process.stdout.write(JSON.stringify(output, null, 2))
+}