@bakery-framework/core 1.0.0

package/src/core/context.ts

@@ -0,0 +1,121 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { matchBlocked } from '../utils/constants'
+import { fs } from '../utils/fs'
+
+export type HostContext = {
+  config: Readonly<ProcessedAppConfig>
+  hostname: string
+  /**
+   * Per-request memo of raw `.forbidden` marker probes, keyed by the marker
+   * path (`<dir>/.forbidden`). Lazily created by `fs.isForbidden` and never
+   * read anywhere else. Scoped to one request by construction: every
+   * `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
+   * 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
+   * 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
+   * by path alone because both call sites pass the ambient host config's
+   * globs, which are frozen for the life of the store.
+   */
+  blockedPaths?: Map<string, boolean>
+}
+
+export const hostStore = new AsyncLocalStorage<HostContext>()
+
+/**
+ * `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
+ * skipped. See `HostContext.blockedPaths` for the scoping argument.
+ */
+export function matchBlockedCached(
+  blocked: { match(path: string): boolean } | undefined,
+  path: string,
+): boolean {
+  const store = hostStore.getStore()
+  const seen = store ? (store.blockedPaths ??= new Map()) : null
+
+  let verdict = seen?.get(path)
+  if (verdict === undefined) {
+    verdict = matchBlocked(blocked, path)
+    seen?.set(path, verdict)
+  }
+  return verdict
+}
+
+/**
+ * The **application's** version, from `<cwd>/package.json`.
+ *
+ * Named `getBakeryVersion` until 2026-08-09, which is exactly the wrong name:
+ * it reads the package.json of whatever is being served, not the framework's.
+ * That misnomer hid a real bug for as long as it existed — see
+ * {@link getFrameworkVersion}.
+ */
+/**
+ * What each version reader returns when it cannot read its manifest.
+ *
+ * They must be **distinct from each other and impossible as a real version**,
+ * 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
+ * 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.
+ *
+ * A prerelease suffix keeps them valid semver while making the collision
+ * unrepeatable: no published version can equal these.
+ */
+const UNKNOWN_APP = '0.0.0-unknown-app'
+const UNKNOWN_FW = '0.0.0-unknown-framework'
+
+let _appVersion: string | null = null
+export function getAppVersion() {
+  if (_appVersion) return _appVersion
+  try {
+    const content = fs.readFileSync(fs.resolve(fs.cwd, 'package.json'))
+    if (content) _appVersion = JSON.parse(content).version || UNKNOWN_APP
+  } catch {
+    // Missing or malformed package.json. The version is cosmetic and the
+    // fallback below is the answer either way.
+  }
+  return _appVersion || UNKNOWN_APP
+}
+
+/**
+ * The **framework's** version, from `@bakery-framework/core`'s own package.json.
+ *
+ * Resolved from this module's location rather than by package specifier: a
+ * package self-referencing by name works only via the `exports` field and is
+ * one config edit away from breaking, while `../../package.json` is the same
+ * relative path in the repo and in the published tarball (`files` keeps both
+ * `src/` and the manifest).
+ *
+ * This exists because `.cache/` invalidation was keyed on the *app's* version
+ * alone, so upgrading `@bakery-framework/*` left a cache compiled by the previous
+ * framework version in place. In-repo that was invisible: `apps/example`'s
+ * version tracks the framework's, so bumping both wiped it anyway.
+ */
+let _frameworkVersion: string | null = null
+export function getFrameworkVersion() {
+  if (_frameworkVersion) return _frameworkVersion
+  try {
+    const content = fs.readFileSync(
+      fs.resolve(import.meta.dir, '../../package.json'),
+    )
+    if (content) _frameworkVersion = JSON.parse(content).version || UNKNOWN_FW
+  } catch {
+    // Same reasoning as above, with one addition: a fallback that never
+    // changes would silently stop invalidating the cache, so it is a distinct
+    // value from the app fallback.
+  }
+  return _frameworkVersion || UNKNOWN_FW
+}

package/src/core/index.ts

