@nifrajs/cli 2.1.0 → 2.3.0

package/dist/cli.js

@@ -8,27 +8,32 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 /**
- * `nifra` — the zero-config CLI for a nifra app. Reads `framework.ts` + `backend.ts` + `routes/` from
+ * `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 build    emit a complete target-specific deploy directory        — @nifrajs/web/build
- *   nifra start    run the default Bun build                               — dist/server.js
+ *   nifra dev      true-HMR dev server (Vite middleware + nifra SSR)        - @nifrajs/web/vite
+ *   nifra build    emit a complete target-specific deploy directory        - @nifrajs/web/build
+ *   nifra start    run the default Bun build                               - dist/server.js
  *
  * Bun-only (it runs the framework's TS + Bun plugins directly). The *output* runs anywhere.
  */
 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, SERVER_FN_MODULE, SERVER_ONLY_MODULE, } from "@nifrajs/web";
 import { discoverRoutes } from "@nifrajs/web/fs";
 import { describeProject, describeRoutes } from "./introspect.js";
-import { loadApp, resolvePlugins } from "./load.js";
-const HELP = `nifra — zero-config dev/build/start for a nifra app
+import { loadApp } from "./load.js";
+import { chooseBuildPipeline } 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}.
-  nifra build   [--out <dir>] [--report]  Emit a complete Bun deploy directory by default.
+                [--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 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
                                          buildClient + buildServer (+ prerender for static) so an app
@@ -36,6 +41,11 @@ Usage:
                                          _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).
+                [--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,
+                                         and it says so. --bun is refused in exactly that case rather
+                                         than dropping the transforms silently.
   nifra start   [--port <n>] [--out <dir>]  Run the Bun build at <out>/server.js. Default port ${DEFAULT_DEV_PORT}.
   nifra context                          Print this project's route INDEX (API + page routes) + conventions
                                          for an AI agent's prompt. Per-route schemas: nifra mcp's
@@ -44,6 +54,11 @@ Usage:
                                          routes (routes/) + the in-process backend's API routes,
                                          marking which API routes are auto-mounted under apiPrefix.
                                          --json for agents (see POST /api/x is/isn't served, not via 405).
+  nifra routes --modes [--target <t>]    Show each page route's RENDER MODE (static | isr | ssr),
+                                         hydration, and cache policy in one table. With --target, gate
+                                         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),
@@ -56,7 +71,7 @@ Usage:
                                          nifra_example (verified snippets), nifra_scaffold (route→file),
                                          nifra_check (drift gate + fixes), nifra_levels (verification
                                          ladder), nifra_doctor (deps + duplicate installs).
-  nifra docs-mcp [--port <n>]            Serve the PUBLIC docs MCP over HTTP (nifra_docs + nifra_example) —
+  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 check   [--json] [--lints-only]  Gate: typecheck + lints (hand-rolled fetch(), untyped client("…"),
                                          server-only imports in routes/). Run as "done"; --json for agents;
@@ -64,13 +79,16 @@ Usage:
   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).
+  nifra sync-routes                      Regenerate nifra-routes.d.ts from routes/ so navigate({ to, search })
+                                         is typed against each static route's searchSchema (a stale shape is a
+                                         tsc error). Include the file in your tsconfig. Pure file write.
   nifra snapshot [--out <file>]          Write the backend's API contract (routes + schemas) as plain
-                                         JSON — the baseline for \`nifra diff\`. Default api-snapshot.json.
+                                         JSON - the baseline for \`nifra diff\`. Default api-snapshot.json.
   nifra diff    [<baseline>] [--json]    Breaking-change gate: re-snapshot the contract and compare
                                          against the committed baseline. Direction-aware (a new required
                                          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.
+                                         closed. Exits non-zero on any breaking change - run it in CI.
   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.
@@ -103,7 +121,7 @@ Usage:
                 [--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 non-zero when a used feature is
+                                         --ci (or any --target) exits nonzero when a used feature is
                                          unsupported on the target; --strict also fails on caveats.
 
 Reads nifra.config.ts (adapter + clientModule + plugins; or framework.ts), backend.ts (optional), and
@@ -112,12 +130,155 @@ 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.1.0";
+const CLI_VERSION = "2.3.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 apiOf = (backend) => backend === undefined ? {} : { api: inProcessClient(backend) };
+/**
+ * Render an error for the CLI, unwrapping the detail a bare `.message` drops.
+ *
+ * `Bun.build` reports a bundling failure as an `AggregateError` whose `.message` is a generic
+ * "Bundle failed" and whose `.errors` hold the real causes - the unresolved import, the plugin that
+ * threw, each with a file and line. `buildClient`/`buildServer` catch a RETURNED `{ success: false }`
+ * and print `result.logs`, but a `Bun.build` that THROWS (a plugin `onLoad`/`onResolve` that throws, a
+ * resolution failure) rejects before that check runs, so the AggregateError reaches the CLI whole and a
+ * catch printing only `.message` throws the causes away. That is the difference between "Bundle failed"
+ * and "Could not resolve ./db from routes/x.tsx". So unwrap an AggregateError - directly, or one carried
+ * as a `.cause` - into a line per underlying error.
+ */
+export function formatCliError(err) {
+    const aggregate = err instanceof AggregateError
+        ? err
+        : err instanceof Error && err.cause instanceof AggregateError
+            ? err.cause
+            : undefined;
+    if (aggregate !== undefined && aggregate.errors.length > 0) {
+        const outer = err instanceof Error ? err.message : "";
+        const head = outer !== "" && outer !== "Bundle failed" ? outer : "build failed";
+        // `String(e)` (not `e.message`) so a Bun BuildMessage/ResolveMessage renders with its file + line,
+        // not just the bare text. Multi-line entries are indented to stay under the head. Deduplicated
+        // because Bun can repeat one cause across `.errors`.
+        const details = [...new Set(aggregate.errors.map((e) => String(e).trim()))].map((line) => `  - ${line.replace(/\n/g, "\n    ")}`);
+        return [head, ...details].join("\n");
+    }
+    if (err instanceof Error)
+        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) {
+    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;
+    }
+    // Server functions are the same trade with a worse consequence. The client build replaces a `*.fn`
+    // module with stubs so its body never reaches a browser; Bun's dev-server bundler takes no plugins, so
+    // there it would be bundled WHOLE - the function bodies and every secret they import. Measured, not
+    // assumed: a runtime `Bun.plugin` onLoad does not reach `HTMLBundle`, so the module ships raw.
+    //
+    // `*.server` modules are the same trade again: the client build EMPTIES them, and with no plugins
+    // here they ship whole.
+    //
+    // Both are matched with the SAME regexes the transforms use, imported rather than re-encoded. A
+    // hand-written glob here is how these two gates drifted from the pipelines they guard: the old
+    // `**/*.fn.{ts,tsx,js,jsx}` missed `.fn.mts`, `.fn.cts`, `.fn.mjs` and `.fn.cjs`, every one of which
+    // both build pipelines stub - so a module the framework calls a server function was waved straight
+    // into the browser by the check that exists to stop exactly that. A gate written in a second dialect
+    // is a gate that eventually disagrees with the thing it guards.
+    const leaking = [];
+    const serverOnly = [];
+    for await (const file of new Glob("**/*.{server,fn,ts,tsx,js,jsx,mts,cts,mjs,cjs}").scan({
+        cwd: app.cwd,
+        dot: false,
+    })) {
+        if (/(^|\/)(node_modules|dist|\.nifra|\.git)\//.test(file))
+            continue;
+        // Strip the source extension once so the conventions' regexes see `src/todos.fn` / `src/db.server`,
+        // which is the shape they match. The glob also includes the extensionless `.fn` / `.server` forms;
+        // those already have the matcher-ready shape and pass through unchanged.
+        const stem = file.replace(/\.[cm]?[jt]sx?$/, "");
+        if (SERVER_FN_MODULE.test(stem)) {
+            if (leaking.length < 5)
+                leaking.push(file);
+        }
+        else if (SERVER_ONLY_MODULE.test(stem)) {
+            if (serverOnly.length < 5)
+                serverOnly.push(file);
+        }
+        if (leaking.length >= 5 && serverOnly.length >= 5)
+            break;
+    }
+    if (serverOnly.length > 0) {
+        throw new Error("[nifra] `nifra dev --bun` can't empty `*.server` modules: Bun's DEV-server bundler takes no " +
+            "plugins, so a server-only module would be bundled WHOLE into the browser - along with whatever " +
+            "it imports and any secret it holds. `nifra build` and `nifra dev` (Vite) both replace it with " +
+            "an empty module, so only this pipeline is affected.\n" +
+            `  Server-only modules found: ${serverOnly.join(", ")}\n` +
+            "  Use `nifra dev` (the Vite pipeline), or reach these from a route/loader for the Bun dev loop.");
+    }
+    if (leaking.length > 0) {
+        throw new Error("[nifra] `nifra dev --bun` can't transform server functions: Bun's DEV-server bundler takes no " +
+            "plugins, so a `*.fn` module would be bundled WHOLE into the browser - its function bodies and " +
+            "anything they import, secrets included. `nifra build` and `nifra dev` (Vite) both replace it " +
+            "with client stubs, so only this pipeline is affected.\n" +
+            `  Server-function modules found: ${leaking.join(", ")}\n` +
+            "  Use `nifra dev` (the Vite pipeline), or move these calls behind a route for the Bun dev loop.");
+    }
+    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);
+        const { createDevServer } = await import("@nifrajs/web/dev");
+        const { framework: fw, routesDir, outDir, backend } = app;
+        const server = await createDevServer({
+            routesDir,
+            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.
+            plugins: asBunPlugins(app.resolvedPlugins.clientPlugins),
+            ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
+            ...(fw.conditions ? { conditions: fw.conditions } : {}),
+            ...(fw.define ? { define: fw.define } : {}),
+            createApp: (clientEntry, importQuery) => createWebApp({
+                adapter: asAdapter(fw.adapter),
+                manifest: discoverRoutes(routesDir, { importQuery }),
+                clientEntry,
+                ...apiOf(backend),
+            }),
+        });
+        console.log(`nifra dev (bun) → http://localhost:${server.port}`);
+        return;
+    }
     // Preflight: `nifra dev` 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.
