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

package/src/cache-adapter/runtime.ts

@@ -0,0 +1,124 @@
+// The cache adapter at run time, on both hosts: the per-process (native) / per-isolate (Workers)
+// adapter, what `cache.invalidate` does after the tier-1 primitive, and the native worker-0
+// subscriber that replays other processes' invalidations. No `bun` import (CF-bundle safe).
+//
+// L3: a replayed event is applied through the host's REPLAY primitive (napi `cacheReplay`, wasm
+// `core.l2_replay`), never through `cache.invalidate`, so it is never published again.
+import type { CacheAdapter, InvalidateArgs, InvalidationEvent } from './types'
+
+export interface CacheRuntime {
+  adapter: CacheAdapter
+  /** This process / isolate: events it published carry it and are not replayed here. */
+  origin: string
+  /** Keeps a background promise alive (Workers: `waitUntil`; native: a swallowed floating promise). */
+  defer: (p: Promise<unknown>) => void
+  /** Bumps a `stats.l2` counter (napi `cacheL2Count` / wasm `rt.l2Count`). */
+  count: (name: string) => void
+  /** Resolves once the adapter's `init` ran (Workers defer it to the first use). */
+  ready?: () => Promise<void>
+  /**
+   * The host's replay primitive (napi `cacheReplay` / wasm `rt.replay` → `Core::l2_replay`): tier 1
+   * again plus the floor at `seq` (`null` = tier 1 only). Never publishes.
+   */
+  replay?: (args: InvalidateArgs, seq: number | null) => void
+}
+
+let current: CacheRuntime | null = null
+
+/** Installed at worker boot (native) / `install` (Workers); `null` uninstalls (tests). */
+export function setCacheRuntime(r: CacheRuntime | null): void {
+  current = r
+}
+
+export function cacheRuntime(): CacheRuntime | null {
+  return current
+}
+
+const describe = (e: unknown) => (e instanceof Error ? e.message : String(e))
+
+/**
+ * After `cache.invalidate`'s tier-1 primitive: the shared-side delete, THEN the publish (ruling
+ * L7a: other instances replay only once the store no longer holds the bodies), deferred off the
+ * request path; THEN this instance replays its own invalidation once (review F1): a request in the
+ * window before the delete landed could re-fill tier 1 from the old L2 body, and its own echo is
+ * skipped, so the replay re-clears tier 1 and raises the floor to the publish seq (a re-filled
+ * body is older). Never throws, never leaves a rejected promise (a worker-side unhandled rejection
+ * is fatal on native). Option values are never logged.
+ */
+export function afterInvalidate(args: InvalidateArgs): void {
+  const r = current
+  if (!r || (!r.adapter.store && !r.adapter.broadcast)) return
+  const { adapter, origin, count } = r
+  const task = (async () => {
+    await r.ready?.()
+    if (adapter.store) {
+      try {
+        await adapter.store.invalidate(args)
+      } catch (e) {
+        count('errors')
+        console.error(`[brust] cache adapter "${adapter.name}": store.invalidate failed: ${describe(e)}`)
+      }
+    }
+    let seq: number | null = null
+    if (adapter.broadcast) {
+      try {
+        seq = await adapter.broadcast.publish(args, origin)
+        count('published')
+      } catch (e) {
+        count('publish_errors')
+        console.error(`[brust] cache adapter "${adapter.name}": publish failed: ${describe(e)}`)
+      }
+    }
+    try {
+      r.replay?.(args, typeof seq === 'number' && Number.isSafeInteger(seq) && seq >= 0 ? seq : null)
+    } catch (e) {
+      count('errors')
+      console.error(`[brust] cache adapter "${adapter.name}": own replay failed: ${describe(e)}`)
+    }
+  })()
+  r.defer(task.catch(() => {}))
+}
+
+export interface SubscriberDeps {
+  /** napi `cacheReplay(args, seq)`: tier 1 + the floor, never re-published. */
+  replay: (args: InvalidateArgs, seq: number) => void
+  /** napi `cacheClear()`: both tier-1 caches dropped (a gap). */
+  clear: () => void
+  count: (name: string) => void
+}
+
+/**
+ * Native worker 0's push subscriber (R10): first event adopts its seq; `seq <= last` is ignored;
+ * `seq > last + 1` clears tier 1 then adopts; `onGap` clears and forgets. Own events advance the
+ * seq but are not replayed (tier 1 is already invalidated). Resolves to the unsubscribe.
+ */
+export async function startSubscriber(adapter: CacheAdapter, origin: string, deps: SubscriberDeps): Promise<(() => Promise<void>) | null> {
+  const sub = adapter.broadcast?.subscribe
+  if (!sub) return null
+  let last: number | null = null
+  const on = (e: InvalidationEvent) => {
+    try {
+      if (last !== null && e.seq <= last) return
+      if (last !== null && e.seq > last + 1) deps.clear()
+      last = e.seq
+      if (e.origin === origin) {
+        deps.count('skipped_own')
+        return
+      }
+      deps.replay(e.args, e.seq)
+      deps.count('received')
+    } catch (err) {
+      deps.count('errors')
+      console.error(`[brust] cache adapter "${adapter.name}": replay failed: ${describe(err)}`)
+    }
+  }
+  const onGap = () => {
+    try {
+      deps.clear()
+    } catch (err) {
+      console.error(`[brust] cache adapter "${adapter.name}": clear failed: ${describe(err)}`)
+    }
+    last = null
+  }
+  return sub.call(adapter.broadcast, on, onGap)
+}

