@nifrajs/cli 2.10.0 → 2.12.0

package/dist/cli.js

@@ -11,7 +11,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * `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
  *
@@ -20,19 +20,22 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { inProcessClient } from "@nifrajs/client";
-import { createWebApp, DEFAULT_DEV_PORT } from "@nifrajs/web";
+import { createWebApp, DEFAULT_DEV_PORT, } from "@nifrajs/web";
 import { discoverRoutes } from "@nifrajs/web/fs";
 import { describeProject, describeRouteGraph, describeRoutes } from "./introspect.js";
 import { loadApp } from "./load.js";
-import { chooseBuildPipeline } from "./pipeline-guard.js";
+import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.js";
 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
@@ -67,8 +70,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
@@ -81,6 +87,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).
@@ -96,9 +104,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.
@@ -115,9 +128,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.
@@ -138,10 +157,11 @@ routes/ from the current directory. Run from your project root.
 Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with \`--port <n>\` (alias \`-p\`) or the
 \`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) => v;
 const asBunPlugins = (v) => v;
+const asUse = (v) => v;
 const apiOf = (backend) => backend === undefined ? {} : { api: inProcessClient(backend) };
 /**
  * Render an error for the CLI, unwrapping the detail a bare `.message` drops.
@@ -174,52 +194,22 @@ export function formatCliError(err) {
         return err.message;
     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) {
-    // 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 = [];
-    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, flags) {
-    // `--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
@@ -237,13 +227,34 @@ async function dev(app, flags) {
                     "relaunches. Something is rewriting `.nifra/dev-bun/` or the environment between " +
                     "launches; refusing to serve without the client-boundary plugins.");
             }
-            const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd);
-            const child = Bun.spawn([process.execPath, `--config=${bunfigPath}`, ...process.argv.slice(1)], {
+            const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd, app.configPath);
+            const child = Bun.spawn([
+                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",
                 },
             });
             const forward = () => child.kill("SIGINT");
@@ -251,6 +262,28 @@ async function dev(app, flags) {
             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({
@@ -258,8 +291,10 @@ async function dev(app, flags) {
             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 } : {}),
@@ -268,13 +303,15 @@ async function dev(app, flags) {
                 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 {
@@ -294,6 +331,18 @@ async function dev(app, flags) {
     // 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,
@@ -312,10 +361,12 @@ async function dev(app, flags) {
             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)}`);
 }
 /**
  * `nifra build --target <t>` - package the engine (buildClient + buildServer + prerender) into one
@@ -324,6 +375,32 @@ async function dev(app, flags) {
  * `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, configPath, frameworkFile) {
+    if (use === undefined || configPath === frameworkFile)
+        return;
+    const mod = (await import(__rewriteRelativeImportExtension(frameworkFile)).catch(() => ({})));
+    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, target, flags) {
     const { isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import("@nifrajs/web/build");
     if (!isBuildTarget(target)) {
@@ -352,6 +429,7 @@ async function buildForTarget(app, target, flags) {
             ? 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.
@@ -370,6 +448,7 @@ async function buildForTarget(app, target, flags) {
         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 } : {}),
@@ -379,11 +458,10 @@ async function buildForTarget(app, target, flags) {
         // 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)}`);
 }
@@ -402,6 +480,7 @@ async function buildPrerenderApp(app) {
         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 } : {}),
@@ -471,7 +550,10 @@ async function main() {
     // 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.js");
-        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
@@ -501,11 +583,36 @@ async function main() {
         const { runCheck } = await import("./check.js");
         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.js");
+            const { applyDiagnosticRecipe } = await import("./fix-recipes.js");
+            const result = await collectCheckResult(process.cwd(), { lintsOnly: true });
+            const changed = [];
+            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.
@@ -538,9 +645,18 @@ async function main() {
     // so it runs on an API-only / not-yet-built project.
     if (command === "doctor") {
         const { runDoctor } = await import("./doctor.js");
+        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;
         return;
@@ -618,6 +734,15 @@ async function main() {
         try {
             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 } : {}),
             })))
                 process.exitCode = 1;
@@ -628,6 +753,57 @@ async function main() {
         }
         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.js");
+            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.js");
+            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) => {
@@ -740,6 +916,45 @@ async function main() {
         }
         return;
     }
+    if (command === "prove") {
+        const valueAfter = (flag) => {
+            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 = [];
+            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.js");
+            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).