@nifrajs/cli 2.2.0 → 2.3.0

package/src/init-agents.ts

@@ -1,18 +1,18 @@
 /**
- * `nifra init-agents` — retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
+ * `nifra init-agents` - retrofit an EXISTING app with the agent-discovery files a freshly scaffolded
  * app ships, so an already-built project adopts the nifra MCP in one command:
  *
- *   .mcp.json          — Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
- *   .cursor/mcp.json   — Cursor's MCP registry (same server config)
- *   CLAUDE.md          — Claude's MCP-first preamble + `@AGENTS.md` import
- *   AGENTS.md          — a `## MCP server` section appended (or a minimal file if none exists)
+ *   .mcp.json          - Claude Code's project MCP registry  (launches `bunx @nifrajs/cli mcp`)
+ *   .cursor/mcp.json   - Cursor's MCP registry (same server config)
+ *   CLAUDE.md          - Claude's MCP-first preamble + `@AGENTS.md` import
+ *   AGENTS.md          - a `## MCP server` section appended (or a minimal file if none exists)
  *
- * The generators are imported from `create-nifra/agent-files` — the SAME source of truth `create-nifra`
- * uses at scaffold time — so a retrofitted app and a freshly scaffolded one get byte-identical configs.
+ * The generators are imported from `create-nifra/agent-files` - the SAME source of truth `create-nifra`
+ * uses at scaffold time - so a retrofitted app and a freshly scaffolded one get byte-identical configs.
  *
  * Safety: this writes into the user's existing tree, so it NEVER silently clobbers a file they may have
  * customized. By default an existing `.mcp.json` / `CLAUDE.md` / `.cursor/mcp.json` is SKIPPED with a
- * notice; `--force` overwrites. `AGENTS.md` is special-cased — if it already has the MCP section it's
+ * notice; `--force` overwrites. `AGENTS.md` is special-cased - if it already has the MCP section it's
  * left alone, otherwise the section is APPENDED (never overwriting the user's conventions), and `--force`
  * is not needed for that append since it's additive. Every write path is resolved + confined under the
  * cwd (no `..` traversal escaping the project root).
@@ -34,10 +34,10 @@ import {
 export interface InitAgentsFileResult {
   /** Project-root-relative POSIX path. */
   readonly path: string
-  /** `wrote` — created or (with --force) overwrote; `appended` — added the MCP section to an existing
-   * AGENTS.md; `skipped` — already present and not forced; `present` — MCP section already there. */
+  /** `wrote` - created or (with --force) overwrote; `appended` - added the MCP section to an existing
+   * AGENTS.md; `skipped` - already present and not forced; `present` - MCP section already there. */
   readonly action: "wrote" | "appended" | "skipped" | "present"
-  /** Why it was skipped/left, for the notice (e.g. "exists — pass --force to overwrite"). */
+  /** Why it was skipped/left, for the notice (e.g. "exists - pass --force to overwrite"). */
   readonly note?: string
 }
 
