@bakery-framework/core 1.0.0

package/src/handlers/routes/proxy.ts

@@ -0,0 +1,74 @@
+import { Bakery } from '../../core/bakery'
+import { handlerLog } from '../../logger'
+import { response } from '../../utils/http'
+import { Handler } from '../core/$base'
+
+export class ProxyHandler extends Handler {
+  /** Answers from an upstream, not from disk. See `Handler.servesFiles`. */
+  static servesFiles = false
+
+  static get proxies() {
+    return Bakery.config.proxy || {}
+  }
+
+  static canHandle(path: string) {
+    for (const prefix in this.proxies) {
+      if (path.startsWith(prefix)) return true
+    }
+    return false
+  }
+
+  static async handle(path: string, req: Request) {
+    let proxyUrl = ''
+
+    for (const [prefix, target] of Object.entries(this.proxies)) {
+      if (!path.startsWith(prefix)) continue
+
+      const trailingPath = path.substring(prefix.length)
+      const baseTarget = target.endsWith('/') ? target.slice(0, -1) : target
+      proxyUrl =
+        baseTarget +
+        (trailingPath.startsWith('/') ? '' : '/') +
+        trailingPath +
+        ((req as any).__parsedUrl || new URL(req.url)).search
+      break
+    }
+
+    if (!proxyUrl) return response.error('Not Found')
+
+    handlerLog.PROXY_REQ({ path, target: proxyUrl })
+
+    // Don't hand a third-party upstream the caller's credentials. `host` is
+    // dropped so fetch derives it from the target URL rather than ours.
+    const headers = new Headers(req.headers)
+    for (const h of ['cookie', 'authorization', 'host', 'sec-fetch-site']) {
+      headers.delete(h)
+    }
+
+    const proxyReq = new Request(proxyUrl, {
+      method: req.method,
+      headers,
+      body: ['GET', 'HEAD'].includes(req.method) ? undefined : req.body,
+    })
+
+    let proxyRes: Response
+    try {
+      // Manual redirects: following one automatically would re-attach these
+      // headers to whatever host the upstream names, including link-local IPs.
+      proxyRes = await fetch(proxyReq, { redirect: 'manual' })
+    } catch {
+      return response.error('Bad Gateway', 502)
+    }
+
+    const resHeaders = new Headers(proxyRes.headers)
+    // Bun already decompressed the body, so the upstream's content-encoding is
+    // wrong — and so is its content-length, which described the compressed size.
+    resHeaders.delete('content-encoding')
+    resHeaders.delete('content-length')
+    return new Response(proxyRes.body, {
+      status: proxyRes.status,
+      statusText: proxyRes.statusText,
+      headers: resHeaders,
+    })
+  }
+}

package/src/logger/clients.ts

@@ -0,0 +1,12 @@
+/**
+ * WebSocket clients subscribed to the live log stream.
+ *
+ * `LiveReloadHandler` owns membership — it adds a socket on
+ * `subscribe_logger` and removes it on close. Consumers (the dashboard's
+ * log broadcast, the analytics `activeLoggers` gauge) only read.
+ *
+ * This lives in core rather than a plugin deliberately: it used to be
+ * defined in `plugins/analytics/core`, which made core import from a
+ * plugin — a backwards edge that blocks packaging core on its own.
+ */
+export const connectedLoggers = new Set<any>()

package/src/logger/index.ts

@@ -0,0 +1,3 @@
+export * from './clients'
+export * from './logger'
+export * from './serve-log'

package/src/logger/logger.ts

