@bakery-framework/core 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
   "keywords": [
     "bakery",

package/src/cache/shared-db.ts

@@ -7,19 +7,39 @@ import { fs } from '../utils'
 /**
  * The tiered cache's spill-to-disk store — sessions and LRU overflow.
  *
- * Under `Bakery.cacheDir`, not `dataDir`, because every row in it is
- * rebuildable: a session is a cookie plus whatever the app chose to hang off
- * it, and the LRU tier re-fills from source on the next miss. It used to sit
- * beside `server.db` in the data directory, which put a disposable file behind
- * the one durability guarantee the framework makes.
- *
- * **The consequence is that sessions do not survive a framework upgrade.**
- * `checkCacheVersion` wipes the whole cache directory on every version bump and
- * every dev<->prod switch, and this file goes with it — users are logged out.
- * That is intended: the alternative is a cache format from an older framework
- * version being read by a newer one, which is exactly the failure the version
- * wipe exists to prevent. Anything that must outlive an upgrade belongs in the
- * app's own tables under `Bakery.dataDir`.
+ * Under `Bakery.dataDir`, beside `server.db`. Rows here are *rebuildable* — a
+ * session is a cookie plus whatever the app hung off it, and the LRU tier
+ * refills from source on the next miss — but rebuildable is not the same as
+ * disposable-on-a-schedule, which is what living in `cacheDir` amounted to.
+ * See the reversal below.
+ *
+ * **Sessions used to be wiped on every framework upgrade. They are not now, and
+ * this paragraph is the reversal.**
+ *
+ * The file lived under `Bakery.cacheDir`, so `checkCacheVersion` deleted it on
+ * every version bump and every dev<->prod switch — logging every user out. The
+ * argument for that was sound: a cache format written by an older framework
+ * must never be read by a newer one, and the version wipe is what guarantees
+ * it.
+ *
+ * What changed is how often a version bumps. That reasoning was written when
+ * releases were cut by hand and rare; releases are now computed from commit
+ * messages and published automatically, so a patch ships whenever a `fix:`
+ * lands. Logging out every user of every app on every patch is a far worse
+ * trade than it was, and it was never the *goal* — only the consequence of
+ * keying durability on a version number that had nothing to do with the stored
+ * format.
+ *
+ * So the file moved to `Bakery.dataDir` and carries its own `SCHEMA_VERSION`.
+ * The safety property is unchanged and now keyed on the thing that governs it:
+ * a schema mismatch drops the tables, a framework bump does not.
+ *
+ * Two consequences worth knowing. An app with no ORM now creates a `bakery/`
+ * directory where it previously created none — it is storing durable data, so
+ * that is honest, but it means "no `bakery/` directory" is no longer evidence
+ * that `initDB` never ran. And the LRU spill tier shares this file, so overflow
+ * entries also survive; they are still rebuildable, just no longer discarded on
+ * a schedule nobody chose.
  *
  * **That was aspirational until 2026-08-09, and the `await` below is what makes
  * it true.** The check ran from `initConfig()`, while this module opens the
@@ -33,10 +53,45 @@ import { fs } from '../utils'
  */
 await checkCacheVersion()
 
-const dbFilePath = `${Bakery.cacheDir}/shared-cache.db`
+/**
+ * Bumped only when the *shape* of what is stored here changes.
+ *
+ * This is what replaced "wipe on every framework version". A schema change is
+ * rare and deliberate; a framework patch is neither, and tying the two together
+ * meant every patch logged out every user.
+ */
+const SCHEMA_VERSION = 1
+
+const dbFilePath = `${Bakery.dataDir}/sessions.db`
 if (!fs.exists(dbFilePath)) await fs.mkdir(dirname(dbFilePath))
 
 export const cacheDb = new Database(dbFilePath, { create: true })
+
+/**
+ * Drop everything if the stored schema version is not this one.
+ *
+ * The safety property the cache wipe provided — a newer framework never reads
+ * an older format — is preserved exactly, just keyed on the thing that actually
+ * governs compatibility. A mismatch logs users out, which is the same outcome
+ * as before; the difference is that it now happens when the format changes
+ * rather than when any version number does.
+ */
+cacheDb.run('CREATE TABLE IF NOT EXISTS __schema (version INTEGER NOT NULL)')
+const stored = cacheDb
+  .query<{ version: number }, []>('SELECT version FROM __schema LIMIT 1')
+  .get()
+
+if (!stored) {
+  cacheDb.run('INSERT INTO __schema (version) VALUES (?)', [SCHEMA_VERSION])
+} else if (stored.version !== SCHEMA_VERSION) {
+  const tables = cacheDb
+    .query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name != '__schema'",
+    )
+    .all()
+  for (const { name } of tables) cacheDb.run(`DROP TABLE IF EXISTS "${name}"`)
+  cacheDb.run('UPDATE __schema SET version = ?', [SCHEMA_VERSION])
+}
 const journalMode = process.platform === 'win32' ? 'DELETE' : 'WAL'
 cacheDb.run(`PRAGMA journal_mode = ${journalMode};`)
 cacheDb.run('PRAGMA synchronous = NORMAL;')

package/src/compiler/tsconfig-sync.ts

@@ -1,5 +1,6 @@
 import { Bakery } from '../core/bakery'
 import { errorMsg, serveLog } from '../logger'
+import type { PluginTsProject } from '../plugins/types'
 import type { MapOf } from '../types'
 import { fs } from '../utils/fs'
 import { parseJSONC } from '../utils/jsonc'
@@ -10,6 +11,9 @@ const RE_HTTP = /^https?:\/\//
 const RE_LEADING_SLASHES = /^(\.\/|\/)/
 const RE_RELATIVE = /^\.\.?\//
 const RE_TRAILING_WILDCARD = /\/?\*?$/
+// Drive letters included: `Bakery.config.root` is absolute, and on Windows
+// that is `C:/…` rather than a leading slash.
+const RE_ABSOLUTE = /^([A-Za-z]:)?[\\/]/
 
 // The application's tsconfig, resolved against its cwd. This used to write into
 // a tsconfig *inside the framework* — app-specific paths mutating a shipped
