@nifrajs/cli 3.3.0 → 4.0.0

package/src/load.ts

@@ -1,37 +1,43 @@
 /**
  * Zero-config app discovery. The CLI reads a few conventions from the project root:
  *   - `routes/`         - the file-based routes (per `@nifrajs/web/fs`).
- *   - `nifra.config.ts`  - the CLI's framework wiring (see {@link NifraFramework}); `framework.ts` is
- *                         used as a fallback. One of the two is required.
- *   - `backend.ts`      - exports `backend` (a `@nifrajs/core` server, the contract). Optional.
+ *   - `nifra.config.ts`  - the CLI's framework wiring (see {@link NifraFramework});
+ * `backend/framework.ts` is                         used as a fallback. One of the two is required.
+ *   - `backend/app.ts`      - exports `backend` (a `@nifrajs/core` server, the contract). Optional.
  *
- * Why two filenames: a multi-target app's edge entry (`_worker.ts`) imports `framework.ts` for the
- * render adapter, so `framework.ts` must stay edge-bundlable - it can't reference Vite plugins or the
- * SFC compiler (Bun would pull them into the `target:"browser"` worker and fail on `child_process`).
- * `nifra.config.ts` holds that build/dev tooling instead: it's imported ONLY by this CLI (which runs on
- * Bun), so its Vite plugin + SFC-compiler imports (`@vitejs/plugin-vue`, `@nifrajs/web-vue/plugin`) never
- * reach the edge bundle. A simple single-target app with no edge build can put it all in `framework.ts`.
+ * Why two filenames: a multi-target app's edge entry (`_worker.ts`) imports `backend/framework.ts`
+ * for the render adapter, so `backend/framework.ts` must stay edge-bundlable - it can't reference
+ * Vite plugins or the SFC compiler (Bun would pull them into the `target:"browser"` worker and fail
+ * on `child_process`). `nifra.config.ts` holds that build/dev tooling instead: it's imported ONLY
+ * by this CLI (which runs on Bun), so its Vite plugin + SFC-compiler imports (`@vitejs/plugin-vue`,
+ * `@nifrajs/web-vue/plugin`) never reach the edge bundle. A simple single-target app with no edge
+ * build can put it all in `backend/framework.ts`.
  */
 import { existsSync } from "node:fs"
 import { isAbsolute, resolve } from "node:path"
