@brust/core 2.0.0-alpha.2 → 2.0.0-alpha.4

package/src/build/ssg.ts

@@ -0,0 +1,146 @@
+// `brust build --target static` planner (gaps round L9, R9.2-R9.3): which paths to render and the
+// file each one is written to. Pure: no server, no filesystem. `params()` results come in resolved.
+import type { FlatRoute, RouteSsgConfig } from '../routes'
+import { BuildError } from './errors'
+
+/** The path the `*` route is rendered at: no route matches it, so the server answers the 404 page. */
+export const NOT_FOUND_PATH = '/__brust_ssg_not_found__'
+
+export interface PlannedPage {
+  /** The request path (each `{name}` value percent-encoded). */
+  path: string
+  /** Relative to the static dir: `index.html`, `docs.html`, `docs/x.html`, `404.html`. */
+  file: string
+  routeId: string
+  pattern: string
+  /** 200, or 404 for the `*` route. */
+  expect: 200 | 404
+}
+
+export interface StaticPlan {
+  pages: PlannedPage[]
+  /** Routes `ssg: false` left out (listed in the report). */
+  skipped: { routeId: string; pattern: string }[]
+  /** No `*` route: the build writes a default 404.html. */
+  defaultNotFound: boolean
+}
+
+/** A leaf's own `ssg` field (the last node of its chain). */
+export function ssgOf(leaf: FlatRoute): RouteSsgConfig | undefined {
+  return leaf.chain[leaf.chain.length - 1]?.ssg
+}
+
+const SEGMENT = /\{(\*?)([^}]*)\}/g
+
+/** The `{name}` / `{*name}` segment names of a pattern, in order. */
+export function patternParams(pattern: string): { name: string; rest: boolean }[] {
+  return [...pattern.matchAll(SEGMENT)].map((m) => ({ name: m[2]!, rest: m[1] === '*' }))
+}
+
+/** The file a request path is written to: `/` → `index.html`, `/a/b` → `a/b.html` (decoded, so a
+ * host that decodes the URL finds it). A segment that is not valid percent-encoding (a stray `%`)
+ * is a `ssg-param-encoding` error naming `where` (review N1), never a URIError. */
+export function fileFor(path: string, where = path): string {
+  if (path === '/') return 'index.html'
+  const decoded = path
+    .slice(1)
+    .split('/')
+    .map((s) => {
+      try {
+        return decodeURIComponent(s)
+      } catch {
+        throw new BuildError('ssg-param-encoding', `${where}: path segment ${JSON.stringify(s)} is not valid percent-encoding (write a literal % as %25)`)
+      }
+    })
+    .join('/')
+  return `${decoded}.html`
+}
+
+/** `encodeURIComponent`, as an `ssg-param-encoding` error naming `where` for a lone surrogate (review N1). */
+function encodeSegment(v: string, where: string): string {
+  try {
+    return encodeURIComponent(v)
+  } catch {
+    throw new BuildError('ssg-param-encoding', `${where} = ${JSON.stringify(v)} is not encodable (a lone UTF-16 surrogate)`)
+  }
+}
+
+/** One `{name}` value: a non-empty string; `/` only in a `{*rest}` value, and never an empty, `.`
+ * or `..` segment (the file name would leave its directory). */
+function checkValue(leaf: FlatRoute, i: number, name: string, rest: boolean, v: unknown): string {
+  const where = `route ${leaf.id} (${leaf.pattern}) ssg.params()[${i}].${name}`
+  if (typeof v !== 'string' || v === '') throw new BuildError('ssg-params', `${where} is ${v === '' ? 'empty' : 'missing'}: every {${name}} needs a non-empty string`)
+  if (!rest && v.includes('/')) throw new BuildError('ssg-params', `${where} = ${JSON.stringify(v)} contains '/': a {${name}} value is one path segment`)
+  for (const seg of v.split('/'))
+    if (seg === '' || seg === '.' || seg === '..') throw new BuildError('ssg-params', `${where} = ${JSON.stringify(v)} has an empty, '.' or '..' segment`)
+  return v
+}
+
+/** Plans every page. `params` holds each dynamic route's resolved `ssg.params()` by route id. */
+export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>): StaticPlan {
+  const pages: PlannedPage[] = []
+  const skipped: StaticPlan['skipped'] = []
+  let catchAll: FlatRoute | undefined
+  for (const leaf of leaves) {
+    const ssg = ssgOf(leaf)
+    if (ssg === false) {
+      skipped.push({ routeId: leaf.id, pattern: leaf.pattern })
+      continue
+    }
+    if (leaf.catchAll) {
+      catchAll = leaf
+      continue
+    }
+    const names = patternParams(leaf.pattern)
+    if (names.length === 0) {
+      pages.push({ path: leaf.pattern, file: fileFor(leaf.pattern, `route ${leaf.id} (${leaf.pattern})`), routeId: leaf.id, pattern: leaf.pattern, expect: 200 })
+      continue
+    }
+    if (!ssg || ssg.params === undefined)
+      throw new BuildError(
+        'ssg-params-missing',
+        `route ${leaf.id} (${leaf.pattern}) is dynamic: add ssg: { params: () => [{ ${names.map((n) => `${n.name}: '…'`).join(', ')} }] } or ssg: false`,
+      )
+    const recs = params.get(leaf.id)
+    if (!Array.isArray(recs)) throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params() must return an array of records`)
+    recs.forEach((rec, i) => {
+      if (typeof rec !== 'object' || rec === null || Array.isArray(rec)) throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params()[${i}] is not a record`)
+      const r = rec as Record<string, unknown>
+      let k = 0
+      const path = leaf.pattern.replace(SEGMENT, () => {
+        const { name, rest } = names[k++]!
+        const v = checkValue(leaf, i, name, rest, r[name])
+        return v
+          .split('/')
+          .map((seg) => encodeSegment(seg, `route ${leaf.id} (${leaf.pattern}) ssg.params()[${i}].${name}`))
+          .join('/')
+      })
+      pages.push({ path, file: fileFor(path, `route ${leaf.id} (${leaf.pattern})`), routeId: leaf.id, pattern: leaf.pattern, expect: 200 })
+    })
+  }
+  const seen = new Map<string, PlannedPage>()
+  // Keyed case-folded (review N2): macOS and Windows file systems are case-insensitive, so `/A` and
+  // `/a` would overwrite each other's file.
+  for (const p of pages) {
+    const key = p.file.toLowerCase()
+    const prev = seen.get(key)
+    if (prev && prev.file === p.file) throw new BuildError('ssg-params', `${prev.path} (route ${prev.routeId}) and ${p.path} (route ${p.routeId}) both write ${p.file}`)
+    if (prev)
+      throw new BuildError(
+        'ssg-path-collision',
+        `${prev.path} (route ${prev.routeId}, ${prev.file}) and ${p.path} (route ${p.routeId}, ${p.file}) differ only by case: on a case-insensitive file system one file overwrites the other`,
+      )
+    seen.set(key, p)
+  }
+  if (seen.has('404.html')) throw new BuildError('ssg-params', `${seen.get('404.html')!.path} would overwrite 404.html`)
+  if (catchAll) pages.push({ path: NOT_FOUND_PATH, file: '404.html', routeId: catchAll.id, pattern: catchAll.pattern, expect: 404 })
+  return { pages, skipped, defaultNotFound: catchAll === undefined }
+}
+
+/** The output paths `ssg.params()` must be resolved for: dynamic leaves with `ssg.params`. */
+export function paramRoutes(leaves: FlatRoute[]): FlatRoute[] {
+  return leaves.filter((l) => {
+    const ssg = ssgOf(l)
+    return !l.catchAll && ssg && ssg.params !== undefined && patternParams(l.pattern).length > 0
+  })
+}

