@nifrajs/cli 3.3.0 → 4.0.0

package/dist/cli.js

@@ -8,8 +8,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 /**
- * `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` - the zero-config CLI for a nifra app. Reads `backend/framework.ts` + `backend/app.ts` +
+ * `routes/` from the project root (see {@link loadApp}) and wires the right `@nifrajs/web`
+ * entrypoint:
  *
  *   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
@@ -20,21 +21,24 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { inProcessClient } from "@nifrajs/client";
 import { createWebApp, DEFAULT_DEV_PORT, } from "@nifrajs/web";
 import { discoverRoutes } from "@nifrajs/web/fs";
+import { formatShadowedPages, shadowedPages } from "@nifrajs/web/route-manifest";
+import { adapterFile, BACKEND_APP_FILE } from "./app-files.js";
 import { bindCommandArgv, findCommandSpec, renderCommandCatalogHelp } from "./command-catalog.js";
-import { applyEnvFiles, takeEnvFileFlags } from "./env-file.js";
-import { loadApp } from "./load.js";
+import { applyEnvFiles, forgetAutoLoadedEnv, takeEnvFileFlags } from "./env-file.js";
+import { FRAMEWORK_WEB_OPTIONS, loadApp } from "./load.js";
 import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.js";
+import { frameworkMountPaths, frameworkOptionImports, frameworkWebAppOptions, } from "./web-app-options.js";
 /** Forward a re-exec'd Bun child's output without relying on Windows inheriting a pipe-of-a-pipe. */
