@nifrajs/cli 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "The nifra CLI — zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -41,14 +41,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "2.1.0",
-    "@nifrajs/core": "2.1.0",
-    "@nifrajs/mcp": "2.1.0",
-    "@nifrajs/runner": "2.1.0",
-    "@nifrajs/schema": "2.1.0",
-    "@nifrajs/testing": "2.1.0",
-    "@nifrajs/web": "2.1.0",
-    "create-nifra": "2.1.0"
+    "@nifrajs/client": "2.2.0",
+    "@nifrajs/core": "2.2.0",
+    "@nifrajs/mcp": "2.2.0",
+    "@nifrajs/runner": "2.2.0",
+    "@nifrajs/schema": "2.2.0",
+    "@nifrajs/testing": "2.2.0",
+    "@nifrajs/web": "2.2.0",
+    "create-nifra": "2.2.0"
   },
   "repository": {
     "type": "git",

package/src/check.ts

@@ -471,6 +471,69 @@ export function scanUntypedClient(file: string, content: string): SourceFinding[
   return out
 }
 
+/**
+ * Specifiers that no longer exist, and what replaced them.
+ *
+ * These are the breaks a typecheck does not catch and a test suite does not either. `@nifrajs/core/ws`
+ * was a side-effect import removed in 2.0 in favour of `.use(websocket())`; a consuming package kept
+ * the import and a 533-test suite stayed green while the app could not boot. `@nifrajs/budget` folded
+ * into core with no npm deprecation, so `bun install` fails workspace-wide with a resolution error
+ * that names neither the cause nor the replacement.
+ *
+ * A lint is the right shape for this: it runs before boot, names the file and line, and states the
+ * replacement - which is what neither the resolver error nor the runtime failure does.
+ */
+const REMOVED_IMPORTS: ReadonlyArray<{
+  readonly specifier: string
+  readonly since: string
+  readonly replacement: string
+  /** Flag ONLY the bare side-effect form (`import "x"`). A module that still exports values is not
+   * removed - only its install-by-import behaviour is - so flagging every import of it would be
+   * wrong and would train people to ignore the rule. */
+  readonly sideEffectOnly?: boolean
+}> = [
+  {
+    specifier: "@nifrajs/budget",
+    since: "2.0",
+    replacement:
+      'import from "@nifrajs/core/budget" — the package folded into core and npm `latest` is still 1.13.0, so a `^2` range resolves to nothing',
+  },
+  {
+    specifier: "@nifrajs/core/ws",
+    since: "2.0",
+    sideEffectOnly: true,
+    replacement:
+      'a bare `import "@nifrajs/core/ws"` no longer installs the runtime — register it explicitly with `.use(websocket())`, importing `websocket` from the same module',
+  },
+]
+
+/** Whether the import statement at `index` is the bare side-effect form (`import "x"`), rather than
+ * one with bindings (`import { y } from "x"`). */
+function isSideEffectImport(content: string, index: number): boolean {
+  // `staticImportEdges` reports the index of the STATEMENT, not of the specifier, so read forward:
+  // a side-effect import is `import` followed directly by the quoted specifier, with no bindings and
+  // no `from` in between.
+  return /^import\s*["'`]/.test(content.slice(index, index + 32))
+}
+
+/** Flag an import of a specifier that no longer exists. Pure; matches the exact specifier or a subpath
+ * of it, so `@nifrajs/budget/x` is caught alongside `@nifrajs/budget`. */
+export function scanRemovedImports(file: string, content: string): SourceFinding[] {
+  const out: SourceFinding[] = []
+  const lines = content.split("\n")
+  for (const edge of staticImportEdges(content)) {
+    const removed = REMOVED_IMPORTS.find(
+      (entry) =>
+        edge.specifier === entry.specifier || edge.specifier.startsWith(`${entry.specifier}/`),
+    )
+    if (removed === undefined) continue
+    if (removed.sideEffectOnly === true && !isSideEffectImport(content, edge.index)) continue
+    const line = lineAt(content, edge.index)
+    out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() })
+  }
+  return out
+}
+
 /** Scan a route module for top-level server-only imports. Returns `[]` for non-route files (only
  * `routes/` modules are browser-bundled, so a server-only import elsewhere is fine). Each finding carries
  * the offending `specifier` so the diagnostic can render the `routeFile → specifier` chain. Pure. */
