@nifrajs/cli 2.0.0 → 2.2.0

package/src/load.ts

@@ -14,6 +14,7 @@
  */
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
+import { checkPipelineSeparation } from "./pipeline-guard.ts"
 
 /**
  * A plugin list — either an array, or a **thunk** that returns one (optionally async). Both forms are
@@ -49,6 +50,33 @@ export interface NifraFramework {
   readonly conditions?: readonly string[]
   /** Compile-time `define` replacements, e.g. Vue's `__VUE_*` flags. */
   readonly define?: Readonly<Record<string, string>>
+  /** Static files directory. Defaults to `<app>/public`; `false` disables it. */
+  readonly publicDir?: string | false
+  /** Client-visible environment prefix (default `"PUBLIC_"`; empty disables exposure). */
+  readonly publicEnvPrefix?: string
+}
+
+/**
+ * Refuse a config that puts one pipeline's plugins into the other's slot.
+ *
+ * Checked here rather than in `nifra check`, which holds a deliberate pre-`loadApp` invariant - reading
+ * plugins means importing the app's config, which is code execution. This runs at the moment the app
+ * IS loaded, so `dev`, `build` and `start` are all covered from one place, immediately before the
+ * plugins are handed to a bundler.
+ *
+ * Throws rather than warns. A misplaced plugin does not fail the build: Bun.build has no `transform`
+ * hook and Vite never calls `setup`, so the wrong-slot plugin is accepted and silently never invoked -
+ * the transform just does not happen, and the output looks plausible. A loud stop with the exact move
+ * is strictly better than a build that succeeds and omits the work. The classifier only fires on a
+ * decisive hook shape, so a plugin it cannot place is left alone.
+ */
+function assertPipelineSeparation(plugins: ResolvedPlugins, configFile: string): void {
+  const mismatches = checkPipelineSeparation(plugins)
+  if (mismatches.length === 0) return
+  throw new Error(
+    `[nifra] ${configFile}: plugins are in the wrong pipeline slot. nifra supports Vite and Bun, but a phase is owned by ONE of them - a plugin in the wrong slot is silently never called.\n\n` +
+      mismatches.map((m) => `  - ${m.fix}`).join("\n"),
+  )
 }
 
 /** Normalize a {@link PluginsField} (array | thunk | undefined) to a fresh array, awaiting a thunk. */
@@ -57,12 +85,20 @@ export async function resolvePlugins(field: PluginsField | undefined): Promise<u
   return value ? [...value] : []
 }
 
+export interface ResolvedPlugins {
+  readonly vitePlugins: readonly unknown[]
+  readonly clientPlugins: readonly unknown[]
+  readonly serverPlugins: readonly unknown[]
+}
+
 export interface LoadedApp {
   readonly cwd: string
   readonly routesDir: string
   /** Build output dir (also where `nifra start` reads `manifest.json` + serves `/assets/*`). */
   readonly outDir: string
   readonly framework: NifraFramework
+  /** Plugin thunks resolved exactly once during app loading and reused by every command phase. */
+  readonly resolvedPlugins: ResolvedPlugins
   /** The `backend` export from `backend.ts`, or `undefined` if there's no `backend.ts`. */
   readonly backend: unknown
 }
@@ -160,6 +196,13 @@ export async function loadApp(
       `[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`,
     )
   }
+  const [vitePlugins, clientPlugins, serverPlugins] = await Promise.all([
+    resolvePlugins(fw.vitePlugins),
+    resolvePlugins(fw.clientPlugins),
+    resolvePlugins(fw.serverPlugins),
+  ])
+  const resolvedPlugins = { vitePlugins, clientPlugins, serverPlugins }
+  assertPipelineSeparation(resolvedPlugins, configFile)
 
   let backend: unknown
   const backendPath = resolve(cwd, "backend.ts")
@@ -173,6 +216,7 @@ export async function loadApp(
     routesDir: resolve(cwd, "routes"),
     outDir: resolve(cwd, outDirName),
     framework: fw as NifraFramework,
+    resolvedPlugins,
     backend,
   }
 }

package/src/mcp-docs-tools.ts