package/src/build/static-worker.ts

@@ -0,0 +1,91 @@
+// `brust build --target static` with `[actions]` (gaps round L12, R12.1): the static tree plus a
+// Cloudflare Pages advanced-mode Worker that serves ONLY the action prefix.
+//   static/_worker.js/index.js   a WorkerEntrypoint: the action prefix -> the Cloudflare core, everything else -> env.ASSETS
+//   static/_worker.js/core/      the `--target cloudflare` worker tree (glue + wasm + brust-app.js), verbatim
+//   static/_routes.json          include: the prefix only, so pages and assets never invoke the Worker
+//   wrangler.jsonc         the Pages project file (name, compatibility date); sits next to `static/`
+import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { type CfPrepared, cacheNeeds } from './cloudflare'
+import { workerNameOf } from './cf-wrangler'
+import { BuildError } from './errors'
+import { CF_MIN_COMPAT_DATE } from './config'
+import type { CacheRecord } from './manifest'
+
+/** `.assetsignore`: the Worker source and the routes file are deploy inputs, never public assets. */
+export const ASSETS_IGNORE = '_worker.js\n_routes.json\n.assetsignore\n'
+
+/** The deploy inputs the Worker answers with a 404 (N1). */
+export const HIDDEN = ['/_worker.js', '/_worker.js/*', '/_routes.json', '/.assetsignore']
+
+/** `_routes.json` (R12.1): the prefix itself and everything under it reach the Worker, and so do the
+ * deploy inputs (N1): a static host that would otherwise serve `_worker.js/*` as files (the local
+ * `wrangler pages dev` does) is answered by the Worker's 404 instead. Pages and assets never do. */
+export function routesJson(prefix: string): string {
+  return `${JSON.stringify({ version: 1, include: [prefix, `${prefix}/*`, ...HIDDEN], exclude: [] }, null, 2)}\n`
+}
+
+/** `_worker.js/index.js`. Pages' pipeline wants a module object with `fetch`, not the class the core
+ * exports (a WorkerEntrypoint whose `fetch` reads `this.env` and `this.ctx`), so the core's method is
+ * called with exactly those two. A request that reaches the Worker and is not an action (a path
+ * `_routes.json` keeps away, or a probe) falls through to the static files, except the deploy inputs
+ * themselves (`_worker.js/*`, `_routes.json`, `.assetsignore`), which are a 404 whatever serves the assets (N1). */
+export function workerSource(main: string, prefix: string): string {
+  const q = JSON.stringify
+  return `${[
+    '// generated by `brust build --target static` (actions on Pages) — do not edit',
+    `import Core from ${q(`./core/${main}`)}`,
+    `const PREFIX = ${q(prefix)}`,
+    'export default {',
+    '  fetch(request, env, ctx) {',
+    '    const path = new URL(request.url).pathname',
+    '    if (path === PREFIX || path.startsWith(`${PREFIX}/`)) return Core.prototype.fetch.call({ env, ctx }, request)',
+    '    let plain = path',
+    '    try { plain = decodeURIComponent(path) } catch {}',
+    '    if (/^\\/(_worker\\.js(\\/|$)|_routes\\.json$|\\.assetsignore$)/i.test(plain)) return new Response("Not Found", { status: 404 })',
+    '    return env.ASSETS.fetch(request)',
+    '  },',
+    '}',
+  ].join('\n')}\n`
+}
+
+/** The Pages project file: bindings and secrets are the user's (`wrangler pages` / the dashboard), never baked. */
+export function pagesConfig(p: CfPrepared): string {
+  const name = p.cfg.name ?? (p.pkgName ? workerNameOf(p.pkgName) : undefined)
+  const compatibilityDate = p.cfg.compatibilityDate ?? p.core.meta.compatibilityDate
+  if (compatibilityDate < CF_MIN_COMPAT_DATE) throw new BuildError('config', `compatibility_date ${compatibilityDate} is older than ${CF_MIN_COMPAT_DATE}`)
+  const c = { ...(name !== undefined ? { name } : {}), pages_build_output_dir: './static', compatibility_date: compatibilityDate }
+  return `// generated by \`brust build --target static\` — bindings and secrets: \`wrangler pages secret put\` / the dashboard (docs/cloudflare.md §12)\n${JSON.stringify(c, null, 2)}\n`
+}
+
+/** R12: `[cache]` does not apply to static pages, and the Worker serves actions only, so an adapter
+ * that needs a Cloudflare binding (KV, Durable Object) has nowhere to be used: refused before any write. */
+export function assertNoCacheBindings(cache: Pick<CacheRecord, 'adapter' | 'broadcast' | 'options' | 'broadcastOptions'> | null | undefined): void {
+  const need = cacheNeeds(cache ?? undefined)
+  if (need)
+    throw new BuildError(
+      'ssg-actions-cache',
+      `[cache] adapter "${cache!.adapter}" needs a Cloudflare binding (${[need.kv && `KV ${need.kv}`, need.do && `Durable Object ${need.do}`].filter(Boolean).join(', ')}), which the static + actions Worker does not carry (static pages are never cached, the Worker serves actions only); drop [cache], or use --target cloudflare`,
+    )
+}
+
+/** Turns `<dist>/cf/` (built by `buildCloudflare`) into the Pages Worker inside `<dist>/static/`, then
+ * drops `cf/`: the build is `--target static`, its only output is `static/`. */
+export function writeStaticWorker(dist: string, actions: { prefix: string }, p: CfPrepared, log: (s: string) => void): void {
+  const staticDir = join(dist, 'static')
+  const worker = join(dist, 'cf', 'worker')
+  if (!existsSync(join(worker, p.core.meta.main))) throw new BuildError('cf-wasm', `the Cloudflare build wrote no worker/${p.core.meta.main}`)
+  const out = join(staticDir, '_worker.js')
+  rmSync(out, { recursive: true, force: true })
+  cpSync(worker, join(out, 'core'), { recursive: true })
+  writeFileSync(join(out, 'index.js'), workerSource(p.core.meta.main, actions.prefix))
+  writeFileSync(join(staticDir, '_routes.json'), routesJson(actions.prefix))
+  // Workers Static Assets uploads the whole directory as public files unless told otherwise; Pages never serves these two.
+  writeFileSync(join(staticDir, '.assetsignore'), ASSETS_IGNORE)
+  writeFileSync(join(dist, 'wrangler.jsonc'), pagesConfig(p))
+  const report = join(staticDir, 'ssg.json')
+  const json = JSON.parse(readFileSync(report, 'utf8')) as Record<string, unknown>
+  writeFileSync(report, `${JSON.stringify({ ...json, actions: { prefix: actions.prefix, worker: '_worker.js' } }, null, 2)}\n`)
+  rmSync(join(dist, 'cf'), { recursive: true, force: true })
+  log(`[brust] static: actions under ${actions.prefix} are served by _worker.js (_routes.json keeps pages and assets off the Worker)`)
+}

package/src/build/static.ts

@@ -0,0 +1,258 @@
+// `brust build --target static` (gaps round L9, R9.1-R9.5): after the normal dist is built, render
+// every planned page through the real server (a child process, `ssg-render.ts`) and write
+// `<out>/static/`: one HTML file per page, `404.html`, the assets the native host serves
+// (`layoutAssets`), `_headers`, `_redirects` and an `ssg.json` report. The layout is what
+// Cloudflare Pages and Workers Static Assets (`not_found_handling = "404-page"`) serve as is.
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { FlatRoute } from '../routes'
+import { layoutAssets } from './cf-assets'
+import { BuildError } from './errors'
+import type { Rendered } from './ssg-render'
+import { assertNoCacheBindings } from './static-worker'
+import { NOT_FOUND_PATH, type PlannedPage, type StaticPlan, paramRoutes, planStatic, ssgOf } from './ssg'
+
+export interface StaticOptions {
+  /** `--strict`: a loader reading the request fails the build instead of warning. */
+  strict: boolean
+}
+
+/** The request reads of one cache key expression (the server's grammar, through the addon). */
+export type ExprReads = (expr: string) => string[]
+
+/** R9.3/R9.4: everything that refuses a static build, checked before a byte is written; then the
+ * resolved plan. `actions`: whether `[actions]` is configured. */
+export async function prepareStatic(
+  leaves: FlatRoute[],
+  actions: boolean,
+  reads: ExprReads,
+  log: (s: string) => void,
+  cache?: Parameters<typeof assertNoCacheBindings>[0],
+): Promise<StaticPlan> {
+  // L12: `[actions]` makes the output hybrid (static pages + a Pages Worker for the action prefix).
+  if (actions) assertNoCacheBindings(cache)
+  let cacheInfo = false
+  for (const leaf of leaves) {
+    const cache = leaf.chain[leaf.chain.length - 1]?.cache
+    if (!cache || ssgOf(leaf) === false) continue
+    cacheInfo = true
+    for (const [field, expr] of [
+      ['prefix', cache.prefix],
+      ['bypass', typeof cache.bypass === 'string' ? cache.bypass : undefined],
+    ] as const) {
+      if (expr === undefined) continue
+      let r: string[]
+      try {
+        r = reads(expr)
+      } catch (e) {
+        throw new BuildError('ssg-varies', `route ${leaf.id} (${leaf.pattern}) cache.${field}: ${(e as Error).message}`)
+      }
+      if (r.length > 0)
+        throw new BuildError(
+          'ssg-varies',
+          `route ${leaf.id} (${leaf.pattern}) cache.${field} reads ${r.join(', ')}: the page varies per request, and a static file is one page for everyone (set ssg: false on the route, or drop the read)`,
+        )
+    }
+  }
+  if (cacheInfo) log('[brust] static: cache.ttl_seconds does not apply to static files (ignored)')
+  const params = new Map<string, unknown>()
+  for (const leaf of paramRoutes(leaves)) {
+    const ssg = ssgOf(leaf)
+    if (!ssg || !ssg.params) continue
+    try {
+      params.set(leaf.id, await ssg.params())
+    } catch (e) {
+      throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params() threw: ${(e as Error).message ?? String(e)}`)
+    }
+  }
+  return planStatic(leaves, params)
+}
+
+export interface StaticReport {
+  pages: { path: string; file: string; routeId: string }[]
+  redirects: { from: string; to: string; status: number }[]
+  skipped: { routeId: string; pattern: string }[]
+  notFound: { file: '404.html'; routeId: string | null }
+  warnings: string[]
+}
+
+type SsgRecord =
+  | { kind: 'read'; routeId: string; path: string; field: string; key: string }
+  | { kind: 'headers'; routeId: string; path: string; names: string[] }
+
+const DEFAULT_404 =
+  '<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>404 Not Found</title></head><body><h1>404 Not Found</h1></body></html>\n'
+
+/** A `_redirects` source as Cloudflare Pages matches it (review N4): the decoded path, with only what
+ * the file format or the decoding needs escaped (whitespace and control characters, and `%`, so a
+ * literal `%` is not read as an escape). Non-ASCII stays as UTF-8. */
+export function redirectSource(path: string): string {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(path)
+  } catch {
+    decoded = path
+  }
+  return decoded.replace(/[\s%\u0000-\u001f\u007f]/gu, (c) => encodeURIComponent(c))
+}
+
+const text = (r: Rendered) => Buffer.from(r.body, 'base64').toString('utf8')
+const excerpt = (s: string) => (s.length > 300 ? `${s.slice(0, 300)}…` : s).replace(/\s+/g, ' ').trim()
+
+/** Spawns the render child against the dist at `dist`; the rendered responses in plan order and
+ * the loader records. `cwd` is the app root (its `brust.toml` is the server's config). */
+async function render(dist: string, entry: string, cwd: string, paths: string[]): Promise<{ addr: string; rendered: Rendered[]; records: SsgRecord[] }> {
+  const stage = join(dist, '.ssg')
+  mkdirSync(stage, { recursive: true })
+  const plan = join(stage, 'plan.json')
+  const out = join(stage, 'rendered.json')
+  const logFile = join(stage, 'records.jsonl')
+  const progress = join(stage, 'progress.txt')
+  writeFileSync(plan, JSON.stringify(paths))
+  writeFileSync(logFile, '')
+  writeFileSync(progress, '')
+  const proc = Bun.spawn([process.execPath, join(import.meta.dir, 'ssg-render.ts')], {
+    cwd,
+    env: {
+      ...process.env,
+      BRUST_DIST_DIR: dist,
+      BRUST_APP_ENTRY: entry,
+      BRUST_SSG: '1',
+      BRUST_SSG_PLAN: plan,
+      BRUST_SSG_OUT: out,
+      BRUST_SSG_LOG: logFile,
+      BRUST_SSG_PROGRESS: progress,
+      BRUST_ADDR: '127.0.0.1',
+      BRUST_PORT: '',
+    },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  // Review N3: the whole render is bounded too; past it the child (our own PID) is killed.
+  const totalMs = Number(process.env.BRUST_SSG_TIMEOUT_MS) || 600_000
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<'late'>((r) => {
+    timer = setTimeout(() => r('late'), totalMs)
+  })
+  const texts = Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()])
+  const first = await Promise.race([proc.exited, late])
+  clearTimeout(timer)
+  if (first === 'late') {
+    proc.kill('SIGKILL')
+    await proc.exited
+    const last = readFileSync(progress, 'utf8').trim().split('\n').pop() || '(before the first page)'
+    throw new BuildError('ssg-timeout', `the render took longer than ${totalMs} ms (BRUST_SSG_TIMEOUT_MS); it was rendering ${last}`)
+  }
+  const code = first
+  const [stdout, stderr] = await texts
+  const result = existsSync(out) ? (JSON.parse(readFileSync(out, 'utf8')) as { addr: string; pages?: Rendered[]; timeout?: { path: string; ms: number } }) : null
+  if (result?.timeout)
+    throw new BuildError('ssg-timeout', `GET ${result.timeout.path} did not answer within ${result.timeout.ms} ms (BRUST_SSG_PAGE_TIMEOUT_MS)`)
+  if (code !== 0 || !result?.pages) throw new BuildError('ssg-render', `the render server failed (exit ${code}):\n${(stderr || stdout).trim()}`)
+  const { addr, pages: rendered } = result as { addr: string; pages: Rendered[] }
+  const records = readFileSync(logFile, 'utf8')
+    .split('\n')
+    .filter((l) => l !== '')
+    .map((l) => JSON.parse(l) as SsgRecord)
+  rmSync(stage, { recursive: true, force: true })
+  return { addr, rendered, records }
+}
+
+/** Renders `plan` against the built dist at `dist` and writes `<dist>/static/`. Returns the report. */
+export async function writeStatic(
+  dist: string,
+  o: { entry: string; appRoot: string; plan: StaticPlan; version: string; strict: boolean; log: (s: string) => void; /** The dir as the user will find it (the build renders into a temp dist). */ shownDir?: string },
+): Promise<StaticReport> {
+  const dir = join(dist, 'static')
+  rmSync(dir, { recursive: true, force: true })
+  const assetsStage = join(dist, '.ssg-assets')
+  const assets = layoutAssets(dist, assetsStage, o.version)
+  renameSync(join(assetsStage, 'assets'), dir)
+  rmSync(assetsStage, { recursive: true, force: true })
+  const warnings = [...assets.warnings]
+  const warn = (w: string) => {
+    warnings.push(w)
+    o.log(w)
+  }
+  for (const w of assets.warnings) o.log(w)
+
+  // R9.4: [cache] does not apply to static files, so the render must not need its adapter (a Redis
+  // that is not running at build time): the render reads a manifest without `cache`, and the dist
+  // keeps the real one for `brust start`.
+  const manifestFile = join(dist, 'manifest.json')
+  const manifest = readFileSync(manifestFile, 'utf8')
+  const parsed = JSON.parse(manifest) as { cache?: unknown }
+  if (parsed.cache) {
+    o.log('[brust] static: [cache] does not apply to static files (ignored while rendering)')
+    writeFileSync(manifestFile, `${JSON.stringify({ ...parsed, cache: null }, null, 2)}\n`)
+  }
+  let r: Awaited<ReturnType<typeof render>>
+  try {
+    r = await render(dist, o.entry, o.appRoot, o.plan.pages.map((p) => p.path))
+  } finally {
+    writeFileSync(manifestFile, manifest)
+  }
+  const { addr, rendered, records } = r
+  const report: StaticReport = { pages: [], redirects: [], skipped: o.plan.skipped, notFound: { file: '404.html', routeId: null }, warnings }
+  const write = (file: string, body: Buffer) => {
+    mkdirSync(dirname(join(dir, file)), { recursive: true })
+    writeFileSync(join(dir, file), body)
+  }
+  rendered.forEach((r, i) => {
+    const page: PlannedPage = o.plan.pages[i]!
+    const where = `GET ${page.path} (route ${page.routeId} ${page.pattern})`
+    const body = Buffer.from(r.body, 'base64')
+    if (text(r).includes(addr) || (r.headers.location ?? '').includes(addr))
+      throw new BuildError('ssg-render', `${where}: the response names the render server's loopback origin; a static page must not (build absolute URLs from a configured origin)`)
+    if (page.expect === 404) {
+      if (r.status !== 404) throw new BuildError('ssg-render', `${where}: the * route answered ${r.status}, want 404: ${excerpt(text(r))}`)
+      write('404.html', body)
+      report.notFound.routeId = page.routeId
+      return
+    }
+    if (r.status === 200) {
+      write(page.file, body)
+      report.pages.push({ path: page.path, file: page.file, routeId: page.routeId })
+      return
+    }
+    if (r.status >= 300 && r.status < 400 && r.headers.location) {
+      report.redirects.push({ from: page.path, to: r.headers.location, status: r.status })
+      return
+    }
+    throw new BuildError('ssg-render', `${where}: status ${r.status}, want 200 (or a redirect()): ${excerpt(text(r))}`)
+  })
+  if (o.plan.defaultNotFound) {
+    write('404.html', Buffer.from(DEFAULT_404))
+    warn("[brust] warning ssg-404 no '*' route: wrote a default 404.html (without one, Cloudflare Pages serves every unknown path as the home page)")
+  }
+  writeFileSync(join(dir, '_redirects'), report.redirects.map((r) => `${redirectSource(r.from)} ${r.to} ${r.status}\n`).join(''))
+
+  const seen = new Set<string>()
+  const reads: string[] = []
+  for (const rec of records) {
+    const leaf = o.plan.pages.find((p) => p.routeId === rec.routeId)
+    const route = `route ${rec.routeId}${leaf ? ` (${leaf.pattern})` : ''}`
+    if (rec.kind === 'headers') {
+      const key = `h ${rec.routeId} ${rec.names.join(',')}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      warn(`[brust] warning ssg-headers ${route}: the loader's response headers (${rec.names.join(', ')}) are dropped: a static file carries none`)
+      continue
+    }
+    const key = `r ${rec.routeId} ${rec.field} ${rec.key}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const what = rec.key === '*' ? `lists req.${rec.field}` : `reads req.${rec.field}[${JSON.stringify(rec.key)}]`
+    reads.push(`${route} ${what} (at ${rec.path}): the static page is what a visitor with no headers, cookies or query sees`)
+  }
+  if (reads.length > 0 && o.strict) throw new BuildError('ssg-request-read', reads.join('\n'))
+  for (const r of reads) warn(`[brust] warning ssg-request-read ${r}`)
+
+  writeFileSync(join(dir, 'ssg.json'), `${JSON.stringify(report, null, 2)}\n`)
+  o.log(
+    `[brust] static: ${report.pages.length} page(s), ${report.redirects.length} redirect(s), 404.html${report.notFound.routeId ? '' : ' (default)'}${report.skipped.length ? `, ${report.skipped.length} route(s) ssg: false` : ''} -> ${o.shownDir ?? dir}`,
+  )
+  return report
+}
+
+export { NOT_FOUND_PATH }

package/src/build-time.ts

@@ -0,0 +1,10 @@
+// `buildTime(() => …)`: the explicit opt-in to evaluate a pure call once, at `brust build` (L2/H1).
+// The compiler recognises the call only when it is imported from `@brust/core`; the closure may be
+// `async` and may use package imports. At runtime (a per-request job, the server) it just runs the
+// closure, so behaviour is identical wherever it is not folded away at build. It is a build error
+// in code that reaches the browser.
+
+/** Runs `fn`. At build the compiler evaluates it once and bakes the result into the template. */
+export function buildTime<T>(fn: () => T): T {
+  return fn()
+}

package/src/cache-adapter/bridge.ts

@@ -0,0 +1,91 @@
+// The worker side of the native `cache` call kind (cache-adapter R2/R3): Rust asks this worker's
+// adapter store to `get` or `set` one page. Every outcome is an A2 frame `[u32 LE meta_len][meta
+// JSON][body]` in the slot; a hit too large for the slot leaves by `putFetchReply` (meta `heap`), a
+// set body arrives by `takeFetchBody`. Never rejects (Rust's own timer bounds the get; the races
+// here guarantee the call settles, so a hung adapter never pins the slot).
+import type { HeapIo } from '../actions-bridge'
+import type { CacheStore, SetMeta, StoredPage } from './types'
+
+export interface CacheBridgeDeps {
+  store: CacheStore | undefined
+  getTimeoutMs: number
+  maxBodyBytes: number
+  count: (name: string) => void
+}
+
+/** A get is answered `{error}` this long after Rust's `get_timeout` gave up on it (the two timers must not race). */
+export const GET_SETTLE_SLACK_MS = 100
+
+/** A set gets this long before it is answered `{error}` (the slot is then released). */
+export const SET_TIMEOUT_MS = 5000
+
+type GetReq = { op: 'get'; key: string }
+type SetReq = { op: 'set'; key: string; status: number; headers: [string, string][]; meta: SetMeta; heap: number }
+
+const enc = new TextEncoder()
+const EMPTY = new Uint8Array(0)
+
+function frame(view: Uint8Array, slot: number, slots: number, meta: object, body: Uint8Array = EMPTY): number {
+  const sub = Math.floor(view.byteLength / Math.max(1, slots))
+  const dst = view.subarray(slot * sub, slot * sub + sub)
+  let m = enc.encode(JSON.stringify(meta))
+  if (4 + m.length + body.length > sub) {
+    m = enc.encode(JSON.stringify({ error: 'cache reply does not fit the slot' }))
+    body = EMPTY
+  }
+  new DataView(dst.buffer, dst.byteOffset, 4).setUint32(0, m.length, true)
+  dst.set(m, 4)
+  dst.set(body, 4 + m.length)
+  return 4 + m.length + body.length
+}
+
+const TIMEOUT = Symbol('timeout')
+function within<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMEOUT> {
+  let t: ReturnType<typeof setTimeout> | undefined
+  return Promise.race([p, new Promise<typeof TIMEOUT>(r => (t = setTimeout(() => r(TIMEOUT), ms)))]).finally(() => clearTimeout(t))
+}
+
+const describe = (e: unknown) => (e instanceof Error ? e.message : String(e))
+
+export async function runCache(requestJson: string, view: Uint8Array, slot: number, slots: number, io: HeapIo, deps: CacheBridgeDeps): Promise<number> {
+  const out = (meta: object, body?: Uint8Array) => frame(view, slot, slots, meta, body)
+  try {
+    const store = deps.store
+    if (!store) return out({ error: 'no cache adapter store in this worker' })
+    const req = JSON.parse(requestJson) as GetReq | SetReq
+    if (req.op === 'get') {
+      const pending = store.get(req.key)
+      pending.catch(() => {})
+      // Rust's own `get_timeout` answers the request (as a timeout); this later race only frees the slot.
+      const r = await within(pending, deps.getTimeoutMs + GET_SETTLE_SLACK_MS)
+      if (r === TIMEOUT) return out({ error: 'get timed out' })
+      if (!r.page) return out({ hit: false, stamp: r.stamp })
+      const p = r.page
+      if (p.body.length > deps.maxBodyBytes) {
+        deps.count('errors')
+        return out({ hit: false, stamp: r.stamp })
+      }
+      const meta = { hit: true, status: p.status, headers: p.headers, stamp: r.stamp, entryStamp: r.entryStamp, storedAt: r.storedAt }
+      const sub = Math.floor(view.byteLength / Math.max(1, slots))
+      if (4 + enc.encode(JSON.stringify(meta)).length + p.body.length <= sub) return out(meta, p.body)
+      if (!io.putReply(slot, p.body)) {
+        deps.count('errors')
+        return out({ hit: false, stamp: r.stamp })
+      }
+      return out({ ...meta, heap: p.body.length })
+    }
+    if (req.op === 'set') {
+      const body = io.takeBody(slot)
+      if (!body || body.length !== req.heap) return out({ error: `set body ${body ? `${body.length} != ${req.heap}` : 'missing'} bytes` })
+      const page: StoredPage = { status: req.status, headers: req.headers, body }
+      const pending = store.set(req.key, page, req.meta)
+      pending.catch(() => {})
+      const ok = await within(pending, SET_TIMEOUT_MS)
+      if (ok === TIMEOUT) return out({ error: 'set timed out' })
+      return out({ ok: ok === true })
+    }
+    return out({ error: `unknown cache op ${(req as { op?: unknown }).op}` })
+  } catch (e) {
+    return out({ error: describe(e) })
+  }
+}