package/src/cache-adapter/types.ts

@@ -0,0 +1,96 @@
+// The cache adapter contract (docs/design/2026-10-12-cache-adapter-design.md §3.1): a shared second
+// tier behind brust's in-process cache. An adapter has two optional capabilities — a `store` of
+// rendered pages and a `broadcast` of invalidations (push `subscribe` or pull `since`) — so a store
+// without a channel (KV) can be composed with another adapter's broadcast (DO).
+//
+// One sequence space per adapter: every `stamp`, `entryStamp` and event `seq` is a number in its
+// broadcast's sequence (a store without a broadcast reports `null` stamps and its writes are unguarded).
+import type { InvalidateArgs } from '../native'
+
+export type { InvalidateArgs }
+
+/** A rendered page: the identity body and its validated headers, in order (repeats kept). */
+export interface StoredPage {
+  status: number
+  headers: [string, string][]
+  body: Uint8Array
+}
+
+export interface SetMeta {
+  ttlMs: number
+  tags: string[]
+  method: string
+  path: string
+  /** The `stamp` the lookup returned (read before the render); `null` = unguarded write. */
+  stamp: number | null
+}
+
+export interface GetResult {
+  page: StoredPage | null
+  /** The broadcast seq NOW: the write-guard base of the set that may follow this miss. */
+  stamp: number | null
+  /** The stamp the entry was written under (`SetMeta.stamp`); the invalidation floor compares it. */
+  entryStamp: number | null
+  /** When the entry was written (ms since the epoch); `null` = unknown (full ttl). */
+  storedAt: number | null
+}
+
+export interface CacheStore {
+  get(key: string): Promise<GetResult>
+  /**
+   * `false` = refused: the stamp is older than an invalidation of one of `meta.tags` or of
+   * `meta.method meta.path` (a store with atomic writes MUST refuse it), or the body is over `maxBodyBytes`.
+   */
+  set(key: string, page: StoredPage, meta: SetMeta): Promise<boolean>
+  /**
+   * Shared-side delete by tags/path (`key` is a no-op: the store holds pages only). Records the
+   * invalidation marker BEFORE deleting, so a concurrent stale `set` is refused even before the
+   * publish (ruling L7b).
+   */
+  invalidate(args: InvalidateArgs): Promise<void>
+  readonly maxBodyBytes: number
+}
+
+export interface InvalidationEvent {
+  seq: number
+  origin: string
+  args: InvalidateArgs
+}
+
+export interface EpochSince {
+  /** The broadcast's generation: a change means its history is gone (every reader clears). */
+  gen: string
+  /** The latest seq. */
+  seq: number
+  /** The reader is further behind than the retained history: it must clear. */
+  behind: boolean
+  /** Every retained event with a seq above the one asked for, in order. */
+  events: InvalidationEvent[]
+}
+
+export interface CacheBroadcast {
+  /** Append an invalidation; resolves to the seq it was assigned. */
+  publish(args: InvalidateArgs, origin: string): Promise<number>
+  /** Push: events in order; `onGap` when delivery may have lost some. Resolves to an unsubscribe. */
+  subscribe?(on: (e: InvalidationEvent) => void, onGap: () => void): Promise<() => Promise<void>>
+  /** Pull: the events after `seq` (Workers: the only mode, no connection outlives a request). */
+  since?(seq: number): Promise<EpochSince>
+}
+
+export interface CacheAdapterInit {
+  namespace: string
+  buildId: string
+  runtime: 'bun' | 'workers'
+  workerId: number
+}
+
+export interface CacheAdapter {
+  readonly name: string
+  readonly runtimes: ReadonlyArray<'bun' | 'workers'>
+  store?: CacheStore
+  broadcast?: CacheBroadcast
+  init?(ctx: CacheAdapterInit): Promise<void>
+  close?(): Promise<void>
+}
+
+export type CacheAdapterFactory = (options: Record<string, unknown>) => CacheAdapter