@@ -0,0 +1,375 @@
+import { PromptTracker } from '../compiler/prompt-tracker'
+import type { MapOf } from '../types'
+import { Case } from '../utils/common/case'
+import { match } from '../utils/common/match'
+import { Try } from '../utils/common/try'
+
+const logLevels = ['info', 'warn', 'error', 'fatal', 'debug', 'trace'] as const
+const byLength = 15
+
+export type LogLevels = (typeof logLevels)[number]
+
+export type LoggerEntry = {
+  level?: LogLevels
+  by?: string
+  msg: string
+}
+
+function getStackTrace(depth = 10, startAt = 0): string[] {
+  const stack = new Error().stack
+  const cwd = process.cwd()
+  if (!stack) return []
+  startAt += 2
+  return stack
+    .split('\n')
+    .map(line => line.replace(cwd, '.'))
+    .slice(startAt, startAt + depth)
+}
+
+const levelColors: Record<LogLevels | 'reset', string> = {
+  info: '%w', // White (Regular)
+  warn: '%y', // Yellow
+  error: '%r', // Red
+  fatal: '%r;31m', // Bold Red
+  debug: '%m', // Magenta
+  trace: '%d', // Gray
+  reset: '%0', // Reset
+}
+
+let onLogCallback: ((entry: LoggerEntry) => void) | null = null
+export function setLogCallback(cb: (entry: LoggerEntry) => void) {
+  onLogCallback = cb
+}
+
+/**
+ * Hand an entry to the registered sink, if there is one.
+ *
+ * Three call sites used to spell this as `Promise.try(() =>
+ * onLogCallback?.(…)).catch(() => {})`, which allocated two promises and
+ * scheduled a microtask for *every* line — including every line logged while
+ * no sink was registered at all. `Try` swallows a synchronous throw and a
+ * rejected promise alike (see `utils/isomorphic/try.ts`) without allocating
+ * anything on the synchronous path, which is the only path a sink typed
+ * `=> void` is supposed to take.
+ *
+ * The call stays synchronous, as `Promise.try` also was: `logger.test.ts`
+ * asserts the callback has fired by the time `log()` returns.
+ */
+function emit(entry: LoggerEntry): void {
+  if (!onLogCallback) return
+  Try(() => onLogCallback?.(entry))
+}
+
+// Hoisted: both were rebuilt on every call, and neither depends on the input.
+// The colour table is a 23-property literal and the pattern a regex literal,
+// so a process logging steadily paid for both on every line.
+const COLORS: MapOf<string> = {
+  r: '\x1b[31m', // Red
+  g: '\x1b[32m', // Green
+  y: '\x1b[33m', // Yellow
+  b: '\x1b[34m', // Blue
+  m: '\x1b[35m', // Magenta
+  c: '\x1b[36m', // Cyan
+  w: '\x1b[37m', // White
+  d: '\x1b[90m', // Gray / Dark Gray
+  B: '\x1b[38;5;94m', // Brown
+  p: '\x1b[38;5;129m', // Purple / Indigo
+  o: '\x1b[38;5;208m', // Orange
+  '*': '\x1b[0m', // Reset
+  '0': '\x1b[0m', // Reset
+
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+  brown: '\x1b[38;5;94m',
+  purple: '\x1b[38;5;129m',
+  orange: '\x1b[38;5;208m',
+  reset: '\x1b[0m',
+}
+
+// Safe to share despite the /g flag: `String.prototype.replace` resets
+// `lastIndex` on a global regex before it starts.
+const RX_COLORIZE = /%<([a-zA-Z0-9]+)>|%([a-zA-Z0-9*%])/g
+
+function colorizeTerminal(msg: string): string {
+  return msg.replace(RX_COLORIZE, (match, longName, short) => {
+    if (longName) return COLORS[longName] || match
+    if (short === '%') return '%'
+    return COLORS[short] || match
+  })
+}
+
+function getFormattedLine(
+  line: string,
+  index: number,
+  totalLines: number,
+  level: LogLevels,
+  by: string,
+  newLine: boolean,
+): string | null {
+  if (index === totalLines - 1 && line === '' && index > 0) return null
+
+  const color = levelColors[level] || levelColors.info
+  const lvTag = `${color}[${Case.upper(level.at(0) || '?')}]`
+  const byPad =
+    by.length <= byLength
+      ? by.padEnd(byLength)
+      : `${by.substring(0, byLength - 3)}...`
+
+  let message = `${lvTag} ${byPad}%0 ${line}%0 `
+
+  if ((level === 'trace' || level === 'fatal') && index === totalLines - 1) {
+    const stack = getStackTrace(5, 1)
+    const prefix = `\n${lvTag} ${byPad}%d `
+    message += `${prefix + stack.join(prefix)}%0`
+  }
+
+  message += `%0${newLine || index < totalLines - 1 ? '\n' : ''}`
+  return message
+}
+
+export function log(
+  { level = 'info', by = 'global', msg }: LoggerEntry,
+  newLine = true,
+) {
+  if (level === 'debug' && import.meta.env.PROD) return
+
+  const lines = msg.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const formatted = getFormattedLine(
+      lines[i],
+      i,
+      lines.length,
+      level,
+      by,
+      newLine,
+    )
+    if (formatted !== null) {
+      process.stdout.write(colorizeTerminal(formatted))
+    }
+  }
+
+  emit({ level, by, msg })
+}
+
+function withPromptTracker<T>(fn: () => T): T {
+  const isWatcherActive = process.env.DEV_WATCHER_ACTIVE === '1'
+  if (isWatcherActive) {
+    PromptTracker.activate(process.pid)
+  }
+
+  try {
+    return fn()
+  } finally {
+    if (isWatcherActive) {
+      PromptTracker.deactivate(process.pid)
+    }
+  }
+}
+
+export function confirm(msg: string, by = 'global'): boolean {
+  return withPromptTracker(() => {
+    const promptMsg = `%y${msg} (y/n): %r`
+
+    const formatted = getFormattedLine(promptMsg, 0, 1, 'warn', by, false)
+    const promptStr = formatted ? colorizeTerminal(formatted) : ''
+    emit({ level: 'warn', by, msg: promptMsg })
+
+    // No TTY: decline rather than treat an unanswerable prompt as consent.
+    if (!isInteractive()) return false
+
+    const response = prompt(promptStr)?.trim().toLowerCase()
+    return response === 'y' || response === 'yes'
+  })
+}
+
+const MAX_PROMPT_ATTEMPTS = 10
+
+/** False in Docker/CI, where `prompt()` returns null instead of blocking. */
+export function isInteractive(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+export function select(msg: string, options: string[], by = 'global'): string {
+  const index = selectIndex(msg, options, by)
+  return options[index] as string
+}
+
+function readValidIndex(_msg: string, max: number, by: string): number {
+  const promptMsg = `Select an option (1-${max}): `
+  const formatted = getFormattedLine(promptMsg, 0, 1, 'info', by, false)
+  const promptStr = formatted ? colorizeTerminal(formatted) : ''
+
+  // Without a TTY (Docker, CI) `prompt()` returns null immediately, so looping
+  // here would spin forever printing "Invalid option."
+  if (!isInteractive()) {
+    log({
+      level: 'error',
+      by,
+      msg: 'Cannot prompt for input: no interactive terminal. Re-run with an explicit choice (e.g. --choose=db) or a TTY.',
+    })
+    process.exit(1)
+  }
+
+  let attempts = 0
+  while (attempts++ < MAX_PROMPT_ATTEMPTS) {
+    emit({ level: 'info', by, msg: promptMsg })
+
+    const response = prompt(promptStr)?.trim()
+    const num = parseInt(response || '', 10)
+    if (!Number.isNaN(num) && num >= 1 && num <= max) {
+      return num - 1
+    }
+    log({ level: 'error', by, msg: 'Invalid option.' })
+  }
+
+  log({
+    level: 'error',
+    by,
+    msg: `No valid option after ${MAX_PROMPT_ATTEMPTS} attempts. Aborting.`,
+  })
+  process.exit(1)
+}
+
+export function selectIndex(msg: string, opt: string[], by = 'global'): number {
+  return withPromptTracker(() => {
+    log({ by, msg: '\n' })
+    log({ by, msg })
+
+    opt.forEach((opt, i) => void log({ by, msg: `  ${i + 1}. ${opt}` }))
+
+    const index = readValidIndex(msg, opt.length, by)
+    log({ by, msg: '\n' })
+    return index
+  })
+}
+
+export class Logger {
+  constructor(private by: string) {}
+
+  static log = log
+  static confirm = confirm
+  static select = select
+  static selectIndex = selectIndex
+
+  static messages<T extends MapOf<string>>(by: string, msgs: T) {
+    const logger = new Logger(by)
+    return messageLogger(logger, msgs)
+  }
+
+  log(msg: string, level?: LogLevels) {
+    log({ level, by: this.by, msg })
+  }
+
+  confirm(msg: string) {
+    return confirm(msg, this.by)
+  }
+
+  select(msg: string, options: string[]) {
+    return select(msg, options, this.by)
+  }
+
+  selectIndex(msg: string, options: string[]) {
+    return selectIndex(msg, options, this.by)
+  }
+}
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {}
+
+type ExtractArgs<S extends string> =
+  S extends `${infer _}{${infer Param}}${infer Rest}`
+    ? Prettify<{ [K in Param]: string | number | boolean } & ExtractArgs<Rest>>
+    : // No placeholders in this message, so it takes no arguments.
+      {}
+
+type Messages<T extends MapOf<string>> = {
+  [K in keyof T]: T[K] extends string
+    ? keyof ExtractArgs<T[K]> extends never
+      ? () => void
+      : (payload: ExtractArgs<T[K]>) => void
+    : never
+}
+
+// Shared for the same reason as RX_COLORIZE above.
+const RX_PARAM = /\{([^}]+)\}/g
+
+type ParsedMessage = {
+  /** The string this was parsed from — the cache's validity check. */
+  raw: string
+  level: LogLevels
+  template: string
+}
+
+/**
+ * Split `'W Rate limited: %y{ip}%*'` into its level tag and its template.
+ *
+ * A pure function of the declared message string, so it is a per-key constant
+ * and belongs behind the cache in `messageLogger` rather than on the call path.
+ */
+function parseMessage(raw: string): ParsedMessage {
+  const spaceIdx = raw.indexOf(' ')
+  const rawLevel = spaceIdx > -1 ? raw.substring(0, spaceIdx) : 'E'
+
+  return {
+    raw,
+    level: match(rawLevel, {
+      W: 'warn',
+      E: 'error',
+      D: 'debug',
+      [match]: 'info',
+    }),
+    template: spaceIdx > -1 ? raw.substring(spaceIdx + 1) : raw,
+  }
+}
+
+export function messageLogger<T extends MapOf<string>>(
+  loggerInstance: Logger,
+  targetMsgs: T,
+) {
+  /**
+   * One entry per *declared* key, so it is bounded by the message table — the
+   * tables in `serve-log.ts` are literals of a dozen-odd entries each.
+   * Undeclared props are deliberately left uncached: the trap fabricates a
+   * message for those, and a caller reading arbitrary property names off the
+   * proxy would otherwise grow this map without limit (convention 6).
+   */
+  const emitters = new Map<string, ParsedMessage & { fn: Emitter }>()
+
+  const build =
+    (parsed: ParsedMessage): Emitter =>
+    (payload?: MapOf<any>) => {
+      const formattedMessage = parsed.template.replace(RX_PARAM, (_, key) => {
+        return String(payload?.[key] ?? `{${key}}`)
+      })
+
+      loggerInstance.log(formattedMessage, parsed.level)
+    }
+
+  return new Proxy(targetMsgs, {
+    get(target, prop: string) {
+      const raw = target[prop]
+      if (!raw) return build(parseMessage(msgNotFound(prop)))
+
+      let cached = emitters.get(prop)
+      // Re-parse when the table was mutated under us. `raw` is the entire
+      // parse input, so comparing it is the whole validity check.
+      if (!cached || cached.raw !== raw) {
+        const parsed = parseMessage(raw)
+        cached = { ...parsed, fn: build(parsed) }
+        emitters.set(prop, cached)
+      }
+
+      return cached.fn
+    },
+  }) as any as Messages<T>
+}
+
+type Emitter = (payload?: MapOf<any>) => void
+
+const msgNotFound = (prop: string) =>
+  `E Error message not found: ${String(prop)}`

