@nifrajs/cli 3.1.0 → 3.3.0

package/src/frontend-guidance.ts

@@ -0,0 +1,259 @@
+/**
+ * `nifra_frontend` - a symptom-indexed catalog of the mistakes an agent (or a human) hits on the client
+ * side of a nifra app, across every adapter. It is the FRONTEND companion to `nifra_check`: where the
+ * check statically flags the footguns nifra's own seam owns (server-only imports, the nano lane), this
+ * catalog covers the ones a static rule can't own cheaply - hydration nondeterminism, a duplicated
+ * framework runtime, and the per-framework reactivity-loss idioms that each ecosystem's own linter is
+ * the real authority on.
+ *
+ * Deliberately a compact reference, not an accumulated fault corpus: two kinds of entry only.
+ *   - Seam entries (`adapters: ["all"]`) - the boundary nifra defines: server/client split, the loader
+ *     data contract, hydration determinism, one framework copy. These point at a `nifra_*` tool to fix
+ *     and verify, because nifra owns that surface.
+ *   - Framework entries - the classic reactivity-loss shape for one adapter (Vue ref, Solid props,
+ *     Svelte runes, React/Preact deps). These point at that framework's own ESLint plugin, which is the
+ *     authority; nifra does not re-implement it, it routes you to it.
+ *
+ * One source, two heads: `nifra_frontend` (MCP) serves it to an agent; `nifra frontend` (CLI) prints it
+ * for a human. Both call {@link renderFrontendResult}, so they can never drift.
+ */
+
+import type { Framework } from "./scaffold.ts"
+
+/** An adapter an entry applies to, or `all` for a seam issue that is adapter-independent. */
+export type GuidanceAdapter = Framework | "all"
+
+export interface GuidanceEntry {
+  /** Stable slug, e.g. `server-import`. */
+  readonly id: string
+  /** Which adapters this applies to. `["all"]` is a seam issue every adapter shares. */
+  readonly adapters: readonly GuidanceAdapter[]
+  /** What you observe - the searchable symptom, phrased as the failure, not the cause. */
+  readonly symptom: string
+  /** Why it happens. */
+  readonly cause: string
+  /** The concrete change that fixes it. */
+  readonly fix: string
+  /** How to confirm it is fixed - a `nifra_*` tool for a seam issue, the framework's linter otherwise. */
+  readonly verify: string
+  /** Where to go deeper - a `nifra_docs`/`nifra_example` query, or the ecosystem linter that owns it. */
+  readonly seeAlso?: string | undefined
+}
+
+/**
+ * The catalog. Seam entries first (they are the nifra-specific value and apply everywhere), then the
+ * per-framework reactivity-loss entries. Keep it compact and high-signal - a curated fault corpus mined
+ * from real failures is operated depth and lives elsewhere, not in the public package.
+ */
+export const FRONTEND_GUIDANCE: readonly GuidanceEntry[] = [
+  {
+    id: "server-import",
+    adapters: ["all"],
+    symptom:
+      "A client component crashes at build or runtime with a missing Node built-in, a leaked secret, or 'module not found in the browser'.",
+    cause:
+      "A server-only module (the DB, a secret, `node:*`, the backend file) is imported at the top level of a component, so the bundler tries to ship it to the browser.",
+    fix: "Move the access into a server-only `loader`/`action` and read the result in the component. Reach the backend through the typed `api` argument, never a top-level server-only import.",
+    verify:
+      "nifra_check - its transitive server-import scan flags the exact import chain into a client module.",
+    seeAlso: "loader action server-only import boundary",
+  },
+  {
+    id: "hydration-mismatch",
+    adapters: ["all"],
+    symptom:
+      "A hydration warning, text that flips on load, or 'server HTML did not match client' the first time the page becomes interactive.",
+    cause:
+      "The first client render is not identical to the SSR HTML - usually a non-deterministic read during render: `Date.now()`, `Math.random()`, `window`/`localStorage`, or a locale/timezone the server did not have.",
+    fix: "Render deterministic markup, then apply anything client-only in an effect / `onMount` after the first paint. Pass anything the server knew (time, locale, flags) down through loader data so both renders agree.",
+    verify:
+      "nifra_render the route and diff its HTML against the first client render; nifra_check's hydration assurance reports nondeterminism it can see.",
+    seeAlso: "hydration ssr determinism loader data",
+  },
+  {
+    id: "duplicate-runtime",
+    adapters: ["react", "preact", "solid", "vue", "svelte"],
+    symptom:
+      "'Invalid hook call', a null context/provider, signals that never update, or a component that mounts twice.",
+    cause:
+      "Two copies of the framework are in the bundle - the app's own dependency and a second one resolved through the adapter - so the two runtimes do not share the same module-level state.",
+    fix: "Dedupe the framework to a single version across the workspace (one entry in the lockfile). The adapter must resolve the app's copy, not bundle its own.",
+    verify: "nifra_doctor - it detects a duplicated framework runtime (NF-H002).",
+    seeAlso: "duplicate framework runtime dedupe NF-H002",
+  },
+  {
+    id: "loader-typing",
+    adapters: ["all"],
+    symptom:
+      "Loader data is typed `any` in the page, or a hand-written interface silently drifts from what the loader actually returns.",
+    cause:
+      "The component types its props by hand instead of inferring them from the loader, so a change to the loader is not a type error at the use site.",
+    fix: "Type the page from the loader: `props: { data: LoaderData<typeof loader> }`. Call the backend through the typed `api` so the request/response shape is inferred, not restated.",
+    verify:
+      "nifra_context prints the exact loader shape and typed call form; nifra_check fails on drift.",
+    seeAlso: "LoaderData typed client loader inference",
+  },
+  {
+    id: "list-key",
+    adapters: ["all"],
+    symptom:
+      "List rows keep the wrong state on reorder/insert - a checked box, focus, or an input value jumps to a different row.",
+    cause:
+      "The list is keyed by the array index (or not keyed at all), so add/remove/reorder maps the wrong item to an existing node.",
+    fix: "Key each row by a stable, unique id from the item, never its position in the array.",
+    verify:
+      "The framework's own linter for JSX keys; on the vanilla nano lane, nifra_check flags an index key as NF-C022.",
+    seeAlso: "list key stable id reconcile nano",
+  },
+  {
+    id: "vue-lost-reactivity",
+    adapters: ["vue"],
+    symptom:
+      "A value stops updating the template after you pull it out of a ref, reactive object, or props.",
+    cause:
+      "Destructuring a `reactive()` object or `props` copies the current value and drops the reactive link; a `ref` read in script forgets `.value`.",
+    fix: "Keep the reactive source intact: use `toRefs`/`storeToRefs` when you must destructure, access `props.x` directly, and remember `.value` on a ref in script (templates unwrap it for you).",
+    verify:
+      "eslint-plugin-vue - it is the authority on Vue reactivity; nifra does not re-implement it.",
+    seeAlso: "eslint-plugin-vue toRefs reactivity",
+  },
+  {
+    id: "solid-lost-reactivity",
+    adapters: ["solid"],
+    symptom: "A prop or store value renders once and never tracks updates in a Solid component.",
+    cause:
+      "Solid props are getters, evaluated where you read them. Destructuring props (or reading them outside JSX/an effect) reads once and loses tracking.",
+    fix: "Access `props.x` at the point of use inside JSX, or `splitProps`/`mergeProps` when you need to pass a subset on. Never destructure props in the function signature.",
+    verify:
+      "eslint-plugin-solid - the authority on Solid reactivity; nifra routes you to it, not around it.",
+    seeAlso: "eslint-plugin-solid splitProps props getters",
+  },
+  {
+    id: "svelte-runes",
+    adapters: ["svelte"],
+    symptom:
+      "In a Svelte 5 component, `export let` props or a `$:` statement do not behave as expected, or the compiler rejects them in runes mode.",
+    cause:
+      "Runes mode replaces the Svelte 4 idioms: props come from `$props()`, derived values from `$derived`, side effects from `$effect`. Mixing the two models is the mismatch.",
+    fix: "In runes mode use `$props()` for inputs, `$state` for local state, `$derived` for computed values, and `$effect` for side effects - not `export let` or `$:`.",
+    verify:
+      "eslint-plugin-svelte and the Svelte compiler warnings own this; nifra points you at them.",
+    seeAlso: "eslint-plugin-svelte runes $props $derived",
+  },
+  {
+    id: "react-stale-deps",
+    adapters: ["react", "preact"],
+    symptom:
+      "An effect or callback uses a stale value, fires too often, or never re-runs when a value it reads changes.",
+    cause:
+      "The dependency array omits a value the effect/callback closes over (or the effect has no array), so the closure captures an old render's value.",
+    fix: "List every reactive value the effect reads in its deps, or hold the mutable value in a ref when it must not trigger a re-run. Do not silence the rule by emptying the array.",
+    verify:
+      "eslint-plugin-react-hooks (`exhaustive-deps`) is the authority on effect deps; nifra does not duplicate it.",
+    seeAlso: "eslint-plugin-react-hooks exhaustive-deps effect closure",
+  },
+  {
+    id: "prefer-nano-or-island",
+    adapters: ["vanilla"],
+    symptom:
+      "A vanilla page needs local state or a list a human edits, and hand-written DOM updates are getting fragile.",
+    cause:
+      "The islands lane is imperative and has no state primitive, so each update is hand-wired and a list means rebuilding the container.",
+    fix: "Use the nano lane: `signal` + `computed(fn, [deps])` for state, `bindList` for a keyed list, `resource` for async. Every reactive edge is a visible call, so its mistakes are static lints.",
+    verify:
+      "nifra_check runs NF-C021 (discarded disposer), NF-C022 (index key), NF-C023 (missing dep) over the nano code.",
+    seeAlso: "nano signal computed bindList resource islands",
+  },
+]
+
+const ADAPTER_ALIASES: Record<string, GuidanceAdapter> = {
+  all: "all",
+  react: "react",
+  preact: "preact",
+  solid: "solid",
+  vue: "vue",
+  svelte: "svelte",
+  vanilla: "vanilla",
+}
+
+/** Normalize a free-text adapter argument to a known adapter, or `undefined` if it is not one. */
+export function parseAdapter(value: string | undefined): GuidanceAdapter | undefined {
+  if (value === undefined) return undefined
+  return ADAPTER_ALIASES[value.trim().toLowerCase()]
+}
+
+const appliesTo = (entry: GuidanceEntry, adapter: GuidanceAdapter): boolean =>
+  adapter === "all" || entry.adapters.includes("all") || entry.adapters.includes(adapter)
+
+/** Keyword score of an entry against a query - counts distinct query words found in its text. */
+function score(entry: GuidanceEntry, words: readonly string[]): number {
+  const hay =
+    `${entry.id} ${entry.symptom} ${entry.cause} ${entry.fix} ${entry.seeAlso ?? ""}`.toLowerCase()
+  let hits = 0
+  for (const w of words) if (hay.includes(w)) hits++
+  return hits
+}
+
+function renderEntry(entry: GuidanceEntry): string {
+  const scope = entry.adapters.includes("all") ? "all adapters" : entry.adapters.join(", ")
+  const parts = [
+    `[${entry.id}]  (${scope})`,
+    `Symptom: ${entry.symptom}`,
+    `Cause:   ${entry.cause}`,
+    `Fix:     ${entry.fix}`,
+    `Verify:  ${entry.verify}`,
+  ]
+  if (entry.seeAlso !== undefined) parts.push(`See:     ${entry.seeAlso}`)
+  return parts.join("\n")
+}
+
+function renderIndex(
+  entries: readonly GuidanceEntry[],
+  adapter: GuidanceAdapter | undefined,
+): string {
+  const scope = adapter === undefined ? "all adapters" : `adapter: ${adapter}`
+  const lines = entries.map((e) => {
+    const s = e.adapters.includes("all") ? "all" : e.adapters.join("/")
+    return `- ${e.id} (${s}) - ${e.symptom}`
+  })
+  return [
+    `nifra frontend guidance (${entries.length} of ${FRONTEND_GUIDANCE.length}, ${scope}). Pass a symptom to get the cause + fix + how to verify; pass an adapter to filter.`,
+    "",
+    ...lines,
+  ].join("\n")
+}
+
+/**
+ * Render the catalog. Filters by `adapter` (when it names a known one), then by a `symptom` keyword
+ * query. With no query it returns the (filtered) index; with a query it returns the best-matching
+ * entries in full, or the index plus a "no match" note when nothing scores. Pure, so both heads agree.
+ */
+export function renderFrontendResult(args: {
+  adapter?: string | undefined
+  symptom?: string | undefined
+  limit?: number | undefined
+}): string {
+  const adapter = parseAdapter(args.adapter)
+  const scoped =
+    adapter === undefined
+      ? FRONTEND_GUIDANCE
+      : FRONTEND_GUIDANCE.filter((e) => appliesTo(e, adapter))
+  const query = args.symptom?.trim()
+  if (query === undefined || query.length === 0) return renderIndex(scoped, adapter)
+
+  const words = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((w) => w.length > 1)
+  const limit = Math.min(Math.max(args.limit ?? 3, 1), 5)
+  const ranked = scoped
+    .map((entry) => ({ entry, s: score(entry, words) }))
+    .filter((r) => r.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, limit)
+
+  if (ranked.length === 0) {
+    return `No frontend-guidance entry matched "${query}"${adapter ? ` for ${adapter}` : ""}.\n\n${renderIndex(scoped, adapter)}`
+  }
+  return ranked.map((r) => renderEntry(r.entry)).join("\n\n")
+}

