@nifrajs/cli 2.10.0 → 2.12.0

package/src/cli.ts

@@ -3,7 +3,7 @@
  * `nifra` - the zero-config CLI for a nifra app. Reads `framework.ts` + `backend.ts` + `routes/` from
  * the project root (see {@link loadApp}) and wires the right `@nifrajs/web` entrypoint:
  *
- *   nifra dev      true-HMR dev server (Vite middleware + nifra SSR)        - @nifrajs/web/vite
+ *   nifra dev      true-HMR dev server (Bun native HMR + nifra SSR)         - @nifrajs/web/dev
  *   nifra build    emit a complete target-specific deploy directory        - @nifrajs/web/build
  *   nifra start    run the default Bun build                               - dist/server.js
  *
@@ -12,12 +12,17 @@
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
 import { inProcessClient } from "@nifrajs/client"
-import { createWebApp, DEFAULT_DEV_PORT, type RenderAdapter } from "@nifrajs/web"
+import {
+  type CreateWebAppOptions,
+  createWebApp,
+  DEFAULT_DEV_PORT,
+  type RenderAdapter,
+} from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
 import { describeProject, describeRouteGraph, describeRoutes } from "./introspect.ts"
-import { type LoadedApp, loadApp } from "./load.ts"
-import { chooseBuildPipeline } from "./pipeline-guard.ts"
+import { type LoadedApp, loadApp, type NifraFramework } from "./load.ts"
+import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
 export interface Flags {
   readonly port: number
@@ -30,9 +35,8 @@ export interface Flags {
   /** `nifra build --vite`: force the client + server through Vite/Rollup. Without a flag the pipeline is
    * chosen per app (`chooseBuildPipeline`) - Bun unless the app's only transforms are `vitePlugins`. */
   readonly vite: boolean
-  /** `nifra dev --bun`: run the Bun-pipeline dev server (Bun.serve native HMR - including React Fast
-   * Refresh with state preserved - and no Vite in the process). Default stays Vite for its plugin
-   * ecosystem; `--bun` trades that for one bundler across dev and prod. Refuses CSS-Modules apps.
+  /** `nifra dev --bun`: force the Bun-pipeline dev server. Rarely needed - `dev` and `build` share one
+   * rule, so Bun is already the default unless `vitePlugins` are the app's ONLY transforms.
    *
    * `nifra build --bun`: force the Bun build. Refuses when that would drop the app's `vitePlugins`. */
   readonly bun: boolean
@@ -41,11 +45,14 @@ export interface Flags {
 const HELP = `nifra - zero-config dev/build/start for a nifra app
 
 Usage:
-  nifra dev     [--port <n>] [--poll]    Start the true-HMR dev server (Vite). Default port ${DEFAULT_DEV_PORT}.
-                [--bun]                  Run the BUN pipeline instead: Bun.serve native HMR (React Fast
-                                         Refresh included, state preserved), no Vite in the process - one
-                                         bundler across dev and prod. Plain CSS/Tailwind work; refuses an
-                                         app using *.module.css (Bun's dev bundler can't transform it).
+  nifra dev     [--port <n>] [--poll]    Start the true-HMR dev server (Bun). Default port ${DEFAULT_DEV_PORT}.
+                                         An app whose ONLY transforms are \`vitePlugins\` uses Vite (the
+                                         Bun pipeline cannot run them); everything else uses Bun.
+                [--vite]                 Force the Vite middleware/HMR pipeline.
+                [--bun]                  Force Bun.serve native HMR (React Fast Refresh included, state
+                                         preserved), no Vite in the process. CSS Modules, plain CSS,
+                                         Tailwind and the app's own \`clientPlugins\`/\`serverPlugins\` run
+                                         through the same Bun transforms production uses.
   nifra build   [--out <dir>] [--report]  Emit a complete deploy directory.
                 [--target <t>]             Target a FULL deploy dir for <t>:
                                          bun | node | deno | cf-pages | vercel | static. Packages
@@ -80,8 +87,11 @@ Usage:
                                          and a "## MCP server" section in AGENTS.md. No-clobber by
                                          default (skips a file you've customized); --force overwrites the
                                          owned files. AGENTS.md is only appended to, never overwritten.
-  nifra mcp                              Start an MCP server (stdio) exposing this project to a coding
-                                         agent: nifra_context, nifra_routes (routes+schemas as JSON),
+  nifra mcp [dir]                        Start an MCP server (stdio) exposing this project to a coding
+                                         agent. The project root is [dir] when given, else resolved from
+                                         cwd (marker walk-up + the client's MCP roots); tools refuse
+                                         with a fix when no nifra project is found - never a silent
+                                         wrong-project answer. Tools: nifra_context, nifra_routes,
                                          nifra_run (backend), nifra_render (SSR a page), nifra_docs,
                                          nifra_example (verified snippets), nifra_scaffold (route→file),
                                          nifra_check (drift gate + fixes), nifra_levels (verification
@@ -94,6 +104,8 @@ Usage:
   nifra check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
                                          server-only imports in routes/). Run as "done"; --json for agents;
                                          --lints-only skips tsc for a near-instant inner-loop pass.
+  nifra fix     [--code <NF-code>]       Apply a registered diagnostic recipe, then print the remaining
+                                         structured diagnostics.
   nifra sync-manifest                    Regenerate a committed web server-manifest.ts from routes/ WITHOUT
                                          a full build - clears server-manifest drift after a route add/rename
                                          (a new hydrating component still needs a full build).
@@ -109,9 +121,14 @@ Usage:
                                          closed. Exits non-zero on any breaking change - run it in CI.
   nifra sdk     --lang <python|go> [--out <file>]
                                          Generate a deterministic non-TypeScript SDK from backend.ts.
-  nifra assure  [--config <file>] [--json]  Route-assurance gate: load nifra.assurance.ts, classify every
-                                         reflected backend route, and fail when required enforcement
-                                         evidence is missing/forbidden or a route is unclassified.
+  nifra assure  [--config <file>] [--json] [--strict] [--out <file>] [--hydration] [--interact]
+                                         Emit one structured assurance bundle. The bundle records every
+                                         applicable gate as pass, fail, or skip and exits non-zero unless
+                                         its verdict is green. Without these bundle flags, the legacy
+                                         route-assurance report remains available.
+  nifra contracts snapshot [--out <file>] Write the deterministic route contract lock.
+  nifra contracts check [--json]          Check the current routes against contracts.lock.json.
+  nifra replay <file>                     Replay a token-only verification metadata file.
   nifra capabilities snapshot [--out <file>] [--config <file>]
                                          Write the deterministic, token-only capability lockfile, but
                                          only after provenance + idempotency assurance passes.
@@ -128,9 +145,15 @@ Usage:
                                          Compute the verification ladder (L0 typed contract → L1 route
                                          assurance → L2 capability lockfile → L3 route manifest → L4
                                          invariant-tested); --min <n> fails the exit code below level n.
+  nifra prove    [--json] [--file <path>] [--min <n>]
+                                         Build the static verification work graph, plan the cheapest
+                                         proofs for changed files, and report a machine-checkable stop
+                                         condition. Requires a fresh build; never probes a running app.
   nifra doctor  [--json] [--auto-fix]    Flag undeclared imports and multiple physical copies of
-                                         @nifrajs/core/React identity-sensitive dependencies;
-                                         --auto-fix writes safe local-version dependency fixes.
+                [--strict] [--target]     @nifrajs/core/React identity-sensitive dependencies;
+                                         print production readiness, with --strict making absent
+                                         applicable guarantees fail. --auto-fix writes safe local-
+                                         version dependency fixes.
   nifra upgrade <version>                Run the per-release upgrade recipe for <version>: sweep every
                 [--write] [--no-verify]  matching dependency pin (preserving ^/~/exact), move removed
                 [--list] [--json]        packages, apply exact imports, then verify with nifra check.
@@ -152,11 +175,13 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "2.10.0"
+const CLI_VERSION = "2.12.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter
 const asBunPlugins = (v: readonly unknown[]): BunPlugin[] => v as BunPlugin[]
+const asUse = (v: (app: never) => void): NonNullable<CreateWebAppOptions["use"]> =>
+  v as NonNullable<CreateWebAppOptions["use"]>
 const apiOf = (backend: unknown): { api?: unknown } =>
   backend === undefined ? {} : { api: inProcessClient(backend as never) }
 
@@ -194,52 +219,26 @@ export function formatCliError(err: unknown): string {
   return String(err)
 }
 
-/**
- * Refuse `nifra dev --bun` for an app Bun's DEV-server bundler cannot compile.
- *
- * Bun's dev server and `Bun.build` are not the same bundler. `Bun.build` transforms `*.module.css` into a
- * scoped class map (the Bun production build of a CSS-Modules app works, verified), but the dev server's
- * bundler does not: the import compiles to a dangling reference and the browser throws
- * `ReferenceError: import_X_module is not defined` from inside the component - a message that names
- * neither CSS Modules nor the dev server, so the cause is invisible.
- *
- * A silently-broken client is the one outcome worth failing the command over, so this checks up front and
- * names the trade plus both ways out. Narrow by design: only the transform proven missing is refused, so
- * an app without CSS Modules still gets the Bun dev loop.
- */
-export async function assertBunDevSupportsApp(app: LoadedApp): Promise<void> {
-  // Server functions and `*.server` modules are handled: the generated bunfig (dev-bun-config.ts)
-  // delivers the SAME serverFnStubPlugin/serverOnlyEmptyPlugin the production build uses to Bun's
-  // dev-server bundler via `[serve.static] plugins` - the one channel that bundler accepts plugins
-  // through (a runtime `Bun.plugin` never reaches it; programmatic ask: oven-sh/bun#36830). The old
-  // fail-closed refusal for those modules is gone because the leak it guarded is gone.
-  //
-  // CSS Modules remain gated: the `*.module.css` plugin rests on an `onResolve` virtual-module
-  // stylesheet emitter that is not yet verified under `[serve.static]`, and its failure mode is a
-  // broken client rather than a leak - refuse loudly until it is proven there.
-  const { Glob } = await import("bun")
-  const offenders: string[] = []
-  for await (const file of new Glob("**/*.module.css").scan({ cwd: app.cwd, dot: false })) {
-    if (/(^|\/)(node_modules|dist|\.nifra|\.git)\//.test(file)) continue
-    offenders.push(file)
-    if (offenders.length >= 5) break
-  }
-  if (offenders.length === 0) return
-  throw new Error(
-    "[nifra] `nifra dev --bun` can't compile CSS Modules: Bun's DEV-server bundler has no `*.module.css` " +
-      "transform (its production `Bun.build` does, so `nifra build` is unaffected). The client would load " +
-      "with a bare `ReferenceError: import_… is not defined` instead of your component.\n" +
-      `  CSS Modules found: ${offenders.join(", ")}\n` +
-      "  Use `nifra dev` (the Vite pipeline handles them), or drop the CSS Modules to use the Bun dev loop.",
-  )
-}
-
 async function dev(app: LoadedApp, flags: Flags): Promise<void> {
-  // `--bun`: the Bun-pipeline dev server - Bun.serve's native HMR bundles + hot-reloads the client while
-  // Bun's runtime resolves SSR, with no Vite in the process at all. The mirror of `nifra build --vite`:
-  // each pipeline is selectable in BOTH phases, and neither ever runs inside the other.
-  if (flags.bun) {
-    await assertBunDevSupportsApp(app)
+  if (flags.vite && flags.bun) {
+    throw new Error("[nifra] `nifra dev` takes `--vite` or `--bun`, not both.")
+  }
+  // Default to Bun for the dev phase too. An app whose only transforms are Vite plugins stays on Vite so
+  // its transform is never silently dropped; `--vite`/`--bun` make that choice explicit.
+  // ONE rule for both phases - `chooseBuildPipeline` decides `dev` exactly as it decides `build`, so a
+  // project cannot end up bundled by one toolchain in dev and the other in production. An earlier
+  // version of this kept apps declaring `vitePlugins` on Vite for dev even when they also shipped Bun
+  // equivalents, on the theory that the framework plugins were the safer HMR path. Measurement killed
+  // it: Vue, Solid and Svelte all render correctly on the Bun pipeline, so the hedge bought nothing
+  // and cost an app the guarantee that dev and production bundle the same way. (Svelte used to render
+  // ONLY on Bun, which made the hedge actively harmful; it now renders on either - see the note at the
+  // Vite branch for what the adapter had to be given to make that true.)
+  const decision = chooseBuildPipeline(
+    app.resolvedPlugins,
+    flags.vite ? "vite" : flags.bun ? "bun" : undefined,
+    "dev",
+  )
+  if (decision.pipeline === "bun") {
     // Bun's dev-server bundler takes plugins only via bunfig `[serve.static]`, read at process
     // start - so the boundary plugins (server-fn stubs, server-only emptying) are delivered by
     // generating a config and re-execing this same command once with `--config=`. The child proves
@@ -259,15 +258,36 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
             "launches; refusing to serve without the client-boundary plugins.",
         )
       }
-      const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd)
+      const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd, app.configPath)
       const child = Bun.spawn(
-        [process.execPath, `--config=${bunfigPath}`, ...process.argv.slice(1)],
+        [
+          process.execPath,
+          `--config=${bunfigPath}`,
+          // The app's `conditions` reach SSR here or nowhere: bunfig has no key for them (a top-level,
+          // `[run]`, `[serve.static]` or `[bundle]` `conditions` is parsed and ignored), and the re-exec
+          // is the only point where this process's resolver is still configurable. Without it a package
+          // with an `exports` map resolves to a DIFFERENT file on the server than in the client bundle,
+          // which is the two-toolchains-one-module failure the pipeline guard exists to prevent.
+          //
+          // One flag per condition. `--conditions=a,b` is accepted and matches nothing: Bun takes the
+          // whole string as a single condition name, so the comma form fails silently.
+          ...(app.framework.conditions ?? []).map((condition) => `--conditions=${condition}`),
+          ...process.argv.slice(1),
+        ],
         {
           stdio: ["inherit", "inherit", "inherit"],
           env: {
             ...process.env,
             NIFRA_BUN_DEV_TOKEN: launchToken,
             NIFRA_BUN_DEV_DEPTH: String(depth + 1),
+            // The child is the process that renders, so it is the one that needs dev-shaped runtimes.
+            // A library ships its dev build behind the `development` export condition with a `NODE_ENV`
+            // fallback for resolvers that set no conditions - which is Bun's runtime, where SSR runs,
+            // so on the server that fallback is the only signal there is. It has to be in place before
+            // the app's config is read, because reading it imports the adapter and through it the
+            // framework runtime; setting it inside the dev server would already be a step too late.
+            // Preserved if the caller pinned one.
+            NODE_ENV: process.env.NODE_ENV ?? "development",
           },
         },
       )
@@ -276,6 +296,27 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
       process.on("SIGTERM", forward)
       process.exit(await child.exited)
     }
+    // SSR runs in THIS process, on Bun's runtime - a different loader from the dev-server bundler the
+    // bunfig above configures. Both halves have to agree, so the runtime gets the same transforms:
+    //
+    //   - CSS Modules. The scoped name is a pure function of file path + class name, so the `"ssr"` form
+    //     produces the identical map the client bundle emits (and no stylesheet - that ships from the
+    //     client build). Without it `styles.box` is `undefined` on the server: the SSR markup carries no
+    //     class, the page paints unstyled, and hydration then reports a className mismatch.
+    //   - the app's `serverPlugins` - the SSR counterpart of the `clientPlugins` the generated bunfig
+    //     delivers, exactly as `nifra build`'s prerender pass registers them.
+    //
+    // Registered BEFORE `createDevServer`, because a Bun runtime plugin only affects modules loaded
+    // after it - and `createApp` imports the route modules.
+    const { plugin } = await import("bun")
+    const { cssModulesBunPlugin } = await import("@nifrajs/web/plugins/css-modules")
+    plugin(cssModulesBunPlugin("ssr"))
+    for (const p of asBunPlugins(app.resolvedPlugins.serverPlugins)) plugin(p)
+    // "After" has one consequence an adapter has to respect. Reading the app's config is what PRODUCES
+    // these plugins, so the config's import graph - which includes the adapter - is already loaded when
+    // they register. An adapter must therefore not import an asset its own plugin compiles at module
+    // scope; it has to defer to first render, which happens after this point. `@nifrajs/web-svelte`
+    // loads its `Chain.svelte` that way for exactly this reason, and says so at the import.
     const { createDevServer } = await import("@nifrajs/web/dev")
     const { framework: fw, routesDir, outDir, backend } = app
     const server = await createDevServer({
@@ -283,8 +324,10 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
       outDir,
       clientModule: fw.clientModule,
       port: flags.port,
-      // The Bun pipeline's own plugins (SFC compilers etc.) - never `vitePlugins`, which belong to the
-      // other pipeline; `assertPipelineSeparation` already refuses a plugin sitting in the wrong slot.
+      // For the background client-leak guard, which re-runs `buildClient` on change - the SERVED client
+      // bundle gets these same plugins through the generated bunfig, since Bun's dev-server bundler takes
+      // plugins only as module paths. Never `vitePlugins`, which belong to the other pipeline;
+      // `assertPipelineSeparation` already refuses a plugin sitting in the wrong slot.
       plugins: asBunPlugins(app.resolvedPlugins.clientPlugins),
       ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
       ...(fw.conditions ? { conditions: fw.conditions } : {}),
@@ -294,13 +337,15 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
           adapter: asAdapter(fw.adapter),
           manifest: discoverRoutes(routesDir, { importQuery }),
           clientEntry,
+          ...(fw.use ? { use: asUse(fw.use) } : {}),
           ...apiOf(backend),
         }),
     })
     console.log(`nifra dev (bun) → http://localhost:${server.port}`)
+    console.log(`  ${describePipeline(decision)}`)
     return
   }
-  // Preflight: `nifra dev` needs `vite` resolvable from the project. Run via `bunx @nifrajs/cli dev` the CLI
+  // Preflight: the Vite fallback needs `vite` resolvable from the project. Run via `bunx @nifrajs/cli dev` the CLI
   // sits in an isolated install where the project's peer deps don't resolve, so the vite import below fails
   // with an opaque ERR_MODULE_NOT_FOUND. Surface the real fix instead.
   try {
@@ -321,6 +366,18 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
   // same file in one process, with only one of them governed by Vite's `resolve.dedupe`. That is what
   // made an app's hand-written React alias fail to reach SSR, and it is the condition being removed -
   // not a redundancy worth keeping "just in case".
+  //
+  // Svelte is the case that proves the rule, and the discarded attempts are recorded so they are not
+  // retried. The adapter package stays `ssr.external` (its context must be the ONE instance the
+  // Bun-imported adapter provides), so BUN loads it - and `@nifrajs/web-svelte` renders through its own
+  // `Chain.svelte`, which needs a compiler that this pipeline does not put in the runtime. Registering
+  // the app's `serverPlugins` here, scoped to that package's directory, compiles it against a SECOND
+  // Svelte runtime and the first `setContext` dies (`context.function` null); externalizing the
+  // adapter's framework peer as well gets further and then dies on `context.function[FILENAME]`,
+  // because `svelteBunPlugin` and `vite-plugin-svelte` do not emit the same dev-mode component shape.
+  // Both attempts add a compiler. The fix removes one instead: `createViteDevServer` publishes its
+  // `ssrLoadModule` via `setSsrModuleLoader`, and the adapter loads `Chain.svelte` AND `svelte/server`
+  // through it - one toolchain, one runtime, context intact across the whole tree.
   const server = await createViteDevServer({
     root: cwd,
     routesDir,
@@ -340,10 +397,12 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
         adapter: asAdapter(fw.adapter),
         manifest: discoverRoutes(routesDir, { load }),
         clientEntry,
+        ...(fw.use ? { use: asUse(fw.use) } : {}),
         ...apiOf(backend),
       }),
   })
-  console.log(`nifra dev → http://localhost:${server.port}`)
+  console.log(`nifra dev (vite) → http://localhost:${server.port}`)
+  console.log(`  ${describePipeline(decision)}`)
 }
 
 /**
@@ -353,6 +412,37 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
  * `nifra.config.ts`, which pulls in Vite plugins), and the backend from `backend.ts` when present;
  * `buildTarget` generates the per-target server entry from those + the app's `routes/`.
  */