@@ -0,0 +1,61 @@
+import { Logger, log } from '../logger'
+import { definePlugin as _definePlugin } from '../plugins/types'
+import type { RouteHandler } from '../types'
+import { Case, is, Math2, match, Try } from '../utils/common'
+import { response } from '../utils/http'
+import Bakery, { getHostname, hostKey, hostStore } from './bakery'
+import { getConfig, NOOP } from './config'
+import { createElement, Fragment, html } from './jsx'
+
+export const defineConfig = <T extends AppConfig>(config: T): T => config
+export const definePlugin = _definePlugin
+
+/**
+ * Identity at runtime, like `defineConfig`; exists so a route module can
+ * declare its body shape once and have the whole signature inferred:
+ *
+ *   export default defineRoute<{ id: string }>((req, body) => …)
+ *
+ * `defineRoute`, not `defineHandler` — "handler" already means a registered
+ * `Handler` subclass in this framework, and this defines a route module.
+ */
+export const defineRoute = <P = {}>(fn: RouteHandler<P>): RouteHandler<P> => fn
+
+/**
+ * Helper types, previously ambient globals. Importable so an app that declares
+ * its own `MapOf` is not met with a redeclaration error it cannot opt out of.
+ * The Route* types are the app-facing typing surface for route modules.
+ */
+export type {
+  MapOf,
+  MixedPromise,
+  RouteBody,
+  RouteHandler,
+  RouteResponse,
+  Wrapped,
+} from '../types'
+
+export {
+  Bakery,
+  Case,
+  createElement,
+  Fragment,
+  getConfig,
+  // 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,
+  hostKey,
+  hostStore,
+  html,
+  html as HTMLBody,
+  is,
+  Logger,
+  log,
+  Math2,
+  match,
+  NOOP,
+  response,
+  Try,
+}
+
+export default Bakery

package/src/core/init.ts

@@ -0,0 +1,90 @@
+import { createElement, Fragment, html } from './jsx'
+
+const hasDevWorkerArg = process.argv.includes('--dev-worker')
+const isThreadWorker =
+  process.argv.includes('--thread-worker') || process.env.THREAD_WORKER === '1'
+const isDev = process.argv.includes('--dev') || hasDevWorkerArg
+const isTest = process.env.NODE_ENV === 'test' || Bun.env.NODE_ENV === 'test'
+const mode = hasDevWorkerArg
+  ? 'dev-worker'
+  : isThreadWorker
+    ? 'thread-worker'
+    : isDev
+      ? 'development'
+      : 'production'
+
+const getArgValue = (name: string) => {
+  const prefix = `${name}=`
+  const found = process.argv.find(a => a.startsWith(prefix))
+  if (found) return found.slice(prefix.length)
+  const idx = process.argv.indexOf(name)
+  return idx !== -1 && idx + 1 < process.argv.length
+    ? process.argv[idx + 1]
+    : null
+}
+
+const threadId = process.env.THREAD_ID ?? getArgValue('--thread-id') ?? '0'
+
+/**
+ * An accessor pair, not a bare getter.
+ *
+ * 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.
+ */
+const accessor = (initial: any) => {
+  let value = initial
+  return {
+    get: () => value,
+    set: (next: any) => {
+      value = next
+    },
+    enumerable: true,
+    configurable: true,
+  }
+}
+
+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),
+})
+
+/**
+ * "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
+ * 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`,
+ * `compiler/dev-service.ts`, the dashboard plugin's `setup.ts`) and a
+ * byte-identical expression in three files is three chances to drift.
+ *
+ * Read once, at the moment the accessors above are installed: the flags do not
+ * move afterwards, so this is the same value each copy computed at its own
+ * load time.
+ */
+export const isDevWorker = Boolean(
+  import.meta.env.DEV_WORKER && import.meta.env.DEV,
+)
+
+Object.assign(globalThis, {
+  createElement,
+  Fragment,
+  html,
+})
+
+process.on('SIGHUP', () => {})
+process.on('SIGBREAK', () => {})

package/src/core/jsx.ts

