@bakery-framework/core 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "1.1.0",
+  "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/client/utils.ts

@@ -161,7 +161,17 @@ Object.assign(globalThis, {
   request,
   randomId,
   Bakery: {
-    version: import.meta.env.BAKERY_VERSION,
+    // **Cast rather than `import.meta.env` directly.** `ImportMeta.env` is
+    // declared by `bun-types`, and this file is compiled by the *client*
+    // tsconfig, which deliberately has none — reaching for a Bun-provided type
+    // here would undo the split it exists to enforce.
+    //
+    // Declaring `ImportMeta` in client/globals.d.ts instead would clash with
+    // bun-types inside core's own project, which is the incompatible
+    // redeclaration this repo has already had once. The value is substituted by
+    // the compiler at build time, so the cast describes what is actually there.
+    version: (import.meta as { env?: Record<string, string | undefined> }).env
+      ?.BAKERY_VERSION,
     async virtual(path: string) {
       const response = await fetch(path)
       if (!response.ok) {

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)
+}