@nifrajs/cli 2.7.0 → 2.8.0

package/package.json

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

package/src/check.ts

@@ -511,9 +511,145 @@ interface SqlExpressionShape {
   readonly parameterizedTag: boolean
 }
 
+/** Module-scope `const` initializers by name - the one binding form the SQL scanner resolves. */
+type ModuleConsts = ReadonlyMap<string, TSApi.Expression>
+
+/** Collect the file's top-level `const NAME = <initializer>` declarations. Destructured names, `let`,
+ * `var`, and anything nested stay out on purpose: a module-scope `const` is the only form that
+ * provably cannot carry request data. */
+function moduleConstsOf(ts: TypeScriptApi, source: TSApi.SourceFile): ModuleConsts {
+  const map = new Map<string, TSApi.Expression>()
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.initializer !== undefined) {
+        map.set(declaration.name.text, declaration.initializer)
+      }
+    }
+  }
+  return map
+}
+
+/** Whether `name`, read at `at`, might be re-declared by anything between the read and module scope.
+ * Conservative on purpose: the OUTERMOST enclosing function/block subtree is scanned for ANY binding
+ * of the name (parameter, `var`/`let`/`const`, catch, local function, destructuring element) - so a
+ * hoisted `var` in a sibling block, or a binding in a branch that never runs, still refuses
+ * resolution. Over-refusal flags a safe line (the pre-feature behavior); under-refusal would resolve
+ * the wrong binding, which is why the cheap-and-broad scan wins over scope simulation. A use with no
+ * enclosing function or block reads module scope directly and cannot be shadowed. */
+function isShadowedAt(ts: TypeScriptApi, at: TSApi.Node, name: string): boolean {
+  let scope: TSApi.Node | undefined
+  for (let node: TSApi.Node | undefined = at.parent; node !== undefined; node = node.parent) {
+    if (ts.isSourceFile(node)) break
+    if (ts.isFunctionLike(node) || ts.isBlock(node)) scope = node
+  }
+  if (scope === undefined) return false
+  const bindsName = (binding: TSApi.BindingName): boolean =>
+    ts.isIdentifier(binding)
+      ? binding.text === name
+      : binding.elements.some(
+          (element) =>
+            !ts.isOmittedExpression(element) &&
+            (ts.isIdentifier(element.name) ? element.name.text === name : bindsName(element.name)),
+        )
+  let found = false
+  const scan = (node: TSApi.Node): void => {
+    if (found) return
+    if (
+      (ts.isVariableDeclaration(node) || ts.isParameter(node)) &&
+      bindsName(node.name as TSApi.BindingName)
+    ) {
+      found = true
+      return
+    }
+    if (ts.isFunctionDeclaration(node) && node.name?.text === name) {
+      found = true
+      return
+    }
+    ts.forEachChild(node, scan)
+  }
+  scan(scope)
+  return found
+}
+
+const CONST_RESOLUTION_DEPTH = 5
+
+/**
+ * Resolve an interpolated expression to compile-time text, or `undefined` when it can carry runtime
+ * data. Pure syntax, no type checker - the same honest limit the rule already documents. What
+ * resolves: string/number literals, no-substitution templates, templates whose every span resolves,
+ * ternaries with both branches resolvable (BOTH branch texts are returned, so a hostile keyword in
+ * either still feeds the keyword scan), `as`/`satisfies` wrappers, and a same-file module-scope
+ * `const` whose initializer resolves (recursively, depth-capped). Everything else - an imported
+ * name, `let`, a parameter, a call, a member access, a shadowed name - stays unresolved and the
+ * interpolation is flagged exactly as before.
+ */
+function resolveStaticSqlText(
+  ts: TypeScriptApi,
+  node: TSApi.Expression,
+  consts: ModuleConsts,
+  depth: number,
+): string | undefined {
+  if (depth > CONST_RESOLUTION_DEPTH) return undefined
+  if (ts.isParenthesizedExpression(node)) {
+    return resolveStaticSqlText(ts, node.expression, consts, depth)
+  }
+  if (ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
+    return resolveStaticSqlText(ts, node.expression, consts, depth)
+  }
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text
+  if (ts.isNumericLiteral(node)) return node.text
+  if (ts.isTemplateExpression(node)) {
+    let text = node.head.text
+    for (const span of node.templateSpans) {
+      const part = resolveStaticSqlText(ts, span.expression, consts, depth + 1)
+      if (part === undefined) return undefined
+      text += part + span.literal.text
+    }
+    return text
+  }
+  if (ts.isConditionalExpression(node)) {
+    const whenTrue = resolveStaticSqlText(ts, node.whenTrue, consts, depth + 1)
+    const whenFalse = resolveStaticSqlText(ts, node.whenFalse, consts, depth + 1)
+    if (whenTrue === undefined || whenFalse === undefined) return undefined
+    return `${whenTrue} ${whenFalse}`
+  }
+  if (ts.isIdentifier(node)) {
+    const initializer = consts.get(node.text)
+    if (initializer === undefined) return undefined
+    if (isShadowedAt(ts, node, node.text)) return undefined
+    return resolveStaticSqlText(ts, initializer, consts, depth + 1)
+  }
+  return undefined
+}
+
+/** A template's contribution to the shape: resolved span texts fold into `staticText` (so the
+ * keyword scan still sees what a `const` carries); any unresolvable span keeps it `dynamic`. */
+function templateShape(
+  ts: TypeScriptApi,
+  template: TSApi.TemplateExpression,
+  consts: ModuleConsts | undefined,
+): { staticText: string; dynamic: boolean } {
+  let staticText = template.head.text
+  let dynamic = false
+  for (const span of template.templateSpans) {
+    const resolved =
+      consts === undefined ? undefined : resolveStaticSqlText(ts, span.expression, consts, 0)
+    if (resolved === undefined) dynamic = true
+    else staticText += resolved
+    staticText += span.literal.text
+  }
+  return { staticText, dynamic }
+}
+
 /** Describe only the first argument's syntax; comments/strings elsewhere cannot influence the result. */
