@nifrajs/cli 2.9.1 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "2.9.1",
+  "version": "2.11.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.9.1",
-    "@nifrajs/core": "2.9.1",
-    "@nifrajs/mcp": "2.9.1",
-    "@nifrajs/runner": "2.9.1",
-    "@nifrajs/schema": "2.9.1",
-    "@nifrajs/testing": "2.9.1",
-    "@nifrajs/web": "2.9.1",
-    "create-nifra": "2.9.1"
+    "@nifrajs/client": "2.11.0",
+    "@nifrajs/core": "2.11.0",
+    "@nifrajs/mcp": "2.11.0",
+    "@nifrajs/runner": "2.11.0",
+    "@nifrajs/schema": "2.11.0",
+    "@nifrajs/testing": "2.11.0",
+    "@nifrajs/web": "2.11.0",
+    "create-nifra": "2.11.0"
   },
   "repository": {
     "type": "git",

package/src/check.ts

@@ -23,6 +23,9 @@ import { Glob } from "bun"
 import type * as TSApi from "typescript"
 import type { CapabilityProjectReport } from "./capabilities-tool.ts"
 import { importTypeScript, type TypeScriptApi } from "./internal/typescript-import.ts"
+// Type-only: `pipeline-report.ts` imports this module's source scanners, so a value import here would
+// close a cycle. Doctor is what actually runs the collector (see the `pipeline` rule below).
+import type { PipelineReport } from "./pipeline-report.ts"
 
 export interface SourceFinding {
   readonly file: string
@@ -1396,6 +1399,7 @@ export interface CheckDiagnostic {
     | "undeclared-dependency"
     | "duplicate-install"
     | "stale-workspace-dist"
+    | "pipeline"
     | "server-manifest-drift"
     | "manifest-drift"
     | "capability-assurance"
@@ -1443,6 +1447,13 @@ export interface CheckResult {
   readonly ok: boolean
   readonly typecheck: "pass" | "fail" | "skipped"
   readonly diagnostics: readonly CheckDiagnostic[]
+  /**
+   * Which bundler this app's phases run on, read statically from the config, and how nifra concluded
+   * it. Returned even when nothing is wrong: an agent reading this project has to know which plugin
+   * slot is live and which toolchain compiles a component before its next edit, and every `pipeline`
+   * diagnostic below is only interpretable against it. Absent when the directory is not a nifra app.
+   */
+  readonly pipeline?: PipelineReport
   /** Intentional non-typed mount prefixes declared in `nifra.check.json` (e.g. `/auth` for a mounted
    * better-auth). Echoed here so `--json` / the MCP tool / the report can show what the typed-client scan
    * deliberately skipped - a suppressed prefix stays auditable instead of silently hiding real drift. */
@@ -1507,6 +1518,8 @@ const SERVER_IMPORT_HINT =
   "server-only import in a route module (bundled for the browser) - reach it via c.db / ctx.api inside a loader, never a top-level import"
 const RESPONSE_ROUTE_HINT =
   "route handler returns a raw Response - the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you); for a stream use a typed SSE route (`app.sse(...)`), which keeps typed events; or, if a raw Response is intended (file/redirect), add `{ response: t.… }` or a `// nifra-expect raw-response` comment to mark it and silence this"
+const PIPELINE_DOC_HINT =
+  "nifra runs one bundler per phase - `vitePlugins` feed Vite, `clientPlugins`/`serverPlugins` feed Bun, and the file `nifra build` imports the adapter from is bundled into the server. See the Gotchas section of the Dev & HMR guide."
 const UNDECLARED_DEP_HINT =
   "imported package is not declared in package.json dependencies - run bun add to declare it"
 const SQL_COMPILER_MISSING_HINT =
@@ -1944,6 +1957,21 @@ export async function collectCheckResult(
       })
     }
   }
+  // The two-pipeline rule, read from the config as TEXT (doctor collects it - see ./pipeline-report.ts).
+  // `loadApp` already refuses a misplaced plugin, but only when something loads the app; a check that
+  // never executes project code, and CI that never starts a dev server, would otherwise meet these for
+  // the first time as a production server that built cleanly and died at startup.
+  for (const f of dr.pipeline?.findings ?? []) {
+    diagnostics.push({
+      rule: "pipeline",
+      severity: f.severity,
+      file: f.file,
+      ...(f.line !== undefined ? { line: f.line } : {}),
+      message: f.message,
+      fix: f.fix,
+      suggestion: { kind: "manual", title: f.fix, steps: [PIPELINE_DOC_HINT] },
+    })
+  }
   // #7: a committed server-manifest.ts that drifted from routes/ - name the exact missing/extra routes.
   for (const f of manifestDrift) {
     const parts: string[] = []
@@ -2117,6 +2145,7 @@ export async function collectCheckResult(
     ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
     typecheck: tc.ran ? (tc.ok ? "pass" : "fail") : "skipped",
     diagnostics: shown,
+    ...(dr.pipeline !== undefined ? { pipeline: dr.pipeline } : {}),
     ...(checkConfig.externalMounts.length > 0
       ? { externalMounts: checkConfig.externalMounts }
       : {}),
@@ -2146,6 +2175,16 @@ export async function runCheck(
         ? "✗ typecheck failed - the frontend/backend contract is broken"
         : "• typecheck skipped (no tsconfig / typescript not installed)",
   )
+  // Stated on every run, passing or not. "Which bundler is this app on" decides which plugin slot is
+  // live and which toolchain compiles a component, so it belongs in the report rather than only in the
+  // dev server's banner - where CI never sees it.
+  if (result.pipeline !== undefined) {
+    console.log(
+      result.pipeline.pipeline === "unknown"
+        ? `• bundler: not readable from ${result.pipeline.configFile} - ${result.pipeline.reason}`
+        : `• bundler: ${result.pipeline.pipeline} (${result.pipeline.reason})`,
+    )
+  }
   if (result.externalMounts !== undefined && result.externalMounts.length > 0) {
     console.log(
       `• intentional external mounts (not typed-client checked): ${result.externalMounts.join(", ")}`,
@@ -2163,6 +2202,7 @@ export async function runCheck(
     ["undeclared-dependency", "undeclared dependency in package.json"],
     ["duplicate-install", "duplicate identity-sensitive dependency install"],
     ["stale-workspace-dist", "workspace-linked dist older than its source"],
+    ["pipeline", "bundler pipeline (Vite/Bun) config"],
     ["server-manifest-drift", "server-manifest.ts drifted from routes/"],
     ["manifest-drift", "versioned trust manifest drift"],
     ["capability-assurance", "effect/capability assurance"],
@@ -2170,11 +2210,20 @@ export async function runCheck(
     ["check-config", "nifra.check.json"],
   ] as const) {
     const ds = counts(rule)
-    if (rule === "response-route" || rule === "stale-workspace-dist") {
-      // Advisory: surfaced with ⚠, never folded into pass/fail.
-      console.log(ds.length === 0 ? `✓ ${label}: none` : `⚠ ${label}: ${ds.length} (advisory)`)
-    } else if (rule !== "typecheck") {
-      console.log(ds.length === 0 ? `✓ ${label}: none` : `✗ ${label}: ${ds.length}`)
+    if (rule !== "typecheck") {
+      // Marked by SEVERITY, not by rule name. `response-route` and `stale-workspace-dist` are advisory
+      // in whole; `pipeline` is the first rule that is advisory in part (a misplaced plugin fails, a
+      // resolve condition the Bun dev bundler can't take does not), so the counts are split rather than
+      // rounded up to the worse of the two.
+      const errors = ds.filter((d) => d.severity === "error").length
+      const advisory = ds.length - errors
+      console.log(
+        ds.length === 0
+          ? `✓ ${label}: none`
+          : errors === 0
+            ? `⚠ ${label}: ${advisory} (advisory)`
+            : `✗ ${label}: ${errors}${advisory > 0 ? ` (+${advisory} advisory)` : ""}`,
+      )
     }
     for (const d of ds) {
       console.log(`    ${d.file ?? ""}${d.line ? `:${d.line}` : ""}  ${d.message}`)

package/src/cli.ts

@@ -3,7 +3,7 @@
  * `nifra` - the zero-config CLI for a nifra app. Reads `framework.ts` + `backend.ts` + `routes/` from
  * the project root (see {@link loadApp}) and wires the right `@nifrajs/web` entrypoint:
  *
- *   nifra dev      true-HMR dev server (Vite middleware + nifra SSR)        - @nifrajs/web/vite
+ *   nifra dev      true-HMR dev server (Bun native HMR + nifra SSR)         - @nifrajs/web/dev
  *   nifra build    emit a complete target-specific deploy directory        - @nifrajs/web/build
  *   nifra start    run the default Bun build                               - dist/server.js
  *
@@ -15,9 +15,9 @@ import { inProcessClient } from "@nifrajs/client"
 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 { describeProject, describeRouteGraph, describeRoutes } from "./introspect.ts"
 import { type LoadedApp, loadApp } from "./load.ts"
-import { chooseBuildPipeline } from "./pipeline-guard.ts"
+import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
 export interface Flags {
   readonly port: number
@@ -30,9 +30,8 @@ export interface Flags {
   /** `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 dev --bun`: force the Bun-pipeline dev server. Rarely needed - `dev` and `build` share one
+   * rule, so Bun is already the default unless `vitePlugins` are the app's ONLY transforms.
    *
    * `nifra build --bun`: force the Bun build. Refuses when that would drop the app's `vitePlugins`. */
   readonly bun: boolean
@@ -41,11 +40,14 @@ export interface Flags {
 const HELP = `nifra - zero-config dev/build/start for a nifra app
 
 Usage:
-  nifra dev     [--port <n>] [--poll]    Start the true-HMR dev server (Vite). Default port ${DEFAULT_DEV_PORT}.
-                [--bun]                  Run the BUN pipeline instead: Bun.serve native HMR (React Fast
-                                         Refresh included, state preserved), no Vite in the process - one
-                                         bundler across dev and prod. Plain CSS/Tailwind work; refuses an
-                                         app using *.module.css (Bun's dev bundler can't transform it).
+  nifra dev     [--port <n>] [--poll]    Start the true-HMR dev server (Bun). Default port ${DEFAULT_DEV_PORT}.
+                                         An app whose ONLY transforms are \`vitePlugins\` uses Vite (the
+                                         Bun pipeline cannot run them); everything else uses Bun.
+                [--vite]                 Force the Vite middleware/HMR pipeline.
+                [--bun]                  Force Bun.serve native HMR (React Fast Refresh included, state
+                                         preserved), no Vite in the process. CSS Modules, plain CSS,
+                                         Tailwind and the app's own \`clientPlugins\`/\`serverPlugins\` run
+                                         through the same Bun transforms production uses.
   nifra build   [--out <dir>] [--report]  Emit a complete deploy directory.
                 [--target <t>]             Target a FULL deploy dir for <t>:
                                          bun | node | deno | cf-pages | vercel | static. Packages
@@ -67,6 +69,8 @@ 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  --graph [--json]         Render the public route surface as a Mermaid graph, or as
+                                         stable JSON for contract explorers.
   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
@@ -105,6 +109,8 @@ Usage:
                                          request field or a removed response field breaks; widening a
                                          request enum or adding a response field doesn't) and fails
                                          closed. Exits non-zero on any breaking change - run it in CI.
+  nifra sdk     --lang <python|go> [--out <file>]
+                                         Generate a deterministic non-TypeScript SDK from backend.ts.
   nifra 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.
@@ -148,7 +154,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.9.1"
+const CLI_VERSION = "2.11.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
@@ -190,52 +196,26 @@ export function formatCliError(err: unknown): string {
   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> {
-  // Server functions and `*.server` modules are handled: the generated bunfig (dev-bun-config.ts)
-  // delivers the SAME serverFnStubPlugin/serverOnlyEmptyPlugin the production build uses to Bun's
-  // dev-server bundler via `[serve.static] plugins` - the one channel that bundler accepts plugins
-  // through (a runtime `Bun.plugin` never reaches it; programmatic ask: oven-sh/bun#36830). The old
-  // fail-closed refusal for those modules is gone because the leak it guarded is gone.
-  //
-  // CSS Modules remain gated: the `*.module.css` plugin rests on an `onResolve` virtual-module
-  // stylesheet emitter that is not yet verified under `[serve.static]`, and its failure mode is a
-  // broken client rather than a leak - refuse loudly until it is proven there.
-  const { Glob } = await import("bun")
-  const offenders: 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
+async function dev(app: LoadedApp, flags: Flags): Promise<void> {
+  if (flags.vite && flags.bun) {
+    throw new Error("[nifra] `nifra dev` takes `--vite` or `--bun`, not both.")
   }
-  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.",
+  // Default to Bun for the dev phase too. An app whose only transforms are Vite plugins stays on Vite so
+  // its transform is never silently dropped; `--vite`/`--bun` make that choice explicit.
+  // ONE rule for both phases - `chooseBuildPipeline` decides `dev` exactly as it decides `build`, so a
+  // project cannot end up bundled by one toolchain in dev and the other in production. An earlier
+  // version of this kept apps declaring `vitePlugins` on Vite for dev even when they also shipped Bun
+  // equivalents, on the theory that the framework plugins were the safer HMR path. Measurement killed
+  // it: Vue, Solid and Svelte all render correctly on the Bun pipeline, so the hedge bought nothing
+  // and cost an app the guarantee that dev and production bundle the same way. (Svelte used to render
+  // ONLY on Bun, which made the hedge actively harmful; it now renders on either - see the note at the
+  // Vite branch for what the adapter had to be given to make that true.)
+  const decision = chooseBuildPipeline(
+    app.resolvedPlugins,
+    flags.vite ? "vite" : flags.bun ? "bun" : undefined,
+    "dev",
   )
-}
-
-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)
+  if (decision.pipeline === "bun") {
     // Bun's dev-server bundler takes plugins only via bunfig `[serve.static]`, read at process
     // start - so the boundary plugins (server-fn stubs, server-only emptying) are delivered by
     // generating a config and re-execing this same command once with `--config=`. The child proves
@@ -255,15 +235,36 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
             "launches; refusing to serve without the client-boundary plugins.",
         )
       }
-      const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd)
+      const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd, app.configPath)
       const child = Bun.spawn(
-        [process.execPath, `--config=${bunfigPath}`, ...process.argv.slice(1)],
+        [
+          process.execPath,
+          `--config=${bunfigPath}`,
+          // The app's `conditions` reach SSR here or nowhere: bunfig has no key for them (a top-level,
+          // `[run]`, `[serve.static]` or `[bundle]` `conditions` is parsed and ignored), and the re-exec
+          // is the only point where this process's resolver is still configurable. Without it a package
+          // with an `exports` map resolves to a DIFFERENT file on the server than in the client bundle,
+          // which is the two-toolchains-one-module failure the pipeline guard exists to prevent.
+          //
+          // One flag per condition. `--conditions=a,b` is accepted and matches nothing: Bun takes the
+          // whole string as a single condition name, so the comma form fails silently.
+          ...(app.framework.conditions ?? []).map((condition) => `--conditions=${condition}`),
+          ...process.argv.slice(1),
+        ],
         {
           stdio: ["inherit", "inherit", "inherit"],
           env: {
             ...process.env,
             NIFRA_BUN_DEV_TOKEN: launchToken,
             NIFRA_BUN_DEV_DEPTH: String(depth + 1),
+            // The child is the process that renders, so it is the one that needs dev-shaped runtimes.
+            // A library ships its dev build behind the `development` export condition with a `NODE_ENV`
+            // fallback for resolvers that set no conditions - which is Bun's runtime, where SSR runs,
+            // so on the server that fallback is the only signal there is. It has to be in place before
+            // the app's config is read, because reading it imports the adapter and through it the
+            // framework runtime; setting it inside the dev server would already be a step too late.
+            // Preserved if the caller pinned one.
+            NODE_ENV: process.env.NODE_ENV ?? "development",
           },
         },
       )
@@ -272,6 +273,27 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
       process.on("SIGTERM", forward)
       process.exit(await child.exited)
     }
+    // SSR runs in THIS process, on Bun's runtime - a different loader from the dev-server bundler the
+    // bunfig above configures. Both halves have to agree, so the runtime gets the same transforms:
+    //
+    //   - CSS Modules. The scoped name is a pure function of file path + class name, so the `"ssr"` form
+    //     produces the identical map the client bundle emits (and no stylesheet - that ships from the
+    //     client build). Without it `styles.box` is `undefined` on the server: the SSR markup carries no
+    //     class, the page paints unstyled, and hydration then reports a className mismatch.
+    //   - the app's `serverPlugins` - the SSR counterpart of the `clientPlugins` the generated bunfig
+    //     delivers, exactly as `nifra build`'s prerender pass registers them.
+    //
+    // Registered BEFORE `createDevServer`, because a Bun runtime plugin only affects modules loaded
+    // after it - and `createApp` imports the route modules.
+    const { plugin } = await import("bun")
+    const { cssModulesBunPlugin } = await import("@nifrajs/web/plugins/css-modules")
+    plugin(cssModulesBunPlugin("ssr"))
+    for (const p of asBunPlugins(app.resolvedPlugins.serverPlugins)) plugin(p)
+    // "After" has one consequence an adapter has to respect. Reading the app's config is what PRODUCES
+    // these plugins, so the config's import graph - which includes the adapter - is already loaded when
+    // they register. An adapter must therefore not import an asset its own plugin compiles at module
+    // scope; it has to defer to first render, which happens after this point. `@nifrajs/web-svelte`
+    // loads its `Chain.svelte` that way for exactly this reason, and says so at the import.
     const { createDevServer } = await import("@nifrajs/web/dev")
     const { framework: fw, routesDir, outDir, backend } = app
     const server = await createDevServer({
@@ -279,8 +301,10 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
       outDir,
       clientModule: fw.clientModule,
       port: flags.port,
-      // The Bun pipeline's own plugins (SFC compilers etc.) - never `vitePlugins`, which belong to the
-      // other pipeline; `assertPipelineSeparation` already refuses a plugin sitting in the wrong slot.
+      // For the background client-leak guard, which re-runs `buildClient` on change - the SERVED client
+      // bundle gets these same plugins through the generated bunfig, since Bun's dev-server bundler takes
+      // plugins only as module paths. Never `vitePlugins`, which belong to the other pipeline;
+      // `assertPipelineSeparation` already refuses a plugin sitting in the wrong slot.
       plugins: asBunPlugins(app.resolvedPlugins.clientPlugins),
       ...(fw.publicDir !== undefined ? { publicDir: fw.publicDir } : {}),
       ...(fw.conditions ? { conditions: fw.conditions } : {}),
@@ -294,9 +318,10 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
         }),
     })
     console.log(`nifra dev (bun) → http://localhost:${server.port}`)
+    console.log(`  ${describePipeline(decision)}`)
     return
   }
-  // Preflight: `nifra dev` needs `vite` resolvable from the project. Run via `bunx @nifrajs/cli dev` the CLI
+  // Preflight: the Vite fallback needs `vite` resolvable from the project. Run via `bunx @nifrajs/cli dev` the CLI
   // sits in an isolated install where the project's peer deps don't resolve, so the vite import below fails
   // with an opaque ERR_MODULE_NOT_FOUND. Surface the real fix instead.
   try {
@@ -317,6 +342,18 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
   // same file in one process, with only one of them governed by Vite's `resolve.dedupe`. That is what
   // made an app's hand-written React alias fail to reach SSR, and it is the condition being removed -
   // not a redundancy worth keeping "just in case".
+  //
+  // Svelte is the case that proves the rule, and the discarded attempts are recorded so they are not
+  // retried. The adapter package stays `ssr.external` (its context must be the ONE instance the
+  // Bun-imported adapter provides), so BUN loads it - and `@nifrajs/web-svelte` renders through its own
+  // `Chain.svelte`, which needs a compiler that this pipeline does not put in the runtime. Registering
+  // the app's `serverPlugins` here, scoped to that package's directory, compiles it against a SECOND
+  // Svelte runtime and the first `setContext` dies (`context.function` null); externalizing the
+  // adapter's framework peer as well gets further and then dies on `context.function[FILENAME]`,
+  // because `svelteBunPlugin` and `vite-plugin-svelte` do not emit the same dev-mode component shape.
+  // Both attempts add a compiler. The fix removes one instead: `createViteDevServer` publishes its
+  // `ssrLoadModule` via `setSsrModuleLoader`, and the adapter loads `Chain.svelte` AND `svelte/server`
+  // through it - one toolchain, one runtime, context intact across the whole tree.
   const server = await createViteDevServer({
     root: cwd,
     routesDir,
@@ -339,7 +376,8 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
         ...apiOf(backend),
       }),
   })
-  console.log(`nifra dev → http://localhost:${server.port}`)
+  console.log(`nifra dev (vite) → http://localhost:${server.port}`)
+  console.log(`  ${describePipeline(decision)}`)
 }
 
 /**
@@ -407,10 +445,10 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
     // The static target needs a built app to drive prerendering - only build it when targeting static.
     ...(target === "static" ? { prerenderApp: await buildPrerenderApp(app) } : {}),
   })
-  console.log(`nifra build (${target}${useVite ? ", vite" : ""}) → ${result.run}`)
-  // An auto-selected pipeline is stated, never silent: the user asked for the default and got something
-  // else, and the reason is the thing that makes that legible instead of surprising.
-  if (decision.reason !== undefined) console.log(`  ${decision.reason}`)
+  console.log(`nifra build (${target}, ${decision.pipeline}) → ${result.run}`)
+  // The pipeline is stated on every build, not only the surprising ones - an auto-selected Vite build
+  // must never look like the default, and a default Bun build must not leave the question open either.
+  console.log(`  ${describePipeline(decision)}`)
   if (flags.report) console.log(`\n${renderSizeReport(result.size)}`)
 }
 
@@ -619,6 +657,30 @@ async function main(): Promise<void> {
     }
     return
   }
+  if (command === "sdk") {
+    const languageIndex = argv.indexOf("--lang")
+    const language = languageIndex === -1 ? undefined : argv[languageIndex + 1]
+    const outIndex = argv.indexOf("--out")
+    const out = outIndex === -1 ? undefined : argv[outIndex + 1]
+    if (language !== "python" && language !== "go") {
+      console.error("[nifra] sdk needs --lang python or --lang go")
+      process.exitCode = 1
+      return
+    }
+    if (outIndex !== -1 && (out === undefined || out.startsWith("-"))) {
+      console.error("[nifra] --out needs a file path")
+      process.exitCode = 1
+      return
+    }
+    try {
+      const { runSdk } = await import("./sdk.ts")
+      await runSdk(process.cwd(), { language, ...(out !== undefined ? { out } : {}) })
+    } catch (err) {
+      console.error(formatCliError(err))
+      process.exitCode = 1
+    }
+    return
+  }
   // Route assurance intentionally loads only its explicit config (which imports the backend it audits),
   // not the full SSR app. Like snapshot/diff, this works for API-only projects.
   if (command === "assure") {
@@ -823,7 +885,9 @@ async function main(): Promise<void> {
   else if (command === "build") await buildForTarget(app, flags.target, flags)
   else if (command === "context") console.log(describeProject(app))
   else if (command === "routes") {
-    if (argv.includes("--modes")) {
+    if (argv.includes("--graph")) {
+      console.log(await describeRouteGraph(app, { json: argv.includes("--json") }))
+    } else 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

package/src/dev-bun-config.ts

@@ -7,10 +7,15 @@
  * would ship to the browser WHOLE (body, DB handles, secrets) instead of as the RPC stub the
  * production client build emits, and a `*.server` module would ship instead of being emptied.
  *
+ * The same channel is the only way an app's OWN `clientPlugins` (SFC compilers and the like) can reach
+ * that bundler: the CLI holds them as plugin OBJECTS, and bunfig accepts only module paths - so the
+ * generated module re-imports the app's config and composes them in.
+ *
  * So the CLI generates, under `.nifra/dev-bun/`:
  *   - `boundary-plugin.ts` - default-exports one plugin composing the SAME `serverFnStubPlugin` +
- *     `serverOnlyEmptyPlugin` the production build uses (imported from `@nifrajs/web/build`, resolved
- *     from the app - identical stubs, not a re-implementation);
+ *     `serverOnlyEmptyPlugin` + CSS Modules transform the production build uses (imported from
+ *     `@nifrajs/web`, resolved from the app - identical transforms, not re-implementations), plus the
+ *     app's own `clientPlugins`;
  *   - `bunfig.toml` - the app's ENTIRE bunfig carried over verbatim (jsx, loaders, defines, install
  *     settings - dropping any of them would give dev a different Bun than the app configured), with
  *     `[serve.static] plugins` merged to put the boundary plugin first and path-bearing entries
@@ -34,7 +39,7 @@
  */
 import { timingSafeEqual } from "node:crypto"
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
-import { resolve } from "node:path"
+import { relative, resolve } from "node:path"
 
 /** TOML string literal: basic (double-quoted) form with the two escapes it needs. */
 function tomlString(value: string): string {
@@ -132,22 +137,56 @@ export function renderDevBunfig(
   )
 }
 
-/** The generated plugin module: compose the two production boundary plugins into one default
- * export. Import specifiers are bare so they resolve from the APP's install (the module lives
- * under the app's `.nifra/`), keeping dev stubs byte-identical to production's. */
-export function renderBoundaryPluginModule(): string {
-  return `// Generated by \`nifra dev --bun\` - do not edit. Regenerated on every dev start.
-import { serverFnStubPlugin, serverOnlyEmptyPlugin } from "@nifrajs/web/build"
+/** A TS/JS import specifier for `target` as seen from `fromDir`, always `./`-prefixed and posix-slashed
+ * so it reads as a FILE path to the module loader rather than a package name. */
+function relativeSpecifier(fromDir: string, target: string): string {
+  const rel = relative(fromDir, target).replaceAll("\\", "/")
+  return rel.startsWith(".") ? rel : `./${rel}`
+}
 
+/**
+ * The generated plugin module: compose the production boundary plugins, the production CSS Modules
+ * transform, and the APP's own `clientPlugins` into one default export.
+ *
+ * The `@nifrajs/*` specifiers are bare so they resolve from the APP's install (the module lives under
+ * the app's `.nifra/`), keeping dev transforms byte-identical to production's.
+ *
+ * `configPath` is the app's `nifra.config.ts` (or `framework.ts`). Importing it here is the only way an
+ * app's `clientPlugins` can reach Bun's dev-server bundler at all: that bundler takes plugins as module
+ * PATHS via bunfig, never as the plugin objects the CLI already holds in memory. Without this an app
+ * whose transforms live in `clientPlugins` had no working Bun dev loop - its client would be bundled
+ * with the transform silently missing. `setup` is async because `clientPlugins` may be a thunk.
+ */
+export function renderBoundaryPluginModule(configPath?: string, pluginDir?: string): string {
+  const appImport =
+    configPath !== undefined && pluginDir !== undefined
+      ? `import * as appConfig from ${tomlString(relativeSpecifier(pluginDir, configPath))}\n`
+      : ""
+  const appSetup =
+    appImport === ""
+      ? ""
+      : `    // The app's OWN client transforms (SFC compilers etc.). \`clientPlugins\` may be a thunk.
+    const field = appConfig.clientPlugins
+    const appPlugins = (typeof field === "function" ? await field() : field) ?? []
+    for (const p of appPlugins) await p.setup(build)
+`
+  return `// Generated by \`nifra dev\` (Bun pipeline) - do not edit. Regenerated on every dev start.
+import { serverFnStubPlugin, serverOnlyEmptyPlugin } from "@nifrajs/web/build"
+import { cssModulesBunPlugin } from "@nifrajs/web/plugins/css-modules"
+${appImport}
 const fn = serverFnStubPlugin()
 const serverOnly = serverOnlyEmptyPlugin()
+const cssModules = cssModulesBunPlugin("dom")
 
 export default {
   name: "nifra-dev-boundary",
-  setup(build) {
+  async setup(build) {
+    // Boundary first: an app plugin must never get to transform a module that the boundary is about to
+    // empty or stub, or the transform decides what ships instead of the boundary.
     serverOnly.setup(build)
     fn.setup(build)
-  },
+    cssModules.setup(build)
+${appSetup}  },
 }
 `
 }
@@ -161,12 +200,16 @@ export interface BunDevConfig {
 const TOKEN_FILE = "launch-token"
 
 /** Write the generated config for an app; returns the bunfig path to re-exec with and the fresh
- * launch token to pass in the child's environment. */
-export async function writeBunDevConfig(appRoot: string): Promise<BunDevConfig> {
+ * launch token to pass in the child's environment. `configPath` (the app's `nifra.config.ts` /
+ * `framework.ts`) is what lets the app's own `clientPlugins` reach Bun's dev-server bundler. */
+export async function writeBunDevConfig(
+  appRoot: string,
+  configPath?: string,
+): Promise<BunDevConfig> {
   const dir = resolve(appRoot, ".nifra", "dev-bun")
   mkdirSync(dir, { recursive: true })
   const pluginPath = resolve(dir, "boundary-plugin.ts")
-  writeFileSync(pluginPath, renderBoundaryPluginModule())
+  writeFileSync(pluginPath, renderBoundaryPluginModule(configPath, dir))
   const userToml = await Bun.file(resolve(appRoot, "bunfig.toml"))
     .text()
     .catch(() => undefined)