-async function forwardChildOutput(stream, sink) {
+async function forwardChildOutput(stream, sink, observe) {
     const reader = stream.getReader();
     try {
         for (;;) {
             const { done, value } = await reader.read();
             if (done)
                 return;
+            observe?.(value);
             await sink.write(value);
         }
     }
@@ -42,6 +46,30 @@ async function forwardChildOutput(stream, sink) {
         reader.releaseLock();
     }
 }
+/** The last `max` bytes of a stream, decoded: what a crashed child printed last. */
+function streamTail(max) {
+    let chunks = [];
+    let size = 0;
+    return {
+        push(chunk) {
+            chunks.push(chunk);
+            size += chunk.length;
+            while (size - (chunks[0]?.length ?? 0) >= max && chunks.length > 1) {
+                size -= chunks.shift()?.length ?? 0;
+            }
+        },
+        text() {
+            const all = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                all.set(chunk, offset);
+                offset += chunk.length;
+            }
+            chunks = [all];
+            return new TextDecoder().decode(all.subarray(Math.max(0, size - max)));
+        },
+    };
+}
 const HELP = `nifra - zero-config dev/build/start for a nifra app
 
 Usage:
@@ -57,14 +85,33 @@ Usage:
                                          loud warning instead of a hard failure, so a duplicate React/
                                          adapter copy from a linked sibling repo doesn't take dev down
                                          while you fix the resolution. Dev only - \`nifra build\` still fails.
+                [--no-indicator]         No in-page issues badge. Browser errors still reach
+                                         \`nifra errors\` and the agent tools.
+  nifra errors  [--since <n>] [--category <c>] [--request <id>]  What the running dev server caught:
+                                         SSR/loader/API/build/browser/hydration errors, each a structured
+                                         diagnostic. Finds the server itself; reads the log a crashed
+                                         one left. Exits 1 while current-code errors are open.
+  nifra logs    [--since <n>] [--level <l>] [--grep <s>]  The dev server's console, server and
+                                         browser, each line tagged with its request.
+  nifra cdn-check <url>                  Check a deployed page behind a CDN: served from cache, no
+                                         internal or CDN-only headers reaching the visitor, and soft
+                                         navigations get page data, not the cached document. Exits 1
+                                         on a failure.
+  nifra db schema [<table>]              The development database declared as \`devDatabase\` in
+                                         nifra.config.ts: tables, columns, keys, indexes.
+  nifra db query "<sql>" [--explain [--analyze]]  One read-only SELECT (or its plan), in a fresh
+                                         process killed at devDatabase.timeoutMs. Rows capped, secrets
+                                         masked. Postgres: a superuser connection is refused.
+  nifra db role                          Print the SQL for a read-only Postgres role. Runs nothing.
+  nifra db audit [--limit <n>]           What nifra db ran (.nifra/db-audit.jsonl), never the rows.
   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
+                                         bun | node | deno | cloudflare | vercel | static. Packages
                                          buildClient + buildServer (+ prerender for static) so an app
                                          no longer hand-writes build-<target>.ts + _worker.ts +
                                          _routes.json. The server entry is generated from your
-                                         framework.ts (adapter) + backend.ts + routes/. --report prints
-                                         a per-chunk size + gzip table (biggest first).
+                                         backend/framework.ts (adapter) + backend/app.ts + routes/.
+                                         --report prints a per-chunk size + gzip table (biggest first).
                 [--vite | --bun]         Force the bundler. Without a flag it follows your config: Bun
                                          (faster, Bun-native) unless your ONLY transforms are
                                          \`vitePlugins\`, which the Bun build cannot run - then Vite,
@@ -85,12 +132,20 @@ Usage:
                                          against it: a route the target can't honour (an ssr route on a
                                          static build, ISR where there's no revalidation) exits nonzero
                                          with the consequence - run in CI so it fails the build, not prod.
-  nifra init-agents [--force] [--json]   Retrofit an EXISTING app with the agent-discovery files a new
-                                         app ships: .mcp.json + .cursor/mcp.json (register this project's
-                                         nifra MCP), CLAUDE.md (MCP-first preamble + @AGENTS.md import),
-                                         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 init-agents [--force] [--json]   Retrofit an EXISTING app with the agent files a new app ships:
+                                         .mcp.json + .cursor/mcp.json (register this project's nifra MCP),
+                                         each agent's pointer to AGENTS.md (CLAUDE.md, GEMINI.md,
+                                         .cursor/rules/nifra.mdc, .github/copilot-instructions.md), and
+                                         AGENTS.md's "## MCP server" and (with routes/) "## Project
+                                         structure" sections. No-clobber by default (skips a file you've
+                                         customized); --force overwrites the owned files. AGENTS.md is
+                                         only appended to, never overwritten.
+  nifra init-agents --sync-mcp [--json]  Re-pin an existing app's MCP launch to the nifra the project
+                                         installs: rewrites only the @nifrajs/cli@x.y.z version in
+                                         .mcp.json, .cursor/mcp.json, CLAUDE.md and AGENTS.md's MCP
+                                         section - every other byte stays as it is. Creates nothing.
+                                         At a workspace root with one nifra member, the two registries'
+                                         launch also names that member (\`mcp app\`).
   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
@@ -99,15 +154,20 @@ Usage:
                                          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
-                                         ladder), nifra_doctor (deps), nifra_explain (structured errors),
-                                         nifra_inspect (request traces), nifra_learn (guided build path).
+                                         ladder), nifra_doctor (deps), nifra_errors + nifra_logs (what
+                                         the running dev server saw), nifra_db_schema + nifra_db_query +
+                                         nifra_db_role (the declared dev database, read-only),
+                                         nifra_explain (structured errors), nifra_inspect (request
+                                         traces), nifra_learn (guided build path).
   nifra docs-mcp [--port <n>]            Serve the PUBLIC docs MCP over HTTP (nifra_docs + nifra_example) -
                                          self-host on a VPS so any remote agent can learn nifra. Default :8787.
   nifra learn   [<step>]                 Print the guided build-an-app path (the human view of nifra_learn):
                                          no arg for the step index, a number for one step's goal/do/verify.
-  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 check   [--json] [--sarif] [--lints-only]
+                                         Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
+                                         backend code in browser code). Run as "done"; --json for agents;
+                                         --sarif emits the same stable diagnostics as SARIF 2.1.0 for external
+                                         review tools; --lints-only skips tsc for a near-instant inner-loop pass.
   nifra verify   [--release] [--json]    Run the shared repository verification gate. --release runs the
                                          full build, test, coverage, corpus, consumer, and cross-runtime gate.
   nifra fix     [--code <NF-code>]       Apply a registered diagnostic recipe, then print the remaining
@@ -125,8 +185,8 @@ Usage:
                                          request field or a removed response field breaks; widening a
                                          request enum or adding a response field doesn't) and fails
                                          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 sdk     --lang <python|go> [--out <file>] [--strict]
+                                         Generate a deterministic non-TypeScript SDK from backend/app.ts.
   nifra assure  [--config <file>] [--json]  Route-assurance report. Human table by default; --json emits
                                          the {ok, routes, findings} report for agents.
   nifra assure  --bundle [--json] [--strict] [--out <file>] [--hydration] [--interact]
@@ -164,22 +224,40 @@ Usage:
                                          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.
+  nifra upgrade <version>                Upgrade to <version>, running every release recipe between the
+                [--write] [--no-verify]  installed version and it, oldest first: move removed packages,
+                [--list] [--json]        apply exact imports, pin every matching dependency (keeping
+                [--exact]                ^/~, or exact with --exact), then verify with nifra check.
                 [--allow-downgrade]      Dry-run by default; --write applies then verifies (--no-verify
-                                         to skip). --list shows available targets. Fail-closed on an
-                                         unknown version or a rollback (--allow-downgrade overrides).
-                                         Deterministic + idempotent.
+                                         to skip). --list shows available targets. A version newer than
+                                         this CLI prints the command for that release's CLI. Fail-closed
+                                         on an unknown version or a rollback (--allow-downgrade
+                                         overrides). Deterministic + idempotent.
+  nifra migrate layout [--write] [--json]
+                                         Move an app onto the frontend/backend split: split each route
+                                         into x.tsx + x.backend.ts, fold _middleware.ts into
+                                         _layout.backend.ts, move backend.ts/framework.ts under backend/,
+                                         and zone the other modules into frontend/, backend/ or shared/.
+                                         Dry-run by default; --write applies.
+  nifra types   [--check] [--json]       Generate each route's ./+types module under .nifra/types: its
+                                         params, the data its output schemas let through, and api typed
+                                         by backend/app.ts. dev, build and check refresh them too;
+                                         --check fails when one is stale.
   nifra port    [--target <t>] [--json]  Portability linter: print a feature × deploy-target capability
                 [--ci] [--strict]        matrix (in-memory stores, in-process cron/WebSocket, Bun/Deno
                                          globals, node: builtins) with file:line evidence. --target auto-
                                          detected from build/deploy scripts, wrangler.toml, or vercel config;
                                          --ci (or any --target) exits nonzero when a used feature is
                                          unsupported on the target; --strict also fails on caveats.
+  nifra i18n check [entry]               Check i18n catalogs: coverage, missing + unused keys, ICU syntax,
+                [--json] [--strict]      placeholder + tag parity, plural cases, script purity,
+                                         untranslated messages. IMPORTS the entry (default: the first
+                                         i18n.ts in ., lib/, src/, src/lib/, app/), which exports
+                                         \`locales\` + \`catalogs\` (+ optional \`ignore\`). Exits 1 on
+                                         errors; --strict also on warnings.
 
-Reads nifra.config.ts (adapter + clientModule + plugins; or framework.ts), backend.ts (optional), and
-routes/ from the current directory. Run from your project root.
+Reads nifra.config.ts (adapter + clientModule + plugins; or backend/framework.ts), backend/app.ts
+(optional), and 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).
@@ -192,12 +270,10 @@ set in the process environment is never overwritten by a file.
 
 ${renderCommandCatalogHelp()}`;
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "3.3.0";
+const CLI_VERSION = "4.0.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.
  *