@@ -128,26 +289,33 @@ async function dev(app, flags) {
         throw new Error("[nifra] `nifra dev` needs `vite` installed in this project. Run it via your workspace-local " +
             "script (`bun run dev`), not `bunx @nifrajs/cli dev` (which can't resolve the project's peers).");
     }
-    const { plugin } = await import("bun");
     const { createViteDevServer } = await import("@nifrajs/web/vite");
     const { framework: fw, routesDir, cwd, backend } = app;
-    // nifra SSRs each request by importing the route modules through Bun (not Vite's ssrLoadModule), so
-    // `.vue`/`.svelte`/Solid routes need their SSR compile plugin registered on Bun's runtime first —
-    // the dev analog of `nifra start`. React/Preact JSX is Bun-native → no server plugins → no-op.
-    for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins)))
-        plugin(p);
+    // No Bun SSR plugins here. `nifra dev` runs the VITE pipeline, and Vite now resolves and compiles
+    // route modules for SSR too (via `ssrLoadModule`), so `.vue`/`.svelte`/Solid are handled by the
+    // app's `vitePlugins` on both halves.
+    //
+    // Registering Bun's SFC plugins alongside was the structural intermix: two toolchains compiling the
+    // 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".
     const server = await createViteDevServer({
         root: cwd,
         routesDir,
         clientModule: fw.clientModule,
-        plugins: await resolvePlugins(fw.vitePlugins),
+        plugins: app.resolvedPlugins.vitePlugins,
+        ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
+        ...(fw.publicEnvPrefix !== undefined ? { publicEnvPrefix: fw.publicEnvPrefix } : {}),
         poll: flags.poll,
         port: flags.port,
         ...(fw.conditions ? { conditions: fw.conditions } : {}),
         ...(fw.define ? { define: fw.define } : {}),
-        createApp: (clientEntry, importQuery) => createWebApp({
+        // `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({
             adapter: asAdapter(fw.adapter),
-            manifest: discoverRoutes(routesDir, { importQuery }),
+            manifest: discoverRoutes(routesDir, { load }),
             clientEntry,
             ...apiOf(backend),
         }),
@@ -155,17 +323,30 @@ async function dev(app, flags) {
     console.log(`nifra dev → http://localhost:${server.port}`);
 }
 /**
- * `nifra build --target <t>` — package the engine (buildClient + buildServer + prerender) into one
+ * `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
+ * _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/`.
  */
-async function buildForTarget(app, target, report) {
-    const { buildTarget, isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import("@nifrajs/web/build");
+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(", ")}.`);
     }
+    if (flags.vite && flags.bun) {
+        throw new Error("[nifra] `nifra build` takes `--vite` or `--bun`, not both.");
+    }
+    // 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);
+    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
@@ -176,6 +357,18 @@ async function buildForTarget(app, target, report) {
             ? resolve(cwd, "nifra.config.ts")
             : resolve(cwd, "framework.ts");
     const backendFile = resolve(cwd, "backend.ts");
+    // 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.
+    const plugins = useVite
+        ? {
+            clientPlugins: app.resolvedPlugins.vitePlugins,
+            serverPlugins: app.resolvedPlugins.vitePlugins,
+        }
+        : {
+            clientPlugins: asBunPlugins(app.resolvedPlugins.clientPlugins),
+            serverPlugins: asBunPlugins(app.resolvedPlugins.serverPlugins),
+        };
     const result = await buildTarget(target, {
         routesDir,
         outDir,
@@ -183,27 +376,32 @@ async function buildForTarget(app, target, report) {
         clientModule: fw.clientModule,
         adapterImport: frameworkFile,
         ...(backend !== undefined && existsSync(backendFile) ? { backendImport: backendFile } : {}),
-        clientPlugins: asBunPlugins(await resolvePlugins(fw.clientPlugins)),
-        serverPlugins: asBunPlugins(await resolvePlugins(fw.serverPlugins)),
+        ...plugins,
         ...(fw.conditions ? { conditions: fw.conditions } : {}),
         ...(fw.define ? { define: fw.define } : {}),
-        // The static target needs a built app to drive prerendering — only build it when targeting static.
+        ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
+        ...(fw.publicEnvPrefix !== undefined ? { publicEnvPrefix: fw.publicEnvPrefix } : {}),
+        // 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}) → ${result.run}`);
-    if (report)
+    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}`);
+    if (flags.report)
         console.log(`\n${renderSizeReport(result.size)}`);
 }
 /** Build the app FACTORY for the `static` target's prerender pass. Registers the
  * framework's SSR Bun plugins (so `.vue`/`.svelte`/Solid routes import) once, then return a factory that
  * `createWebApp`s the app for the client build's manifest. The client entry MUST be the real content-hashed
- * bundle (`client.entry`) — it's the hydration `<script src>` the prerendered HTML emits, so a placeholder
+ * bundle (`client.entry`) - it's the hydration `<script src>` the prerendered HTML emits, so a placeholder
  * would 404 and the pages would render but never hydrate (inert controls). Styles/route-preload are wired
  * from the same manifest so the static HTML matches the deployed app. */
 async function buildPrerenderApp(app) {
     const { plugin } = await import("bun");
     const { framework: fw, routesDir, backend } = app;
-    for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins)))
+    for (const p of asBunPlugins(app.resolvedPlugins.serverPlugins))
         plugin(p);
     return (client) => createWebApp({
         adapter: asAdapter(fw.adapter),
@@ -225,7 +423,7 @@ async function start(app, flags) {
             throw new Error(`[nifra] ${app.outDir} holds a Cloudflare Pages worker bundle (_worker.js), not a self-hosting ` +
                 "server. Run `nifra build --target bun` then `nifra start`, or serve this dir with `wrangler pages`.");
         }
-        throw new Error(`[nifra] no ${serverFile} — run \`nifra build\` or \`nifra build --target bun\` first.`);
+        throw new Error(`[nifra] no ${serverFile} - run \`nifra build\` or \`nifra build --target bun\` first.`);
     }
     Bun.env.PORT = String(flags.port);
     await import(__rewriteRelativeImportExtension(serverFile));