package/src/cache-adapter/workers.ts

@@ -0,0 +1,118 @@
+// The cache adapter inside a Workers isolate (cache adapters R11, R14): `install(rt, ext)` builds the
+// adapter, wires `cache.invalidate`'s publish through `waitUntil`, and answers the wasm side's bridge
+// (`crates/brust-wasm/src/host.rs` `CacheBridge`). No `bun` import (it is bundled into brust-app.js).
+import { checkRuntime, compose, instantiate } from './load'
+import { setCacheRuntime } from './runtime'
+import type { CacheAdapter, InvalidateArgs, SetMeta } from './types'
+
+/** What the wasm side passes to `install` (`bridge.rs`). */
+export interface CfRuntimeBase {
+  l2Count?(name: string): boolean
+  /** `Core::l2_replay`: tier 1 + the floor at `seq`, never published (review F1's own replay). */
+  replay?(args: InvalidateArgs, seq: number | null): unknown
+}
+
+/** `CONFIG.cache` (build/cf-entry.ts), as the entry passes it. */
+export interface CfCacheConfig {
+  adapter: string
+  getTimeoutMs: number
+  maxBodyBytes: number
+  namespace: string
+  buildId: string
+  epochIntervalMs: number
+}
+
+/** The generated entry's second `install` argument. */
+export interface CfInstallExt {
+  /** The adapter module's namespace, default export, or factory. */
+  adapter: unknown
+  options: Record<string, unknown>
+  /** A composed built-in broadcast (`[cache] broadcast`), same forms as `adapter`. */
+  broadcast?: unknown
+  broadcastOptions?: Record<string, unknown>
+  config: CfCacheConfig
+  waitUntil: (p: Promise<unknown>) => void
+}
+
+/** The wasm side's view: `get`/`set` only with a store, `since` only with a pull broadcast. */
+export interface CfCacheBridge {
+  origin: string
+  get?: (key: string) => Promise<{ json: string; body: Uint8Array | null }>
+  set?: (key: string, json: string, body: Uint8Array) => void
+  since?: (seq: number) => Promise<string>
+}
+
+const describe = (e: unknown) => (e instanceof Error ? e.message : String(e))
+
+/** Throws (a TypeError → the Worker refuses to boot, lane-3 R11) on a bad adapter or a push-only broadcast. */
+export function installCache(rt: CfRuntimeBase, ext: CfInstallExt): CfCacheBridge {
+  const { config: c, waitUntil } = ext
+  let a: CacheAdapter = instantiate(ext.adapter, ext.options, `"${c.adapter}"`)
+  if (ext.broadcast !== undefined) {
+    const other = instantiate(ext.broadcast, ext.broadcastOptions ?? {}, 'broadcast')
+    if (!other.broadcast) throw new TypeError(`cache adapter "${other.name}" has no broadcast to compose`)
+    a = compose(a, other)
+  }
+  checkRuntime(a, 'workers')
+  const count = (name: string) => void rt.l2Count?.(name)
+  // `init` may do I/O, which a Worker refuses at start: it runs on the first use, once.
+  let ready: Promise<void> | null = null
+  const ensure = () => (ready ??= Promise.resolve(a.init?.({ namespace: c.namespace, buildId: c.buildId, runtime: 'workers', workerId: 0 })))
+  // A Worker may not draw random values at start (global scope): the origin is made on first read.
+  let origin: string | null = null
+  const getOrigin = () => (origin ??= crypto.randomUUID())
+  setCacheRuntime({
+    adapter: a,
+    get origin() {
+      return getOrigin()
+    },
+    defer: (p) => waitUntil(p),
+    count,
+    ready: ensure,
+    replay: (args, seq) => void rt.replay?.(args, seq),
+  })
+  const store = a.store
+  const since = a.broadcast?.since?.bind(a.broadcast)
+  return {
+    get origin() {
+      return getOrigin()
+    },
+    ...(store
+      ? {
+          async get(key: string) {
+            try {
+              await ensure()
+              const r = await store.get(key)
+              if (!r.page || r.page.body.length > c.maxBodyBytes) {
+                if (r.page) count('errors')
+                return { json: JSON.stringify({ hit: false, stamp: r.stamp }), body: null }
+              }
+              const p = r.page
+              return { json: JSON.stringify({ hit: true, status: p.status, headers: p.headers, stamp: r.stamp, entryStamp: r.entryStamp, storedAt: r.storedAt }), body: p.body }
+            } catch (e) {
+              return { json: JSON.stringify({ error: describe(e) }), body: null }
+            }
+          },
+          set(key: string, json: string, body: Uint8Array) {
+            const task = (async () => {
+              const { status, headers, meta } = JSON.parse(json) as { status: number; headers: [string, string][]; meta: SetMeta }
+              await ensure()
+              count((await store.set(key, { status, headers, body }, meta)) ? 'sets' : 'set_refused')
+            })().catch((e) => {
+              count('errors')
+              console.error(`[brust] cache adapter "${a.name}": set failed: ${describe(e)}`)
+            })
+            waitUntil(task)
+          },
+        }
+      : {}),
+    ...(since
+      ? {
+          async since(seq: number) {
+            await ensure()
+            return JSON.stringify(await since(seq))
+          },
+        }
+      : {}),
+  }
+}

