@nifrajs/cli 2.9.1 → 2.11.0

package/src/doctor.ts

@@ -21,6 +21,7 @@ import { readdir, realpath, stat } from "node:fs/promises"
 import { builtinModules } from "node:module"
 import { dirname, join, relative, sep } from "node:path"
 import { codePositionMask, type SourceFinding, stripComments, walkSource } from "./check.ts"
+import { collectPipelineReport, type PipelineReport } from "./pipeline-report.ts"
 
 // Runtime-provided modules that are never an npm dependency: Node core (bare + `node:` form) and Bun's
 // own `bun` module. `node:`/`bun:`-prefixed specifiers are filtered in packageOf by prefix.
@@ -135,6 +136,15 @@ export interface DoctorResult {
    * Advisory (never folded into `ok`): while actively editing a linked package its dist is always
    * momentarily behind - the finding matters when a dev server starts against it. */
   readonly staleDists: readonly StaleDistFinding[]
+  /**
+   * Which bundler this app's `dev`/`build` phases run on, read statically, plus the config hazards
+   * that exist only because there are two. Absent when the directory is not a nifra app.
+   *
+   * Reported by doctor rather than only by `dev`/`build` because the answer governs how the rest of a
+   * project is read - which plugin slot is live, whether `conditions` reach the client bundle, which
+   * toolchain compiles a component - and asking for it should not require starting a server.
+   */
+  readonly pipeline?: PipelineReport
   /** Dependencies written by `--auto-fix` / MCP `autoFix:true`. */
   readonly fixed?: readonly DoctorAppliedFix[]
   /** Findings that were safe to report but not safe to write automatically. */
@@ -701,13 +711,16 @@ export async function collectDoctorResult(cwd: string): Promise<DoctorResult> {
   findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
   const duplicateInstalls = await collectDuplicateInstalls(cwd, pkg)
   const staleDists = await collectStaleWorkspaceDists(cwd, pkg)
+  const pipeline = await collectPipelineReport(cwd)
+  const pipelineErrors = pipeline.findings.filter((f) => f.severity === "error")
   // `staleDists` is advisory (see DoctorResult): it never fails `ok`.
   return {
-    ok: findings.length === 0 && duplicateInstalls.length === 0,
+    ok: findings.length === 0 && duplicateInstalls.length === 0 && pipelineErrors.length === 0,
     ran: true,
     findings,
     duplicateInstalls,
     staleDists,
+    ...(pipeline.ran ? { pipeline } : {}),
   }
 }
 
@@ -811,6 +824,20 @@ export async function runDoctor(
     }
     console.log("")
   }
+  // Printed before the findings and regardless of ok: which bundler owns this app is the frame the
+  // rest of the report is read in, not a footnote to it.
+  if (result.pipeline !== undefined) {
+    const p = result.pipeline
+    console.log(
+      p.pipeline === "unknown"
+        ? `• bundler: could not be read from ${p.configFile} - ${p.reason}\n`
+        : `• bundler: ${p.pipeline} (${p.reason})\n`,
+    )
+    for (const f of p.findings) {
+      console.log(`${f.severity === "error" ? "✗" : "⚠"} ${f.file}:${f.line ?? 0}  ${f.message}`)
+      console.log(`      fix: ${f.fix}\n`)
+    }
+  }
   // Advisory, printed regardless of ok: a stale linked dist doesn't fail doctor, but silently eating
   // it costs an hour of misdiagnosis when the dev server 500s inside the package.
   if (result.staleDists.length > 0) {

package/src/introspect.ts

@@ -9,6 +9,7 @@ import { type ReflectedRoute, reflectRoutes, type SchemaReflection } from "@nifr
 import type { Manifest } from "@nifrajs/web"
 import { discoverRoutes } from "@nifrajs/web/fs"
 import type { LoadedApp } from "./load.ts"
+import { chooseBuildPipeline, describePipeline } from "./pipeline-guard.ts"
 
 /** Read the backend's registered routes, if it's a `server()` with a `.routes()` method. */
 export function backendRoutes(backend: unknown): ReflectedRoute[] {
@@ -232,6 +233,11 @@ export function describeProject(app: LoadedApp, filter?: ContextFilter): string
       // Point agents at the verified surface, not recalled APIs - nifra is young, so training data is the
       // wrong source. The MCP tools (nifra_docs / nifra_example) are checked against the installed version.
       "> **Build against THIS surface + the verified tools - do not write nifra APIs from memory** (the\n> framework is young; recalled APIs drift). For framework code, call `nifra_example` (snippets\n> typechecked against the installed version) or `nifra_docs`; verify edits with `nifra_run` + `nifra_check`.",
+      // The authoritative answer, not the static reading `nifra_check`/`nifra_doctor` give: this runs on
+      // the LOADED config, so it is the same decision `nifra dev` and `nifra build` make. Stated in the
+      // index because it governs where a plugin goes and which toolchain compiles a component - an edit
+      // put in the other pipeline's slot is accepted and then silently never runs.
+      `**Bundler**: ${describePipeline(chooseBuildPipeline(app.resolvedPlugins))}. \`vitePlugins\` feed Vite; \`clientPlugins\`/\`serverPlugins\` feed Bun.build. Both phases (dev and build) use the same one.`,
     )
   }
   if (filter?.kind !== "pages") {
@@ -430,6 +436,106 @@ export function routeTableToJson(rows: readonly RouteTableEntry[]): {
   }
 }
 