+/**
+ * Refuse a `use` the generated server entry cannot import.
+ *
+ * `nifra build` emits `import { use } from <frameworkFile>` (framework.ts, the edge-bundlable file),
+ * but `loadApp` prefers `nifra.config.ts` - so an app with BOTH files whose `use` lives only in
+ * `nifra.config.ts` makes `fw.use` defined while `framework.ts` exports nothing of that name, and the
+ * build dies later with an opaque bundler error pointing at generated code. Refuse it here with the
+ * exact move instead, in the spirit of `assertPipelineSeparation` (load.ts).
+ *
+ * Detected by importing `frameworkFile` and checking the named export, not by comparing paths alone:
+ * a split app legitimately DEFINES `use` in framework.ts and re-exports it from nifra.config.ts
+ * (exactly how `adapter` reaches both readers), and a path compare would refuse that correct layout.
+ * The import is cheap - framework.ts is already in the loaded config's module graph in that layout.
+ */
+export async function assertUseIsEdgeExported(
+  use: NifraFramework["use"],
+  configPath: string,
+  frameworkFile: string,
+): Promise<void> {
+  if (use === undefined || configPath === frameworkFile) return
+  const mod = (await import(frameworkFile).catch(() => ({}))) as { use?: unknown }
+  if (typeof mod.use === "function") return
+  throw new Error(
+    `[nifra] \`use\` is exported from ${configPath} but not from ${frameworkFile}. ` +
+      "`nifra build` generates a server entry that imports `use` from framework.ts (the edge-bundled " +
+      "file), so this build would fail later with an opaque bundler error inside generated code.\n\n" +
+      "  - Define `use` in framework.ts and re-export it from nifra.config.ts " +
+      '(`export { use } from "./framework.ts"`) so `nifra dev` sees it too.',
+  )
+}
+
 async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Promise<void> {
   const { isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import("@nifrajs/web/build")
   if (!isBuildTarget(target)) {
@@ -384,6 +474,7 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
       ? resolve(cwd, "nifra.config.ts")
       : resolve(cwd, "framework.ts")
   const backendFile = resolve(cwd, "backend.ts")
+  await assertUseIsEdgeExported(fw.use, app.configPath, frameworkFile)
   // Plugin FORMAT differs by pipeline: the Bun build takes Bun plugins (clientPlugins/serverPlugins); the
   // Vite build takes the app's Vite plugins (fw.vitePlugins) for BOTH halves. buildTargetWith forwards
   // whatever it's given straight to the chosen bundler, which casts to its own plugin type.
@@ -402,6 +493,7 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
     workDir: resolve(cwd, ".nifra-build"),
     clientModule: fw.clientModule,
     adapterImport: frameworkFile,
+    ...(fw.use ? { useImport: frameworkFile } : {}),
     ...(backend !== undefined && existsSync(backendFile) ? { backendImport: backendFile } : {}),
     ...plugins,
     ...(fw.conditions ? { conditions: fw.conditions } : {}),
@@ -411,10 +503,10 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
     // The static target needs a built app to drive prerendering - only build it when targeting static.
     ...(target === "static" ? { prerenderApp: await buildPrerenderApp(app) } : {}),
   })
-  console.log(`nifra build (${target}${useVite ? ", vite" : ""}) → ${result.run}`)
-  // An auto-selected pipeline is stated, never silent: the user asked for the default and got something
-  // else, and the reason is the thing that makes that legible instead of surprising.
-  if (decision.reason !== undefined) console.log(`  ${decision.reason}`)
+  console.log(`nifra build (${target}, ${decision.pipeline}) → ${result.run}`)
+  // The pipeline is stated on every build, not only the surprising ones - an auto-selected Vite build
+  // must never look like the default, and a default Bun build must not leave the question open either.
+  console.log(`  ${describePipeline(decision)}`)
   if (flags.report) console.log(`\n${renderSizeReport(result.size)}`)
 }
 
