@nifrajs/cli 3.5.0 → 4.0.0

package/src/manifest-tool.ts

@@ -12,6 +12,7 @@ import {
   serializeNifraManifestSignature,
   signNifraManifest,
 } from "@nifrajs/core/manifest"
+import { codeUnitOrder } from "./internal/code-unit-order.ts"
 import { collectProjectVerification } from "./verification.ts"
 
 export const DEFAULT_MANIFEST_FILE = "nifra.manifest.json"
@@ -23,8 +24,8 @@ export function formatManifestDiff(diff: NifraManifestDiff): string {
     .sort(
       (a, b) =>
         weight[a.severity] - weight[b.severity] ||
-        a.path.localeCompare(b.path) ||
-        a.method.localeCompare(b.method),
+        codeUnitOrder(a.path, b.path) ||
+        codeUnitOrder(a.method, b.method),
     )
     .map(
       (change) =>

package/src/mcp-app-tool.ts

@@ -54,6 +54,8 @@ export function examplesAppTool(loadExamples: () => Promise<Example[] | undefine
     annotations: {
       title: "Browse the nifra example gallery",
       readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
       openWorldHint: false,
     },
     description:

package/src/mcp-context.ts

@@ -74,7 +74,7 @@ export function projectResources(
     {
       uri: "nifra://openapi",
       name: "OpenAPI 3.1",
-      description: "OpenAPI document generated from backend.ts using @nifrajs/schema.",
+      description: "OpenAPI document generated from backend/app.ts using @nifrajs/schema.",
       mimeType: "application/json",
       read: async () => ({ text: await openApiHandler({ format: "json" }, loadAppCached) }),
     },

package/src/mcp-delegate.ts

@@ -0,0 +1,162 @@
+/**
+ * One nifra per MCP session: the version the project installs.
+ *
+ * A client that spawns a globally installed `nifra mcp` against a project pinned to a different
+ * release gets types, checks, docs and contracts for a surface the project does not have - and every
+ * answer still reads as authoritative. So the server settles the version before it serves:
+ *
+ *   1. The project installs its own `@nifrajs/cli` at a different version: hand the whole session to
+ *      that CLI (`node_modules/.bin/nifra mcp`, stdio inherited) and step aside.
+ *   2. Handing off is impossible (no project CLI, a missing bin, or this process IS the hand-off and
+ *      the versions still disagree): serve, but the version-sensitive tools refuse with the fix
+ *      instead of answering for the wrong release.
+ */
+
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import type { McpTool, McpToolResult } from "./mcp-protocol.ts"
+import type { ToolingDrift } from "./mcp-root.ts"
+
+/** Set on the hand-off child so it never hands off again, whatever it finds. */
+export const MCP_DELEGATED_ENV = "NIFRA_MCP_DELEGATED"
+
+/** The tools whose answer is a property of the nifra release: they refuse under a version split. */
+export const VERSION_SENSITIVE_TOOLS: ReadonlySet<string> = new Set([
+  "nifra_check",
+  "nifra_types",
+  "nifra_docs",
+  "nifra_example",
+  "nifra_assure",
+  "nifra_contracts",
+])
+
+/** The project's own CLI: its version and, when the install linked one, its bin. */
+export interface ProjectCli {
+  readonly version: string
+  readonly bin?: string
+}
+
+const BIN_NAME = process.platform === "win32" ? "nifra.exe" : "nifra"
+const MAX_ANCESTOR_DIRS = 8
+
+/** The nearest `@nifrajs/cli` install at or above `root` (a monorepo app hoists to the repo root). */
+export async function findProjectCli(root: string): Promise<ProjectCli | undefined> {
+  let dir = root
+  for (let depth = 0; depth < MAX_ANCESTOR_DIRS; depth++) {
+    const modules = join(dir, "node_modules")
+    try {
+      const meta = JSON.parse(
+        await readFile(join(modules, "@nifrajs", "cli", "package.json"), "utf8"),
+      ) as { version?: unknown }
+      if (typeof meta.version === "string" && meta.version.length > 0) {
+        const bin = join(modules, ".bin", BIN_NAME)
+        return existsSync(bin) ? { version: meta.version, bin } : { version: meta.version }
+      }
+    } catch {
+      // Not installed at this level - keep walking up.
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+  return undefined
+}
+
+/**
+ * Hand this stdio session to the project's own CLI when it installs a different version. Resolves to
+ * the child's exit code once the session ends, or `undefined` when this process should serve itself
+ * (versions agree, no project CLI or bin, already a hand-off, or the spawn failed). Must run before
+ * anything reads stdin: the child inherits the descriptor and owns the whole conversation.
+ */
+export async function delegateToProjectCli(options: {
+  readonly cwd: string
+  readonly root: string
+  readonly version: string
+  readonly args: readonly string[]
+}): Promise<number | undefined> {
+  if (process.env[MCP_DELEGATED_ENV] === "1") return undefined
+  const cli = await findProjectCli(options.root)
+  if (cli === undefined || cli.version === options.version || cli.bin === undefined)
+    return undefined
+  return handOffSession([cli.bin, "mcp", ...options.args], {
+    cwd: options.cwd,
+    env: { ...process.env, [MCP_DELEGATED_ENV]: "1" },
+    announce: `[nifra] mcp: this CLI is ${options.version}; the project installs @nifrajs/cli ${cli.version} - serving this session from ${cli.bin}`,
+  })
+}
+
+/**
+ * Hand this stdio session to `command`: the child inherits stdin, stdout and stderr and owns the
+ * whole conversation, and this process forwards signals and waits. Resolves to the child's exit code,
+ * or `undefined` when it could not start. Must run before anything reads stdin.
+ */
+export async function handOffSession(
+  command: readonly string[],
+  options: {
+    readonly cwd: string
+    readonly env: Record<string, string | undefined>
+    /** Written to stderr once the child runs. */
+    readonly announce?: string
+  },
+): Promise<number | undefined> {
+  let child: ReturnType<typeof Bun.spawn>
+  try {
+    child = Bun.spawn([...command], {
+      cwd: options.cwd,
+      env: options.env,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    })
+  } catch {
+    return undefined
+  }
+  // stderr only: stdout is the JSON-RPC channel, and it now belongs to the child.
+  if (options.announce !== undefined) process.stderr.write(`${options.announce}\n`)
+  const forward = (signal: NodeJS.Signals) => () => child.kill(signal)
+  const onTerm = forward("SIGTERM")
+  const onInt = forward("SIGINT")
+  process.on("SIGTERM", onTerm)
+  process.on("SIGINT", onInt)
+  try {
+    return await child.exited
+  } finally {
+    process.off("SIGTERM", onTerm)
+    process.off("SIGINT", onInt)
+  }
+}
+
+const refusalFix = (drift: ToolingDrift): string =>
+  drift.package === "@nifrajs/cli"
+    ? "Fix: point the MCP client at the project's own CLI (`./node_modules/.bin/nifra mcp`, reinstalling if that file is missing), or restart this server from the project directory so it hands the session over."
+    : `Fix: add the matching CLI to the project (\`bun add -d @nifrajs/cli@${drift.project}\`) and restart the MCP server - it then hands the session to the project's CLI - or point the client at a nifra ${drift.project} install.`
+
+/** The in-band refusal a version-sensitive tool returns under a version split. */
+export const versionRefusal = (tool: string, drift: ToolingDrift): McpToolResult => ({
+  content: [
+    {
+      type: "text",
+      text:
+        `${tool} refused: this MCP server runs nifra CLI ${drift.cli}, but the project installs ${drift.package} ${drift.project}, ` +
+        `so its answer would describe a different nifra than your code builds with. ${refusalFix(drift)}`,
+    },
+  ],
+  isError: true,
+})
+
+/**
+ * Swap each version-sensitive tool's handler for the refusal while `drift` holds. Apply it before
+ * namespacing, so a monorepo's `nifra_<app>_check` refuses too. No drift: the tools pass through.
+ */
+export function refuseVersionSensitive(
+  tools: McpTool[],
+  drift: ToolingDrift | undefined,
+): McpTool[] {
+  if (drift === undefined) return tools
+  return tools.map((tool) =>
+    VERSION_SENSITIVE_TOOLS.has(tool.name)
+      ? { ...tool, handler: async () => versionRefusal(tool.name, drift) }
+      : tool,
+  )
+}

package/src/mcp-docs-tools.ts

@@ -28,7 +28,13 @@ export function docsTools(
     // The annotations state that for MCP hosts (and directory reviews check for them).
     {
       name: "nifra_docs",
-      annotations: { title: "Search nifra docs", readOnlyHint: true, openWorldHint: false },
+      annotations: {
+        title: "Search nifra docs",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
       description:
         "Search nifra's framework documentation and get back ONLY the matching sections - auth, uploads, ISR, WebSockets, loaders, deployment, anything. Call with no query for the cheap section index; pass query (e.g. \"isr revalidate\") for the top matching sections. Use this instead of reading llms-full.txt (~150 KB) whole. For the EXACT TypeScript of a type/interface/function, call nifra_types instead (don't read .d.ts files).",
       inputSchema: {
@@ -57,10 +63,12 @@ export function docsTools(
       annotations: {
         title: "Get a verified nifra example",
         readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
         openWorldHint: false,
       },
       description:
-        'Get a VERIFIED, copy-pasteable nifra code example for a task - auth route, file upload, ISR page, loader/action, typed client, SSE, deployment, etc. Every snippet is typechecked against the installed nifra version, so it compiles as-is. PREFER THIS over writing nifra code from memory (training data drifts). Returns code as TEXT for direct use; to visually browse the whole example set instead, use nifra_gallery. Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
+        'Get a verified, copy-pasteable Nifra code example for a task - auth route, file upload, ISR page, loader/action, typed client, SSE, deployment, and more. Every snippet is typechecked against the installed Nifra version, so it compiles as-is. Returns code as text for direct use. Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
       inputSchema: {
         type: "object",
         properties: {
@@ -84,9 +92,15 @@ export function docsTools(
     },
     {
       name: "nifra_types",
-      annotations: { title: "Look up nifra API types", readOnlyHint: true, openWorldHint: false },
+      annotations: {
+        title: "Look up nifra API types",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
       description:
-        'Get the EXACT TypeScript declaration of any exported @nifrajs/* symbol - interface, type, class, function, const. Each signature is generated from the package\'s built .d.ts, so it is the LITERAL declaration: complete, authoritative, never prose and never truncated. THIS IS THE SOURCE OF TRUTH for nifra\'s types - do NOT read node_modules/@nifrajs/**/*.d.ts; call this instead. Pass `name` for an exact symbol (e.g. "RateLimitStore", "RouteSchema", "Context", "rateLimit"); pass `query` to search by keyword; omit both for the per-package index of names. A `name` lookup is always the complete declaration; a `query` returns a one-line summary plus the signature, collapsing an oversized body - pass `full: true` to override.',
+        'Get the exact TypeScript declaration of any exported @nifrajs/* symbol - interface, type, class, function, or const. Each signature is generated from the package\'s built .d.ts and returns the complete declaration rather than prose. Pass `name` for an exact symbol (e.g. "RateLimitStore", "RouteSchema", "Context", "rateLimit"); pass `query` to search by keyword; omit both for the per-package index of names. A `name` lookup is always the complete declaration; a `query` returns a one-line summary plus the signature, collapsing an oversized body - pass `full: true` to override.',
       inputSchema: {
         type: "object",
         properties: {
@@ -132,6 +146,8 @@ export function docsTools(
       annotations: {
         title: "Guided nifra learning path",
         readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
         openWorldHint: false,
       },
       description:
@@ -153,10 +169,12 @@ export function docsTools(
       annotations: {
         title: "Frontend footgun guidance",
         readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
         openWorldHint: false,
       },
       description:
-        'Diagnose a CLIENT-SIDE nifra problem by symptom, across every adapter (React/Preact/Solid/Vue/Svelte/vanilla). Returns the cause, the concrete fix, and how to verify it. Covers the nifra SEAM (a server-only import leaking into a client component, a hydration mismatch, a duplicated framework runtime, loader-data typing) - where it points at the nifra_* tool that fixes and checks it - and the per-framework reactivity-loss idioms (Vue ref, Solid props, Svelte runes, React effect deps), where it points at that framework\'s own ESLint plugin. Call with no args for the index; pass `symptom` (e.g. "hydration mismatch", "value stopped updating") and/or `adapter` to filter. Use this when a rendered page misbehaves and nifra_check is green (check owns the static seam; this owns the rest).',
+        'Diagnose a client-side Nifra problem by symptom across every adapter (React, Preact, Solid, Vue, Svelte, and vanilla). Returns the likely cause, a concrete fix, and how to verify it. Covers the Nifra server/client seam, hydration mismatches, duplicated framework runtimes, loader-data typing, and adapter-specific reactivity guidance. Call with no args for the index; pass `symptom` (e.g. "hydration mismatch", "value stopped updating") and/or `adapter` to filter.',
       inputSchema: {
         type: "object",
         properties: {