@nifrajs/cli 2.1.0 → 2.3.0

package/src/introspect.ts

@@ -1,6 +1,6 @@
 /**
- * Introspect a loaded nifra project into a Markdown brief — the API routes (`backend.routes()`), the
- * page routes (`discoverRoutes`), and a conventions summary — for piping into an AI coding agent's
+ * Introspect a loaded nifra project into a Markdown brief - the API routes (`backend.routes()`), the
+ * page routes (`discoverRoutes`), and a conventions summary - for piping into an AI coding agent's
  * prompt. Used by `nifra context` (stdout) and the `nifra mcp` server (a tool result), so an agent sees
  * *this* project's actual surface, not just generic docs.
  */
@@ -28,7 +28,7 @@ interface JsonSchemaNode {
 }
 
 /**
- * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the
+ * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) - the
  * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).
  * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output
  * is always faithful, just not always minimal.
@@ -74,7 +74,7 @@ export function tsTypeOf(schema: unknown, depth = 0): string {
 }
 
 /** One route's request/response field shapes, indented under its line. Reads the declared schemas off the
- * descriptor so an agent gets the exact input + output contract — not just "this route is validated". */
+ * descriptor so an agent gets the exact input + output contract - not just "this route is validated". */
 function schemaLines(schema: ReflectedRoute["schema"]): string[] {
   const s = schema
   if (!s) return []
@@ -95,11 +95,11 @@ function schemaLines(schema: ReflectedRoute["schema"]): string[] {
 const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
 /**
- * The typed-client call form for a route — the exact `client<typeof app>` proxy chain an agent should
+ * The typed-client call form for a route - the exact `client<typeof app>` proxy chain an agent should
  * write, derived from the same convention `@nifrajs/client` implements (so it never has to read the
  * client tests to learn it): a static segment is a property (`.users`), a path param/wildcard is a call
  * that appends the value (`({ id })`), the root path is `.index`, and the HTTP verb is the terminal call.
- * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first —
+ * Body verbs (POST/PUT/PATCH) take the body first then call-options; other verbs take call-options first -
  * so the `{ query }` argument lands in the right slot for each.
  */
 export function clientCall(method: string, path: string, schema: unknown): string {
@@ -140,10 +140,10 @@ export function apiRoutesSection(routes: readonly ReflectedRoute[]): string {
       ...schemaLines(r.schema),
       `    - call: \`${clientCall(r.method, r.path, r.schema)}\` → \`{ ok, status, data, error }\``,
     ])
-  return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract — the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`
+  return `## API routes (backend.ts)\n\nEach route's \`body\`/\`query\`/\`response\` shape is its contract - the typed client derives request inputs and \`res.data\` from these, so a screen built on \`client<typeof app>\` stays in sync automatically. The \`call\` line is the exact \`client<typeof app>\` form: static path segments are properties, a path param is a call (\`({ id })\`), the verb is the terminal call (body first for POST/PUT/PATCH), and every call returns the never-throwing \`{ ok, status, data, error }\` Result.\n\n${lines.join("\n")}`
 }
 
-/** Compact API-routes INDEX for the no-arg `nifra_context` call — `METHOD path` per route, WITHOUT the
+/** Compact API-routes INDEX for the no-arg `nifra_context` call - `METHOD path` per route, WITHOUT the
  * body/query/response shapes or the per-route `call` line. Bounds the first-call payload on a big backend:
  * an agent gets the full route list (so it knows what's mounted) plus a pointer to fetch any route's full
  * contract via the `path`/`kind` slice, instead of every schema up front. */
@@ -154,7 +154,7 @@ export function apiRoutesIndexSection(routes: readonly ReflectedRoute[]): string
   const lines = [...routes]
     .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method))
     .map((r) => `- \`${r.method} ${r.path}\``)
-  return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form — or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
+  return `## API routes (backend.ts)\n\n${routes.length} route${routes.length === 1 ? "" : "s"}. Call \`nifra_context\` again with \`path\` (a route prefix) and/or \`kind: "api"\` for the body/query/response contracts + the exact \`client<typeof app>\` call form - or \`nifra_routes\` for the same as structured JSON.\n\n${lines.join("\n")}`
 }
 
 /** Markdown section listing the file-routed pages (URL pattern → source file). */