@@ -435,6 +527,7 @@ async function buildPrerenderApp(
       adapter: asAdapter(fw.adapter),
       manifest: discoverRoutes(routesDir),
       clientEntry: client.entry,
+      ...(fw.use ? { use: asUse(fw.use) } : {}),
       ...(client.routes ? { routePreload: client.routes } : {}),
       ...(client.css ? { styles: client.css } : {}),
       ...(client.routeStyles ? { routeStyles: client.routeStyles } : {}),
@@ -511,7 +604,10 @@ async function main(): Promise<void> {
   // the eager `loadApp` below (which would fail fast on a project that's API-only / not yet built).
   if (command === "mcp") {
     const { runMcpServer } = await import("./mcp.ts")
-    await runMcpServer(process.cwd(), CLI_VERSION)
+    // `nifra mcp [dir]` - an explicit project directory pins the root (for clients configured outside
+    // the project); otherwise the server resolves it from cwd + the client's MCP roots.
+    const dirArg = argv[1] !== undefined && !argv[1].startsWith("-") ? argv[1] : undefined
+    await runMcpServer(process.cwd(), CLI_VERSION, dirArg)
     return
   }
   // `docs-mcp` runs the PUBLIC docs MCP over HTTP - project-independent (serves the bundled corpus), so
@@ -546,12 +642,36 @@ async function main(): Promise<void> {
     if (
       !(await runCheck(process.cwd(), {
         json: argv.includes("--json"),
+        structured: argv.includes("--json"),
         lintsOnly: argv.includes("--lints-only"),
       }))
     )
       process.exitCode = 1
     return
   }
+  if (command === "fix") {
+    const codeIndex = argv.indexOf("--code")
+    const code = codeIndex === -1 ? undefined : argv[codeIndex + 1]
+    try {
+      const { collectCheckResult } = await import("./check.ts")
+      const { applyDiagnosticRecipe } = await import("./fix-recipes.ts")
+      const result = await collectCheckResult(process.cwd(), { lintsOnly: true })
+      const changed: string[] = []
+      for (const diagnostic of result.structuredDiagnostics ?? []) {
+        if (code !== undefined && diagnostic.code !== code) continue
+        changed.push(...(await applyDiagnosticRecipe(process.cwd(), diagnostic)))
+      }
+      const final = await collectCheckResult(process.cwd(), { lintsOnly: true })
+      console.log(
+        JSON.stringify({ changed, diagnostics: final.structuredDiagnostics ?? [] }, null, 2),
+      )
+      if (final.ok === false) process.exitCode = 1
+    } catch (err) {
+      console.error(formatCliError(err))
+      process.exitCode = 1
+    }
+    return
+  }
   // `init-agents` retrofits the agent-discovery files (.mcp.json, CLAUDE.md, …) into the cwd. It's a
   // pure file-writing command independent of the app loading, so dispatch it before the eager `loadApp`
   // (an existing app might be API-only or not yet built). It always succeeds unless a write throws.
@@ -582,10 +702,19 @@ async function main(): Promise<void> {
   // so it runs on an API-only / not-yet-built project.
   if (command === "doctor") {
     const { runDoctor } = await import("./doctor.ts")
+    const targetIdx = argv.indexOf("--target")
+    const target = targetIdx !== -1 ? argv[targetIdx + 1] : undefined
+    if (targetIdx !== -1 && (target === undefined || target.startsWith("-"))) {
+      console.error("[nifra] --target needs a value: bun | node | deno | cf-pages | vercel")
+      process.exitCode = 1
+      return
+    }
     if (
       !(await runDoctor(process.cwd(), {
         json: argv.includes("--json"),
         autoFix: argv.includes("--auto-fix") || argv.includes("--fix"),
+        strict: argv.includes("--strict"),
+        ...(target === undefined ? {} : { target }),
       }))
     )
       process.exitCode = 1
@@ -662,6 +791,16 @@ async function main(): Promise<void> {
       if (
         !(await runAssurance(process.cwd(), {
           json: argv.includes("--json"),
+          bundle:
+            argv.includes("--json") ||
+            argv.includes("--strict") ||
+            argv.includes("--hydration") ||
+            argv.includes("--interact") ||
+            argv.includes("--out"),
+          strict: argv.includes("--strict"),
+          hydration: argv.includes("--hydration"),
+          interact: argv.includes("--interact"),
+          ...(argv.includes("--out") ? { out: argv[argv.indexOf("--out") + 1] } : {}),
           ...(config !== undefined ? { config } : {}),
         }))
       )
@@ -672,6 +811,49 @@ async function main(): Promise<void> {
     }
     return
   }
+  if (command === "contracts") {
+    const action = argv[1]
+    const outIndex = argv.indexOf("--out")
+    const out = outIndex === -1 ? undefined : argv[outIndex + 1]
+    try {
+      const { checkContractsLock, snapshotContracts } = await import("./contracts.ts")
+      if (action === "snapshot") {
+        const lock = await snapshotContracts(process.cwd(), out)
+        if (argv.includes("--json")) console.log(JSON.stringify(lock, null, 2))
+        else console.log(`[nifra] wrote ${Object.keys(lock.routes).length} contract digests`)
+      } else if (action === "check") {
+        const result = await checkContractsLock(process.cwd())
+        const output = { ok: result.present && result.diagnostics.length === 0, ...result }
+        console.log(JSON.stringify(output, null, 2))
+        if (!output.ok) process.exitCode = 1
+      } else {
+        console.error("[nifra] contracts needs snapshot or check")
+        process.exitCode = 1
+      }
+    } catch (err) {
+      console.error(formatCliError(err))
+      process.exitCode = 1
+    }
+    return
+  }
+  if (command === "replay") {
+    const file = argv[1]
+    if (file === undefined || file.startsWith("-")) {
+      console.error("[nifra] replay needs a file path")
+      process.exitCode = 1
+      return
+    }
+    try {
+      const { runReplay } = await import("./replay.ts")
+      const result = await runReplay(process.cwd(), file)
+      console.log(JSON.stringify(result, null, 2))
+      if (!result.ok) process.exitCode = 1
+    } catch (err) {
+      console.error(formatCliError(err))
+      process.exitCode = 1
+    }
+    return
+  }
   if (command === "capabilities") {
     const action = argv[1]
     const valueAfter = (flag: string): string | undefined => {
@@ -786,6 +968,45 @@ async function main(): Promise<void> {
     }
     return
   }
+  if (command === "prove") {
+    const valueAfter = (flag: string): string | undefined => {
+      const index = argv.indexOf(flag)
+      const value = index === -1 ? undefined : argv[index + 1]
+      if (index !== -1 && (value === undefined || value.startsWith("-"))) {
+        throw new Error(`[nifra] ${flag} needs a value`)
+      }
+      return value
+    }
+    try {
+      const minRaw = valueAfter("--min")
+      const min = minRaw === undefined ? undefined : Number(minRaw)
+      if (min !== undefined && (!Number.isInteger(min) || min < 0 || min > 4)) {
+        throw new Error("[nifra] --min must be an integer level between 0 and 4")
+      }
+      const changedFiles: string[] = []
+      for (let index = 0; index < argv.length; index++) {
+        if (argv[index] !== "--file") continue
+        const file = argv[index + 1]
+        if (file === undefined || file.startsWith("-"))
+          throw new Error("[nifra] --file needs a path")
+        changedFiles.push(file)
+        index++
+      }
+      const { runWorkGraph } = await import("./work-graph.ts")
+      if (
+        !(await runWorkGraph(process.cwd(), {
+          json: argv.includes("--json"),
+          ...(changedFiles.length === 0 ? {} : { changedFiles }),
+          ...(min === undefined ? {} : { minLevel: min }),
+        }))
+      )
+        process.exitCode = 1
+    } catch (err) {
+      console.error(formatCliError(err))
+      process.exitCode = 1
+    }
+    return
+  }
   // `upgrade` is a pure cwd file-transformer (package.json pins + import moves) driven by a per-release
   // recipe, then verified with `nifra check`. Dispatch before the eager `loadApp` - it must run on any
   // repo (API-only, not built, or mid-upgrade with edits that don't yet typecheck under dry-run).