+import type { CreateWebAppOptions, CssLoadingMode } from "@nifrajs/web"
+import type { SecretExemption } from "@nifrajs/web/build"
+import { assertCurrentLayout, BACKEND_APP_FILE, CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
 import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
- * A plugin list - either an array, or a **thunk** that returns one (optionally async). Both forms are
- * accepted; {@link resolvePlugins} normalizes them. The thunk is just a convenience for deferring a
- * plugin's construction - it does NOT make a plugin edge-safe (Bun.build follows a dynamic `import()`
- * even from an unused export, so a Vite/compiler import in an edge-bundled file fails regardless). Edge
- * safety comes from WHERE the config lives: keep these fields in `nifra.config.ts` (CLI-only), not in
- * the edge-imported `framework.ts`. See the module header.
+ * A plugin list - either an array, or a **thunk** that returns one (optionally async). Both forms
+ * are accepted; {@link resolvePlugins} normalizes them. The thunk is just a convenience for
+ * deferring a plugin's construction - it does NOT make a plugin edge-safe (Bun.build follows a
+ * dynamic `import()` even from an unused export, so a Vite/compiler import in an edge-bundled file
+ * fails regardless). Edge safety comes from WHERE the config lives: keep these fields in
+ * `nifra.config.ts` (CLI-only), not in the edge-imported `backend/framework.ts`. See the module
+ * header.
  */
 export type PluginsField =
   | readonly unknown[]
   | (() => readonly unknown[] | Promise<readonly unknown[]>)
 
 /**
- * The CLI's framework wiring - exported from `nifra.config.ts` (or `framework.ts` as a fallback).
- * `create-nifra` generates it. Only `adapter` + `clientModule` are required; the plugin/condition
- * fields are framework-specific extras (Vue/Svelte/Solid need them; React/Preact don't).
+ * The CLI's framework wiring - exported from `nifra.config.ts` (or `backend/framework.ts` as a
+ * fallback). `create-nifra` generates it. Only `adapter` + `clientModule` are required; the
+ * plugin/condition fields are framework-specific extras (Vue/Svelte/Solid need them; React/Preact
+ * don't).
  */
 export interface NifraFramework {
   /** The render adapter, e.g. `reactAdapter` from `@nifrajs/web-react`. */
@@ -41,7 +47,7 @@ export interface NifraFramework {
   /** App-level middleware applied to the web app before its page routes are declared -
    * e.g. `(app) => app.use(securityHeaders())`. Runs ahead of the `api`/`mounts` hooks.
    *
-   * MUST be exported from `framework.ts`, not `nifra.config.ts`: `nifra build` emits a
+   * MUST be exported from `backend/framework.ts`, not `nifra.config.ts`: `nifra build` emits a
    * server entry that imports it, and that entry is edge-bundled. See the module header. */
   readonly use?: (app: never) => void
   /** Vite plugins for `nifra dev`'s HMR, e.g. `[react()]` / `() => import("@vitejs/plugin-vue")…`. */
@@ -56,10 +62,88 @@ export interface NifraFramework {
   readonly conditions?: readonly string[]
   /** Compile-time `define` replacements, e.g. Vue's `__VUE_*` flags. */
   readonly define?: Readonly<Record<string, string>>
+  /** The deploy target `nifra build` emits without `--target` (default `"bun"`); `nifra target <t>`
+   * rewrites it. */
+  readonly target?: string
+  /** `"platform"` makes a `cloudflare` / `vercel` build read `c.clientIp` from the header that
+   * platform's edge overwrites (`cf-connecting-ip` / `x-real-ip`). Left out, an edge build has no
+   * caller address, so a per-caller `rateLimit` refuses every request. Declare it only while that edge
+   * is the sole way in: served any other way the header is whatever the client sent. Self-hosting
+   * targets use the socket peer either way. */
+  readonly clientIp?: "platform"
+  /** `nifra dev` settings. `indicator: false` turns the in-page issues badge off for every run
+   * (`nifra dev --no-indicator` does it for one); browser errors still reach `nifra errors`. */
+  readonly dev?: { readonly indicator?: boolean }
   /** Static files directory. Defaults to `<app>/public`; `false` disables it. */
   readonly publicDir?: string | false
   /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
   readonly publicEnvPrefix?: string
+  /** Reviewed false positives of `nifra build`'s secret scan, each `{ rule, file, reason }` (or
+   * `{ rule: "private-env-value", env, reason }`). There is no exemption by value. */
+  readonly secretExemptions?: readonly SecretExemption[]
+  /** Vite production CSS output policy. `false` emits one aggregate stylesheet for the whole client. */
+  readonly cssCodeSplit?: boolean
+  /** Framework-owned SSR stylesheet activation. Deferred mode is intended for aggregate CSS. */
+  readonly cssLoading?: CssLoadingMode
+  /** Path `backend/app.ts`'s backend is served at (default `"/api"`; `""` turns the mount off). A
+   * page file under it can never render, so the app refuses to start and `nifra build` refuses to
+   * build.
+   *
+   * The fields from here down reach the generated server entry, so like `use` they MUST be exported
+   * from `backend/framework.ts` (re-export them from `nifra.config.ts` when both exist). */
+  readonly apiPrefix?: string
+  /** Strip {@link apiPrefix} before the backend sees the path, for a backend that declares its routes
+   * without it. Default `false`. */
+  readonly apiStrip?: boolean
+  /** Apps mounted ahead of page routing - an auth handler, a webhook receiver, a backend served at an
+   * extra path. See `createWebApp`'s `mounts`. */
+  readonly mounts?: CreateWebAppOptions["mounts"]
+  /** A hash-based Content-Security-Policy from `createCspPolicy`. Exclusive with {@link nonce}. */
+  readonly csp?: CreateWebAppOptions["csp"]
+  /** A per-request CSP nonce resolver. Exclusive with {@link csp}. */
+  readonly nonce?: CreateWebAppOptions["nonce"]
+}
+
+/** The {@link NifraFramework} fields forwarded to `createWebApp` and imported by the generated server
+ * entry, in one list so every command that builds the app forwards the same set. */
+export const FRAMEWORK_WEB_OPTIONS = ["apiPrefix", "apiStrip", "mounts", "csp", "nonce"] as const
+export type FrameworkWebOption = (typeof FRAMEWORK_WEB_OPTIONS)[number]
+
+/** Refuse a forwarded field of the wrong shape at load, naming the field, rather than letting it fail
+ * later inside `createWebApp` or the generated server entry. */
+function assertFrameworkWebOptions(fw: Partial<NifraFramework>, configFile: string): void {
+  const wrong = (field: string, expected: string): never => {
+    throw new Error(`[nifra] ${configFile}: \`${field}\` must be ${expected}.`)
+  }
+  if (fw.apiPrefix !== undefined && typeof fw.apiPrefix !== "string") {
+    wrong("apiPrefix", 'a path string such as "/api", or "" to turn the backend mount off')
+  }
+  if (fw.apiStrip !== undefined && typeof fw.apiStrip !== "boolean") wrong("apiStrip", "a boolean")
+  if (fw.mounts !== undefined && !Array.isArray(fw.mounts)) {
+    wrong("mounts", "an array of { path, app } entries")
+  }
+  if (fw.csp !== undefined && (typeof fw.csp !== "object" || fw.csp === null)) {
+    wrong("csp", "the policy createCspPolicy() returns")
+  }
+  if (fw.nonce !== undefined && typeof fw.nonce !== "function") {
+    wrong("nonce", "a nonce resolver function, such as createNonceResolver() returns")
+  }
+  if (fw.secretExemptions !== undefined && !Array.isArray(fw.secretExemptions)) {
+    wrong("secretExemptions", "an array of { rule, file, reason } entries")
+  }
+  if (fw.target !== undefined && typeof fw.target !== "string") {
+    wrong("target", 'a deploy target name such as "bun"')
+  }
+  if (fw.clientIp !== undefined && fw.clientIp !== "platform") {
+    wrong("clientIp", '"platform" (trust the edge platform\'s client-address header), or left out')
+  }
+  if (fw.dev !== undefined) {
+    if (typeof fw.dev !== "object" || fw.dev === null)
+      wrong("dev", "an object such as { indicator: false }")
+    const indicator: unknown = Reflect.get(fw.dev, "indicator")
+    if (indicator !== undefined && typeof indicator !== "boolean")
+      wrong("dev.indicator", "a boolean")
+  }
 }
 
 /**
@@ -99,8 +183,9 @@ export interface ResolvedPlugins {
 
 export interface LoadedApp {
   readonly cwd: string
-  /** Absolute path of the config this app was loaded from - `nifra.config.ts`, or `framework.ts` as the
-   * fallback. `nifra dev`'s Bun pipeline re-imports it from a GENERATED module so the app's own
+  /** Absolute path of the config this app was loaded from - `nifra.config.ts`, or
+   * `backend/framework.ts` as the fallback. `nifra dev`'s Bun pipeline re-imports it from a
+   * GENERATED module so the app's own
    * `clientPlugins` reach Bun's dev-server bundler, which takes plugins only as module paths. */
   readonly configPath: string
   readonly routesDir: string
@@ -109,7 +194,7 @@ export interface LoadedApp {
   readonly framework: NifraFramework
   /** Plugin thunks resolved exactly once during app loading and reused by every command phase. */
   readonly resolvedPlugins: ResolvedPlugins
-  /** The `backend` export from `backend.ts`, or `undefined` if there's no `backend.ts`. */
+  /** The `backend` export from `backend/app.ts`, or `undefined` if there's no `backend/app.ts`. */
   readonly backend: unknown
 }
 
@@ -121,7 +206,8 @@ export interface LoadAppOptions {
 /**
  * Root-level monorepo config - exported from `nifra.config.ts` at the workspace root.
  * Each key in `apps` is the short name used to namespace MCP tools (`nifra_<name>_context` etc.);
- * each value is a path relative to the root that contains its own `nifra.config.ts` / `framework.ts`.
+ * each value is a path relative to the root that contains its own `nifra.config.ts` /
+ * `backend/framework.ts`.
  *
  * Example:
  * ```ts
@@ -172,23 +258,48 @@ const isAdapter = (v: unknown): boolean => typeof v === "object" && v !== null
 const importWithQuery = (path: string, query: string | undefined): Promise<unknown> =>
   import(query === undefined || query === "" ? path : `${path}?${query}`)
 
-/** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back to
- * `framework.ts`. Throws a clear, actionable error if neither exists or the config is malformed. */
+/**
+ * What reads only the backend (`nifra openapi`): the whole app when it has a web config, else
+ * `backend/app.ts` alone, so an API-only app needs no adapter to describe its routes.
+ */
+export async function loadBackendApp(
+  cwd: string,
+  options: LoadAppOptions = {},
+): Promise<Pick<LoadedApp, "cwd" | "backend">> {
+  if (existsSync(resolve(cwd, CONFIG_FILE)) || existsSync(resolve(cwd, FRAMEWORK_FILE))) {
+    return loadApp(cwd, "dist", options)
+  }
+  assertCurrentLayout(cwd)
+  const backendPath = resolve(cwd, BACKEND_APP_FILE)
+  if (!existsSync(backendPath)) {
+    throw new Error(
+      `[nifra] no ${BACKEND_APP_FILE} in ${cwd}: the OpenAPI document describes its routes`,
+    )
+  }
+  const backend = (
+    (await importWithQuery(backendPath, options.importQuery)) as { backend?: unknown }
+  ).backend
+  return { cwd, backend }
+}
+
+/** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back
+ * to
+ * `backend/framework.ts`. Throws a clear, actionable error if neither exists or the config is
+ * malformed. */
 export async function loadApp(
   cwd: string,
   outDirName = "dist",
   options: LoadAppOptions = {},
 ): Promise<LoadedApp> {
   // nifra.config.ts is the CLI's config (it may import Vite plugins / the SFC compiler, which a
-  // multi-target app keeps OUT of the edge-imported framework.ts). framework.ts is the fallback for a
-  // simple single-target app that has no edge build.
-  const configFile = existsSync(resolve(cwd, "nifra.config.ts"))
-    ? "nifra.config.ts"
-    : "framework.ts"
+  // multi-target app keeps OUT of the edge-imported backend/framework.ts). backend/framework.ts is
+  // the fallback for a simple single-target app that has no edge build.
+  assertCurrentLayout(cwd)
+  const configFile = existsSync(resolve(cwd, CONFIG_FILE)) ? CONFIG_FILE : FRAMEWORK_FILE
   const configPath = resolve(cwd, configFile)
   if (!existsSync(configPath)) {
     throw new Error(
-      `[nifra] no nifra.config.ts or framework.ts found in ${cwd}.\n` +
+      `[nifra] no ${CONFIG_FILE} or ${FRAMEWORK_FILE} found in ${cwd}.\n` +
         "      nifra is zero-config but needs one of them exporting at least:\n" +
         "        export const adapter = reactAdapter            // from @nifrajs/web-react\n" +
         '        export const clientModule = "@nifrajs/web-react/client"\n' +
@@ -206,6 +317,7 @@ export async function loadApp(
       `[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`,
     )
   }
+  assertFrameworkWebOptions(fw, configFile)
   // A `clientModule` given as a RELATIVE path (a local client entry, e.g. `./src/client.tsx`) is
   // resolved to absolute here. It is embedded verbatim as an import specifier in the generated client
   // entry, and `nifra dev` and `nifra build` write that entry into DIFFERENT directories - so a relative
@@ -246,7 +358,7 @@ export async function loadApp(
   assertPipelineSeparation(resolvedPlugins, configFile)
 
   let backend: unknown
-  const backendPath = resolve(cwd, "backend.ts")
+  const backendPath = resolve(cwd, BACKEND_APP_FILE)
   if (existsSync(backendPath)) {
     backend = ((await importWithQuery(backendPath, options.importQuery)) as { backend?: unknown })
       .backend

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

@@ -7,9 +7,10 @@
 
 import { realpathSync } from "node:fs"
 import { readFile } from "node:fs/promises"
-import { basename, isAbsolute, relative, resolve, sep } from "node:path"
+import { basename, isAbsolute, relative, resolve } from "node:path"
 import type { LoadedApp } from "./load.ts"
 import { createCachedAppLoader } from "./mcp-exec.ts"
+import { resolveMcpProjectPath } from "./mcp-path.ts"
 import type { McpPrompt, McpResource, McpServerFeatures, McpTool } from "./mcp-protocol.ts"
 
 function openApiFormat(args: Record<string, unknown>): "json" | "yaml" {
@@ -31,11 +32,8 @@ async function readProjectFile(
   relativeFile: string,
   maxChars: number,
 ): Promise<string> {
-  const target = resolve(cwd, relativeFile)
-  const root = resolve(cwd)
-  if (target !== root && !target.startsWith(`${root}${sep}`)) {
-    throw new Error(`refusing to read outside project root: ${relativeFile}`)
-  }
+  const target = resolveMcpProjectPath(cwd, relativeFile)
+  if (target === null) throw new Error(`refusing to read outside project root: ${relativeFile}`)
   try {
     const text = await readFile(target, "utf8")
     return text.length <= maxChars
@@ -76,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: {