@nifrajs/web 5.4.0 → 5.5.0

package/src/build.ts

@@ -1,3 +1,4 @@
+import { formatBuildLog } from "./diagnostic.ts"
 import { publicEnvDefines } from "./internal/public-env.ts"
 
 export { publicEnvDefines } from "./internal/public-env.ts"
@@ -33,12 +34,14 @@ import {
   type BuildTarget,
   type BuildTargetPlan,
   type Bundler,
+  buildAssetPaths,
   type ChunkSize,
   detectNodeBuiltinsInClient,
   detectServerOnlyInClient,
   formatNodeBuiltinLeak,
   formatServerOnlyLeak,
   parseBuildTarget,
+  parseManifestBuildAssets,
   parseManifestClientEntry,
   parseManifestCopyChunks,
   parseManifestCssLoading,
@@ -52,6 +55,7 @@ import { sanitizeOutputNames } from "./chunk-names.ts"
 import { type CssLoadingMode, normalizeCssCodeSplit, normalizeCssLoading } from "./css-contract.ts"
 import { discoverRoutes } from "./fs.ts"
 import { generateClientEntry, generateServerManifest } from "./index.ts"
+import { missingClientEntry } from "./internal/codegen.ts"
 import { loadCopySplit } from "./internal/copy-split.ts"
 import { assertDisposableDir } from "./internal/disposable-dir.ts"
 import { entryChunks } from "./internal/entry-chunks.ts"
@@ -396,6 +400,7 @@ export function resyncServerManifestSource(
 ): string {
   const cssLoading = parseManifestCssLoading(source)
   const copyChunks = parseManifestCopyChunks(source)
+  const buildAssets = parseManifestBuildAssets(source)
   return generateServerManifest(manifest, {
     resolve: (file) => `${routesPrefix}${file}`,
     clientEntry: parseManifestClientEntry(source) ?? "",
@@ -403,6 +408,7 @@ export function resyncServerManifestSource(
     routeStyles: parseManifestRouteStyles(source),
     ...(cssLoading !== undefined ? { cssLoading } : {}),
     ...(copyChunks !== undefined ? { copyChunks } : {}),
+    ...(buildAssets !== undefined ? { buildAssets } : {}),
     lazy: MANIFEST_IS_LAZY.test(source),
   })
 }
@@ -569,7 +575,7 @@ export async function buildClient(options: BuildClientOptions): Promise<BuildMan
     if (verdict !== undefined) throw new Error(verdict)
     if (refused.size > 0) throw new Error(formatRefusedFiles(refused, root))
     throw new Error(
-      `[nifra/web] client build failed:\n${result.logs.map((l) => String(l)).join("\n")}`,
+      `[nifra/web] client build failed:\n${result.logs.map((l) => formatBuildLog(l, root)).join("\n")}`,
     )
   }
 
@@ -816,9 +822,16 @@ export interface BuildServerOptions {
   readonly serverEntry: string
   /** Output directory for the bundled worker (absolute path). */
   readonly outDir: string
+  /**
+   * The manifest `buildClient` returned. Supplies {@link clientEntry}, {@link styles},
+   * {@link routeStyles}, {@link copyChunks} and {@link buildAssets} at once, so none can be forgotten
+   * (a forgotten `styles` ships unstyled pages); an option given explicitly still wins.
+   */
+  readonly client?: BuildManifest
   /** The content-hashed client entry URL (from `buildClient`'s manifest) - **baked** into the generated
-   * server manifest, since a disk-less worker can't read `manifest.json` at runtime. */
-  readonly clientEntry: string
+   * server manifest, since a disk-less worker can't read `manifest.json` at runtime. Required unless
+   * {@link client} is given. */
+  readonly clientEntry?: string
   /** The app's aggregate stylesheet URLs (`buildClient`'s `BuildManifest.css`) - baked into the generated
    * manifest so the server entry hands them to `createWebApp` (→ `<link rel="stylesheet">`). Omit ⇒ no CSS
    * link (the built SSR page would otherwise render unstyled). */
@@ -827,6 +840,12 @@ export interface BuildServerOptions {
   readonly routeStyles?: Readonly<Record<string, readonly string[]>> | undefined
   /** Copy chunk URLs by locale (`buildClient`'s `BuildManifest.copyChunks`) - baked as `copyChunks`. */
   readonly copyChunks?: Readonly<Record<string, string>> | undefined
+  /**
+   * Every file the build emitted, by request path (`buildClient`'s `assets` plus its `publicFiles`):
+   * baked as `buildAssets` and `isBuildAsset(pathname)` for a host policy or a hand-written static
+   * handler. Defaults from {@link client}; without either, the manifest exports neither name.
+   */
+  readonly buildAssets?: readonly string[] | undefined
   /** How framework-owned stylesheet links should activate before hydration (default `"blocking"`). */
   readonly cssLoading?: CssLoadingMode
   /** Route/layout file → import specifier in the generated manifest (default: a relative path from the
@@ -1098,6 +1117,12 @@ function formatRefusedFiles(refused: ReadonlyMap<string, string>, root: string):
   return `[nifra/web] the browser build reached code that may not ship to a browser:\n${lines.join("\n")}`
 }
 
+export {
+  checkHostReach,
+  type HostReachOptions,
+  type HostReachReport,
+  type HostReachResult,
+} from "./host-reach.ts"
 export { importGlobPlugin } from "./plugins/import-glob.ts"
 export { zoneGuardPlugin } from "./plugins/zone-guard.ts"
 
@@ -1153,7 +1178,26 @@ const solidWebServerPlugin = (from: string): BunPlugin => ({
  * silently ships a broken worker.
  */
 export async function buildServer(options: BuildServerOptions): Promise<ServerBuild> {
-  const { routesDir, serverEntry, outDir, clientEntry, styles, routeStyles, cssLoading } = options
+  const { routesDir, serverEntry, outDir, client } = options
+  if (
+    client !== undefined &&
+    (typeof client !== "object" ||
+      client === null ||
+      typeof client.entry !== "string" ||
+      !Array.isArray(client.assets))
+  ) {
+    throw new TypeError(
+      "[nifra/web] buildServer `client` must be the manifest buildClient returned ({ entry, assets, ... })",
+    )
+  }
+  const clientEntry = options.clientEntry ?? client?.entry
+  if (clientEntry === undefined) throw missingClientEntry(clientEntry)
+  const styles = options.styles ?? client?.css
+  const routeStyles = options.routeStyles ?? client?.routeStyles
+  const copyChunks = options.copyChunks ?? client?.copyChunks
+  const cssLoading = options.cssLoading ?? client?.cssLoading
+  const buildAssets =
+    options.buildAssets ?? (client === undefined ? undefined : buildAssetPaths(client))
   const entryDir = dirname(serverEntry)
   const manifestFile = options.manifestFile ?? "server-manifest.ts"
   // Default: import routes relative from the generated manifest (next to serverEntry) to routesDir.
@@ -1178,7 +1222,8 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
       styles,
       routeStyles,
       ...(cssLoading !== undefined ? { cssLoading } : {}),
-      ...(options.copyChunks !== undefined ? { copyChunks: options.copyChunks } : {}),
+      ...(copyChunks !== undefined ? { copyChunks } : {}),
+      ...(buildAssets !== undefined ? { buildAssets } : {}),
       lazy,
     }),
   )
@@ -1214,8 +1259,9 @@ export async function buildServer(options: BuildServerOptions): Promise<ServerBu
     ],
   })
   if (!result.success) {
+    const root = resolvePath(options.root ?? dirname(routesDir))
     throw new Error(
-      `[nifra/web] server build failed:\n${result.logs.map((l) => String(l)).join("\n")}`,
+      `[nifra/web] server build failed:\n${result.logs.map((l) => formatBuildLog(l, root)).join("\n")}`,
     )
   }
   // Named as the metafile names outputs: relative to `outdir`.