@@ -172,25 +172,25 @@ const CONVENTIONS = `## Conventions (summary)
 
 - **Backend:** \`server()\` from \`@nifrajs/core\`; returning a value sends JSON. Validate untrusted input with
   a route schema (\`{ body, query, params }\` using \`t\` from \`@nifrajs/schema\` or any Standard Schema) and read
-  the typed \`c.body\` / \`c.query\` / \`c.params\` — never hand-parse.
+  the typed \`c.body\` / \`c.query\` / \`c.params\` - never hand-parse.
 - **Cross-cutting concerns** (rate limit / \`429\`, CORS, auth, CSRF, caching, security headers, body limits)
   → \`@nifrajs/middleware\`, applied with \`app.use(...)\`. Don't hand-roll them; call \`nifra_docs("middleware")\`
   for the full list + usage.
 - **Need the exact TypeScript of a \`@nifrajs/*\` symbol?** Call \`nifra_types({ name })\` (e.g. \`RateLimitStore\`,
-  \`RouteSchema\`) — the authoritative, complete declaration. Never read \`@nifrajs\` \`.d.ts\` files.
+  \`RouteSchema\`) - the authoritative, complete declaration. Never read \`@nifrajs\` \`.d.ts\` files.
 - **Response contract (no drift):** declare \`{ response: t.object({...}) }\` on a route to lock its output
-  shape — the handler is type-checked against it and the client sees exactly that shape. The contract above
+  shape - the handler is type-checked against it and the client sees exactly that shape. The contract above
   is the single source of truth for both sides.
-- **Client — ALWAYS use this for API calls:** \`client<typeof app>(url)\` derives request inputs AND
+- **Client - ALWAYS use this for API calls:** \`client<typeof app>(url)\` derives request inputs AND
   \`res.data\` from the backend's route types, so the compiler catches any frontend/backend drift. Never
-  hand-roll \`fetch\` + ad-hoc response types for an internal API — that's exactly how screens drift. It
+  hand-roll \`fetch\` + ad-hoc response types for an internal API - that's exactly how screens drift. It
   never throws: branch on \`res.ok ? res.data : res.error\`.
 - **Pages:** file-routed under \`routes/\`; \`loader\`/\`action\` are server-only but the module is also bundled
-  for the browser — **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
+  for the browser - **never top-level-import server-only code** (DB, secrets, \`process.env\`) into a route
   file; reach it via \`ctx.api\` / \`ctx.env\`.
 - \`app.fetch(Request)\` is the universal entry. Full reference: this repo's \`AGENTS.md\`, or \`llms-full.txt\`.`
 