@@ -0,0 +1,152 @@
+import type { MapOf, RouteBody } from '../types'
+import { is } from '../utils/common/misc'
+import { Bakery } from './bakery'
+
+type Server = Bun.Server<any>
+
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+])
+
+export const Fragment = ({ children }: { children?: any }) =>
+  raw(renderChildren([children]))
+
+/**
+ * Markup that is already HTML and must not be escaped again.
+ *
+ * A String subclass rather than a plain string, because `createElement`
+ * composes by returning strings: without a marker there is no way to tell
+ * "HTML produced by a child component" from "text a user typed". It behaves
+ * like a string everywhere (`.trim()`, concatenation, `String()`), so callers
+ * are unaffected.
+ */
+export class SafeHtml extends String {}
+
+/** Mark a string as trusted HTML, exempting it from escaping. */
+export function raw(value: unknown): string {
+  return new SafeHtml(value ?? '') as unknown as string
+}
+
+/** True for markup this module produced, or that a caller vouched for. */
+export function isSafeHtml(value: unknown): boolean {
+  return value instanceof SafeHtml
+}
+
+const TEXT_ESCAPES: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+}
+
+function escapeText(value: unknown): string {
+  return String(value).replace(/[&<>"']/g, ch => TEXT_ESCAPES[ch] || ch)
+}
+
+/**
+ * Children are escaped unless they are SafeHtml. Nested `createElement` calls
+ * return SafeHtml, so composition still works; a bare string interpolated from
+ * data is treated as text, which is the safe default.
+ */
+function renderChildren(children: any[]): string {
+  return children
+    .flat(10)
+    .map(c => {
+      if (c === null || c === undefined || is.boolean(c)) return ''
+      return isSafeHtml(c) ? String(c) : escapeText(c)
+    })
+    .join('')
+}
+
+export const createElement = (
+  tag: any,
+  props: MapOf<any> | null,
+  ...children: any[]
+): string => {
+  if (is.function(tag)) return tag({ ...props, children })
+
+  const childStr = renderChildren(children)
+
+  let attrStr = ''
+  for (const [key, value] of Object.entries(props || {})) {
+    if (key === 'children') continue
+    if (value === false || value === null || value === undefined) continue
+
+    if (value === true) {
+      attrStr += ` ${key}`
+      continue
+    }
+
+    let attrKey = key
+
+    if (key === 'className') attrKey = 'class'
+    else if (key === 'htmlFor') attrKey = 'for'
+
+    const safeValue = escapeText(value)
+    attrStr += ` ${attrKey}="${safeValue}"`
+  }
+
+  const isVoid = VOID_ELEMENTS.has(tag)
+
+  return raw(
+    isVoid ? `<${tag}${attrStr}>` : `<${tag}${attrStr}>${childStr}</${tag}>`,
+  )
+}
+
+type RenderFn<P = {}> = (
+  req: Request,
+  body: RouteBody<P>,
+  server: Server,
+) => string | Promise<string> | Promise<Response> | Response
+
+/**
+ * `<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.
+ */
+export function html<P = {}>(render: RenderFn<P>) {
+  return async (req: Request, body: RouteBody<P>) => {
+    const rendered = await render(req, body, Bakery.server!)
+    const rawDom = rendered instanceof Response ? rendered : String(rendered)
+
+    if (rawDom instanceof Response) {
+      return rawDom
+    }
+
+    if (rawDom.trim().toLowerCase().startsWith('<html'))
+      return `<!DOCTYPE html>\n${rawDom}`
+    if (rawDom.trim().toLowerCase().startsWith('<!doctype')) return rawDom
+
+    let title = 'Document'
+    const dom = rawDom.replace(/<title>(.*?)<\/title>/i, (_, t) => {
+      title = t
+      return ''
+    })
+
+    return `
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <title>${title}</title>
+            </head>
+            <body>
+              ${dom}
+            </body>
+          </html>
+        `
+  }
+}

package/src/core/paths.ts

@@ -0,0 +1,24 @@
+import { FileSystem as fs } from '../utils/fs'
+
+/**
+ * Where the framework's own files live, as opposed to where the application
+ * lives.
+ *
+ * Two roots were previously conflated on `process.cwd()`: the app root (its
+ * `src/`, `public/`, `api/`, `schema.ts`) and the framework root (the client
+ * runtime it serves at `/_client/*`, the dashboard's assets, the tsconfig
+ * templates). Framework assets were addressed as `<cwd>/.server/...`, which
+ * only holds while the framework is a directory inside the app.
+ *
+ * Derived from this module's own location, so it keeps working once the
+ * framework is a workspace package or resolved out of `node_modules`.
+ *
+ * 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, '..')
+
+/** Resolve a path against the framework's own root. */
+export function frameworkPath(...segments: string[]): string {
+  return fs.resolve(frameworkRoot, ...segments)
+}

package/src/core/plugins.ts

@@ -0,0 +1,120 @@
+import type { Handler } from '../handlers'
+import { errorMsg, pluginLog, serveLog } from '../logger'
+import { Try } from '../utils'
+import { is } from '../utils/common'
+import { injectIfHtml, response } from '../utils/http'
+import { Bakery } from './bakery'
+
+function getPlugins() {
+  return Bakery.config.plugins
+}
+
+async function normalizePluginResult(result: Handler.Response) {
+  if (result instanceof Response) {
+    const injectedRes = await injectIfHtml(result)
+    return injectedRes || result
+  }
+
+  if (result !== undefined && result !== null) {
+    return is.object(result)
+      ? response.json(200, 'OK', result)
+      : response.text(String(result))
+  }
+
+  return null
+}
+
+export namespace PluginHooks {
+  export async function setup() {
+    for (const plugin of getPlugins()) {
+      const [err] = await Try.catch(() => plugin.setup?.(Bakery.config))
+      if (err) {
+        serveLog.UNHANDLED_ERR({
+          error: `Plugin setup error (${plugin.name}): ${errorMsg(err)}`,
+        })
+      }
+    }
+  }
+
+  export async function onRequest(req: Request) {
+    for (const plugin of getPlugins()) {
+      const [err, result] = await Try.catch(plugin.onRequest?.(req))
+      if (err) {
+        serveLog.UNHANDLED_ERR({
+          error: `Plugin request error (${plugin.name}): ${errorMsg(err)}`,
+        })
+        return response.json.error(
+          500,
+          'Internal Server Error',
+        ) as unknown as Response
+      }
+
+      const normalized = await normalizePluginResult(result)
+      if (normalized) return normalized
+    }
+    return null
+  }
+
+  export async function onRoute(req: Request) {
+    for (const plugin of getPlugins()) {
+      const [err] = await Try.catch(() => plugin.onRoute?.(req))
+
+      if (err) {
+        pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })
+      }
+    }
+  }
+
+  export async function onStart(server: any) {
+    for (const plugin of getPlugins()) {
+      const [err] = await Try.catch(() => plugin.onStart?.(server))
+
+      if (err) {
+        pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })
+      }
+    }
+  }
+
+  export async function onError(error: Handler.Error.Data, req?: Request) {
+    for (const plugin of getPlugins()) {
+      if (!plugin.onError) continue
+      const [err, result] = await Try.catch(() => plugin.onError!(error, req))
+
+      if (err) {
+        pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })
+        continue
+      }
+
+      const normalized = await normalizePluginResult(result)
+      if (normalized) return normalized
+    }
+    return null
+  }
+
+  export async function onShutdown() {
+    for (const plugin of getPlugins()) {
+      const [err] = await Try.catch(() => plugin.onShutdown?.())
+      if (err) {
+        pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })
+      }
+    }
+  }
+
+  export async function onCompile(
+    content: string,
+    path: string,
+  ): Promise<string> {
+    for (const plugin of getPlugins()) {
+      if (!plugin.onCompile) continue
+      const [err, res] = await Try.catch(() => plugin.onCompile!(content, path))
+      if (err) {
+        pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })
+        continue
+      }
+      if (typeof res === 'string') {
+        content = res
+      }
+    }
+    return content
+  }
+}

