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

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`
+}

package/src/build/cloudflare.ts

@@ -0,0 +1,317 @@
+// `brust build --target cloudflare` (M4-CF spec §4): after the normal build, writes `<out>/cf/`:
+//   worker/      the @brust/core-cf glue + wasm (verbatim)  +  <appModuleDir>/brust-app.js (ONE Bun bundle, R2)
+//   assets/      Static Assets tree + _headers (R7)         wrangler.jsonc  (user config merged with brust's keys, R5)
+//   .stage/      the generated entry + the smoke harness (kept for inspection)
+import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { builtinModules } from 'node:module'
+import { dirname, join, relative } from 'node:path'
+import type { BunPlugin } from 'bun'
+import { BrustConfigError, type CorsConfig, loadCors } from '../config'
+import { layoutAssets } from './cf-assets'
+import { serverOnlyEmptyPlugin } from './server-only'
+import { type CfConfigJson, cfEntrySource } from './cf-entry'
+import { type CoreCf, resolveCoreCf } from './cf-core'
+import { type CacheNeed, mergeWrangler, readUserWrangler, renderWrangler, type UserWrangler, verifyCacheBindings } from './cf-wrangler'
+import { type CloudflareBuildConfig, CF_MIN_COMPAT_DATE } from './config'
+import { MANIFEST_VERSION } from './manifest'
+import { exposePlugin, PRODUCTION, type SourceOf, sourceDirPlugin } from './bundle'
+import type { Compiled } from './compile'
+import { cssPlugin } from './css'
+import { BuildError } from './errors'
+import type { CacheRecord } from './manifest'
+import { BUILTINS as CACHE_BUILTINS } from '../cache-adapter/load'
+
+export interface CfFlags {
+  fromSource: boolean
+  env: Record<string, string | undefined>
+}
+
+export interface CfPrepared {
+  cfg: CloudflareBuildConfig
+  core: CoreCf
+  user: UserWrangler
+  coreVersion: string
+  pkgName: string | undefined
+  /** brust.toml `[cors]`, validated before any write */
+  cors: CorsConfig | undefined
+  warnings: string[]
+}
+
+const DEFAULT_CFG: CloudflareBuildConfig = { name: undefined, compatibilityDate: undefined, l1Capacity: 256, jobCacheCapacity: 512, stats: false, edgeCache: 'off', alias: {} }
+
+/** Everything that can fail on the app's own input or install, before a byte is written (index.ts rule). */
+export async function prepareCloudflare(appRoot: string, cfg: CloudflareBuildConfig | null, flags: CfFlags): Promise<CfPrepared> {
+  const core = resolveCoreCf({ appRoot, fromSource: flags.fromSource, env: flags.env })
+  const user = await readUserWrangler(appRoot)
+  const warnings = [...core.warnings]
+  try {
+    const toml = Bun.file(join(appRoot, 'brust.toml'))
+    if (await toml.exists()) {
+      const root = Bun.TOML.parse(await toml.text()) as Record<string, unknown>
+      for (const k of ['server', 'workers']) if (k in root) warnings.push(`[brust] brust.toml [${k}] is ignored on this target`)
+    }
+  } catch {
+    // loadBuildConfig already reported a malformed brust.toml
+  }
+  let pkgName: string | undefined
+  try {
+    pkgName = (JSON.parse(readFileSync(join(appRoot, 'package.json'), 'utf8')) as { name?: string }).name
+  } catch {
+    pkgName = undefined
+  }
+  const coreVersion = String((JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as { version?: string }).version ?? '0.0.0')
+  let cors: CorsConfig | undefined
+  try {
+    cors = await loadCors(appRoot)
+  } catch (e) {
+    if (e instanceof BrustConfigError) throw new BuildError('config', e.message)
+    throw e
+  }
+  return { cfg: cfg ?? DEFAULT_CFG, core, user, coreVersion, pkgName, cors, warnings }
+}
+
+export interface CfBuildCtx {
+  appRoot: string
+  entry: string
+  /** the FINAL dist dir (`out` is a tmp sibling that is renamed to it): wrangler paths are relative to `<dist>/cf` */
+  dist: string
+  compiled: Map<string, Compiled>
+  manifest: { components: Record<string, { template: string }>; actions?: { prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } | null; cache?: CacheRecord }
+  sourceOf: SourceOf
+  actionsEntry: string | null
+  /** L16 R16.3: an actions-only Worker: no pages (no routes entry, no jobs, no templates), no Static Assets. */
+  actionsOnly?: boolean
+  /** A custom cache adapter's source module (absolute). */
+  cacheModule?: string | null
+  /** `[cache] get_timeout_ms` as written (absent → the Workers default, 100). */
+  cacheGetTimeoutMs?: number
+  /** L19: CSS Module class maps (the worker reads the same map as the browser). */
+  cssMaps?: Map<string, Record<string, string>>
+  log: (s: string) => void
+}
+
+const CORE_SRC = join(import.meta.dir, '..')
+const BUILTINS = new Set(builtinModules.filter((m) => !m.startsWith('_')))
+
+/** Violations of the Workers host surface: `bun`/`bun:*` anywhere in the graph (R2 f). */
+function cfGuard(appRoot: string, violations: string[]): BunPlugin {
+  return {
+    name: 'brust-cf-guard',
+    setup(b) {
+      b.onResolve({ filter: /^bun(:.*)?$/ }, (a) => {
+        violations.push(`${relative(appRoot, a.importer) || a.importer} imports ${a.path}`)
+        return { path: a.path, external: true }
+      })
+      b.onResolve({ filter: /^[a-z_]+(\/[a-z_/]+)?$/ }, (a) => (BUILTINS.has(a.path) ? { path: `node:${a.path}`, external: true } : undefined))
+    },
+  }
+}
+
+/** `[cloudflare] alias` (spec R12): a module whose resolved path is a key is replaced by its value. */
+function cfAlias(alias: Record<string, string>, sourceOf: SourceOf): BunPlugin {
+  return {
+    name: 'brust-cf-alias',
+    setup(b) {
+      if (Object.keys(alias).length === 0) return
+      b.onResolve({ filter: /.*/ }, (a) => {
+        if (a.importer === '' || a.importer.includes('/node_modules/')) return undefined
+        let abs: string
+        try {
+          abs = Bun.resolveSync(a.path, dirname(sourceOf.get(a.importer) ?? a.importer))
+        } catch {
+          return undefined
+        }
+        const to = alias[abs]
+        return to === undefined ? undefined : { path: to }
+      })
+    },
+  }
+}
+
+/** The CF bundle's stand-in for the napi addon (`native.ts` `require('../native/index.js')`, R8): every call
+ * fails loudly, since a Worker has no addon. */
+function cfNativeStub(handlersPath: string): BunPlugin {
+  const names = ['startServer', 'registerWorker', 'untilReady', 'beginDrain', 'cacheInvalidate', 'cacheStats', 'localAddr', 'planJobs', 'planJobsBuf', 'takeFetchBody', 'putFetchReply', 'cacheReplay', 'cacheL2Count', 'cacheClear']
+  return {
+    name: 'brust-cf-native',
+    setup(b) {
+      b.onResolve({ filter: /^\.\.\/native\/index\.js$/ }, (a) => (/[\\/]src[\\/]native\.ts$/.test(a.importer) ? { path: 'brust-cf-native', namespace: 'brust-cf' } : undefined))
+      b.onLoad({ filter: /.*/, namespace: 'brust-cf' }, () => ({
+        loader: 'js',
+        // cacheInvalidate -> the `rt.invalidate` the glue installed at start (ruling 19753649); the rest has no Worker meaning.
+        contents: `import { installedRuntime } from ${JSON.stringify(handlersPath)}\nconst no = (n) => () => { throw new Error(n + ' is not available on Cloudflare Workers') }\nmodule.exports = {${names.map((n) => (n === 'cacheInvalidate' ? 'cacheInvalidate: (a) => installedRuntime().invalidate(a)' : `${n}: no(${JSON.stringify(n)})`)).join(', ')}}\n`,
+      }))
+    },
+  }
+}
+
+/** The @brust/core `workerStorePlugin` twin for a bundle that inlines `@brust/core` (not external). */
+function cfStorePlugin(appRoot: string): BunPlugin {
+  return {
+    name: 'brust-cf-store',
+    setup(b) {
+      // The core's own re-export files (`src/store/{index,react}.ts`) must keep their real target, else they loop.
+      b.onResolve({ filter: /^@brust\/runtime-dom\/store(\/react)?$/ }, (a) =>
+        a.importer.startsWith(CORE_SRC) ? undefined : { path: Bun.resolveSync(a.path.replace('@brust/runtime-dom', '@brust/core'), appRoot) },
+      )
+    },
+  }
+}
+
+/** The entry's cache wiring (R8 on Workers): the custom source module or the built-in spec; an `env:`
+ * option cannot be resolved inside a Worker (no process env at bundle time) and is refused. */
+function cfEntryCache(c: CacheRecord, customModule: string | null) {
+  const noEnv = (o: Record<string, unknown> | undefined) => {
+    for (const [k, v] of Object.entries(o ?? {}))
+      if (typeof v === 'string' && v.startsWith('env:')) throw new BuildError('cache', `cache option ${k}: "env:" values are not available on Cloudflare Workers (use a binding)`)
+  }
+  noEnv(c.options)
+  noEnv(c.broadcastOptions)
+  const module = c.adapter === 'custom' ? customModule : CACHE_BUILTINS[c.adapter]
+  if (!module) throw new BuildError('cache', `cache adapter "${c.adapter}" has no module to bundle`)
+  return { module, options: c.options, ...(c.broadcast ? { broadcast: CACHE_BUILTINS[c.broadcast]!, broadcastOptions: c.broadcastOptions ?? {} } : {}) }
+}
+
+/** R2/R10: which Cloudflare bindings the configured cache needs (`[cache.cloudflare]` keys land in the adapter's options), or null. */
+export function cacheNeeds(c: Pick<CacheRecord, 'adapter' | 'broadcast' | 'options' | 'broadcastOptions'> | undefined): CacheNeed | null {
+  if (!c) return null
+  const opt = (o: Record<string, unknown> | undefined, k: string) => (typeof o?.[k] === 'string' ? (o[k] as string) : undefined)
+  const all = [c.options, c.broadcastOptions]
+  const names = [c.adapter, c.broadcast]
+  const kv = names.includes('cloudflare-kv') ? (all.map((o) => opt(o, 'kv_binding')).find((b) => b) ?? 'BRUST_CACHE') : undefined
+  const explicitDo = all.map((o) => opt(o, 'do_binding')).find((b) => b)
+  const dobind = names.includes('cloudflare-do') || explicitDo !== undefined ? (explicitDo ?? 'BRUST_CACHE_DO') : undefined
+  return kv === undefined && dobind === undefined ? null : { ...(kv !== undefined ? { kv } : {}), ...(dobind !== undefined ? { do: dobind } : {}) }
+}
+
+function smokeFiles(app: string, cache = false): { preload: string; smoke: string } {
+  const preload = `// generated: stubs the Workers-only modules so brust-app.js can be imported under Bun
+import { plugin } from 'bun'
+plugin({
+  name: 'brust-cf-smoke',
+  setup(b) {
+    b.module('cloudflare:workers', () => ({ exports: { env: {}, waitUntil() {}, DurableObject: class {} }, loader: 'object' }))
+  },
+})
+`
+  const smoke = `// generated: build-time smoke check of the CF bundle (child process; mock leaks are process-wide)
+const m = await import(${JSON.stringify(app)})
+const bad = []
+for (const k of ['loader', 'jobs', 'action', 'install']) if (typeof m[k] !== 'function') bad.push(k + ' is not a function')
+if (typeof m.MANIFEST !== 'string' || JSON.parse(m.MANIFEST).version !== ${MANIFEST_VERSION}) bad.push('MANIFEST.version !== ${MANIFEST_VERSION}')
+if (typeof m.CONFIG !== 'string' || JSON.parse(m.CONFIG).abi !== 1) bad.push('CONFIG.abi !== 1')
+if (typeof m.TEMPLATES !== 'object' || m.TEMPLATES === null) bad.push('TEMPLATES is not an object')
+const r = await m.loader('{}')
+if (typeof r !== 'string' || !r.includes('error')) bad.push('loader({}) did not resolve an error string: ' + String(r))${cache ? `
+try {
+  const out = m.install({ invalidate: () => ({ l1Removed: 0, jobRemoved: 0 }), l2Count: () => true })
+  if (!out || !out.cache || typeof out.cache.origin !== 'string') bad.push('install() returned no cache bridge')
+} catch (e) { bad.push('cache adapter: ' + (e && e.message ? e.message : String(e))) }` : ''}
+if (bad.length) { console.error(bad.join('\\n')); process.exit(1) }
+`
+  return { preload, smoke }
+}
+
+export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepared): Promise<string[]> {
+  const cfDir = join(out, 'cf')
+  const stage = join(cfDir, '.stage')
+  const warnings = [...p.warnings]
+  // R10: a Cloudflare cache built-in needs the user's own bindings; verify (never add) before anything is bundled.
+  const need = cacheNeeds(ctx.manifest.cache)
+  if (need) {
+    const v = verifyCacheBindings(p.user.config, need)
+    if (!v.ok) throw new BuildError('cf-config', v.message)
+  }
+  const doClass = need?.do !== undefined
+  if (doClass && existsSync(join(p.core.workerDir, 'main.js'))) throw new BuildError('cf-config', `@brust/core-cf ships its own worker/main.js; brust cannot add the BrustCacheDO re-export (R1)`)
+  mkdirSync(stage, { recursive: true })
+  cpSync(p.core.workerDir, join(cfDir, 'worker'), { recursive: true })
+
+  const templates: Record<string, string> = {}
+  for (const [id, c] of Object.entries(ctx.manifest.components)) {
+    const comp = ctx.compiled.get(id)
+    if (comp) templates[c.template] = comp.jinja
+  }
+  const templatesPath = join(stage, 'templates.json')
+  writeFileSync(templatesPath, JSON.stringify(templates))
+
+  const cors = p.cors
+  const a = ctx.manifest.actions
+  const cache = ctx.manifest.cache ? { ...ctx.manifest.cache, getTimeoutMs: ctx.cacheGetTimeoutMs ?? 100 } : null
+  const entryCache = cache ? cfEntryCache(cache, ctx.cacheModule ?? null) : null
+  const config: CfConfigJson = {
+    abi: 1,
+    generator: `brust/${p.coreVersion}`,
+    l1Capacity: p.cfg.l1Capacity,
+    jobCacheCapacity: p.cfg.jobCacheCapacity,
+    stats: p.cfg.stats,
+    edgeCache: p.cfg.edgeCache,
+    ...(cors ? { cors } : {}),
+    ...(a ? { actions: { prefix: a.prefix, maxBodyBytes: a.maxBodyBytes, maxResponseBytes: a.maxResponseBytes ?? 8_388_608, crossSite: a.crossSite ?? 'reject' } } : {}),
+    ...(cache ? { cache: { adapter: cache.adapter, getTimeoutMs: cache.getTimeoutMs, maxBodyBytes: cache.maxBodyBytes, namespace: cache.namespace, buildId: cache.buildId, epochIntervalMs: cache.epochIntervalMs } } : {}),
+  }
+  const entryPath = join(stage, 'brust-app.entry.js')
+  const jobsEntry = join(out, '.stage', 'jobs.ts')
+  writeFileSync(
+    entryPath,
+    cfEntrySource({ entry: ctx.entry, jobsEntry, actionsOnly: ctx.actionsOnly === true, actionsEntry: a ? ctx.actionsEntry : null, prefix: a?.prefix ?? '', manifestPath: join(out, 'manifest.json'), templatesPath, config, cache: entryCache, doClass }),
+  )
+  // Bare imports of the generated files resolve from the app root (an --out-dir outside the app has no node_modules above it).
+  // (registered by absolute AND real path: the bundler reports the real one, e.g. /private/var on macOS)
+  for (const f of ctx.actionsOnly ? [entryPath] : [entryPath, jobsEntry]) {
+    ctx.sourceOf.set(f, ctx.entry)
+    ctx.sourceOf.set(realpathSync(f), ctx.entry)
+  }
+
+  const glue = p.core.meta.glue
+  const appDir = join(cfDir, 'worker', p.core.meta.appModuleDir)
+  const glueRel = relative(appDir, join(cfDir, 'worker', glue)).split('\\').join('/')
+  const glueSpec = glueRel.startsWith('.') ? glueRel : `./${glueRel}`
+  const violations: string[] = []
+  const res = await Bun.build({
+    entrypoints: [entryPath],
+    target: 'browser',
+    format: 'esm',
+    conditions: ['workerd', 'worker', 'browser'],
+    define: PRODUCTION,
+    minify: false,
+    external: ['node:*', 'cloudflare:*', glueSpec],
+    plugins: [serverOnlyEmptyPlugin(), cssPlugin(ctx.cssMaps ?? new Map()), cfGuard(ctx.appRoot, violations), cfAlias(p.cfg.alias, ctx.sourceOf), cfNativeStub(Bun.resolveSync('@brust/core/server-handlers', ctx.appRoot)), cfStorePlugin(ctx.appRoot), sourceDirPlugin(ctx.sourceOf, ctx.appRoot, ['node:*', 'cloudflare:*']), exposePlugin(ctx.compiled)],
+  })
+  if (violations.length > 0) throw new BuildError('cf-unsupported', `${[...new Set(violations)].join('\n')}\nthese modules do not exist on Cloudflare Workers; swap them with [cloudflare] alias`)
+  if (!res.success) throw new BuildError('bundle', `cloudflare: ${res.logs.map(String).join('\n')}`)
+  const js = res.outputs.filter((o) => o.kind === 'entry-point')
+  if (js.length !== 1) throw new BuildError('bundle', `cloudflare: expected one entry-point output, got ${js.length}`)
+  for (const o of res.outputs) if (o.kind !== 'entry-point') warnings.push(`[brust] cloudflare bundle: dropped non-JS output ${o.path}`)
+  const appFile = join(appDir, 'brust-app.js')
+  mkdirSync(appDir, { recursive: true })
+  writeFileSync(appFile, await js[0]!.text())
+
+  // An actions-only Worker has no pages and so no Static Assets (no `assets` binding in its wrangler.jsonc either).
+  if (!ctx.actionsOnly) warnings.push(...layoutAssets(out, cfDir, p.coreVersion).warnings)
+  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}`)
+  if (doClass) {
+    // R1: the Durable Object class must be exported by the deployed main module; the glue already imports ./brust-app.js, so it is one module copy.
+    const appRel = relative(join(cfDir, 'worker'), appFile).split('\\').join('/')
+    writeFileSync(
+      join(cfDir, 'worker', 'main.js'),
+      `// generated by brust build --target cloudflare (do not edit)\nexport * from "./${p.core.meta.main}"\nexport { default } from "./${p.core.meta.main}"\nexport { BrustCacheDO } from "./${appRel}"\n`,
+    )
+  }
+  const merged = mergeWrangler(p.user, { appRoot: ctx.appRoot, cfDir: join(ctx.dist, 'cf'), name: p.cfg.name, pkgName: p.pkgName, compatibilityDate, main: doClass ? 'main.js' : p.core.meta.main, version: p.coreVersion, ...(ctx.actionsOnly ? { noAssets: true } : {}) })
+  warnings.push(...merged.warnings)
+  writeFileSync(join(cfDir, 'wrangler.jsonc'), renderWrangler(merged.config))
+
+  const { preload, smoke } = smokeFiles(appFile, cache !== null)
+  writeFileSync(join(stage, 'smoke-preload.ts'), preload)
+  writeFileSync(join(stage, 'smoke.ts'), smoke)
+  const r = Bun.spawnSync([process.execPath, '--preload', join(stage, 'smoke-preload.ts'), join(stage, 'smoke.ts')], {
+    cwd: ctx.appRoot,
+    env: { ...process.env, NODE_ENV: 'production' },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  if (r.exitCode !== 0) throw new BuildError('cf-smoke', `${r.stderr.toString().trim() || r.stdout.toString().trim()}\n(open bindings lazily: module top level runs at build time with env = {})`)
+  return warnings
+}