@@ -1284,6 +1330,7 @@ export const SERVER_ENTRY_OPTIONS = [
   "csp",
   "nonce",
   "i18n",
+  "hostPolicy",
 ] as const
 export type ServerEntryOption = (typeof SERVER_ENTRY_OPTIONS)[number]
 /** Each importable option mapped to the specifier of the module that exports it. */
@@ -1308,6 +1355,13 @@ const PLATFORM_CLIENT_IP_HEADERS: Readonly<Partial<Record<BuildTarget, string>>>
   vercel: "x-real-ip",
 }
 
+// A static path a host's policy refuses is not answered from disk: it falls through to the app, whose
+// own copy of the policy refuses it the same way it refuses a page.
+const HOST_ALLOWS_STATIC =
+  ' && hostPolicy.allows(request.headers.get("host") ?? "", pathname, buildAssets)'
+const NODE_STATIC_ALLOW =
+  "      allow: (host: string, pathname: string) => hostPolicy.allows(host, pathname, buildAssets),"
+
 /** Where a self-hosting build writes its prerendered pages, beside `server.js`. */
 const PRERENDERED_DIR = "_prerendered"
 
@@ -1404,11 +1458,18 @@ export function generateServerEntry(options: {
   if (backendImport !== undefined) {
     lines.push(`import { backend } from ${JSON.stringify(backendImport)}`)
   }
-  lines.push(
-    options.copyChunks === true
-      ? 'import { clientEntry, copyChunks, cssLoading, manifest, styles, routeStyles } from "./server-manifest"'
-      : 'import { clientEntry, cssLoading, manifest, styles, routeStyles } from "./server-manifest"',
-  )
+  // A host policy is checked before the static files too, which takes the build's own file set.
+  const hostPolicy = importedOptions.includes("hostPolicy")
+  const manifestImports = [
+    ...(hostPolicy ? ["buildAssets"] : []),
+    "clientEntry",
+    ...(options.copyChunks === true ? ["copyChunks"] : []),
+    "cssLoading",
+    "manifest",
+    "styles",
+    "routeStyles",
+  ]
+  lines.push(`import { ${manifestImports.join(", ")} } from "./server-manifest"`)
   // Cloudflare needs the fetch-handler shape; the others call app.fetch directly.
   if (target === "cloudflare") lines.push('import { toFetchHandler } from "@nifrajs/core/server"')
   if (target === "node") lines.push('import { serve } from "@nifrajs/node"')
@@ -1416,7 +1477,7 @@ export function generateServerEntry(options: {
   if (target === "deno") {
     lines.push(
       'import { parseByteRange } from "@nifrajs/core/range"',
-      'import { contentTags, contentTypeOf, ifRangeAllowsPartial, isHiddenPath, isNotModified, lastModifiedOf } from "@nifrajs/core/static-file"',
+      'import { CONTENT_SNAPSHOT_MAX, contentTags, contentTypeOf, ifRangeAllowsPartial, isHiddenPath, isNotModified, lastModifiedOf, streamedLastModifiedOf } from "@nifrajs/core/static-file"',
       'import { createHash } from "node:crypto"',
     )
   }
@@ -1442,6 +1503,7 @@ export function generateServerEntry(options: {
     ...(useImport !== undefined ? ["  use,"] : []),
     ...(prerendered.length > 0 ? ["  prerenderedPages,"] : []),
     ...importedOptions.map((name) => `  ${name},`),
+    ...(hostPolicy ? ["  buildAssets,"] : []),
     "  manifest,",
     "  clientEntry,",
     "  styles,",
@@ -1474,7 +1536,7 @@ export function generateServerEntry(options: {
       "  fetch(request: Request, env: Assets, ctx: ExecutionContext) {",
       "    const { pathname } = new URL(request.url)",
       "    // Only the build's own outputs: the hashed bundle prefix and the files it copied.",
-      '    if (env?.ASSETS !== undefined && (pathname.startsWith("/assets/") || PUBLIC_FILES.has(pathname))) {',
+      `    if (env?.ASSETS !== undefined && (pathname.startsWith("/assets/") || PUBLIC_FILES.has(pathname))${hostPolicy ? HOST_ALLOWS_STATIC : ""}) {`,
       "      return env.ASSETS.fetch(request)",
       "    }",
       "    return handler.fetch(request, env as never, ctx)",
@@ -1514,6 +1576,7 @@ export function generateServerEntry(options: {
       '      prefix: "/assets",',
       ...(hashedFiles !== undefined ? ["      hashedFiles: HASHED_FILES,"] : []),
       `      cacheControl: ${JSON.stringify(ONE_DAY)},`,
+      ...(hostPolicy ? [NODE_STATIC_ALLOW] : []),
       "    },",
       "    {",
       "      dir: fileURLToPath(STATIC_ROOT),",
@@ -1521,6 +1584,7 @@ export function generateServerEntry(options: {
       "      files: PUBLIC_FILES,",
       "      immutable: false,",
       `      cacheControl: ${JSON.stringify(ONE_DAY)},`,
+      ...(hostPolicy ? [NODE_STATIC_ALLOW] : []),
       "    },",
       "  ],",
       "})",
@@ -1564,7 +1628,7 @@ export function generateServerEntry(options: {
       "  async fetch(req, server) {",
       "    const { pathname } = new URL(req.url)",
       // Braced: the next emitted line opens with `(`, which would otherwise call the returned value.
-      "    if (staticPath(pathname) !== undefined) {",
+      `    if (staticPath(pathname) !== undefined${hostPolicy ? HOST_ALLOWS_STATIC.replaceAll("request", "req") : ""}) {`,
       "      return staticResponse(req)",
       "    }",
       `    ${markFramed}`,
@@ -1584,7 +1648,7 @@ export function generateServerEntry(options: {
     'Deno.serve({ port: Number(Deno.env.get("PORT") ?? "3000") }, async (req, info) => {',
     "  const { pathname } = new URL(req.url)",
     "  const filePath = staticPath(pathname)",
-    "  if (filePath !== undefined) {",
+    `  if (filePath !== undefined${hostPolicy ? HOST_ALLOWS_STATIC.replaceAll("request", "req") : ""}) {`,
     "    return staticResponse(req, filePath, pathname)",
     "  }",
     `  ${markFramed}`,
@@ -1615,9 +1679,10 @@ function denoStaticResponse(hashed: boolean): string[] {
     "// @ts-ignore - Deno global is present on the Deno runtime this output targets.",
     "const STATIC_REAL: string = await Deno.realPath(STATIC_ROOT)",
     "// One per process: the tag of a file is remembered by its real path.",
-    "const STATIC_TAGS = contentTags(createHash)",
+    "// A stat costs Deno more than hashing a snapshot of up to 24 KiB, so only a larger one is restatted.",
+    "const STATIC_TAGS = contentTags(createHash, { rehashMax: 24 * 1024 })",
     "// Up to this many bytes are read whole to tag a file, and the response is then served from them.",
-    "const STATIC_INLINE_MAX = 256 * 1024",
+    "const STATIC_INLINE_MAX = CONTENT_SNAPSHOT_MAX",
     "const staticResponse = async (req: Request, filePath: string, pathname: string): Promise<Response> => {",
     '  const missing = () => new Response("not found", { status: 404 })',
     '  if (req.method !== "GET" && req.method !== "HEAD") return missing()',
@@ -1652,19 +1717,24 @@ function denoStaticResponse(hashed: boolean): string[] {
     "  const size: number = info.size",
     "  const headers = new Headers(staticHeaders(pathname, real))",
     "  // Deno reports a field the platform does not keep as null; NaN never matches a remembered version.",
-    "  const version = {",
-    "    dev: info.dev,",
-    "    ino: info.ino ?? Number.NaN,",
-    "    size,",
-    "    mtimeMs: info.mtime?.getTime() ?? Number.NaN,",
-    "    ctimeMs: info.ctime?.getTime() ?? Number.NaN,",
-    "  }",
+    "  const versionOf = (stat: { dev: number; ino: number | null; size: number; mtime: Date | null; ctime: Date | null }) => ({",
+    "    dev: stat.dev,",
+    "    ino: stat.ino ?? Number.NaN,",
+    "    size: stat.size,",
+    "    mtimeMs: stat.mtime?.getTime() ?? Number.NaN,",
+    "    ctimeMs: stat.ctime?.getTime() ?? Number.NaN,",
+    "  })",
+    "  const version = versionOf(info)",
+    "  const snapshot = size <= STATIC_INLINE_MAX",
+    "  const lastModified = snapshot ? lastModifiedOf(version) : streamedLastModifiedOf(version)",
+    '  const ifNoneMatch = req.headers.get("if-none-match")',
+    '  const ifModifiedSince = req.headers.get("if-modified-since")',
     "  let whole: Uint8Array<ArrayBuffer> | undefined",
-    "  let moved = false",
-    "  let etag: string | undefined",
+    "  // A HEAD or a 304 sends none of the file, so the tag remembered for this settled version",
+    "  // answers it from the stat alone: a write since that tag would show in the stat.",
+    "  let etag: string | undefined = snapshot ? STATIC_TAGS.cached(real, version) : undefined",
     "  try {",
-    "    etag = STATIC_TAGS.cached(real, version)",
-    "    if (etag === undefined && size <= STATIC_INLINE_MAX) {",
+    '    if (snapshot && (etag === undefined || !(req.method === "HEAD" || isNotModified(ifNoneMatch, ifModifiedSince, etag, lastModified)))) {',
     "      whole = new Uint8Array(size)",
     "      let filled = 0",
     "      while (filled < size) {",
@@ -1673,29 +1743,23 @@ function denoStaticResponse(hashed: boolean): string[] {
     "        filled += read",
     "      }",
     "      if (filled < size) whole = whole.subarray(0, filled)",
-    "      etag = STATIC_TAGS.ofBytes(real, version, whole)",
+    "      etag = await STATIC_TAGS.ofSnapshot(real, version, whole, async () => versionOf(await file.stat()))",
     "    }",
-    "    etag ??= await STATIC_TAGS.ofFile(real, version, async (bytes: Uint8Array, position: number) => {",
-    "      moved = true",
-    "      // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
-    "      await file.seek(position, Deno.SeekMode.Start)",
-    "      return (await file.read(bytes)) ?? 0",
-    "    })",
     "  } catch {",
     "    file.close()",
     "    return missing()",
     "  }",
     '  if (etag !== undefined) headers.set("etag", etag)',
-    "  const lastModified = lastModifiedOf(version)",
     '  if (lastModified !== undefined) headers.set("last-modified", new Date(lastModified).toUTCString())',
-    '  if (isNotModified(req.headers.get("if-none-match"), req.headers.get("if-modified-since"), etag, lastModified)) {',
+    "  if (isNotModified(ifNoneMatch, ifModifiedSince, etag, lastModified)) {",
     "    file.close()",
     '    headers.delete("content-type")',
     "    return new Response(null, { status: 304, headers })",
     "  }",
     '  const rangeHeader = req.method === "GET" ? req.headers.get("range") : null',
     "  const range =",
-    '    rangeHeader !== null && ifRangeAllowsPartial(req.headers.get("if-range"), etag, lastModified)',
+    "  // A streamed body's date is weak: a write during the stream must never splice two versions.",
+    '    rangeHeader !== null && ifRangeAllowsPartial(req.headers.get("if-range"), etag, snapshot ? lastModified : undefined)',
     "      ? parseByteRange(rangeHeader, size)",
     '      : { kind: "none" as const }',
     '  if (req.method === "HEAD" || range.kind === "unsatisfiable") {',
@@ -1746,8 +1810,6 @@ function denoStaticResponse(hashed: boolean): string[] {
     '    headers.set("content-length", String(whole.byteLength))',
     "    return new Response(whole, { headers })",
     "  }",
-    "  // @ts-ignore - Deno global is present on the Deno runtime this output targets.",
-    "  if (moved) await file.seek(0, Deno.SeekMode.Start)",
     '  headers.set("content-length", String(size))',
     "  return new Response(file.readable, { headers })",
     "}",
@@ -1899,6 +1961,7 @@ export const bunBundler: Bundler = {
       ...(input.styles !== undefined ? { styles: input.styles } : {}),
       ...(input.routeStyles !== undefined ? { routeStyles: input.routeStyles } : {}),
       ...(input.copyChunks !== undefined ? { copyChunks: input.copyChunks } : {}),
+      ...(input.buildAssets !== undefined ? { buildAssets: input.buildAssets } : {}),
       ...(input.plugins ? { plugins: input.plugins as BunPlugin[] } : {}),
       ...(input.define ? { define: input.define } : {}),
       ...(input.cssLoading !== undefined ? { cssLoading: input.cssLoading } : {}),
@@ -2157,6 +2220,7 @@ export async function buildTargetWith(
     ...(client.css !== undefined ? { styles: client.css } : {}),
     ...(client.routeStyles !== undefined ? { routeStyles: client.routeStyles } : {}),
     ...(client.copyChunks !== undefined ? { copyChunks: client.copyChunks } : {}),
+    buildAssets: buildAssetPaths(client),
     ...(options.serverPlugins ? { plugins: options.serverPlugins } : {}),
     define: { "process.env.NODE_ENV": '"production"', ...(options.define ?? {}) },
     ...(client.cssLoading !== undefined
@@ -2175,10 +2239,16 @@ export async function buildTargetWith(
     cpSync(worker, `${outDir}/${targetPlan.outputFile}`)
     // The app's real patterns, so a directory is only collapsed into a glob once the route table
     // proves nothing can be served beneath it.
-    const rules = cloudflareRouteRules(
-      publicFiles,
-      discoverRoutes(routesDir).routes.map((route) => route.pattern),
-    )
+    // A host policy must see every file request, which Pages answers from the CDN before the worker
+    // when the path is excluded, so with one nothing is: each file costs an invocation, and the
+    // worker serves the allowed ones from ASSETS.
+    const rules =
+      options.optionImports?.hostPolicy === undefined
+        ? cloudflareRouteRules(
+            publicFiles,
+            discoverRoutes(routesDir).routes.map((route) => route.pattern),
+          )
+        : { include: ["/*"], exclude: [], omitted: [] }
     writeFileSync(
       `${outDir}/_routes.json`,
       `${JSON.stringify({ version: 1, include: rules.include, exclude: rules.exclude }, null, 2)}\n`,

package/src/deferred.ts

@@ -47,6 +47,20 @@ function isDeferred(value: unknown): value is Deferred<unknown> {
   )
 }
 
+/** `target[key] = value` runs the prototype setter for a `__proto__` key; define it as data instead. */
+function setOwn(target: Record<string, unknown>, key: string, value: unknown): void {
+  if (key === "__proto__") {
+    Object.defineProperty(target, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    })
+  } else {
+    target[key] = value
+  }
+}
+
 /**
  * Split a loader (or action) result into the **component-facing** data (deferred values carry their
  * assigned `id` + promise, for `<Await>`) and the **client-serializable** data (deferred values
@@ -113,8 +127,8 @@ export function prepareDeferred(
         const r = split(v)
         if (r === undefined) {
           if (fc !== undefined && cl !== undefined) {
-            fc[k] = v
-            cl[k] = v
+            setOwn(fc, k, v)
+            setOwn(cl, k, v)
           }
           continue
         }
@@ -125,12 +139,12 @@ export function prepareDeferred(
             if (!Object.hasOwn(input, prev)) continue
             if (prev === k) break
             const prevValue = input[prev]
-            fc[prev] = prevValue
-            cl[prev] = prevValue
+            setOwn(fc, prev, prevValue)
+            setOwn(cl, prev, prevValue)
           }
         }
-        fc[k] = r.fc
-        cl[k] = r.cl
+        setOwn(fc, k, r.fc)
+        setOwn(cl, k, r.cl)
       }
       return fc === undefined || cl === undefined ? undefined : { fc, cl }
     }

package/src/dev.ts

@@ -65,6 +65,7 @@ import {
   isLoopbackHost,
 } from "./dev-session.ts"
 import { createSsrGraph, type SsrGraph } from "./dev-ssr-graph.ts"
+import { formatBuildLog } from "./diagnostic.ts"
 import { discoverRoutes } from "./fs.ts"
 import { DEFAULT_DEV_PORT, generateClientEntry } from "./index.ts"
 import { DEV_ENTRY_FILE } from "./internal/dev-reserved.ts"
@@ -634,11 +635,6 @@ export async function createDevServer(options: DevServerOptions): Promise<DevSer
  * Overlapping runs are collapsed - a save during a bundle queues exactly one re-run, so a burst of edits
  * cannot pile up builds behind each other.
  */
-/**
- * Format a client-build rejection for the guard's report. Bun.build rejects with an AggregateError
- * whose message is just "Bundle failed" - the actionable part (which file, which import) lives in
- * `.errors`. Surface it, or the guard reports a failure while hiding the reason.
- */
 /** A Host header's name: lowercased, without its port or IPv6 brackets. */
 function hostName(host: string): string {
   const name = host.trim().toLowerCase()
@@ -648,9 +644,14 @@ function hostName(host: string): string {
   return colon === -1 ? name : name.slice(0, colon)
 }
 
+/**
+ * Format a client-build rejection for the guard's report. Bun.build rejects with an AggregateError
+ * whose message is just "Bundle failed" - the actionable part (which file, which import) lives in
+ * `.errors`. Surface it, or the guard reports a failure while hiding the reason.
+ */
 export function buildFailureDetail(err: unknown): string {
   return err instanceof AggregateError && err.errors.length > 0
-    ? err.errors.map((e) => `  ${e instanceof Error ? e.message : String(e)}`).join("\n")
+    ? err.errors.map((e) => `  ${formatBuildLog(e).replaceAll("\n", "\n  ")}`).join("\n")
     : `  ${err instanceof Error ? err.message : String(err)}`
 }
 

package/src/diagnostic.ts

@@ -34,6 +34,49 @@ export {
 /** Shared endpoint name used by both dev pipelines and the agent-facing MCP tools. */
 export const LAST_ERROR_PATH = "/__nifra/last-error"
 
+/** `file` relative to `root` when it sits inside it (the bundler reports real paths, so a symlinked
+ * root is compared by its real path too), else `file` as given. */
+function pathUnder(root: string, file: string): string {
+  const inside = (base: string): string | undefined => {
+    const rel = relative(base, file).replaceAll("\\", "/")
+    return rel === ".." || rel.startsWith("../") || isAbsolute(rel) ? undefined : rel
+  }
+  let real: string | undefined
+  try {
+    real = realpathSync(root)
+  } catch {
+    real = undefined
+  }
+  return inside(root) ?? (real === undefined ? undefined : inside(real)) ?? file
+}
+
+/**
+ * One bundler log as `file:line:column: message`, the source line it points at underneath. Bun's
+ * `BuildMessage`/`ResolveMessage` carry the place in `position`, which their `String()` drops: a
+ * failed build said "Could not resolve: ./db" without naming the module that imported it.
+ */
+export function formatBuildLog(log: unknown, root: string = process.cwd()): string {
+  const message =
+    typeof log === "object" && log !== null && "message" in log && typeof log.message === "string"
+      ? log.message
+      : String(log)
+  const position =
+    typeof log === "object" && log !== null && "position" in log ? log.position : undefined
+  if (typeof position !== "object" || position === null || !("file" in position)) return message
+  const file = typeof position.file === "string" ? position.file : ""
+  if (file === "") return message
+  const where = [
+    pathUnder(root, file),
+    "line" in position && typeof position.line === "number" ? position.line : undefined,
+    "column" in position && typeof position.column === "number" ? position.column : undefined,
+  ]
+    .filter((part) => part !== undefined)
+    .join(":")
+  const text =
+    "lineText" in position && typeof position.lineText === "string" ? position.lineText.trim() : ""
+  return text === "" ? `${where}: ${message}` : `${where}: ${message}\n    ${text}`
+}
+
 /** One parsed stack frame. `file`/`line`/`column` are present only when the frame could be located. */
 export interface DiagnosticFrame {
   readonly raw: string