package/src/core/port.ts

@@ -0,0 +1,73 @@
+/**
+ * The one answer to "what port are we on".
+ *
+ * This was written three times, with three different rules, in three files that
+ * all have to agree or the framework lies to the developer:
+ *
+ * - `cli/worker.ts` decides the port `Bun.serve` actually binds.
+ * - `startup.ts` decides the port the startup banner prints.
+ * - `compiler/dev-service.ts` decides the URL the dev master advertises.
+ *
+ * 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
+ * `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.
+ *
+ * The rule here is `Number` plus an explicit range check, and a malformed
+ * `PORT` is an **error** rather than a guess. Convention 2 is about guards, but
+ * the same instinct applies: a value the operator plainly meant as a port and
+ * which is not one has no safe default. Silently binding 3000 hides a typo in a
+ * deploy script until something else is already on 3000; silently binding a
+ * random port hides it until a health check times out. Failing at boot names
+ * 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
+ * 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.
+ */
+
+/** Where `PORT` and a portless `server.config.ts` both land. */
+export const DEFAULT_PORT = 3000
+
+/** Highest port number a TCP socket can bind. */
+const MAX_PORT = 65535
+
+// 🚀 Hoisted Regex
+const RE_DECIMAL = /^\d+$/
+
+/**
+ * Resolve `PORT` → `configPort` → {@link DEFAULT_PORT}.
+ *
+ * An unset *or empty* `PORT` counts as absent: `PORT=` is how a shell and a
+ * process manager both spell "no value", and all three call sites already
+ * treated it that way.
+ *
+ * @throws if `PORT` is set to anything that is not an integer in `0..65535`.
+ */
+export function resolvePort(configPort?: number | null): number {
+  const raw = process.env.PORT
+
+  if (raw !== undefined && raw.trim() !== '') {
+    const trimmed = raw.trim()
+    // Decimal digits only, deliberately narrower than `Number`: `Number` also
+    // accepts `0x1f` (31), `1e3` (1000) and `+80`, none of which anyone types
+    // into a `PORT` on purpose, and all of which would resolve to a port the
+    // operator did not write down.
+    const parsed = RE_DECIMAL.test(trimmed) ? Number(trimmed) : Number.NaN
+    if (!Number.isInteger(parsed) || parsed < 0 || parsed > MAX_PORT) {
+      throw new Error(
+        `Invalid PORT: ${JSON.stringify(raw)} is not an integer between 0 and ${MAX_PORT}`,
+      )
+    }
+    return parsed
+  }
+
+  // `||`, not `??`: a config that says `port: 0` has always meant "unset" here
+  // rather than "ephemeral", and only `PORT=0` asks for an ephemeral port.
+  // Changing that is a separate decision from unifying the three call sites.
+  return configPort || DEFAULT_PORT
+}