@brust/core 2.0.0-alpha.1 → 2.0.0-alpha.11

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/tailwind.ts

@@ -0,0 +1,117 @@
+// Tailwind CSS v4 for `brust build` (L32, F135, R33.1-R33.4): brust's own Bun plugin over the app's Tailwind.
+// It does what the official integrations (@tailwindcss/vite, @tailwindcss/postcss) do: `compile()` from
+// `@tailwindcss/node`, a `Scanner` from `@tailwindcss/oxide` over the compiler's sources (the app root unless the
+// stylesheet says `source(...)`, plus every `@source` / `@source not`), then `build(candidates)`. Both packages are
+// resolved from the APP, never bundled into or depended on by brust, so the compiler is the app's pinned
+// `tailwindcss` (`@tailwindcss/node` depends on its own exact `tailwindcss`; the app installs all three at one
+// version, and a mismatch is a loud warning with the command that aligns them).
+import { readFileSync } from 'node:fs'
+import { dirname, relative } from 'node:path'
+import type { BunPlugin } from 'bun'
+import { BuildError } from './errors'
+
+/** The install set (R33.2): one exact version for all three. */
+export const TAILWIND_PACKAGES = ['tailwindcss', '@tailwindcss/node', '@tailwindcss/oxide'] as const
+
+interface SourceEntry {
+  base: string
+  pattern: string
+  negated: boolean
+}
+interface Compiler {
+  root: 'none' | { base: string; pattern: string } | null
+  sources: SourceEntry[]
+  build(candidates: string[]): string
+}
+interface TailwindNode {
+  compile(css: string, o: { base: string; from?: string; shouldRewriteUrls?: boolean; onDependency: (path: string) => void }): Promise<Compiler>
+}
+interface TailwindOxide {
+  Scanner: new (o: { sources: SourceEntry[] }) => { scan(): string[] }
+}
+
+/** The `version` of `pkg` as resolved from `from` (a directory), or undefined when it does not resolve. */
+function versionFrom(pkg: string, from: string): string | undefined {
+  try {
+    return (JSON.parse(readFileSync(Bun.resolveSync(`${pkg}/package.json`, from), 'utf8')) as { version?: string }).version
+  } catch {
+    return undefined
+  }
+}
+
+/** The versions that decide what compiles (R33.3): the app's `tailwindcss`, the `tailwindcss` that
+ * `@tailwindcss/node` imports (the compiler), and the two integration packages. */
+export function tailwindVersions(appRoot: string): { app?: string; compiler?: string; node?: string; oxide?: string } {
+  let compiler: string | undefined
+  try {
+    compiler = versionFrom('tailwindcss', dirname(Bun.resolveSync('@tailwindcss/node/package.json', appRoot)))
+  } catch {}
+  return { app: versionFrom('tailwindcss', appRoot), compiler, node: versionFrom('@tailwindcss/node', appRoot), oxide: versionFrom('@tailwindcss/oxide', appRoot) }
+}
+
+/** The oldest Tailwind this plugin runs (review F1): 4.0's `compile()` has no `sources` (it takes globs), so its build
+ * would crash mid-way; 4.1.0 is the first with the API the official integrations use today. */
+export const TAILWIND_FLOOR = '4.1.0'
+/** The version brust is tested with (create-app pins the same); the command that lifts an app off an old Tailwind names it. */
+export const TAILWIND_TESTED = '4.3.3'
+
+/** `a < b` for plain `major.minor.patch` versions (a pre-release suffix counts as its base version). */
+export function versionBelow(a: string, b: string): boolean {
+  const n = (v: string) => v.split('-')[0]!.split('.').map((x) => Number(x) || 0)
+  const [x, y] = [n(a), n(b)]
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0)
+  return false
+}
+
+const addCommand = (v: string) => `bun add -d --exact ${TAILWIND_PACKAGES.map((p) => `${p}@${v}`).join(' ')}`
+
+/** The Tailwind plugin of the CSS build, resolved from the app. Missing packages → `tailwind-missing` with the
+ * exact install command; versions that differ → one warning through `log` with the command that aligns them.
+ * `uses(file)` says whether a stylesheet needs the compiler (it, or a relative `@import` of it, uses Tailwind);
+ * other stylesheets stay Bun's. */
+export async function loadTailwind(appRoot: string, usedBy: string, uses: (file: string) => boolean, log?: (s: string) => void): Promise<BunPlugin> {
+  const v = tailwindVersions(appRoot)
+  const missing = TAILWIND_PACKAGES.filter((p) => versionFrom(p, appRoot) === undefined)
+  if (missing.length > 0)
+    throw new BuildError(
+      'tailwind-missing',
+      `${relative(appRoot, usedBy)} uses Tailwind CSS, but ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not installed in the app: run \`${v.app ? addCommand(v.app) : `bun add -d ${TAILWIND_PACKAGES.map((p) => `${p}@4`).join(' ')}`}\``,
+    )
+  const old = (
+    [
+      ['tailwindcss', v.app],
+      ['the compiler tailwindcss', v.compiler],
+      ['@tailwindcss/node', v.node],
+      ['@tailwindcss/oxide', v.oxide],
+    ] as const
+  ).filter(([, ver]) => ver !== undefined && versionBelow(ver, TAILWIND_FLOOR))
+  if (old.length > 0)
+    throw new BuildError(
+      'tailwind-version',
+      `${relative(appRoot, usedBy)} uses Tailwind CSS, but ${old.map(([p, ver]) => `${p} ${ver}`).join(', ')} ${old.length > 1 ? 'are' : 'is'} older than ${TAILWIND_FLOOR}, the oldest brust builds with: run \`${addCommand(TAILWIND_TESTED)}\``,
+    )
+  if (new Set([v.app, v.compiler, v.node, v.oxide]).size > 1)
+    log?.(
+      `[brust] warning tailwind-version the app has tailwindcss ${v.app}, but the compiler is tailwindcss ${v.compiler} (@tailwindcss/node ${v.node}, @tailwindcss/oxide ${v.oxide}): install one version of all three: ${addCommand(v.app!)}`,
+    )
+  const node = (await import(Bun.resolveSync('@tailwindcss/node', appRoot))) as TailwindNode
+  const oxide = (await import(Bun.resolveSync('@tailwindcss/oxide', appRoot))) as TailwindOxide
+  return {
+    name: 'brust-tailwind',
+    setup(b) {
+      b.onLoad({ filter: /\.css$/ }, async (a) => {
+        if (!uses(a.path)) return undefined // Bun's own loader (CSS Modules included)
+        const css = readFileSync(a.path, 'utf8')
+        const compiler = await node.compile(css, { base: dirname(a.path), from: a.path, shouldRewriteUrls: true, onDependency: () => {} })
+        const root: SourceEntry[] =
+          compiler.root === 'none' ? [] : compiler.root === null ? [{ base: appRoot, pattern: '**/*', negated: false }] : [{ ...compiler.root, negated: false }]
+        const scanner = new oxide.Scanner({ sources: [...root, ...compiler.sources] })
+        let out = compiler.build(scanner.scan())
+        // `@reference "./app.css"` pulls in Tailwind's license banner too; only the file that imports Tailwind ships it
+        // (one banner per page, as before)
+        if (!/@import\s+(?:url\(\s*)?["']tailwindcss["']/.test(css)) out = out.replace(/\/\*! tailwindcss v[^*]*\*\/\s*/g, '')
+        return { contents: out, loader: 'css' }
+      })
+    },
+  }
+}