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

package/src/shadcn/registry.ts

@@ -0,0 +1,149 @@
+// F228: a registry URL given to `brust shadcn init` names a third-party item that declares its own file targets, known
+// only once the item is fetched. This fetches the item JSON BEFORE the shadcn CLI is spawned (https only, a size cap, a
+// timeout, redirects followed by hand and only to https) and checks every path it can make the CLI write. The command
+// then hands the CLI the file it checked, not the URL, so the item cannot change between the check and the write.
+
+/** The most bytes of item JSON read; a bigger answer is refused. */
+export const ITEM_MAX_BYTES = 1024 * 1024
+/** The whole fetch (redirects included) gets this long. */
+export const ITEM_TIMEOUT_MS = 15_000
+/** Redirects followed by hand; each target must be https. */
+export const MAX_REDIRECTS = 3
+
+export interface FetchOptions {
+  /** URL schemes allowed for the request and every redirect. Default `https:` only; a test passes `http:` for a local server. */
+  schemes?: string[]
+  maxBytes?: number
+  timeoutMs?: number
+}
+
+/** Fetches `url` and returns the body text, or throws an `Error` whose message is the reason it was refused. */
+export async function fetchRegistryItem(url: string, o: FetchOptions = {}): Promise<string> {
+  const schemes = o.schemes ?? ['https:']
+  const maxBytes = o.maxBytes ?? ITEM_MAX_BYTES
+  const signal = AbortSignal.timeout(o.timeoutMs ?? ITEM_TIMEOUT_MS)
+  let cur = url
+  try {
+    for (let hop = 0; ; hop++) {
+      let u: URL
+      try {
+        u = new URL(cur)
+      } catch {
+        throw new Error(`${cur} is not a URL`)
+      }
+      if (!schemes.includes(u.protocol)) throw new Error(`${cur} is not an ${schemes.join(' or ').replace(/:/g, '')} URL`)
+      if (u.username !== '' || u.password !== '') throw new Error(`${u.origin}${u.pathname} carries credentials in the URL`)
+      const res = await fetch(u, { redirect: 'manual', signal, headers: { accept: 'application/json' } })
+      if (res.status >= 300 && res.status < 400) {
+        const next = res.headers.get('location')
+        await res.body?.cancel()
+        if (!next) throw new Error(`${cur} answered ${res.status} with no Location`)
+        if (hop >= MAX_REDIRECTS) throw new Error(`${url} redirects more than ${MAX_REDIRECTS} times`)
+        cur = new URL(next, u).toString() // the next loop turn refuses a non-https target
+        continue
+      }
+      if (!res.ok) {
+        await res.body?.cancel()
+        throw new Error(`${cur} answered HTTP ${res.status}`)
+      }
+      const declared = Number(res.headers.get('content-length'))
+      if (Number.isFinite(declared) && declared > maxBytes) {
+        await res.body?.cancel()
+        throw new Error(`${cur} is ${declared} bytes; the limit is ${maxBytes}`)
+      }
+      const reader = res.body?.getReader()
+      if (!reader) return ''
+      const chunks: Uint8Array[] = []
+      let size = 0
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        size += value.length
+        if (size > maxBytes) {
+          await reader.cancel()
+          throw new Error(`${cur} is bigger than the limit of ${maxBytes} bytes`)
+        }
+        chunks.push(value)
+      }
+      return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))
+    }
+  } catch (e) {
+    if (signal.aborted) throw new Error(`${url} did not answer within ${(o.timeoutMs ?? ITEM_TIMEOUT_MS) / 1000} s`)
+    throw e instanceof Error ? e : new Error(String(e))
+  }
+}
+
+/** True for a path that is not a plain relative path: absolute, a drive, a backslash, a NUL, a control character or `..`. */
+export function unsafeRel(p: string): boolean {
+  return p === '' || p.startsWith('/') || /^[a-zA-Z]:/.test(p) || p.includes('\\') || /[\x00-\x1f]/.test(p) || p.split('/').some((s) => s === '..') || (p.includes('%') && /%2e|%2f|%5c|%00/i.test(p))
+}
+
+export interface VettedItem {
+  /** Project-relative paths the CLI may write for this item, beyond the alias directories (checked for symlinks). */
+  paths: string[]
+}
+
+const PLAIN_NAME = /^[a-z0-9][a-z0-9-]*$/
+
+/** The top-level keys of an item in the pinned registry schema (`@shadcn/registry` 0.1.3). Allowlist, not denylist: a key
+ *  this does not name (`font`, which makes the CLI write the CSS entry and a layout file, or one a later schema adds) is a
+ *  refusal, because the CLI could write something this never judged. */
+const ITEM_KEYS = new Set(['$schema', 'extends', 'name', 'type', 'title', 'author', 'description', 'dependencies', 'devDependencies', 'registryDependencies', 'files', 'tailwind', 'cssVars', 'css', 'envVars', 'meta', 'docs', 'categories'])
+/** Item types whose files the CLI rewrites to a framework path (`registry:page`) or whose write set is not judged (`registry:font`). */
+const REFUSED_TYPES = new Set(['registry:font', 'registry:page'])
+
+/**
+ * Judges item JSON: the file targets it declares and the other things it makes the CLI write or fetch. Returns the
+ * paths to check for symlinks, or the reason it is refused. Fail closed: anything it cannot judge is a refusal.
+ */
+export function vetItem(text: string, cssEntry: string): VettedItem | { error: string } {
+  let item: unknown
+  try {
+    item = JSON.parse(text)
+  } catch {
+    return { error: 'is not valid JSON' }
+  }
+  if (typeof item !== 'object' || item === null || Array.isArray(item)) return { error: 'is not a JSON object' }
+  const o = item as Record<string, unknown>
+  if (o.type !== undefined && (typeof o.type !== 'string' || REFUSED_TYPES.has(o.type))) return { error: `is of type ${JSON.stringify(o.type)}, whose files the CLI places by rules this check does not model` }
+  const unknown = Object.keys(o).find((k) => !ITEM_KEYS.has(k))
+  if (unknown !== undefined) return { error: `has the key ${JSON.stringify(unknown)}, which this check does not know; it may make the CLI write files that cannot be checked` }
+  const paths: string[] = []
+  if (o.files !== undefined) {
+    if (!Array.isArray(o.files)) return { error: '"files" is not an array' }
+    for (const f of o.files) {
+      if (typeof f !== 'object' || f === null) return { error: 'has a file entry that is not an object' }
+      const { path, target } = f as { path?: unknown; target?: unknown }
+      if (path !== undefined && typeof path !== 'string') return { error: 'has a file with a "path" that is not a string' }
+      if (target !== undefined && typeof target !== 'string') return { error: 'has a file with a "target" that is not a string' }
+      if (typeof path === 'string' && unsafeRel(path)) return { error: `declares the file path ${JSON.stringify(path)}, which is not a plain path inside the project` }
+      if (typeof target === 'string' && target !== '') {
+        // The CLI's own rules (resolveFilePath): `~/x` is project-relative; `@components|ui|lib|hooks/x` is inside that alias
+        // directory (scanned already); any other target is joined to the project root, once as written and, in a `src/`
+        // project, under `src/` (it drops one `src/` from the target either way). All of them are checked.
+        const t = target.startsWith('~/') ? target.slice(2) : target
+        const alias = /^@(components|ui|lib|hooks)\/(.+)$/.exec(t)
+        if (alias) {
+          if (unsafeRel(alias[2]!)) return { error: `declares the file target ${JSON.stringify(target)}, which is not a plain path inside the project` }
+        } else {
+          const rel = t.replace(/^@([^/]+)\//, '$1/')
+          if (unsafeRel(rel)) return { error: `declares the file target ${JSON.stringify(target)}, which is not a plain path inside the project` }
+          const bare = rel.replace('src/', '')
+          paths.push(rel, bare, `src/${bare}`)
+        }
+      }
+    }
+  }
+  // what else the CLI writes: the Tailwind CSS entry (css, cssVars), env files (envVars)
+  if (o.css !== undefined || o.cssVars !== undefined || o.tailwind !== undefined) paths.push(cssEntry)
+  if (o.envVars !== undefined) paths.push('.env', '.env.local')
+  // dependencies on other items the CLI would fetch after this check (a `config` that would merge into components.json is an unknown key, refused above)
+  const deps = [...(Array.isArray(o.registryDependencies) ? o.registryDependencies : o.registryDependencies === undefined ? [] : [null]), ...(o.extends === undefined ? [] : [o.extends])]
+  for (const d of deps) {
+    if (typeof d !== 'string') return { error: 'has a registryDependencies / extends entry that is not a string' }
+    if (!PLAIN_NAME.test(d)) {
+      return { error: `depends on ${JSON.stringify(d)}, which the CLI would fetch after this check; pass that URL to the command as its own argument so it is checked too` }
+    }
+  }
+  return { paths }
+}

package/src/store/builtin.ts

@@ -0,0 +1,4 @@
+// Store modules brust ships. The compiler names them by package specifier (`StoreRef.module`) instead of an app-relative
+// path, so the manifest's `stores`, the `jobs.js` stores table and the loader's `touchStores` all use this spelling.
+export const NAVIGATION_MODULE = '@brust/core/navigation'
+export const BUILTIN_STORE_MODULES: readonly string[] = [NAVIGATION_MODULE]

package/src/worker.ts

@@ -1,14 +1,16 @@
 // The Bun side of contract 7 (`crates/brust-server/src/protocol.rs`): requests arrive as inline
 // JSON, responses go into this worker's SharedArrayBuffer slot (SAB rule, `dispatch.rs`). A
 // handler NEVER rejects across the tsfn: every failure becomes `{error}` / `{id, error}`.
+import { appendFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { workerData } from 'node:worker_threads'
 import { type HeapIo, runFetch, setActionsApp, setActionsLimits } from './actions-bridge'
 import { DEFAULT_MAX_RESPONSE_BYTES } from './actions/prefix'
 import { type CacheBridgeDeps, runCache } from './cache-adapter/bridge'
 import type { CacheManifest } from './cache-adapter/load'
-import { type Handlers, type JobsModule, type ManifestLike, makeHandlers, toJson } from './handlers'
-import { cacheClear, cacheL2Count, cacheReplay, planJobs, putFetchReply, registerWorker, takeFetchBody } from './native'
+import { type Handlers, type JobsModule, type ManifestLike, makeHandlers, type SsgRecord, toJson } from './handlers'
+import { cacheClear, cacheL2Count, cacheReplay, planJobs, planJobsBuf, putFetchReply, registerWorker, takeFetchBody } from './native'
+import { installProductionJsxDev, installServerOnlyRuntime } from './build/server-only'
 import { flattenRoutes, type Route } from './routes'
 
 export * from './handlers'
@@ -17,24 +19,58 @@ export * from './handlers'
 
 const enc = new TextEncoder()
 
+/** L10: the default `maxLoaderResponseBytes` (config.ts keeps the range). */
+export const DEFAULT_MAX_LOADER_RESPONSE_BYTES = 8_388_608
+
+/** L10: a reply too large for the slot crosses by heap: `HeapIo.putReply` hands Rust the bytes, and the slot holds
+ * the 5-byte marker `[0x00][u32 LE n]` (JSON never starts with 0x00). `cap` = `maxLoaderResponseBytes`. */
+export const HEAP_MARKER_BYTES = 5
+export interface HeapReply {
+  io: HeapIo
+  /** `planJobsBuf` (napi): plan a loader response handed over directly. */
+  planBuf: (slot: number, buf: Uint8Array) => string
+  /** Default: the worker's `maxLoaderResponseBytes` (env `BRUST_MAX_LOADER_RESPONSE_BYTES`, 8 MiB). */
+  cap?: number
+}
+const nativeHeap: HeapReply = { io: cacheHeapIo(), planBuf: (slot, buf) => planJobsBuf(slot, buf) }
+let loaderCap = DEFAULT_MAX_LOADER_RESPONSE_BYTES
+
 /** Writes `json` as UTF-8 at the start of `slot`'s sub-region `[slot*sub, slot*sub+sub)`,
  * `sub = floor(view.byteLength / slots)`; returns the byte length (> 0, ≤ sub). ONE copy: the
  * encoder writes straight into the slot (M3-P P1); it stops at the last whole code point that
  * fits, so `read < json.length` means "did not fit" and the neighbouring slot is never touched.
- * A response that does not fit is replaced by a small `{"error":"response too large: <n> > <sub>"}`
- * (`n` = its exact UTF-8 length, computed only on this path). */
-export function writeSlot(view: Uint8Array, slot: number, slots: number, json: string): number {
+ * A response that does not fit goes by heap when `io` and `cap` are given (L10): encoded once, handed to
+ * Rust with `io.putReply`, and the slot holds the 5-byte marker. Over `cap` (or declined), or with no `io`, it is
+ * replaced by a small `{"error":"response too large: <n> > <limit>"}` (`n` = its exact UTF-8 length, computed
+ * only on this path). */
+export function writeSlot(view: Uint8Array, slot: number, slots: number, json: string, io?: HeapIo, cap?: number): number {
   const sub = Math.floor(view.byteLength / Math.max(1, slots))
   const dst = view.subarray(slot * sub, slot * sub + sub)
   const r = enc.encodeInto(json, dst)
   if (r.read === json.length) return r.written
-  const err = JSON.stringify({ error: `response too large: ${Buffer.byteLength(json)} > ${sub}` })
+  let why = `response too large: ${Buffer.byteLength(json)} > ${sub}`
+  if (io && cap !== undefined && sub >= HEAP_MARKER_BYTES) {
+    const bytes = enc.encode(json)
+    const n = heapMarker(dst, slot, bytes, io, cap)
+    if (n > 0) return n
+    // Name the real reason: over the cap, or a put Rust declined while under it (idle slot, a second put).
+    why = bytes.length > cap ? `response too large: ${bytes.length} > ${cap} (maxLoaderResponseBytes)` : `heap reply declined: ${bytes.length} bytes did not fit the ${sub}-byte slot and Rust refused the handover`
+  }
+  const err = JSON.stringify({ error: why })
   const e = enc.encodeInto(err, dst)
   if (e.read === err.length) return e.written
   // Not even the message fits: the first `sub` bytes of a fixed one (ASCII, so byte = char).
   return enc.encodeInto('{"error":"too large"}', dst).written
 }
 
+/** Hand `bytes` to Rust and write the marker at `dst`; 0 when over `cap` or Rust declined. */
+function heapMarker(dst: Uint8Array, slot: number, bytes: Uint8Array, io: HeapIo, cap: number): number {
+  if (bytes.length > cap || !io.putReply(slot, bytes)) return 0
+  dst[0] = 0
+  new DataView(dst.buffer, dst.byteOffset + 1, 4).setUint32(0, bytes.length, true)
+  return HEAP_MARKER_BYTES
+}
+
 /** `planJobs` (napi): the misses' JobsRequest JSON, '' (every job hit) or PLAN_DECLINED. */
 export type PlanJobs = (slot: number, len: number) => string
 /** `planJobs` declined: the loader response already in the slot is the answer (Rust plans after the call). */
@@ -44,11 +80,13 @@ const PLANNED = { planned: true } as const
 /** The tsfn callback for `registerWorker`. Never rejects: a parse error, an unknown kind or a
  * throwing handler is written to the slot as `{error}`. A loader request with `plan: true` whose
  * chain answered `ok` is planned in the same call (`plan`, the napi `planJobs` by default — the
- * addon is touched only then). */
-export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan: PlanJobs = planJobs) {
+ * addon is touched only then). A loader/jobs/planned reply that does not fit the slot crosses by heap
+ * (`heap`, the napi addon by default; L10). */
+export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan: PlanJobs = planJobs, heap: HeapReply = nativeHeap) {
+  const cap = () => heap.cap ?? loaderCap
   return async (kind: string, requestJson: string, slot: number): Promise<number> => {
     if (kind === 'fetch') return runFetch(requestJson, view, slot, slots)
-    if (kind === 'cache') return runCache(requestJson, view, slot, slots, cacheHeapIo, cacheDeps)
+    if (kind === 'cache') return runCache(requestJson, view, slot, slots, cacheHeapIo(), cacheDeps)
     let out: unknown
     try {
       const req = JSON.parse(requestJson)
@@ -58,9 +96,20 @@ export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan:
           // One round trip (M3-P P6): the ctx goes to Rust through this slot, synchronously, and only
           // the jobs Rust found missing run here; the final answer replaces it in the same slot.
           const json = toJson(out)
-          const n = writeSlot(view, slot, slots, json)
-          const misses = plan(slot, n)
-          if (misses === PLAN_DECLINED) return n
+          const sub = Math.floor(view.byteLength / Math.max(1, slots))
+          const dst = view.subarray(slot * sub, slot * sub + sub)
+          const w = enc.encodeInto(json, dst)
+          let misses: string
+          if (w.read === json.length) {
+            misses = plan(slot, w.written)
+            if (misses === PLAN_DECLINED) return w.written
+          } else {
+            // L10: too large for the slot — plan from the bytes directly; a declined plan hands them over as the answer.
+            const bytes = enc.encode(json)
+            if (bytes.length > cap()) return writeSlot(view, slot, slots, json, heap.io, cap())
+            misses = heap.planBuf(slot, bytes)
+            if (misses === PLAN_DECLINED) return writeSlot(view, slot, slots, json, heap.io, cap())
+          }
           out = misses === '' ? PLANNED : { planned: true, results: (await h.jobs(JSON.parse(misses))).results }
         }
       } else if (kind === 'jobs') out = await h.jobs(req)
@@ -68,13 +117,15 @@ export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan:
     } catch (e) {
       out = { error: String(e) }
     }
-    return writeSlot(view, slot, slots, toJson(out))
+    return writeSlot(view, slot, slots, toJson(out), heap.io, cap())
   }
 }
 
 // ---- cache adapter (the `cache` call kind) ----
 