package/src/cache.ts

@@ -1,6 +1,8 @@
 // Component-level cache declaration (S4 / §5). The compiler reads `cache(Comp, opts)` statically;
 // at runtime it is identity. `cache.invalidate` drops L1 pages and job-cache entries in the
-// running server (napi `cacheInvalidate`).
+// running server (napi `cacheInvalidate`), then — with a cache adapter — the shared store and the
+// broadcast to every other instance (deferred, `cache-adapter/runtime.ts`).
+import { afterInvalidate } from './cache-adapter/runtime'
 import { cacheComponent } from './cache-core'
 import { type InvalidateArgs, type InvalidateResult, cacheInvalidate } from './native'
 
@@ -19,6 +21,7 @@ function invalidate(args: InvalidateArgs): InvalidateResult {
       throw new Error(`${NO_SERVER}: ${msg}`)
     throw e
   }
+  afterInvalidate(args)
   return { l1Removed: r.l1Removed, jobRemoved: r.jobRemoved }
 }
 

package/src/cf.ts

@@ -0,0 +1,18 @@
+// `@brust/core` under the `workerd` export condition (M4-CF, ruling c30e2633): the app-facing API a Worker can run.
+// Same names as `index.ts` minus what needs a host process: no `run`, no `loadConfig`. `cache.invalidate` goes through
+// the CF bundle's napi stub to the runtime the wasm glue installed at start (`server-handlers` `install`).
+export { cache } from './cache'
+export type { ComponentCacheOptions, InvalidateArgs, InvalidateResult } from './cache'
+export {
+  ALLOWED_ROUTE_FIELDS,
+  BrustRouteError,
+  defineRoutes,
+  flattenRoutes,
+  httpError,
+  isHttpErrorTrigger,
+  isVerdict,
+  notFound,
+  Outlet,
+  redirect,
+} from './routes'
+export type { ComponentType, FlatRoute, HttpErrorOpts, HttpErrorTrigger, LoaderCtx, LoaderReq, Route, RouteCacheConfig, Verdict } from './routes'

package/src/cli.ts

@@ -3,10 +3,12 @@
 // Exit codes: 0 ok, 1 build/boot error (`error <rule> <message>` / `[brust] …`), 2 usage.
 import { parseArgs } from 'node:util'
 import { BuildError, runBuild } from './build'