@@ -73,7 +73,7 @@ export function docsTools(
     {
       name: "nifra_types",
       description:
-        'Get the EXACT TypeScript declaration of any exported @nifrajs/* symbol — interface, type, class, function, const. Each signature is generated from the package\'s built .d.ts, so it is the LITERAL declaration: complete, authoritative, never prose and never truncated. THIS IS THE SOURCE OF TRUTH for nifra\'s types — do NOT read node_modules/@nifrajs/**/*.d.ts; call this instead. Pass `name` for an exact symbol (e.g. "RateLimitStore", "RouteSchema", "Context", "rateLimit"); pass `query` to search by keyword; omit both for the per-package index of names.',
+        'Get the EXACT TypeScript declaration of any exported @nifrajs/* symbol — interface, type, class, function, const. Each signature is generated from the package\'s built .d.ts, so it is the LITERAL declaration: complete, authoritative, never prose and never truncated. THIS IS THE SOURCE OF TRUTH for nifra\'s types — do NOT read node_modules/@nifrajs/**/*.d.ts; call this instead. Pass `name` for an exact symbol (e.g. "RateLimitStore", "RouteSchema", "Context", "rateLimit"); pass `query` to search by keyword; omit both for the per-package index of names. A `name` lookup is always the complete declaration; a `query` returns a one-line summary plus the signature, collapsing an oversized body — pass `full: true` to override.',
       inputSchema: {
         type: "object",
         properties: {
@@ -91,6 +91,11 @@ export function docsTools(
             type: "number",
             description: "Max results for a query/search (default 5, max 8).",
           },
+          full: {
+            type: "boolean",
+            description:
+              "Query mode only: return whole declarations instead of collapsed ones. Off by default — a search is for picking a symbol, and one match can be tens of thousands of characters.",
+          },
         },
         additionalProperties: false,
       },
@@ -99,8 +104,13 @@ export function docsTools(
         if (corpus === undefined) {
           return "types corpus missing — run `bun run build && bun run gen:llms` in the nifra repo (published builds ship it)."
         }
-        const { name, query, limit } = args as { name?: string; query?: string; limit?: number }
-        return renderTypesResult(corpus, name, query, clamp(limit, 1, 8, 5))
+        const { name, query, limit, full } = args as {
+          name?: string
+          query?: string
+          limit?: number
+          full?: boolean
+        }
+        return renderTypesResult(corpus, name, query, clamp(limit, 1, 8, 5), full === true)
       },
     },
   ]

package/src/mcp-http.ts

@@ -26,7 +26,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.0.0"
+const VERSION = "2.2.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 const DOCS_HEALTH =
   "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."

package/src/mcp-render.ts

@@ -169,5 +169,13 @@ if (import.meta.main) {
   } catch {
     output = { error: "invalid input: expected JSON { requests: [...] }" }
   }
-  process.stdout.write(JSON.stringify(output, null, 2))
+  await Bun.write(Bun.stdout, JSON.stringify(output, null, 2))
+  // Exit explicitly, exactly as the `--worker` branch above already does.
+  //
+  // Loading the app runs its module side effects, and a real app opens things: a database pool, a
+  // Redis client, a metrics interval. Any one of those keeps the event loop alive, so falling off
+  // the end of this module never terminates the process - and the parent is sitting in
+  // `await proc.exited`. The render itself finished; there is nothing left to wait for, and this
+  // process is single-use. `Bun.write` above is awaited so the output is flushed before we exit.
+  process.exit(0)
 }

package/src/mcp.ts

@@ -61,6 +61,26 @@ function childPath(name: "mcp-run" | "mcp-render" | "mcp-ws"): string {
 }
 
 /** Spawn `bun <child> <cwd>`, pipe `input` to its stdin, return its stdout (or a stderr-backed error). */