@@ -246,7 +322,7 @@ async function dev(app, flags) {
     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
+        // start - so the boundary plugins (zone guard, server-fn stubs) are delivered by
         // generating a config and re-execing this same command once with `--config=`. The child proves
         // it IS the configured child with a per-launch random token (matched against the file the
         // parent just wrote, consumed on first read). A fixed sentinel here would be a secret-leak
@@ -262,7 +338,7 @@ 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, app.configPath);
+            const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd, app.configPath, app.framework.define);
             // Bun 1.4 on Windows may discard the script-relative portion of argv when `--config` is
             // present. Keep a second, authenticated copy of the user vector in the child's environment so
             // the configured process cannot silently fall back to `nifra`'s help and exit 0. The launch token
@@ -310,16 +386,31 @@ async function dev(app, flags) {
                     NODE_ENV: process.env.NODE_ENV ?? "development",
                 },
             });
+            // The child's last words, kept so a crash leaves a record `nifra errors` can read after the fact.
+            const stderrTail = streamTail(16 * 1024);
             const forwarded = Promise.all([
                 forwardChildOutput(child.stdout, Bun.stdout),
-                forwardChildOutput(child.stderr, Bun.stderr),
+                forwardChildOutput(child.stderr, Bun.stderr, stderrTail.push),
             ]);