@@ -939,6 +1002,7 @@ export interface CheckDiagnostic {
     | "typed-client"
     | "untyped-client"
     | "server-only-import"
+    | "removed-import"
     | "response-route"
     | "undeclared-dependency"
     | "duplicate-install"
@@ -1189,6 +1253,7 @@ export async function collectCheckResult(
   const fetches: SourceFinding[] = []
   const staticRoutes: StaticRouteFinding[] = []
   const untypedClients: SourceFinding[] = []
+  const removedImports: SourceFinding[] = []
   const serverImports: TransitiveServerImportFinding[] = []
   const responseRoutes: SourceFinding[] = []
   // Route modules (rel + content) collected during the walk, so the TRANSITIVE server-only resolution
@@ -1207,6 +1272,7 @@ export async function collectCheckResult(
       fetches.push(...scanFetchText(rel, content, checkConfig.externalMounts))
       staticRoutes.push(...scanStaticRouteText(rel, content))
       untypedClients.push(...scanUntypedClient(rel, content))
+      removedImports.push(...scanRemovedImports(rel, content))
       if (ROUTE_FILE.test(rel)) routeModules.push({ rel, content })
       responseRoutes.push(...scanResponseRoutes(rel, content))
     }),
@@ -1299,6 +1365,21 @@ export async function collectCheckResult(
       suggestion: ownFetchSuggestion(f, routes),
     })
   }
+  for (const f of removedImports.sort(bySite)) {
+    const entry = REMOVED_IMPORTS.find(
+      (candidate) =>
+        f.snippet.includes(`"${candidate.specifier}`) ||
+        f.snippet.includes(`'${candidate.specifier}`),
+    )
+    diagnostics.push({
+      rule: "removed-import",
+      severity: "error",
+      file: f.file,
+      line: f.line,
+      message: `${f.snippet} — removed in nifra ${entry?.since ?? "2.0"}: ${entry?.replacement ?? "see the changelog"}`,
+      fix: entry?.replacement ?? "see the changelog",
+    })
+  }
   for (const f of untypedClients.sort(bySite)) {
     diagnostics.push({
       rule: "untyped-client",
@@ -1602,5 +1683,15 @@ export async function runCheck(
       "\ntip: no .mcp.json here - run `nifra init-agents` to wire this project's MCP + agent files (no-clobber).",
     )
   }
+  // `public/` used to be served in dev (inherited from Vite) and not in production, so every app
+  // hand-rolled static serving in its own server entry - or shipped a file that 404'd only once
+  // deployed. `@nifrajs/web` owns it now, so an app carrying the workaround can delete it. A tip
+  // rather than a finding: a hand-rolled handler still works (it simply runs first), so this is
+  // not a failure, and telling an app it can delete code is the entire point.
+  if (existsSync(join(cwd, "public"))) {
+    console.log(
+      '\ntip: `public/` is now served by @nifrajs/web in dev AND production (publicDir, default "public"). If your server entry hand-rolls static serving, you can delete it.',
+    )
+  }
   return result.ok
 }

package/src/cli.ts

@@ -16,7 +16,8 @@ import { createWebApp, DEFAULT_DEV_PORT, type RenderAdapter } 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 +27,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
 
 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 +54,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 +67,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),
@@ -107,7 +131,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 +141,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.2.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 +149,67 @@ const asBunPlugins = (v: readonly unknown[]): BunPlugin[] => v as BunPlugin[]
 const apiOf = (backend: unknown): { api?: unknown } =>
   backend === undefined ? {} : { api: inProcessClient(backend as never) }
 
+/**
+ * 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.
+ */
+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
+  }
+  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 +221,33 @@ 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 } : {}),
     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),
       }),
@@ -171,13 +262,27 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
  * `nifra.config.ts`, which pulls in Vite plugins), and the backend from `backend.ts` when present;
  * `buildTarget` generates the per-target server entry from those + the app's `routes/`.
  */
-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 +293,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,15 +312,19 @@ 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 } : {}),
+    ...(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
@@ -217,7 +338,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),
@@ -266,6 +387,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 +396,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> {
@@ -588,10 +713,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)
 }
 

package/src/doctor.ts

@@ -10,7 +10,7 @@
  * when a monorepo would hoist it. Relative paths, runtime builtins (node core, `node:`/`bun:`, `bun`),
  * the package's own name, and tsconfig `paths` aliases are excluded — none of them are npm deps.
  */
