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

package/src/build/bundle.ts

@@ -12,14 +12,23 @@ import { builtinModules } from 'node:module'
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import type { BunPlugin } from 'bun'
 import type { Compiled } from './compile'
+import { cssPlugin } from './css'
 import { BuildError } from './errors'
 
 const REACT_EXTERNALS = ['react', 'react/*', 'react-dom', 'react-dom/*']
-/** Production React (and the production JSX transform: `react/jsx-runtime`, never `jsxDEV`). */
-const PRODUCTION = { 'process.env.NODE_ENV': JSON.stringify('production') }
+/** Production React (and the production JSX transform: `react/jsx-runtime`, never `jsxDEV`). `brust dev` builds set
+ * `BRUST_BUILD_MODE=development` for readable errors and hydration diffs (R13.4); `brust build` never does. */
+export const PRODUCTION: Record<string, string> = { 'process.env.NODE_ENV': JSON.stringify(process.env.BRUST_BUILD_MODE === 'development' ? 'development' : 'production'), __BRUST_DEV__: 'false' }
+
+/** `brust build --dev` (L14, R14.3): the client runtime exposes its live instances on a dev global. `__BRUST_DEV__` is a
+ * define, `false` in every other build, so the minifier removes the dev code from production bundles. */
+export function setDevBuild(dev: boolean): void {
+  PRODUCTION.__BRUST_DEV__ = dev ? 'true' : 'false'
+}
 
 const matchesExternal = (spec: string, external: string[]) =>
-  external.some((p) => (p.endsWith('/*') ? spec.startsWith(p.slice(0, -1)) : spec === p))
+  // A trailing `*` is a prefix (`elysia/*`, `node:*`, `cloudflare:*`): the generated CF entry imports `cloudflare:workers`.
+  external.some((p) => (p.endsWith('*') ? spec.startsWith(p.slice(0, -1)) : spec === p))
 
 /** Staged artifact (by its absolute and its real path) → the component SOURCE file it was
  * generated from. */
@@ -33,6 +42,8 @@ export interface BrowserCtx {
   serverOnly: string[]
   /** Real paths of server-only files (the actions entry, R8): a browser import of one is refused. */
   serverFiles?: string[]
+  /** L19: CSS Module class maps for `cssPlugin` (absent: no CSS was built). */
+  cssMaps?: Map<string, Record<string, string>>
 }
 
 /** Resolution for staged artifacts (`importer` = a staged file registered in `sourceOf`): relative
@@ -145,7 +156,7 @@ function serverOnlyPlugin(ctx: BrowserCtx, violations: string[]): BunPlugin {
 }
 
 const hex = (s: string) => createHash('sha256').update(s).digest('hex').slice(0, 10)
-const write = (file: string, text: string) => {
+export const write = (file: string, text: string) => {
   mkdirSync(dirname(file), { recursive: true })
   writeFileSync(file, text)
 }
@@ -165,7 +176,7 @@ async function browserBuild(
   try {
     res = await Bun.build({
       ...config,
-      plugins: [serverOnlyPlugin(ctx, violations), ...(config.plugins ?? [])],
+      plugins: [serverOnlyPlugin(ctx, violations), cssPlugin(ctx.cssMaps ?? new Map()), ...(config.plugins ?? [])],
       target: 'browser',
       format: 'esm',
       minify: true,
@@ -261,13 +272,22 @@ export async function buildClientChunks(dist: string, compiled: Map<string, Comp
 }
 
 /** Registers a written artifact (by its path and its real path: the importer Bun reports). */
