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

package/src/cache-adapter/memory.ts

@@ -0,0 +1,229 @@
+// The in-memory cache adapter: the reference implementation of the contract (exact stale-write
+// guard, push or pull broadcast with a bounded ring) and the test double for brust's own suites.
+// Not a production backend: it shares nothing across processes. No `bun` import (CF-bundle safe).
+import type {
+  CacheAdapter,
+  CacheBroadcast,
+  CacheStore,
+  EpochSince,
+  GetResult,
+  InvalidateArgs,
+  InvalidationEvent,
+  SetMeta,
+  StoredPage,
+} from './types'
+
+export interface MemoryAdapterOptions {
+  broadcast?: 'push' | 'pull' | 'none'
+  /** Ring capacity in events (pull). Default 1024. */
+  ring?: number
+  /** Ring capacity in serialized bytes (pull). Default 1 MiB. */
+  ringBytes?: number
+  /** Default 8 MiB. */
+  maxBodyBytes?: number
+  now?: () => number
+}
+
+/** One event above this many serialized bytes is kept as a gap marker (readers clear). */
+const OVERSIZE_EVENT = 64 * 1024
+
+interface Entry {
+  page: StoredPage
+  tags: string[]
+  method: string
+  path: string
+  entryStamp: number | null
+  storedAt: number
+  expiresAt: number
+}
+
+type Slot = { seq: number; bytes: number; event: InvalidationEvent | null }
+
+export interface MemoryAdapterTest {
+  /** A new generation (a restarted broadcast): readers see `gen` change. */
+  regen(): void
+  /** The next `get` settles as a miss after `ms` (default 2000). */
+  hangNextGet(ms?: number): void
+  /** The next store/broadcast call rejects. */
+  failNext(): void
+  /** The next `store.invalidate` waits `ms` before it marks and deletes (a slow networked store). */
+  delayNextInvalidate(ms: number): void
+  publishCount(): number
+  /** Stored entries (expired ones included). */
+  size(): number
+}
+
+export type MemoryAdapter = CacheAdapter & { store: CacheStore; __test: MemoryAdapterTest }
+
+const pathName = (method: string | undefined, path: string) => `${method ?? 'GET'} ${path}`
+
+export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
+  const mode = o.broadcast ?? 'push'
+  const ringCap = o.ring ?? 1024
+  const ringBytes = o.ringBytes ?? 1_048_576
+  const maxBodyBytes = o.maxBodyBytes ?? 8_388_608
+  const now = o.now ?? Date.now
+  const entries = new Map<string, Entry>()
+  const tagSeq = new Map<string, number>()
+  const pathSeq = new Map<string, number>()
+  let seq = 0
+  // Drawn on first use: a Workers module may not make random values at global scope.
+  let genValue: string | null = null
+  const gen = () => (genValue ??= randomGen())
+  const ring: Slot[] = []
+  let ringUsed = 0
+  /** The highest seq no longer in the ring (a reader at or below seq-1 of it is behind). */
+  let dropped = 0
+  let publishes = 0
+  let hang: number | null = null
+  let fail = false
+  let invalidateDelay = 0
+  const subscribers = new Set<{ on: (e: InvalidationEvent) => void; onGap: () => void }>()
+
+  const guarded = mode !== 'none'
+  const failing = () => {
+    if (!fail) return false
+    fail = false
+    return true
+  }
+  const raise = (m: Map<string, number>, k: string, s: number) => m.set(k, Math.max(m.get(k) ?? 0, s))
+  const mark = (args: InvalidateArgs, s: number) => {
+    for (const t of args.tags ?? []) raise(tagSeq, t, s)
+    if (args.path !== undefined) raise(pathSeq, pathName(args.method, args.path), s)
+  }
+
+  const store: CacheStore = {
+    maxBodyBytes,
+    async get(key: string): Promise<GetResult> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      if (hang !== null) {
+        const ms = hang
+        hang = null
+        await new Promise(r => setTimeout(r, ms))
+        return { page: null, stamp: guarded ? seq : null, entryStamp: null, storedAt: null }
+      }
+      const e = entries.get(key)
+      const stamp = guarded ? seq : null
+      if (!e || e.expiresAt <= now()) {
+        if (e) entries.delete(key)
+        return { page: null, stamp, entryStamp: null, storedAt: null }
+      }
+      return { page: copyPage(e.page), stamp, entryStamp: e.entryStamp, storedAt: e.storedAt }
+    },
+    async set(key: string, page: StoredPage, meta: SetMeta): Promise<boolean> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      if (page.body.length > maxBodyBytes) return false
+      if (meta.stamp !== null) {
+        const s = meta.stamp
+        const stale = (m: Map<string, number>, k: string) => (m.get(k) ?? 0) > s
+        if (meta.tags.some(t => stale(tagSeq, t)) || stale(pathSeq, pathName(meta.method, meta.path))) return false
+      }
+      const at = now()
+      entries.set(key, {
+        page: copyPage(page),
+        tags: [...meta.tags],
+        method: meta.method,
+        path: meta.path,
+        entryStamp: meta.stamp,
+        storedAt: at,
+        expiresAt: at + meta.ttlMs,
+      })
+      return true
+    },
+    async invalidate(args: InvalidateArgs): Promise<void> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      if (invalidateDelay > 0) {
+        const ms = invalidateDelay
+        invalidateDelay = 0
+        await new Promise(r => setTimeout(r, ms))
+      }
+      // L7b: the marker first, at the seq the matching publish will take (seq + 1), so a set whose
+      // stamp was read before this call is refused from now on; then the delete.
+      mark(args, seq + 1)
+      const tags = new Set(args.tags ?? [])
+      const p = args.path === undefined ? null : pathName(args.method, args.path)
+      for (const [k, e] of entries) {
+        if (e.tags.some(t => tags.has(t)) || (p !== null && pathName(e.method, e.path) === p)) entries.delete(k)
+      }
+    },
+  }
+
+  const push = (event: InvalidationEvent) => {
+    const bytes = JSON.stringify(event).length
+    const slot: Slot = { seq: event.seq, bytes: Math.min(bytes, OVERSIZE_EVENT), event: bytes > OVERSIZE_EVENT ? null : event }
+    ring.push(slot)
+    ringUsed += slot.bytes
+    while (ring.length > ringCap || ringUsed > ringBytes) {
+      const old = ring.shift()!
+      ringUsed -= old.bytes
+      dropped = old.seq
+    }
+  }
+
+  const broadcast: CacheBroadcast = {
+    async publish(args: InvalidateArgs, origin: string): Promise<number> {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      seq += 1
+      publishes += 1
+      mark(args, seq)
+      const event: InvalidationEvent = { seq, origin, args: structuredClone(args) }
+      push(event)
+      for (const s of subscribers) queueMicrotask(() => s.on(structuredClone(event)))
+      return seq
+    },
+  }
+  if (mode === 'push') {
+    broadcast.subscribe = async (on, onGap) => {
+      const sub = { on, onGap }
+      subscribers.add(sub)
+      return async () => {
+        subscribers.delete(sub)
+      }
+    }
+  }
+  if (mode === 'pull') {
+    broadcast.since = async (from: number): Promise<EpochSince> => {
+      if (failing()) throw new Error('memory adapter: injected failure')
+      const after = ring.filter(s => s.seq > from)
+      const behind = from < dropped || after.some(s => s.event === null)
+      return { gen: gen(), seq, behind, events: behind ? [] : after.map(s => structuredClone(s.event!)) }
+    }
+  }
+
+  return {
+    name: 'memory',
+    runtimes: ['bun', 'workers'],
+    store,
+    ...(mode === 'none' ? {} : { broadcast }),
+    __test: {
+      regen() {
+        genValue = randomGen()
+        ring.length = 0
+        ringUsed = 0
+        dropped = seq
+        for (const s of subscribers) queueMicrotask(() => s.onGap())
+      },
+      hangNextGet(ms = 2000) {
+        hang = ms
+      },
+      failNext() {
+        fail = true
+      },
+      delayNextInvalidate(ms: number) {
+        invalidateDelay = ms
+      },
+      publishCount: () => publishes,
+      size: () => entries.size,
+    },
+  }
+}
+
+function copyPage(p: StoredPage): StoredPage {
+  return { status: p.status, headers: p.headers.map(([k, v]) => [k, v] as [string, string]), body: p.body.slice() }
+}
+
+function randomGen(): string {
+  const b = new Uint8Array(8)
+  crypto.getRandomValues(b)
+  return Array.from(b, x => x.toString(16).padStart(2, '0')).join('')
+}

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)