@@ -45,6 +49,263 @@ function buildPaths(): MapOf<string[]> {
   return newPaths
 }
 
+/** Where the generated projects go, and where the root config points. */
+const PROJECT_DIR = fs.resolve(APP_DIR, '.cache/tsconfig')
+
+/**
+ * The two projects core always generates.
+ *
+ * The split is the whole point: only `server` carries `bun-types`, so `Bun.*`
+ * in a file bound for the browser is a type error rather than a runtime one.
+ * Before this existed, one config covered everything and `Bun.hash()` in a
+ * client file typechecked clean and failed in the browser.
+ *
+ * Globs are app-relative here and rewritten to be relative to the generated
+ * file, which sits two levels down.
+ */
+export function coreProjects(): PluginTsProject[] {
+  const root = Bakery.config.root ?? 'src'
+
+  return [
+    {
+      name: 'server',
+      extends: '@bakery-framework/core/tsconfig.server.json',
+      // Repeated rather than inherited: Bun's runtime does not follow
+      // `extends` into a package specifier, only a relative path.
+      compilerOptions: {
+        jsx: 'react',
+        jsxFactory: 'createElement',
+        jsxFragmentFactory: 'Fragment',
+      },
+      include: [
+        `${root}/**/api/**/*.ts`,
+        `${root}/**/*.tsx`,
+        'server.config.ts',
+        'schema.ts',
+        'orm/**/*.ts',
+      ],
+    },
+    {
+      name: 'client',
+      extends: '@bakery-framework/core/tsconfig.app.json',
+      include: [`${root}/**/*.ts`],
+      exclude: [`${root}/**/api/**/*.ts`],
+      // The only project that gets `importMap` aliases, because the import map
+      // is a browser mechanism — see `importMapPaths` on `PluginTsProject`.
+      importMapPaths: true,
+    },
+  ]
+}
+
+/**
+ * Turn an app-relative glob into one relative to `.cache/tsconfig/`.
+ *
+ * Two levels up, and always with a leading `../` so TypeScript reads it as a
+ * path rather than resolving it against the project directory.
+ */
+export function fromProjectDir(pathOrGlob: string): string {
+  // **`Bakery.config.root` is absolute**, so globs built from it arrive here as
+  // full paths. Prefixing `../../` to one yields
+  // `../../C:/WebDAV/.../src/**/*.ts`, which matches nothing — and a project
+  // that matches nothing typechecks clean, so the mistake presents as success.
+  // That is exactly how the first version of this passed with zero files.
+  if (RE_ABSOLUTE.test(pathOrGlob)) {
+    const rel = fs.relative(PROJECT_DIR, pathOrGlob).replace(/\\/g, '/')
+    return RE_RELATIVE.test(rel) ? rel : `./${rel}`
+  }
+  return `../../${pathOrGlob.replace(RE_LEADING_SLASHES, '')}`
+}
+
+/**
+ * Resolve a `files` entry to something TypeScript will actually load.
+ *
+ * A package specifier is the useful form for a plugin to write — it does not
+ * know where it was installed — but `files` is resolved as a path, so
+ * `@scope/pkg/x.d.ts` would simply be missing. Resolution failure is not fatal:
+ * a plugin whose declaration cannot be found should degrade to "no types" and
+ * say so, not stop the dev server from booting.
+ */
+function resolveFilesEntry(entry: string): string | null {
+  if (entry.startsWith('.') || entry.startsWith('/')) {
+    return fromProjectDir(entry)
+  }
+  try {
+    const abs = Bun.resolveSync(entry, APP_DIR)
+    const rel = fs.relative(PROJECT_DIR, abs).replace(/\\/g, '/')
+    return RE_RELATIVE.test(rel) ? rel : `./${rel}`
+  } catch {
+    return null
+  }
+}
+
+/** Every project: core's two, plus whatever the loaded plugins contribute. */
+function allProjects(): PluginTsProject[] {
+  const projects = coreProjects()
+  const seen = new Set(projects.map(p => p.name))
+
+  for (const plugin of Bakery.config.plugins ?? []) {
+    const project = plugin?.tsconfig?.project
+    if (!project) continue
+
+    // A plugin cannot silently replace `server` or `client`, or another
+    // plugin's project. Skipping with a log beats a collision that presents as
+    // "my types stopped working" three plugins later.
+    if (seen.has(project.name)) {
+      serveLog.TSCONFIG_PROJECT_CLASH({
+        plugin: plugin.name,
+        project: project.name,
+      })
+      continue
+    }
+
+    seen.add(project.name)
+    projects.push(project)
+  }
+
+  return projects
+}
+
+/**
+ * Write `.cache/tsconfig/*.json` and point the root config at them.
+ *
+ * The root becomes references-only. Anything a person had in `compilerOptions`
+ * there stops applying, which is why the generated projects carry the JSX
+ * options rather than relying on the root.
+ */
+export async function writeProjects(paths: MapOf<string[]>): Promise<string[]> {
+  const written: string[] = []
+
+  for (const project of allProjects()) {
+    const files = (project.files ?? [])
+      .map(entry => {
+        const resolved = resolveFilesEntry(entry)
+        if (!resolved) {
+          serveLog.TSCONFIG_FILE_UNRESOLVED({ entry })
+        }
+        return resolved
+      })
+      .filter((f): f is string => f !== null)
+
+    const config: Record<string, unknown> = {
+      $comment:
+        'GENERATED by Bakery on dev boot. Edits are lost; change the plugin or server.config.ts instead.',
+      extends: project.extends,
+      compilerOptions: {
+        ...(project.compilerOptions ?? {}),
+        // Only projects that opt in. `importMap` is served to the browser as
+        // `<script type="importmap">`, so its specifiers are resolved there and
+        // nowhere else — writing them into the server project made an import
+        // that cannot work on the server typecheck as though it could.
+        ...(project.importMapPaths && Object.keys(paths).length
+          ? { paths: mapPaths(paths) }
+          : {}),
+      },
+    }
+
+    if (files.length) config.files = files
+    if (project.include) config.include = project.include.map(fromProjectDir)
+    if (project.exclude) config.exclude = project.exclude.map(fromProjectDir)
+
+    const target = fs.resolve(PROJECT_DIR, `${project.name}.json`)
+    await Bun.write(target, `${JSON.stringify(config, null, 2)}\n`)
+    written.push(project.name)
+  }
+
+  return written
+}
+
+/** `paths` values are app-relative; the generated files sit two levels down. */
+function mapPaths(paths: MapOf<string[]>): MapOf<string[]> {
+  const out: MapOf<string[]> = {}
+  for (const [key, values] of Object.entries(paths)) {
+    out[key] = values.map(fromProjectDir)
+  }
+  return out
+}
+
+/**
+ * The app's root tsconfig with `references` set, and nothing else touched.
+ *
+ * Pure, and exported, so the merge can be tested without a function that writes
+ * to `process.cwd()`. The property that matters is negative — *no key the
+ * developer wrote is lost* — which is the kind of thing a shape assertion on the
+ * source cannot check.
+ */
+export function mergeRootConfig(
+  current: Record<string, unknown> | null,
+  references: { path: string }[],
+): Record<string, unknown> {
+  // Spread first so `references` is the only key this owns.
+  if (current) return { ...current, references }
+
+  // No root config at all. The generated projects do not help Bun's runtime, so
+  // the one this writes has to carry the JSX options itself.
+  return {
+    extends: '@bakery-framework/core/tsconfig.server.json',
+    compilerOptions: {
+      jsx: 'react',
+      jsxFactory: 'createElement',
+      jsxFragmentFactory: 'Fragment',
+    },
+    references,
+  }
+}
+
+/**
+ * Generate the project configs and add `references` to the app's root tsconfig.
+ *
+ * Separate from `syncTSConfigPaths` because an app can reasonably want one and
+ * not the other: the paths sync has existed for a long time and rewrites a file
+ * people keep in git, while this owns a directory nobody edits.
+ *
+ * **It used to replace the root config with a references-only stub, and that
+ * silently broke every `.tsx` page in the app.** The reasoning was tidy — the
+ * generated projects carry the JSX options, so the root does not need them — and
+ * it was wrong about *who reads the root*. `tsc` follows `references`; **Bun's
+ * runtime does not.** Bun reads `compilerOptions.jsx*` from the root
+ * `tsconfig.json` and nothing else, so a references-only root means pages get
+ * transpiled against the automatic JSX runtime instead of Bakery's
+ * `createElement`.
+ *
+ * The symptom is worse than the 500 that mistake usually produces. Measured on a
+ * scratch app: `GET /` answered **200** with
+ * `{"type":"html","props":{…},"_owner":null,"_store":{}}` — a React element tree,
+ * JSON-encoded, because the handler received an object where it expects a
+ * `SafeHtml` string. Nothing logs, nothing throws, the status is fine.
+ *
+ * So the root is now *merged*, not replaced: every key the developer wrote stays,
+ * and only `references` is ours. That also settles the contradiction with the
+ * scaffolder, which writes those JSX options under a comment saying to keep them
+ * — and with the three documentation pages that repeat it.
+ */
+export async function syncTSConfigProjects(): Promise<void> {
+  try {
+    const written = await writeProjects(buildPaths())
+
+    const references = written.map(name => ({
+      path: `./.cache/tsconfig/${name}.json`,
+    }))
+
+    const current = fs.exists(APP_CONFIG_PATH)
+      ? parseJSONC(await Bun.file(APP_CONFIG_PATH).text())
+      : null
+
+    // Only rewrite when the reference set actually changed. The root config is
+    // committed, and a dev boot that dirties git every time trains people to
+    // ignore the diff.
+    if (current && Bun.deepEquals(current.references, references)) return
+
+    const root = mergeRootConfig(current, references)
+
+    await Bun.write(APP_CONFIG_PATH, `${JSON.stringify(root, null, 2)}\n`)
+    serveLog.TSCONFIG_PROJECTS_WRITTEN({ count: String(written.length) })
+  } catch (err: any) {
+    serveLog.UNHANDLED_ERR({
+      error: `TSConfig project sync error: ${errorMsg(err)}`,
+    })
+  }
+}
+
 export async function syncTSConfigPaths(): Promise<void> {
   try {
     const newPaths = buildPaths()

package/src/core/config.ts

@@ -21,6 +21,13 @@ const defaultConfig: Required<AppConfig> = {
   middleware: [],
   backups: DEFAULT_DB_BACKUPS,
   blocked: [],
+  // No CORS by default. Not even permissive in development: a framework
+
+  // that quietly allows every origin teaches people it works, then
+
+  // surprises them in production.
+
+  cors: null,
   head: '',
   body: '',
   plugins: [],

package/src/core/define-route.ts

@@ -0,0 +1,66 @@
+import type { RouteHandler } from '../types'
+import { response } from '../utils/http'
+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
+ * `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
+ * the barrel; core's modules and tests import this file directly.
+ */
+
+/**
+ * Identity at runtime in its one-argument form; exists so a route module can
+ * declare its body shape once and have the whole signature inferred:
+ *
+ *   export default defineRoute<{ id: string }>((req, body) => …)
+ *
+ * With a validator, it also *enforces* that shape — see the overload below.
+ *
+ * `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>
+/**
+ * Validate the body before the handler runs.
+ *
+ *   export default defineRoute({ body: schema }, (req, body) => …)
+ *
+ * `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.
+ */
+export function defineRoute<T>(
+  options: { body: Validator<T> },
+  fn: RouteHandler<T>,
+): RouteHandler<T>
+export function defineRoute(
+  a: RouteHandler<any> | { body: Validator<any> },
+  b?: RouteHandler<any>,
+): RouteHandler<any> {
+  // One argument: identity, unchanged. Types only, no runtime cost — every
+  // existing route keeps working byte for byte.
+  if (typeof a === 'function') return a
+
+  const { body: validator } = a
+  const fn = b as RouteHandler<any>
+
+  return async function validatedRoute(req, body, server) {
+    const result = await validate(validator, body)
+    if (!result.ok) {
+      // The framework's one JSON envelope, so a validation failure looks like
+      // every other error a client receives rather than a special case.
+      return response.json.error(400, 'Invalid request body', {
+        issues: result.issues,
+      })
+    }
+    // The *parsed* value, not the raw body: a schema that coerces or strips
+    // unknown keys is doing so precisely to be used, and handing the handler
+    // the original would make the coercion a lie.
+    return fn(req, result.value, server)
+  }
+}

package/src/core/index.ts

@@ -1,8 +1,7 @@
 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 { encodeSSE, response, sse } from '../utils/http'
 import Bakery, { getHostname, hostKey, hostStore } from './bakery'
 import { getConfig, NOOP } from './config'
 import { createElement, Fragment, html } from './jsx'
@@ -10,17 +9,6 @@ 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.
@@ -34,11 +22,44 @@ export type {
   RouteResponse,
   Wrapped,
 } from '../types'
+/** Configured in `server.config.ts`; the type is exported so an app can build one. */
+export type { CorsOptions } from '../utils/http/cors'
+export type { SSEMessage, SSEOptions, SSEStream } from '../utils/http/sse'
+// The validation surface, so an app can type its own schemas and validators.
+export type {
+  FunctionValidator,
+  StandardSchemaLike,
+  ValidationIssue,
+  Validator,
+} from '../utils/http/validate'
+/**
+ * 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 { defineRoute } from './define-route'
 
+/**
+ * Note the shape of the two lines below: `sse` and `encodeSSE` are *imported*
+ * at the top of this file and re-exported here, not re-exported directly from
+ * `../utils/http/sse`.
+ *
+ * That is not style. `export … from '../utils/http/sse'` adds a second edge
+ * 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.
+ */
 export {
   Bakery,
   Case,
   createElement,
+  encodeSSE,
   Fragment,
   getConfig,
   // Multi-host helpers. Documented in docs/configuration/multi-host.md, and
@@ -55,6 +76,7 @@ export {
   match,
   NOOP,
   response,
+  sse,
   Try,
 }
 

package/src/core/port.ts

@@ -71,3 +71,58 @@ export function resolvePort(configPort?: number | null): number {
   // Changing that is a separate decision from unifying the three call sites.
   return configPort || DEFAULT_PORT
 }
+
+/**
+ * `--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`
+ * rejects it would be exactly the drift this module exists to end.
+ */
+function portFlagValue(argv: string[]): string | null {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--port' || arg === '-p') return argv[i + 1] ?? ''
+    if (arg.startsWith('--port=')) return arg.slice('--port='.length)
+    if (arg.startsWith('-p=')) return arg.slice('-p='.length)
+  }
+  return null
+}
+
+/**
+ * Fold a `--port` flag into `process.env.PORT`, before anything reads it.
+ *
+ * **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
+ * 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
+ * once, in the entry, means every existing reader is already correct.
+ *
+ * **Precedence: flag beats `PORT` beats config.** That is what `--port` means
+ * everywhere else a developer has met it (Vite, Next, Astro, Nuxt), and an
+ * explicit argument losing to an inherited environment variable would be the
+ * surprising order. It is also the recoverable one: a shell with a stale
+ * exported `PORT` is fixed by typing the flag, whereas the reverse needs the
+ * developer to work out which variable is winning.
+ *
+ * @throws if the flag is present but its value is not an integer in `0..65535`,
+ *   including when it is missing entirely (`bakery --port` with nothing after
+ *   it). A flag typed and then ignored is worse than one that complains.
+ */
+export function applyPortFlag(argv: string[] = process.argv.slice(2)): void {
+  const raw = portFlagValue(argv)
+  if (raw === null) return
+
+  const trimmed = raw.trim()
+  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}`,
+    )
+  }
+
+  process.env.PORT = String(parsed)
+}

package/src/global.d.ts

@@ -44,15 +44,30 @@ declare global {
     inBody?: boolean
   }
 
+  /**
+   * 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`.
+   */
+  type MiddlewareResponse =
+    | Response
+    | import('./utils/common/json').JsonResponseData
+
   type HostEntry = {
     root?: string
     importMap?: Record<string, string>
     middleware?: ((
       req: Request,
       server: Bun.Server<any>,
-    ) => MixedPromise<Response | void>)[]
+    ) => MixedPromise<MiddlewareResponse | void>)[]
     onRequest?(req: Request): MixedPromise<any>
     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
+     * permissive default, not even in development.
+     */
+    cors?: import('./utils/http/cors').CorsOptions | null
     head?: string
     body?: string
     proxy?: Record<string, string>
@@ -79,6 +94,12 @@ declare global {
 
     proxy?: Record<string, string>
 
+    /**
+     * Cross-origin resource sharing. Absent means no CORS headers at all,
+     * 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
     head?: string
 
     body?: string
@@ -94,7 +115,7 @@ declare global {
     middleware?: ((
       req: Request,
       server: Bun.Server<any>,
-    ) => MixedPromise<Response | void>)[]
+    ) => MixedPromise<MiddlewareResponse | void>)[]
 
     plugins?: ServerPlugin[]
 

package/src/handlers/core/$middleware.ts

@@ -1,15 +1,39 @@
 import { Bakery } from '../../core/bakery'
 import { errorMsg, handlerLog } from '../../logger/serve-log'
+import { JsonResponseData } from '../../utils/common/json'
 import { injectIfHtml, response } from '../../utils/http'
 import { Handler } from './$base'
 
+/**
+ * What a middleware may return to stop the chain.
+ *
+ * A `Response` and a `response.json.*` envelope, and deliberately nothing
+ * else. `JsonResponseData` is the framework's one-envelope idiom (convention
+ * 7) and `processResponse` already renders it with its own `status`, so an
+ * `ApiHandler` route returning `response.json.error(401, …)` answered 401
+ * while the identical line in a middleware did not — the value was not a
+ * `Response`, so the chain ignored it and the request carried on.
+ *
+ * Widening further, to "anything truthy", is the tempting version and is
+ * wrong: a middleware that returns a stray string or object would then halt
+ * the request by accident, and returning a value is how middleware signals
+ * *nothing* in plenty of code (`arr.map`, an assignment expression, an
+ * implicit arrow return). Two named shapes, both of which mean "I am the
+ * response".
+ */
+type MiddlewareResult = Response | JsonResponseData
+
+function isMiddlewareResult(value: unknown): value is MiddlewareResult {
+  return value instanceof Response || value instanceof JsonResponseData
+}
+
 /**
  * Per-request slot for the response produced during `canHandle`, so `handle`
  * can return it without re-running the chain. This was previously a static
  * field, which meant two concurrent requests could swap responses — including
  * each other's `Set-Cookie` headers — at any `await` boundary.
  */
-const pending = new WeakMap<Request, Response>()
+const pending = new WeakMap<Request, MiddlewareResult>()
 
 export class MiddlewareHandler extends Handler {
   /** Answers from app code, not from disk. See `Handler.servesFiles`. */
@@ -48,12 +72,12 @@ export class MiddlewareHandler extends Handler {
       return (await injectIfHtml(intercepted)) || intercepted
     }
 
-    let data: any
+    let data: MiddlewareResult | undefined
 
     for (const middleware of config.middleware) {
       try {
         const result = await middleware(req, Bakery.server!)
-        if (result instanceof Response) {
+        if (isMiddlewareResult(result)) {
           data = result
           break
         }
@@ -65,7 +89,12 @@ export class MiddlewareHandler extends Handler {
       }
     }
 
-    const injectedRes = await injectIfHtml(data)
+    // An envelope is JSON by construction, so it skips injection rather than
+    // paying `DOMTools.isHTML` to be told so. `processResponse` reads its
+    // `status` and serialises it.
+    if (data instanceof JsonResponseData) return data
+
+    const injectedRes = await injectIfHtml(data!)
     return injectedRes || data
   }
 }

package/src/logger/serve-log.ts

@@ -25,6 +25,17 @@ const serveMsgs = {
   WATCHER_ERR: 'E Watcher error: %r{error}%*',
   TSCONFIG_SYNCED:
     'I Synced %ytsconfig.json%* paths with %yserver.config.ts%*!',
+  TSCONFIG_PROJECTS_WRITTEN:
+    'I Wrote %y{count}%* tsconfig project(s) to %y.cache/tsconfig/%*',
+  // A plugin asking for a project name that is taken. Named rather than
+  // silent: the symptom otherwise is one plugin's types quietly not applying,
+  // discovered much later and blamed on the wrong thing.
+  TSCONFIG_PROJECT_CLASH:
+    'W Plugin %y{plugin}%* wants tsconfig project %y{project}%*, which already exists — %rskipped%*',
+  // Degrades to "no types" rather than failing the boot: a missing declaration
+  // is a worse editor experience, not a broken server.
+  TSCONFIG_FILE_UNRESOLVED:
+    'W Could not resolve tsconfig files entry %y{entry}%* — %rskipped%*',
   MANUAL_RELOAD: 'I %yManual reload%* triggered from client logger!',
   CONFIG_IMPORT_ERR: 'E Failed to import %yserver.config.ts%*: %r{error}%*',
   // Multi-line on purpose: a present-but-broken config booting on defaults is

package/src/plugins/types.ts

@@ -3,9 +3,68 @@ import type { MixedPromise } from '../types'
 
 export type ValidResponses = Handler.Response
 
+/**
+ * A TypeScript project a plugin contributes to the app.
+ *
+ * Written to `.cache/tsconfig/<name>.json` on every dev boot and referenced
+ * from the app's root `tsconfig.json`, so the editor typechecks each file under
+ * the project that owns it. Regenerated rather than committed: it is derived
+ * from the plugin list and the app's config, and `.cache/` is the disposable
+ * half of the two runtime directories.
+ */
+export interface PluginTsProject {
+  /** File name under `.cache/tsconfig/`, and the project's identity. */
+  name: string
+  /** Usually one of core's three bases. Written through as-is. */
+  extends: string
+  /** Globs, relative to the **app root** — the generator rewrites them. */
+  include?: string[]
+  exclude?: string[]
+  /**
+   * Ambient declarations the plugin owns.
+   *
+   * Package specifiers are allowed here and resolved to real paths before
+   * writing, because TypeScript resolves `files` as paths and would treat
+   * `@scope/pkg/x.d.ts` as a missing file rather than a module.
+   */
+  files?: string[]
+  compilerOptions?: Record<string, unknown>
+  /**
+   * Whether this project should receive `paths` derived from `importMap`.
+   *
+   * Off by default, and that default is the correction: the generator used to
+   * write those `paths` into *every* project on the reasoning that an alias is
+   * app-wide. It is not. `importMap` is a **browser** import map — the framework
+   * serves it as `<script type="importmap">` and the browser is what resolves
+   * its specifiers. An alias in the server project therefore typechecks an
+   * import that only the browser can satisfy, which is the same class of bug the
+   * server/client split was introduced to end.
+   *
+   * A plugin whose project compiles browser code should set it.
+   */
+  importMapPaths?: boolean
+}
+
+/** What a plugin contributes to the generated tsconfig projects. */
+export interface PluginTsConfig {
+  /** A project this plugin owns outright — Vue SFCs, for instance. */
+  project?: PluginTsProject
+}
+
 export interface ServerPlugin {
   name: string
   setup?(config: ProcessedAppConfig): MixedPromise<void>
+
+  /**
+   * Declarative, unlike every hook below it: read by the tsconfig generator at
+   * dev boot, never by the running server.
+   *
+   * A plugin that brings its own file type or its own ambient globals needs a
+   * project to typecheck them under. `@bakery-framework/plugin-vue` is the
+   * worked example — it owns `.vue` and declares `req`/`body` for SFC scope,
+   * globals core deliberately does not provide.
+   */
+  tsconfig?: PluginTsConfig
   onStart?(server: Bun.Server<any>): MixedPromise<void>
   onRequest?(req: Request): ValidResponses
   onRoute?(req: Request): MixedPromise<void>

package/src/router.ts

@@ -18,6 +18,7 @@ import {
   response,
   withStatus,
 } from './utils/http'
+import { applyCors, preflightResponse } from './utils/http/cors'
 
 /**
  * Resolve a WebSocket upgrade, refusing cross-origin handshakes first.
@@ -97,6 +98,19 @@ export async function handleRequest(req: Request) {
   // itself, so that was a second full path resolution of the same string on
   // every request.
   const config = Bakery.config
+
+  // Before anything else, including the forbidden-path check: a preflight names
+  // the route it is asking about in a *header*, not the path, so running it
+  // through routing would answer a question nobody asked. The browser sends no
+  // credentials with it either, which is why it cannot be authorised.
+  //
+  // Only when `cors` is configured. Absent, this is not reached at all and the
+  // browser's own default applies.
+  if (config.cors) {
+    const preflight = preflightResponse(config.cors, req)
+    if (preflight) return preflight
+  }
+
   const serveRoot = config.root
   if (fs.isForbidden(serveRoot + path, serveRoot)) {
     return new Response('Forbidden', { status: 403 })
@@ -338,6 +352,14 @@ export async function processResponse(
   // append, not set: a handler may already have issued its own Set-Cookie
   // (e.g. an auth cookie from a login route) that must not be overwritten.
   sess && resp.headers.append('Set-Cookie', sess)
+
+  // Every response funnels through here — pages, API JSON, static files, error
+  // pages — so this is the one place that cannot miss one. Applied before ETag
+  // so the negotiated `Vary` sees the `Origin` entry and merges with it rather
+  // than either overwriting the other.
+  const cors = Bakery.config.cors
+  if (cors) applyCors(cors, req, resp)
+
   const final = ETag.sendResponse(req, resp)
   if (!(final instanceof Response)) {
     log({

package/src/utils/http/cors.ts

@@ -0,0 +1,170 @@
+/**
+ * Cross-origin resource sharing.
+ *
+ * Bakery already ships the pieces of an API server — `ApiHandler`, sessions,
+ * CSRF, rate limiting — and had no way to serve one to a browser on another
+ * origin. This is that.
+ *
+ * Two halves, and both are needed: a preflight `OPTIONS` has to be answered
+ * before routing (there is no route to run, and the browser will not send the
+ * real request until it is answered), and every *other* response needs the
+ * headers appended on the way out.
+ *
+ * **Nothing happens unless `cors` is configured.** No default origin, not even
+ * a permissive one in development: a framework that quietly allows every origin
+ * teaches people it works and then surprises them in production. An absent
+ * config means the headers are never written, which is the browser's own
+ * default and the safe one.
+ */
+
+/** What the app writes in `server.config.ts`. */
+export interface CorsOptions {
+  /**
+   * Origins allowed to read responses.
+   *
+   * `'*'` is honoured literally, and is refused in combination with
+   * `credentials` — see `resolveOrigin`. A function receives the request's
+   * `Origin` and returns the value to echo, or `null` to deny.
+   */
+  origin: string | string[] | ((origin: string) => string | null)
+  /** Defaults to the methods a browser will preflight for. */
+  methods?: string[]
+  /** Request headers the browser may send. Defaults to echoing what it asks. */
+  allowHeaders?: string[]
+  /** Response headers JavaScript may read. Nothing is exposed by default. */
+  exposeHeaders?: string[]
+  /** Send `Access-Control-Allow-Credentials`. Incompatible with `origin: '*'`. */
+  credentials?: boolean
+  /** Preflight cache lifetime in seconds. */
+  maxAge?: number
+}
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+
+/**
+ * The value for `Access-Control-Allow-Origin`, or `null` to send nothing.
+ *
+ * **`'*'` with credentials is refused rather than silently downgraded.** The
+ * browser rejects that pairing anyway, so honouring it would produce a request
+ * that fails in the client with a CORS error and a server that believes it
+ * allowed the call. Echoing the origin instead would be a *quiet widening* of
+ * what the app asked for. Returning null makes the misconfiguration visible as
+ * a denied request, which is the direction a security control should fail in.
+ */
+export function resolveOrigin(
+  options: CorsOptions,
+  requestOrigin: string | null,
+): string | null {
+  const { origin, credentials } = options
+
+  if (origin === '*') return credentials ? null : '*'
+  if (!requestOrigin) return null
+
+  if (typeof origin === 'function') return origin(requestOrigin)
+  if (Array.isArray(origin)) {
+    return origin.includes(requestOrigin) ? requestOrigin : null
+  }
+  return origin === requestOrigin ? requestOrigin : null
+}
+
+/**
+ * Headers for a non-preflight response, or `null` when the origin is denied.
+ *
+ * `Vary: Origin` is always set when the allowed origin is anything but `'*'`,
+ * because the response now differs per origin and a shared cache that ignored
+ * that would serve one origin's response to another.
+ */
+export function corsHeaders(
+  options: CorsOptions,
+  requestOrigin: string | null,
+): Record<string, string> | null {
+  const allowed = resolveOrigin(options, requestOrigin)
+  if (allowed === null) return null
+
+  const headers: Record<string, string> = {
+    'Access-Control-Allow-Origin': allowed,
+  }
+  if (allowed !== '*') headers.Vary = 'Origin'
+  if (options.credentials) {
+    headers['Access-Control-Allow-Credentials'] = 'true'
+  }
+  if (options.exposeHeaders?.length) {
+    headers['Access-Control-Expose-Headers'] = options.exposeHeaders.join(', ')
+  }
+  return headers
+}
+
+/**
+ * The response to a preflight, or `null` if this is not one.
+ *
+ * A preflight is `OPTIONS` *with* `Access-Control-Request-Method` — plain
+ * `OPTIONS` is a normal request and must fall through to routing, or an app
+ * with its own OPTIONS route would find it shadowed.
+ *
+ * 204 rather than 200: there is no body, and some proxies treat a 200 with no
+ * content-length as needing one.
+ */
+export function preflightResponse(
+  options: CorsOptions,
+  req: Request,
+): Response | null {
+  if (req.method !== 'OPTIONS') return null
+  if (!req.headers.get('Access-Control-Request-Method')) return null
+
+  const base = corsHeaders(options, req.headers.get('Origin'))
+  // A denied origin still gets an answer, just without the headers that would
+  // permit the call. Returning 403 here would be a worse signal: the browser
+  // reports a CORS failure either way, and a 403 invites debugging the route.
+  if (!base) return new Response(null, { status: 204 })
+
+  const headers: Record<string, string> = {
+    ...base,
+    'Access-Control-Allow-Methods': (options.methods ?? DEFAULT_METHODS).join(
+      ', ',
+    ),
+  }
+
+  // Echoing the requested headers is what makes a default config usable:
+  // enumerating every header a client might send is a list nobody maintains,
+  // and getting it wrong fails at request time in the browser only.
+  const requested = req.headers.get('Access-Control-Request-Headers')
+  const allow = options.allowHeaders?.length
+    ? options.allowHeaders.join(', ')
+    : requested
+  if (allow) headers['Access-Control-Allow-Headers'] = allow
+
+  if (options.maxAge !== undefined) {
+    headers['Access-Control-Max-Age'] = String(options.maxAge)
+  }
+
+  // Vary on the negotiated request headers too, for the same caching reason.
+  headers.Vary = [headers.Vary, 'Access-Control-Request-Headers']
+    .filter(Boolean)
+    .join(', ')
+
+  return new Response(null, { status: 204, headers })
+}
+
+/** Append the headers to a response that already exists. */
+export function applyCors(
+  options: CorsOptions,
+  req: Request,
+  res: Response,
+): Response {
+  const headers = corsHeaders(options, req.headers.get('Origin'))
+  if (!headers) return res
+
+  for (const [key, value] of Object.entries(headers)) {
+    // `Vary` may already carry a value from ETag negotiation; appending keeps
+    // both rather than dropping whichever ran second.
+    if (key === 'Vary' && res.headers.has('Vary')) {
+      const existing = res.headers.get('Vary') ?? ''
+      if (!existing.split(',').some(v => v.trim() === value)) {
+        res.headers.set('Vary', `${existing}, ${value}`)
+      }
+      continue
+    }
+    res.headers.set(key, value)
+  }
+  return res
+}

package/src/utils/http/index.ts

@@ -6,3 +6,4 @@ export * from './etag'
 export * from './html'
 export * from './ip'
 export * from './response'
+export * from './sse'

package/src/utils/http/sse.ts

@@ -0,0 +1,200 @@
+/**
+ * Server-sent events.
+ *
+ * Bakery had WebSockets and nothing for one-way streaming, which is the cheaper
+ * half of that pair and the right shape for progress, notifications and tailing
+ * — no upgrade, no protocol, reconnects handled by the browser.
+ *
+ * A route could always return a `Response` wrapping a `ReadableStream` and it
+ * would reach the client intact: `ETag.sendResponse` returns early without an
+ * `ETag` header, and `injectIfHtml` ignores anything that is not HTML. What was
+ * missing is the framing, and framing is where this goes wrong — a payload
+ * containing a newline silently truncates unless every line is prefixed, and a
+ * write after the client has gone throws where nobody is catching.
+ */
+
+/** One event. Every field is optional except the payload. */
+export interface SSEMessage {
+  /** Serialised with `JSON.stringify` unless it is already a string. */
+  data: unknown
+  /** `event:` — the client listens for this name instead of `message`. */
+  event?: string
+  /** `id:` — echoed back as `Last-Event-ID` when the browser reconnects. */
+  id?: string
+  /** `retry:` — how long the browser waits before reconnecting, in ms. */
+  retry?: number
+}
+
+/** The handle a producer writes to. */
+export interface SSEStream {
+  /** Send one event. A no-op once the stream is closed. */
+  send(message: SSEMessage | unknown): void
+  /** Send a `:` comment. Useful as a keep-alive through idle proxies. */
+  comment(text?: string): void
+  /** Close the stream. Idempotent. */
+  close(): void
+  /** True once the client has gone or `close()` has run. */
+  readonly closed: boolean
+}
+
+export interface SSEOptions {
+  /**
+   * Milliseconds between automatic keep-alive comments. `0` disables them.
+   *
+   * Defaults to 15s because idle proxies and load balancers commonly cut a
+   * connection at 30–60s, and a dead SSE stream is invisible: the browser
+   * reconnects silently, so the symptom is duplicated work on the server rather
+   * than an error anyone sees.
+   */
+  keepAlive?: number
+  /** Initial `retry:` hint sent once, before any event. */
+  retry?: number
+}
+
+/**
+ * Encode one message as an SSE frame.
+ *
+ * **Every line of `data` is prefixed.** A payload containing a newline is
+ * otherwise cut short at that newline — the rest is read as a new field, and
+ * the client sees a truncated message rather than an error. Pretty-printed JSON
+ * and stack traces both hit this.
+ */
+export function encodeSSE(message: SSEMessage): string {
+  const lines: string[] = []
+
+  if (message.event) lines.push(`event: ${message.event}`)
+  if (message.id !== undefined) lines.push(`id: ${message.id}`)
+  if (message.retry !== undefined) lines.push(`retry: ${message.retry}`)
+
+  const payload =
+    typeof message.data === 'string'
+      ? message.data
+      : JSON.stringify(message.data)
+
+  // `?? ''` rather than skipping: `JSON.stringify(undefined)` is undefined, and
+  // a frame with no `data:` line at all is a comment to the client — the event
+  // would vanish rather than arrive empty.
+  for (const line of (payload ?? '').split('\n')) lines.push(`data: ${line}`)
+
+  // The blank line terminates the frame. Without it the client buffers forever.
+  return `${lines.join('\n')}\n\n`
+}
+
+/**
+ * Build an SSE response and hand the producer a stream to write to.
+ *
+ *     export default defineRoute(req =>
+ *       sse(req, stream => {
+ *         const timer = setInterval(() => stream.send({ now: Date.now() }), 1000)
+ *         return () => clearInterval(timer)
+ *       }),
+ *     )
+ *
+ * The producer may return a cleanup function, which runs exactly once when the
+ * client disconnects or `close()` is called. That is the only reliable place to
+ * stop a timer or unsubscribe: without it, a closed connection leaves the
+ * interval running for the life of the process, and the leak is silent.
+ */
+export function sse(
+  req: Request,
+  producer: (
+    stream: SSEStream,
+  ) => void | (() => void) | Promise<void | (() => void)>,
+  options: SSEOptions = {},
+): Response {
+  const encoder = new TextEncoder()
+  const { keepAlive = 15_000, retry } = options
+
+  let controller: ReadableStreamDefaultController<Uint8Array> | null = null
+  let closed = false
+  let cleanup: (() => void) | void
+  let keepAliveTimer: ReturnType<typeof setInterval> | undefined
+
+  const write = (chunk: string) => {
+    if (closed || !controller) return
+    try {
+      controller.enqueue(encoder.encode(chunk))
+    } catch {
+      // The client went away between the `closed` check and the enqueue. That
+      // is a normal race on every disconnect, not an error worth surfacing —
+      // and throwing here would reject inside a timer callback, where nothing
+      // is catching.
+      finish()
+    }
+  }
+
+  function finish() {
+    if (closed) return
+    closed = true
+    if (keepAliveTimer) clearInterval(keepAliveTimer)
+    try {
+      cleanup?.()
+    } catch {
+      // A producer's cleanup that throws must not prevent the stream closing;
+      // the connection is already going away either way.
+    }
+    try {
+      controller?.close()
+    } catch {
+      // Already closed by the runtime when the client disconnected.
+    }
+  }
+
+  const stream: SSEStream = {
+    send(message) {
+      const normalised: SSEMessage =
+        message && typeof message === 'object' && 'data' in (message as object)
+          ? (message as SSEMessage)
+          : { data: message }
+      write(encodeSSE(normalised))
+    },
+    comment(text = '') {
+      write(`: ${text}\n\n`)
+    },
+    close: finish,
+    get closed() {
+      return closed
+    },
+  }
+
+  const body = new ReadableStream<Uint8Array>({
+    async start(c) {
+      controller = c
+
+      // The client aborting is the common ending, not an exception. Without
+      // this the producer keeps writing into a dead socket.
+      req.signal?.addEventListener('abort', finish, { once: true })
+      if (req.signal?.aborted) return finish()
+
+      if (retry !== undefined) write(`retry: ${retry}\n\n`)
+      if (keepAlive > 0) {
+        keepAliveTimer = setInterval(
+          () => stream.comment('keep-alive'),
+          keepAlive,
+        )
+      }
+
+      try {
+        cleanup = await producer(stream)
+      } catch {
+        // A producer that throws ends the stream rather than leaving the client
+        // hanging on a connection nobody will write to again.
+        finish()
+      }
+    },
+    cancel: finish,
+  })
+
+  return new Response(body, {
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      // A cached event stream is a stream that never arrives.
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      // nginx buffers proxied responses by default, which holds every event
+      // until the buffer fills — the stream appears to work in development and
+      // to hang in production. This is the documented opt-out.
+      'X-Accel-Buffering': 'no',
+    },
+  })
+}

package/src/utils/http/validate.ts

@@ -0,0 +1,106 @@
+/**
+ * Request-body validation for route modules.
+ *
+ * `defineRoute<{ title: string }>` declares a body shape and enforces nothing —
+ * the scaffolder's own template says so twice: *"declares the contract — it
+ * does not validate it. The body is still client input."* Every route was left
+ * to hand-check or not, and most did not.
+ *
+ * **No schema library is bundled, and none is depended on.** `@bakery-framework/
+ * core` has zero runtime dependencies and that is worth keeping, so validation
+ * accepts two shapes it can consume without knowing who produced them:
+ *
+ *   - **Standard Schema** (`~standard`) — the shared interface zod, valibot and
+ *     arktype all implement. Bring your own library; Bakery never imports it.
+ *   - **A plain function** that returns the parsed value or throws.
+ *
+ * The second exists because the first is overkill for `body => { if (!body.id)
+ * throw new Error('id required'); return body }`, and a framework that forces a
+ * dependency for that has made the common case worse.
+ */
+
+/** The subset of Standard Schema v1 that validation needs. */
+export interface StandardSchemaLike<T> {
+  '~standard': {
+    version: 1
+    vendor: string
+    validate(value: unknown): StandardResult<T> | Promise<StandardResult<T>>
+  }
+}
+
+type StandardResult<T> =
+  | { value: T; issues?: undefined }
+  | { issues: readonly StandardIssue[] }
+
+interface StandardIssue {
+  message: string
+  path?: readonly (PropertyKey | { key: PropertyKey })[]
+}
+
+/** A function validator: return the parsed value, or throw to reject. */
+export type FunctionValidator<T> = (value: unknown) => T | Promise<T>
+
+export type Validator<T> = StandardSchemaLike<T> | FunctionValidator<T>
+
+/** One human-readable problem, with the field path when the schema gave one. */
+export interface ValidationIssue {
+  path: string
+  message: string
+}
+
+export type ValidationResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; issues: ValidationIssue[] }
+
+function isStandardSchema<T>(v: Validator<T>): v is StandardSchemaLike<T> {
+  return typeof v === 'object' && v !== null && '~standard' in v
+}
+
+/**
+ * Render a Standard Schema path as dotted notation.
+ *
+ * Segments may be plain keys or `{ key }` objects — the spec allows both, and a
+ * library that uses the object form would otherwise render as `[object Object]`
+ * in the very message meant to tell someone which field is wrong.
+ */
+function renderPath(path: StandardIssue['path']): string {
+  if (!path?.length) return ''
+  return path
+    .map(seg => (typeof seg === 'object' && seg !== null ? seg.key : seg))
+    .join('.')
+}
+
+/**
+ * Run a validator, never throwing.
+ *
+ * A function validator that throws is a *rejection*, not a crash: that is the
+ * whole idiom for the plain-function form. Its message becomes the issue, so
+ * `throw new Error('id must be a number')` reaches the client as written.
+ */
+export async function validate<T>(
+  validator: Validator<T>,
+  value: unknown,
+): Promise<ValidationResult<T>> {
+  if (isStandardSchema(validator)) {
+    const result = await validator['~standard'].validate(value)
+    if (result.issues) {
+      return {
+        ok: false,
+        issues: result.issues.map(issue => ({
+          path: renderPath(issue.path),
+          message: issue.message,
+        })),
+      }
+    }
+    return { ok: true, value: result.value }
+  }
+
+  try {
+    return { ok: true, value: await validator(value) }
+  } catch (error: any) {
+    return {
+      ok: false,
+      issues: [{ path: '', message: error?.message ?? 'Invalid request body' }],
+    }
+  }
+}