-const cacheHeapIo: HeapIo = { takeBody: (slot) => takeFetchBody(slot), putReply: (slot, body) => putFetchReply(slot, body) }
+function cacheHeapIo(): HeapIo {
+  return { takeBody: (slot) => takeFetchBody(slot), putReply: (slot, body) => putFetchReply(slot, body) }
+}
 const count = (name: string) => void cacheL2Count(name)
 let cacheDeps: CacheBridgeDeps = { store: undefined, getTimeoutMs: 50, maxBodyBytes: 1_048_576, count }
 
@@ -97,12 +148,20 @@ async function startCacheAdapter(m: CacheManifest, dist: string, appDir: string,
   return { adapter, origin }
 }
 
+// ---- static output (gaps round R9.5) ----
+
+/** Appends each record as one JSON line to `file` (every worker of the render appends to it). */
+function ssgLog(file: string): (r: SsgRecord) => void {
+  return (r) => appendFileSync(file, `${JSON.stringify(r)}\n`)
+}
+
 // ---- worker entry ----
 
+/** The default response slot (`slotBytes`, config.ts: 64 KiB..16 MiB). */
 export const SLOT_BYTES = 256 * 1024
 
 export interface StartWorkerOptions {
-  /** The response buffer to register (`SLOT_BYTES * slots` bytes). `run()` allocates it on the
+  /** The response buffer to register (`slotBytes * slots` bytes). `run()` allocates it on the
    * MAIN thread and keeps it for the process lifetime, passing it as `workerData.sab`: the Rust
    * dispatcher holds a raw pointer into it until the process exits, so its backing store must not
    * die with this worker (`crates/brust-napi/src/dispatch.rs` BufPtr). Absent (tests, a worker
@@ -121,29 +180,46 @@ export async function startWorker(opts: StartWorkerOptions = {}): Promise<number
   const env = process.env
   const slots = Math.max(1, Number.parseInt(env.BRUST_RENDER_SLOTS ?? '1', 10) || 1)
   const dist = resolve(env.BRUST_DIST_DIR ?? 'dist')
-  const entry = env.BRUST_APP_ENTRY
+  // L16 R16.3: an actions-only dist has no routes module (so no BRUST_APP_ENTRY either).
+  const manifestFile = join(dist, 'manifest.json')
+  const hasManifest = await Bun.file(manifestFile).exists()
+  const actionsOnly = hasManifest && !env.BRUST_APP_ENTRY && ((await Bun.file(manifestFile).json()) as { actions_only?: boolean }).actions_only === true
+  const entry = env.BRUST_APP_ENTRY ?? (actionsOnly ? join(dist, 'index.js') : undefined)
   if (!entry) throw new Error('BRUST_APP_ENTRY is not set')
-  const manifest = (await Bun.file(join(dist, 'manifest.json')).json()) as ManifestLike & { cache?: CacheManifest | null }
-  const app = await import(resolve(entry))
-  const routes = (app.routes ?? app.default) as Route[] | undefined
+  const manifest = (await Bun.file(manifestFile).json()) as ManifestLike & { cache?: CacheManifest | null; actions_only?: boolean }
+  let routes: Route[] | undefined = []
+  if (!manifest.actions_only) {
+    installServerOnlyRuntime()
+    installProductionJsxDev(dirname(resolve(entry)))
+    const app = await import(resolve(entry))
+    routes = (app.routes ?? app.default) as Route[] | undefined
+  }
   if (!Array.isArray(routes)) throw new Error(`${entry} exports no routes (export const routes or default)`)
   const jobsMod = await import(join(dist, manifest.jobs_module ?? 'jobs.js'))
   const jobs = (jobsMod.default ?? jobsMod) as JobsModule
   if (manifest.actions) {
     // Lazy: elysia is an optional peer, so an app without [actions] must boot without it installed (R7).
-    const { loadActionsApp } = await import('./actions/load')
-    setActionsApp(await loadActionsApp(join(dist, manifest.actions.entry), manifest.actions.prefix))
+    const { loadActionsApp, shadowedGetActions } = await import('./actions/load')
+    const actionsApp = await loadActionsApp(join(dist, manifest.actions.entry), manifest.actions.prefix)
+    setActionsApp(actionsApp)
+    // F470: a GET under the prefix that a route there matches is the route's; say which GET actions that hides (once)
+    const shadowed = env.BRUST_WORKER_ID && env.BRUST_WORKER_ID !== '0' ? [] : shadowedGetActions(actionsApp, flattenRoutes(routes).leaves.map((l) => l.pattern), manifest.actions.prefix)
+    if (shadowed.length) console.warn(`[brust] warning: a route under the actions prefix answers GET there, so these GET actions are never reached: ${shadowed.join(', ')}`)
     setActionsLimits({ maxResponseBytes: manifest.actions.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES })
   }
+  loaderCap = Number.parseInt(env.BRUST_MAX_LOADER_RESPONSE_BYTES ?? '', 10) || DEFAULT_MAX_LOADER_RESPONSE_BYTES
+  const slotBytes = Number.parseInt(env.BRUST_SLOT_BYTES ?? '', 10) || SLOT_BYTES
   const workerId = Number.parseInt(env.BRUST_WORKER_ID ?? '0', 10) || 0
   const l2 = manifest.cache ? await startCacheAdapter(manifest.cache, dist, dirname(resolve(entry)), workerId) : null
-  sab = opts.sab ?? new SharedArrayBuffer(SLOT_BYTES * slots)
+  sab = opts.sab ?? new SharedArrayBuffer(slotBytes * slots)
   view = new Uint8Array(sab)
   const handlers = makeHandlers({
     leaves: flattenRoutes(routes).leaves,
     jobs,
     manifest,
     stores: (jobsMod.stores ?? {}) as Record<string, object>,
+    ...(env.BRUST_SSG === '1' && env.BRUST_SSG_LOG ? { ssg: ssgLog(env.BRUST_SSG_LOG) } : {}),
+    dev: env.NODE_ENV === 'development',
   })
   const id = registerWorker(view, slots, makeDispatch(handlers, view, slots))
   if (l2 && env.BRUST_WORKER_ID === '0') {