package/src/levels-tool.ts

@@ -132,6 +132,12 @@ export async function collectVerificationLevels(
       if (assurance.ok && (capabilityReport === undefined || capabilityReport.ok)) {
         const current = await buildNifraManifest({
           source: config.source,
+          // `evidence` is NOT optional detail here - it is what `nifra manifest emit` and the
+          // `versioned trust manifest drift` check in `nifra check` both hash. Omitting it made
+          // this recompute a manifest nothing else ever emits, so every app that publishes
+          // assurance evidence from outside its `.use()` chain (the `assure()` seam) reported a
+          // freshly emitted manifest as stale and could never reach L3.
+          ...(verification.evidence !== undefined ? { evidence: verification.evidence } : {}),
           assurance,
           ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
         })

package/src/load.ts

@@ -214,7 +214,10 @@ export async function loadApp(
   // and passes through unchanged.
   let clientModule: string
   if (fw.clientModule.startsWith("./") || fw.clientModule.startsWith("../")) {
-    clientModule = resolve(cwd, fw.clientModule)
+    // The value is embedded in generated import source, not passed directly to a filesystem API.
+    // Keep it absolute but slash-normalized so the generated module is identical on POSIX and
+    // Windows (Bun accepts an absolute drive path with forward slashes).
+    clientModule = resolve(cwd, fw.clientModule).replaceAll("\\", "/")
   } else {
     // A specifier that is neither `./`-relative, scoped (`@…`), nor absolute is read as a BARE PACKAGE
     // specifier - resolved against `node_modules`, not `cwd`. If a real local file sits at that path

package/src/mcp-context.ts

@@ -0,0 +1,266 @@
+/**
+ * Project context and trust-local utilities for the MCP server.
+ *
+ * Resources, prompts, path scoping, and monorepo namespacing are independent of the JSON-RPC loop and
+ * of backend reflection. App loading is injected through the shared cached loader seam.
+ */
+
+import { realpathSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { basename, isAbsolute, relative, resolve, sep } from "node:path"
+import type { LoadedApp } from "./load.ts"
+import { createCachedAppLoader } from "./mcp-exec.ts"
+import type { McpPrompt, McpResource, McpServerFeatures, McpTool } from "./mcp-protocol.ts"
+
+function openApiFormat(args: Record<string, unknown>): "json" | "yaml" {
+  const format = args.format
+  return format === "yaml" ? "yaml" : "json"
+}
+
+export async function openApiHandler(
+  args: Record<string, unknown>,
+  loadAppCached: (outDirName?: string) => Promise<LoadedApp>,
+): Promise<string> {
+  const { renderOpenApiWithTypes } = await import("./openapi-tool.ts")
+  const pathPrefix = typeof args.path === "string" ? args.path : undefined
+  return renderOpenApiWithTypes(await loadAppCached(), openApiFormat(args), pathPrefix)
+}
+
+async function readProjectFile(
+  cwd: string,
+  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}`)
+  }
+  try {
+    const text = await readFile(target, "utf8")
+    return text.length <= maxChars
+      ? text
+      : `${text.slice(0, maxChars)}\n…(trimmed; read ${relativeFile} directly for the rest)`
+  } catch (err) {
+    if (err && typeof err === "object" && (err as { code?: string }).code === "ENOENT") {
+      return `No ${relativeFile} found in ${basename(cwd)}.`
+    }
+    throw err
+  }
+}
+
+function promptText(
+  text: string,
+): readonly [
+  { readonly role: "user"; readonly content: { readonly type: "text"; readonly text: string } },
+] {
+  return [{ role: "user", content: { type: "text", text } }]
+}
+
+export function projectResources(
+  cwd: string,
+  loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
+): McpResource[] {
+  return [
+    {
+      uri: "nifra://routes",
+      name: "API routes",
+      description:
+        "Structured API routes with typed-client calls and compact request/response shapes.",
+      mimeType: "application/json",
+      read: async () => {
+        const { routesToJson } = await import("./introspect.ts")
+        return { text: JSON.stringify(routesToJson(await loadAppCached()), null, 2) }
+      },
+    },
+    {
+      uri: "nifra://openapi",
+      name: "OpenAPI 3.1",
+      description: "OpenAPI document generated from backend.ts using @nifrajs/schema.",
+      mimeType: "application/json",
+      read: async () => ({ text: await openApiHandler({ format: "json" }, loadAppCached) }),
+    },
+    {
+      uri: "nifra://package-json",
+      name: "package.json",
+      description: "Project package metadata and scripts.",
+      mimeType: "application/json",
+      read: async () => ({ text: await readProjectFile(cwd, "package.json", 40_000) }),
+    },
+    {
+      uri: "nifra://agents-md",
+      name: "AGENTS.md",
+      description: "Repository-specific agent instructions if the project has them.",
+      mimeType: "text/markdown",
+      read: async () => ({ text: await readProjectFile(cwd, "AGENTS.md", 40_000) }),
+    },
+  ]
+}
+
+export function projectPrompts(): McpPrompt[] {
+  return [
+    {
+      name: "nifra_new_route",
+      description:
+        "Implement a new file route with the right routes/ filename, examples, and checks.",
+      arguments: [
+        { name: "path", description: 'URL path, e.g. "/users/:id".', required: true },
+        { name: "goal", description: "What the page should do.", required: false },
+      ],
+      handler: async (args) =>
+        promptText(
+          [
+            `Create a nifra page route for ${JSON.stringify(args.path ?? "/new-route")}.`,
+            args.goal ? `Goal: ${String(args.goal)}` : undefined,
+            'Use `nifra_context` with `{ kind: "pages" }`, then `nifra_scaffold` for the exact file path.',
+            "If the stub is not writable for this framework, call `nifra_example` for a verified page/loader example before editing.",
+            "Verify with `nifra_render` for the route and finish with `nifra_check`.",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        ),
+    },
+    {
+      name: "nifra_add_endpoint",
+      description:
+        "Add or update a backend endpoint with schemas, typed-client usage, and verification.",
+      arguments: [
+        { name: "method", description: "HTTP method.", required: true },
+        { name: "path", description: 'API path, e.g. "/users/:id".', required: true },
+        { name: "goal", description: "What the endpoint should do.", required: false },
+      ],
+      handler: async (args) =>
+        promptText(
+          [
+            `Add a nifra backend endpoint: ${String(args.method ?? "GET").toUpperCase()} ${String(args.path ?? "/api")}.`,
+            args.goal ? `Goal: ${String(args.goal)}` : undefined,
+            "Read `nifra://routes` or call `nifra_routes` first so the new route fits the existing API shape.",
+            "Use route schemas for untrusted body/query input and declare `response` when the frontend consumes the shape.",
+            "Verify behavior with `nifra_run`, then run `nifra_check` and `nifra_test` for the touched area.",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        ),
+    },
+    {
+      name: "nifra_debug_drift",
+      description:
+        "Debug frontend/backend contract drift using the typed client and checker output.",
+      arguments: [
+        { name: "symptom", description: "The error or behavior to investigate.", required: false },
+      ],
+      handler: async (args) =>
+        promptText(
+          [
+            "Debug nifra contract drift.",
+            args.symptom ? `Symptom: ${String(args.symptom)}` : undefined,
+            "Start with `nifra_check`; use each diagnostic as the source of truth.",
+            "Read `nifra://routes` for the exact typed-client calls and compact body/query/response shapes.",
+            "Prefer `client<typeof app>` over hand-rolled internal `fetch`. Verify fixed endpoints with `nifra_run`.",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        ),
+    },
+  ]
+}
+
+export function projectFeatures(
+  cwd: string,
+  loadAppCached: (outDirName?: string) => Promise<LoadedApp> = createCachedAppLoader(cwd),
+): McpServerFeatures {
+  return { resources: projectResources(cwd, loadAppCached), prompts: projectPrompts() }
+}
+
+/**
+ * Resolve an optional `dir` tool argument - a subdirectory of the project root the caller wants to scope a
+ * check/test to (e.g. `nifra check` on `app/` when the MCP server's root is a monorepo). Returns the
+ * absolute target, or `null` if `dir` escapes the root (a path-traversal guard: no `..` out, no absolute
+ * path elsewhere). `undefined`/empty → the root itself.
+ */
+export function resolveProjectDir(root: string, dir: string | undefined): string | null {
+  if (dir === undefined || dir === "") return root
+  const target = resolve(root, dir)
+  let canonicalRoot: string
+  try {
+    canonicalRoot = realpathSync(root)
+  } catch {
+    const lexical = relative(root, target)
+    return lexical === "" || (!lexical.startsWith("..") && !isAbsolute(lexical)) ? target : null
+  }
+  let probe = target
+  const missing: string[] = []
+  while (true) {
+    try {
+      const canonicalProbe = realpathSync(probe)
+      const rel = relative(canonicalRoot, canonicalProbe)
+      if (rel.startsWith("..") || isAbsolute(rel)) return null
+      return missing.length === 0 ? canonicalProbe : resolve(canonicalProbe, ...missing.reverse())
+    } catch {
+      const parent = resolve(probe, "..")
+      if (parent === probe) return null
+      // `basename`, not a slice past `parent`: when `parent` is the filesystem root its trailing
+      // separator is part of it, so `parent.length + 1` eats the first character of the segment and
+      // the path gets rebuilt wrong.
+      missing.push(basename(probe))
+      probe = parent
+    }
+  }
+}
+
+/** Consistent error string for a `dir` that escapes the project root. */
+export function dirError(dir: string | undefined): string {
+  return JSON.stringify(
+    { ok: false, error: `dir must be a subdirectory of the project root - "${dir}" escapes it.` },
+    null,
+    2,
+  )
+}
+
+/** Build the project-scoped tools for `cwd`. */
+export interface CommandMcpToolOptions {
+  readonly cwd: string
+  readonly loadAppCached?: () => Promise<LoadedApp>
+}
+
+/** Adapt one executable catalog spec to its MCP descriptor and project-scoped handler. */
+export function namespaceForApp(
+  name: string,
+  tools: McpTool[],
+  features: McpServerFeatures,
+): { tools: McpTool[]; features: McpServerFeatures } {
+  const prefix = `nifra_${name}_`
+  const namespacedTools = tools.map((t) => ({
+    ...t,
+    name: t.name.startsWith("nifra_") ? t.name.replace(/^nifra_/, prefix) : `${name}_${t.name}`,
+  }))
+  const namespacedResources = (features.resources ?? []).map((r) => ({
+    ...r,
+    uri: r.uri.replace(/^nifra:\/\//, `nifra://${name}/`),
+  }))
+  const namespacedPrompts = (features.prompts ?? []).map((p) => ({
+    ...p,
+    name: p.name.replace(/^nifra_/, prefix),
+  }))
+  return {
+    tools: namespacedTools,
+    features: { resources: namespacedResources, prompts: namespacedPrompts },
+  }
+}
+
+/**
+ * Merge the backend-derived resources/prompts into `base` - and keep a project that cannot be loaded
+ * from deciding whether the server starts at all.
+ *
+ * Resources and prompts are OPTIONAL capabilities extracted from the app's backend, so this load is a
+ * best-effort enrichment. It was awaited unguarded, which made it a hard boot requirement: `loadApp`
+ * needs a web config (`adapter` + `clientModule`) and a `routes/` directory, and a backend-only
+ * project - the shape `create-nifra`'s DEFAULT template produces - has neither. On those projects the
+ * throw escaped before the JSON-RPC loop began, so the server wrote nothing and exited. `nifra
+ * init-agents` would happily register an `.mcp.json` pointing at a server that could never start, and
+ * every tool went with it, including the twelve that never touch the app (docs, examples, types,
+ * check, doctor, levels, test).
+ *
+ * Degrading costs only the backend resources/prompts. Tools that genuinely need the app still fail,
+ * but per call, with their own message - which is a diagnosis instead of a silence.
+ */

package/src/mcp-docs-tools.ts

@@ -9,6 +9,7 @@
 
 import { renderDocsResult } from "./docs-search.ts"
 import { type Example, renderExamplesResult } from "./examples.ts"
+import { renderFrontendResult } from "./frontend-guidance.ts"
 import { renderLearnResult } from "./learn.ts"
 import type { McpTool } from "./mcp-protocol.ts"
 import { renderTypesResult, type TypeEntry } from "./types-search.ts"
@@ -147,5 +148,41 @@ export function docsTools(
       },
       handler: async (args) => renderLearnResult((args as { step?: number }).step),
     },
+    {
+      name: "nifra_frontend",
+      annotations: {
+        title: "Frontend footgun guidance",
+        readOnlyHint: 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).',
+      inputSchema: {
+        type: "object",
+        properties: {
+          symptom: {
+            type: "string",
+            maxLength: 256,
+            description: "What you observe (omit for the index).",
+          },
+          adapter: {
+            type: "string",
+            enum: ["react", "preact", "solid", "vue", "svelte", "vanilla"],
+            description:
+              "Filter to one adapter's entries (plus the adapter-independent seam entries).",
+          },
+          limit: { type: "number", description: "Max entries to return (default 3, max 5)." },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const { symptom, adapter, limit } = args as {
+          symptom?: string
+          adapter?: string
+          limit?: number
+        }
+        return renderFrontendResult({ symptom, adapter, limit: clamp(limit, 1, 5, 3) })
+      },
+    },
   ]
 }