-function stage(sourceOf: SourceOf, file: string, c: Compiled): void {
+export function stage(sourceOf: SourceOf, file: string, c: Compiled): void {
   sourceOf.set(file, c.file)
   sourceOf.set(realpathSync(file), c.file)
 }
 
 const isReact = (c: Compiled) => typeof c.ir.tier === 'object' && c.ir.tier !== null && 'React' in c.ir.tier
 
+/** The `import` line that brings a react-tier component's code in as `local`: its own module, or
+ * for a package export (L22) the export itself. */
+export function componentImport(c: Compiled, local: string): string {
+  const ext = c.ir.external
+  if (!ext) return `import ${local} from ${JSON.stringify(c.file)}`
+  const from = JSON.stringify(ext.source)
+  return ext.export === 'default' ? `import ${local} from ${from}` : `import { ${JSON.stringify(ext.export).replace(/^"|"$/g, '')} as ${local} } from ${from}`
+}
+
 /** The island entry of a react-tier component: registers `(host, props) => …` under its id. A
  * `client_only` component was never server-rendered (its host is empty), so it mounts with
  * `createRoot`; hydrating it would fail (React #418). Everything else hydrates the SSR markup. */
@@ -277,7 +297,7 @@ export function islandShim(c: Compiled): string {
     ? ['createRoot', `createRoot(host, { identifierPrefix: ${JSON.stringify(c.id)} }).render(createElement(Comp, props))`]
     : ['hydrateRoot', `hydrateRoot(host, createElement(Comp, props), { identifierPrefix: ${JSON.stringify(c.id)} })`]
   return (
-    `import { ${api} } from 'react-dom/client'\nimport { createElement } from 'react'\nimport Comp from ${JSON.stringify(c.file)}\n` +
+    `import { ${api} } from 'react-dom/client'\nimport { createElement } from 'react'\n${componentImport(c, 'Comp')}\n` +
     `;((globalThis as any).__brustIslands ||= []).push([${JSON.stringify(c.id)}, (host: Element, props: any) => { ${mount} }])\n` +
     `;(globalThis as any).__brustIslandReady?.()\n`
   )
@@ -334,16 +354,32 @@ const ACTIONS_EXTERNALS = [...JOBS_EXTERNALS, 'elysia', 'elysia/*', '@elysia/*']
 
 /** `dist/actions.js` (M3-F E1): the actions entry for the worker (`target: 'bun'`). No `define`: Elysia
  * and app code read NODE_ENV at runtime (run.ts sets production). */
-export async function buildActions(dist: string, entry: string): Promise<string> {
-  const res = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', external: ACTIONS_EXTERNALS, plugins: [workerStorePlugin] })
+export async function buildActions(dist: string, entry: string, cssMaps: Map<string, Record<string, string>> = new Map()): Promise<string> {
+  const res = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', external: ACTIONS_EXTERNALS, plugins: [cssPlugin(cssMaps), workerStorePlugin] })
   if (!res.success) throw new BuildError('bundle', `actions: ${res.logs.map(String).join('\n')}`)
   write(join(dist, 'actions.js'), await res.outputs[0]!.text())
   return 'actions.js'
 }
 
+/** `dist/cache-adapter.js` (cache adapters R8): a custom adapter module for the worker (`target: 'bun'`), with
+ * the actions externals so it shares the app's dependencies. */
+export async function buildCacheAdapter(dist: string, entry: string, cssMaps: Map<string, Record<string, string>> = new Map()): Promise<string> {
+  const res = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', external: ACTIONS_EXTERNALS, plugins: [cssPlugin(cssMaps)] })
+  if (!res.success) throw new BuildError('bundle', `cache adapter: ${res.logs.map(String).join('\n')}`)
+  write(join(dist, 'cache-adapter.js'), await res.outputs[0]!.text())
+  return 'cache-adapter.js'
+}
+
 /** `dist/jobs.js` (`target: 'bun'`, React and `@brust/core` external): default export
  * `{ [componentId]: { precompute?, ssr? } }`; `ssr` only for react-tier, non-client_only components. */
-export async function buildJobs(dist: string, compiled: Map<string, Compiled>, sourceOf: SourceOf, appRoot: string, stores: string[] = []): Promise<void> {
+export async function buildJobs(
+  dist: string,
+  compiled: Map<string, Compiled>,
+  sourceOf: SourceOf,
+  appRoot: string,
+  stores: string[] = [],
+  cssMaps: Map<string, Record<string, string>> = new Map(),
+): Promise<void> {
   const imports: string[] = ["import { createElement } from 'react'", "import { renderToString } from 'react-dom/server'"]
   const entries: string[] = []
   const storePaths = [...new Set(stores)].sort()
@@ -364,7 +400,7 @@ export async function buildJobs(dist: string, compiled: Map<string, Compiled>, s
       fns.push(`precompute: j${n}.precompute`)
     }
     if (isReact(c) && !c.ir.tier.React.client_only) {
-      imports.push(`import C${n} from ${JSON.stringify(c.file)}`)
+      imports.push(componentImport(c, `C${n}`))
       // Ruling 2bf3775a (R1): the island's component id prefixes React's useId on BOTH sides
       // (the shim's hydrateRoot passes the same prefix), so ids differ across islands.
       fns.push(`ssr: (props: any) => renderToString(createElement(C${n}, props), { identifierPrefix: ${JSON.stringify(c.id)} })`)
@@ -380,7 +416,7 @@ export async function buildJobs(dist: string, compiled: Map<string, Compiled>, s
     format: 'esm',
     define: PRODUCTION,
     external: JOBS_EXTERNALS,
-    plugins: [workerStorePlugin, sourceDirPlugin(sourceOf, appRoot, JOBS_EXTERNALS)],
+    plugins: [cssPlugin(cssMaps), workerStorePlugin, sourceDirPlugin(sourceOf, appRoot, JOBS_EXTERNALS)],
   })
   if (!res.success) throw new BuildError('bundle', `jobs: ${res.logs.map(String).join('\n')}`)
   write(join(dist, 'jobs.js'), await res.outputs[0]!.text())

package/src/build/cf-assets.ts

@@ -0,0 +1,83 @@
+// Static assets for Workers Static Assets (M4-CF R7): only files the native host would serve (`safe_rel` in
+// `crates/brust-core/src/static_rules.rs`), laid out under the URL they are requested at, plus `_headers`.
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const SEG = /^[A-Za-z0-9_.-]+$/
+const IMMUTABLE = 'public, max-age=31536000, immutable'
+const PUBLIC_DEFAULT = 'public, max-age=3600'
+const MAX_RULES = 100
+
+/** `static_rules.rs` `is_hashed`: the stem ends in `-<hex6+>` (lowercase) with at least one digit. */
+export function isHashed(file: string): boolean {
+  const base = file.slice(file.lastIndexOf('/') + 1)
+  const dot = base.lastIndexOf('.')
+  const stem = dot > 0 ? base.slice(0, dot) : base
+  const i = stem.lastIndexOf('-')
+  if (i < 0) return false
+  const h = stem.slice(i + 1)
+  return h.length >= 6 && /^[0-9a-f]+$/.test(h) && /\d/.test(h)
+}
+
+const segOk = (s: string) => s !== '' && !s.startsWith('.') && SEG.test(s)
+
+/** `client/<file>.js|.css`: `is_safe_island_filename` / `is_safe_css_filename`, plus the fonts and images a
+ * stylesheet references (`is_safe_client_asset_filename`, L19). */
+const CLIENT_EXT = /\.(js|css|woff2|woff|ttf|otf|eot|png|jpg|jpeg|gif|webp|avif|svg|ico)$/
+const clientOk = (f: string) => segOk(f) && !f.includes('..') && CLIENT_EXT.test(f)
+
+function walk(dir: string, rel = ''): string[] {
+  const out: string[] = []
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const r = rel ? `${rel}/${e.name}` : e.name
+    if (e.isDirectory()) out.push(...walk(join(dir, e.name), r))
+    else if (e.isFile() || statSync(join(dir, e.name)).isFile()) out.push(r)
+  }
+  return out.sort()
+}
+
+/** Copies the admissible files of `<out>/client` and `<out>/public` into `<cfDir>/assets/...`; returns the
+ * asset-relative paths (`_brust/client/x.js`, `public/img/a.png`) and writes `assets/_headers`. */
+export function layoutAssets(out: string, cfDir: string, version: string): { files: string[]; warnings: string[] } {
+  const assets = join(cfDir, 'assets')
+  mkdirSync(assets, { recursive: true })
+  const files: string[] = []
+  const warnings: string[] = []
+  const copy = (from: string, to: string) => {
+    mkdirSync(dirname(join(assets, to)), { recursive: true })
+    cpSync(from, join(assets, to))
+    files.push(to)
+  }
+  const client = join(out, 'client')
+  if (existsSync(client))
+    for (const f of walk(client)) {
+      if (!f.includes('/') && clientOk(f)) copy(join(client, f), `_brust/client/${f}`)
+      else warnings.push(`[brust] assets: client/${f} is not served natively; skipped`)
+    }
+  const pub = join(out, 'public')
+  if (existsSync(pub))
+    for (const f of walk(pub)) {
+      if (f.split('/').every(segOk)) copy(join(pub, f), `public/${f}`)
+      else warnings.push(`[brust] assets: public/${f} has a name the native host would not serve; skipped`)
+    }
+  const h = headersFile(files, version)
+  warnings.push(...h.warnings)
+  writeFileSync(join(assets, '_headers'), h.text)
+  return { files, warnings }
+}
+
+export function headersFile(files: string[], version: string): { text: string; warnings: string[] } {
+  const warnings: string[] = []
+  const rules: string[] = [
+    `/*\n  X-Content-Type-Options: nosniff\n  X-Powered-By: brust/${version}`,
+    `/_brust/client/*\n  Cache-Control: ${IMMUTABLE}`,
+  ]
+  const pub = files.filter((f) => f.startsWith('public/'))
+  if (rules.length + pub.length <= MAX_RULES)
+    for (const f of pub) rules.push(`/${f}\n  Cache-Control: ${isHashed(f) ? IMMUTABLE : PUBLIC_DEFAULT}`)
+  else if (pub.length > 0) {
+    rules.push(`/public/*\n  Cache-Control: ${PUBLIC_DEFAULT}`)
+    warnings.push(`[brust] assets: ${pub.length} public files exceed the 100-rule _headers limit; one /public/* max-age=3600 rule (no per-file immutable)`)
+  }
+  return { text: `${rules.join('\n\n')}\n`, warnings }
+}

package/src/build/cf-core.ts

@@ -0,0 +1,90 @@
+// Locates `@brust/core-cf` (the wasm core + glue, built by lane M4-CF-3) and reads its `brust` metadata (M4-CF R3, R4).
+// Order: `--wasm-from-source` > env BRUST_CORE_CF_DIR > the app's node_modules > next to @brust/core.
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { BuildError } from './errors'
+
+export interface CoreCfMeta {
+  abi: number
+  /** worker-build entry, relative to `worker/` */
+  main: string
+  glue: string
+  /** dir under `worker/` that holds `brust-app.js` (next to the glue's `raw_module`) */
+  appModuleDir: string
+  compatibilityDate: string
+}
+
+export interface CoreCf {
+  dir: string
+  workerDir: string
+  meta: CoreCfMeta
+  version: string
+  warnings: string[]
+}
+
+export interface ResolveOpts {
+  appRoot: string
+  fromSource: boolean
+  env: Record<string, string | undefined>
+  /** `@brust/core`'s package dir (default: this package) */
+  corePkgDir?: string
+  run?: (cmd: string[], cwd: string) => number
+  which?: (bin: string) => string | null
+}
+
+const HINT = (v: string) => `install it with \`bun add -d @brust/core-cf@${v}\` or pass --wasm-from-source`
+
+function readJson(file: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function fromDir(dir: string, coreVersion: string): CoreCf {
+  const pkg = readJson(join(dir, 'package.json'))
+  const m = pkg?.brust as Partial<CoreCfMeta> | undefined
+  if (!pkg || !m) throw new BuildError('cf-wasm', `${dir}/package.json has no "brust" metadata (not a @brust/core-cf package?)`)
+  if (m.abi !== 1) throw new BuildError('cf-wasm', `@brust/core-cf has abi ${String(m.abi)}; this brust supports abi 1 — upgrade brust or core-cf`)
+  const meta: CoreCfMeta = {
+    abi: 1,
+    main: m.main ?? 'index.js',
+    glue: m.glue ?? m.main ?? 'index.js',
+    appModuleDir: m.appModuleDir ?? '.',
+    compatibilityDate: m.compatibilityDate ?? '2026-10-01',
+  }
+  const workerDir = join(dir, 'worker')
+  if (!existsSync(join(workerDir, meta.main)))
+    throw new BuildError('cf-wasm', `@brust/core-cf has no worker/${meta.main} (${dir}); ${HINT(coreVersion)}`)
+  const version = String(pkg.version ?? '')
+  const warnings: string[] = []
+  if (version !== coreVersion) warnings.push(`[brust] @brust/core-cf ${version} differs from @brust/core ${coreVersion}`)
+  return { dir, workerDir, meta, version, warnings }
+}
+
+export function resolveCoreCf(o: ResolveOpts): CoreCf {
+  const corePkgDir = o.corePkgDir ?? join(import.meta.dir, '..', '..')
+  const coreVersion = String(readJson(join(corePkgDir, 'package.json'))?.version ?? '0.0.0')
+  if (o.fromSource) {
+    const repo = join(corePkgDir, '..', '..')
+    if (!existsSync(join(repo, 'crates', 'brust-wasm'))) throw new BuildError('cf-wasm', 'cf-wasm needs crates/brust-wasm (lane M4-CF-3): --wasm-from-source requires a brust checkout')
+    const which = o.which ?? ((b: string) => Bun.which(b))
+    for (const bin of ['cargo']) if (!which(bin)) throw new BuildError('cf-wasm', `--wasm-from-source needs \`${bin}\` on PATH`)
+    const run = o.run ?? ((cmd, cwd) => Bun.spawnSync(cmd, { cwd, stdio: ['inherit', 'inherit', 'inherit'] }).exitCode)
+    // The build script writes npm/core-cf/worker/ (lane 3 owns it; never bare `worker-build`).
+    const code = run(['bun', join('crates', 'brust-wasm', 'scripts', 'build.ts')], repo)
+    if (code !== 0) throw new BuildError('cf-wasm', `crates/brust-wasm/scripts/build.ts failed (exit ${code})`)
+    return fromDir(join(repo, 'npm', 'core-cf'), coreVersion)
+  }
+  const envDir = o.env.BRUST_CORE_CF_DIR
+  if (envDir) return fromDir(envDir, coreVersion)
+  for (const from of [o.appRoot, corePkgDir]) {
+    try {
+      return fromDir(dirname(Bun.resolveSync('@brust/core-cf/package.json', from)), coreVersion)
+    } catch (e) {
+      if (e instanceof BuildError) throw e
+    }
+  }
+  throw new BuildError('cf-wasm', `@brust/core-cf is not installed; ${HINT(coreVersion)}`)
+}

package/src/build/cf-entry.ts

@@ -0,0 +1,76 @@
+// The generated Cloudflare entry (M4-CF spec §4, R9, R13): ~25 lines that wire the user's routes, jobs and
+// actions into the six exports the wasm glue imports from `./brust-app.js`. Pure: text in, text out.
+export interface CfConfigJson {
+  abi: 1
+  generator: string
+  l1Capacity: number
+  jobCacheCapacity: number
+  stats: boolean
+  edgeCache: 'off'
+  cors?: unknown
+  actions?: { prefix: string; maxBodyBytes: number; maxResponseBytes: number; crossSite: 'reject' | 'allow' }
+  /** The cache adapter (optional under abi 1, cache adapters R13). */
+  cache?: { adapter: string; getTimeoutMs: number; maxBodyBytes: number; namespace: string; buildId: string; epochIntervalMs: number }
+}
+
+/** The cache adapter wiring of the entry: absent → the entry is byte-identical to the no-cache one (D3). */
+export interface CfEntryCache {
+  /** The adapter module (an absolute path, or a built-in package spec). */
+  module: string
+  options: Record<string, unknown>
+  /** A composed built-in broadcast's package spec. */
+  broadcast?: string
+  broadcastOptions?: Record<string, unknown>
+}
+
+export interface CfEntryInput {
+  /** absolute paths; each goes through JSON.stringify */
+  entry: string
+  jobsEntry: string
+  actionsEntry: string | null
+  /** L16: no pages: the routes module and the jobs module are not imported; the handlers serve an empty route table. */
+  actionsOnly?: boolean
+  prefix: string
+  manifestPath: string
+  templatesPath: string
+  config: CfConfigJson
+  cache?: CfEntryCache | null
+  /** A Durable Object is configured: the entry re-exports `BrustCacheDO` (R1; `worker/main.js` re-exports it from this one module). */
+  doClass?: boolean
+}
+
+export function cfEntrySource(i: CfEntryInput): string {
+  const q = JSON.stringify
+  const actions = i.actionsEntry !== null
+  const c = i.cache ?? null
+  const pages = i.actionsOnly !== true
+  return `${[
+    '// generated by `brust build --target cloudflare` — do not edit (M4-CF spec §4)',
+    ...(pages ? [`import * as R from ${q(i.entry)}`, `import J, * as JM from ${q(i.jobsEntry)}`] : []),
+    ...(actions ? [`import A from ${q(i.actionsEntry)}`] : []),
+    `import M from ${q(i.manifestPath)}`,
+    `import T from ${q(i.templatesPath)}`,
+    `import { fetchInScope, flattenRoutes, jsonCall, makeHandlers, noActions } from "@brust/core/server-handlers"`,
+    ...(actions ? ['import { mountActions } from "@brust/core/server-handlers/actions"'] : []),
+    pages
+      ? 'const h = makeHandlers({ leaves: flattenRoutes(R.routes ?? R.default).leaves, jobs: J, manifest: M, stores: JM.stores ?? {} })'
+      : 'const h = makeHandlers({ leaves: [], jobs: {}, manifest: M, stores: {} })',
+    ...(actions ? [`const app = mountActions(A, ${q(i.prefix)}).compile() // startup-phase compile (R9)`] : []),
+    'export const loader = jsonCall(h.loader)',
+    'export const jobs = jsonCall(h.jobs)',
+    actions ? 'export const action = (req) => fetchInScope(app, req)' : 'export const action = noActions',
+    'export const MANIFEST = JSON.stringify(M)',
+    'export const TEMPLATES = T',
+    ...(c
+      ? [
+          `import CACHE from ${q(c.module)}`,
+          ...(c.broadcast ? [`import CACHE_BROADCAST from ${q(c.broadcast)}`] : []),
+          'import { waitUntil } from "cloudflare:workers"',
+          'import { install as installRuntime } from "@brust/core/server-handlers"',
+          `export const install = (rt) => installRuntime(rt, { adapter: CACHE, options: ${JSON.stringify(c.options)}, ${c.broadcast ? `broadcast: CACHE_BROADCAST, broadcastOptions: ${JSON.stringify(c.broadcastOptions ?? {})}, ` : ''}config: ${JSON.stringify(i.config.cache)}, waitUntil })`,
+        ]
+      : ['export { install } from "@brust/core/server-handlers"']),
+    ...(i.doClass ? ['export { BrustCacheDO } from "@brust/cache-cloudflare/do"'] : []),
+    `export const CONFIG = ${q(JSON.stringify(i.config))}`,
+  ].join('\n')}\n`
+}

package/src/build/cf-wrangler.ts

@@ -0,0 +1,169 @@
+// `wrangler.jsonc` for `dist/cf/` (M4-CF R5, R6, R7): the user's app-root config merged with the keys brust owns.
+// Pure apart from `readUserWrangler`. Never adds an `account_id`; copies one only if the user wrote it.
+import { existsSync } from 'node:fs'
+import { isAbsolute, join, relative } from 'node:path'
+import { BuildError } from './errors'
+
+type Json = Record<string, unknown>
+export interface UserWrangler {
+  file: string | null
+  config: Json
+}
+
+export interface MergeOpts {
+  appRoot: string
+  cfDir: string
+  /** `[cloudflare] name` */
+  name?: string
+  pkgName?: string
+  compatibilityDate: string
+  /** worker-build entry, relative to `worker/` (core-cf `brust.main`) */
+  main: string
+  version: string
+  /** L16: an actions-only Worker has no Static Assets (and no ASSETS binding). */
+  noAssets?: boolean
+}
+
+const OWNED = ['main', 'assets', 'compatibility_date', 'no_bundle', 'find_additional_modules', 'base_dir', 'rules', 'build', 'site']
+const CONFIG_FILES = ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml']
+
+export async function readUserWrangler(appRoot: string): Promise<UserWrangler> {
+  const found = CONFIG_FILES.filter((f) => existsSync(join(appRoot, f)))
+  if (found.length > 1) throw new BuildError('cf-config', `more than one wrangler config in ${appRoot}: ${found.join(', ')} — keep one`)
+  const f = found[0]
+  if (!f) return { file: null, config: {} }
+  const text = await Bun.file(join(appRoot, f)).text()
+  try {
+    const parsed = f.endsWith('.toml') ? Bun.TOML.parse(text) : Bun.JSONC.parse(text)
+    return { file: f, config: (parsed ?? {}) as Json }
+  } catch (e) {
+    throw new BuildError('cf-config', `failed to parse ${join(appRoot, f)}: ${(e as Error).message}`)
+  }
+}
+
+const isObj = (v: unknown): v is Json => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/** package.json `name` -> a Worker name: scope dropped, lowercased, non-[a-z0-9-] -> `-`, <= 63. */
+export function workerNameOf(pkgName: string): string {
+  return pkgName.replace(/^@[^/]*\//, '').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 63)
+}
+
+function rebase(o: MergeOpts, p: string): string {
+  return isAbsolute(p) ? p : relative(o.cfDir, join(o.appRoot, p))
+}
+
+function assertNoAssetsBinding(v: unknown, path: string): void {
+  if (Array.isArray(v)) return v.forEach((x, i) => assertNoAssetsBinding(x, `${path}[${i}]`))
+  if (!isObj(v)) return
+  for (const [k, x] of Object.entries(v)) {
+    if (k === 'assets' && path === '') continue
+    if ((k === 'binding' || (k === 'name' && /durable_objects/.test(path))) && x === 'ASSETS') throw new BuildError('cf-config', `wrangler config: a binding named ASSETS (${path || 'root'}) clashes with brust's static-assets binding`)
+    if (k === 'vars' && isObj(x) && 'ASSETS' in x) throw new BuildError('cf-config', 'wrangler config: vars.ASSETS clashes with brust\'s static-assets binding')
+    assertNoAssetsBinding(x, `${path}.${k}`)
+  }
+}
+
+function rebasePaths(o: MergeOpts, block: Json): void {
+  if (Array.isArray(block.d1_databases))
+    for (const d of block.d1_databases)
+      if (isObj(d)) d.migrations_dir = rebase(o, typeof d.migrations_dir === 'string' ? d.migrations_dir : 'migrations')
+  if (typeof block.tsconfig === 'string') block.tsconfig = rebase(o, block.tsconfig)
+  if (isObj(block.alias))
+    for (const [k, v] of Object.entries(block.alias)) if (typeof v === 'string' && v.startsWith('.')) block.alias[k] = rebase(o, v)
+}
+
+function checkFlags(block: Json, where: string): void {
+  if (Array.isArray(block.compatibility_flags) && block.compatibility_flags.some((f) => typeof f === 'string' && /^no_nodejs_compat/.test(f)))
+    throw new BuildError('cf-config', `wrangler config${where}: compatibility_flags "no_nodejs_compat*" is not allowed (AsyncLocalStorage needs nodejs_compat)`)
+}
+
+export function mergeWrangler(user: UserWrangler, o: MergeOpts): { config: Json; warnings: string[] } {
+  const warnings: string[] = []
+  const src = structuredClone(user.config)
+  assertNoAssetsBinding(src, '')
+  checkFlags(src, '')
+  const owned = (k: string, where: string) => warnings.push(`[brust] wrangler: ${where}${k} is owned by brust build --target cloudflare; ignored`)
+  const rest: Json = {}
+  for (const [k, v] of Object.entries(src)) {
+    if (OWNED.includes(k)) owned(k, '')
+    else rest[k] = v
+  }
+  const userName = typeof rest.name === 'string' ? rest.name : undefined
+  if (o.name !== undefined && userName !== undefined && userName !== o.name)
+    warnings.push(`[brust] wrangler: name "${userName}" conflicts with [cloudflare] name "${o.name}"; brust.toml wins`)
+  const name = o.name ?? userName ?? (o.pkgName ? workerNameOf(o.pkgName) : undefined)
+  rebasePaths(o, rest)
+  if (isObj(rest.env))
+    for (const [en, eb] of Object.entries(rest.env)) {
+      if (!isObj(eb)) continue
+      checkFlags(eb, ` env.${en}`)
+      for (const k of OWNED)
+        if (k in eb) {
+          owned(k, `env.${en}.`)
+          delete eb[k]
+        }
+      rebasePaths(o, eb)
+    }
+  const config: Json = {
+    ...(name !== undefined ? { name } : {}),
+    main: `worker/${o.main}`,
+    compatibility_date: o.compatibilityDate,
+    ...(o.noAssets ? {} : { assets: { directory: 'assets', binding: 'ASSETS', run_worker_first: false, html_handling: 'none', not_found_handling: 'none' } }),
+    ...Object.fromEntries(Object.entries(rest).filter(([k]) => k !== 'name')),
+  }
+  return { config, warnings }
+}
+
+export interface CacheNeed {
+  kv?: string
+  do?: string
+}
+
+const KV_SNIPPET = (b: string) => `"kv_namespaces": [{ "binding": "${b}", "id": "<wrangler kv namespace create brust-cache>" }]`
+const DO_SNIPPET = (b: string) =>
+  `"durable_objects": { "bindings": [{ "name": "${b}", "class_name": "BrustCacheDO" }] },\n  "migrations": [{ "tag": "brust-cache-v1", "new_sqlite_classes": ["BrustCacheDO"] }]`
+
+/** Does `block` declare BrustCacheDO as a SQLite class (migrations or `exports`)? `'kv'` = declared only as a KV-backed `new_classes`. */
+function declaresDoClass(block: Json): boolean | 'kv' {
+  if (Array.isArray(block.migrations)) {
+    let kvBacked = false
+    for (const m of block.migrations) {
+      if (!isObj(m)) continue
+      if (Array.isArray(m.new_sqlite_classes) && m.new_sqlite_classes.includes('BrustCacheDO')) return true
+      if (Array.isArray(m.new_classes) && m.new_classes.includes('BrustCacheDO')) kvBacked = true
+    }
+    if (kvBacked) return 'kv'
+  }
+  const e = isObj(block.exports) ? block.exports.BrustCacheDO : undefined
+  return isObj(e) && e.type === 'durable-object' && e.storage === 'sqlite'
+}
+
+/**
+ * R10: the user's wrangler config (top level and every `env.<name>`) must declare the bindings the configured Cloudflare cache needs. Nothing is
+ * added for them. A class declaration (`migrations` / `exports`) is also accepted from the top level for an env block. Pure; `config` is not mutated.
+ */
+export function verifyCacheBindings(config: Json, need: CacheNeed): { ok: true } | { ok: false; message: string } {
+  const problems: string[] = []
+  const blocks: [string, Json][] = [['the top level', config]]
+  if (isObj(config.env)) for (const [n, b] of Object.entries(config.env)) if (isObj(b)) blocks.push([`env.${n}`, b])
+  for (const [where, b] of blocks) {
+    if (need.kv !== undefined) {
+      const ok = Array.isArray(b.kv_namespaces) && b.kv_namespaces.some((k) => isObj(k) && k.binding === need.kv)
+      if (!ok) problems.push(`wrangler config ${where}: no kv_namespaces binding "${need.kv}". Add:\n  ${KV_SNIPPET(need.kv)}`)
+    }
+    if (need.do !== undefined) {
+      const bound = isObj(b.durable_objects) && Array.isArray(b.durable_objects.bindings) && b.durable_objects.bindings.some((d) => isObj(d) && d.name === need.do && d.class_name === 'BrustCacheDO' && d.script_name === undefined)
+      if (!bound) problems.push(`wrangler config ${where}: no durable_objects binding { "name": "${need.do}", "class_name": "BrustCacheDO" } (without script_name). Add:\n  ${DO_SNIPPET(need.do)}`)
+      else {
+        const decl = declaresDoClass(b) || (where === 'the top level' ? false : declaresDoClass(config))
+        if (decl === 'kv') problems.push(`wrangler config ${where}: BrustCacheDO is declared with new_classes (KV-backed, no SQL API); use new_sqlite_classes:\n  "migrations": [{ "tag": "brust-cache-v1", "new_sqlite_classes": ["BrustCacheDO"] }]`)
+        else if (decl !== true) problems.push(`wrangler config ${where}: BrustCacheDO is not declared. Add:\n  "migrations": [{ "tag": "brust-cache-v1", "new_sqlite_classes": ["BrustCacheDO"] }]`)
+      }
+    }
+  }
+  return problems.length === 0 ? { ok: true } : { ok: false, message: problems.join('\n') }
+}
+
+export function renderWrangler(config: Json): string {
+  return `// generated by \`brust build --target cloudflare\` — edit the app-root wrangler config instead\n${JSON.stringify(config, null, 2)}\n`
+}