package/src/logger/serve-log.ts

@@ -0,0 +1,206 @@
+import { Logger, messageLogger } from './logger'
+
+const serveMsgs = {
+  STARTING: 'I Starting server in %c{mode}%* mode...',
+  STARTING_THREADS:
+    'I Starting cluster supervisor with %g{count}%* workers (%creusePort%*)...',
+  THREAD_STARTED: 'I [%cWorker #{id}%*] Server running at:',
+  RESTART_REQ: 'I Dev server restart requested from %ysync engine%*!',
+  // Emitted by the dev worker (cli/dev.ts) when the schema-source hash matches
+  // the one recorded after the last successful sync, so the boot-time schema
+  // sync is skipped. `--sync` bypasses the skip.
+  SCHEMA_SYNC_SKIP:
+    'I Schema unchanged since last sync — %yskipping schema sync%* (%c--sync%* forces it)',
+  // The skip above is precisely when drift goes unnoticed: schema.ts has not
+  // changed, so no sync runs, so nothing looks at the database. Something else
+  // altered it — a hand-run ALTER, another environment pointed at the same URL,
+  // a restore from an older dump.
+  SCHEMA_DRIFT:
+    'W %yDatabase no longer matches the last schema Bakery applied%*: {reason}. Run %cdb:history%* to see what was applied, or %cdb:sync --dry-run%* to see what the difference means.',
+  UNHANDLED_ERR: 'E Unhandled Server Error: %r{error}%*',
+  SHUTTING_DOWN: 'W %yShutting down server...%*',
+  BACKEND_CHANGE: 'I Backend change detected: %y{file}%*',
+  SERVER_STARTED: 'I %gServer running at:%*',
+  SERVER_URL: 'I   ➜ %w{type}%*: %bhttp://{host}:{port}%*',
+  WATCHER_ERR: 'E Watcher error: %r{error}%*',
+  TSCONFIG_SYNCED:
+    'I Synced %ytsconfig.json%* paths with %yserver.config.ts%*!',
+  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
+  // the kind of failure a single scrolled-away line hides. DEV only — in PROD
+  // the same condition throws out of initConfig() instead of logging.
+  CONFIG_BROKEN:
+    'E %rserver.config.ts is present but failed to load — booting on built-in defaults (no plugins, no hosts, default port)%*\n  file: %y{file}%*\n{error}',
+  // The banner restatement of CONFIG_BROKEN, so the warning survives console
+  // scrollback and sits next to the URLs the developer actually reads.
+  CONFIG_BROKEN_BANNER:
+    'W %rserver.config.ts failed to load%* %y— running on built-in defaults. See the import error above.%*',
+  WEBSOCKET_ERR: 'E WebSocket error from %y{ip}%*: %r{error}%*',
+  RATE_LIMITED: 'W Rate limited: %y{ip}%*',
+  // Emitted instead of RATE_LIMITED when sampling (cli/rate-limit.ts) held
+  // lines back; the "30s" must stay in step with RATE_LIMIT_LOG_WINDOW_MS.
+  RATE_LIMITED_SUPPRESSED:
+    'W Rate limited: %y{ip}%* (%y{count}%* rejections suppressed in the last 30s)',
+  // Printed only when the *default* limit is in effect: an unconfigured rate
+  // limit silently 429s load tests and shared-NAT offices, so its existence
+  // gets one announcement. An app-configured value prints nothing.
+  RATE_LIMIT_DEFAULT:
+    'I Rate limit: %y{max}%* burst / %y{refill}%* req/s per IP (default) — set %crateLimit: false%* to disable',
+  // Multi-worker port sharing rides on kernel-level SO_REUSEPORT load
+  // balancing, which only Linux provides; elsewhere N sockets either fail to
+  // bind or never receive balanced traffic.
+  CLUSTER_CLAMPED:
+    'W [Cluster] %y{platform}%* has no kernel-level SO_REUSEPORT load balancing (Linux-only), so %y{requested}%* workers cannot share one port. Running a single worker.',
+  WORKER_RESPAWN:
+    'W [Cluster] Worker %g{id}%* exited unexpectedly — restarting in %y{delay}%*ms (consecutive failure #%y{failures}%*).',
+  // Thread-worker only: the master should hand over the shared memory pool
+  // before the worker starts serving; past the deadline the worker serves on
+  // its local pool rather than deadlock.
+  SHARED_POOL_TIMEOUT:
+    'W [Cluster] No shared memory pool from the master within %y{timeout}%*ms — serving on a worker-local pool; cross-worker counters and rate limits will not be shared until it arrives.',
+  // The version wipe could not empty the cache directory, so no "current"
+  // marker was written and the next boot will try again. Worth a line rather
+  // than silence: something is holding those files open, and a stale compiled
+  // page surviving an upgrade is the failure the wipe exists to prevent.
+  CACHE_WIPE_INCOMPLETE:
+    'W Cache directory could not be cleared for the version change — %y{dir}%* still contains %y{files}%*. Retrying on next start; close anything holding those files.',
+} as const
+
+export const serveLog = messageLogger(new Logger('serve'), serveMsgs)
+
+const handlerMsgs = {
+  // Emitted by `DynamicHandler.executeModule`, which every route handler goes
+  // through — an API route, a `.tsx` page and an `error-*.tsx` all land here.
+  // It used to say "API module" while printing a `.tsx` path, alongside a
+  // `TSX_IMPORT_ERR` that no code ever reached.
+  API_IMPORT_ERR: 'E Failed to import route module (%y{file}%*): %r{error}%*',
+  // The other half of the same failure: the module *loaded*, and exports no
+  // default. `ApiHandler` used to answer that with a bare 404 naming nothing,
+  // which reads as "your route file is missing" for a file that is right there.
+  API_NO_DEFAULT:
+    'E API route has no %cexport default%* (%y{file}%*) — the module loaded but exposes no handler',
+  // A handler ran and returned neither a value nor a Response. Still a 404 (see
+  // `ApiHandler.handle`), but the log names the file rather than leaving the
+  // developer to guess which route answered.
+  API_NO_RESPONSE: 'W API route returned no response: %y{file}%*',
+  PROXY_REQ: 'I Proxying %y{path}%* -> %b{target}%*',
+  MIDDLEWARE_ERR: 'E Middleware error: %r{error}%*',
+  BUNDLE_ERR: 'E Failed to bundle module (%y{file}%*): %r{error}%*',
+} as const
+
+export const handlerLog = messageLogger(new Logger('handlers'), handlerMsgs)
+
+const compileMsgs = {
+  FILE_STATUS: 'I File is %y{status}%*: %w{file}%*',
+  COMPILE_FAIL: 'E Failed to compile %y{file}%*: %r{error}%*',
+  /** Same failure, but for a source string with no originating file. */
+  COMPILE_SOURCE_FAIL: 'E Failed to compile inline source: %r{error}%*',
+  FILE_DEL: 'I File deleted: %w{file}%*',
+} as const
+
+export const compLog = messageLogger(new Logger('compile'), compileMsgs)
+
+const pluginMsgs = {
+  UNHANDLED_ERR: 'E Unhandled Plugin Error: %r{error}%*',
+  ANALYTICS_STORE_ERR: 'E Analytics store init failed: %r{error}%*',
+  DASHBOARD_BUNDLE_ERR: 'E Failed to bundle %ydashboard.js%*: %r{error}%*',
+} as const
+
+export const pluginLog = messageLogger(new Logger('plugins'), pluginMsgs)
+
+export const errorMsg = (err: any) => err?.stack || err?.message || String(err)
+
+/**
+ * The position record Bun attaches to a transpiler or resolver diagnostic.
+ *
+ * `BuildMessage` and `ResolveMessage` are the two things Bun throws for a
+ * syntax error and an unresolvable import. Neither is `instanceof Error`,
+ * neither carries a `stack`, and both report *zero* own enumerable keys — so
+ * nothing that inspects a thrown value by spreading it or by `instanceof` sees
+ * anything at all. `message`, `name` and `position` are the accessors that
+ * actually answer.
+ */
+type Diagnostic = {
+  name?: string
+  message?: string
+  position?: {
+    file?: string
+    line?: number
+    column?: number
+    lineText?: string
+  } | null
+}
+
+const headline = (err: Diagnostic) => {
+  const message = err.message || String(err)
+  return err.name && message
+    ? `${err.name}: ${message}`
+    : message || String(err)
+}
+
+function positionLines(position: Diagnostic['position']): string[] {
+  if (!position || typeof position !== 'object') return []
+
+  const lines: string[] = []
+  const { file, line, column, lineText } = position
+
+  if (file) lines.push(`  at ${file}:${line ?? 0}:${column ?? 0}`)
+  else if (line != null) lines.push(`  at line ${line}, column ${column ?? 0}`)
+
+  if (typeof lineText === 'string' && lineText.trim()) {
+    lines.push(`  | ${lineText}`)
+  }
+
+  return lines
+}
+
+/**
+ * Everything a thrown value knows about where it came from.
+ *
+ * `errorMsg` answers `stack || message`, which is the right answer for an
+ * `Error` and useless for the diagnostics above: they have no stack, so it
+ * degrades to a bare "Expected identifier but found end of file" with no file
+ * and no line. This walks `position` instead, and recurses through the
+ * `AggregateError.errors` array that `import()`ing a broken `.tsx` throws —
+ * that one *is* an `Error`, but it has no stack either, so the summary line
+ * ("4 errors building …") was all anyone ever saw.
+ *
+ * A real `Error` with a real stack still returns exactly `err.stack`, so the
+ * existing contract for the common case is unchanged.
+ */
+export function errorDetail(err: any): string {
+  if (!err || typeof err !== 'object') return String(err)
+  if (err.stack) return err.stack
+
+  const lines = [headline(err)]
+
+  if (Array.isArray(err.errors) && err.errors.length) {
+    for (const sub of err.errors) {
+      for (const line of errorDetail(sub).split('\n')) lines.push(`  ${line}`)
+    }
+    return lines.join('\n')
+  }
+
+  lines.push(...positionLines(err.position))
+  return lines.join('\n')
+}
+
+/**
+ * `errorMsg` with the diagnostic's line and column, but not its file.
+ *
+ * For the log lines whose template already names the file. Bun's own
+ * `position.file` is `input.ts` whenever `transform()` was handed a source
+ * string rather than a path — which is every compile this codebase does — so
+ * printing it beside the real path would contradict it.
+ */
+export function errorWithPosition(err: any): string {
+  const position = (err as Diagnostic)?.position
+  if (!position || position.line == null) return errorMsg(err)
+
+  const message = (err as Diagnostic).message || errorMsg(err)
+  return `${message} (line ${position.line}, column ${position.column ?? 0})`
+}
+
+const toMS = (ns: number) => parseFloat((ns / 1e6).toFixed(2))
+export const getElapsed = (start: number) => toMS(Bun.nanoseconds() - start)

package/src/plugins/index.ts

@@ -0,0 +1,15 @@
+/**
+ * The plugin-authoring surface, as one barrel.
+ *
+ * Every other public directory in core has an `index.ts` and `plugins/` did
+ * not, so `@bakery-framework/core/plugins` pointed straight at `routes.ts` — which meant
+ * `definePlugin` and `ServerPlugin` were only reachable through
+ * `@bakery-framework/core/plugins/types`, a second subpath for one concept. It also broke
+ * under TypeScript's `paths` resolution, which maps `@bakery-framework/core/plugins` to
+ * this directory and looks for an index rather than consulting the export map.
+ *
+ * Two files, one entry point: `routeTable`/`dispatch` from `routes`, and the
+ * plugin shape from `types`.
+ */
+export * from './routes'
+export * from './types'