@nifrajs/cli 3.5.0 → 4.0.0

package/src/mcp-root.ts

@@ -5,9 +5,12 @@
  *   1. An explicit `nifra mcp <dir>` argument is taken literally (human configuration wins).
  *   2. A cwd guess walks UP to the nearest nifra marker (a `package.json` depending on `@nifrajs/*`,
  *      or a `nifra.config.ts` monorepo root), so running from a subdirectory still finds the project.
+ *      When nothing above is a project but the spawn directory is a package-manager workspace root
+ *      (`package.json` `workspaces`) with exactly one nifra member, the server adopts that member.
  *   3. The client's MCP `roots` (its workspace folders) are requested after the handshake. When the
  *      guess found no project - or found one DISJOINT from every workspace root - and exactly one
- *      workspace root is a nifra project, the server adopts it.
+ *      workspace root (or one member of a workspace-root folder) is a nifra project, the server
+ *      adopts it.
  *   4. What cannot be resolved fails CLOSED: project-scoped tools refuse with a remediation message
  *      instead of describing whatever directory the server happened to start in.
  *
@@ -15,12 +18,13 @@
  */
 
 import { readFile } from "node:fs/promises"
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 
 /** How the current root was chosen. `arg` = explicit `nifra mcp <dir>`; `cwd` = the spawn directory;
- * `parent` = a marker found walking up from cwd; `client-root` = adopted from the client's MCP roots. */
-export type McpRootSource = "arg" | "cwd" | "parent" | "client-root"
+ * `parent` = a marker found walking up from cwd; `workspace` = the one nifra member of the spawn
+ * directory's package-manager workspaces; `client-root` = adopted from the client's MCP roots. */
+export type McpRootSource = "arg" | "cwd" | "parent" | "workspace" | "client-root"
 
 export interface McpRootState {
   /** Absolute directory every project-scoped tool operates on. */
@@ -31,11 +35,17 @@ export interface McpRootState {
   /** The client's workspace roots (absolute paths), or `null` until (unless) the client answers
    * `roots/list`. `null` disables mismatch detection - no data is not a mismatch. */
   readonly clientRoots: readonly string[] | null
+  /** Nifra members of the spawn directory's workspaces when there were several to choose from - the
+   * remediation list, since adopting one of them would be a guess. */
+  readonly workspaceCandidates?: readonly string[]
 }
 
 const MAX_CLIENT_ROOTS = 64
 const MAX_ROOT_URI_LENGTH = 16_384
 const MAX_ROOT_PATH_LENGTH = 4_096
+/** Workspace members probed per workspace root. A monorepo larger than this is pointed at explicitly
+ * (`nifra mcp <dir>`) rather than scanned on every server start. */
+const MAX_WORKSPACE_MEMBERS = 256
 
 /** A directory is a nifra project when its `package.json` depends on any `@nifrajs/*` package, or it
  * is a `nifra.config.ts` monorepo root. Backend-only projects (no web config, no `routes/`) count -
@@ -69,8 +79,56 @@ export async function findNifraRoot(start: string): Promise<string | null> {
   }
 }
 
+/** The `workspaces` globs a `package.json` declares (the array form, or Yarn's `{ packages }`), or
+ * `null` when the directory is not a workspace root. Negated patterns are dropped: they only exclude. */
+async function workspacePatterns(dir: string): Promise<readonly string[] | null> {
+  let field: unknown
+  try {
+    field = (
+      JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as Record<string, unknown>
+    ).workspaces
+  } catch {
+    return null
+  }
+  const list = Array.isArray(field)
+    ? field
+    : typeof field === "object" && field !== null
+      ? (field as { packages?: unknown }).packages
+      : undefined
+  if (!Array.isArray(list)) return null
+  return list.filter(
+    (pattern): pattern is string =>
+      typeof pattern === "string" && pattern !== "" && !pattern.startsWith("!"),
+  )
+}
+
+/**
+ * The nifra projects among `dir`'s package-manager workspace members, in declaration order. Empty when
+ * `dir` declares no `workspaces`. A member is a directory a pattern matches that holds a `package.json`;
+ * `node_modules` is never a member.
+ */
+export async function workspaceProjects(dir: string): Promise<string[]> {
+  const patterns = await workspacePatterns(dir)
+  if (patterns === null) return []
+  const members = new Set<string>()
+  let probed = 0
+  for (const pattern of patterns) {
+    const glob = new Bun.Glob(`${pattern.replace(/\/+$/, "")}/package.json`)
+    for await (const match of glob.scan({ cwd: dir, onlyFiles: true })) {
+      if (match.split(/[\\/]/).includes("node_modules")) continue
+      if (++probed > MAX_WORKSPACE_MEMBERS) break
+      members.add(dirname(join(dir, match)))
+    }
+    if (probed > MAX_WORKSPACE_MEMBERS) break
+  }
+  const projects: string[] = []
+  for (const member of members) if (await isNifraProjectDir(member)) projects.push(member)
+  return projects
+}
+
 /** Initial root state. An explicit dir is taken literally (no walk-up - the human named it); a cwd
- * guess walks up so a subdirectory spawn still lands on the project. */
+ * guess walks up so a subdirectory spawn still lands on the project, then tries the spawn directory's
+ * workspace members so a monorepo root finds its one nifra app. */
 export async function resolveRootState(
   requested: string,
   explicit: boolean,
@@ -92,7 +150,17 @@ export async function resolveRootState(
       clientRoots: null,
     }
   }
-  return { root: requested, source: "cwd", isProject: false, clientRoots: null }
+  const members = await workspaceProjects(requested)
+  if (members.length === 1) {
+    return { root: members[0] as string, source: "workspace", isProject: true, clientRoots: null }
+  }
+  return {
+    root: requested,
+    source: "cwd",
+    isProject: false,
+    clientRoots: null,
+    ...(members.length > 1 ? { workspaceCandidates: members } : {}),
+  }
 }
 
 /** `file://` roots from a `roots/list` result, as absolute paths. Non-file and malformed URIs are
@@ -151,9 +219,9 @@ export function rootMismatch(state: McpRootState): boolean {
 /**
  * Fold the client's workspace roots into the state, adopting one of them when the current root is
  * wrong and the correction is unambiguous: the root was GUESSED (never an explicit `nifra mcp <dir>`),
- * it is not a project - or is one disjoint from the whole workspace - and exactly ONE workspace root
- * is a nifra project. Ambiguity (zero or several candidates) adopts nothing; the guard's remediation
- * message lists the candidates instead.
+ * it is not a project - or is one disjoint from the whole workspace - and exactly ONE candidate exists
+ * (see {@link nifraCandidates}). Ambiguity (zero or several candidates) adopts nothing; the guard's
+ * remediation message lists the candidates instead.
  */
 export async function applyClientRoots(
   state: McpRootState,
@@ -162,8 +230,7 @@ export async function applyClientRoots(
   const next: McpRootState = { ...state, clientRoots: paths }
   if (state.source === "arg") return next
   if (next.isProject && !rootMismatch(next)) return next
-  const candidates: string[] = []
-  for (const path of paths) if (await isNifraProjectDir(path)) candidates.push(path)
+  const candidates = await nifraCandidates(paths)
   if (candidates.length !== 1) return next
   return {
     root: candidates[0] as string,
@@ -173,11 +240,15 @@ export async function applyClientRoots(
   }
 }
 
-/** The nifra project roots among the client's workspace roots - the remediation list when adoption
- * was ambiguous. */
+/** The nifra projects the client's workspace roots name: each root that is a project itself, and
+ * otherwise the nifra members of a root that is a package-manager workspace. The remediation list
+ * when adoption was ambiguous. */
 export async function nifraCandidates(paths: readonly string[]): Promise<string[]> {
   const candidates: string[] = []
-  for (const path of paths) if (await isNifraProjectDir(path)) candidates.push(path)
+  for (const path of paths) {
+    if (await isNifraProjectDir(path)) candidates.push(path)
+    else for (const member of await workspaceProjects(path)) candidates.push(member)
+  }
   return candidates
 }
 
@@ -198,10 +269,15 @@ export async function rootVerdict(state: McpRootState): Promise<McpRootVerdict>
       ? ` Client workspace roots: ${state.clientRoots.join(", ")}.`
       : ""
   if (!state.isProject) {
-    const candidates = state.clientRoots !== null ? await nifraCandidates(state.clientRoots) : []
+    const candidates = [
+      ...new Set([
+        ...(state.workspaceCandidates ?? []),
+        ...(state.clientRoots !== null ? await nifraCandidates(state.clientRoots) : []),
+      ]),
+    ]
     const hint =
       candidates.length > 1
-        ? ` Several workspace roots are nifra projects (${candidates.join(", ")}) - pass one: \`nifra mcp <dir>\`.`
+        ? ` Several workspace folders are nifra projects (${candidates.join(", ")}) - pass one: \`nifra mcp <dir>\`.`
         : ""
     return {
       blocked:
@@ -250,7 +326,8 @@ export interface ToolingDrift {
 export const driftNote = (drift: ToolingDrift): string =>
   `WARNING: this server runs nifra CLI ${drift.cli}, but the project installs ${drift.package} ${drift.project}. ` +
   "Types, checks, and docs may describe a different version than your code builds with. " +
-  "Fix: run the project's own CLI (`bunx --bun nifra mcp` from the project directory, or point the client at ./node_modules/.bin/nifra)."
+  `Fix: re-pin the project's MCP launch to the nifra it installs with \`${syncMcpCommand(drift.cli)}\` (run in the project directory), then restart the agent. ` +
+  "If this server is not launched from the project's .mcp.json, run the project's own CLI instead (`bunx --bun nifra mcp` from the project directory, or point the client at ./node_modules/.bin/nifra)."
 
 /** Feature-level agreement. Patch drift is not reported: it never changes the surface being described. */
 const featureVersion = (version: string): string => version.split(".").slice(0, 2).join(".")
@@ -285,16 +362,34 @@ export async function detectToolingDrift(
   root: string,
   cliVersion: string,
 ): Promise<ToolingDrift | undefined> {
+  const installed = await installedNifraVersion(root)
+  if (installed === undefined) return undefined
+  return featureVersion(installed.version) === featureVersion(cliVersion)
+    ? undefined
+    : { cli: cliVersion, project: installed.version, package: installed.package }
+}
+
+/**
+ * The nifra the project builds with: its `@nifrajs/cli` when installed, else its `@nifrajs/core`
+ * (`fixed` versioning keeps the two in lockstep, so either names the CLI that matches the project).
+ * The version drift detection compares against and the version `init-agents --sync-mcp` pins to.
+ */
+export async function installedNifraVersion(
+  root: string,
+): Promise<{ readonly package: string; readonly version: string } | undefined> {
   for (const name of ["@nifrajs/cli", "@nifrajs/core"]) {
-    const project = await installedVersion(root, name)
-    if (project === undefined) continue
-    return featureVersion(project) === featureVersion(cliVersion)
-      ? undefined
-      : { cli: cliVersion, project, package: name }
+    const version = await installedVersion(root, name)
+    if (version !== undefined) return { package: name, version }
   }
   return undefined
 }
 
+/** The command that re-pins a project's MCP launch to the nifra it installs. Named with the running
+ * CLI's own exact version: the binary printing this is the one known to have `--sync-mcp`, and it pins
+ * to the project's version, not its own. */
+export const syncMcpCommand = (cliVersion: string): string =>
+  `bunx @nifrajs/cli@${cliVersion} init-agents --sync-mcp`
+
 /** Tool names served from the bundled corpus; they do not depend on the project root. */
 const PROJECT_FREE_TOOLS = new Set(["nifra_docs", "nifra_example", "nifra_types", "nifra_learn"])
 

package/src/mcp-run.ts

@@ -8,7 +8,16 @@
 import { existsSync, realpathSync } from "node:fs"
 import { isAbsolute, relative, resolve, sep } from "node:path"
 import { pathToFileURL } from "node:url"
-import { type AppLike, runApp } from "@nifrajs/runner"
+import { type AppLike, type RequestSpec, type RunResult, runApp } from "@nifrajs/runner"
+import {
+  captureInto,
+  createDevFeed,
+  type DevFeed,
+  type DevLogLevel,
+  runWithDevRequest,
+} from "@nifrajs/web/dev-feed"
+import type { Diagnostic } from "@nifrajs/web/diagnostic"
+import { BACKEND_APP_FILE } from "./app-files.ts"
 import {
   CHILD_INPUT_MAX_BYTES,
   CHILD_OUTPUT_MAX_BYTES,
@@ -17,7 +26,7 @@ import {
   serializeBoundedJson,
 } from "./mcp-io.ts"
 
-const ENTRY_CANDIDATES = ["backend.ts", "app.ts", "src/backend.ts", "src/app.ts"]
+const ENTRY_CANDIDATES = [BACKEND_APP_FILE, "app.ts", "src/app.ts"]
 
 const errString = (err: unknown): string =>
   err instanceof Error ? `${err.name}: ${err.message}` : String(err)
@@ -85,12 +94,75 @@ export async function runBackend(
   if ("error" in loaded) return loaded
 
   try {
-    return { results: await runApp(loaded.app, requests as Parameters<typeof runApp>[1]) }
+    return { results: await runCaptured(cwd, loaded.app, requests) }
   } catch (err) {
     return { error: errString(err) }
   }
 }
 
+/** What `nifra_run` adds to the runner's result: what the app printed, and what failed, structured. */
+export interface RunCapture {
+  readonly logs?: ReadonlyArray<{ readonly level: DevLogLevel; readonly message: string }>
+  readonly errors?: readonly Diagnostic[]
+}
+
+const MAX_LOGS_PER_REQUEST = 100
+
+/**
+ * Run `requests` one at a time, each inside its own request context, so what a handler logs - and
+ * core's `unhandled request error` line behind a bare 500 - lands on the result of the request that
+ * produced it, redacted, with the error as a Diagnostic (codeframe, cause, fix). Without this a 500 came
+ * back as `internal_error` and the reason only ever reached a stderr nobody reads.
+ */
+export async function runCaptured(
+  cwd: string,
+  app: AppLike,
+  requests: readonly unknown[],
+): Promise<Array<RunResult & RunCapture>> {
+  const feed = createDevFeed({ root: cwd, persist: false })
+  const detach = captureInto(feed)
+  const runs: Array<{ readonly requestId: string; readonly result: RunResult }> = []
+  try {
+    for (const [index, spec] of requests.entries()) {
+      const requestId = `run${index + 1}`
+      const [method, path] = describeSpec(spec)
+      const [result] = await runWithDevRequest(
+        { feedId: feed.id, requestId, method, path },
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: runApp validates each spec itself and reports a malformed one as that request's error.
+        () => runApp(app, [spec as RequestSpec]),
+      )
+      if (result !== undefined) runs.push({ requestId, result })
+    }
+    // A line a handler scheduled for later (a promise continuation, a 0 ms timer) still lands.
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  } finally {
+    detach()
+  }
+  return runs.map(({ requestId, result }) => withCapture(feed, requestId, result))
+}
+
+function describeSpec(spec: unknown): [string, string] {
+  if (typeof spec !== "object" || spec === null) return ["GET", "/"]
+  const method = "method" in spec && typeof spec.method === "string" ? spec.method : "GET"
+  const path = "path" in spec && typeof spec.path === "string" ? spec.path : "/"
+  return [method, path]
+}
+
+function withCapture(feed: DevFeed, requestId: string, result: RunResult): RunResult & RunCapture {
+  if (result.error !== undefined) {
+    const thrown = new Error(result.error.message)
+    thrown.name = result.error.name
+    if (result.error.stack !== undefined) thrown.stack = result.error.stack
+    feed.recordError(thrown, { category: "api", requestId })
+  }
+  const capture: { -readonly [K in keyof RunCapture]: RunCapture[K] } = {}
+  const logs = feed.logs({ requestId, limit: MAX_LOGS_PER_REQUEST }).logs
+  if (logs.length > 0) capture.logs = logs.map(({ level, message }) => ({ level, message }))
+  const errors = feed.errors({ requestId }).errors
+  if (errors.length > 0) capture.errors = errors.map((entry) => entry.diagnostic)
+  return { ...result, ...capture }
+}
+
 interface WorkerMessage {
   readonly id?: unknown
   readonly input?: { readonly requests?: unknown; readonly entry?: string }
@@ -113,13 +185,31 @@ function safeResponseId(value: unknown): number | string | null {
   return null
 }
 
-async function runWorker(cwd: string): Promise<void> {
+/**
+ * Keep stdout for the protocol. The app's console and any direct `process.stdout.write` go to stderr,
+ * or a stray `console.log` in a handler would corrupt the JSON the parent reads. Returns the writer
+ * that still reaches the real stdout.
+ */
+function reserveStdout(): (text: string) => void {
   redirectConsoleToStderr()
+  const original: unknown = Reflect.get(process.stdout, "write")
+  const write = typeof original === "function" ? original.bind(process.stdout) : undefined
+  // Bound now, before any capture patches stderr: a redirected stdout line is captured once, as stdout.
+  const toStderr = process.stderr.write.bind(process.stderr)
+  Reflect.set(process.stdout, "write", (chunk: unknown, ...rest: unknown[]) =>
+    Reflect.apply(toStderr, process.stderr, [chunk, ...rest]),
+  )
+  return (text) => {
+    write?.(text)
+  }
+}
+
+async function runWorker(cwd: string, protocol: (text: string) => void): Promise<void> {
   const apps = new Map<string, Promise<{ app: AppLike } | { error: string }>>()
   const send = (id: unknown, output: unknown): void => {
     const responseId = safeResponseId(id)
     const encoded = serializeBoundedJson({ id: responseId, output }, CHILD_OUTPUT_MAX_BYTES - 1)
-    process.stdout.write(
+    protocol(
       `${encoded ?? JSON.stringify({ id: responseId, output: { error: "worker output exceeded the size limit" } })}\n`,
     )
   }
@@ -175,9 +265,7 @@ async function runWorker(cwd: string): Promise<void> {
       continue
     }
     try {
-      send(id, {
-        results: await runApp(app.app, requests as Parameters<typeof runApp>[1]),
-      })
+      send(id, { results: await runCaptured(cwd, app.app, requests) })
     } catch (err) {
       send(id, { error: errString(err) })
     }
@@ -188,8 +276,9 @@ async function runWorker(cwd: string): Promise<void> {
 // this only executes when run directly (not when imported by a test).
 if (import.meta.main) {
   const cwd = process.argv[2] ?? process.cwd()
+  const protocol = reserveStdout()
   if (process.argv.includes("--worker")) {
-    await runWorker(cwd)
+    await runWorker(cwd, protocol)
     process.exit(0)
   }
   let output: unknown
@@ -207,8 +296,13 @@ if (import.meta.main) {
       output = { error: "invalid input: expected JSON { requests: [...] }" }
     }
   }
-  process.stdout.write(
+  // `Bun.write` to the fd, not the patched `process.stdout.write`, so the answer is flushed when it
+  // resolves. Then exit: the app's own handles (a pool, an interval) would keep this single-use
+  // process alive until the parent's timeout, and the parent waits for it to exit.
+  await Bun.write(
+    Bun.stdout,
     serializeBoundedJson(output, CHILD_OUTPUT_MAX_BYTES, 2) ??
       JSON.stringify({ error: `output exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes` }),
   )
+  process.exit(0)
 }

package/src/mcp-ws.ts

@@ -324,5 +324,8 @@ if (import.meta.main) {
       error: 'invalid input: expected JSON { "path": "/..." }',
     } satisfies WebSocketVerificationResult
   }
-  process.stdout.write(JSON.stringify(output, null, 2))
+  // Flushed, then exit: the app's own handles would keep this single-use process alive until the
+  // parent's timeout, as in mcp-run and mcp-render.
+  await Bun.write(Bun.stdout, JSON.stringify(output, null, 2))
+  process.exit(0)
 }