@nifrajs/cli 3.5.0 → 4.0.2

package/src/mcp-isolate.ts

@@ -0,0 +1,287 @@
+/**
+ * Where `nifra mcp` keeps project code: in a fresh subprocess per call (`mcp-project-child.ts`), never
+ * in the server. The server lists the tools, resources and prompts and forwards each call; the child,
+ * started in the project's directory, loads `.env` there, imports the config and the backend, answers
+ * and exits. So the server holds neither the project's environment nor its modules, and every call
+ * sees the project's current code.
+ */
+
+import { randomUUID } from "node:crypto"
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { CONFIG_FILE } from "./app-files.ts"
+import type { NifraMonorepoConfig } from "./load.ts"
+import { appFingerprint } from "./mcp-exec.ts"
+import { CHILD_TIMEOUT_MS, readBoundedLines, readBoundedStream } from "./mcp-io.ts"
+import type {
+  AppSurface,
+  ProjectChildAnswer,
+  ProjectChildMessage,
+  ProjectChildRequest,
+} from "./mcp-project-child.ts"
+import type {
+  McpPrompt,
+  McpPromptMessage,
+  McpResource,
+  McpTool,
+  McpToolContext,
+  McpToolResult,
+} from "./mcp-protocol.ts"
+
+/**
+ * Project tools that stay in the server, because none runs project code in this process: each starts
+ * its own subprocess (run, render, ws, hydrate, test, the database tools), or reads only the
+ * framework's docs or the dev server's feed. `mcp-project-isolation.test.ts` calls each one and fails
+ * if the server evaluated project code, or if a name here has no probe there.
+ */
+export const IN_PROCESS_TOOLS: ReadonlySet<string> = new Set([
+  "nifra_run",
+  "nifra_render",
+  "nifra_ws",
+  "nifra_hydrate",
+  "nifra_test",
+  "nifra_db_schema",
+  "nifra_db_query",
+  "nifra_db_role",
+  "nifra_errors",
+  "nifra_logs",
+  "nifra_inspect",
+  "nifra_explain",
+  "nifra_docs",
+  "nifra_example",
+  "nifra_types",
+  "nifra_learn",
+  "nifra_frontend",
+])
+
+/** A tool result is bounded again by the stdio message limit when the server sends it. */
+const ANSWER_MAX_BYTES = 8 * 1024 * 1024
+
+function childPath(): string {
+  return fileURLToPath(new URL(import.meta.url)).replace(
+    /mcp-isolate\.(ts|js)$/,
+    "mcp-project-child.$1",
+  )
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const isAnswer = (value: unknown): value is ProjectChildAnswer =>
+  isRecord(value) &&
+  (value.ok === true || (value.ok === false && typeof value.message === "string"))
+
+function parseMessage(text: string): ProjectChildMessage | undefined {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  if (!isRecord(value)) return undefined
+  if (value.type === "answer" && isAnswer(value.answer)) {
+    return { type: "answer", answer: value.answer }
+  }
+  if (value.type === "progress" && typeof value.progress === "number") {
+    return typeof value.total === "number"
+      ? { type: "progress", progress: value.progress, total: value.total }
+      : { type: "progress", progress: value.progress }
+  }
+  return undefined
+}
+
+const failed = (message: string): ProjectChildAnswer => ({
+  ok: false,
+  message: `[nifra] ${message}`,
+})
+
+export interface ProjectChildOptions {
+  /** Progress is forwarded to it, and its cancellation kills the subprocess. */
+  readonly context?: McpToolContext
+  /** Kill the subprocess after this long. Tool calls have none: a client cancels them instead. */
+  readonly timeoutMs?: number
+}
+
+/** Answer `request` in a fresh subprocess in `cwd`; a crash, a timeout or no answer is `ok: false`. */
+export async function askProjectChild(
+  cwd: string,
+  request: ProjectChildRequest,
+  options: ProjectChildOptions = {},
+): Promise<ProjectChildAnswer> {
+  const { context, timeoutMs } = options
+  if (context?.signal.aborted) return failed("the call was cancelled before it started")
+  const token = randomUUID()
+  let proc: Bun.Subprocess<"pipe", "pipe", "pipe">
+  try {
+    proc = Bun.spawn([process.execPath, childPath(), cwd], {
+      cwd,
+      // Explicit: without `env`, Bun passes the environment it started with, missing `--env-file` values.
+      env: process.env,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+  } catch (error) {
+    return failed(
+      `cannot start a process in ${cwd}: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+  let stopped: "timeout" | "cancel" | undefined
+  const stop = (reason: "timeout" | "cancel"): void => {
+    if (stopped !== undefined) return
+    stopped = reason
+    proc.kill("SIGKILL")
+  }
+  const timer = timeoutMs === undefined ? undefined : setTimeout(() => stop("timeout"), timeoutMs)
+  const onAbort = (): void => stop("cancel")
+  context?.signal.addEventListener("abort", onAbort, { once: true })
+  try {
+    proc.stdin.write(JSON.stringify({ ...request, token }))
+    await proc.stdin.end()
+    const stderr = readBoundedStream(proc.stderr, 16 * 1024)
+    let answer: ProjectChildAnswer | undefined
+    let tooLarge = false
+    for await (const item of readBoundedLines(proc.stdout, ANSWER_MAX_BYTES)) {
+      if (item.kind === "too-large") {
+        tooLarge = true
+        continue
+      }
+      if (!item.text.startsWith(`${token} `)) continue
+      const message = parseMessage(item.text.slice(token.length + 1))
+      if (message?.type === "progress") context?.reportProgress(message.progress, message.total)
+      else if (message?.type === "answer") answer = message.answer
+    }
+    const [errors] = await Promise.all([stderr, proc.exited])
+    if (answer !== undefined) return answer
+    if (stopped === "timeout") {
+      return failed(`the project process did not answer within ${timeoutMs}ms and was killed`)
+    }
+    if (stopped === "cancel") return failed("the call was cancelled")
+    if (tooLarge) return failed(`the answer exceeded ${ANSWER_MAX_BYTES} bytes`)
+    const tail = errors.text.trim().slice(-600)
+    const how = proc.signalCode === null ? `with code ${proc.exitCode}` : `on ${proc.signalCode}`
+    return failed(
+      `the project process exited ${how} before answering${tail === "" ? "" : `: ${tail}`}`,
+    )
+  } finally {
+    clearTimeout(timer)
+    context?.signal.removeEventListener("abort", onAbort)
+  }
+}
+
+async function callTool(
+  cwd: string,
+  name: string,
+  args: Record<string, unknown>,
+  context: McpToolContext,
+): Promise<string | McpToolResult> {
+  const answer = await askProjectChild(cwd, { op: "tool", name, args }, { context })
+  if (!answer.ok) throw new Error(answer.message)
+  if ("result" in answer) return answer.result
+  throw new Error(`[nifra] the project process answered ${name} without a result`)
+}
+
+async function readResource(
+  cwd: string,
+  uri: string,
+): Promise<{ readonly text: string; readonly mimeType?: string }> {
+  const answer = await askProjectChild(
+    cwd,
+    { op: "resource", uri },
+    { timeoutMs: CHILD_TIMEOUT_MS },
+  )
+  if (!answer.ok) throw new Error(answer.message)
+  if ("resource" in answer) return answer.resource
+  throw new Error(`[nifra] the project process answered ${uri} without its text`)
+}
+
+async function getPrompt(
+  cwd: string,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<readonly McpPromptMessage[]> {
+  const answer = await askProjectChild(
+    cwd,
+    { op: "prompt", name, args },
+    { timeoutMs: CHILD_TIMEOUT_MS },
+  )
+  if (!answer.ok) throw new Error(answer.message)
+  if ("messages" in answer) return answer.messages
+  throw new Error(`[nifra] the project process answered ${name} without messages`)
+}
+
+/** Each tool runs in a fresh project subprocess, unless it is one that runs no project code here. */
+export function isolateTools(cwd: string, tools: readonly McpTool[]): McpTool[] {
+  return tools.map((tool) =>
+    IN_PROCESS_TOOLS.has(tool.name)
+      ? tool
+      : { ...tool, handler: (args, context) => callTool(cwd, tool.name, args, context) },
+  )
+}
+
+/** Each resource is read in a fresh project subprocess. */
+export function isolateResources(cwd: string, resources: readonly McpResource[]): McpResource[] {
+  return resources.map((resource) => ({ ...resource, read: () => readResource(cwd, resource.uri) }))
+}
+
+/** The app's own tools, resources and prompts, each forwarded to a project subprocess. */
+export interface IsolatedSurface {
+  readonly tools: readonly McpTool[]
+  readonly resources: readonly McpResource[]
+  readonly prompts: readonly McpPrompt[]
+}
+
+const EMPTY_SURFACE: AppSurface = { tools: [], resources: [], prompts: [] }
+
+async function readSurface(cwd: string): Promise<IsolatedSurface> {
+  const answer = await askProjectChild(cwd, { op: "surface" }, { timeoutMs: CHILD_TIMEOUT_MS })
+  const surface = answer.ok && "surface" in answer ? answer.surface : EMPTY_SURFACE
+  return {
+    tools: surface.tools.map((tool) => ({
+      ...tool,
+      handler: (args, context) => callTool(cwd, tool.name, args, context),
+    })),
+    resources: surface.resources.map((resource) => ({
+      ...resource,
+      read: () => readResource(cwd, resource.uri),
+    })),
+    prompts: surface.prompts.map((prompt) => ({
+      ...prompt,
+      handler: (args) => getPrompt(cwd, prompt.name, args),
+    })),
+  }
+}
+
+/**
+ * What the app declares on its backend (`app.tool(...)` and its resources and prompts), read in a
+ * project subprocess and kept until `nifra.config.ts`, `backend/framework.ts` or `backend/app.ts`
+ * changes. An app that cannot be loaded declares nothing: its absence must not withdraw the built-in
+ * tools, and a broken app must not start a subprocess on every message.
+ */
+export function createAppSurface(cwd: string): () => Promise<IsolatedSurface> {
+  let cached:
+    | { readonly fingerprint: string; readonly surface: Promise<IsolatedSurface> }
+    | undefined
+  return async () => {
+    const fingerprint = await appFingerprint(cwd).catch(() => "unreadable")
+    if (cached?.fingerprint !== fingerprint) {
+      cached = { fingerprint, surface: readSurface(cwd) }
+    }
+    return cached.surface
+  }
+}
+
+/**
+ * `detectMonorepo`, with the root config evaluated in a project subprocess. Only a directory with a
+ * `nifra.config.ts` and no `routes/` can be a monorepo root, so no other directory starts one.
+ */
+export async function detectMonorepoIsolated(cwd: string): Promise<NifraMonorepoConfig | null> {
+  if (!existsSync(resolve(cwd, CONFIG_FILE)) || existsSync(resolve(cwd, "routes"))) return null
+  const answer = await askProjectChild(cwd, { op: "monorepo" }, { timeoutMs: CHILD_TIMEOUT_MS })
+  if (!answer.ok || !("apps" in answer) || answer.apps === null) return null
+  const apps = Object.entries(answer.apps).filter(
+    (entry): entry is [string, string] => typeof entry[1] === "string",
+  )
+  return { apps: Object.fromEntries(apps) }
+}

package/src/mcp-project-child.ts

@@ -0,0 +1,182 @@
+/**
+ * The subprocess `nifra mcp` runs project code in. The server (`mcp-isolate.ts`) spawns a fresh one
+ * per call in the project's directory, so Bun loads that directory's `.env` files here, and the
+ * config, the backend and everything they import run here and exit with the process. The tools,
+ * resources and prompts answered here are the same ones the server lists: the project tools, and the
+ * ones the app declares on its backend.
+ *
+ * Protocol: one JSON request on stdin; on stdout, progress lines and then one answer line, each
+ * prefixed with the request's token, so anything project code prints cannot be read as an answer.
+ */
+
+import { detectMonorepo } from "./load.ts"
+import { projectResources } from "./mcp-context.ts"
+import { createCachedAppLoader, projectTools } from "./mcp-exec.ts"
+import { CHILD_INPUT_MAX_BYTES, readBoundedStream } from "./mcp-io.ts"
+import type {
+  McpPrompt,
+  McpPromptMessage,
+  McpResource,
+  McpTool,
+  McpToolResult,
+} from "./mcp-protocol.ts"
+import {
+  extractBackendPrompts,
+  extractBackendResources,
+  extractBackendTools,
+} from "./mcp-reflect.ts"
+
+export type ProjectChildRequest =
+  | { readonly op: "monorepo" }
+  | { readonly op: "surface" }
+  | { readonly op: "tool"; readonly name: string; readonly args: Record<string, unknown> }
+  | { readonly op: "resource"; readonly uri: string }
+  | { readonly op: "prompt"; readonly name: string; readonly args: Record<string, unknown> }
+
+/** What the server lists for the tools, resources and prompts the app declares on its backend. */
+export interface AppSurface {
+  readonly tools: readonly Omit<McpTool, "handler">[]
+  readonly resources: readonly Omit<McpResource, "read">[]
+  readonly prompts: readonly Omit<McpPrompt, "handler">[]
+}
+
+export type ProjectChildAnswer =
+  | { readonly ok: true; readonly apps: Readonly<Record<string, string>> | null }
+  | { readonly ok: true; readonly surface: AppSurface }
+  | { readonly ok: true; readonly result: string | McpToolResult }
+  | { readonly ok: true; readonly resource: { readonly text: string; readonly mimeType?: string } }
+  | { readonly ok: true; readonly messages: readonly McpPromptMessage[] }
+  | { readonly ok: false; readonly message: string }
+
+export type ProjectChildMessage =
+  | { readonly type: "progress"; readonly progress: number; readonly total?: number }
+  | { readonly type: "answer"; readonly answer: ProjectChildAnswer }
+
+/**
+ * Answer `request` for the project at `cwd`. A tool, resource or prompt that throws answers
+ * `ok: false` with its message; an app that cannot be loaded declares nothing, as in the server.
+ */
+export async function answerProjectRequest(
+  cwd: string,
+  request: ProjectChildRequest,
+  reportProgress: (progress: number, total?: number) => void = () => {},
+): Promise<ProjectChildAnswer> {
+  try {
+    if (request.op === "monorepo") {
+      return { ok: true, apps: (await detectMonorepo(cwd))?.apps ?? null }
+    }
+    const loadAppCached = createCachedAppLoader(cwd)
+    const backend = (): Promise<unknown> =>
+      loadAppCached().then(
+        (app) => app.backend,
+        () => undefined,
+      )
+    if (request.op === "surface") {
+      const declared = await backend()
+      return {
+        ok: true,
+        surface: {
+          tools: extractBackendTools(declared),
+          resources: extractBackendResources(declared),
+          prompts: extractBackendPrompts(declared),
+        },
+      }
+    }
+    if (request.op === "tool") {
+      const tool =
+        projectTools(cwd, loadAppCached).find((t) => t.name === request.name) ??
+        extractBackendTools(await backend()).find((t) => t.name === request.name)
+      if (tool === undefined) return { ok: false, message: `unknown tool: ${request.name}` }
+      const result = await tool.handler(request.args, {
+        signal: new AbortController().signal,
+        requestId: null,
+        reportProgress,
+      })
+      return { ok: true, result }
+    }
+    if (request.op === "resource") {
+      const resource =
+        projectResources(cwd, loadAppCached).find((r) => r.uri === request.uri) ??
+        extractBackendResources(await backend()).find((r) => r.uri === request.uri)
+      if (resource === undefined) return { ok: false, message: `unknown resource: ${request.uri}` }
+      return { ok: true, resource: await resource.read() }
+    }
+    const prompt = extractBackendPrompts(await backend()).find((p) => p.name === request.name)
+    if (prompt === undefined) return { ok: false, message: `unknown prompt: ${request.name}` }
+    return { ok: true, messages: await prompt.handler(request.args) }
+  } catch (error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+const isArgs = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+function parseRequest(text: string): { token: string; request: ProjectChildRequest } | undefined {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  if (!isArgs(value)) return undefined
+  const { token, op, name, uri, args } = value
+  if (typeof token !== "string" || !/^[0-9a-f-]{16,64}$/.test(token)) return undefined
+  if (op === "monorepo" || op === "surface") return { token, request: { op } }
+  if (op === "resource" && typeof uri === "string") return { token, request: { op, uri } }
+  if ((op === "tool" || op === "prompt") && typeof name === "string" && isArgs(args)) {
+    return { token, request: { op, name, args } }
+  }
+  return undefined
+}
+
+/**
+ * Serve one request: read it from `input`, answer it and write each message through `write`,
+ * prefixed with the request's token. Returns false (writing nothing) for a malformed request.
+ */
+export async function serveProjectChild(
+  cwd: string,
+  input: ReadableStream<Uint8Array>,
+  write: (line: string) => Promise<void>,
+): Promise<boolean> {
+  const text = await readBoundedStream(input, CHILD_INPUT_MAX_BYTES)
+  const parsed = text.truncated ? undefined : parseRequest(text.text)
+  if (parsed === undefined) return false
+  const send = (message: ProjectChildMessage): Promise<void> =>
+    write(`${parsed.token} ${JSON.stringify(message)}\n`)
+  const answer = await answerProjectRequest(cwd, parsed.request, (progress, total) => {
+    void send(
+      total === undefined ? { type: "progress", progress } : { type: "progress", progress, total },
+    )
+  })
+  let line: string
+  try {
+    line = JSON.stringify({ type: "answer", answer } satisfies ProjectChildMessage)
+  } catch {
+    line = JSON.stringify({
+      type: "answer",
+      answer: { ok: false, message: "the answer is not serializable" },
+    } satisfies ProjectChildMessage)
+  }
+  await write(`${parsed.token} ${line}\n`)
+  return true
+}
+
+if (import.meta.main) {
+  // Bound before project code loads, so nothing it patches can reach the protocol channel.
+  const stdout = process.stdout.write.bind(process.stdout)
+  const toStderr = (...args: unknown[]): void => {
+    process.stderr.write(`${args.map((arg) => String(arg)).join(" ")}\n`)
+  }
+  console.log = toStderr
+  console.info = toStderr
+  console.debug = toStderr
+  const served = await serveProjectChild(
+    process.argv[2] ?? process.cwd(),
+    Bun.stdin.stream(),
+    (line) => new Promise((done) => stdout(line, () => done())),
+  )
+  if (!served) process.stderr.write("nifra mcp: invalid project request\n")
+  // Project code may leave a handle open (a pool, an interval); the answer is written, so stop here.
+  process.exit(served ? 0 : 2)
+}

package/src/mcp-render.ts

@@ -10,7 +10,6 @@
  * `{ 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"
@@ -22,6 +21,7 @@ import {
   readBoundedStream,
   serializeBoundedJson,
 } from "./mcp-io.ts"
+import { frameworkWebAppOptions } from "./web-app-options.ts"
 
 const errString = (err: unknown): string =>
   err instanceof Error ? `${err.name}: ${err.message}` : String(err)
@@ -54,7 +54,7 @@ async function buildWebApp(cwd: string): Promise<{ app: AppLike } | { error: str
       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) } : {}),
+      ...frameworkWebAppOptions(app.framework, app.backend),
     }) as unknown as AppLike
     return { app: webApp }
   } catch (err) {