@bakery-framework/core 1.2.3 → 2.0.0-alpha.11

package/src/compiler/prompt-tracker.ts

@@ -1,13 +1,30 @@
 import { unlinkSync } from 'node:fs'
-import { Bakery } from '../core/bakery'
+import { cacheDir } from '../core/context'
 import { Try } from '../utils/common/try'
 
+/**
+ * **`cacheDir` comes from `core/context`, not from `Bakery` — do not change it
+ * back.** `logger.ts` imports this module, so importing `core/bakery` here
+ * completed a cycle:
+ *
+ *     logger.ts -> prompt-tracker.ts -> core/bakery.ts -> core/config.ts
+ *       -> logger/serve-log.ts -> logger.ts
+ *
+ * `serve-log.ts` runs `new Logger('serve')` at module scope, so whichever
+ * import arrived first found `Logger` still in its temporal dead zone. That
+ * shipped in 1.2.3 and made `import '@bakery-framework/core'` throw
+ * `ReferenceError: Cannot access 'Logger' before initialization` from a clean
+ * install — see `tests/module-cycle.test.ts`.
+ *
+ * `core/context` holds the same single definition of the path and imports
+ * nothing that reaches the logger.
+ */
 export const PromptTracker = {
   getFilePath(pid: number): string {
     // Derived, not written out: this lands in the cache directory, which the
     // framework wipes wholesale, and a stale literal here would leave marker
     // files behind in a directory nothing sweeps.
-    return `${Bakery.cacheDir}/.prompt-active-${pid}`
+    return `${cacheDir()}/.prompt-active-${pid}`
   },
 
   async isActive(pid: number): Promise<boolean> {

package/src/compiler/tsconfig-sync.ts

@@ -61,6 +61,13 @@ const PROJECT_DIR = fs.resolve(APP_DIR, '.cache/tsconfig')
  * Before this existed, one config covered everything and `Bun.hash()` in a
  * client file typechecked clean and failed in the browser.
  *
+ * The includes overlap the app's own tsconfig, and that is fine *because
+ * nothing references these projects*: each is a standalone projection of one
+ * concern, pointed at directly (`tsc -p .cache/tsconfig/client.json`), and
+ * subtracting the app's include would gut them into projects that check
+ * nothing. What must never come back is the `references` wiring that composed
+ * them with the app project — see {@link syncTSConfigProjects}.
+ *
  * Globs are app-relative here and rewritten to be relative to the generated
  * file, which sits two levels down.
  */
@@ -322,22 +329,81 @@ function mapPaths(paths: MapOf<string[]>): MapOf<string[]> {
 }
 
 /**
- * The app's root tsconfig with `references` set, and nothing else touched.
+ * A `references` entry the generator wrote in a previous release, as opposed
+ * to one the developer owns. Ours always pointed into `.cache/tsconfig/`, and
+ * nothing else has a reason to: `.cache/` is the disposable runtime directory,
+ * and every project inside it is regenerated on boot.
+ */
+const RE_GENERATED_REF = /^(\.[\\/])?\.cache[\\/]tsconfig[\\/]/
+
+function isGeneratedReference(entry: unknown): boolean {
+  if (typeof entry !== 'object' || entry === null) return false
+  const path = (entry as { path?: unknown }).path
+  return typeof path === 'string' && RE_GENERATED_REF.test(path)
+}
+
+/**
+ * The root config with the generator's own `references` removed, or `null`
+ * when there is nothing to repair.
+ *
+ * Until 2026-08-27 `syncTSConfigProjects` *added* those references, wiring the
+ * generated projects into the app's project graph. That glue is what broke
+ * `tsc -p <app>` for every consumer who had booted once. Measured directly
+ * (TypeScript 6.0.3):
+ *
+ * - `tsc -p` verifies every referenced project whenever the referencing
+ *   program has input files of its own: a reference to a non-composite
+ *   project is TS6306 and to a `noEmit` one TS6310 — **even when the
+ *   referenced project's include is disjoint from the root's, and even when
+ *   it matches zero files**. No include shape survives.
+ * - Each root file a referenced project also claims is redirected to that
+ *   project's declaration output, which `noEmit` guarantees was never built:
+ *   TS6305, once per overlapping file — `src/**`, `server.config.ts`, every
+ *   `.tsx` page.
+ *
+ * The generated projects extend `noEmit` bases and rely on
+ * `allowImportingTsExtensions`, so they are unbuildable by design. Making them
+ * `composite` instead would trade the errors above for a `tsc -b` build-order
+ * requirement no consumer runs — and TS6305 would still fire for any root file
+ * importing into one while unbuilt. The only reference shape `tsc -p`
+ * tolerates from a root that has files of its own is no reference at all, so
+ * the projects stand alone now and this strips what previous releases wrote.
+ *
+ * Everything the developer owns is preserved: only entries into
+ * `.cache/tsconfig/` are removed, a real project reference (say `../shared`)
+ * stays, and the `references` key itself survives unless the generator wrote
+ * every entry in it.
+ *
+ * Pure, and exported, so the repair 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 a shape assertion on the source cannot
+ * check.
+ */
+export function stripGeneratedReferences(
+  current: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const refs = current.references
+  if (!Array.isArray(refs)) return null
+
+  const kept = refs.filter(entry => !isGeneratedReference(entry))
+  if (kept.length === refs.length) return null
+
+  const repaired = { ...current }
+  if (kept.length) repaired.references = kept
+  else delete repaired.references
+  return repaired
+}
+
+/**
+ * The root config written when the app has none at all.
  *
- * 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.
+ * The generated projects do not help Bun's runtime — it reads
+ * `compilerOptions.jsx*` from the root `tsconfig.json` and follows `extends`
+ * only into a relative path, never a package specifier — so the file this
+ * writes has to carry the JSX options itself, inline, exactly as the
+ * scaffolder spells them.
  */
-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.
+export function defaultRootConfig(): Record<string, unknown> {
   return {
     extends: '@bakery-framework/core/tsconfig.server.json',
     compilerOptions: {
@@ -345,58 +411,63 @@ export function mergeRootConfig(
       jsxFactory: 'createElement',
       jsxFragmentFactory: 'Fragment',
     },
-    references,
   }
 }
 
 /**
- * Generate the project configs and add `references` to the app's root tsconfig.
+ * Generate the project configs, and keep the app's root tsconfig viable —
+ * created with the runtime JSX options when the app has none, and stripped of
+ * the `references` a previous release wrote into it.
  *
  * 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.
+ * **The generated projects are standalone on purpose; the root config does not
+ * reference them.** They exist for direct invocation against the one concern
+ * each covers: `vue-tsc -p .cache/tsconfig/vue.json` is the only way an SFC
+ * typechecks at all, `tsc -p .cache/tsconfig/client.json` proves browser code
+ * clean of `Bun.*`, and a plugin's project carries its own ambients the same
+ * way. Their `include` deliberately overlaps the app's own project — they are
+ * alternate projections of the same files, used *instead of* the root for
+ * their slice, never composed with it. Wiring them in as `references` broke
+ * `tsc -p <app>` for any consumer who had booted once (TS6305/6306/6310 — the
+ * measurements are on {@link stripGeneratedReferences}), and what the wiring
+ * bought was less than it looked: tsserver routes a file to the project whose
+ * `include` claims it, so for everything a scaffolded root claims — `src/**`,
+ * `server.config.ts`, `orm/**` — the reference walk never ran anyway.
  *
- * 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.
+ * Two earlier lessons still bind the root-config half. It used to be
+ * *replaced* with a references-only stub, which silently broke every `.tsx`
+ * page: Bun's runtime reads `compilerOptions.jsx*` from the root and does not
+ * follow `references`, so pages transpiled against the automatic JSX runtime
+ * and `GET /` answered 200 with a JSON-encoded React element tree. Hence
+ * {@link defaultRootConfig} when no root exists, and surgical repair — never
+ * wholesale rewrite — when one does. And a boot that dirties git every time
+ * trains people to ignore the diff, so an already-clean root is not rewritten.
  */
 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
+    if (!current) {
+      await Bun.write(
+        APP_CONFIG_PATH,
+        `${JSON.stringify(defaultRootConfig(), null, 2)}\n`,
+      )
+      serveLog.TSCONFIG_PROJECTS_WRITTEN({ count: String(written.length) })
+      return
+    }
 
-    const root = mergeRootConfig(current, references)
+    const repaired = stripGeneratedReferences(current)
+    if (!repaired) return
 
-    await Bun.write(APP_CONFIG_PATH, `${JSON.stringify(root, null, 2)}\n`)
-    serveLog.TSCONFIG_PROJECTS_WRITTEN({ count: String(written.length) })
+    await Bun.write(APP_CONFIG_PATH, `${JSON.stringify(repaired, null, 2)}\n`)
+    serveLog.TSCONFIG_REFERENCES_REMOVED()
   } catch (err: any) {
     serveLog.UNHANDLED_ERR({
       error: `TSConfig project sync error: ${errorMsg(err)}`,

package/src/core/bakery.ts

@@ -2,7 +2,7 @@ import { HandlerMap } from '../handlers/core/$registry'
 import { fs } from '../utils/fs'
 import { SharedMemoryPool } from '../utils/shared-pool'
 import { getConfig, resolveHostname } from './config'
-import { getAppVersion, hostStore } from './context'
+import { cacheDir, dataDir, getAppVersion, hostStore } from './context'
 
 export type { HostContext } from './context'
 export { hostStore } from './context'
@@ -70,17 +70,16 @@ export const Bakery: globalThis.Bakery = {
     return getAppVersion()
   },
   sharedPool: new SharedMemoryPool(1024 * 1024),
-  // The disposable directory is the hidden one, and the precious one is not.
-  // This is the reverse of the old `.bakery/cache` + `.data` pairing, and the
-  // reversal is the whole point: `.cache` is wiped by the framework itself on
-  // every version bump and dev<->prod switch, so a `rm -rf .*` or a "clean out
-  // the dotfiles" sweep does exactly what the framework already does. The
-  // database is not disposable, so it does not live behind a leading dot where
-  // such a sweep can reach it.
-  cacheDir: `${fs.cwd}/.cache`,
-  // Holds the database and its backups. Visible, and deliberately not under
-  // `.cache`: clearing a cache must never be able to destroy data.
-  dataDir: `${fs.cwd}/bakery`,
+  // Defined in `core/context.ts`, which is low enough that a module needing a
+  // path does not have to import `Bakery` to get one — reaching them through
+  // here is what closed the logger cycle. These stay the reading surface for
+  // application and framework code; context is the single definition.
+  //
+  // Called here rather than forwarded through a getter, so these remain plain
+  // writable properties: `nm.test.ts` repoints them at a fixture tree, which a
+  // getter turns into `TypeError: Attempted to assign to readonly property`.
+  cacheDir: cacheDir(),
+  dataDir: dataDir(),
   startNs: Bun.nanoseconds(),
   handlers: {
     fetch: new HandlerMap(),

package/src/core/context.ts

@@ -29,6 +29,40 @@ export type HostContext = {
 
 export const hostStore = new AsyncLocalStorage<HostContext>()
 
+/**
+ * The two runtime directories, defined here rather than on `Bakery`.
+ *
+ * `Bakery.cacheDir` / `Bakery.dataDir` remain the way application and framework
+ * code reads them — these are the single definition those two forward to, and
+ * still the only writer of either path. They live in this module because it is
+ * low enough to be imported without pulling in `core/config`, and therefore
+ * without pulling in the logger: `compiler/prompt-tracker.ts` needs the cache
+ * directory and reaching it through `Bakery` closed a module cycle that made
+ * the whole package unimportable. See the note on `prompt-tracker.ts`.
+ *
+ * **Functions, not constants, and that is not a style choice.** `utils/fs.ts`
+ * imports this module for `hostStore`, so the two are themselves a cycle: a
+ * top-level `` `${fs.cwd}/.cache` `` here is evaluated with `fs` still
+ * uninitialised whenever `core/context` is reached first, and throws
+ * `TypeError: undefined is not an object`. Reading `fs.cwd` at call time is
+ * what makes the order irrelevant.
+ *
+ * The disposable directory is the hidden one, and the precious one is not. This
+ * is the reverse of the old `.bakery/cache` + `.data` pairing, and the reversal
+ * is the whole point: `.cache` is wiped by the framework itself on every version
+ * bump and dev<->prod switch, so a `rm -rf .*` or a "clean out the dotfiles"
+ * sweep does exactly what the framework already does. The database is not
+ * disposable, so it does not live behind a leading dot where such a sweep can
+ * reach it, and never under `.cache` — clearing a cache must not destroy data.
+ */
+export function cacheDir(): string {
+  return `${fs.cwd}/.cache`
+}
+
+export function dataDir(): string {
+  return `${fs.cwd}/bakery`
+}
+
 /**
  * `matchBlocked`, deduplicated within the current request.
  *
@@ -51,14 +85,6 @@ export function matchBlockedCached(
   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.
  *
@@ -78,6 +104,14 @@ const UNKNOWN_APP = '0.0.0-unknown-app'
 const UNKNOWN_FW = '0.0.0-unknown-framework'
 
 let _appVersion: string | null = null
+
+/**
+ * The **application's** version, from `<cwd>/package.json`.
+ *
+ * Not the framework's — this reads the manifest of whatever is being served.
+ * The distinction is load-bearing for cache invalidation; see
+ * {@link getFrameworkVersion}.
+ */
 export function getAppVersion() {
   if (_appVersion) return _appVersion
   try {

package/src/core/index.ts

@@ -4,6 +4,10 @@ import { Case, is, Math2, match, Try } from '../utils/common'
 import { encodeSSE, response, sse } from '../utils/http'
 import Bakery, { getHostname, hostKey, hostStore } from './bakery'
 import { getConfig, NOOP } from './config'
+// `./context` is already in this barrel's graph — line 5 reaches it through
+// `./bakery`, which re-exports `hostStore` from exactly here — so naming it
+// adds no module edge, only a name.
+import { getFrameworkVersion } from './context'
 import { createElement, Fragment, html } from './jsx'
 
 export const defineConfig = <T extends AppConfig>(config: T): T => config
@@ -19,6 +23,7 @@ export type {
   MixedPromise,
   RouteBody,
   RouteHandler,
+  RouteParam,
   RouteResponse,
   Wrapped,
 } from '../types'
@@ -62,6 +67,19 @@ export {
   encodeSSE,
   Fragment,
   getConfig,
+  /**
+   * The version of `@bakery-framework/core` itself, read from its own manifest.
+   *
+   * **Not the app's version**, which is what `import.meta.env.BAKERY_VERSION`
+   * and `getAppVersion()` report — the compiler reads those from
+   * `<cwd>/package.json`, so in an application they answer with the
+   * application's number. The name is a long-standing misnomer and this is the
+   * one that means what "Bakery version" sounds like it means.
+   *
+   * Exported because a plugin rendering framework chrome has no other way to
+   * ask. The dashboard's footer showed a hardcoded `v3` for want of it.
+   */
+  getFrameworkVersion,
   // Multi-host helpers. Documented in docs/configuration/multi-host.md, and
   // the only reason `./core/bakery` had to be a subpath of its own.
   getHostname,

package/src/core/init.ts

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

package/src/global.d.ts

@@ -342,13 +342,31 @@ declare global {
   // `ImportMeta.env` with its own incompatible shape, which is TS2687/TS2717 —
   // suppressed, like everything else in a .d.ts, by skipLibCheck.
   interface ImportMetaEnv {
-    readonly DEV: boolean
-    readonly PROD: boolean
-    readonly WORKER: boolean
-    readonly DEV_WORKER: boolean
-    readonly THREAD_WORKER: boolean
+    // `'1'` or `''`, not `true` or `false`. These live on `process.env`, and
+    // Bun 1.4 stopped accepting accessor descriptors there — a boolean is no
+    // longer expressible on that object at all, since data descriptors coerce
+    // too. See the encoding block in `core/init.ts`.
+    //
+    // Typed as the literal pair rather than `string` on purpose: it makes
+    // `import.meta.env.PROD !== false` a *compile* error. That comparison was
+    // real, in the dashboard's fail-closed gate, and under the string encoding
+    // it is true for every value including the `''` a development server sets —
+    // so the gate would have denied on loopback in development while still
+    // reading as correct. A type that only said `string` would not have caught
+    // it either.
+    //
+    // In a **browser** bundle these are real booleans: `compiler.ts` substitutes
+    // `JSON.stringify(!!import.meta.env.DEV)` at build time, so the literal
+    // `true`/`false` is inlined and this declaration is a slight lie there. It
+    // is the harmless direction — both encodings agree on truthiness, which is
+    // all client code tests — and the server is where the mistakes happen.
+    readonly DEV: '1' | ''
+    readonly PROD: '1' | ''
+    readonly WORKER: '1' | ''
+    readonly DEV_WORKER: '1' | ''
+    readonly THREAD_WORKER: '1' | ''
     readonly THREAD_ID: string
-    readonly TEST: boolean
+    readonly TEST: '1' | ''
     readonly MODE: 'production' | 'development' | 'dev-worker' | 'thread-worker'
     // `readonly SERVE_ROOT: string` was declared here. Nothing defines it —
     // not init.ts, not the compiler's `defines` — and nothing reads it, so any