@nifrajs/cli 2.2.0 → 2.3.0

package/src/cli.ts

@@ -1,18 +1,24 @@
 #!/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"
@@ -30,15 +36,15 @@ 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
+  /** `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}.
@@ -84,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;
@@ -92,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.
@@ -141,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.2.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
@@ -149,20 +158,54 @@ 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
+ * `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> {
+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 })) {
@@ -170,6 +213,58 @@ async function assertBunDevSupportsApp(app: LoadedApp): Promise<void> {
     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` " +
@@ -181,7 +276,7 @@ async function assertBunDevSupportsApp(app: LoadedApp): Promise<void> {
 }
 
 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`: 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) {
@@ -193,7 +288,7 @@ 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
+      // 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 } : {}),
@@ -237,6 +332,7 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
     clientModule: fw.clientModule,
     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 } : {}),
@@ -256,9 +352,9 @@ 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/`.
  */
@@ -278,7 +374,7 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
     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
+  // 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
@@ -317,7 +413,7 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
     ...(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.
+    // 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}`)
@@ -330,7 +426,7 @@ async function buildForTarget(app: LoadedApp, target: string, flags: Flags): Pro
 /** 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(
@@ -371,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)
@@ -416,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")
@@ -436,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")
@@ -468,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")
@@ -481,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")
@@ -495,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
@@ -508,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
@@ -533,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
@@ -574,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
@@ -616,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
@@ -647,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")
@@ -668,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")
@@ -693,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
@@ -748,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
   })
 }

package/src/diff-tool.ts

@@ -1,5 +1,5 @@
 /**
- * `nifra snapshot` / `nifra diff` — the API breaking-change gate.
+ * `nifra snapshot` / `nifra diff` - the API breaking-change gate.
  *
  *   nifra snapshot [--out api-snapshot.json]   Write the backend's route contract as plain JSON.
  *   nifra diff <baseline.json> [--json]        Re-snapshot and compare against the committed
@@ -10,7 +10,7 @@
  * before it ships. Classification lives in `@nifrajs/core/diff` (direction-aware, fails closed);
  * this module only loads `backend.ts` and renders the result.
  *
- * Loads ONLY `backend.ts` — the API contract — so it works on an API-only project with no
+ * Loads ONLY `backend.ts` - the API contract - so it works on an API-only project with no
  * framework config or routes/ directory (unlike the eager `loadApp`).
  */
 
@@ -24,7 +24,7 @@ import {
   snapshotRoutes,
 } from "@nifrajs/core/diff"
 
-/** Snapshot file envelope — versioned so a future format change can migrate instead of misparse. */
+/** Snapshot file envelope - versioned so a future format change can migrate instead of misparse. */
 export interface SnapshotFile {
   readonly nifraSnapshot: 1
   readonly routes: readonly RouteSnapshot[]
@@ -39,7 +39,7 @@ export function parseSnapshotFile(content: string, sourcePath: string): Snapshot
     parsed = JSON.parse(content)
   } catch {
     throw new Error(
-      `[nifra] ${sourcePath} is not valid JSON — regenerate it with \`nifra snapshot\`.`,
+      `[nifra] ${sourcePath} is not valid JSON - regenerate it with \`nifra snapshot\`.`,
     )
   }
   const record = parsed as Partial<SnapshotFile> | null
@@ -50,7 +50,7 @@ export function parseSnapshotFile(content: string, sourcePath: string): Snapshot
     !Array.isArray(record.routes)
   ) {
     throw new Error(
-      `[nifra] ${sourcePath} is not a nifra API snapshot — expected { "nifraSnapshot": 1, "routes": [...] }.`,
+      `[nifra] ${sourcePath} is not a nifra API snapshot - expected { "nifraSnapshot": 1, "routes": [...] }.`,
     )
   }
   return record as SnapshotFile
@@ -76,7 +76,7 @@ export function formatDiff(diff: RoutesDiff): string {
     .map(describeChange)
   const breaking = diff.changes.filter((change) => change.severity === "breaking").length
   const summary = diff.hasBreaking
-    ? `${breaking} breaking change${breaking === 1 ? "" : "s"} — existing clients will fail.`
+    ? `${breaking} breaking change${breaking === 1 ? "" : "s"} - existing clients will fail.`
     : "No breaking changes."
   return `${lines.join("\n")}\n\n${summary}`
 }