-            const forward = () => child.kill("SIGINT");
+            let interrupted = false;
+            const forward = () => {
+                interrupted = true;
+                child.kill("SIGINT");
+            };
             process.on("SIGINT", forward);
             process.on("SIGTERM", forward);
             try {
                 const [code] = await Promise.all([child.exited, forwarded]);
                 process.exitCode = code;
+                if (code !== 0 && !interrupted) {
+                    try {
+                        const { recordDevCrash } = await import("@nifrajs/web/dev-feed");
+                        recordDevCrash(app.cwd, code, stderrTail.text());
+                    }
+                    catch {
+                        // The crash is already on the terminal; failing to persist it must not mask the exit code.
+                    }
+                }
             }
             finally {
                 process.off("SIGINT", forward);
@@ -370,12 +461,13 @@ async function dev(app, flags) {
             ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
             ...(fw.conditions ? { conditions: fw.conditions } : {}),
             ...(fw.define ? { define: fw.define } : {}),
-            createApp: (clientEntry, importQuery) => createWebApp({
+            indicator: showsIndicator(flags, fw),
+            createApp: (clientEntry, importQuery, dev) => createWebApp({
                 adapter: asAdapter(fw.adapter),
                 manifest: discoverRoutes(routesDir, { importQuery }),
                 clientEntry,
-                ...(fw.use ? { use: asUse(fw.use) } : {}),
-                ...apiOf(backend),
+                ...frameworkWebAppOptions(fw, backend),
+                onLoaderError: dev.onLoaderError,
             }),
         });
         console.log(`nifra dev (bun) → http://localhost:${server.port}`);
@@ -424,17 +516,18 @@ async function dev(app, flags) {
         poll: flags.poll,
         port: flags.port,
         ...(flags.allowDuplicateIdentity ? { allowDuplicateIdentity: true } : {}),
+        indicator: showsIndicator(flags, fw),
         ...(fw.conditions ? { conditions: fw.conditions } : {}),
         ...(fw.define ? { define: fw.define } : {}),
         // `load` resolves route modules through VITE, not through Bun. That is what makes the Vite
         // pipeline own the whole phase: the client and the server now agree on every specifier, so
         // `resolve.dedupe` finally governs SSR and the dual-React crash cannot occur.
-        createApp: (clientEntry, load) => createWebApp({
+        createApp: (clientEntry, load, dev) => createWebApp({
             adapter: asAdapter(fw.adapter),
             manifest: discoverRoutes(routesDir, { load }),
             clientEntry,
-            ...(fw.use ? { use: asUse(fw.use) } : {}),
-            ...apiOf(backend),
+            ...frameworkWebAppOptions(fw, backend),
+            onLoaderError: dev.onLoaderError,
         }),
     });
     console.log(`nifra dev (vite) → http://localhost:${server.port}`);
@@ -443,23 +536,26 @@ async function dev(app, flags) {
 /**
  * `nifra build --target <t>` - package the engine (buildClient + buildServer + prerender) into one
  * command that emits a full deploy dir, so an app no longer hand-writes build-bun.ts + _worker.ts +
- * _routes.json per target. The adapter is imported from `framework.ts` (the edge-bundlable file - never
- * `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/`.
+ * _routes.json per target. The adapter is imported from `backend/framework.ts` (the edge-bundlable
+ * file - never `nifra.config.ts`, which pulls in Vite plugins), and the backend from
+ * `backend/app.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).
+ * `nifra build` emits `import { use } from <frameworkFile>` (backend/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 `backend/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.
+ * Detected by importing `frameworkFile` and checking the named export, not by comparing paths
+ * alone: a split app legitimately DEFINES `use` in backend/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 - backend/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)
@@ -468,10 +564,55 @@ export async function assertUseIsEdgeExported(use, configPath, frameworkFile) {
     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.');
+        "`nifra build` generates a server entry that imports `use` from backend/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 backend/framework.ts and re-export it from nifra.config.ts " +
+        '(`export { use } from "./backend/framework.ts"`) so `nifra dev` sees it too.');
+}
+/**
+ * Refuse a forwarded framework field (`apiPrefix`, `mounts`, `csp`, ...) the generated server entry
+ * would not see, or would see with a different value.
+ *
+ * `nifra dev` reads these from the loaded config (`nifra.config.ts` when it exists) while the
+ * server entry imports them from backend/framework.ts. A field set only in nifra.config.ts would be
+ * missing from production, and one defined separately in each file could differ - dev mounting the
+ * backend at one path while production mounts it at another. Identity is required, which a
+ * re-export satisfies.
+ */
+export async function assertFrameworkOptionsEdgeExported(fw, configPath, frameworkFile) {
+    if (configPath === frameworkFile)
+        return;
+    const set = FRAMEWORK_WEB_OPTIONS.filter((name) => fw[name] !== undefined);
+    if (set.length === 0)
+        return;
+    const mod = (await import(__rewriteRelativeImportExtension(frameworkFile)).catch(() => ({})));
+    const drifted = set.filter((name) => mod[name] !== fw[name]);
+    if (drifted.length === 0)
+        return;
+    const names = drifted.map((name) => `\`${name}\``).join(", ");
+    throw new Error(`[nifra] ${names} ${drifted.length === 1 ? "is" : "are"} exported from ${configPath} but not, or not as the same value, from ${frameworkFile}. ` +
+        "`nifra build` generates a server entry that imports these from backend/framework.ts, so production " +
+        "would serve a different app than `nifra dev`.\n\n" +
+        `  - Define ${drifted.length === 1 ? "it" : "them"} in backend/framework.ts and re-export from nifra.config.ts ` +
+        `(\`export { ${drifted.join(", ")} } from "./backend/framework.ts"\`).`);
+}
+/**
+ * Refuse a build whose page routes sit under a mount: each would ship as a route that can never render.
+ * Read from the config and `routes/` alone; the server also checks its own mount table at startup,
+ * which covers a mount added inside `use`.
+ */
+/** `nifra dev` shows the in-page issues badge unless `--no-indicator` or `dev.indicator: false` turns it off. */
+export function showsIndicator(flags, fw) {
+    return !flags.noIndicator && fw.dev?.indicator !== false;
+}
+export function assertNoShadowedPages(app) {
+    const paths = frameworkMountPaths(app.framework, app.backend !== undefined);
+    if (paths.length === 0)
+        return;
+    const shadowed = shadowedPages(discoverRoutes(app.routesDir), paths);
+    if (shadowed.length === 0)
+        return;
+    throw new Error(`[nifra] build blocked: ${formatShadowedPages(shadowed)}`);
 }
 /**
  * A production build must not ship a workspace-linked package whose `default`-condition artifact is
@@ -503,35 +644,55 @@ async function assertFreshWorkspaceDists(cwd) {
         : `  ${f.package}: ${f.distFile} is ${f.behindSeconds}s behind ${f.sourceFile}`);
     throw new Error(`[nifra] build blocked: ${stale.length} workspace-linked package(s) ship a stale or missing dist artifact, so the deployed app would serve code this build did not produce:\n${lines.join("\n")}\nBuild the offending package(s) (\`bun run build\` in each) so every export target exists and is at least as new as its source, then rebuild.`);
 }
-async function buildForTarget(app, target, flags) {
-    const { isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import("@nifrajs/web/build");
-    if (!isBuildTarget(target)) {
-        throw new Error(`[nifra] unknown --target "${target}". Valid: ${BUILD_TARGETS.join(", ")}.`);
-    }
+async function buildForTarget(app, flag, flags) {
+    const { parseBuildTarget, renderSizeReport } = await import("@nifrajs/web/build");
+    const target = parseBuildTarget(flag ?? app.framework.target ?? "bun", flag === undefined ? "target in nifra.config.ts" : "--target");
     if (flags.vite && flags.bun) {
         throw new Error("[nifra] `nifra build` takes `--vite` or `--bun`, not both.");
     }
+    const { framework: fw } = app;
+    const cssCodeSplitRequested = fw.cssCodeSplit === false;
+    const hasBunTransforms = app.resolvedPlugins.clientPlugins.length > 0 || app.resolvedPlugins.serverPlugins.length > 0;
+    if (cssCodeSplitRequested && flags.bun) {
+        throw new Error("[nifra] `cssCodeSplit: false` is a Vite-only production option, but `nifra build --bun` was requested. " +
+            "Drop `--bun` (Nifra will select Vite automatically) or remove the aggregate CSS setting.");
+    }
+    if (cssCodeSplitRequested && hasBunTransforms) {
+        throw new Error("[nifra] `cssCodeSplit: false` requires the Vite production pipeline, but this app also declares " +
+            "Bun client/server plugins. Use `--vite` with Vite equivalents, or remove the aggregate CSS setting; " +
+            "switching pipelines would silently drop the Bun transforms.");
+    }
     // Which bundler builds this app. Default is Bun; an app whose ONLY transforms are `vitePlugins` gets
     // Vite instead, because the Bun build cannot run them and would silently omit the work. `--vite`/`--bun`
     // force it, and the one forced combination that would drop transforms throws.
-    const decision = chooseBuildPipeline(app.resolvedPlugins, flags.vite ? "vite" : flags.bun ? "bun" : undefined);
+    let decision = chooseBuildPipeline(app.resolvedPlugins, flags.vite ? "vite" : flags.bun ? "bun" : undefined);
+    if (cssCodeSplitRequested && decision.pipeline === "bun") {
+        // With no Bun transforms, aggregate CSS is a Vite-only request that can be honored safely by
+        // selecting the same pipeline the user would otherwise have to force explicitly.
+        decision = {
+            pipeline: "vite",
+            why: "auto",
+            reason: "auto: this app requested Vite's aggregate CSS output (`cssCodeSplit: false`)",
+        };
+    }
     const useVite = decision.pipeline === "vite";
     // Same deploy-dir output - buildTargetVite delegates to the same orchestrator as buildTarget - so only
     // the bundler and the plugin FORMAT (Vite plugins, not Bun) differ.
     const buildTarget = useVite
         ? (await import("@nifrajs/web/build-vite")).buildTargetVite
         : (await import("@nifrajs/web/build")).buildTarget;
-    const { framework: fw, routesDir, outDir, cwd, backend } = app;
-    // The server entry must import the adapter from `framework.ts` (edge-safe), not the loaded config.
-    // `loadApp` guarantees one of them exists; prefer framework.ts so a multi-target app's Vite-plugin
-    // config never reaches the edge bundle (see load.ts module header).
-    const frameworkFile = existsSync(resolve(cwd, "framework.ts"))
-        ? resolve(cwd, "framework.ts")
-        : existsSync(resolve(cwd, "nifra.config.ts"))
-            ? resolve(cwd, "nifra.config.ts")
-            : resolve(cwd, "framework.ts");
-    const backendFile = resolve(cwd, "backend.ts");
+    const { routesDir, cwd, backend } = app;
+    // `vercel deploy --prebuilt` uploads `.vercel/output` from the project root, so that is where a
+    // Vercel build goes unless `--out` says otherwise.
+    const outDir = target === "vercel" && flags.out === undefined ? resolve(cwd, ".vercel/output") : app.outDir;
+    // The server entry must import the adapter from `backend/framework.ts` (edge-safe), not the
+    // loaded config, so a multi-target app's Vite-plugin config never reaches the edge bundle
+    // (load.ts header).
+    const frameworkFile = adapterFile(cwd);
+    const backendFile = resolve(cwd, BACKEND_APP_FILE);
     await assertUseIsEdgeExported(fw.use, app.configPath, frameworkFile);
+    await assertFrameworkOptionsEdgeExported(fw, app.configPath, frameworkFile);
+    assertNoShadowedPages(app);
     // 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.
@@ -551,12 +712,17 @@ async function buildForTarget(app, target, flags) {
         clientModule: fw.clientModule,
         adapterImport: frameworkFile,
         ...(fw.use ? { useImport: frameworkFile } : {}),
+        ...frameworkOptionImports(fw, frameworkFile),
         ...(backend !== undefined && existsSync(backendFile) ? { backendImport: backendFile } : {}),
         ...plugins,
         ...(fw.conditions ? { conditions: fw.conditions } : {}),
         ...(fw.define ? { define: fw.define } : {}),
         ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
         ...(fw.publicEnvPrefix !== undefined ? { publicEnvPrefix: fw.publicEnvPrefix } : {}),
+        ...(fw.secretExemptions !== undefined ? { secretExemptions: fw.secretExemptions } : {}),
+        ...(fw.cssCodeSplit !== undefined ? { cssCodeSplit: fw.cssCodeSplit } : {}),
+        ...(fw.cssLoading !== undefined ? { cssLoading: fw.cssLoading } : {}),
+        ...(fw.clientIp !== undefined ? { clientIp: fw.clientIp } : {}),
         // The static target needs a built app to drive prerendering - only build it when targeting static.
         ...(target === "static" ? { prerenderApp: await buildPrerenderApp(app) } : {}),
     });
@@ -587,18 +753,18 @@ async function buildPrerenderApp(app) {
         adapter: asAdapter(fw.adapter),
         manifest: discoverRoutes(routesDir),
         clientEntry: client.entry,
-        ...(fw.use ? { use: asUse(fw.use) } : {}),
+        ...frameworkWebAppOptions(fw, backend),
         ...(client.routes ? { routePreload: client.routes } : {}),
         ...(client.css ? { styles: client.css } : {}),
         ...(client.routeStyles ? { routeStyles: client.routeStyles } : {}),
-        ...apiOf(backend),
+        ...(client.cssLoading !== undefined ? { cssLoading: client.cssLoading } : {}),
     });
 }
 async function start(app, flags) {
     const serverFile = resolve(app.outDir, "server.js");
     if (!existsSync(serverFile)) {
         // A Cloudflare Pages build emits `_worker.js` (a Workers bundle), not a self-hosting `server.js` - so
-        // `nifra start` on a dir built for cf-pages would otherwise fail with a bare "no server.js". Name the
+        // `nifra start` on a dir built for cloudflare would otherwise fail with a bare "no server.js". Name the
         // actual mismatch and the fix.
         if (existsSync(resolve(app.outDir, "_worker.js"))) {
             throw new Error(`[nifra] ${app.outDir} holds a Cloudflare Pages worker bundle (_worker.js), not a self-hosting ` +
@@ -614,13 +780,14 @@ export function parseFlags(args) {
     // the SAME uncommon port for `nifra dev` and `nifra start` (DEFAULT_DEV_PORT) so a project's URL is
     // stable across commands and doesn't collide with the usual 3000/5173/8080 crowd.
     let port = Number(Bun.env.PORT ?? DEFAULT_DEV_PORT);
-    let out = "dist";
+    let out;
     let poll = Bun.env.CHOKIDAR_USEPOLLING === "1";
-    let target = "bun";
+    let target;
     let report = false;
     let vite = false;
     let bun = false;
     let allowDuplicateIdentity = false;
+    let noIndicator = false;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if ((a === "--port" || a === "-p") && args[i + 1])
@@ -639,11 +806,13 @@ export function parseFlags(args) {
             bun = true;
         else if (a === "--allow-duplicate-identity")
             allowDuplicateIdentity = true;
+        else if (a === "--no-indicator")
+            noIndicator = true;
     }
     if (!Number.isFinite(port) || port < 0 || port > 65535) {
         throw new Error(`[nifra] invalid --port: ${port}`);
     }
-    return { port, out, poll, target, report, vite, bun, allowDuplicateIdentity };
+    return { port, out, poll, target, report, vite, bun, allowDuplicateIdentity, noIndicator };
 }
 /**
  * `assure` uses the structured-bundle lane only when explicitly asked. A bare `--json` is NOT a
@@ -678,8 +847,15 @@ function installReflectionExitHint() {
         inFlight = command;
     };
 }
+/** Set on the copy of `nifra mcp` that serves without `.env` files, so it does not restart again. */
+const MCP_WITHOUT_ENV_FILES = "NIFRA_MCP_WITHOUT_ENV_FILES";
 async function main() {
     const { argv: rawArgv, files: envFiles } = takeEnvFileFlags(cliArgv());
+    // `nifra mcp` keeps none of the `.env` values Bun loaded at startup. Decided before the
+    // `--env-file`s below, which the caller names explicitly and which stay.
+    const forgotten = rawArgv[0] === "mcp" && process.env[MCP_WITHOUT_ENV_FILES] !== "1"
+        ? await forgetAutoLoadedEnv()
+        : [];
     // Applied before any command runs: a reflecting command imports the app on its first await, and the
     // app reads its environment at module scope, so the variables must already be in place by then.
     if (envFiles.length > 0)
@@ -701,6 +877,16 @@ async function main() {
     // `mcp` runs a long-lived stdio server and loads the project lazily per-tool - it must not go through
     // the eager `loadApp` below (which would fail fast on a project that's API-only / not yet built).
     if (command === "mcp") {
+        // Bun passes what it loaded to every subprocess whatever `process.env` says now, so the session
+        // moves to a copy of this process that never loads `.env` files.
+        if (forgotten.length > 0) {
+            const { handOffSession } = await import("./mcp-delegate.js");
+            const exitCode = await handOffSession([process.execPath, "--no-env-file", ...process.argv.slice(1)], { cwd: process.cwd(), env: { ...process.env, [MCP_WITHOUT_ENV_FILES]: "1" } });
+            if (exitCode !== undefined) {
+                process.exitCode = exitCode;
+                return;
+            }
+        }
         const { runMcpServer } = await import("./mcp.js");
         // `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.
@@ -746,11 +932,16 @@ async function main() {
         }));
         return;
     }
-    const catalogSpec = command === undefined ? undefined : findCommandSpec(command);
+    // `nifra db <sub>` is the catalog's `db-<sub>` command, projected to MCP as `nifra_db_<sub>`.
+    const dbSub = command === "db" && argv[1] !== undefined && !argv[1].startsWith("-") ? argv[1] : undefined;
+    if (command === "db" && (dbSub === undefined || findCommandSpec(`db-${dbSub}`) === undefined)) {
+        throw new Error("[nifra] usage: nifra db schema|query|role|audit - see `nifra help`");
+    }
+    const catalogSpec = findCommandSpec(dbSub === undefined ? command : `db-${dbSub}`);
     if (catalogSpec?.transports.includes("cli")) {
         const markReflecting = installReflectionExitHint();
         try {
-            const input = bindCommandArgv(catalogSpec, argv.slice(1));
+            const input = bindCommandArgv(catalogSpec, argv.slice(dbSub === undefined ? 1 : 2));
             markReflecting(command);
             const output = await catalogSpec.run(input, { cwd: process.cwd(), cliVersion: CLI_VERSION });
             markReflecting(undefined);
@@ -763,15 +954,28 @@ async function main() {
             else {
                 console.log(catalogSpec.render(output, input).join("\n"));
             }
-            if (catalogSpec.success !== undefined && !catalogSpec.success(output, input))
+            if (catalogSpec.exitCode !== undefined) {
+                process.exitCode = catalogSpec.exitCode(output, input);
+            }
+            else if (catalogSpec.success !== undefined && !catalogSpec.success(output, input)) {
                 process.exitCode = 1;
+            }
         }
         catch (err) {
             // A thrown error is nifra's own reporting path, not a silent abort: clear the sentinel so the
             // hint stays reserved for the case where the process died inside the app import.
             markReflecting(undefined);
             console.error(formatCliError(err));
-            process.exitCode = 1;
+            const candidate = typeof err === "object" && err !== null && "exitCode" in err
+                ? err.exitCode
+                : undefined;
+            process.exitCode =
+                typeof candidate === "number" &&
+                    Number.isInteger(candidate) &&
+                    candidate >= 0 &&
+                    candidate <= 255
+                    ? candidate
+                    : 1;
         }
         return;
     }
@@ -785,7 +989,7 @@ async function main() {
             process.exitCode = 1;
         return;
     }
-    // `init-agents` retrofits the agent-discovery files (.mcp.json, CLAUDE.md, …) into the cwd. It's a
+    // `init-agents` retrofits the agent files (.mcp.json, CLAUDE.md, AGENTS.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.
     if (command === "init-agents") {
@@ -793,6 +997,7 @@ async function main() {
         await runInitAgents(process.cwd(), {
             json: argv.includes("--json"),
             force: argv.includes("--force"),
+            syncMcp: argv.includes("--sync-mcp"),
         });
         return;
     }
@@ -813,7 +1018,11 @@ async function main() {
         }
         try {
             const { runSdk } = await import("./sdk.js");
-            await runSdk(process.cwd(), { language, ...(out !== undefined ? { out } : {}) });
+            await runSdk(process.cwd(), {
+                language,
+                ...(out !== undefined ? { out } : {}),
+                ...(argv.includes("--strict") ? { strict: true } : {}),
+            });
         }
         catch (err) {
             console.error(formatCliError(err));
@@ -835,6 +1044,8 @@ async function main() {
                 list: argv.includes("--list"),
                 verify: !argv.includes("--no-verify"),
                 allowDowngrade: argv.includes("--allow-downgrade"),
+                exact: argv.includes("--exact"),
+                cliVersion: CLI_VERSION,
             });
             if (!ok)
                 process.exitCode = 1;
@@ -855,6 +1066,13 @@ async function main() {
     }
     const flags = parseFlags(argv.slice(1));
     const app = await loadApp(process.cwd(), flags.out);
+    if (command !== "start") {
+        const { refreshRouteTypes, watchRouteTypes } = await import("./route-types.js");
+        refreshRouteTypes(app.cwd);
+        // A relaunched `nifra dev --bun` child runs beside its parent, which already watches.
+        if (command === "dev" && process.env.NIFRA_BUN_DEV_TOKEN === undefined)
+            watchRouteTypes(app.cwd);
+    }
     if (command === "dev")
         await dev(app, flags);
     else if (command === "build")
@@ -946,6 +1164,7 @@ function isCliCommandToken(value) {
         value === "mcp" ||
         value === "init-agents" ||
         value === "upgrade" ||
+        value === "db" ||
         value === "help" ||
         value === "--help" ||
         value === "-h" ||