@bakery-framework/core 2.0.0-alpha.9 → 2.0.0-rc.2

package/src/core/context.ts

@@ -5,6 +5,16 @@ import { fs } from '../utils/fs'
 export type HostContext = {
   config: Readonly<ProcessedAppConfig>
   hostname: string
+  /**
+   * The request this store was entered for, when there is one.
+   *
+   * Optional because two of the three `hostStore.run` sites have no request
+   * to offer: a WebSocket event carries `ws.data` rather than a `Request`,
+   * and the server's `error` hook receives one only sometimes. `getRequest()`
+   * below is what callers should use, and it reports the absence rather than
+   * handing back `undefined` for them to trip over.
+   */
+  req?: Request
   /**
    * Per-request memo of raw `.forbidden` marker probes, keyed by the marker
    * path (`<dir>/.forbidden`). Lazily created by `fs.isForbidden` and never
@@ -12,12 +22,12 @@ export type HostContext = {
    * `hostStore.run` in the tree wraps a single request, WebSocket event or
    * error dispatch, so the map dies with the store. That is what keeps this
    * distinct from the cross-request cache `fs.isForbidden`'s regression test
-   * forbids — see the block comment there. Bounded (convention 6) by request
+   * forbids. See the block comment there. Bounded (convention 6) by request
    * lifetime: one request touches a handful of paths, each of bounded depth.
    */
   forbiddenProbes?: Map<string, boolean>
   /**
-   * Per-request memo of `matchBlocked` verdicts keyed by request path — the
+   * Per-request memo of `matchBlocked` verdicts keyed by request path: the
    * router runs the check before dispatch and `StaticHandler.handle` must
    * keep its own (direct callers bypass the router gate), so without this the
    * same globs matched the same path twice per static request. Sound to key
@@ -33,7 +43,7 @@ export const hostStore = new AsyncLocalStorage<HostContext>()
  * The two runtime directories, defined here rather than on `Bakery`.
  *
  * `Bakery.cacheDir` / `Bakery.dataDir` remain the way application and framework
- * code reads them — these are the single definition those two forward to, and
+ * code reads them: these are the single definition those two forward to, and
  * still the only writer of either path. They live in this module because it is
  * low enough to be imported without pulling in `core/config`, and therefore
  * without pulling in the logger: `compiler/prompt-tracker.ts` needs the cache
@@ -43,7 +53,7 @@ export const hostStore = new AsyncLocalStorage<HostContext>()
  * **Functions, not constants, and that is not a style choice.** `utils/fs.ts`
  * imports this module for `hostStore`, so the two are themselves a cycle: a
  * top-level `` `${fs.cwd}/.cache` `` here is evaluated with `fs` still
- * uninitialised whenever `core/context` is reached first, and throws
+ * uninitialized whenever `core/context` is reached first, and throws
  * `TypeError: undefined is not an object`. Reading `fs.cwd` at call time is
  * what makes the order irrelevant.
  *
@@ -53,7 +63,7 @@ export const hostStore = new AsyncLocalStorage<HostContext>()
  * bump and dev<->prod switch, so a `rm -rf .*` or a "clean out the dotfiles"
  * sweep does exactly what the framework already does. The database is not
  * disposable, so it does not live behind a leading dot where such a sweep can
- * reach it, and never under `.cache` — clearing a cache must not destroy data.
+ * reach it, and never under `.cache`: clearing a cache must not destroy data.
  */
 export function cacheDir(): string {
   return `${fs.cwd}/.cache`
@@ -67,7 +77,7 @@ export function dataDir(): string {
  * `matchBlocked`, deduplicated within the current request.
  *
  * Outside a request store (tests, direct handler calls) this is exactly
- * `matchBlocked` — no caching, fail closed on nothing, because nothing is
+ * `matchBlocked`: no caching, fail closed on nothing, because nothing is
  * skipped. See `HostContext.blockedPaths` for the scoping argument.
  */
 export function matchBlockedCached(
@@ -92,7 +102,7 @@ export function matchBlockedCached(
  * and both halves are load-bearing. Distinct, because the two readers exist to
  * be different files and a shared fallback would let one silently stand in for
  * the other. Impossible, because they used to be plain `'1.0.0'` and `'0.0.0'`
- * — and when the framework was renumbered to 1.0.0 for its first publish, the
+ *, and when the framework was renumbered to 1.0.0 for its first publish, the
  * app fallback became a legitimate framework version. Nothing broke at runtime,
  * but `cache-version.test.ts` could no longer tell "read the manifest" from
  * "fell back to the other one", so the guard was disarmed by a version bump.
@@ -108,7 +118,7 @@ let _appVersion: string | null = null
 /**
  * The **application's** version, from `<cwd>/package.json`.
  *
- * Not the framework's — this reads the manifest of whatever is being served.
+ * Not the framework's: this reads the manifest of whatever is being served.
  * The distinction is load-bearing for cache invalidation; see
  * {@link getFrameworkVersion}.
  */
@@ -153,3 +163,39 @@ export function getFrameworkVersion() {
   }
   return _frameworkVersion || UNKNOWN_FW
 }
+
+/**
+ * The request being served, from anywhere inside the request.
+ *
+ * The point is that it needs no ambient declaration to reach a file. The Vue
+ * plugin's `<script server>` blocks used to get `req` and `body` as globals
+ * declared in `plugin-vue/src/vue.d.ts`, which works only if that file lands
+ * in whatever tsconfig project the editor picks for an SFC. It routinely does
+ * not: the generated project that names it lives under `.cache/tsconfig/`,
+ * which is not an ancestor of `src/`, so no editor resolves an SFC to it, and
+ * the symptom is `req` unresolved and `req.session` missing with nothing to
+ * point at. An import cannot fail that way.
+ *
+ * Two things it fixes beyond reachability. The ambient said `Request` while
+ * the value the Vue wrapper actually passes is typed `any`, so the promise
+ * and the runtime disagreed; this returns the one real type, `session`
+ * included. And it works inside a helper the block calls, which a wrapper
+ * parameter cannot reach without being threaded through by hand.
+ *
+ * **Throws when there is no request**, rather than returning `undefined`.
+ * There are exactly two such places and neither is application code that
+ * meant to ask: a WebSocket event (which has `ws.data`, not a `Request`) and
+ * boot-time code running before any request. Handing back `undefined` would
+ * push a null check into every call site to serve two cases that are bugs.
+ */
+export function getRequest(): Request {
+  const store = hostStore.getStore()
+  if (!store?.req) {
+    throw new Error(
+      'getRequest() was called outside a request. A WebSocket event has no ' +
+        'Request (use the handler argument), and boot-time code runs before ' +
+        'there is one.',
+    )
+  }
+  return store.req
+}

package/src/core/define-route.ts

@@ -5,8 +5,7 @@ import { type Validator, validate } from '../utils/http/validate'
 /**
  * `defineRoute`, in its own module rather than in `core/index.ts`.
  *
- * `core/index.ts` is a barrel — it pulls in the logger, plugins, jsx and utils —
- * so anything importing it from *inside* core closes a cycle and dies with
+ * `core/index.ts` is a barrel (it pulls in the logger, plugins, jsx and utils),  * so anything importing it from *inside* core closes a cycle and dies with
  * `ReferenceError: Cannot access 'Logger' before initialization`. That is
  * recorded in CLAUDE.md as costing 67 tests once; it cost this file's own tests
  * a second time, which is what moved it here. Consumers still reach it through
@@ -19,9 +18,9 @@ import { type Validator, validate } from '../utils/http/validate'
  *
  *   export default defineRoute<{ id: string }>((req, body) => …)
  *
- * With a validator, it also *enforces* that shape — see the overload below.
+ * With a validator, it also *enforces* that shape. See the overload below.
  *
- * `defineRoute`, not `defineHandler` — "handler" already means a registered
+ * `defineRoute`, not `defineHandler`: "handler" already means a registered
  * `Handler` subclass in this framework, and this defines a route module.
  */
 export function defineRoute<P = {}>(fn: RouteHandler<P>): RouteHandler<P>
@@ -30,7 +29,7 @@ export function defineRoute<P = {}>(fn: RouteHandler<P>): RouteHandler<P>
  *
  *   export default defineRoute({ body: schema }, (req, body) => …)
  *
- * `body` is a Standard Schema (zod, valibot, arktype — Bakery imports none of
+ * `body` is a Standard Schema (zod, valibot, arktype, Bakery imports none of
  * them) or a plain function returning the parsed value. A rejection answers
  * `400` through the framework's JSON envelope and the handler never runs.
  */
@@ -42,7 +41,7 @@ export function defineRoute(
   a: RouteHandler<any> | { body: Validator<any> },
   b?: RouteHandler<any>,
 ): RouteHandler<any> {
-  // One argument: identity, unchanged. Types only, no runtime cost — every
+  // One argument: identity, unchanged. Types only, no runtime cost: every
   // existing route keeps working byte for byte.
   if (typeof a === 'function') return a
 

package/src/core/index.ts

@@ -4,11 +4,11 @@ import { Case, is, Math2, match, Try } from '../utils/common'
 import { encodeSSE, response, sse } from '../utils/http'
 import Bakery, { getHostname, hostKey, hostStore } from './bakery'
 import { getConfig, NOOP } from './config'
-// `./context` is already in this barrel's graph — line 5 reaches it through
-// `./bakery`, which re-exports `hostStore` from exactly here — so naming it
+// `./context` is already in this barrel's graph: line 5 reaches it through
+// `./bakery`, which re-exports `hostStore` from exactly here, so naming it
 // adds no module edge, only a name.
-import { getFrameworkVersion } from './context'
-import { createElement, Fragment, html } from './jsx'
+import { getFrameworkVersion, getRequest } from './context'
+import { createElement, Fragment, html, raw } from './jsx'
 
 export const defineConfig = <T extends AppConfig>(config: T): T => config
 export const definePlugin = _definePlugin
@@ -43,7 +43,7 @@ export type {
  *
  *   export default defineRoute<{ id: string }>((req, body) => …)
  *
- * `defineRoute`, not `defineHandler` — "handler" already means a registered
+ * `defineRoute`, not `defineHandler`. "handler" already means a registered
  * `Handler` subclass in this framework, and this defines a route module.
  */
 export { defineRoute } from './define-route'
@@ -57,8 +57,8 @@ export { defineRoute } from './define-route'
  * into the module graph and reorders evaluation enough to close the cycle this
  * barrel is always one step away from: it typechecks, and then 47 tests fail
  * with `ReferenceError: Cannot access 'Logger' before initialization`. Going
- * through the `utils/http` index — which line 4 already imports for `response`
- * — adds no edge at all. Every other value here follows the same rule.
+ * through the `utils/http` index (which line 4 already imports for `response`
+ *) adds no edge at all. Every other value here follows the same rule.
  */
 export {
   Bakery,
@@ -67,11 +67,23 @@ export {
   encodeSSE,
   Fragment,
   getConfig,
+  /**
+   * Opt a string out of JSX escaping.
+   *
+   * Here because it had nowhere else to be. `createElement` escapes children
+   * unless they came from itself, so `raw` is the documented way to
+   * interpolate markup an application already trusts, and it was reachable
+   * only through a `./jsx` subpath that existed to alias one file. The
+   * routing guide pointed at `@bakery-framework/core/core/jsx`, which the
+   * export map never named at all, so the documented import could not resolve
+   * for a consumer either way.
+   */
+  raw,
   /**
    * The version of `@bakery-framework/core` itself, read from its own manifest.
    *
    * **Not the app's version**, which is what `import.meta.env.BAKERY_VERSION`
-   * and `getAppVersion()` report — the compiler reads those from
+   * and `getAppVersion()` report: the compiler reads those from
    * `<cwd>/package.json`, so in an application they answer with the
    * application's number. The name is a long-standing misnomer and this is the
    * one that means what "Bakery version" sounds like it means.
@@ -80,6 +92,15 @@ export {
    * ask. The dashboard's footer showed a hardcoded `v3` for want of it.
    */
   getFrameworkVersion,
+  /**
+   * The request being served, from anywhere inside the request.
+   *
+   * Here rather than reachable only through `./core/context` because the
+   * whole point is that it needs no ambient declaration and no deep
+   * subpath to reach a file: a Vue `<script server>` block, a helper it
+   * calls, a `.tsx` page and an API route all import it the same way.
+   */
+  getRequest,
   // Multi-host helpers. Documented in docs/configuration/multi-host.md, and
   // the only reason `./core/bakery` had to be a subpath of its own.
   getHostname,

package/src/core/init.ts

@@ -27,46 +27,49 @@ const getArgValue = (name: string) => {
 const threadId = process.env.THREAD_ID ?? getArgValue('--thread-id') ?? '0'
 
 /**
- * An accessor pair, not a bare getter.
+ * The mode flags are **strings on `process.env`**: `'1'` for true, `''` for
+ * false. They were booleans behind an accessor pair until Bun 1.4.
  *
- * These are `process.env` properties, and a getter with no setter is readonly:
- * in strict-mode ESM an assignment to one throws
- * `TypeError: Attempted to assign to readonly property`. `threads.ts` assigns
- * `THREAD_ID = '0'` on the single-worker/clamped path (deliberately not
- * `THREAD_WORKER` — a cluster of one must keep full-size caches). When the
- * assignment was getter-only it was wrapped in `Try(...)`, so the throw was
- * swallowed and the flags never moved — `reusePort`, the per-worker cache
- * scaling and the startup banner all silently read the master's values. The
- * `Try(...)` was what made a dead code path look deliberate.
+ * **Bun 1.4.0 rejects accessor descriptors on `process.env` outright.**
+ * `Object.defineProperty(process.env, 'X', { get })` throws
+ * `ERR_INVALID_OBJECT_DEFINE_PROPERTY`. This block runs at import time in every
+ * entry, so the whole framework died on `import` under current Bun: a
+ * scaffolded app could not reach step 2 of its own quick start. Data
+ * descriptors are accepted and coerce anyway (`{ value: false }` reads back as
+ * `"false"`), so a boolean here is no longer expressible at all; and
+ * `import.meta.env === process.env` in Bun, so there is no second object to put
+ * one on.
+ *
+ * **`'1'` / `''`, never `'true'` / `'false'`.** Truthiness has to survive the
+ * coercion: `"false"` is a truthy string, so every `if (import.meta.env.DEV)`
+ * in the codebase would have inverted silently rather than failed. `''` also
+ * keeps the key *present*: `'PROD' in process.env` stays true, which is what
+ * separates "explicitly not production" from "never booted", a distinction
+ * `utils/http/authorize.ts` depends on to fail closed.
+ *
+ * Plain assignment, so `threads.ts` can still assign `THREAD_ID = '0'` on the
+ * single-worker/clamped path (deliberately not `THREAD_WORKER`: a cluster of
+ * one must keep full-size caches). That assignment is why these were an
+ * accessor *pair* rather than a bare getter: a getter with no setter is
+ * readonly, the assignment threw, and the throw was swallowed by a `Try(...)`
+ * that made a dead code path look deliberate.
  */
-const accessor = (initial: any) => {
-  let value = initial
-  return {
-    get: () => value,
-    set: (next: any) => {
-      value = next
-    },
-    enumerable: true,
-    configurable: true,
-  }
-}
+const flag = (on: boolean) => (on ? '1' : '')
 
-Object.defineProperties(process.env, {
-  DEV: accessor(isDev),
-  TEST: accessor(isTest),
-  PROD: accessor(!isDev && !hasDevWorkerArg),
-  WORKER: accessor(hasDevWorkerArg || isThreadWorker),
-  DEV_WORKER: accessor(hasDevWorkerArg),
-  THREAD_WORKER: accessor(isThreadWorker),
-  THREAD_ID: accessor(threadId),
-  MODE: accessor(mode),
-})
+process.env.DEV = flag(isDev)
+process.env.TEST = flag(isTest)
+process.env.PROD = flag(!isDev && !hasDevWorkerArg)
+process.env.WORKER = flag(hasDevWorkerArg || isThreadWorker)
+process.env.DEV_WORKER = flag(hasDevWorkerArg)
+process.env.THREAD_WORKER = flag(isThreadWorker)
+process.env.THREAD_ID = threadId
+process.env.MODE = mode
 
 /**
  * "This process is the worker of a *development* server."
  *
- * `DEV_WORKER` alone would answer the same — `isDev` above is
- * `--dev || --dev-worker`, so a dev worker always carries `DEV` too — but the
+ * `DEV_WORKER` alone would answer the same (`isDev` above is
+ * `--dev || --dev-worker`, so a dev worker always carries `DEV` too), but the
  * conjunction is the condition the call sites were written against, and it
  * says what it means. Exported from here rather than recomputed per module
  * because three of them branch on it (`cli/worker.ts`,
@@ -86,8 +89,8 @@ Object.assign(globalThis, {
   Fragment,
   html,
   // The same value the browser runtime binds (`client/utils.ts`), so code
-  // that moves between an SFC's browser script and its server block — where
-  // it runs as a bare global either way — does not lose the name. Declared
+  // that moves between an SFC's browser script and its server block (where
+  // it runs as a bare global either way) does not lose the name. Declared
   // once, in `shared.d.ts`.
   randomId,
 })

package/src/core/jsx.ts

@@ -114,9 +114,9 @@ type RenderFn<P = {}> = (
 ) => string | Promise<string> | Promise<Response> | Response
 
 /**
- * `<P>` is type-level only — declare the route's params once and `body` is
+ * `<P>` is type-level only. Declare the route's params once and `body` is
  * typed inside the render function: `html<{ id: string }>((req, body) => …)`.
- * `RouteBody<{}>` is `MapOf<any>`, so an unparameterised call is unchanged.
+ * `RouteBody<{}>` is `MapOf<any>`, so an unparameterized call is unchanged.
  */
 export function html<P = {}>(render: RenderFn<P>) {
   return async (req: Request, body: RouteBody<P>) => {
@@ -127,9 +127,24 @@ export function html<P = {}>(render: RenderFn<P>) {
       return rawDom
     }
 
-    if (rawDom.trim().toLowerCase().startsWith('<html'))
+    // Both questions are about the first nine characters, so only the first
+    // nine are trimmed and lowercased. The form this replaces built two whole
+    // trimmed, lowercased copies of the document to answer them: on a 124 KB
+    // page that was 159 us per render against 0.17 us here, a 920x difference
+    // on a path every server-rendered page goes through. Measured interleaved
+    // with a CPU-bound control that stayed flat at 29-34 ms, and the two forms
+    // agree on 18 hand-picked shapes and 200,000 fuzzed strings.
+    //
+    // The search scans the leading whitespace and stops, so the cost is the
+    // indentation rather than the document. `<!doctype` is the longer of the
+    // two prefixes at nine characters, which is the whole window needed.
+    const startsAt = rawDom.search(/\S/)
+    const prefix =
+      startsAt < 0 ? '' : rawDom.slice(startsAt, startsAt + 9).toLowerCase()
+
+    if (prefix.startsWith('<html'))
       return `<!DOCTYPE html>\n${rawDom}`
-    if (rawDom.trim().toLowerCase().startsWith('<!doctype')) return rawDom
+    if (prefix.startsWith('<!doctype')) return rawDom
 
     let title = 'Document'
     const dom = rawDom.replace(/<title>(.*?)<\/title>/i, (_, t) => {

package/src/core/paths.ts

@@ -16,7 +16,9 @@ import { FileSystem as fs } from '../utils/fs'
  * Use `frameworkPath()` for files the framework ships. Use `Bakery.root` (cwd)
  * for anything the application owns.
  */
-export const frameworkRoot: string = fs.resolve(import.meta.dir, '..')
+/** File-local: `core/paths.ts` is not a published subpath and nothing
+ * outside this file read it. `frameworkPath()` below is the way in. */
+const frameworkRoot: string = fs.resolve(import.meta.dir, '..')
 
 /** Resolve a path against the framework's own root. */
 export function frameworkPath(...segments: string[]): string {

package/src/core/plugins.ts

@@ -27,7 +27,8 @@ async function normalizePluginResult(result: Handler.Response) {
 export namespace PluginHooks {
   export async function setup() {
     for (const plugin of getPlugins()) {
-      const [err] = await Try.catch(() => plugin.setup?.(Bakery.config))
+      if (!plugin.setup) continue
+      const [err] = await Try.catch(() => plugin.setup!(Bakery.config))
       if (err) {
         serveLog.UNHANDLED_ERR({
           error: `Plugin setup error (${plugin.name}): ${errorMsg(err)}`,
@@ -38,7 +39,15 @@ export namespace PluginHooks {
 
   export async function onRequest(req: Request) {
     for (const plugin of getPlugins()) {
-      const [err, result] = await Try.catch(plugin.onRequest?.(req))
+      // Skipped rather than awaited. `Try.catch` of an absent hook still
+      // allocates a promise and costs a microtask turn, and this loop runs on
+      // every request against every registered plugin - most of which declare
+      // no `onRequest` at all. Measured with four plugins and none declaring
+      // one, 1.33 us per request against 0.24 us; with one declaring it,
+      // 1.23 us against 0.60 us. Small, and `onError` below already reads
+      // this way, so the loops now share one idiom instead of three.
+      if (!plugin.onRequest) continue
+      const [err, result] = await Try.catch(plugin.onRequest(req))
       if (err) {
         serveLog.UNHANDLED_ERR({
           error: `Plugin request error (${plugin.name}): ${errorMsg(err)}`,
@@ -57,7 +66,8 @@ export namespace PluginHooks {
 
   export async function onRoute(req: Request) {
     for (const plugin of getPlugins()) {
-      const [err] = await Try.catch(() => plugin.onRoute?.(req))
+      if (!plugin.onRoute) continue
+      const [err] = await Try.catch(() => plugin.onRoute!(req))
 
       if (err) {
         pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })
@@ -67,7 +77,8 @@ export namespace PluginHooks {
 
   export async function onStart(server: any) {
     for (const plugin of getPlugins()) {
-      const [err] = await Try.catch(() => plugin.onStart?.(server))
+      if (!plugin.onStart) continue
+      const [err] = await Try.catch(() => plugin.onStart!(server))
 
       if (err) {
         pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })

package/src/core/port.ts

@@ -10,7 +10,7 @@
  *
  * They drifted on two axes. `parseInt` (startup, dev-service) reads `3000x` as
  * `3000`; `Number` (worker) reads it as `NaN`, and `Bun.serve({port: NaN})`
- * quietly binds an **ephemeral** port — so `PORT=3000x` printed
+ * quietly binds an **ephemeral** port, so `PORT=3000x` printed
  * `http://localhost:3000/` while the server was listening on 51570. And the
  * final fallbacks differed (`Bakery.server?.port || 0` against a literal
  * `3000`), so the two survivors of a bad parse disagreed again.
@@ -24,7 +24,7 @@
  * the variable and its value while the operator is still looking at the
  * terminal.
  *
- * `0` is deliberately *not* an error — it is the documented "let the OS pick
+ * `0` is deliberately *not* an error: it is the documented "let the OS pick
  * one" port, and `startup.ts` prefers `Bakery.server.port` precisely so the
  * banner prints the port that was picked rather than the `0` that was asked
  * for.
@@ -76,7 +76,7 @@ export function resolvePort(configPort?: number | null): number {
  * `--port 8080`, `--port=8080`, `-p 8080`, `-p=8080`.
  *
  * Returns the raw string so the caller can validate it through the one rule
- * above rather than a second one — a flag that accepted `0x1f` where `PORT`
+ * above rather than a second one: a flag that accepted `0x1f` where `PORT`
  * rejects it would be exactly the drift this module exists to end.
  */
 function portFlagValue(argv: string[]): string | null {
@@ -95,10 +95,10 @@ function portFlagValue(argv: string[]): string | null {
  * **Why the env rather than a parameter.** The port is read in three places
  * (see the note at the top of this file) across up to three *processes*: the
  * dev master, the dev worker it spawns, and N cluster workers. The spawn sites
- * pass `env: {...process.env}` and build their argv explicitly — `dev-service`
- * forwards `--dev`, `--dev-worker` and `--sync`, and nothing else — so a flag
+ * pass `env: {...process.env}` and build their argv explicitly (`dev-service`
+ * forwards `--dev`, `--dev-worker` and `--sync`, and nothing else), so a flag
  * would have to be threaded through each of them and kept in step forever,
- * while an environment variable already propagates to all of them. Normalising
+ * while an environment variable already propagates to all of them. Normalizing
  * once, in the entry, means every existing reader is already correct.
  *
  * **Precedence: flag beats `PORT` beats config.** That is what `--port` means

package/src/global.d.ts

@@ -21,7 +21,7 @@ declare global {
   // runtime resolves those names in global scope.
   //
   // `var req: Request` and `var body: any` used to live here too. Nothing ever
-  // assigned them — not init.ts, not client/utils.ts, nothing — so
+  // assigned them, not init.ts, not client/utils.ts, nothing, so
   // `req.headers.get('host')` typechecked anywhere in the codebase and threw
   // `ReferenceError: req is not defined` when it ran. A global that only
   // exists in the type system is worse than no global at all.
@@ -29,7 +29,7 @@ declare global {
   var Fragment: typeof import('./core/jsx').Fragment
   var html: typeof import('./core/jsx').html
 
-  // JsonResponse and ISFunction are declared once, in shared.d.ts — the
+  // JsonResponse and ISFunction are declared once, in shared.d.ts: the
   // browser runtime needs them too. MapOf, Wrapped and MixedPromise are not
   // global at all any more; they are imported from ./types above.
   //
@@ -46,8 +46,8 @@ declare global {
 
   /**
    * What a middleware may return to stop the chain: a `Response`, or a
-   * `response.json.*` envelope. Anything else — including a bare object or a
-   * string — is ignored and the next middleware runs. See `$middleware.ts`.
+   * `response.json.*` envelope. Anything else (including a bare object or a
+   * string) is ignored and the next middleware runs. See `$middleware.ts`.
    */
   type MiddlewareResponse =
     | Response
@@ -64,7 +64,7 @@ declare global {
     onError?(error: Handler.Error.Data): MixedPromise<any>
     /**
      * Cross-origin resource sharing. Absent means no CORS headers at all,
-     * which is the browser default and the safe one — there is deliberately no
+     * which is the browser default and the safe one: there is deliberately no
      * permissive default, not even in development.
      */
     cors?: import('./utils/http/cors').CorsOptions | null
@@ -96,7 +96,7 @@ declare global {
 
     /**
      * Cross-origin resource sharing. Absent means no CORS headers at all,
-     * which is the browser default and the safe one — there is deliberately no
+     * which is the browser default and the safe one: there is deliberately no
      * permissive default, not even in development.
      */
     cors?: import('./utils/http/cors').CorsOptions | null
@@ -125,7 +125,7 @@ declare global {
 
     // `maxCacheSize?: number` was declared and defaulted to 500 here, and read
     // by nothing: the route LRUs size themselves and the tiered cache takes its
-    // own options. Deleted rather than wired up — there is no single cache it
+    // own options. Deleted rather than wired up: there is no single cache it
     // plausibly governs, and a knob that silently does nothing is worse than an
     // absent one. Removing it before the first publish is a docs note; after,
     // it is a breaking change.
@@ -143,14 +143,14 @@ declare global {
     trustProxy?: boolean
 
     /**
-     * Where the ORM finds the app's schema — a file, or a folder containing
+     * Where the ORM finds the app's schema: a file, or a folder containing
      * `index.ts`. Relative paths resolve against the app's cwd. Omit it (or
      * leave it empty) to auto-detect `orm/` then `schema.ts`.
      *
      * A plain string, deliberately: core must never depend on `@bakery-framework/orm`,
      * which depends on core, and a path carries no type from it. The ORM reads
      * this through `schemaFromConfig`. A configured path that does not exist is
-     * a hard error rather than a fall back to auto-detect — otherwise a typo
+     * a hard error rather than a fall back to auto-detect: otherwise a typo
      * makes the sync engine generate a fresh schema at the wrong path while the
      * real one sits untouched.
      */
@@ -339,19 +339,37 @@ declare global {
 
   // Defined as getters on process.env by core/init.ts, and substituted into
   // browser bundles by the compiler's `defines`. The client used to redeclare
-  // `ImportMeta.env` with its own incompatible shape, which is TS2687/TS2717 —
+  // `ImportMeta.env` with its own incompatible shape, which is TS2687/TS2717:
   // suppressed, like everything else in a .d.ts, by skipLibCheck.
   interface ImportMetaEnv {
-    readonly DEV: boolean
-    readonly PROD: boolean
-    readonly WORKER: boolean
-    readonly DEV_WORKER: boolean
-    readonly THREAD_WORKER: boolean
+    // `'1'` or `''`, not `true` or `false`. These live on `process.env`, and
+    // Bun 1.4 stopped accepting accessor descriptors there: a boolean is no
+    // longer expressible on that object at all, since data descriptors coerce
+    // too. See the encoding block in `core/init.ts`.
+    //
+    // Typed as the literal pair rather than `string` on purpose: it makes
+    // `import.meta.env.PROD !== false` a *compile* error. That comparison was
+    // real, in the dashboard's fail-closed gate, and under the string encoding
+    // it is true for every value including the `''` a development server sets,
+    // so the gate would have denied on loopback in development while still
+    // reading as correct. A type that only said `string` would not have caught
+    // it either.
+    //
+    // In a **browser** bundle these are real booleans: `compiler.ts` substitutes
+    // `JSON.stringify(!!import.meta.env.DEV)` at build time, so the literal
+    // `true`/`false` is inlined and this declaration is a slight lie there. It
+    // is the harmless direction (both encodings agree on truthiness, which is
+    // all client code tests), and the server is where the mistakes happen.
+    readonly DEV: '1' | ''
+    readonly PROD: '1' | ''
+    readonly WORKER: '1' | ''
+    readonly DEV_WORKER: '1' | ''
+    readonly THREAD_WORKER: '1' | ''
     readonly THREAD_ID: string
-    readonly TEST: boolean
+    readonly TEST: '1' | ''
     readonly MODE: 'production' | 'development' | 'dev-worker' | 'thread-worker'
-    // `readonly SERVE_ROOT: string` was declared here. Nothing defines it —
-    // not init.ts, not the compiler's `defines` — and nothing reads it, so any
+    // `readonly SERVE_ROOT: string` was declared here. Nothing defines it,
+    // not init.ts, not the compiler's `defines`, and nothing reads it, so any
     // code that trusted the declaration would have got `undefined` typed as
     // `string`. The resolved root is `Bakery.serveRoot`; use that.
     /** Compiler define; the only one the browser bundle reads. */

package/src/handlers/assets/google-font.ts

@@ -9,8 +9,8 @@ import { Handler } from '../core/$base'
  * The Google Fonts CSS endpoints this proxy is willing to forward to.
  *
  * `css` is the v1 API, `css2` the current one, `icon` the Material icon
- * stylesheet. Everything else on `fonts.googleapis.com` — and anything at all
- * once the path is attacker-supplied — is refused, because this handler is an
+ * stylesheet. Everything else on `fonts.googleapis.com` (and anything at all
+ * once the path is attacker-supplied) is refused, because this handler is an
  * unauthenticated outbound fetch from the server's own IP and the path used to
  * be forwarded verbatim.
  */
@@ -22,7 +22,7 @@ const GF_CSS_PATHS = new Set(['css', 'css2', 'icon'])
  * Google answers `200` for a request carrying parameters it does not know, so
  * before this list every `?family=Roboto&junk=<n>` was a fresh cache key *and*
  * a fresh outbound request: six junk requests were measured producing six keys
- * and eighteen files. Names are compared raw, without percent-decoding — a
+ * and eighteen files. Names are compared raw, without percent-decoding: a
  * name spelled `%66amily` simply fails the list, which is the safe direction.
  */
 const GF_CSS_PARAMS = new Set([
@@ -39,7 +39,7 @@ const GF_MAX_QUERY = 512
 const GF_MAX_GSTATIC_PATH = 256
 
 /**
- * A path under `fonts.gstatic.com`, as the rewritten CSS references it —
+ * A path under `fonts.gstatic.com`, as the rewritten CSS references it:
  * `s/roboto/v47/KFOmCnqEu92Fr1Mu4mxK.woff2`.
  *
  * Every segment must start with an alphanumeric, which is what rules out `..`
@@ -54,7 +54,7 @@ const GF_GSTATIC_PATH =
  *
  * `getOrCreateCachedFile` writes three files per entry (raw, `.zst`, `.gz`)
  * and nothing ever removed them, so the cache directory grew with the number
- * of distinct request URLs — which is to say, without bound. The allow-lists
+ * of distinct request URLs, which is to say, without bound. The allow-lists
  * above shrink the key space but do not close it: a family *name* is still
  * free text, and a wrong one costs a 400 from Google rather than a rejection
  * here. This is the bound, in the shape convention 6 asks for.
@@ -86,7 +86,7 @@ function trackCacheEntry(cacheDir: string, cacheName: string): void {
  * Test seams for the bound, in the `__`-prefixed style of `__setTestConfig`.
  *
  * Every other branch of this handler is reachable from a test through
- * `handle()` — the allow-lists refuse before anything is fetched. The eviction
+ * `handle()`: the allow-lists refuse before anything is fetched. The eviction
  * path is not: reaching it legitimately means 257 successful round trips to
  * Google, which is not a unit test. These let one assert the bound holds and
  * that an evicted entry takes its `.zst`/`.gz` companions with it.