@@ -86,7 +86,7 @@ async function snapshotBackend(cwd: string): Promise<readonly RouteSnapshot[]> {
   const backendPath = resolve(cwd, "backend.ts")
   if (!existsSync(backendPath)) {
     throw new Error(
-      `[nifra] no backend.ts in ${cwd} — \`nifra snapshot\`/\`nifra diff\` compare the API contract, which lives in backend.ts.`,
+      `[nifra] no backend.ts in ${cwd} - \`nifra snapshot\`/\`nifra diff\` compare the API contract, which lives in backend.ts.`,
     )
   }
   const backend = ((await import(backendPath)) as { backend?: unknown }).backend
@@ -115,7 +115,7 @@ export async function runDiff(
   const baselineFile = Bun.file(resolved)
   if (!(await baselineFile.exists())) {
     throw new Error(
-      `[nifra] baseline not found: ${resolved} — create it on your main branch with \`nifra snapshot\`.`,
+      `[nifra] baseline not found: ${resolved} - create it on your main branch with \`nifra snapshot\`.`,
     )
   }
   const baseline = parseSnapshotFile(await baselineFile.text(), baselinePath)

package/src/docs-search.ts

@@ -1,8 +1,8 @@
 /**
- * `nifra_docs` — searchable framework documentation for agents. The corpus is the generated
+ * `nifra_docs` - searchable framework documentation for agents. The corpus is the generated
  * `llms-full.txt` (written into this package by `bun run gen:llms`, so it can't drift from the
  * source it's generated from). Instead of dumping the whole ~150 KB into an agent's context, the
- * tool keyword-scores the document's `##` sections and returns only the top matches — or, with no
+ * tool keyword-scores the document's `##` sections and returns only the top matches - or, with no
  * query, just the section index (the cheap discovery call).
  *
  * Deliberately NOT a vector search: the corpus is one curated document with descriptive headings;
@@ -68,7 +68,7 @@ export function searchSections(
   return scored.sort((a, b) => b.score - a.score).slice(0, limit)
 }
 
-/** Cap a section body for the tool result — whole sections can be pages long; the agent can ask
+/** Cap a section body for the tool result - whole sections can be pages long; the agent can ask
  * again with a narrower query if the trim cuts what it needed. */
 const MAX_SECTION_CHARS = 2800
 
@@ -81,7 +81,7 @@ export function renderDocsResult(
   const sections = splitSections(markdown)
   if (query === undefined || query.trim() === "") {
     const index = sections.map((s) => `- ${s.heading}`).join("\n")
-    return `# nifra docs — section index (pass \`query\` to fetch matching sections)\n\n${index}`
+    return `# nifra docs - section index (pass \`query\` to fetch matching sections)\n\n${index}`
   }
   const matches = searchSections(sections, query, limit)
   if (matches.length === 0) {
@@ -91,7 +91,7 @@ export function renderDocsResult(
     .map((m) => {
       const body =
         m.body.length > MAX_SECTION_CHARS
-          ? `${m.body.slice(0, MAX_SECTION_CHARS)}\n…(trimmed — narrow the query for the rest)`
+          ? `${m.body.slice(0, MAX_SECTION_CHARS)}\n…(trimmed - narrow the query for the rest)`
           : m.body
       return `## ${m.heading}\n\n${body}`
     })
@@ -99,7 +99,7 @@ export function renderDocsResult(
 }
 
 /** Load the bundled corpus. Resolves relative to this module so it works from `src/` (repo dev)
- * and `dist/` (published) alike — `docs/llms-full.txt` sits at the package root next to both. */
+ * and `dist/` (published) alike - `docs/llms-full.txt` sits at the package root next to both. */
 export async function loadDocsCorpus(): Promise<string | undefined> {
   const url = new URL("../docs/llms-full.txt", import.meta.url)
   try {

package/src/doctor.ts

@@ -1,14 +1,14 @@
 /**
- * `nifra doctor` — catches the Bun-workspace footgun the typed-client lint can't: a package that's
+ * `nifra doctor` - catches the Bun-workspace footgun the typed-client lint can't: a package that's
  * IMPORTED in source but NOT declared in `package.json`. Bun resolves it at runtime (via hoisting or a
- * workspace), so tests pass and `bun install` reports "no changes" — false confidence — yet `tsc` fails
+ * workspace), so tests pass and `bun install` reports "no changes" - false confidence - yet `tsc` fails
  * and a fresh or standalone install can't resolve it. doctor diffs every bare import specifier against
  * the package's declared dependencies and flags the gap, with a stable `--json` shape for agents/CI.
  *
  * Scope is intentionally per-package: it checks the `package.json` at `cwd`, because a dependency must be
  * declared by the package that imports it (for `tsc` and for that package to install on its own) even
  * 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.
+ * the package's own name, and tsconfig `paths` aliases are excluded - none of them are npm deps.
  */
 import { realpath, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
@@ -25,7 +25,7 @@ const BUILTINS: ReadonlySet<string> = new Set<string>([
 
 // The four specifier-bearing forms: static import/re-export with a source, side-effect import, dynamic
 // import, and CJS require. Anchored with `(?<![.\w$])` so `myimport`/`.import`/`foorequire` never match.
-// Comments are stripped before these run (see stripComments) — else a doc-comment usage example would be
+// Comments are stripped before these run (see stripComments) - else a doc-comment usage example would be
 // flagged as a real import.
 const IMPORT_PATTERNS: readonly RegExp[] = [
   /(?<![.\w$])(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g,
@@ -56,7 +56,7 @@ export function packageOf(spec: string): string | undefined {
   if (spec.startsWith("node:") || spec.startsWith("bun:")) return undefined
   if (spec.startsWith("@")) {
     const [scope, name] = spec.split("/")
-    if (!scope || scope === "@" || !name) return undefined // `@/alias`, `@foo` — not a real package
+    if (!scope || scope === "@" || !name) return undefined // `@/alias`, `@foo` - not a real package
     const pkg = `${scope}/${name}`
     return isNpmPackageName(pkg) ? pkg : undefined
   }
@@ -66,7 +66,7 @@ export function packageOf(spec: string): string | undefined {
 }
 
 /** Build a predicate matching tsconfig `paths` aliases (e.g. `@/*`, `~/utils`), which resolve to local
- * source, not npm packages — so doctor must not flag them. */
+ * source, not npm packages - so doctor must not flag them. */
 export function aliasMatcher(
   paths: Readonly<Record<string, unknown>> | undefined,
 ): (spec: string) => boolean {
@@ -113,13 +113,13 @@ export function scanUndeclaredImports(
 export interface DoctorFinding {
   readonly file: string
   readonly line: number
-  /** The undeclared package name — add it to `package.json` dependencies. */
+  /** The undeclared package name - add it to `package.json` dependencies. */
   readonly package: string
 }
 
 export interface DoctorResult {
   readonly ok: boolean
-  /** `false` when no `package.json` was found at cwd — doctor can't run (reported, not a crash). */
+  /** `false` when no `package.json` was found at cwd - doctor can't run (reported, not a crash). */
   readonly ran: boolean
   readonly findings: readonly DoctorFinding[]
   /** Packages that resolve to more than one physical install across this workspace. */
@@ -622,7 +622,7 @@ export async function runDoctor(
   }
   console.log("nifra doctor\n")
   if (!result.ran) {
-    console.log("• no package.json at this directory — nothing to check")
+    console.log("• no package.json at this directory - nothing to check")
     return true
   }
   if (result.fixed && result.fixed.length > 0) {
@@ -635,7 +635,7 @@ export async function runDoctor(
   if (result.skippedFixes && result.skippedFixes.length > 0) {
     console.log("• not auto-fixed:")
     for (const f of result.skippedFixes) {
-      console.log(`  ${f.package} — ${f.reason}; run \`${f.command.join(" ")}\``)
+      console.log(`  ${f.package} - ${f.reason}; run \`${f.command.join(" ")}\``)
     }
     console.log("")
   }

package/src/examples.ts

@@ -1,8 +1,8 @@
 /**
- * `nifra_example` — verified, copy-pasteable code examples for agents. The corpus is `examples.json`
+ * `nifra_example` - verified, copy-pasteable code examples for agents. The corpus is `examples.json`
  * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks
  * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the
- * installed version — the antidote to an agent hallucinating a framework API from stale training.
+ * installed version - the antidote to an agent hallucinating a framework API from stale training.
  *
  * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its
  * code body. No query → a grouped index of what's available (the cheap discovery call).
@@ -12,9 +12,9 @@ import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-
 
 export interface Example {
   readonly name: string
-  /** The doc page's title, e.g. "Nifra — Auth & sessions". */
+  /** The doc page's title, e.g. "Nifra - Auth & sessions". */
   readonly topic: string
-  /** The doc page slug, e.g. "auth" — a short, matchable tag. */
+  /** The doc page slug, e.g. "auth" - a short, matchable tag. */
   readonly slug: string
   readonly code: string
 }
@@ -63,19 +63,19 @@ export function renderExamplesResult(
     const index = [...byTopic.entries()]
       .map(([topic, names]) => `- **${topic}**: ${names.join(", ")}`)
       .join("\n")
-    return `# nifra examples — index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version — prefer these over recalling an API.\n\n${index}`
+    return `# nifra examples - index (${examples.length} verified snippets; pass \`query\` to fetch code)\n\nEvery snippet is typechecked against the installed nifra version - prefer these over recalling an API.\n\n${index}`
   }
   const matches = searchExamples(examples, query, limit)
   if (matches.length === 0) {
     return `No examples matched ${JSON.stringify(query)}. Call without a query for the index, or try a broader term (e.g. "auth", "upload", "isr", "client").`
   }
   return matches
-    .map((m) => `## ${m.name} — ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
+    .map((m) => `## ${m.name} - ${m.topic}\n\n\`\`\`ts\n${m.code}\n\`\`\``)
     .join("\n\n---\n\n")
 }
 
 /** Load the bundled example corpus. Resolves relative to this module so it works from `src/` (repo dev)
- * and `dist/` (published) alike — `docs/examples.json` sits at the package root next to both. */
+ * and `dist/` (published) alike - `docs/examples.json` sits at the package root next to both. */
 export async function loadExamplesCorpus(): Promise<Example[] | undefined> {
   const url = new URL("../docs/examples.json", import.meta.url)
   try {