@@ -52,7 +52,7 @@ export interface InitAgentsOptions {
 }
 
 /** Confine a project-relative path under `cwd` and return the absolute path. Rejects a spec that escapes
- * the root (defense-in-depth — these specs are constants, but the cwd-confinement invariant is enforced
+ * the root (defense-in-depth - these specs are constants, but the cwd-confinement invariant is enforced
  * at the seam, not assumed). Exported so the invariant is directly testable. */
 export function safeJoin(cwd: string, rel: string): string {
   const abs = resolve(cwd, rel)
@@ -80,7 +80,7 @@ async function writeOwned(
 ): Promise<InitAgentsFileResult> {
   const abs = safeJoin(cwd, rel)
   if (!force && (await fileExists(abs))) {
-    return { path: rel, action: "skipped", note: "exists — pass --force to overwrite" }
+    return { path: rel, action: "skipped", note: "exists - pass --force to overwrite" }
   }
   // `.cursor/mcp.json` needs its parent dir; `recursive` is a no-op for the root-level files.
   await mkdir(resolve(abs, ".."), { recursive: true })
@@ -91,7 +91,7 @@ async function writeOwned(
 /**
  * AGENTS.md is additive, not owned: if it exists and already has the MCP section, leave it; if it exists
  * without the section, append the section (preserving the user's conventions); if it's absent, write a
- * minimal AGENTS.md that is just the MCP section under a heading. `--force` is irrelevant here — we never
+ * minimal AGENTS.md that is just the MCP section under a heading. `--force` is irrelevant here - we never
  * overwrite the user's existing guidance.
  */
 async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
@@ -121,7 +121,7 @@ async function ensureAgentsMd(cwd: string): Promise<InitAgentsFileResult> {
 
 /**
  * Retrofit `cwd` with the four agent-discovery files. Pure enough to unit-test (no argv, no process.exit,
- * no console) — the CLI wrapper handles printing + the exit code.
+ * no console) - the CLI wrapper handles printing + the exit code.
  */
 export async function initAgents(
   cwd: string,
@@ -153,13 +153,13 @@ export function renderInitAgents(result: InitAgentsResult): string {
   const wroteAny = result.files.some((f) => f.action === "wrote" || f.action === "appended")
   const footer = wroteAny
     ? "\nThe nifra MCP is now registered. Restart your agent so it picks up .mcp.json, then prefer nifra_docs / nifra_example and gate on nifra check."
-    : "\nNothing to do — every file was already present (use --force to overwrite the owned ones)."
+    : "\nNothing to do - every file was already present (use --force to overwrite the owned ones)."
   return `nifra init-agents\n\n${lines.join("\n")}\n${footer}`
 }
 
 /**
  * CLI entry: run the retrofit at `cwd` and print the result. Returns `true` (the command always succeeds
- * unless a write throws — which propagates as a non-zero exit via the dispatcher's catch). `--json`
+ * unless a write throws - which propagates as a non-zero exit via the dispatcher's catch). `--json`
  * emits the structured result for agents/CI.
  */
 export async function runInitAgents(

package/src/internal/typescript-import.ts

@@ -0,0 +1,33 @@
+/**
+ * The one place the CLI imports TypeScript from.
+ *
+ * The interpolated-SQL rule parses source with the TypeScript compiler, because the regex it replaced
+ * could not tell `sql\`… ${id} …\`` (bound) from a plain template (injectable) without guessing at
+ * string and comment boundaries. That is the right tool, but it is a ~25 MB dependency, and the CLI's
+ * own typecheck step already treats `tsc` as something the PROJECT provides rather than something the
+ * CLI ships. Making it a hard dependency would have contradicted that for every install.
+ *
+ * So it is an optional peer, resolved at the moment the rule runs. Every Nifra project has TypeScript
+ * - the templates all ship a `typecheck` script - so this resolves in practice; the point is that an
+ * install does not pay for it.
+ */
+
+/** The slice of the compiler the SQL scanner uses. Structural, so the peer stays optional. */
+export type TypeScriptApi = typeof import("typescript")
+
+/**
+ * Import the project's TypeScript, or `undefined` when it is not installed.
+ *
+ * Only a RESOLUTION failure is absence. A compiler that resolves and then fails while evaluating is a
+ * broken install, not a missing one, and telling that user to install what they already have sends
+ * them the wrong way - so that error is rethrown for the caller to report.
+ */
+export async function importTypeScript(): Promise<TypeScriptApi | undefined> {
+  try {
+    return (await import("typescript")) as TypeScriptApi
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    if (/cannot find (?:package|module)|ERR_MODULE_NOT_FOUND/i.test(message)) return undefined
+    throw cause
+  }
+}

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
@@ -17,9 +17,9 @@ 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.
@@ -29,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).
  */
@@ -43,7 +43,7 @@ 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"]`. */
@@ -109,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`.
  *
@@ -145,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,
@@ -187,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>
@@ -196,6 +196,15 @@ 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),
@@ -215,7 +224,7 @@ 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