+/**
+ * How long a child gets before it is killed.
+ *
+ * A child loads the app, which runs its module side effects - a database pool, a Redis client, a
+ * metrics interval. Any of those keeps the child's event loop alive after the work is done, and the
+ * parent is sitting in `await proc.exited`. The children now exit explicitly, so this is the backstop
+ * rather than the fix: without it a single wedged child blocks an agent indefinitely, and the caller
+ * has no way to tell "still working" from "never returning".
+ *
+ * Generous enough for a cold start that compiles route modules, short enough that a hang is reported
+ * within one attention span rather than after minutes of polling.
+ */
+const CHILD_TIMEOUT_MS = 30_000
+
+const timeoutMessage = (label: string, ms: number): string =>
+  `${label} timed out after ${ms / 1000}s and was terminated.\n` +
+  `The app was loaded but the process did not finish. Most often this is a module-level side effect ` +
+  `that keeps the event loop alive (a database pool, a Redis client, an interval) opened during import ` +
+  `rather than lazily. Check for top-level connections in the app entry or anything it imports.`
+
 async function spawnChild(
   child: "mcp-run" | "mcp-render" | "mcp-ws",
   cwd: string,
@@ -76,6 +96,11 @@ async function spawnChild(
   })
   const abort = (): void => proc.kill()
   signal?.addEventListener("abort", abort, { once: true })
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    proc.kill()
+  }, CHILD_TIMEOUT_MS)
   try {
     proc.stdin.write(JSON.stringify(input))
     await proc.stdin.end()
@@ -88,8 +113,13 @@ async function spawnChild(
       const reason = typeof signal.reason === "string" ? `: ${signal.reason}` : ""
       return `${label} cancelled${reason}.`
     }
-    return out.trim() || `${label} failed:\n${err.trim() || "(no output)"}`
+    // A killed child may still have flushed a complete result before the timer fired; prefer real
+    // output over the timeout message so a slow-but-successful render is not reported as a failure.
+    const text = out.trim()
+    if (timedOut && text === "") return timeoutMessage(label, CHILD_TIMEOUT_MS)
+    return text || `${label} failed:\n${err.trim() || "(no output)"}`
   } finally {
+    clearTimeout(timer)
     signal?.removeEventListener("abort", abort)
   }
 }
@@ -189,10 +219,23 @@ export class WarmWorker {
         // process here would reject every OTHER in-flight request via the `exited` handler and force a
         // cold rebuild. Leave it hot — `createWarmHandler` already replaces it on file change.
         this.pending.delete(id)
+        clearTimeout(timer)
         const reason = typeof signal?.reason === "string" ? `: ${signal.reason}` : ""
         resolve(`${this.label} cancelled${reason}.`)
       }