+import { runDev } from './dev'
 import { run } from './run'
 
 const USAGE = `usage:
-  brust build [entry=routes.tsx] [--out-dir dist] [--force]
+  brust build [entry=routes.tsx] [--out-dir dist] [--force] [--target bun|cloudflare] [--wasm-from-source]
+  brust dev [entry=routes.tsx] --target cloudflare [--out-dir dist] [--port N] [--wasm-from-source] [-- <wrangler args>]
   brust start [--port N] [--workers N] [--dist-dir dist] [--entry routes.tsx]
 
 Config precedence for start: env (BRUST_ADDR, BRUST_PORT, BRUST_WORKERS, BRUST_RENDER_SLOTS,
@@ -29,7 +31,10 @@ function intFlag(name: string, v: string | undefined, min: number): number | und
 }
 
 export async function main(argv: string[]): Promise<void> {
-  const [cmd, ...rest] = argv
+  const [cmd, ...all] = argv
+  const dd = cmd === 'dev' ? all.indexOf('--') : -1
+  const rest = dd < 0 ? all : all.slice(0, dd)
+  const passthrough = dd < 0 ? [] : all.slice(dd + 1)
   if (cmd === undefined || cmd === '--help' || cmd === '-h' || cmd === 'help') {
     process.stdout.write(USAGE)
     process.exit(cmd === undefined ? 2 : 0)
@@ -46,6 +51,8 @@ export async function main(argv: string[]): Promise<void> {
         port: { type: 'string' },
         workers: { type: 'string' },
         force: { type: 'boolean' },
+        target: { type: 'string' },
+        'wasm-from-source': { type: 'boolean' },
         help: { type: 'boolean', short: 'h' },
       },
     })
@@ -58,6 +65,8 @@ export async function main(argv: string[]): Promise<void> {
     process.exit(0)
   }
   const str = (k: string) => values[k] as string | undefined
+  const target = str('target')
+  if (target !== undefined && target !== 'bun' && target !== 'cloudflare') usage(`--target must be bun or cloudflare (got ${JSON.stringify(target)})`)
 
   if (cmd === 'build') {
     if (positionals.length > 1) usage(`build takes one entry (got ${positionals.join(' ')})`)
@@ -68,6 +77,8 @@ export async function main(argv: string[]): Promise<void> {
         entry: positionals[0] ?? 'routes.tsx',
         outDir: str('out-dir') ?? 'dist',
         force: values.force === true,
+        target: target as 'bun' | 'cloudflare' | undefined,
+        wasmFromSource: values['wasm-from-source'] === true,
         log: (s) => console.log(s),
       })
     } catch (e) {
@@ -79,6 +90,28 @@ export async function main(argv: string[]): Promise<void> {
     console.log(`[brust] built ${str('out-dir') ?? 'dist'} in ${Math.round(performance.now() - t0)}ms`)
     process.exit(0)
   }
+  if (cmd === 'dev') {
+    if (positionals.length > 1) usage(`dev takes one entry (got ${positionals.join(' ')})`)
+    if (target !== 'cloudflare') usage('brust dev: only --target cloudflare in this release')
+    const port = intFlag('port', str('port'), 0)
+    try {
+      process.exit(
+        await runDev({
+          appRoot: process.cwd(),
+          entry: positionals[0] ?? 'routes.tsx',
+          outDir: str('out-dir') ?? 'dist',
+          ...(port !== undefined && { port }),
+          wranglerArgs: passthrough,
+          fromSource: values['wasm-from-source'] === true,
+          log: (s) => console.log(s),
+        }),
+      )
+    } catch (e) {
+      if (e instanceof BuildError) console.error(`error ${e.rule} ${e.message}`)
+      else console.error(`error dev ${(e as Error).stack ?? String(e)}`)
+      process.exit(1)
+    }
+  }
   if (cmd === 'start') {
     if (positionals.length > 0) usage(`start takes no positional arguments (got ${positionals.join(' ')})`)
     const port = intFlag('port', str('port'), 0)

package/src/config.ts

@@ -89,6 +89,22 @@ export async function loadConfig(cwd: string = process.cwd(), cli: Partial<Brust
   }
 }
 
+/** `[cors]` of brust.toml and nothing else (no env, no cli): what the Cloudflare build ships in CONFIG.
+ * Throws `BrustConfigError` on a bad table, exactly like `loadConfig`. */
+export async function loadCors(cwd: string): Promise<CorsConfig | undefined> {
+  const tomlPath = join(cwd, 'brust.toml')
+  const file = Bun.file(tomlPath)
+  if (!(await file.exists())) return undefined
+  let parsed: unknown
+  try {
+    parsed = Bun.TOML.parse(await file.text())
+  } catch (e) {
+    throw new BrustConfigError(`failed to parse ${tomlPath}: ${(e as Error).message}`, tomlPath)
+  }
+  const root = (parsed ?? {}) as Record<string, unknown>
+  return 'cors' in root ? parseCors(root.cors, tomlPath) : undefined
+}
+
 /** CLI / programmatic overrides get the same bounds as env (a CLI `--port 0` = any free port). */
 function checkCli(cli: Partial<BrustConfig>): void {
   const check = (name: string, v: number | undefined, min: number, max: number) => {

package/src/dev.ts

@@ -0,0 +1,110 @@
+// `brust dev [entry] --target cloudflare [-- <wrangler args>]` (M4-CF R10): build, run `wrangler dev` on the
+// generated project, rebuild + restart wrangler on a source change. No HMR. Each build runs in a child
+// process: a failed build keeps the old wrangler, and module caches never leak between builds.
+import { type FSWatcher, watch } from 'node:fs'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { BuildError } from './build/errors'
+
+export interface DevOptions {
+  appRoot: string
+  entry: string
+  outDir: string
+  port?: number
+  wranglerArgs: string[]
+  fromSource: boolean
+  log: (s: string) => void
+}
+
+const IGNORED = new Set(['node_modules', '.wrangler', '.git'])
+const DEBOUNCE_MS = 300
+
+function wranglerBin(appRoot: string): string {
+  const fake = process.env.BRUST_WRANGLER
+  if (fake) return fake
+  const found = Bun.which('wrangler', { PATH: `${join(appRoot, 'node_modules', '.bin')}:${process.env.PATH ?? ''}` })
+  if (!found) throw new BuildError('cf-dev', 'wrangler not found (bun add -d wrangler)')
+  return found
+}
+
+/** Resolves with the exit code once the session ends (SIGINT/SIGTERM -> 0, or the child's own exit code). */
+export async function runDev(o: DevOptions): Promise<number> {
+  const appRoot = resolve(o.appRoot)
+  const dist = resolve(appRoot, o.outDir)
+  const bin = wranglerBin(appRoot)
+  const build = (): Promise<number> => {
+    const p = Bun.spawn([process.execPath, join(import.meta.dir, 'cli.ts'), 'build', o.entry, '--target', 'cloudflare', '--out-dir', o.outDir, ...(o.fromSource ? ['--wasm-from-source'] : [])], {
+      cwd: appRoot,
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+    return p.exited
+  }
+  if ((await build()) !== 0) return 1
+
+  const args = ['dev', '-c', join(dist, 'cf', 'wrangler.jsonc'), '--persist-to', join(appRoot, '.wrangler', 'state'), ...(o.port !== undefined ? ['--port', String(o.port)] : []), ...o.wranglerArgs]
+  let child: ReturnType<typeof Bun.spawn> | null = null
+  let stopping = false
+  let restarting = false
+  let exitCode: (c: number) => void = () => {}
+  const done = new Promise<number>((r) => {
+    exitCode = r
+  })
+  const spawn = () => {
+    const c = Bun.spawn([bin, ...args], { cwd: appRoot, stdio: ['inherit', 'inherit', 'inherit'] })
+    child = c
+    c.exited.then((code) => {
+      if (child !== c || stopping || restarting) return
+      watcher?.close()
+      exitCode(code)
+    })
+  }
+  const stopChild = async () => {
+    const c = child
+    if (!c) return
+    c.kill('SIGTERM')
+    await c.exited
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let building = false
+  let again = false
+  const rebuild = async () => {
+    if (building) {
+      again = true
+      return
+    }
+    building = true
+    do {
+      again = false
+      o.log('[brust] change detected; rebuilding')
+      if ((await build()) === 0) {
+        restarting = true
+        await stopChild()
+        restarting = false
+        if (!stopping) spawn()
+      } else o.log('[brust] rebuild failed; keeping the running wrangler')
+    } while (again && !stopping)
+    building = false
+  }
+  const ignored = (rel: string) => {
+    const abs = resolve(appRoot, rel)
+    return rel.split(sep).some((s) => IGNORED.has(s)) || abs === dist || abs.startsWith(dist + sep) || abs.startsWith(`${dist}.`) || abs.startsWith(join(dirname(dist), `.${basename(dist)}.brust-`)) || relative(dist, abs) === ''
+  }
+  let watcher: FSWatcher | null = watch(appRoot, { recursive: true }, (_ev, name) => {
+    if (!name || ignored(String(name))) return
+    clearTimeout(timer)
+    timer = setTimeout(() => void rebuild(), DEBOUNCE_MS)
+  })
+
+  spawn()
+  const stop = () => {
+    if (stopping) return
+    stopping = true
+    clearTimeout(timer)
+    watcher?.close()
+    void stopChild().then(() => exitCode(0))
+  }
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+  return done
+}