+export interface RouteGraphNode {
+  readonly id: string
+  readonly kind: "root" | RouteKind
+  readonly path: string
+  readonly methods?: readonly string[]
+  readonly file?: string
+  readonly autoMounted?: boolean
+}
+
+export interface RouteGraphEdge {
+  readonly from: string
+  readonly to: string
+}
+
+export interface RouteGraph {
+  readonly nodes: readonly RouteGraphNode[]
+  readonly edges: readonly RouteGraphEdge[]
+}
+
+function parentPath(path: string): string | undefined {
+  if (path === "/") return undefined
+  const trimmed = path.replace(/\/$/, "")
+  const slash = trimmed.lastIndexOf("/")
+  return slash <= 0 ? "/" : trimmed.slice(0, slash)
+}
+
+/** Build a stable parent/child graph from the public route table. Pure and topology-neutral. */
+export function buildRouteGraph(rows: readonly RouteTableEntry[]): RouteGraph {
+  const sorted = [...rows].sort(
+    (a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind),
+  )
+  const nodes: RouteGraphNode[] = [
+    { id: "root", kind: "root", path: "/" },
+    ...sorted.map((row) => ({
+      id: `${row.kind}:${row.path}`,
+      kind: row.kind,
+      path: row.path,
+      methods: row.methods,
+      ...(row.file === undefined ? {} : { file: row.file }),
+      ...(row.kind === "api" ? { autoMounted: row.autoMounted === true } : {}),
+    })),
+  ]
+  const nodeIds = new Set(nodes.map((node) => node.id))
+  const edges: RouteGraphEdge[] = []
+  for (const row of sorted) {
+    let parent = parentPath(row.path)
+    let from = "root"
+    while (parent !== undefined) {
+      const candidate = `${row.kind}:${parent}`
+      if (nodeIds.has(candidate)) {
+        from = candidate
+        break
+      }
+      parent = parentPath(parent)
+    }
+    edges.push({ from, to: `${row.kind}:${row.path}` })
+  }
+  return { nodes, edges }
+}
+
+/** Stable JSON shape for agents and contract explorers. */
+export function routeGraphToJson(graph: RouteGraph): RouteGraph {
+  return {
+    nodes: graph.nodes.map((node) => ({
+      ...node,
+      ...(node.methods === undefined ? {} : { methods: [...node.methods] }),
+    })),
+    edges: graph.edges.map((edge) => ({ ...edge })),
+  }
+}
+
+function mermaidText(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll(/[\r\n]/g, " ")
+}
+
+function mermaidLabel(node: RouteGraphNode): string {
+  if (node.kind === "root") return "routes"
+  const methods = node.methods?.join(", ") ?? ""
+  const mounted = node.autoMounted === true ? " (auto-mounted)" : ""
+  return mermaidText(`${node.kind}: ${methods} ${node.path}${mounted}`)
+}
+
+/** Render a route graph as Mermaid for terminals, docs, and agent-facing previews. */
+export function renderRouteGraph(graph: RouteGraph): string {
+  const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]))
+  const lines = ["flowchart TD"]
+  for (const node of graph.nodes) {
+    lines.push(`  ${ids.get(node.id)}["${mermaidLabel(node)}"]`)
+  }
+  for (const edge of graph.edges) {
+    lines.push(`  ${ids.get(edge.from)} --> ${ids.get(edge.to)}`)
+  }
+  return lines.join("\n")
+}
+
 /** A route module that may export an `action` (→ the page serves POST). */
 interface MaybeActionModule {
   readonly action?: unknown
@@ -441,10 +547,7 @@ interface MaybeActionModule {
  * text (default) or JSON (`--json`). The page-route load mirrors what SSR would do; a load failure
  * degrades to GET-only for that route (never throws the whole command).
  */
-export async function describeRoutes(
-  app: LoadedApp,
-  opts: { readonly json?: boolean } = {},
-): Promise<string> {
+async function collectRouteTable(app: LoadedApp): Promise<RouteTableEntry[]> {
   let manifest: Manifest | undefined
   try {
     manifest = discoverRoutes(app.routesDir)
@@ -463,5 +566,22 @@ export async function describeRoutes(
     pages.push({ pattern: route.pattern, file: route.file, hasAction })
   }
   const rows = buildRouteTable({ pages, api: backendRoutes(app.backend) })
+  return rows
+}
+
+export async function describeRoutes(
+  app: LoadedApp,
+  opts: { readonly json?: boolean } = {},
+): Promise<string> {
+  const rows = await collectRouteTable(app)
   return opts.json ? JSON.stringify(routeTableToJson(rows), null, 2) : renderRouteTable(rows)
 }
+
+/** Gather and render the public route graph for `nifra routes --graph`. */
+export async function describeRouteGraph(
+  app: LoadedApp,
+  opts: { readonly json?: boolean } = {},
+): Promise<string> {
+  const graph = buildRouteGraph(await collectRouteTable(app))
+  return opts.json ? JSON.stringify(routeGraphToJson(graph), null, 2) : renderRouteGraph(graph)
+}

package/src/load.ts

@@ -93,6 +93,10 @@ export interface ResolvedPlugins {
 
 export interface LoadedApp {
   readonly cwd: string
+  /** Absolute path of the config this app was loaded from - `nifra.config.ts`, or `framework.ts` as the
+   * fallback. `nifra dev`'s Bun pipeline re-imports it from a GENERATED module so the app's own
+   * `clientPlugins` reach Bun's dev-server bundler, which takes plugins only as module paths. */
+  readonly configPath: string
   readonly routesDir: string
   /** Build output dir (also where `nifra start` reads `manifest.json` + serves `/assets/*`). */
   readonly outDir: string
@@ -222,6 +226,7 @@ export async function loadApp(
 
   return {
     cwd,
+    configPath,
     routesDir: resolve(cwd, "routes"),
     outDir: resolve(cwd, outDirName),
     framework: { ...fw, clientModule } as NifraFramework,

package/src/mcp-http.ts

@@ -29,7 +29,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "2.9.1"
+const VERSION = "2.11.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>

package/src/mcp.ts

@@ -1124,7 +1124,7 @@ export function projectTools(
     {
       name: "nifra_check",
       description:
-        'Run the project\'s drift gate and return a structured result { ok, typecheck, diagnostics[] }: typecheck (the frontend↔backend contract), plus lints for hand-rolled fetch() to your own API, untyped client("…") calls missing <typeof app>, and server-only imports in routes/. Pass lintsOnly:true for a near-instant lint pass while iterating; run the full gate (default) to confirm the work is done - fix every diagnostic before finishing.',
+        'Run the project\'s drift gate and return a structured result { ok, typecheck, diagnostics[], pipeline? }: typecheck (the frontend↔backend contract), plus lints for hand-rolled fetch() to your own API, untyped client("…") calls missing <typeof app>, and server-only imports in routes/. `pipeline` answers "which bundler does this app run on" (bun|vite, for dev AND build alike) without starting a server, and its `pipeline` diagnostics catch the hazards of having two: a plugin in the slot the other bundler reads (accepted, then never called), a dev toolchain imported by the file `nifra build` bundles into the production server, and `conditions` that cannot reach Bun\'s dev client bundle. Read it before adding a plugin or a compiler. Pass lintsOnly:true for a near-instant lint pass while iterating; run the full gate (default) to confirm the work is done - fix every diagnostic before finishing.',
       inputSchema: {
         type: "object",
         properties: {
@@ -1323,7 +1323,7 @@ export function projectTools(
     {
       name: "nifra_doctor",
       description:
-        "Check this project for packages imported in source but NOT declared in package.json - the Bun-workspace trap where an import resolves at runtime (hoisting/workspace) so tests pass and `bun install` says no changes, yet tsc fails and a fresh/standalone install can't resolve it. Returns { ok, ran, findings[], fixed?, skippedFixes? }. Pass autoFix:true to update package.json only when the dependency version can be inferred locally from an ancestor package.json or installed package metadata; otherwise the tool returns the exact bun add command to run.",
+        "Check this project for packages imported in source but NOT declared in package.json - the Bun-workspace trap where an import resolves at runtime (hoisting/workspace) so tests pass and `bun install` says no changes, yet tsc fails and a fresh/standalone install can't resolve it. Also reports `pipeline`: which bundler (bun|vite) this app's dev AND build phases run on and why, plus config hazards that only exist because there are two - a plugin sitting in the slot the other bundler reads (accepted, then never called), a dev toolchain imported by the file `nifra build` bundles into the production server (builds clean, dies at startup), and `conditions` that cannot reach the client bundle Bun's dev server serves. Returns { ok, ran, findings[], pipeline?, fixed?, skippedFixes? }. Pass autoFix:true to update package.json only when the dependency version can be inferred locally from an ancestor package.json or installed package metadata; otherwise the tool returns the exact bun add command to run.",
       inputSchema: {
         type: "object",
         properties: {

package/src/pipeline-guard.ts

@@ -116,6 +116,13 @@ export type BuildPipeline = "bun" | "vite"
 
 export interface PipelineDecision {
   readonly pipeline: BuildPipeline
+  /**
+   * How the pipeline was arrived at. Always set, because "which bundler am I on" is a question every
+   * `dev`/`build` run should answer without the user reading this source: `default` is the plain Bun
+   * default, `auto` means the config forced nifra's hand (see {@link reason}), `forced` is `--vite` /
+   * `--bun`.
+   */
+  readonly why: "default" | "auto" | "forced"
   /**
    * Why this pipeline, for the `nifra build` log line - so an auto-selected Vite build never looks
    * like the user got the default. `undefined` when the choice was the plain default or was forced.
@@ -139,16 +146,14 @@ const pluginNames = (plugins: readonly unknown[]): string =>
     .join(", ")
 
 /**
- * Pick the bundler for `nifra build`, per app rather than per global default.
+ * Pick the bundler for `nifra build` and `nifra dev`, per app rather than per global default.
  *
- * The phase defaults are deliberately asymmetric - `nifra dev` is Vite (for the plugin ecosystem, and
- * because Bun's DEV-server bundler cannot compile CSS Modules), `nifra build` is Bun (faster and
- * Bun-native). For an app with no transforms that asymmetry is free: there is nothing to disagree about.
- * For an app whose ONLY transforms are Vite plugins it is not. Those plugins run in dev and are then
- * dropped by the Bun build - `buildForTarget` reads `clientPlugins`/`serverPlugins`, never `vitePlugins`
- * - so the build succeeds, the output looks plausible, and the transform simply did not happen. That is
- * the same failure {@link checkPipelineSeparation} exists to prevent, reached by crossing PHASES instead
- * of slots, and the slot check cannot see it because the plugins are correctly placed.
+ * The phase defaults are Bun (faster and Bun-native). For an app with no transforms that is direct and
+ * predictable. For an app whose ONLY transforms are Vite plugins it is not: those plugins are required in
+ * both dev and production, while the Bun build reads `clientPlugins`/`serverPlugins`, never `vitePlugins`.
+ * Selecting Bun would make the build succeed with the transform omitted. That is the same failure
+ * {@link checkPipelineSeparation} exists to prevent, reached by crossing PHASES instead of slots, and the
+ * slot check cannot see it because the plugins are correctly placed.
  *
  * So the default follows the app: Vite plugins with no Bun counterpart means the app has exactly one
  * pipeline that can build it, and that is the one used. An app declaring BOTH has supplied the Bun
@@ -161,26 +166,51 @@ const pluginNames = (plugins: readonly unknown[]): string =>
 export function chooseBuildPipeline(
   slots: PipelineSlots,
   forced?: BuildPipeline,
+  command: "build" | "dev" = "build",
 ): PipelineDecision {
   const vitePlugins = slots.vitePlugins ?? []
   const bunPlugins = [...(slots.clientPlugins ?? []), ...(slots.serverPlugins ?? [])]
   const viteOnly = vitePlugins.length > 0 && bunPlugins.length === 0
 
   if (forced === "bun" && viteOnly) {
+    // Named for the command the user actually typed - a `nifra dev --bun` failure that talks about
+    // `nifra build` sends them looking at the wrong command.
+    const phase = command === "dev" ? "dev server" : "build"
     throw new Error(
-      "[nifra] `nifra build --bun` would silently drop this app's only transforms. `vitePlugins` are " +
-        "read by the Vite build; the Bun build reads `clientPlugins`/`serverPlugins`, so these would " +
+      `[nifra] \`nifra ${command} --bun\` would silently drop this app's only transforms. \`vitePlugins\` are ` +
+        `read by the Vite ${phase}; the Bun ${phase} reads \`clientPlugins\`/\`serverPlugins\`, so these would ` +
         "never run and the output would look plausible without them.\n" +
         `  Would be dropped: ${pluginNames(vitePlugins)}\n` +
-        "  Drop the flag to build with Vite, or add the Bun equivalents to `clientPlugins`/`serverPlugins`.",
+        `  Drop the flag to use Vite, or add the Bun equivalents to \`clientPlugins\`/\`serverPlugins\`.`,
     )
   }
-  if (forced !== undefined) return { pipeline: forced }
+  if (forced !== undefined) return { pipeline: forced, why: "forced" }
   if (viteOnly) {
     return {
       pipeline: "vite",
+      why: "auto",
       reason: `auto: this app's only transforms are \`vitePlugins\` (${pluginNames(vitePlugins)}), which the Bun build cannot run`,
     }
   }
-  return { pipeline: "bun" }
+  return { pipeline: "bun", why: "default" }
+}
+
+/**
+ * The one-line "which bundler, and why" note `nifra dev` and `nifra build` print under their banner.
+ *
+ * Printed on EVERY run, not only the surprising ones. A pipeline that announces itself only when it
+ * deviates teaches nobody which pipeline they are normally on, and every gotcha in the dev docs -
+ * plugin slots, resolve conditions, which compiler owns a `.svelte` file - is answerable only once you
+ * know that. The line also names the flag that switches, so the answer to "can I try the other one"
+ * is on screen rather than in the docs.
+ */
+export function describePipeline(decision: PipelineDecision): string {
+  const other = decision.pipeline === "bun" ? "--vite" : "--bun"
+  const detail =
+    decision.why === "forced"
+      ? `forced by --${decision.pipeline}`
+      : decision.why === "auto"
+        ? (decision.reason ?? "auto")
+        : `default; ${other} to switch`
+  return `bundler: ${decision.pipeline} (${detail})`
 }