-      const cleanup = (): void => signal?.removeEventListener("abort", abort)
+      // Same backstop as the cold path: a worker wedged mid-request would otherwise leave this
+      // promise unsettled forever. Drop the id and replace the worker - unlike a per-request cancel,
+      // a timeout means the worker itself is suspect, so the next call should start from a fresh one.
+      const timer = setTimeout(() => {
+        if (!this.pending.delete(id)) return
+        signal?.removeEventListener("abort", abort)
+        this.stop()
+        resolve(timeoutMessage(this.label, CHILD_TIMEOUT_MS))
+      }, CHILD_TIMEOUT_MS)
+      const cleanup = (): void => {
+        clearTimeout(timer)
+        signal?.removeEventListener("abort", abort)
+      }
       signal?.addEventListener("abort", abort, { once: true })
       this.pending.set(id, { resolve, reject, cleanup })
       try {

package/src/pipeline-guard.ts

@@ -0,0 +1,186 @@
+/**
+ * Pipeline separation guard — one bundler owns a phase, never two.
+ *
+ * nifra supports both Vite and Bun, and the config keeps them in separate slots: `vitePlugins` for
+ * the Vite pipeline, `clientPlugins`/`serverPlugins` for the Bun one. Nothing enforces the split, so
+ * a plugin lands in the wrong slot and is silently ignored - a Vite plugin in `clientPlugins` is
+ * handed to `Bun.build`, which has no `transform` hook to call, so the transform simply never runs
+ * and the build succeeds.
+ *
+ * That failure mode is the whole reason for this file. nifra's expensive bugs are not caused by Vite
+ * or by Bun; they are caused by two toolchains disagreeing about one module. Dual-React is that, the
+ * dedupe plugins are patches for that, and a `resolve.alias` that never reaches SSR is that. Mixing
+ * is the defect - choice is not - so the separation has to be checked rather than documented.
+ *
+ * Detection is by hook shape, which is what each bundler actually dispatches on:
+ *   - a Bun plugin has `setup(build)`
+ *   - a Rollup/Vite plugin has `resolveId` / `load` / `transform` / `config` / `configResolved` /
+ *     `transformIndexHtml` and no `setup`
+ *
+ * Deliberately conservative: a plugin that matches neither shape is left alone rather than guessed
+ * at. A guard that fires on correct config is a guard people turn off.
+ */
+
+/** Which pipeline a slot belongs to. */
+export type PipelineSlot = "vitePlugins" | "clientPlugins" | "serverPlugins"
+
+export interface PipelineMismatch {
+  readonly slot: PipelineSlot
+  /** The plugin's `name`, or a positional label when it has none. */
+  readonly plugin: string
+  /** The pipeline the slot feeds. */
+  readonly expected: "vite" | "bun"
+  /** The pipeline the plugin's hooks say it belongs to. */
+  readonly actual: "vite" | "bun"
+  readonly fix: string
+}
+
+const ROLLUP_HOOKS = [
+  "resolveId",
+  "load",
+  "transform",
+  "config",
+  "configResolved",
+  "configureServer",
+  "transformIndexHtml",
+  "generateBundle",
+  "renderChunk",
+] as const
+
+/** Classify a plugin by the hooks it exposes, or `undefined` when its shape says nothing. */
+function classify(plugin: unknown): "vite" | "bun" | undefined {
+  if (typeof plugin !== "object" || plugin === null) return undefined
+  const record = plugin as Record<string, unknown>
+  // `setup` is Bun's only entry point, so its presence is decisive even alongside other keys.
+  if (typeof record.setup === "function") return "bun"
+  if (ROLLUP_HOOKS.some((hook) => typeof record[hook] === "function")) return "vite"
+  return undefined
+}
+
+const SLOT_PIPELINE: Readonly<Record<PipelineSlot, "vite" | "bun">> = {
+  vitePlugins: "vite",
+  clientPlugins: "bun",
+  serverPlugins: "bun",
+}
+
+const MOVE_TO: Readonly<Record<"vite" | "bun", string>> = {
+  vite: "`vitePlugins`",
+  bun: "`clientPlugins` (client bundle) or `serverPlugins` (SSR)",
+}
+
+/**
+ * Check one slot's resolved plugin list. Pure: takes the already-resolved array so a thunk-valued
+ * field is awaited by the caller, and so this stays testable without loading a project.
+ */
+export function checkPipelineSlot(
+  slot: PipelineSlot,
+  plugins: readonly unknown[],
+): PipelineMismatch[] {
+  const expected = SLOT_PIPELINE[slot]
+  const out: PipelineMismatch[] = []
+  for (let i = 0; i < plugins.length; i++) {
+    const plugin = plugins[i]
+    const actual = classify(plugin)
+    if (actual === undefined || actual === expected) continue
+    const named = (plugin as { name?: unknown }).name
+    const label = typeof named === "string" && named !== "" ? named : `${slot}[${i}]`
+    out.push({
+      slot,
+      plugin: label,
+      expected,
+      actual,
+      fix:
+        actual === "vite"
+          ? `"${label}" is a Vite/Rollup plugin (it defines Rollup hooks, not \`setup\`) but sits in \`${slot}\`, which feeds Bun.build. Bun never calls those hooks, so the transform silently does not run. Move it to ${MOVE_TO.vite}.`
+          : `"${label}" is a Bun plugin (it defines \`setup\`) but sits in \`${slot}\`, which feeds Vite. Vite never calls \`setup\`, so the transform silently does not run. Move it to ${MOVE_TO.bun}.`,
+    })
+  }
+  return out
+}
+
+/** Check every slot of a resolved framework config. */
+export function checkPipelineSeparation(slots: {
+  readonly vitePlugins?: readonly unknown[]
+  readonly clientPlugins?: readonly unknown[]
+  readonly serverPlugins?: readonly unknown[]
+}): PipelineMismatch[] {
+  return [
+    ...checkPipelineSlot("vitePlugins", slots.vitePlugins ?? []),
+    ...checkPipelineSlot("clientPlugins", slots.clientPlugins ?? []),
+    ...checkPipelineSlot("serverPlugins", slots.serverPlugins ?? []),
+  ]
+}
+
+/** Which bundler a build runs on. */
+export type BuildPipeline = "bun" | "vite"
+
+export interface PipelineDecision {
+  readonly pipeline: BuildPipeline
+  /**
+   * 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.
+   */
+  readonly reason?: string
+}
+
+/** The plugin slots a decision reads, already resolved. */
+export interface PipelineSlots {
+  readonly vitePlugins?: readonly unknown[]
+  readonly clientPlugins?: readonly unknown[]
+  readonly serverPlugins?: readonly unknown[]
+}
+
+const pluginNames = (plugins: readonly unknown[]): string =>
+  plugins
+    .map((plugin, i) => {
+      const named = (plugin as { name?: unknown }).name
+      return typeof named === "string" && named !== "" ? named : `vitePlugins[${i}]`
+    })
+    .join(", ")
+
+/**
+ * Pick the bundler for `nifra build`, 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.
+ *
+ * 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
+ * equivalent on purpose - nothing is dropped - so the fast Bun default stands.
+ *
+ * `forced` is `--vite` / `--bun` and always wins, except for the one combination that silently discards
+ * work, which throws instead. Refusing rather than warning matches the slot guard: a build that succeeds
+ * and omits the transform is worse than one that stops and says so.
+ */
+export function chooseBuildPipeline(
+  slots: PipelineSlots,
+  forced?: BuildPipeline,
+): PipelineDecision {
+  const vitePlugins = slots.vitePlugins ?? []
+  const bunPlugins = [...(slots.clientPlugins ?? []), ...(slots.serverPlugins ?? [])]
+  const viteOnly = vitePlugins.length > 0 && bunPlugins.length === 0
+
+  if (forced === "bun" && viteOnly) {
+    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 " +
+        "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`.",
+    )
+  }
+  if (forced !== undefined) return { pipeline: forced }
+  if (viteOnly) {
+    return {
+      pipeline: "vite",
+      reason: `auto: this app's only transforms are \`vitePlugins\` (${pluginNames(vitePlugins)}), which the Bun build cannot run`,
+    }
+  }
+  return { pipeline: "bun" }
+}

