@nifrajs/cli 3.3.0 → 4.0.0

package/src/mcp-http.ts

@@ -29,7 +29,7 @@ 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 = "3.3.0"
+const VERSION = "4.0.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>
@@ -40,10 +40,12 @@ const docsHealth = (tools: McpTool[]): string =>
 /** The project-independent tools, reading the package's bundled corpus from disk (CLI use): the text
  * docs tools plus the `nifra_gallery` MCP Apps widget tool. */
 export function publicDocsTools(): McpTool[] {
-  return [
-    ...docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus),
-    examplesAppTool(loadExamplesCorpus),
-  ]
+  return [...openAiDocsTools(), examplesAppTool(loadExamplesCorpus)]
+}
+
+/** The text-only tool surface used by the public OpenAI Agent Plugin package. */
+function openAiDocsTools(): McpTool[] {
+  return docsTools(loadDocsCorpus, loadExamplesCorpus, loadTypesCorpus)
 }
 
 /**
@@ -59,9 +61,21 @@ export function respondMcpHttp(
   return respondMcpHttpCore(request, tools, SERVER_INFO, { health: docsHealth(tools), ...options })
 }
 
+/** The text-only handler used by the OpenAI Agent Plugin surface. */
+function handleOpenAiMcpHttp(request: Request): Promise<Response> {
+  return respondMcpHttp(request, openAiDocsTools(), {
+    features: {
+      instructions:
+        "Nifra's public documentation tools for the OpenAI plugin. The server is stateless, read-only, and limited to Nifra's bundled documentation corpus, verified examples, API types, learning path, and frontend guidance.",
+    },
+    allowAnyOrigin: true,
+  })
+}
+
 /** The CLI HTTP handler: serves the disk-backed corpus tools + registers the examples widget's `ui://`
  * resource so MCP Apps hosts can render `nifra_gallery`. (`nifra docs-mcp` / `bun run` this file.) */
 export function handleMcpHttp(request: Request): Promise<Response> {
+  if (new URL(request.url).pathname === "/openai") return handleOpenAiMcpHttp(request)
   return respondMcpHttp(request, publicDocsTools(), {
     features: {
       resources: [examplesWidget.resource],
@@ -69,6 +83,9 @@ export function handleMcpHttp(request: Request): Promise<Response> {
       instructions:
         "nifra's own documentation, runnable examples, and API types - for building with the nifra framework. Call nifra_docs / nifra_example / nifra_types / nifra_learn to learn it without a local checkout.",
     },
+    // This is the intentionally public, secret-free docs server. Other MCP mounts use the
+    // transport's same-origin default unless they explicitly opt into public cross-origin access.
+    allowAnyOrigin: true,
   })
 }
 

package/src/mcp-io.ts

@@ -8,6 +8,8 @@
 export const CHILD_TIMEOUT_MS = 30_000
 /** Maximum stdout or stderr retained from a project subprocess. The process is killed at the limit. */
 export const CHILD_OUTPUT_MAX_BYTES = 1_048_576
+/** Maximum serialized request sent to a project subprocess or warm worker. */
+export const CHILD_INPUT_MAX_BYTES = 4 * 1024 * 1024
 
 /** 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. */
@@ -81,6 +83,134 @@ export interface BoundedOutput {
   readonly truncated: boolean
 }
 
+export type BoundedLine =
+  | { readonly kind: "line"; readonly text: string }
+  | { readonly kind: "too-large" }
+
+function decodeLine(chunks: readonly Uint8Array[], totalBytes: number): string {
+  const bytes = new Uint8Array(totalBytes)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return new TextDecoder().decode(bytes)
+}
+
+/** Read newline-delimited input without retaining a line larger than the configured byte budget. */
+export async function* readBoundedLines(
+  stream: ReadableStream<Uint8Array>,
+  maxBytes = CHILD_INPUT_MAX_BYTES,
+): AsyncGenerator<BoundedLine> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    throw new RangeError("maxBytes must be a positive safe integer")
+  const chunks: Uint8Array[] = []
+  let totalBytes = 0
+  let tooLarge = false
+  for await (const raw of stream) {
+    const value = raw as Uint8Array
+    let start = 0
+    while (start < value.byteLength) {
+      const newline = value.indexOf(0x0a, start)
+      const end = newline === -1 ? value.byteLength : newline
+      const segment = value.subarray(start, end)
+      if (!tooLarge) {
+        if (totalBytes + segment.byteLength > maxBytes) {
+          tooLarge = true
+          chunks.length = 0
+          totalBytes = 0
+        } else if (segment.byteLength > 0) {
+          chunks.push(segment)
+          totalBytes += segment.byteLength
+        }
+      }
+      if (newline === -1) break
+      if (tooLarge) yield { kind: "too-large" }
+      else yield { kind: "line", text: decodeLine(chunks, totalBytes) }
+      chunks.length = 0
+      totalBytes = 0
+      tooLarge = false
+      start = newline + 1
+    }
+  }
+  if (tooLarge) yield { kind: "too-large" }
+  else if (totalBytes > 0) yield { kind: "line", text: decodeLine(chunks, totalBytes) }
+}
+
+/** Serialize a JSON value only when its UTF-8 representation fits within the byte budget. */
+export function serializeBoundedJson(
+  value: unknown,
+  maxBytes: number,
+  space?: string | number,
+): string | undefined {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) return undefined
+  let text: string | undefined
+  try {
+    text = JSON.stringify(value, null, space)
+  } catch {
+    return undefined
+  }
+  if (text === undefined || new TextEncoder().encode(text).byteLength > maxBytes) return undefined
+  return text
+}
+
+/** What {@link readHeadTail} kept: the start and end of a stream, and how many bytes fell between. */
+export interface HeadTailOutput {
+  readonly head: string
+  readonly tail: string
+  /** Bytes dropped between `head` and `tail`; when 0, `head + tail` is the whole stream. */
+  readonly droppedBytes: number
+}
+
+/**
+ * Drain a stream to its end, keeping at most `headBytes` from its start and `tailBytes` from its end,
+ * so a child that prints without limit costs bounded memory and still runs to completion.
+ */
+export async function readHeadTail(
+  stream: ReadableStream<Uint8Array>,
+  headBytes: number,
+  tailBytes: number,
+): Promise<HeadTailOutput> {
+  const head: Uint8Array[] = []
+  let headSize = 0
+  const tail: Uint8Array[] = []
+  let tailSize = 0
+  let droppedBytes = 0
+  for await (let chunk of stream) {
+    if (headSize < headBytes) {
+      const taken = chunk.subarray(0, headBytes - headSize)
+      head.push(taken)
+      headSize += taken.byteLength
+      chunk = chunk.subarray(taken.byteLength)
+    }
+    if (chunk.byteLength === 0) continue
+    tail.push(chunk)
+    tailSize += chunk.byteLength
+    while (tailSize > tailBytes) {
+      const first = tail[0]!
+      const excess = tailSize - tailBytes
+      if (first.byteLength <= excess) {
+        tail.shift()
+        tailSize -= first.byteLength
+        droppedBytes += first.byteLength
+      } else {
+        tail[0] = first.subarray(excess)
+        tailSize -= excess
+        droppedBytes += excess
+      }
+    }
+  }
+  const decode = (chunks: readonly Uint8Array[]): string => Buffer.concat(chunks).toString("utf8")
+  return { head: decode(head), tail: decode(tail), droppedBytes }
+}
+
+/** A {@link HeadTailOutput} as one string, marking where bytes were dropped. */
+export function joinHeadTail(output: HeadTailOutput): string {
+  return output.droppedBytes === 0
+    ? output.head + output.tail
+    : `${output.head}\n…(${output.droppedBytes} bytes omitted)…\n${output.tail}`
+}
+
 /** Read child output incrementally and cancel as soon as the byte budget is crossed. */
 export async function readBoundedStream(
   stream: ReadableStream<Uint8Array>,

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-path.ts

@@ -0,0 +1,50 @@
+import { realpathSync } from "node:fs"
+import { basename, isAbsolute, relative, resolve } from "node:path"
+
+/**
+ * Resolve an MCP path without allowing lexical or symlink escapes from the selected project.
+ *
+ * MCP callers are not equivalent to a local CLI user: the selected checkout is their filesystem
+ * capability boundary. The nearest-existing-ancestor walk also supports output files that do not
+ * exist yet while still canonicalizing every existing path component.
+ */
+export function resolveMcpProjectPath(root: string, value: string): string | null {
+  if (value.length === 0 || isAbsolute(value)) return null
+
+  const lexicalRoot = resolve(root)
+  const target = resolve(lexicalRoot, value)
+  const lexicalRelative = relative(lexicalRoot, target)
+  if (lexicalRelative.startsWith("..") || isAbsolute(lexicalRelative)) return null
+
+  let canonicalRoot: string
+  try {
+    canonicalRoot = realpathSync(lexicalRoot)
+  } catch {
+    return null
+  }
+
+  let probe = target
+  const missing: string[] = []
+  while (true) {
+    try {
+      const canonicalProbe = realpathSync(probe)
+      const canonicalRelative = relative(canonicalRoot, canonicalProbe)
+      if (canonicalRelative.startsWith("..") || isAbsolute(canonicalRelative)) return null
+
+      const candidate = resolve(canonicalProbe, ...missing.reverse())
+      const candidateRelative = relative(canonicalRoot, candidate)
+      return candidateRelative.startsWith("..") || isAbsolute(candidateRelative) ? null : candidate
+    } catch (error) {
+      if (!(error && typeof error === "object" && (error as { code?: string }).code === "ENOENT"))
+        return null
+      const parent = resolve(probe, "..")
+      if (parent === probe) return null
+      missing.push(basename(probe))
+      probe = parent
+    }
+  }
+}
+
+export function mcpProjectPathError(label: string, value: string): string {
+  return `${label} must be a relative path inside the selected project directory: ${value}`
+}