-import { realpath } from "node:fs/promises"
+import { realpath, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
 import { dirname, join, relative } from "node:path"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
@@ -336,13 +336,75 @@ const displayPath = (cwd: string, path: string): string => {
   return rel === "" ? "." : rel
 }
 
+/**
+ * Resolve the workspace root that actually governs `cwd`, or `undefined` when there is none.
+ *
+ * Everything below is anchored to a package that declares `workspaces`. In a monorepo you run
+ * `nifra check` from the app - `apps/web` - and THAT manifest declares nothing, so the scan collapses
+ * to the app itself and the sibling package holding the second copy is never probed. Running from an
+ * app subdirectory is the normal case, which made this the configuration the check was blind in.
+ *
+ * An ancestor is adopted only when its `workspaces` patterns genuinely match `cwd`. A parent
+ * directory that happens to contain a manifest is not automatically this project's root, and adopting
+ * one would silently widen the scan to an unrelated tree. The walk also stops at a `.git` boundary
+ * (checked after the manifest, so a repo root that IS the workspace root still counts) and at the
+ * filesystem root.
+ */
+/** Whether `path` exists at all. `stat`, not a file read: a `.git` is a directory in a normal
+ * checkout and a FILE in a worktree or submodule, and both mark the same boundary. */
+const pathExists = (path: string): Promise<boolean> =>
+  stat(path).then(
+    () => true,
+    () => false,
+  )
+
+async function findWorkspaceRoot(
+  cwd: string,
+): Promise<{ root: string; package: Record<string, unknown> } | undefined> {
+  let dir = dirname(cwd)
+  for (;;) {
+    const manifestPath = join(dir, "package.json")
+    const manifest = await readJson(manifestPath)
+    if (manifest !== undefined) {
+      const patterns = workspacePatterns(manifest)
+      if (patterns.length > 0 && (await patternsCover(dir, patterns, cwd))) {
+        return { root: dir, package: manifest }
+      }
+    }
+    // A `.git` here means we have reached this project's boundary; anything above belongs to a
+    // different repo (or a parent checkout) and must not be adopted.
+    if (await pathExists(join(dir, ".git"))) return undefined
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
+/** Whether any of `root`'s workspace patterns resolves to a manifest inside `target`'s package. */
+async function patternsCover(root: string, patterns: string[], target: string): Promise<boolean> {
+  for (const pattern of patterns) {
+    const packagePattern = `${pattern.replace(/\/$/, "")}/package.json`
+    for await (const rel of new Bun.Glob(packagePattern).scan({ cwd: root, dot: false })) {
+      if (rel.split(/[\\/]/).includes("node_modules")) continue
+      if (dirname(join(root, rel)) === target) return true
+    }
+  }
+  return false
+}
+
 /** Find identity-sensitive dependencies that resolve to multiple physical directories. Two copies at
- * the same version still fail: module identity (React hooks, Nifra symbols/registries) is path-based. */
+ * the same version still fail: module identity (React hooks, Nifra symbols/registries) is path-based.
+ *
+ * `cwd` is where the user ran the check; the scan is anchored at the workspace root above it (see
+ * {@link findWorkspaceRoot}) so sibling packages are probed, while paths are still REPORTED relative
+ * to `cwd` so the findings read the way the user's terminal does. */
 export async function collectDuplicateInstalls(
   cwd: string,
   rootPackage: Record<string, unknown>,
 ): Promise<DuplicateInstallFinding[]> {
-  const importers = await workspaceImporters(cwd, rootPackage)
+  const workspace = await findWorkspaceRoot(cwd)
+  const scanRoot = workspace?.root ?? cwd
+  const importers = await workspaceImporters(scanRoot, workspace?.package ?? rootPackage)
   const byPackage = new Map<string, Map<string, { version: string; importers: Set<string> }>>()
   const record = (
     name: string,
@@ -364,7 +426,10 @@ export async function collectDuplicateInstalls(
     for (const name of duplicateTargets(importer.package)) {
       if (importer.package.name === name) continue
       targets.add(name)
-      const copy = await resolvedInstalledCopy(importer.root, cwd, name)
+      // Boundary is the SCAN root, not `cwd`: an importer can now sit beside or above the directory
+      // the user ran from, and stopping the upward walk at `cwd` would abandon it before reaching the
+      // hoisted copy it actually resolves.
+      const copy = await resolvedInstalledCopy(importer.root, scanRoot, name)
       if (copy !== undefined) record(name, copy, displayPath(cwd, importer.root))
     }
   }
@@ -374,8 +439,8 @@ export async function collectDuplicateInstalls(
   // out hides the very split it should catch: every declaring package nested onto one copy while the
   // root resolved a different one, which reads as a single copy when only declarers are consulted.
   for (const name of targets) {
-    const copy = await resolvedInstalledCopy(cwd, cwd, name)
-    if (copy !== undefined) record(name, copy, ".")
+    const copy = await resolvedInstalledCopy(scanRoot, scanRoot, name)
+    if (copy !== undefined) record(name, copy, displayPath(cwd, scanRoot))
   }
 
   const findings: DuplicateInstallFinding[] = []