@nifrajs/cli 2.1.0 → 2.3.0

package/src/cli.ts

@@ -1,22 +1,29 @@
 #!/usr/bin/env bun
 /**
- * `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, type RenderAdapter } from "@nifrajs/web"
+import {
+  createWebApp,
+  DEFAULT_DEV_PORT,
+  type RenderAdapter,
+  SERVER_FN_MODULE,
+  SERVER_ONLY_MODULE,
+} from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
 import { describeProject, describeRoutes } from "./introspect.ts"
-import { type LoadedApp, loadApp, resolvePlugins } from "./load.ts"
+import { type LoadedApp, loadApp } from "./load.ts"
+import { chooseBuildPipeline } from "./pipeline-guard.ts"
 
 export interface Flags {
   readonly port: number
@@ -26,13 +33,26 @@ export interface Flags {
   readonly target: string
   /** `nifra build --report`: print a per-chunk size + gzip table after the build. */
   readonly report: boolean
+  /** `nifra build --vite`: force the client + server through Vite/Rollup. Without a flag the pipeline is
+   * chosen per app (`chooseBuildPipeline`) - Bun unless the app's only transforms are `vitePlugins`. */
+  readonly vite: boolean
+  /** `nifra dev --bun`: run the Bun-pipeline dev server (Bun.serve native HMR - including React Fast
+   * Refresh with state preserved - and no Vite in the process). Default stays Vite for its plugin
+   * ecosystem; `--bun` trades that for one bundler across dev and prod. Refuses CSS-Modules apps.
+   *
+   * `nifra build --bun`: force the Bun build. Refuses when that would drop the app's `vitePlugins`. */
+  readonly bun: boolean
 }
 
-const HELP = `nifra — zero-config dev/build/start for a nifra app
+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
@@ -40,6 +60,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
@@ -48,6 +73,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),
@@ -60,7 +90,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;
@@ -68,13 +98,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.
@@ -107,7 +140,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
@@ -117,7 +150,7 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "2.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: unknown): RenderAdapter => v as RenderAdapter
@@ -125,7 +158,153 @@ const asBunPlugins = (v: readonly unknown[]): BunPlugin[] => v as BunPlugin[]
 const apiOf = (backend: unknown): { api?: unknown } =>
   backend === undefined ? {} : { api: inProcessClient(backend as never) }
 
+/**
+ * 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: unknown): string {
+  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: LoadedApp): Promise<void> {
+  const { Glob } = await import("bun")
+  const offenders: string[] = []
+  for await (const file of new Glob("**/*.module.css").scan({ cwd: app.cwd, dot: false })) {
+    if (/(^|\/)(node_modules|dist|\.nifra|\.git)\//.test(file)) continue
+    offenders.push(file)
+    if (offenders.length >= 5) break
+  }
+  // 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: string[] = []
+  const serverOnly: string[] = []
+  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: LoadedApp, flags: Flags): Promise<void> {
+  // `--bun`: the Bun-pipeline dev server - Bun.serve's native HMR bundles + hot-reloads the client while
+  // Bun's runtime resolves SSR, with no Vite in the process at all. The mirror of `nifra build --vite`:
+  // each pipeline is selectable in BOTH phases, and neither ever runs inside the other.
+  if (flags.bun) {
+    await assertBunDevSupportsApp(app)
+    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.
@@ -137,26 +316,34 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
         "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) =>
+    // `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),
       }),
