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

package/src/native.ts

@@ -22,6 +22,8 @@ export interface StartOptions {
   workers: number
   claimTimeoutMs?: number
   callTimeoutMs?: number
+  /** L10: the biggest loader/jobs reply that may cross the heap when it does not fit the slot; absent = 8388608. */
+  maxLoaderResponseBytes?: number
   /** tokio I/O threads; absent = one per core. */
   workerThreads?: number
   l1Capacity?: number
@@ -31,6 +33,20 @@ export interface StartOptions {
   cors?: CorsOptions
   /** The actions subtree (M3-F A3); absent = no actions. Boot error `actions: …` when invalid. */
   actions?: ActionsOptions
+  /** L16: what the page tells the browser `client()` (base URL, credentials, a non-default prefix); absent = from `actions` alone. */
+  actionsClient?: ActionsClientOptions
+  /** The cache adapter (`manifest.cache`); absent = none (byte-identical server). */
+  l2?: L2Options
+  /** `brust dev` only (L14): a request carrying this token (`x-brust-dev-token`) is traced; absent in production. */
+  devToken?: string
+}
+/** napi `NapiL2Options`; defaults 50 ms, 1048576 bytes. */
+export interface L2Options {
+  adapter: string
+  getTimeoutMs?: number
+  maxBodyBytes?: number
+  namespace: string
+  buildId: string
 }
 /** napi `NapiCorsOptions` (camelCase keys; snake_case keys are silently dropped). */
 export interface CorsOptions {
@@ -41,12 +57,22 @@ export interface CorsOptions {
   credentials?: boolean
   maxAgeSeconds?: number
 }
-/** napi `NapiActionsOptions`; defaults `/_brust/action`, 262144. */
+/** napi `NapiActionsClient`. */
+export interface ActionsClientOptions {
+  prefix?: string
+  baseUrl?: string
+  credentials?: 'same-origin' | 'include' | 'omit'
+}
+/** napi `NapiActionsOptions`; defaults `/_brust/action`, 1048576, 8388608. */
 export interface ActionsOptions {
   prefix?: string
   maxBodyBytes?: number
+  /** F82: response body cap (bytes). Default 8388608. */
+  maxResponseBytes?: number
+  /** F87: cross-site mutating requests. Default `reject`. */
+  crossSite?: 'reject' | 'allow'
 }
-export type WorkerFn = (kind: 'loader' | 'jobs' | 'fetch', requestJson: string, slot: number) => Promise<number>
+export type WorkerFn = (kind: 'loader' | 'jobs' | 'fetch' | 'cache', requestJson: string, slot: number) => Promise<number>
 export interface NativeBinding {
   startServer(opts: StartOptions): void
   registerWorker(buf: Uint8Array, slots: number, f: WorkerFn): number
@@ -57,6 +83,20 @@ export interface NativeBinding {
   localAddr(): string
   /** M3-P P6 — see crates/brust-napi/src/server.rs `plan_jobs`. Never throws. */
   planJobs(slot: number, len: number): string
+  /** L10 — `planJobs` for a loader response too large for the slot: the bytes are handed over directly. Never throws. */
+  planJobsBuf(slot: number, buf: Uint8Array): string
+  /** F82 — the heap request body of the in-flight `fetch` call, once; null if none. Never throws. */
+  takeFetchBody(slot: number): Uint8Array | null
+  /** F82 — hand Rust a response body too large for the slot; false = declined. Never throws. */
+  putFetchReply(slot: number, body: Uint8Array): boolean
+  /** cache adapter R10 — a foreign broadcast event: tier 1 + the floor at `seq`; never re-published. */
+  cacheReplay(args: InvalidateArgs, seq: number | null): InvalidateResult
+  /** cache adapter R9 — bump `stats.l2[name]`; false = unknown name / no adapter / no server. Never throws. */
+  cacheL2Count(name: string): boolean
+  /** cache adapter R10 — drop both tier-1 caches (a broadcast gap); the L1 entries removed. */
+  cacheClear(): number
+  /** Static output (gaps round R9.4): the request reads of a cache key expression; throws when it does not parse. */
+  cacheExprReads(src: string): string[]
 }
 
 let binding: NativeBinding | null = null
@@ -83,3 +123,10 @@ export const cacheInvalidate = (args: InvalidateArgs): InvalidateResult => nativ
 export const cacheStats = (): string => native().cacheStats()
 export const localAddr = (): string => native().localAddr()
 export const planJobs = (slot: number, len: number): string => native().planJobs(slot, len)
+export const planJobsBuf = (slot: number, buf: Uint8Array): string => native().planJobsBuf(slot, buf)
+export const takeFetchBody = (slot: number): Uint8Array | null => native().takeFetchBody(slot)
+export const putFetchReply = (slot: number, body: Uint8Array): boolean => native().putFetchReply(slot, body)
+export const cacheReplay = (args: InvalidateArgs, seq: number | null): InvalidateResult => native().cacheReplay(args, seq)
+export const cacheL2Count = (name: string): boolean => native().cacheL2Count(name)
+export const cacheClear = (): number => native().cacheClear()
+export const cacheExprReads = (src: string): string[] => native().cacheExprReads(src)

package/src/routes.ts

@@ -1,3 +1,4 @@
+/// <reference path="./css-modules.d.ts" />
 // Route tree, ids and loader verdicts (spec S4, S7 step 4). M2 routes carry ONLY
 // `path/Component/loader/cache/children`; every other 0.1.x field fails loudly (M3).
 
@@ -29,15 +30,21 @@ export interface LoaderCtx<P = Record<string, string>> {
   req: LoaderReq
 }
 
+/** `brust build --target static` (gaps round R9.2): `params` lists the values of a dynamic route's
+ * `{name}` segments, one record per page; `false` leaves the route out of the static output. The
+ * server and Cloudflare targets ignore it. */
+export type RouteSsgConfig<P = Record<string, string>> = { params?: () => P[] | Promise<P[]> } | false
+
 export interface Route<P = Record<string, string>, D = unknown> {
   path?: string
   Component?: ComponentType<any>
   loader?: (ctx: LoaderCtx<P>) => Promise<D> | D
   cache?: RouteCacheConfig
+  ssg?: RouteSsgConfig<P>
   children?: Route<any, any>[]
 }
 
-export const ALLOWED_ROUTE_FIELDS = ['path', 'Component', 'loader', 'cache', 'children'] as const
+export const ALLOWED_ROUTE_FIELDS = ['path', 'Component', 'loader', 'cache', 'ssg', 'children'] as const
 const ALLOWED_CACHE_FIELDS = ['ttl_seconds', 'prefix', 'bypass', 'tags'] as const
 const M3_CACHE_FIELDS = ['key', 'key_ttl_seconds'] as const
 
@@ -61,6 +68,18 @@ function validate(node: Route, where: string): void {
   if (node.path !== undefined && typeof node.path !== 'string') throw new BrustRouteError(`route ${where}: path must be a string`)
   if (node.loader !== undefined && typeof node.loader !== 'function')
     throw new BrustRouteError(`route ${where}: loader must be a function`)
+  if (node.ssg !== undefined) {
+    const ssg = node.ssg as unknown
+    if (ssg !== false && (typeof ssg !== 'object' || ssg === null || Array.isArray(ssg)))
+      throw new BrustRouteError(`route ${where}: ssg must be false or { params }`)
+    if (ssg !== false) {
+      for (const k of Object.keys(ssg as object))
+        if (k !== 'params') throw new BrustRouteError(`route ${where}: unknown ssg field ssg.${k} (allowed: params)`)
+      const params = (ssg as { params?: unknown }).params
+      if (params !== undefined && typeof params !== 'function') throw new BrustRouteError(`route ${where}: ssg.params must be a function`)
+    }
+    if (node.children !== undefined) throw new BrustRouteError(`route ${where}: ssg on a layout route is not supported (put it on each leaf)`)
+  }
   if (node.cache !== undefined) {
     if (typeof node.cache !== 'object' || node.cache === null) throw new BrustRouteError(`route ${where}: cache must be an object`)
     for (const k of Object.keys(node.cache)) {

package/src/run.ts

@@ -4,42 +4,72 @@
 // once (130 / 143); a signal before every worker registered exits 0 at once (nothing is being
 // served yet, and the server's drain only starts once it accepts). A worker that dies (error,
 // process.exit, OOM) → drain → exit 1: M2 does not respawn, the supervisor restarts the process.
+// F165: a build whose manifest says `needs_workers: false` (no loader, job, actions app or cache
+// adapter) spawns none; the server then serves at once and a stray worker call answers 503.
 // Nothing here returns on its own: a started server keeps the process alive and a drained one
 // does not end it, so every exit is an explicit `process.exit`.
 import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { type BrustConfig, loadConfig } from './config'
-import { beginDrain, type StartOptions, startServer, untilReady } from './native'
-import { SLOT_BYTES } from './worker'
+import { type BrustConfig, type ConfigOverrides, loadConfig } from './config'
+import { beginDrain, localAddr, type StartOptions, startServer, untilReady } from './native'
+import { DEFAULT_MAX_LOADER_RESPONSE_BYTES } from './worker'
 
 export interface RunOptions {
   distDir?: string
   /** The routes module the workers import (`export const routes` or default). */
   entry?: string
   /** Overrides below env (CLI flags): see config.ts (incl. `bootTimeoutMs`, default 30000). */
-  config?: Partial<BrustConfig>
+  config?: ConfigOverrides
+  /** Static output (gaps round L9): runs once every worker is ready, with the bound `host:port`;
+   * then the server drains and the process exits with the returned code. */
+  onReady?: (addr: string) => Promise<number>
 }
 
 /** The manifest fields `run` needs (build/manifest.ts owns the full shape). */
 export interface RunManifest {
-  actions?: { entry: string; prefix: string; maxBodyBytes: number } | null
+  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } | null
+  /** L16 R16.3: `brust build --actions-only`: no page routes and no routes entry. */
+  actions_only?: boolean
+  /** L16 R16.4b: a page-only build; the actions app is deployed elsewhere (`[actions] base_url`). */
+  actions_remote?: { prefix: string } | null
+  /** `[cache]`: the server's L2 settings (the workers load the adapter itself). */
+  cache?: { adapter: string; getTimeoutMs: number; maxBodyBytes: number; namespace: string; buildId: string } | null
+  /** F165: `false` = no route can call a worker; absent (older manifests) = the pool is needed. */
+  needs_workers?: boolean
 }
 
-/** Pure: the napi `StartOptions`. No actions/cors → exactly the pre-actions keys. */
-export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest, version: string): StartOptions {
+/** F165 (R40.1): the pool size `run` spawns: none only when the build said no request needs one. */
+export function workerCount(cfg: BrustConfig, m: RunManifest): number {
+  return m.needs_workers === false ? 0 : cfg.workers
+}
+
+/** Pure: the napi `StartOptions`. No actions/cors/cache → exactly the pre-actions keys. */
+export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest, version: string, devToken?: string): StartOptions {
   return {
     host: cfg.host,
     port: cfg.port,
     distDir,
-    workers: cfg.workers,
+    workers: workerCount(cfg, m),
     callTimeoutMs: cfg.callTimeoutMs,
+    ...(cfg.maxLoaderResponseBytes !== undefined && cfg.maxLoaderResponseBytes !== DEFAULT_MAX_LOADER_RESPONSE_BYTES ? { maxLoaderResponseBytes: cfg.maxLoaderResponseBytes } : {}),
     workerThreads: cfg.ioThreads,
     generator: `brust/${version}`,
-    ...(m.actions ? { actions: { prefix: m.actions.prefix, maxBodyBytes: m.actions.maxBodyBytes } } : {}),
+    ...(m.actions ? { actions: { prefix: m.actions.prefix, maxBodyBytes: m.actions.maxBodyBytes, ...(m.actions.maxResponseBytes !== undefined ? { maxResponseBytes: m.actions.maxResponseBytes } : {}), ...(m.actions.crossSite ? { crossSite: m.actions.crossSite } : {}) } } : {}),
+    ...(actionsClient(cfg, m) ? { actionsClient: actionsClient(cfg, m) } : {}),
     ...(cfg.cors ? { cors: cfg.cors } : {}),
+    ...(devToken ? { devToken } : {}),
+    ...(m.cache ? { l2: { adapter: m.cache.adapter, getTimeoutMs: m.cache.getTimeoutMs, maxBodyBytes: m.cache.maxBodyBytes, namespace: m.cache.namespace, buildId: m.cache.buildId } } : {}),
   }
 }
 
+/** L16: what the page tells the browser `client()` (R16.1/R16.2); absent while it would only repeat the prefix script. */
+function actionsClient(cfg: BrustConfig, m: RunManifest): NonNullable<StartOptions['actionsClient']> | undefined {
+  const credentials = cfg.actionsCredentials !== undefined && cfg.actionsCredentials !== 'same-origin' ? cfg.actionsCredentials : undefined
+  if (cfg.actionsBaseUrl === undefined && credentials === undefined && !m.actions_remote) return undefined
+  const prefix = m.actions?.prefix ?? m.actions_remote?.prefix
+  return { ...(prefix ? { prefix } : {}), ...(cfg.actionsBaseUrl !== undefined ? { baseUrl: cfg.actionsBaseUrl } : {}), ...(credentials ? { credentials } : {}) }
+}
+
 /** Every worker's response buffer, kept reachable until the process exits (see run()). */
 const workerBuffers: SharedArrayBuffer[] = []
 
@@ -60,7 +90,8 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail(`bad manifest ${manifest}: ${(e as Error).message}`)
   }
   const entry = resolve(process.env.BRUST_APP_ENTRY || opts.entry || 'routes.tsx')
-  if (!existsSync(entry)) fail(`routes entry ${entry} not found`)
+  // R16.3: an actions-only dist has no pages, so no routes module either.
+  if (!m.actions_only && !existsSync(entry)) fail(`routes entry ${entry} not found`)
 
   let cfg: BrustConfig
   try {
@@ -69,9 +100,11 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail((e as Error).message)
   }
 
+  if (m.actions_remote && cfg.actionsBaseUrl === undefined)
+    fail('this build has no local actions app: set [actions] base_url (or BRUST_ACTIONS_BASE_URL) to the deployment that serves them')
   const version: string = (await Bun.file(join(import.meta.dir, '../package.json')).json()).version
   try {
-    startServer(startOptions(cfg, distDir, m, version))
+    startServer(startOptions(cfg, distDir, m, version, process.env.BRUST_DEV_TOKEN || undefined))
   } catch (e) {
     fail((e as Error).message)
   }
@@ -84,8 +117,12 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     ...process.env,
     NODE_ENV: process.env.NODE_ENV,
     BRUST_RENDER_SLOTS: String(cfg.renderSlots),
+    BRUST_SLOT_BYTES: String(cfg.slotBytes),
+    BRUST_MAX_LOADER_RESPONSE_BYTES: String(cfg.maxLoaderResponseBytes),
     BRUST_DIST_DIR: distDir,
     BRUST_APP_ENTRY: entry,
+    // One cache-adapter origin per process: its workers' published events are not replayed here.
+    BRUST_CACHE_ORIGIN: crypto.randomUUID(),
   }
 
   let ready = false
@@ -106,11 +143,12 @@ export async function run(opts: RunOptions = {}): Promise<void> {
       .finally(() => exit(failed ? 1 : code))
   }
 
+  const workers = workerCount(cfg, m)
   const url = new URL('./worker.ts', import.meta.url)
-  for (let i = 0; i < cfg.workers; i++) {
+  for (let i = 0; i < workers; i++) {
     // The response buffer is owned HERE, for the process lifetime: the Rust dispatcher keeps a raw
     // pointer into it, so it must not be freed with the worker (crates/brust-napi dispatch.rs).
-    const sab = new SharedArrayBuffer(SLOT_BYTES * cfg.renderSlots)
+    const sab = new SharedArrayBuffer(cfg.slotBytes * cfg.renderSlots)
     workerBuffers.push(sab)
     const w = new Worker(url, { env: { ...env, BRUST_WORKER_ID: String(i) }, workerData: { sab } } as WorkerOptions)
     // No respawn in M2: a worker that fails to boot or dies later takes the process down loudly
@@ -152,6 +190,15 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail(`workers not ready: ${String((e as Error).message ?? e)} (BRUST_BOOT_TIMEOUT_MS=${cfg.bootTimeoutMs})`)
   }
   ready = true
-  console.log(`[brust] ready (${cfg.workers} worker${cfg.workers === 1 ? '' : 's'})`)
+  console.log(`[brust] ready (${workers} worker${workers === 1 ? '' : 's'})`)
+  if (opts.onReady) {
+    let code = 1
+    try {
+      code = await opts.onReady(localAddr())
+    } catch (e) {
+      console.error(`[brust] ${(e as Error).stack ?? String(e)}`)
+    }
+    if (!draining) drainThenExit(code)
+  }
   await new Promise<never>(() => {})
 }

package/src/server-handlers.ts

@@ -0,0 +1,32 @@
+// What the generated Cloudflare entry (`brust-app.js`) imports: the host-agnostic handler code and the
+// store-scoped action fetch. No Bun / worker_threads here; `actions-bridge`'s napi import is stubbed by the
+// CF bundle (M4-CF R8).
+import { type CfCacheBridge, type CfInstallExt, installCache } from './cache-adapter/workers'
+import type { InvalidateArgs, InvalidateResult } from './native'
+
+export { fetchInScope, noActions } from './actions-bridge'
+export { jsonCall, makeHandlers } from './handlers'
+export { flattenRoutes } from './routes'
+
+/** What the wasm side hands over at start (`#[event(start]` -> `install({ invalidate, l2Count })`, ruling 19753649). */
+export interface CfRuntime {
+  invalidate(args: InvalidateArgs): InvalidateResult
+  /** Bumps a `stats.l2` counter (cache adapters R9). */
+  l2Count?(name: string): boolean
+}
+export type { CfCacheBridge, CfInstallExt }
+
+let rt: CfRuntime | null = null
+
+/** Called by the wasm glue once at Worker start; the CF bundle's napi stub forwards `cacheInvalidate` to it.
+ * With a cache adapter (`ext`, from the generated entry) it answers the adapter bridge (R11, R14). */
+export function install(runtime: CfRuntime, ext?: CfInstallExt): { cache: CfCacheBridge | null } {
+  rt = runtime
+  return { cache: ext ? installCache(runtime, ext) : null }
+}
+
+/** The installed runtime; throws before `install` (a request cannot arrive earlier). */
+export function installedRuntime(): CfRuntime {
+  if (!rt) throw new Error('brust: the Cloudflare runtime is not installed (install(rt) was not called at start)')
+  return rt
+}

package/src/shadcn/init.ts

@@ -0,0 +1,213 @@
+// `brust shadcn init [component ...]`: sets a brust project up for shadcn/ui and adds components (F175, R41.1-R41.10).
+// shadcn's own `init` does not detect brust, so this writes what `add` needs (components.json, the `@/*` path),
+// installs the four packages the components import, and runs ONE pinned shadcn CLI for the theme and the components.
+// Every child process is spawned from an argv array, never through a shell; the runner is injected for tests.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import { type ObjectNode, raw, readObject } from './jsonc'
+
+/** The shadcn CLI version this command runs (R41.6). A release that moves it re-runs the transcript. */
+export const SHADCN_VERSION = '4.21.4'
+
+/** The packages the components import (R41.5). */
+export const SHADCN_DEPS = ['radix-ui', 'lucide-react', 'class-variance-authority', 'tw-animate-css'] as const
+
+/** Runs `argv` in `cwd` with the terminal attached; resolves to the exit code. Never a shell string. */
+export type Runner = (argv: string[], cwd: string) => Promise<number>
+
+export interface InitOptions {
+  /** Project root (cwd). */
+  root: string
+  components: string[]
+  force?: boolean
+  css?: string
+  baseColor?: string
+  shadcnVersion?: string
+  run: Runner
+  out: (line: string) => void
+}
+
+const COMPONENT = /^[a-z0-9][a-z0-9-]*$/
+const REGISTRY_URL = /^https:\/\/[^\s]+$/
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+const COLOR = /^[a-z]+$/
+
+/** The `components.json` of the tested fixture (`tests/fixtures/shadcn/components.json`), for `css` and `baseColor` (R41.2). */
+export function componentsJson(css: string, baseColor: string): string {
+  return `{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": { "config": "", "css": ${JSON.stringify(css)}, "baseColor": ${JSON.stringify(baseColor)}, "cssVariables": true, "prefix": "" },
+  "iconLibrary": "lucide",
+  "aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui", "lib": "@/lib", "hooks": "@/hooks" }
+}
+`
+}
+
+export type PathEdit =
+  | { kind: 'added'; text: string }
+  | { kind: 'present' }
+  | { kind: 'other'; target: string }
+  | { kind: 'unparseable'; why: string }
+
+const ENTRY = '"@/*": ["./*"]'
+
+/** The separator before a non-empty object's first member, so the new entry takes the same line and indent. */
+function lead(text: string, o: ObjectNode): string {
+  const first = o.members[0]
+  if (!first) return ' '
+  const nl = text.lastIndexOf('\n', first.keyStart)
+  const indent = nl > o.open ? text.slice(nl + 1, first.keyStart) : ''
+  if (nl > o.open && /^\s*$/.test(indent)) return `\n${indent}`
+  const same = text.slice(o.open + 1, first.keyStart)
+  return /^\s*$/.test(same) ? same : ' '
+}
+
+/** Adds `"@/*": ["./*"]` to `compilerOptions.paths` as a text splice (R41.4): comments and layout are kept. */
+export function addAliasPath(text: string): PathEdit {
+  let top: ObjectNode
+  try {
+    top = readObject(text)
+  } catch (e) {
+    return { kind: 'unparseable', why: (e as Error).message }
+  }
+  const co = top.members.find((m) => m.key === 'compilerOptions')?.object
+  if (!co) return { kind: 'unparseable', why: 'no compilerOptions object' }
+  const pathsMember = co.members.find((m) => m.key === 'paths')
+  if (!pathsMember) {
+    const ws = lead(text, co)
+    const body = co.members.length > 0 ? `${ws}"paths": { ${ENTRY} },` : ` "paths": { ${ENTRY} } `
+    return { kind: 'added', text: text.slice(0, co.open + 1) + body + text.slice(co.open + 1) }
+  }
+  const paths = pathsMember.object
+  if (!paths) return { kind: 'unparseable', why: 'compilerOptions.paths is not an object' }
+  const existing = paths.members.find((m) => m.key === '@/*')
+  if (existing) {
+    const target = raw(text, existing)
+    return target.replace(/\s+/g, '') === '["./*"]' ? { kind: 'present' } : { kind: 'other', target }
+  }
+  const ws = lead(text, paths)
+  const body = paths.members.length > 0 ? `${ws}${ENTRY},` : ` ${ENTRY} `
+  return { kind: 'added', text: text.slice(0, paths.open + 1) + body + text.slice(paths.open + 1) }
+}
+
+/** The Tailwind entry CSS: `--css`, else the one top-level `*.css` that imports `tailwindcss` (R41.3). */
+function tailwindEntry(root: string, css: string | undefined): { css: string } | { error: string } {
+  if (css !== undefined) {
+    const abs = resolve(root, css)
+    const rel = relative(root, abs)
+    if (css.startsWith('-') || isAbsolute(css) || rel.startsWith('..') || !existsSync(abs)) {
+      return { error: `--css ${JSON.stringify(css)} must be an existing CSS file inside the project` }
+    }
+    return { css: rel.split('\\').join('/') }
+  }
+  const hit = ['app.css', 'styles.css', 'global.css', 'globals.css', 'index.css'].filter((f) => {
+    const p = join(root, f)
+    return existsSync(p) && /@import\s+["']tailwindcss["']/.test(readFileSync(p, 'utf8'))
+  })
+  if (hit.length === 1) return { css: hit[0]! }
+  return { error: hit.length === 0 ? 'cannot tell which CSS file is the Tailwind entry; pass --css <file>' : `more than one Tailwind entry (${hit.join(', ')}); pass --css <file>` }
+}
+
+type Step = 'done' | 'skipped' | 'failed'
+
+/** Returns the process exit code: 0 ok, 2 usage / not a brust project, else the failing child's code. */
+export async function shadcnInit(o: InitOptions): Promise<number> {
+  const { root, out } = o
+  const fail2 = (msg: string): number => {
+    out(`error shadcn-init ${msg}`)
+    return 2
+  }
+  // R41.1: a brust project root.
+  const pkgPath = join(root, 'package.json')
+  if (!existsSync(pkgPath)) return fail2('no package.json here: run it in the root of a brust project')
+  let pkg: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  } catch {
+    return fail2('package.json is not valid JSON')
+  }
+  if (!pkg.dependencies?.['@brust/core'] && !pkg.devDependencies?.['@brust/core']) {
+    return fail2('package.json does not depend on @brust/core: run it in the root of a brust project')
+  }
+  // R41.8: validate everything that reaches an argv before anything is written.
+  for (const c of o.components) {
+    if (!COMPONENT.test(c) && !REGISTRY_URL.test(c)) return fail2(`component ${JSON.stringify(c)} must match ^[a-z0-9][a-z0-9-]*$ or be an https:// registry URL`)
+  }
+  const version = o.shadcnVersion ?? SHADCN_VERSION
+  if (!VERSION.test(version)) return fail2(`--shadcn-version ${JSON.stringify(version)} must be an exact version like ${SHADCN_VERSION}`)
+  const baseColor = o.baseColor ?? 'neutral'
+  if (!COLOR.test(baseColor)) return fail2(`--base-color ${JSON.stringify(baseColor)} must be a lowercase colour name`)
+  const entry = tailwindEntry(root, o.css)
+  if ('error' in entry) return fail2(entry.error)
+
+  const report = (name: string, step: Step, why = ''): void => out(`${step === 'done' ? '✓' : step === 'skipped' ? '-' : '✗'} ${name}: ${step}${why ? ` (${why})` : ''}`)
+  const stop = (name: string, code: number): number => {
+    report(name, 'failed', `exit ${code}`)
+    out(`error shadcn-init ${name} failed with exit code ${code}; fix it and run the command again (finished steps are skipped)`)
+    return code
+  }
+
+  // R41.2: components.json.
+  const cj = join(root, 'components.json')
+  if (!existsSync(cj) || o.force) {
+    writeFileSync(cj, componentsJson(entry.css, baseColor))
+    report('components.json', 'done', entry.css)
+  } else report('components.json', 'skipped', 'exists; --force replaces it')
+
+  // R41.4: the `@/*` path.
+  const tsPath = join(root, 'tsconfig.json')
+  if (!existsSync(tsPath)) {
+    report('tsconfig.json', 'skipped', `no tsconfig.json; add ${JSON.stringify({ compilerOptions: { paths: { '@/*': ['./*'] } } })}`)
+  } else {
+    const edit = addAliasPath(readFileSync(tsPath, 'utf8'))
+    if (edit.kind === 'added') {
+      writeFileSync(tsPath, edit.text)
+      report('tsconfig.json', 'done', 'added "@/*": ["./*"] under compilerOptions.paths')
+    } else if (edit.kind === 'present') report('tsconfig.json', 'skipped', '"@/*" is already there')
+    else if (edit.kind === 'other') report('tsconfig.json', 'skipped', `warning: "@/*" already points at ${edit.target}; shadcn's imports need ["./*"]`)
+    else report('tsconfig.json', 'skipped', `not edited (${edit.why}); add this line to compilerOptions.paths yourself: ${ENTRY}`)
+  }
+
+  // R41.5: dependencies.
+  const have = { ...pkg.devDependencies, ...pkg.dependencies }
+  const missing = SHADCN_DEPS.filter((d) => !have[d])
+  if (missing.length === 0) report('dependencies', 'skipped', 'all four are installed')
+  else {
+    const code = await o.run(['bun', 'add', ...missing], root)
+    if (code !== 0) return stop('bun add', code)
+    report('dependencies', 'done', missing.join(' '))
+  }
+
+  // R41.6 / R41.7: the pinned shadcn CLI. `bun x` is `bunx`; argv only.
+  const shadcn = (...args: string[]): string[] => ['bun', 'x', `shadcn@${version}`, ...args]
+  const cssText = readFileSync(join(root, entry.css), 'utf8')
+  if (cssText.includes('shadcn/tailwind.css') && !o.force) report('theme', 'skipped', `${entry.css} already has the shadcn theme; --force runs it again`)
+  else {
+    const code = await o.run(shadcn('add', 'index', '-y'), root)
+    if (code !== 0) return stop('shadcn add index', code)
+    report('theme', 'done', `shadcn@${version} add index`)
+  }
+  // A component whose file is already in components/ui is not added again (idempotent); a URL always is.
+  const todo = o.components.filter((c) => o.force || REGISTRY_URL.test(c) || !existsSync(join(root, 'components/ui', `${c}.tsx`)))
+  for (const c of o.components) if (!todo.includes(c)) report(c, 'skipped', 'components/ui already has it')
+  if (todo.length > 0) {
+    const code = await o.run(shadcn('add', ...todo, '-y'), root)
+    if (code !== 0) return stop(`shadcn add ${todo.join(' ')}`, code)
+    for (const c of todo) report(c, 'done')
+  }
+
+  out('')
+  out('next:')
+  out("  import the components from './components/ui/<name>' in a page and add the route to routes.tsx")
+  out('  bun run build')
+  return 0
+}
+
+/** The real runner: argv spawn with the terminal attached, no shell. */
+export const spawnRunner: Runner = async (argv, cwd) => {
+  const p = Bun.spawn(argv, { cwd, stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
+  return await p.exited
+}

package/src/shadcn/jsonc.ts

@@ -0,0 +1,129 @@
+// A minimal JSONC reader that keeps byte offsets, so a file can be edited with a text splice (comments, trailing
+// commas and formatting survive). It does not build values; it finds object members. Anything it cannot read throws.
+
+export interface Member {
+  key: string
+  /** Offset of the member's key (its opening quote). */
+  keyStart: number
+  /** Offset of the member's value (the `{` of an object value). */
+  value: number
+  /** Offset just past the value. */
+  end: number
+  /** Parsed object when the value is an object, else `undefined`. */
+  object?: ObjectNode
+}
+
+export interface ObjectNode {
+  /** Offset of `{`. */
+  open: number
+  /** Offset of `}`. */
+  close: number
+  members: Member[]
+}
+
+class Reader {
+  i = 0
+  constructor(readonly s: string) {}
+
+  ws(): void {
+    const { s } = this
+    for (;;) {
+      const c = s[this.i]
+      if (c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '') this.i++
+      else if (c === '/' && s[this.i + 1] === '/') {
+        while (this.i < s.length && s[this.i] !== '\n') this.i++
+      } else if (c === '/' && s[this.i + 1] === '*') {
+        const e = s.indexOf('*/', this.i + 2)
+        if (e < 0) throw new Error('unterminated comment')
+        this.i = e + 2
+      } else return
+    }
+  }
+
+  string(): string {
+    const { s } = this
+    if (s[this.i] !== '"') throw new Error(`expected a string at ${this.i}`)
+    let j = this.i + 1
+    let out = ''
+    while (j < s.length && s[j] !== '"') {
+      if (s[j] === '\\') {
+        out += s[j + 1] ?? ''
+        j += 2
+      } else if (s[j] === '\n') throw new Error('newline in a string')
+      else out += s[j++]
+    }
+    if (s[j] !== '"') throw new Error('unterminated string')
+    this.i = j + 1
+    return out
+  }
+
+  /** Skips one value; returns its object node when it is an object. */
+  value(): ObjectNode | undefined {
+    this.ws()
+    const c = this.s[this.i]
+    if (c === '{') return this.object()
+    if (c === '[') {
+      this.i++
+      for (;;) {
+        this.ws()
+        if (this.s[this.i] === ']') {
+          this.i++
+          return undefined
+        }
+        this.value()
+        this.ws()
+        if (this.s[this.i] === ',') this.i++
+        else if (this.s[this.i] !== ']') throw new Error(`expected , or ] at ${this.i}`)
+      }
+    }
+    if (c === '"') {
+      this.string()
+      return undefined
+    }
+    const m = /^(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)/.exec(this.s.slice(this.i, this.i + 40))
+    if (!m) throw new Error(`unexpected character at ${this.i}`)
+    this.i += m[0].length
+    return undefined
+  }
+
+  object(): ObjectNode {
+    const open = this.i
+    this.i++
+    const members: Member[] = []
+    for (;;) {
+      this.ws()
+      if (this.s[this.i] === '}') {
+        this.i++
+        return { open, close: this.i - 1, members }
+      }
+      const keyStart = this.i
+      const key = this.string()
+      this.ws()
+      if (this.s[this.i] !== ':') throw new Error(`expected : at ${this.i}`)
+      this.i++
+      this.ws()
+      const value = this.i
+      const object = this.value()
+      members.push({ key, keyStart, value, end: this.i, ...(object && { object }) })
+      this.ws()
+      if (this.s[this.i] === ',') this.i++
+      else if (this.s[this.i] !== '}') throw new Error(`expected , or } at ${this.i}`)
+    }
+  }
+}
+
+/** The top-level object of a JSONC text. Throws on anything that is not JSONC. */
+export function readObject(text: string): ObjectNode {
+  const r = new Reader(text)
+  r.ws()
+  if (text[r.i] !== '{') throw new Error('not an object')
+  const o = r.object()
+  r.ws()
+  if (r.i !== text.length) throw new Error('trailing content')
+  return o
+}
+
+/** The raw text of a member's value. */
+export function raw(text: string, m: Member): string {
+  return text.slice(m.value, m.end)
+}