-function sqlExpressionShape(ts: TypeScriptApi, node: TSApi.Expression): SqlExpressionShape {
-  if (ts.isParenthesizedExpression(node)) return sqlExpressionShape(ts, node.expression)
+function sqlExpressionShape(
+  ts: TypeScriptApi,
+  node: TSApi.Expression,
+  consts?: ModuleConsts,
+): SqlExpressionShape {
+  if (ts.isParenthesizedExpression(node)) return sqlExpressionShape(ts, node.expression, consts)
   if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
     return {
       staticText: node.text,
@@ -529,9 +665,10 @@ function sqlExpressionShape(ts: TypeScriptApi, node: TSApi.Expression): SqlExpre
       (ts.isIdentifier(tag) && tag.text === "sql") ||
       (ts.isPropertyAccessExpression(tag) && tag.getText() === "Prisma.sql")
     const template = node.template
-    const staticText = ts.isTemplateExpression(template)
-      ? [template.head.text, ...template.templateSpans.map((span) => span.literal.text)].join("")
-      : template.text
+    const templated = ts.isTemplateExpression(template)
+      ? templateShape(ts, template, parameterizedTag ? undefined : consts)
+      : { staticText: template.text, dynamic: false }
+    const staticText = templated.staticText
     // Only the ecosystem's binding tags are trusted, by NAME - which is the honest limit of a scanner
     // that reads syntax and runs no type checker. `sql` is what postgres.js, drizzle, slonik and Bun's
     // own driver all call theirs, and `Prisma.sql` is Prisma's; taking those at their word is a
@@ -547,32 +684,53 @@ function sqlExpressionShape(ts: TypeScriptApi, node: TSApi.Expression): SqlExpre
     // is treated as plain interpolation.
     return {
       staticText,
-      dynamic: ts.isTemplateExpression(template) && !parameterizedTag,
+      dynamic: templated.dynamic && !parameterizedTag,
       concatenated: false,
       literal: !ts.isTemplateExpression(template),
       parameterizedTag,
     }
   }
   if (ts.isTemplateExpression(node)) {
+    const templated = templateShape(ts, node, consts)
     return {
-      staticText: [node.head.text, ...node.templateSpans.map((span) => span.literal.text)].join(""),
-      dynamic: true,
+      staticText: templated.staticText,
+      dynamic: templated.dynamic,
       concatenated: false,
       literal: false,
       parameterizedTag: false,
     }
   }
   if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
-    const left = sqlExpressionShape(ts, node.left)
-    const right = sqlExpressionShape(ts, node.right)
+    const left = sqlExpressionShape(ts, node.left, consts)
+    const right = sqlExpressionShape(ts, node.right, consts)
     return {
       staticText: left.staticText + right.staticText,
-      dynamic: left.dynamic || right.dynamic || !left.literal || !right.literal,
+      // A resolved const operand is static text, not a dynamic part - so the old `!literal` test
+      // narrows to what it always actually meant: an operand that carries runtime data (dynamic) or
+      // a binding tag being concatenated into plain text (which un-parameterizes it).
+      dynamic: left.dynamic || right.dynamic || left.parameterizedTag || right.parameterizedTag,
       concatenated: true,
       literal: left.literal && right.literal,
       parameterizedTag: false,
     }
   }
+  // A resolvable expression (a module-`const` name, a literal ternary) contributes its compile-time
+  // text and stays non-dynamic - this is what lets `"SELECT " + COLS + " FROM t"` and
+  // `db.query(`${COLS} FROM t WHERE id = $1`)` pass while an imported or mutable name still flags.
+  // `literal` stays false: the named escape hatches (`unsafe`, `$queryRawUnsafe`) keep flagging a
+  // resolved const, because taking statement text from ANY variable is what their rule warns about.
+  if (consts !== undefined) {
+    const resolved = resolveStaticSqlText(ts, node, consts, 0)
+    if (resolved !== undefined) {
+      return {
+        staticText: resolved,
+        dynamic: false,
+        concatenated: false,
+        literal: false,
+        parameterizedTag: false,
+      }
+    }
+  }
   return {
     staticText: "",
     dynamic: true,
@@ -623,12 +781,16 @@ export function scanInterpolatedSql(
     source as TSApi.SourceFile & { readonly parseDiagnostics?: readonly TSApi.Diagnostic[] }
   ).parseDiagnostics
   if (parseDiagnostics !== undefined && parseDiagnostics.length > 0) return out
+  // Module-scope consts, resolved once per file: an interpolated same-file `const` cannot carry
+  // request data, so the shared-projection idiom (`const COLS = "id, name"` … `${COLS}`) stays quiet
+  // while imported, mutable, parameter, and shadowed names flag exactly as before.
+  const consts = moduleConstsOf(ts, source)
   const visit = (node: TSApi.Node): void => {
     if (ts.isCallExpression(node)) {
       const sink = sqlMethod(ts, node)
       const argument = node.arguments[0]
       if (sink !== undefined && argument !== undefined) {
-        const shape = sqlExpressionShape(ts, argument)
+        const shape = sqlExpressionShape(ts, argument, consts)
         const unsafeEscape =
           ALWAYS_UNSAFE.has(sink.method) && !shape.literal && !shape.parameterizedTag
         const assembledSql =

package/src/cli.ts

@@ -12,13 +12,7 @@
 import { existsSync } from "node:fs"
 import { resolve } from "node:path"
 import { inProcessClient } from "@nifrajs/client"
-import {
-  createWebApp,
-  DEFAULT_DEV_PORT,
-  type RenderAdapter,
-  SERVER_FN_MODULE,
-  SERVER_ONLY_MODULE,
-} from "@nifrajs/web"
+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"
@@ -154,7 +148,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.7.0"
+const CLI_VERSION = "2.8.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
@@ -210,6 +204,15 @@ export function formatCliError(err: unknown): string {
  * 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 })) {
@@ -217,58 +220,6 @@ export 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` " +
@@ -285,6 +236,42 @@ async function dev(app: LoadedApp, flags: Flags): Promise<void> {
   // each pipeline is selectable in BOTH phases, and neither ever runs inside the other.
   if (flags.bun) {
     await assertBunDevSupportsApp(app)
+    // 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
+    // it IS the configured child with a per-launch random token (matched against the file the
+    // parent just wrote, consumed on first read). A fixed sentinel here would be a secret-leak
+    // switch: any inherited environment could set it, skip the generation, and serve the app with
+    // no boundary plugins at all. An unprovable token acts as a parent - fail closed.
+    const { consumeLaunchToken, writeBunDevConfig } = await import("./dev-bun-config.ts")
+    if (!consumeLaunchToken(app.cwd, process.env.NIFRA_BUN_DEV_TOKEN)) {
+      // Re-exec depth backstop: token verification makes recursion terminate (the direct child
+      // always verifies), so hitting this means filesystem/env sabotage - refuse over fork-looping.
+      const depth = Number(process.env.NIFRA_BUN_DEV_DEPTH ?? "0")
+      if (depth >= 3) {
+        throw new Error(
+          "[nifra] `nifra dev --bun` could not verify its generated dev config after several " +
+            "relaunches. Something is rewriting `.nifra/dev-bun/` or the environment between " +
+            "launches; refusing to serve without the client-boundary plugins.",
+        )
+      }
+      const { bunfigPath, launchToken } = await writeBunDevConfig(app.cwd)
+      const child = Bun.spawn(
+        [process.execPath, `--config=${bunfigPath}`, ...process.argv.slice(1)],
+        {
+          stdio: ["inherit", "inherit", "inherit"],
+          env: {
+            ...process.env,
+            NIFRA_BUN_DEV_TOKEN: launchToken,
+            NIFRA_BUN_DEV_DEPTH: String(depth + 1),
+          },
+        },
+      )
+      const forward = (): void => child.kill("SIGINT")
+      process.on("SIGINT", forward)
+      process.on("SIGTERM", forward)
+      process.exit(await child.exited)
+    }
     const { createDevServer } = await import("@nifrajs/web/dev")
     const { framework: fw, routesDir, outDir, backend } = app
     const server = await createDevServer({

package/src/dev-bun-config.ts

@@ -0,0 +1,204 @@
+/**
+ * The `nifra dev --bun` boundary-plugin channel.
+ *
+ * Bun's dev-server bundling (`Bun.serve` HTML imports) accepts plugins ONLY through bunfig's
+ * `[serve.static] plugins` - there is no programmatic option (upstream ask: oven-sh/bun#36830), and
+ * a runtime `Bun.plugin()` never reaches it. Without a plugin there, a `*.fn` server-function module
+ * 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.
+ *
+ * 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);
+ *   - `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
+ *     (`preload`, plugin paths) re-rooted at the app, because bunfig resolves relative entries
+ *     against the CONFIG file's directory;
+ *   - `launch-token` - a per-launch random value (see below).
+ *
+ * `dev --bun` then re-execs itself once with `--config=<generated>` (bunfig is read at process
+ * start, so the already-running CLI can't adopt it) - see `cli.ts`.
+ *
+ * ## Why a random launch token, not a fixed marker
+ *
+ * The child must know it IS the configured child. A fixed sentinel (`SOME_VAR=1`) would let any
+ * inherited environment - a CI wrapper, a shell profile, another tool - satisfy the check and skip
+ * the config generation entirely, serving the app with NO boundary plugins: a silent secret leak
+ * switched on by an environment variable. So the parent mints a fresh `crypto.randomUUID()` per
+ * launch, writes it beside the generated config, and passes it in the child's env; the child accepts
+ * only a token that matches the file, and CONSUMES the file on first read so a stale env value can
+ * never satisfy a later launch. An unverifiable token means the process acts as a parent and
+ * regenerates - fail closed, never serve unproven.
+ */
+import { timingSafeEqual } from "node:crypto"
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+/** TOML string literal: basic (double-quoted) form with the two escapes it needs. */
+function tomlString(value: string): string {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`
+}
+
+/** A parsed bunfig: plain data from `Bun.TOML.parse`. */
+type BunfigData = Record<string, unknown>
+
+/** Parse the app's bunfig. Malformed TOML fails LOUDLY with the parse error - silently treating a
+ * broken config as empty would run dev with different Bun settings than the app declares. */
+export function parseUserBunfig(toml: string | undefined): BunfigData {
+  if (toml === undefined) return {}
+  try {
+    return (Bun.TOML.parse(toml) ?? {}) as BunfigData
+  } catch (err) {
+    throw new Error(
+      `[nifra] the app's bunfig.toml does not parse, so \`nifra dev --bun\` cannot carry it into ` +
+        `the dev server's config: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+}
+
+const BARE_KEY = /^[A-Za-z0-9_-]+$/
+const tomlKey = (key: string): string => (BARE_KEY.test(key) ? key : tomlString(key))
+
+function tomlValue(value: unknown, path: string): string {
+  if (typeof value === "string") return tomlString(value)
+  if (typeof value === "number" || typeof value === "boolean") return String(value)
+  if (Array.isArray(value)) {
+    return `[${value.map((item, i) => tomlValue(item, `${path}[${i}]`)).join(", ")}]`
+  }
+  throw new Error(
+    `[nifra] bunfig field \`${path}\` has a shape \`nifra dev --bun\` cannot re-serialize ` +
+      `(supported: strings, numbers, booleans, arrays of those, and nested tables). ` +
+      `Move it out of bunfig.toml for the Bun dev loop, or report the shape.`,
+  )
+}
+
+const isTable = (value: unknown): value is BunfigData =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+/** Serialize a parsed bunfig back to TOML: scalar/array keys first, then nested tables as dotted
+ * `[section]` headers, recursively. Every field round-trips or the serializer throws - a field
+ * silently dropped here would be a dev server running different Bun settings than the app's. */
+export function serializeBunfig(data: BunfigData): string {
+  const lines: string[] = []
+  const walk = (table: BunfigData, prefix: string): void => {
+    const scalars = Object.entries(table).filter(([, v]) => !isTable(v))
+    const tables = Object.entries(table).filter((entry): entry is [string, BunfigData] =>
+      isTable(entry[1]),
+    )
+    if (prefix !== "" && scalars.length > 0) lines.push(`[${prefix}]`)
+    for (const [key, value] of scalars) {
+      lines.push(`${tomlKey(key)} = ${tomlValue(value, prefix === "" ? key : `${prefix}.${key}`)}`)
+    }
+    for (const [key, value] of tables) {
+      const next = prefix === "" ? tomlKey(key) : `${prefix}.${tomlKey(key)}`
+      // A table with ONLY sub-tables still needs no header of its own; recursion emits the leaves.
+      walk(value, next)
+    }
+  }
+  walk(data, "")
+  return `${lines.join("\n")}\n`
+}
+
+/** Render the generated bunfig: the user's config carried whole, with the boundary plugin prepended
+ * to `[serve.static] plugins` and path-bearing entries (`preload`, plugin paths) re-rooted at the
+ * APP - bunfig resolves relative entries against the config file's own directory, which is
+ * `.nifra/dev-bun/`. */
+export function renderDevBunfig(
+  boundaryPluginPath: string,
+  user: BunfigData,
+  appRoot: string,
+): string {
+  const resolveEntry = (entry: unknown): unknown =>
+    typeof entry === "string" && entry.startsWith(".") ? resolve(appRoot, entry) : entry
+  const data: BunfigData = structuredClone(user)
+  if (data.preload !== undefined) {
+    const entries = Array.isArray(data.preload) ? data.preload : [data.preload]
+    data.preload = entries.map(resolveEntry)
+  }
+  const serve = isTable(data.serve) ? data.serve : {}
+  data.serve = serve
+  const serveStatic = isTable(serve.static) ? serve.static : {}
+  serve.static = serveStatic
+  const existing = Array.isArray(serveStatic.plugins) ? serveStatic.plugins : []
+  serveStatic.plugins = [boundaryPluginPath, ...existing.map(resolveEntry)]
+  return (
+    "# Generated by `nifra dev --bun` - do not edit. Regenerated on every dev start.\n" +
+    "# The app's own bunfig is carried over verbatim; [serve.static] plugins additionally deliver\n" +
+    "# the client-boundary plugins (server-fn stubs, server-only emptying) to Bun's dev-server\n" +
+    "# bundler, which only accepts plugins via this channel (oven-sh/bun#36830).\n" +
+    serializeBunfig(data)
+  )
+}
+
+/** 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"
+
+const fn = serverFnStubPlugin()
+const serverOnly = serverOnlyEmptyPlugin()
+
+export default {
+  name: "nifra-dev-boundary",
+  setup(build) {
+    serverOnly.setup(build)
+    fn.setup(build)
+  },
+}
+`
+}
+
+export interface BunDevConfig {
+  readonly bunfigPath: string
+  /** Per-launch random value the re-exec'd child must present (and the file copy it must match). */
+  readonly launchToken: string
+}
+
+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> {
+  const dir = resolve(appRoot, ".nifra", "dev-bun")
+  mkdirSync(dir, { recursive: true })
+  const pluginPath = resolve(dir, "boundary-plugin.ts")
+  writeFileSync(pluginPath, renderBoundaryPluginModule())
+  const userToml = await Bun.file(resolve(appRoot, "bunfig.toml"))
+    .text()
+    .catch(() => undefined)
+  const bunfigPath = resolve(dir, "bunfig.toml")
+  writeFileSync(bunfigPath, renderDevBunfig(pluginPath, parseUserBunfig(userToml), appRoot))
+  const launchToken = crypto.randomUUID()
+  writeFileSync(resolve(dir, TOKEN_FILE), launchToken)
+  return { bunfigPath, launchToken }
+}
+
+/**
+ * Child-side proof of a configured launch: the presented token must match the token file the parent
+ * just wrote, compared in constant time. The file is CONSUMED (deleted) on the first attempt either
+ * way, so a stale environment value can never satisfy a later launch. `false` means this process
+ * cannot prove the boundary config is active and must act as a parent (regenerate + re-exec) - the
+ * fail-closed direction.
+ */
+export function consumeLaunchToken(appRoot: string, presented: string | undefined): boolean {
+  if (presented === undefined || presented === "") return false
+  const path = resolve(appRoot, ".nifra", "dev-bun", TOKEN_FILE)
+  let stored: string
+  try {
+    stored = readFileSync(path, "utf8")
+  } catch {
+    return false
+  }
+  try {
+    unlinkSync(path)
+  } catch {
+    // Already consumed by a race - the comparison below still decides on the bytes read.
+  }
+  const a = Buffer.from(stored)
+  const b = Buffer.from(presented)
+  return a.length === b.length && timingSafeEqual(a, b)
+}

package/src/mcp-app-tool.ts

@@ -1,5 +1,5 @@
 /**
- * The `nifra_examples_app` MCP tool: nifra's verified code examples as an MCP Apps widget. It returns the
+ * The `nifra_gallery` MCP tool: nifra's verified code examples as an MCP Apps widget. It returns the
  * examples as `structuredContent`, rendered by the {@link examplesWidget} `ui://` widget in MCP Apps hosts
  * (ChatGPT Apps, MCPJam, Goose); text-only hosts still get the example names as plain text. Part of the
  * public docs-MCP tool set (served by `handleMcpHttp`), so every self-host gets it from one definition.
@@ -50,10 +50,14 @@ export const examplesWidget = defineMcpWidget({
 /** The widget-backed tool. `loadExamples` is injected (disk on the CLI, cached fetch on the edge). */
 export function examplesAppTool(loadExamples: () => Promise<Example[] | undefined>): McpTool {
   return defineMcpTool({
-    name: "nifra_examples_app",
-    annotations: { title: "Browse nifra examples", readOnlyHint: true, openWorldHint: false },
+    name: "nifra_gallery",
+    annotations: {
+      title: "Browse the nifra example gallery",
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
     description:
-      "Browse nifra's verified code examples as an interactive, filterable list (MCP Apps widget). Pass query to pre-filter; the widget also filters client-side.",
+      "Open an interactive, filterable gallery of ALL of nifra's verified code examples (MCP Apps widget) - for browsing and discovering what exists. NOT for fetching one snippet as text: use nifra_example for that. Pass query to pre-filter; the widget also filters client-side.",
     inputSchema: {
       type: "object",
       properties: { query: { type: "string", description: "Pre-filter examples by keyword." } },

package/src/mcp-docs-tools.ts

@@ -58,7 +58,7 @@ export function docsTools(
         openWorldHint: false,
       },
       description:
-        'Get a VERIFIED, copy-pasteable nifra code example for a task - auth route, file upload, ISR page, loader/action, typed client, SSE, deployment, etc. Every snippet is typechecked against the installed nifra version, so it compiles as-is. PREFER THIS over writing nifra code from memory (training data drifts). Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
+        'Get a VERIFIED, copy-pasteable nifra code example for a task - auth route, file upload, ISR page, loader/action, typed client, SSE, deployment, etc. Every snippet is typechecked against the installed nifra version, so it compiles as-is. PREFER THIS over writing nifra code from memory (training data drifts). Returns code as TEXT for direct use; to visually browse the whole example set instead, use nifra_gallery. Call with no query for the grouped index; pass query (e.g. "protected route", "upload", "isr revalidate") for matching snippets.',
       inputSchema: {
         type: "object",
         properties: {