package/src/types-search.ts

@@ -60,6 +60,53 @@ function renderEntry(t: TypeEntry): string {
   return `${head}\n\n\`\`\`ts\n${doc}${t.signature}\n\`\`\``
 }
 
+/**
+ * Longest signature rendered whole in a SEARCH result.
+ *
+ * Search is "which symbol did I mean?", not "show me everything about it" - and the corpus is wildly
+ * uneven: the median declaration is small, while `Server` alone is ~32,000 characters, five times the
+ * next largest. One broad query that happened to match it returned the entire class for near-zero
+ * value. Above this, a search result shows the head plus a member count and says how to get the rest;
+ * an exact `name` lookup is never collapsed, because there the caller asked for that symbol.
+ */
+const SEARCH_SIGNATURE_MAX = 600
+
+/** First sentence of the doc block, flattened to one line - enough to pick between candidates. */
+function summarize(doc: string | undefined): string {
+  if (doc === undefined) return ""
+  const text = doc
+    .replace(/\/\*\*|\*\/|^\s*\*/gm, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+  if (text === "") return ""
+  const end = text.search(/\.\s|\.$/)
+  const sentence = end === -1 ? text : text.slice(0, end + 1)
+  return sentence.length > 200 ? `${sentence.slice(0, 197)}...` : sentence
+}
+
+/** Keep the declaration head; replace a long body with a member count. */
+function collapseSignature(signature: string): string {
+  const open = signature.indexOf("{")
+  if (open === -1) return `${signature.slice(0, SEARCH_SIGNATURE_MAX)}…`
+  const body = signature.slice(open)
+  // Rough but honest: count top-level-looking member lines rather than parsing TypeScript here.
+  const members = body.split("\n").filter((line) => /^\s{2,4}\S/.test(line)).length
+  return `${signature.slice(0, open).trim()} { … ${members} members … }`
+}
+
+/** A search hit: enough to choose, not the whole declaration. */
+function renderSearchHit(t: TypeEntry): string {
+  const head = `## ${t.name} — ${t.kind}, \`${t.package}\``
+  const summary = summarize(t.doc)
+  const signature =
+    t.signature.length <= SEARCH_SIGNATURE_MAX ? t.signature : collapseSignature(t.signature)
+  const note =
+    t.signature.length <= SEARCH_SIGNATURE_MAX
+      ? ""
+      : `\n_Collapsed (${t.signature.length} chars). Call \`nifra_types({ name: "${t.name}" })\` for the full declaration._`
+  return `${head}\n${summary ? `\n${summary}\n` : ""}\n\`\`\`ts\n${signature}\n\`\`\`${note}`
+}
+
 /**
  * Render the tool result. `name` → the exact declaration(s); else `query` → the top matches; else a
  * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),
@@ -70,6 +117,7 @@ export function renderTypesResult(
   name: string | undefined,
   query: string | undefined,
   limit: number,
+  full = false,
 ): string {
   if (name !== undefined && name.trim() !== "") {
     const hits = lookupType(types, name)
@@ -83,7 +131,8 @@ export function renderTypesResult(
     if (matches.length === 0) {
       return `No types matched ${JSON.stringify(query)}. Try a broader term, pass an exact \`name\`, or call with no args for the index.`
     }
-    return matches.map(renderEntry).join("\n\n---\n\n")
+    // Search results are collapsed by default; `full` opts back into whole declarations.
+    return matches.map(full ? renderEntry : renderSearchHit).join("\n\n---\n\n")
   }
   const byPkg = new Map<string, string[]>()
   for (const t of types) {