@@ -239,6 +437,8 @@ export function parseFlags(args) {
     let poll = Bun.env.CHOKIDAR_USEPOLLING === "1";
     let target = "bun";
     let report = false;
+    let vite = false;
+    let bun = false;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if ((a === "--port" || a === "-p") && args[i + 1])
@@ -251,11 +451,15 @@ export function parseFlags(args) {
             target = args[++i];
         else if (a === "--report")
             report = true;
+        else if (a === "--vite")
+            vite = true;
+        else if (a === "--bun")
+            bun = true;
     }
     if (!Number.isFinite(port) || port < 0 || port > 65535) {
         throw new Error(`[nifra] invalid --port: ${port}`);
     }
-    return { port, out, poll, target, report };
+    return { port, out, poll, target, report, vite, bun };
 }
 async function main() {
     const argv = Bun.argv.slice(2);
@@ -268,14 +472,14 @@ async function main() {
         console.log(`nifra (@nifrajs/cli) ${CLI_VERSION}`);
         return;
     }
-    // `mcp` runs a long-lived stdio server and loads the project lazily per-tool — it must not go through
+    // `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") {
         const { runMcpServer } = await import("./mcp.js");
         await runMcpServer(process.cwd(), CLI_VERSION);
         return;
     }
-    // `docs-mcp` runs the PUBLIC docs MCP over HTTP — project-independent (serves the bundled corpus), so
+    // `docs-mcp` runs the PUBLIC docs MCP over HTTP - project-independent (serves the bundled corpus), so
     // it self-hosts anywhere Bun runs (a VPS behind a reverse proxy, a container). Long-lived; no loadApp.
     if (command === "docs-mcp") {
         const { handleMcpHttp } = await import("./mcp-http.js");
@@ -288,7 +492,7 @@ async function main() {
         console.log(`nifra docs MCP (HTTP) → ${server.url}`);
         return;
     }
-    // `check` is a pure cwd-based gate (typecheck + lint) — it must run even when the project doesn't
+    // `check` is a pure cwd-based gate (typecheck + lint) - it must run even when the project doesn't
     // load (API-only, not built yet), so it dispatches before the eager `loadApp` below.
     if (command === "check") {
         const { runCheck } = await import("./check.js");
@@ -319,7 +523,15 @@ async function main() {
             process.exitCode = 1;
         return;
     }
-    // `doctor` is a pure cwd check (imports vs declared deps) — like `check`, dispatch before `loadApp`
+    // `sync-routes` regenerates the route-search types `.d.ts` (typed `navigate({ to, search })`) from
+    // `routes/`. Pure fs/text (needs only the route tree, not `framework.ts`), so dispatch before `loadApp`.
+    if (command === "sync-routes") {
+        const { runSyncRoutes } = await import("./sync-routes.js");
+        if (!(await runSyncRoutes(process.cwd())))
+            process.exitCode = 1;
+        return;
+    }
+    // `doctor` is a pure cwd check (imports vs declared deps) - like `check`, dispatch before `loadApp`
     // so it runs on an API-only / not-yet-built project.
     if (command === "doctor") {
         const { runDoctor } = await import("./doctor.js");
@@ -330,7 +542,7 @@ async function main() {
             process.exitCode = 1;
         return;
     }
-    // `snapshot` / `diff` load ONLY backend.ts (the API contract) — like `check`, they must run on an
+    // `snapshot` / `diff` load ONLY backend.ts (the API contract) - like `check`, they must run on an
     // API-only project, so they dispatch before the eager `loadApp`.
     if (command === "snapshot") {
         const { runSnapshot } = await import("./diff-tool.js");
@@ -345,7 +557,7 @@ async function main() {
             await runSnapshot(process.cwd(), out !== undefined ? { out } : {});
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(formatCliError(err));
             process.exitCode = 1;
         }
         return;
@@ -359,7 +571,7 @@ async function main() {
             }
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(formatCliError(err));
             process.exitCode = 1;
         }
         return;
@@ -383,7 +595,7 @@ async function main() {
                 process.exitCode = 1;
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(formatCliError(err));
             process.exitCode = 1;
         }
         return;
@@ -423,7 +635,7 @@ async function main() {
             }
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(formatCliError(err));
             process.exitCode = 1;
         }
         return;
@@ -465,7 +677,7 @@ async function main() {
             }
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(formatCliError(err));
             process.exitCode = 1;
         }
         return;
@@ -495,13 +707,13 @@ async function main() {
                 process.exitCode = 1;
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(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
+    // 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).
     if (command === "upgrade") {
         const { runUpgrade } = await import("./upgrade.js");
@@ -518,12 +730,12 @@ async function main() {
                 process.exitCode = 1;
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(formatCliError(err));
             process.exitCode = 1;
         }
         return;
     }
-    // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) — like `check`/
+    // `port` is a pure cwd-based portability linter (scans source, doesn't run the app) - like `check`/
     // `doctor`, dispatch before the eager `loadApp` so it runs on an API-only / not-yet-built project.
     if (command === "port") {
         const { runPort } = await import("./port.js");
@@ -545,7 +757,7 @@ async function main() {
                 process.exitCode = 1;
         }
         catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
+            console.error(formatCliError(err));
             process.exitCode = 1;
         }
         return;
@@ -565,11 +777,37 @@ async function main() {
     if (command === "dev")
         await dev(app, flags);
     else if (command === "build")
-        await buildForTarget(app, flags.target, flags.report);
+        await buildForTarget(app, flags.target, flags);
     else if (command === "context")
         console.log(describeProject(app));
     else if (command === "routes") {
-        console.log(await describeRoutes(app, { json: argv.includes("--json") }));
+        if (argv.includes("--modes")) {
+            // `--modes` answers a different question than the default table: not "what URLs exist" but "how
+            // does each render, and can the target I'm about to deploy to actually honour that". Resolves
+            // against `--target` when given, so a `static` build's server-needing route fails here, in one
+            // place, instead of 404ing in production.
+            const { buildRouteManifest, renderRouteManifest } = await import("@nifrajs/web/route-manifest");
+            const manifest = discoverRoutes(app.routesDir);
+            // `flags.target` defaults to "bun" for `build`; here an EXPLICIT `--target` is what opts into
+            // gating, so read it from argv rather than inheriting the build default (which would silently gate
+            // every `nifra routes --modes` against bun).
+            const targetIdx = argv.indexOf("--target");
+            const target = targetIdx !== -1 ? argv[targetIdx + 1] : undefined;
+            const routeManifest = await buildRouteManifest(manifest, {
+                ...(target !== undefined ? { target } : {}),
+            });
+            if (argv.includes("--json"))
+                console.log(JSON.stringify(routeManifest, null, 2));
+            else
+                console.log(renderRouteManifest(routeManifest));
+            // A target that cannot honour a route is a build-breaking fact, not a note: exit non-zero so the
+            // same command in CI gates the deploy it is warning about.
+            if (routeManifest.conflicts.length > 0)
+                process.exitCode = 1;
+        }
+        else {
+            console.log(await describeRoutes(app, { json: argv.includes("--json") }));
+        }
     }
     else
         await start(app, flags);
@@ -578,7 +816,7 @@ async function main() {
 // exported `parseFlags`. `import.meta.main` is true only for the process's entry module.
 if (import.meta.main) {
     main().catch((err) => {
-        console.error(err instanceof Error ? err.message : String(err));
+        console.error(formatCliError(err));
         process.exitCode = 1;
     });
 }