@@ -165,19 +352,33 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
 }
 
 /**
- * `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: LoadedApp, target: string, report: boolean): Promise<void> {
-  const { buildTarget, isBuildTarget, renderSizeReport, BUILD_TARGETS } = await import(
-    "@nifrajs/web/build"
-  )
+async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Promise<void> {
+  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
@@ -188,6 +389,18 @@ async function buildForTarget(app: LoadedApp, target: string, report: boolean):
       ? 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 as unknown as BunPlugin[],
+        serverPlugins: app.resolvedPlugins.vitePlugins as unknown as BunPlugin[],
+      }
+    : {
+        clientPlugins: asBunPlugins(app.resolvedPlugins.clientPlugins),
+        serverPlugins: asBunPlugins(app.resolvedPlugins.serverPlugins),
+      }
   const result = await buildTarget(target, {
     routesDir,
     outDir,
@@ -195,21 +408,25 @@ async function buildForTarget(app: LoadedApp, target: string, report: boolean):
     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(`\n${renderSizeReport(result.size)}`)
+  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(
@@ -217,7 +434,7 @@ async function buildPrerenderApp(
 ): Promise<(client: BuiltManifest) => { fetch(req: Request): Response | Promise<Response> }> {
   const { plugin } = await import("bun")
   const { framework: fw, routesDir, backend } = app
-  for (const p of asBunPlugins(await resolvePlugins(fw.serverPlugins))) plugin(p)
+  for (const p of asBunPlugins(app.resolvedPlugins.serverPlugins)) plugin(p)
   return (client) =>
     createWebApp({
       adapter: asAdapter(fw.adapter),
@@ -250,7 +467,7 @@ async function start(app: LoadedApp, flags: Flags): Promise<void> {
       )
     }
     throw new Error(
-      `[nifra] no ${serverFile} — run \`nifra build\` or \`nifra build --target bun\` first.`,
+      `[nifra] no ${serverFile} - run \`nifra build\` or \`nifra build --target bun\` first.`,
     )
   }
   Bun.env.PORT = String(flags.port)
@@ -266,6 +483,8 @@ export function parseFlags(args: readonly string[]): Flags {
   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]) port = Number(args[++i])
@@ -273,11 +492,13 @@ export function parseFlags(args: readonly string[]): Flags {
     else if (a === "--poll") poll = true
     else if (a === "--target" && args[i + 1]) target = args[++i] as string
     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(): Promise<void> {
@@ -291,14 +512,14 @@ async function main(): Promise<void> {
     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.ts")
     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.ts")
@@ -311,7 +532,7 @@ async function main(): Promise<void> {
     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.ts")
@@ -343,7 +564,14 @@ async function main(): Promise<void> {
     if (!(await runSyncManifest(process.cwd()))) 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.ts")
+    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.ts")
@@ -356,7 +584,7 @@ async function main(): Promise<void> {
       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.ts")
@@ -370,7 +598,7 @@ async function main(): Promise<void> {
     try {
       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
@@ -383,7 +611,7 @@ async function main(): Promise<void> {
         process.exitCode = 1
       }
     } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err))
+      console.error(formatCliError(err))
       process.exitCode = 1
     }
     return
@@ -408,7 +636,7 @@ async function main(): Promise<void> {
       )
         process.exitCode = 1
     } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err))
+      console.error(formatCliError(err))
       process.exitCode = 1
     }
     return
@@ -449,7 +677,7 @@ async function main(): Promise<void> {
         throw new Error("[nifra] capabilities needs `snapshot` or `check`")
       }
     } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err))
+      console.error(formatCliError(err))
       process.exitCode = 1
     }
     return
@@ -491,7 +719,7 @@ async function main(): Promise<void> {
         throw new Error("[nifra] manifest needs `emit` or `diff`")
       }
     } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err))
+      console.error(formatCliError(err))
       process.exitCode = 1
     }
     return
@@ -522,13 +750,13 @@ async function main(): Promise<void> {
       )
         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.ts")
@@ -543,12 +771,12 @@ async function main(): Promise<void> {
       })
       if (!ok) 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.ts")
@@ -568,7 +796,7 @@ async function main(): Promise<void> {
       })
       if (!passed) process.exitCode = 1
     } catch (err) {
-      console.error(err instanceof Error ? err.message : String(err))
+      console.error(formatCliError(err))
       process.exitCode = 1
     }
     return
@@ -588,10 +816,34 @@ async function main(): Promise<void> {
   const flags = parseFlags(argv.slice(1))
   const app = await loadApp(process.cwd(), flags.out)
   if (command === "dev") await dev(app, flags)
-  else if (command === "build") await buildForTarget(app, flags.target, flags.report)
+  else if (command === "build") 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)
 }
 
@@ -599,7 +851,7 @@ async function main(): Promise<void> {
 // 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
   })
 }