-/** Optional narrowing for {@link describeProject} — a path prefix and/or one section. A filtered
+/** Optional narrowing for {@link describeProject} - a path prefix and/or one section. A filtered
  * brief omits the conventions block (the agent already has it from its first full call), so
  * follow-up calls cost a fraction of the tokens. */
 export interface ContextFilter {
@@ -199,9 +199,9 @@ export interface ContextFilter {
 }
 
 /**
- * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** — the route list (API
+ * Build the project brief as Markdown. A no-arg call returns a tight **INDEX** - the route list (API
  * routes as `METHOD path`, page routes as `pattern → file`) + conventions + a pointer to fetch full
- * contracts via the slice — so learning a big project is cheap, not a full-surface schema dump. Passing a
+ * contracts via the slice - so learning a big project is cheap, not a full-surface schema dump. Passing a
  * {@link ContextFilter} (`path` prefix and/or `kind`) returns the narrowed, FULL detail (per-route
  * body/query/response shapes + the typed-client `call` form), and omits the conventions block (the agent
  * already has it from the index call).
@@ -211,7 +211,7 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
   try {
     manifest = discoverRoutes(app.routesDir)
   } catch {
-    // No (or unreadable) routes/ — the page-routes section reports that.
+    // No (or unreadable) routes/ - the page-routes section reports that.
   }
   const prefix = filter?.path
   let routes = backendRoutes(app.backend)
@@ -228,10 +228,10 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
   const sections: string[] = [`# nifra project: ${app.cwd.slice(app.cwd.lastIndexOf("/") + 1)}`]
   if (isIndex) {
     sections.push(
-      "A full-stack nifra app — Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
-      // Point agents at the verified surface, not recalled APIs — nifra is young, so training data is the
+      "A full-stack nifra app - Web-standard, one app on Bun, Node, Deno, and the edge. This is the route INDEX; fetch a route's full body/query/response contract on demand (see below).",
+      // Point agents at the verified surface, not recalled APIs - nifra is young, so training data is the
       // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
-      "> **Build against THIS surface + the verified tools — do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
+      "> **Build against THIS surface + the verified tools - do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
     )
   }
   if (filter?.kind !== "pages") {
@@ -255,7 +255,7 @@ export interface RouteJson {
 }
 
 /**
- * The backend's API routes as structured JSON — what the `nifra_routes` MCP tool returns, so an agent
+ * The backend's API routes as structured JSON - what the `nifra_routes` MCP tool returns, so an agent
  * consumes the contract programmatically (`list_routes` / `get_route_schema`) instead of parsing the
  * Markdown brief. Optionally filtered to routes whose path starts with `pathPrefix`. Reuses the exact
  * same `call` form and TS-shaped contracts the Markdown brief shows.
@@ -292,11 +292,11 @@ export function routesToJson(app: LoadedApp, pathPrefix?: string): RouteJson[] {
 }
 
 // ===================================================================================================
-// `nifra routes [--json]` — the focused, uniform view of every route the app serves, with methods.
+// `nifra routes [--json]` - the focused, uniform view of every route the app serves, with methods.
 //
 // `nifra context` lists page routes + API routes for an agent's prompt (Markdown, with schemas).
 // `nifra routes` answers a different question: "what does this app actually serve, and with which
-// methods?" — so an agent sees instantly that `POST /api/explain` is (or isn't) mounted, instead of
+// methods?" - so an agent sees instantly that `POST /api/explain` is (or isn't) mounted, instead of
 // discovering it via a 405. It marks which backend routes are AUTO-MOUNTED under the page router's
 // `apiPrefix` (default `/api`), and `--json` makes it machine-consumable. The table-building +
 // rendering are pure (no fs / no module loads), so they're unit-tested; the cwd gathering is the thin
@@ -313,7 +313,7 @@ export interface RouteTableEntry {
   readonly path: string
   /** Methods this route serves, sorted (page: `GET`, plus `POST` when it has an `action`). */
   readonly methods: readonly string[]
-  /** Source file (page only — the route module path relative to `routes/`). */
+  /** Source file (page only - the route module path relative to `routes/`). */
   readonly file?: string
   /** True when this API route is auto-mounted under the page router's `apiPrefix` (so it's reachable
    * through the same web app, no hand-wired `if (pathname.startsWith("/api/"))`). Pages are never
@@ -345,7 +345,7 @@ function isUnderPrefix(path: string, prefix: string): boolean {
 }
 
 /**
- * Build the unified, sorted route table from page routes + backend API routes. Pure — the caller
+ * Build the unified, sorted route table from page routes + backend API routes. Pure - the caller
  * supplies page `hasAction` (resolved via a module load) and the API descriptors (`backend.routes()`).
  * Page routes serve `GET` (+ `POST` when they export an `action`); API routes carry their declared
  * method, and are flagged `autoMounted` when at/under `apiPrefix`. Sorted by path, then kind, then the
@@ -449,7 +449,7 @@ export async function describeRoutes(
   try {
     manifest = discoverRoutes(app.routesDir)
   } catch {
-    // No (or unreadable) routes/ — fall through with no pages; the table still shows API routes.
+    // No (or unreadable) routes/ - fall through with no pages; the table still shows API routes.
   }
   const pages: PageRouteInput[] = []
   for (const route of manifest?.routes ?? []) {

package/src/levels-tool.ts

@@ -1,36 +1,34 @@
 /**
- * `nifra levels` — the verification ladder, computed from gates that already exist:
+ * `nifra levels` - the verification ladder, computed from gates that already exist:
  *
- *   L0 typed contract      — `nifra check` passes (compiler-enforced frontend↔backend contract)
- *   L1 route assurance     — `nifra.assurance.ts` present and every route satisfies its policy
- *   L2 capability lockfile — capability/effect assurance passes and the lockfile is in sync
- *   L3 route manifest      — the emitted manifest hash-verifies and matches the current app
- *   L4 invariant-tested    — every route passes through an explicitly isolated executor
+ *   L0 typed contract      - `nifra check` passes (compiler-enforced frontend↔backend contract)
+ *   L1 route assurance     - `nifra.assurance.ts` present and every route satisfies its policy
+ *   L2 capability lockfile - capability/effect assurance passes and the lockfile is in sync
+ *   L3 route manifest      - the emitted manifest hash-verifies and matches the current app
+ *   L4 invariant-tested    - every route passes through an explicitly isolated executor
  *
- * A level counts only when every level below it holds — the ladder is cumulative, so "L3" is one
+ * A level counts only when every level below it holds - the ladder is cumulative, so "L3" is one
  * honest word for a whole posture. Levels are computed, never self-declared.
  */
 
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
-import { evaluateRouteAssurance } from "@nifrajs/core/assurance"
-import { type evaluateCapabilityAssurance, snapshotCapabilities } from "@nifrajs/core/capabilities"
+import type { AssuranceReport } from "@nifrajs/core/assurance"
+import { snapshotCapabilities } from "@nifrajs/core/capabilities"
 import { buildNifraManifest, parseNifraManifest } from "@nifrajs/core/manifest"
 import { type ContractTestApp, runAdversarialContract } from "@nifrajs/testing"
-import { loadAssuranceConfig } from "./assure.ts"
 import {
-  collectCapabilityProjectReport,
+  type CapabilityProjectReport,
   diffCapabilitySnapshots,
   parseCapabilityLockfile,
 } from "./capabilities-tool.ts"
-import { collectCheckResult } from "./check.ts"
 import { DEFAULT_MANIFEST_FILE } from "./manifest-tool.ts"
 
 export interface VerificationLevelStatus {
   readonly level: number
   readonly name: string
   readonly ok: boolean
-  /** Why the level does not hold — a gate failure or a missing prerequisite. Empty when ok. */
+  /** Why the level does not hold - a gate failure or a missing prerequisite. Empty when ok. */
   readonly reasons: readonly string[]
 }
 
@@ -51,10 +49,18 @@ export async function collectVerificationLevels(
   cwd: string,
   options: CollectLevelsOptions = {},
 ): Promise<VerificationLevelsResult> {
+  // The ladder is the fullest view over the one project verification: L0 is the check view, L1/L2 read
+  // the route-assurance + capability evidence the same collector already computed (no second walk), and
+  // only the ladder-specific L3 (manifest) and L4 (invariants) are evaluated here.
+  const { collectProjectVerification } = await import("./verification.ts")
+  const verification = await collectProjectVerification(cwd, {
+    ...(options.config !== undefined ? { config: options.config } : {}),
+    maxDiagnostics: 5,
+  })
   const statuses: { level: number; name: string; ok: boolean; reasons: string[] }[] = []
 
-  // L0 — typed contract (`nifra check`).
-  const check = await collectCheckResult(cwd, { maxDiagnostics: 5 })
+  // L0 - typed contract (`nifra check`).
+  const check = await verification.check()
   statuses.push({
     level: 0,
     name: "typed contract",
@@ -63,11 +69,11 @@ export async function collectVerificationLevels(
   })
 
   // L1-L4 all hang off the assurance config; without it the ladder stops at L0 by definition.
-  let config: Awaited<ReturnType<typeof loadAssuranceConfig>> | undefined
-  try {
-    config = await loadAssuranceConfig(cwd, options.config)
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err)
+  if (verification.config === undefined) {
+    const reason =
+      verification.configError instanceof Error
+        ? verification.configError.message
+        : String(verification.configError)
     for (const [level, name] of [
       [1, "route assurance"],
       [2, "capability lockfile"],
@@ -78,9 +84,10 @@ export async function collectVerificationLevels(
     }
     return finalize(statuses)
   }
+  const config = verification.config
 
-  // L1 — route assurance.
-  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  // L1 - route assurance.
+  const assurance = verification.routeAssurance as AssuranceReport
   statuses.push({
     level: 1,
     name: "route assurance",
@@ -88,14 +95,13 @@ export async function collectVerificationLevels(
     reasons: assurance.findings.map((f) => f.message).slice(0, 5),
   })
 
-  // L2 — capability assurance + lockfile in sync.
+  // L2 - capability assurance + lockfile in sync.
   const l2Reasons: string[] = []
-  let capabilityReport: ReturnType<typeof evaluateCapabilityAssurance> | undefined
+  const capabilityReport = verification.capability?.report
   if (config.capabilities === undefined) {
     l2Reasons.push("nifra.assurance.ts declares no capabilities policy")
   } else {
-    const project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
-    capabilityReport = project.report
+    const project = verification.capability as CapabilityProjectReport
     if (!project.report.ok) {
       l2Reasons.push(...project.report.findings.map((f) => f.message).slice(0, 5))
     }
@@ -115,11 +121,11 @@ export async function collectVerificationLevels(
     reasons: l2Reasons,
   })
 
-  // L3 — emitted manifest hash-verifies AND matches the current app.
+  // L3 - emitted manifest hash-verifies AND matches the current app.
   const l3Reasons: string[] = []
   const manifestPath = resolve(cwd, config.manifest?.path ?? DEFAULT_MANIFEST_FILE)
   if (!existsSync(manifestPath)) {
-    l3Reasons.push(`manifest missing (${manifestPath}) — run \`nifra manifest emit\``)
+    l3Reasons.push(`manifest missing (${manifestPath}) - run \`nifra manifest emit\``)
   } else {
     try {
       const recorded = await parseNifraManifest(await Bun.file(manifestPath).text(), manifestPath)
@@ -130,7 +136,7 @@ export async function collectVerificationLevels(
           ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
         })
         if (current.contentHash !== recorded.contentHash) {
-          l3Reasons.push("manifest is stale — the app changed since it was emitted")
+          l3Reasons.push("manifest is stale - the app changed since it was emitted")
         }
       } else {
         l3Reasons.push("manifest cannot be validated while assurance is failing")
@@ -146,11 +152,11 @@ export async function collectVerificationLevels(
     reasons: l3Reasons,
   })
 
-  // L4 — contract-generated invariants against an explicitly isolated executor.
+  // L4 - contract-generated invariants against an explicitly isolated executor.
   const l4Reasons: string[] = []
   if (config.invariants === undefined) {
     l4Reasons.push(
-      "no isolated invariant executor configured — add `invariants.executor` in nifra.assurance.ts",
+      "no isolated invariant executor configured - add `invariants.executor` in nifra.assurance.ts",
     )
   } else {
     const invariants = await runAdversarialContract(config.source as ContractTestApp, {

package/src/load.ts

@@ -1,12 +1,12 @@
 /**
  * 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
+ *   - `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.
+ *   - `backend.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
+ * 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
@@ -14,11 +14,12 @@
  */
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
+import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
- * A plugin list — either an array, or a **thunk** that returns one (optionally async). Both forms are
+ * 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()`
+ * 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.
@@ -28,7 +29,7 @@ export type PluginsField =
   | (() => readonly unknown[] | Promise<readonly unknown[]>)
 
 /**
- * The CLI's framework wiring — exported from `nifra.config.ts` (or `framework.ts` as a fallback).
+ * 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).
  */
@@ -42,13 +43,40 @@ export interface NifraFramework {
   /** Bun build plugins that compile routes for the CLIENT bundle (`nifra build`), e.g.
    * `[vueBunPlugin("dom")]`. React/Preact JSX is Bun-native → none. */
   readonly clientPlugins?: PluginsField
-  /** Bun runtime plugins that compile routes for SSR — `nifra dev` (Bun-native route import) and
+  /** Bun runtime plugins that compile routes for SSR - `nifra dev` (Bun-native route import) and
    * `nifra start` register them via `Bun.plugin`, e.g. `[vueBunPlugin("ssr")]`. React/Preact → none. */
   readonly serverPlugins?: PluginsField
   /** Extra Bun.build / Vite resolve conditions, e.g. Solid's `["solid"]`. */
   readonly conditions?: readonly string[]
   /** Compile-time `define` replacements, e.g. Vue's `__VUE_*` flags. */
   readonly define?: Readonly<Record<string, string>>
+  /** 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
+}
+
+/**
+ * Refuse a config that puts one pipeline's plugins into the other's slot.
+ *
+ * Checked here rather than in `nifra check`, which holds a deliberate pre-`loadApp` invariant - reading
+ * plugins means importing the app's config, which is code execution. This runs at the moment the app
+ * IS loaded, so `dev`, `build` and `start` are all covered from one place, immediately before the
+ * plugins are handed to a bundler.
+ *
+ * Throws rather than warns. A misplaced plugin does not fail the build: Bun.build has no `transform`
+ * hook and Vite never calls `setup`, so the wrong-slot plugin is accepted and silently never invoked -
+ * the transform just does not happen, and the output looks plausible. A loud stop with the exact move
+ * is strictly better than a build that succeeds and omits the work. The classifier only fires on a
+ * decisive hook shape, so a plugin it cannot place is left alone.
+ */
+function assertPipelineSeparation(plugins: ResolvedPlugins, configFile: string): void {
+  const mismatches = checkPipelineSeparation(plugins)
+  if (mismatches.length === 0) return
+  throw new Error(
+    `[nifra] ${configFile}: plugins are in the wrong pipeline slot. nifra supports Vite and Bun, but a phase is owned by ONE of them - a plugin in the wrong slot is silently never called.\n\n` +
+      mismatches.map((m) => `  - ${m.fix}`).join("\n"),
+  )
 }
 
 /** Normalize a {@link PluginsField} (array | thunk | undefined) to a fresh array, awaiting a thunk. */
@@ -57,12 +85,20 @@ export async function resolvePlugins(field: PluginsField | undefined): Promise<u
   return value ? [...value] : []
 }
 
+export interface ResolvedPlugins {
+  readonly vitePlugins: readonly unknown[]
+  readonly clientPlugins: readonly unknown[]
+  readonly serverPlugins: readonly unknown[]
+}
+
 export interface LoadedApp {
   readonly cwd: string
   readonly routesDir: string
   /** Build output dir (also where `nifra start` reads `manifest.json` + serves `/assets/*`). */
   readonly outDir: string
   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`. */
   readonly backend: unknown
 }
@@ -73,7 +109,7 @@ export interface LoadAppOptions {
 }
 
 /**
- * Root-level monorepo config — exported from `nifra.config.ts` at the workspace root.
+ * 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`.
  *
@@ -109,7 +145,7 @@ export async function detectMonorepo(
 
 /**
  * Load all apps declared in a monorepo config. Returns `{ name, cwd, app }[]` in declaration order.
- * Individual app load failures throw — each app must be valid.
+ * Individual app load failures throw - each app must be valid.
  */
 export async function loadMonorepoApps(
   rootCwd: string,
@@ -151,7 +187,7 @@ export async function loadApp(
   }
   if (!existsSync(resolve(cwd, "routes"))) {
     throw new Error(
-      `[nifra] no routes/ directory in ${cwd} — nifra apps are file-routed under routes/.`,
+      `[nifra] no routes/ directory in ${cwd} - nifra apps are file-routed under routes/.`,
     )
   }
   const fw = (await importWithQuery(configPath, options.importQuery)) as Partial<NifraFramework>
@@ -160,6 +196,22 @@ export async function loadApp(
       `[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`,
     )
   }
+  // 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
+  // specifier would resolve against different bases and load in one phase but not the other. A bare or
+  // package specifier (`@nifrajs/web-react/client`) is location-independent and passes through unchanged.
+  const clientModule =
+    fw.clientModule.startsWith("./") || fw.clientModule.startsWith("../")
+      ? resolve(cwd, fw.clientModule)
+      : fw.clientModule
+  const [vitePlugins, clientPlugins, serverPlugins] = await Promise.all([
+    resolvePlugins(fw.vitePlugins),
+    resolvePlugins(fw.clientPlugins),
+    resolvePlugins(fw.serverPlugins),
+  ])
+  const resolvedPlugins = { vitePlugins, clientPlugins, serverPlugins }
+  assertPipelineSeparation(resolvedPlugins, configFile)
 
   let backend: unknown
   const backendPath = resolve(cwd, "backend.ts")
@@ -172,7 +224,8 @@ export async function loadApp(
     cwd,
     routesDir: resolve(cwd, "routes"),
     outDir: resolve(cwd, outDirName),
-    framework: fw as NifraFramework,
+    framework: { ...fw, clientModule } as NifraFramework,
+    resolvedPlugins,
     backend,
   }
 }

package/src/manifest-tool.ts

@@ -1,4 +1,4 @@
-/** `nifra manifest` — emit/sign/diff the deployable route trust artifact. */
+/** `nifra manifest` - emit/sign/diff the deployable route trust artifact. */
 
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
@@ -46,7 +46,9 @@ export async function runManifestEmit(
   options: { readonly config?: string; readonly out?: string; readonly sign?: string } = {},
 ): Promise<boolean> {
   const config = await loadAssuranceConfig(cwd, options.config)
-  const assurance = evaluateRouteAssurance(config.source, config.policy)
+  const assurance = evaluateRouteAssurance(config.source, config.policy, {
+    ...(config.capabilities !== undefined ? { definitions: config.capabilities.definitions } : {}),
+  })
   const capabilityProject =
     config.capabilities === undefined
       ? undefined

package/src/mcp-docs-tools.ts

@@ -1,5 +1,5 @@
 /**
- * The two project-INDEPENDENT MCP tools — `nifra_docs` + `nifra_example` — as a single factory shared
+ * The two project-INDEPENDENT MCP tools - `nifra_docs` + `nifra_example` - as a single factory shared
  * by every transport: the project stdio server ({@link projectTools}), the CLI HTTP server
  * (`nifra docs-mcp`), and the site's Cloudflare-Pages worker (`/mcp`). The corpus source is injected as
  * loaders, so the SAME tool definitions work whether the corpus comes from disk (`Bun.file`, on the
@@ -25,7 +25,7 @@ export function docsTools(
     {
       name: "nifra_docs",
       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).",
+        "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: {
         type: "object",
         properties: {
@@ -40,7 +40,7 @@ export function docsTools(
       handler: async (args) => {
         const corpus = await loadDocs()
         if (corpus === undefined) {
-          return "docs corpus missing — run `bun run gen:llms` in the nifra repo (published builds ship it)."
+          return "docs corpus missing - run `bun run gen:llms` in the nifra repo (published builds ship it)."
         }
         const { query, limit } = args as { query?: string; limit?: number }
         return renderDocsResult(corpus, query, clamp(limit, 1, 5, 3))
@@ -49,7 +49,7 @@ export function docsTools(
     {
       name: "nifra_example",
       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). 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, 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). Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
       inputSchema: {
         type: "object",
         properties: {
@@ -64,7 +64,7 @@ export function docsTools(
       handler: async (args) => {
         const corpus = await loadExamples()
         if (corpus === undefined) {
-          return "examples corpus missing — run `bun run gen:llms` in the nifra repo (published builds ship it)."
+          return "examples corpus missing - run `bun run gen:llms` in the nifra repo (published builds ship it)."
         }
         const { query, limit } = args as { query?: string; limit?: number }
         return renderExamplesResult(corpus, query, clamp(limit, 1, 5, 3))
@@ -73,14 +73,14 @@ export function docsTools(
     {
       name: "nifra_types",
       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.',
+        '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.',
       inputSchema: {
         type: "object",
         properties: {
           name: {
             type: "string",
             description:
-              "Exact symbol name — returns its literal declaration (e.g. RateLimitStore).",
+              "Exact symbol name - returns its literal declaration (e.g. RateLimitStore).",
           },
           query: {
             type: "string",
@@ -91,16 +91,26 @@ export function docsTools(
             type: "number",
             description: "Max results for a query/search (default 5, max 8).",
           },
+          full: {
+            type: "boolean",
+            description:
+              "Query mode only: return whole declarations instead of collapsed ones. Off by default - a search is for picking a symbol, and one match can be tens of thousands of characters.",
+          },
         },
         additionalProperties: false,
       },
       handler: async (args) => {
         const corpus = await loadTypes()
         if (corpus === undefined) {
-          return "types corpus missing — run `bun run build && bun run gen:llms` in the nifra repo (published builds ship it)."
+          return "types corpus missing - run `bun run build && bun run gen:llms` in the nifra repo (published builds ship it)."
+        }
+        const { name, query, limit, full } = args as {
+          name?: string
+          query?: string
+          limit?: number
+          full?: boolean
         }
-        const { name, query, limit } = args as { name?: string; query?: string; limit?: number }
-        return renderTypesResult(corpus, name, query, clamp(limit, 1, 8, 5))
+        return renderTypesResult(corpus, name, query, clamp(limit, 1, 8, 5), full === true)
       },
     },
   ]