create-bakery 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Kyle Cyrus Santos Obille
+
+The Software is provided subject to the standard MIT License, as detailed below, with the addition of the Commons Clause v1.0.
+
+The Commons Clause v1.0
+
+The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, “Sell” means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/support services related to the Software), a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
+
+Standard MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software (subject to the Commons Clause condition above), and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# create-bakery
+
+The scaffolder behind `bun create bakery`.
+
+```bash
+bun create bakery my-app
+```
+
+Writes a working [Bakery](https://github.com/obillekyle/bakery) app: a page,
+an API route that round-trips through SQLite, a registered ORM schema, and a
+`db:sync` script. Then:
+
+```bash
+cd my-app
+bun run db:sync
+bun run dev
+```
+
+## Options
+
+| Flag | Effect |
+| --- | --- |
+| `--name <name>` | Package name, when it should differ from the directory |
+| `--no-install` | Write the files and stop |
+| `-h`, `--help` | Usage |
+
+Use `.` as the directory to scaffold in place. The positional argument is a
+*path*, so its basename becomes the package name — scoped names come from
+`--name`.
+
+It refuses to scaffold into a directory that already has files in it, since that
+is not undoable. A bare `.git` directory is ignored, so
+`git init && bun create bakery .` works.
+
+## Notes
+
+- **Bun only** — the generated app depends on Bun APIs throughout.
+- This package has **no dependencies**, not even on Bakery. It writes files.
+
+## License
+
+MIT with the Commons Clause v1.0 — see [LICENSE](./LICENSE).
+
+**Not an OSI-approved licence.** The Commons Clause removes the right to *sell*
+the software — meaning to charge for a product or service whose value derives
+substantially from it, hosting and support included. Everything else the MIT
+licence grants is unchanged: use it, modify it, ship it inside your own product.
+If your organisation only permits OSI-approved dependencies, this will not pass
+that check.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "create-bakery",
+  "version": "1.0.0",
+  "description": "Scaffold a Bakery app: bun create bakery <directory>",
+  "keywords": [
+    "bakery",
+    "bun",
+    "create",
+    "scaffold",
+    "starter",
+    "template",
+    "boilerplate"
+  ],
+  "author": "obillekyle",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obillekyle/bakery.git",
+    "directory": "packages/create"
+  },
+  "homepage": "https://github.com/obillekyle/bakery#readme",
+  "bugs": "https://github.com/obillekyle/bakery/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "bin": {
+    "create-bakery": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./template": "./src/template.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/tests"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/index.ts

@@ -0,0 +1,359 @@
+#!/usr/bin/env bun
+
+import { mkdir, readdir, writeFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+import { confirm, isInteractive, multiselect } from './prompt'
+import {
+  dependencyRange,
+  isValidAppName,
+  PLUGIN_IDS,
+  type PluginId,
+  type TemplateFile,
+  templateFiles,
+} from './template'
+
+/**
+ * `bun create bakery <dir>`.
+ *
+ * `bun create x` fetches `create-x` and runs its bin with the remaining
+ * arguments, which is the whole reason this is a separate unscoped package
+ * rather than another verb on the `bakery` bin: `@bakery-framework/cli` owns that bin,
+ * and it is a dependency of the app you are trying to create.
+ *
+ * Deliberately dependency-free. `bun create` downloads this package on its own,
+ * so anything it depends on is a download the user waits through before seeing
+ * a single file — and the framework it scaffolds is the last thing it should
+ * drag along.
+ */
+
+const HELP = `bun create bakery <directory>
+
+Scaffold a Bakery app.
+
+Run it without --orm/--no-orm or --plugins and it asks, so long as you are at a
+terminal. Pass either and it stops asking about that one; pass --yes and it
+stops asking entirely.
+
+Arguments:
+  <directory>       Where to create it. Also the package name, unless --name
+                    is given. Use "." for the current directory.
+
+Options:
+  --name <name>     Package name, when it should differ from the directory.
+  --orm             Include the ORM: orm/, db:sync, @bakery-framework/orm.
+  --no-orm          Leave it out. The example API route keeps posts in memory.
+  --plugins <list>  Comma-separated, from: ${PLUGIN_IDS.join(', ')}.
+                    Use --plugins none for an explicit empty set.
+  --yes, -y         Take the defaults for anything not passed (ORM in, no
+                    plugins). What a non-interactive shell does anyway.
+  --no-install      Write the files and stop, without running bun install.
+  -h, --help        This.
+
+Examples:
+  bun create bakery my-app
+  bun create bakery my-app --no-orm --plugins vue
+  bun create bakery . --name my-app --plugins dashboard,analytics
+  bun create bakery my-app --yes
+`
+
+type Options = {
+  dir: string
+  name: string
+  install: boolean
+  /** `null` means "not specified" — ask, or fall back to the default. */
+  orm: boolean | null
+  plugins: PluginId[] | null
+  yes: boolean
+}
+
+/**
+ * Parse one `--plugins` value into the ids it names.
+ *
+ * Split out of `parseArgs` because it is the only flag that validates rather
+ * than assigns, and inlining it put the loop over the complexity limit — which
+ * is the rule doing its job: a `for` over argv should read as a dispatch table.
+ */
+function parsePlugins(
+  value: string,
+): { ok: true; plugins: PluginId[] } | { ok: false; message: string } {
+  // `none` rather than an empty string, so "I want no plugins" is something you
+  // can state — an empty `--plugins=` reads like a mistake and is treated as one
+  // by the caller, which rejects an empty value before reaching here.
+  if (value === 'none') return { ok: true, plugins: [] }
+
+  const requested = value
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean)
+
+  const unknown = requested.filter(p => !PLUGIN_IDS.includes(p as PluginId))
+  if (unknown.length) {
+    return {
+      ok: false,
+      message:
+        `Unknown plugin${unknown.length > 1 ? 's' : ''}: ` +
+        `${unknown.join(', ')}. Available: ${PLUGIN_IDS.join(', ')}.`,
+    }
+  }
+
+  // De-duplicated and put in a fixed order, so `--plugins dashboard,vue` and
+  // `--plugins vue,dashboard` generate byte-identical apps.
+  return { ok: true, plugins: PLUGIN_IDS.filter(id => requested.includes(id)) }
+}
+
+/**
+ * Parse argv into options, or return a message to print and exit on.
+ *
+ * Returns rather than throws for a *usage* problem: a bad flag is a thing the
+ * user typed, and answering it with a stack trace teaches nothing. Throwing is
+ * reserved for a failure of the scaffolding itself.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: argv dispatcher — one branch per flag
+export function parseArgs(
+  argv: string[],
+): { ok: true; options: Options } | { ok: false; message: string } {
+  let dir: string | null = null
+  let name: string | null = null
+  let install = true
+  let orm: boolean | null = null
+  let plugins: PluginId[] | null = null
+  let yes = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+
+    if (arg === '-h' || arg === '--help') return { ok: false, message: HELP }
+
+    if (arg === '--no-install') {
+      install = false
+      continue
+    }
+
+    if (arg === '--yes' || arg === '-y') {
+      yes = true
+      continue
+    }
+
+    if (arg === '--orm' || arg === '--no-orm') {
+      orm = arg === '--orm'
+      continue
+    }
+
+    if (arg === '--plugins' || arg.startsWith('--plugins=')) {
+      const value = arg.startsWith('--plugins=') ? arg.slice(10) : argv[++i]
+      if (!value) {
+        return {
+          ok: false,
+          message: `--plugins needs a value: ${PLUGIN_IDS.join(', ')}, or none.`,
+        }
+      }
+      const parsed = parsePlugins(value)
+      if (!parsed.ok) return parsed
+      plugins = parsed.plugins
+      continue
+    }
+
+    if (arg === '--name' || arg.startsWith('--name=')) {
+      const value = arg.startsWith('--name=') ? arg.slice(7) : argv[++i]
+      if (!value) return { ok: false, message: '--name needs a value.' }
+      name = value
+      continue
+    }
+
+    if (arg.startsWith('-')) {
+      return { ok: false, message: `Unknown option: ${arg}\n\n${HELP}` }
+    }
+
+    if (dir !== null) {
+      return { ok: false, message: `Unexpected argument: ${arg}\n\n${HELP}` }
+    }
+    dir = arg
+  }
+
+  if (dir === null) return { ok: false, message: HELP }
+
+  // `.` is the documented way to scaffold in place, and `basename(resolve('.'))`
+  // is the containing folder's name — which is the name the user means.
+  const resolved = resolve(dir)
+  const appName = name ?? basename(resolved)
+
+  if (!isValidAppName(appName)) {
+    return {
+      ok: false,
+      message:
+        `"${appName}" is not a usable package name: lowercase letters, ` +
+        'digits, dot, dash and underscore only, and it may not start with a ' +
+        'dot or a dash. Pass --name to choose a different one.',
+    }
+  }
+
+  return {
+    ok: true,
+    options: { dir: resolved, name: appName, install, orm, plugins, yes },
+  }
+}
+
+/**
+ * Fill in whatever the flags left unspecified.
+ *
+ * Asks only when there is a terminal on both ends and `--yes` was not passed.
+ * A pipe, a CI runner or a `--yes` takes the defaults — ORM in, no plugins —
+ * which is what `bun create bakery my-app` has always produced, so adding the
+ * prompts changed no existing invocation.
+ *
+ * Returns `null` when the user cancels, which is a distinct outcome from
+ * "chose nothing" and has to stay that way: Ctrl-C should not scaffold.
+ */
+export async function resolveChoices(
+  options: Options,
+): Promise<{ orm: boolean; plugins: PluginId[] } | null> {
+  const interactive = !options.yes && isInteractive()
+
+  let orm = options.orm
+  if (orm === null) {
+    if (!interactive) orm = true
+    else {
+      const answer = await confirm('Include the ORM?', true)
+      if (answer === null) return null
+      orm = answer
+    }
+  }
+
+  let plugins = options.plugins
+  if (plugins === null) {
+    if (!interactive) plugins = []
+    else {
+      const chosen = await multiselect('Plugins', [
+        { id: 'vue', label: 'vue', hint: 'single-file components' },
+        { id: 'analytics', label: 'analytics', hint: 'request metrics' },
+        { id: 'dashboard', label: 'dashboard', hint: 'admin console' },
+      ])
+      if (chosen === null) return null
+      plugins = PLUGIN_IDS.filter(id => chosen.includes(id))
+    }
+  }
+
+  return { orm, plugins }
+}
+
+/**
+ * True when `dir` does not exist, or exists and holds nothing that would be
+ * overwritten.
+ *
+ * Scaffolding is the one operation where "the directory already had something
+ * in it" is almost always a mistake, and it is not undoable — so this refuses
+ * rather than merges or prompts. `.git` and the editor droppings people
+ * routinely create a directory with are ignored, because refusing on those
+ * makes `git init && bun create bakery .` fail for no reason.
+ */
+export async function isScaffoldable(dir: string): Promise<boolean> {
+  const IGNORED = new Set(['.git', '.gitkeep', '.DS_Store', 'Thumbs.db'])
+
+  let entries: string[]
+  try {
+    entries = await readdir(dir)
+  } catch {
+    // Does not exist, which is the common case and the good one. A permission
+    // error also lands here and is caught properly by the write that follows —
+    // reporting it as "not empty" would be a worse message than the real one.
+    return true
+  }
+
+  return entries.every(entry => IGNORED.has(entry))
+}
+
+/** Write the template. Directories are created as needed. */
+export async function writeTemplate(
+  dir: string,
+  files: TemplateFile[],
+): Promise<void> {
+  for (const file of files) {
+    const target = resolve(dir, file.path)
+    await mkdir(resolve(target, '..'), { recursive: true })
+    await writeFile(target, file.contents)
+  }
+}
+
+/**
+ * This package's own version, which the generated dependency range follows.
+ *
+ * Exported only so a test can prove it still reads the right file: the relative
+ * URL breaks silently if this module moves, and the failure is a generated app
+ * pinned to the wrong major with every other test still green.
+ */
+export async function ownVersion(): Promise<string> {
+  const pkg = await Bun.file(new URL('../package.json', import.meta.url)).json()
+  return pkg.version
+}
+
+async function main(): Promise<number> {
+  const parsed = parseArgs(process.argv.slice(2))
+
+  if (!parsed.ok) {
+    // The only console use in this package, and the reason the framework's
+    // no-console rule scopes itself to server code: this is a CLI whose entire
+    // output is for a human at a terminal, with no logger to route it through.
+    console.log(parsed.message)
+    return parsed.message === HELP ? 0 : 1
+  }
+
+  const { dir, name, install } = parsed.options
+
+  // Checked before the prompts, not after: asking someone three questions and
+  // then refusing because the directory was never usable is the rudest possible
+  // ordering.
+  if (!(await isScaffoldable(dir))) {
+    console.log(
+      `${dir} already has files in it. Bakery will not scaffold over an ` +
+        'existing directory — pick an empty one, or empty this one first.',
+    )
+    return 1
+  }
+
+  const choices = await resolveChoices(parsed.options)
+  if (!choices) {
+    console.log('\nCancelled. Nothing was written.')
+    return 130
+  }
+
+  const files = templateFiles(
+    name,
+    dependencyRange(await ownVersion()),
+    choices,
+  )
+  await writeTemplate(dir, files)
+
+  const summary = [
+    choices.orm ? 'with the ORM' : 'without the ORM',
+    choices.plugins.length ? `plugins: ${choices.plugins.join(', ')}` : null,
+  ]
+    .filter(Boolean)
+    .join(', ')
+  console.log(`Created ${name} in ${dir} (${summary})`)
+
+  if (install) {
+    const proc = Bun.spawn(['bun', 'install'], {
+      cwd: dir,
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+    const code = await proc.exited
+    if (code !== 0) {
+      console.log(
+        '\nbun install failed. The app is written — run it again in ' +
+          `${dir} once the problem is fixed.`,
+      )
+      return code
+    }
+  }
+
+  const cd = dir === process.cwd() ? '' : `  cd ${basename(dir)}\n`
+  console.log(
+    `\nNext:\n\n${cd}${install ? '' : '  bun install\n'}` +
+      `${choices.orm ? '  bun run db:sync\n' : ''}  bun run dev\n`,
+  )
+
+  return 0
+}
+
+if (import.meta.main) process.exit(await main())

package/src/prompt.ts

@@ -0,0 +1,231 @@
+/**
+ * The interactive half of `bun create bakery`, written from scratch.
+ *
+ * Every prompt library worth using is a dependency, and this package declares
+ * **none** on purpose — `bun create` downloads it standalone, so anything it
+ * pulls in is a download the user waits through before seeing a single file.
+ * Two prompts is less code than justifying the exception.
+ *
+ * The key handling is separated from the terminal I/O for the same reason
+ * `template.ts` is separated from `index.ts`: a state machine can be tested
+ * exhaustively without a TTY, and the driver below is then thin enough to read
+ * in one sitting.
+ */
+
+const ESC = '\x1b'
+const KEY = {
+  up: `${ESC}[A`,
+  down: `${ESC}[B`,
+  enter: '\r',
+  enterLf: '\n',
+  space: ' ',
+  ctrlC: '\x03',
+  ctrlD: '\x04',
+} as const
+
+export type Choice = { id: string; label: string; hint?: string }
+
+export type MultiselectState = {
+  choices: Choice[]
+  cursor: number
+  selected: Set<string>
+}
+
+export type KeyResult =
+  | { kind: 'update'; state: MultiselectState }
+  | { kind: 'submit'; state: MultiselectState }
+  | { kind: 'cancel' }
+
+/**
+ * Apply one keypress to a multiselect.
+ *
+ * Pure, and it returns a *new* set rather than mutating: the renderer is called
+ * with the result, and a mutated set would make a stale render indistinguishable
+ * from a fresh one while debugging.
+ *
+ * The cursor wraps. `a` toggles everything, which is the shortcut people reach
+ * for when the answer is "all of them" and is cheaper to support than to
+ * explain the absence of.
+ */
+export function applyKey(state: MultiselectState, key: string): KeyResult {
+  if (key === KEY.ctrlC || key === KEY.ctrlD) return { kind: 'cancel' }
+
+  const total = state.choices.length
+  const next = (cursor: number, selected: Set<string>): KeyResult => ({
+    kind: 'update',
+    state: { ...state, cursor, selected },
+  })
+
+  if (key === KEY.up) {
+    return next((state.cursor - 1 + total) % total, state.selected)
+  }
+  if (key === KEY.down) {
+    return next((state.cursor + 1) % total, state.selected)
+  }
+  if (key === KEY.space) {
+    const selected = new Set(state.selected)
+    const id = state.choices[state.cursor]!.id
+    if (!selected.delete(id)) selected.add(id)
+    return next(state.cursor, selected)
+  }
+  if (key === 'a' || key === 'A') {
+    const all = state.selected.size === total
+    return next(
+      state.cursor,
+      all ? new Set() : new Set(state.choices.map(c => c.id)),
+    )
+  }
+  if (key === KEY.enter || key === KEY.enterLf) {
+    return { kind: 'submit', state }
+  }
+  return { kind: 'update', state }
+}
+
+/** Apply one keypress to a yes/no. `null` means "not answered yet". */
+export function applyConfirmKey(
+  key: string,
+  fallback: boolean,
+):
+  | { kind: 'answer'; value: boolean }
+  | { kind: 'cancel' }
+  | { kind: 'ignore' } {
+  if (key === KEY.ctrlC || key === KEY.ctrlD) return { kind: 'cancel' }
+  if (key === 'y' || key === 'Y') return { kind: 'answer', value: true }
+  if (key === 'n' || key === 'N') return { kind: 'answer', value: false }
+  if (key === KEY.enter || key === KEY.enterLf) {
+    return { kind: 'answer', value: fallback }
+  }
+  return { kind: 'ignore' }
+}
+
+const DIM = `${ESC}[2m`
+const CYAN = `${ESC}[36m`
+const GREEN = `${ESC}[32m`
+const RESET = `${ESC}[0m`
+
+export function renderMultiselect(
+  question: string,
+  state: MultiselectState,
+): string {
+  const lines = state.choices.map((choice, i) => {
+    const here = i === state.cursor
+    const box = state.selected.has(choice.id) ? `${GREEN}◉${RESET}` : '◯'
+    const pointer = here ? `${CYAN}❯${RESET}` : ' '
+    const label = here ? `${CYAN}${choice.label}${RESET}` : choice.label
+    const hint = choice.hint ? ` ${DIM}${choice.hint}${RESET}` : ''
+    return `${pointer} ${box} ${label}${hint}`
+  })
+
+  return (
+    `${GREEN}?${RESET} ${question}` +
+    ` ${DIM}(↑↓ move, space toggle, a all, enter confirm)${RESET}\n` +
+    `${lines.join('\n')}\n`
+  )
+}
+
+/** True when both ends of the terminal are real, which is what raw mode needs. */
+export function isInteractive(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+function write(text: string): void {
+  process.stdout.write(text)
+}
+
+/** Move the cursor up `n` lines and clear from there down. */
+function clearLines(n: number): void {
+  if (n > 0) write(`${ESC}[${n}A`)
+  write(`${ESC}[0J`)
+}
+
+async function* keypresses(): AsyncGenerator<string> {
+  process.stdin.setRawMode?.(true)
+  process.stdin.resume()
+  try {
+    for await (const chunk of process.stdin) {
+      // A single read can carry a whole escape sequence, and on a fast paste it
+      // can carry several keys at once. Arrow keys are the only multi-byte
+      // sequence handled, so they are matched first and the rest is yielded
+      // character by character.
+      const text = Buffer.from(chunk).toString('utf8')
+      let i = 0
+      while (i < text.length) {
+        if (text.startsWith(`${ESC}[`, i) && i + 2 < text.length) {
+          yield text.slice(i, i + 3)
+          i += 3
+          continue
+        }
+        yield text[i]!
+        i += 1
+      }
+    }
+  } finally {
+    process.stdin.setRawMode?.(false)
+    process.stdin.pause()
+  }
+}
+
+export async function confirm(
+  question: string,
+  fallback: boolean,
+): Promise<boolean | null> {
+  const suffix = fallback ? 'Y/n' : 'y/N'
+  write(`${GREEN}?${RESET} ${question} ${DIM}(${suffix})${RESET} `)
+
+  for await (const key of keypresses()) {
+    const result = applyConfirmKey(key, fallback)
+    if (result.kind === 'ignore') continue
+    if (result.kind === 'cancel') {
+      write('\n')
+      return null
+    }
+    write(`${CYAN}${result.value ? 'yes' : 'no'}${RESET}\n`)
+    return result.value
+  }
+  return null
+}
+
+/** Returns the chosen ids, or `null` if the user cancelled. */
+export async function multiselect(
+  question: string,
+  choices: Choice[],
+): Promise<string[] | null> {
+  let state: MultiselectState = { choices, cursor: 0, selected: new Set() }
+
+  let frame = renderMultiselect(question, state)
+  write(`${ESC}[?25l${frame}`) // hide the cursor while redrawing
+
+  try {
+    for await (const key of keypresses()) {
+      const result = applyKey(state, key)
+      if (result.kind === 'cancel') {
+        clearLines(frame.split('\n').length - 1)
+        return null
+      }
+
+      const previous = frame
+      state = result.state
+      frame = renderMultiselect(question, state)
+
+      if (result.kind === 'submit') {
+        clearLines(previous.split('\n').length - 1)
+        const names = state.choices
+          .filter(c => state.selected.has(c.id))
+          .map(c => c.label)
+        write(
+          `${GREEN}?${RESET} ${question} ` +
+            `${CYAN}${names.length ? names.join(', ') : 'none'}${RESET}\n`,
+        )
+        return state.choices
+          .filter(c => state.selected.has(c.id))
+          .map(c => c.id)
+      }
+
+      clearLines(previous.split('\n').length - 1)
+      write(frame)
+    }
+  } finally {
+    write(`${ESC}[?25h`) // always give the cursor back
+  }
+  return null
+}

package/src/template.ts

@@ -0,0 +1,474 @@
+/**
+ * The app `bun create bakery` writes, as data.
+ *
+ * Separated from the I/O in `index.ts` so the tests can assert on what gets
+ * written without a filesystem, and so the one interesting invariant is
+ * checkable: **every `@bakery-framework/*` specifier below resolves through an
+ * *enumerated* export, never the `"./*"` wildcard.** That wildcard is a
+ * deprecation ramp with one release to live (MONOREPO.md), so a template that
+ * leaned on it would generate apps that break on its removal — and it would
+ * break them silently, because the wildcard resolves fine today.
+ *
+ * Derived from `apps/starter`, which is the honest reference: written against
+ * public entry points only and booted in CI. The differences are the ones that
+ * have to differ — real dependency ranges instead of `workspace:*`, the
+ * `bakery` bin instead of a relative path into the repo, and a `.gitignore`.
+ */
+
+/** A file to write, relative to the target directory. */
+export type TemplateFile = {
+  path: string
+  contents: string
+}
+
+/** The plugins `--plugins` accepts, in the order they are registered. */
+export const PLUGIN_IDS = ['vue', 'analytics', 'dashboard'] as const
+export type PluginId = (typeof PLUGIN_IDS)[number]
+
+export type TemplateOptions = {
+  /** Generate `orm/` and depend on `@bakery-framework/orm`. */
+  orm: boolean
+  plugins: PluginId[]
+}
+
+/**
+ * What each plugin costs a generated app.
+ *
+ * `peers` matters and is easy to miss: `@bakery-framework/plugin-vue` declares `vue` and
+ * `@vue/compiler-sfc` as **peer** dependencies, so scaffolding the plugin
+ * without them produces an app that installs cleanly and then fails the first
+ * time it compiles an SFC. They go into the generated `dependencies`, because a
+ * scaffolded app is an application — it should pin what it needs rather than
+ * inherit an unmet peer warning.
+ */
+const PLUGINS: Record<
+  PluginId,
+  { pkg: string; import: string; call: string; peers?: Record<string, string> }
+> = {
+  vue: {
+    pkg: '@bakery-framework/plugin-vue',
+    import: 'vuePlugin',
+    call: 'vuePlugin()',
+    peers: { vue: '^3.5.0', '@vue/compiler-sfc': '^3.5.0' },
+  },
+  analytics: {
+    pkg: '@bakery-framework/plugin-analytics',
+    import: 'analyticsPlugin',
+    call: 'analyticsPlugin()',
+  },
+  dashboard: {
+    pkg: '@bakery-framework/plugin-dashboard',
+    import: 'dashboardPlugin',
+    // Deliberately no `authorize`. Omitted, the dashboard limits itself to
+    // loopback in development and denies in production, so a scaffolded app is
+    // never born with an open console. `apps/example` passes `() => true`
+    // because it is a local demo; a generated app is not.
+    call: 'dashboardPlugin()',
+  },
+}
+
+/**
+ * The version range the generated `package.json` asks for.
+ *
+ * Derived from this package's own version rather than written out, because the
+ * scaffolder is published in lockstep with the framework: `create-bakery@4.1.0`
+ * scaffolding `^4.0.0` is the drift this avoids. Caret, so a generated app
+ * picks up patches without regenerating.
+ */
+export function dependencyRange(ownVersion: string): string {
+  return `^${ownVersion}`
+}
+
+/**
+ * A valid npm package name, scoped or not.
+ *
+ * Stricter than npm on the parts that are worth being strict about — no
+ * uppercase, no leading dot or dash — because the generated `name` field is
+ * the only place this lands, and a name npm would reject surfaces as a
+ * confusing `bun install` failure several steps after the mistake.
+ *
+ * Scopes are accepted, and are reachable only through `--name`. The positional
+ * argument is a *directory path*, so `bun create bakery @co/app` means a nested
+ * directory whose basename is `app` — that is what a path argument means, and
+ * quietly treating it as a scoped package name instead would be a guess.
+ */
+export function isValidAppName(name: string): boolean {
+  const SEGMENT = '[a-z0-9][a-z0-9._-]*'
+  return (
+    new RegExp(`^(?:@${SEGMENT}/)?${SEGMENT}$`).test(name) && name.length <= 214
+  )
+}
+
+function serverConfig(plugins: PluginId[]): string {
+  const imports = plugins
+    .map(id => `import ${PLUGINS[id].import} from '${PLUGINS[id].pkg}'\n`)
+    .join('')
+
+  if (!plugins.length) {
+    return `import { defineConfig } from '@bakery-framework/core'
+
+export default defineConfig({
+  root: 'src',
+  port: 3000,
+})
+`
+  }
+
+  const calls = plugins.map(id => `    ${PLUGINS[id].call},\n`).join('')
+  const dashboardNote = plugins.includes('dashboard')
+    ? `  // The dashboard authenticates nobody itself — the app does, because it is\n` +
+      `  // the thing that knows who its users are. With no \`authorize\`, access is\n` +
+      `  // loopback-only in development and denied in production:\n` +
+      `  //\n` +
+      `  //   dashboardPlugin({ authorize: req => req.session.get('role') === 'admin' })\n`
+    : ''
+
+  return `import { defineConfig } from '@bakery-framework/core'
+${imports}
+export default defineConfig({
+  root: 'src',
+  port: 3000,
+${dashboardNote}  plugins: [
+${calls}  ],
+})
+`
+}
+
+const INDEX_PAGE = `export default function Home() {
+  return (
+    <html lang="en">
+      <head>
+        <title>{{name}}</title>
+      </head>
+      <body>
+        <h1>{{name}}</h1>
+        <p>Edit <code>src/index.tsx</code> and save — the page reloads itself.</p>
+        <p id="count">loading…</p>
+        <script src="/script.js" type="module"></script>
+      </body>
+    </html>
+  )
+}
+`
+
+const API_ROUTE = `import { defineRoute, response } from '@bakery-framework/core'
+import DB from '@bakery-framework/orm'
+
+// The type parameter declares the body's shape: body.title / body.slug /
+// body.body are strings below, while undeclared keys stay reachable. It states
+// the contract — it does not validate it. The body is still client input.
+export default defineRoute<{ title: string; slug: string; body: string }>(
+  async (req, body) => {
+    if (req.method === 'POST') {
+      await DB.Insert.into('posts')
+        .values({
+          authorId: 1,
+          title: body.title,
+          slug: body.slug,
+          body: body.body,
+        })
+        .run()
+      return response.json.success('created')
+    }
+
+    const posts = await DB.from('posts').selectAll('posts').array()
+    return response.json.success('ok', posts)
+  },
+)
+`
+
+/**
+ * The same route without a database.
+ *
+ * Kept to the same shape — `defineRoute`, a typed body, one JSON envelope, and
+ * `data` as an array — so the client script below is identical either way and
+ * the two templates do not drift into demonstrating different things.
+ */
+const API_ROUTE_NO_ORM = `import { defineRoute, response } from '@bakery-framework/core'
+
+// In memory, and therefore per process: a cluster (\`--threads N\`) gives each
+// worker its own copy. That is the point at which you want the ORM — scaffold
+// with it, or add @bakery-framework/orm later.
+const posts: { title: string }[] = []
+
+// The type parameter declares the body's shape. It states the contract — it
+// does not validate it. The body is still client input.
+export default defineRoute<{ title: string }>(async (req, body) => {
+  if (req.method === 'POST') {
+    posts.push({ title: body.title })
+    return response.json.success('created')
+  }
+
+  return response.json.success('ok', posts)
+})
+`
+
+const CLIENT_SCRIPT = `const res = await fetch('/api/notes')
+const json = await res.json()
+const el = document.getElementById('count')
+if (el) el.textContent = \`\${json.data?.length ?? 0} posts\`
+`
+
+const ORM_SCHEMA = `import { Field, table } from '@bakery-framework/orm'
+
+export const users = table('users', {
+  id: Field.Primary(),
+  username: Field.Varchar(64, null),
+  email: Field.Varchar(255, null),
+  createdAt: Field.Date.now(),
+})
+
+export const posts = table('posts', {
+  // The reference lives on the column it constrains, and is always an integer
+  // because Field.Primary() always is.
+  id: Field.Primary(),
+  authorId: Field.Foreign(users.id, { onDelete: 'CASCADE' }),
+  title: Field.Varchar(255, null),
+  slug: Field.Varchar(255, null),
+  // Sized because it has a default: MySQL refuses a literal DEFAULT on TEXT.
+  body: Field.Varchar(8192, ''),
+  published: Field.Int(0),
+  createdAt: Field.Date.now(),
+})
+`
+
+const ORM_INDEXES = `import { Field } from '@bakery-framework/orm'
+import { posts, users } from './tables'
+
+export const usernameUniq = Field.Unique(users.username)
+export const slugUniq = Field.Unique(posts.slug)
+export const postsByAuthor = Field.Index(posts.authorId)
+`
+
+/**
+ * The `declare module` block is the whole point of this file: it is what makes
+ * the ORM typed. Without it everything still runs and typechecks, the columns
+ * are just permissive `any` — which is a quiet enough failure that it is worth
+ * generating rather than documenting.
+ */
+
+const ORM_VIEWS = `import { view } from '@bakery-framework/orm'
+import { posts } from './tables'
+
+// A view is a stored SELECT the database treats as a read-only table. Borrowing
+// the source table's columns rather than restating them keeps the two in step.
+export const publishedPosts = view(
+  'published_posts',
+  posts,
+  'SELECT * FROM posts WHERE published = 1',
+)
+`
+
+const ORM_INDEX = `import type { InferOptionals, InferSchema, InferViews } from '@bakery-framework/orm'
+import * as tables from './tables'
+import * as views from './views'
+
+export * from './tables'
+export * from './views'
+export * from './indexes'
+
+// Tables *and* views: InferSchema reads both, and InferViews reads the views
+// specifically -- that is what stops DB.Insert.into() targeting one.
+type Model = typeof tables & typeof views
+
+declare module '@bakery-framework/orm/schema-registry' {
+  interface SchemaRegistry {
+    schema: {
+      DBSchema: InferSchema<Model>
+      DBOptionals: InferOptionals<Model>
+      Views: InferViews<Model>
+    }
+  }
+}
+`
+
+/**
+ * Schema sync as a script rather than a package script pointing into
+ * `node_modules`.
+ *
+ * `bakery --sync` is not this: it syncs and then *boots the server*, which is
+ * the wrong shape for a `db:sync` you run in a deploy step. The CLI's own
+ * standalone path is `import.meta.main` inside `@bakery-framework/orm/sync`, so this
+ * reproduces exactly what that guard does, through the enumerated export.
+ */
+const DB_SYNC_SCRIPT = `import { SyncService } from '@bakery-framework/orm/sync'
+
+await SyncService.run()
+process.exit(0)
+`
+
+function gitignore(orm: boolean): string {
+  // `bakery/` only exists once something opens a database, so an app scaffolded
+  // without the ORM does not get a rule for a directory it will never have.
+  const data = orm
+    ? '\n# `bakery/` holds server.db and backups/. Not tracked either, but do not\n' +
+      '# delete it: nothing regenerates what is in there.\nbakery/\n'
+    : ''
+
+  return `node_modules
+
+# Disposable — the framework deletes it wholesale on every version bump and
+# dev<->prod switch.
+.cache
+${data}`
+}
+
+function readme(name: string, orm: boolean, plugins: PluginId[]): string {
+  const sync = orm
+    ? 'bun run db:sync   # create the tables in orm/tables.ts\n'
+    : ''
+
+  const ormRows = orm
+    ? '| `orm/tables.ts` | Table definitions. Run `bun run db:sync` after editing. |\n' +
+      '| `orm/views.ts` | View definitions — stored SELECTs, read-only. |\n' +
+      "| `orm/index.ts` | Registers the schema with the ORM's types. Without its `declare module` block the ORM still works, untyped. |\n"
+    : ''
+
+  const pluginSection = plugins.length
+    ? `\n## Plugins\n\nRegistered in \`server.config.ts\`:\n\n` +
+      plugins.map(id => `- \`${PLUGINS[id].pkg}\``).join('\n') +
+      (plugins.includes('dashboard')
+        ? '\n\nThe dashboard is loopback-only in development and denied in production ' +
+          'until you give it an `authorize` predicate.'
+        : '') +
+      (plugins.includes('vue')
+        ? '\n\n`vue` and `@vue/compiler-sfc` are direct dependencies rather than ' +
+          'unmet peers, so `.vue` pages compile straight after install.'
+        : '') +
+      '\n'
+    : ''
+
+  const noOrm = orm
+    ? ''
+    : '\nScaffolded without the ORM. `src/api/notes.ts` keeps its posts in memory, ' +
+      'which is per process — add `@bakery-framework/orm` when you want them to outlive a ' +
+      'restart or survive `--threads`.\n'
+
+  return `# ${name}
+
+Built with [Bakery](https://github.com/obillekyle/bakery).
+
+\`\`\`bash
+bun install
+${sync}bun run dev
+\`\`\`
+
+Then open http://localhost:3000.
+${noOrm}
+## Layout
+
+| Path | What it is |
+| --- | --- |
+| \`src/\` | Served. Every file is a route — \`src/index.tsx\` is \`/\`, \`src/api/notes.ts\` is \`/api/notes\`. |
+${ormRows}| \`server.config.ts\` | Port, root directory, plugins. |
+${pluginSection}
+\`bun run start\` serves in production mode; add \`--threads N\` to fork a cluster.
+`
+}
+
+/**
+ * The three JSX options are repeated here on purpose, and removing them breaks
+ * every page in the generated app.
+ *
+ * `@bakery-framework/core/tsconfig.app.json` already sets them, and `tsc` picks them up
+ * from there — but **Bun's runtime does not follow `extends` into a package
+ * specifier**, only a relative path. So at runtime the app is transpiled with
+ * Bun's default automatic JSX runtime instead of Bakery's classic
+ * `createElement`, and every `.tsx` route fails with `Cannot find module
+ * 'react/jsx-dev-runtime'`. Typecheck stays clean throughout, which is what
+ * makes it nasty.
+ *
+ * `extends` still carries everything else, and is what `tsc` reads.
+ */
+function tsconfig(orm: boolean): string {
+  const include = [
+    '"src/**/*.ts"',
+    '"src/**/*.tsx"',
+    ...(orm ? ['"orm/**/*.ts"', '"scripts/**/*.ts"'] : []),
+    '"server.config.ts"',
+  ]
+    .map(entry => `    ${entry}`)
+    .join(',\n')
+
+  return `{
+  "$comment": "The three jsx* options are also set by @bakery-framework/core/tsconfig.app.json, and tsc reads them from there — but Bun's runtime does not follow 'extends' into a package specifier, only a relative path. Without them here, every .tsx page fails at runtime with \\"Cannot find module 'react/jsx-dev-runtime'\\" while typecheck stays clean. Keep them.",
+  "extends": "@bakery-framework/core/tsconfig.app.json",
+  "compilerOptions": {
+    "jsx": "react",
+    "jsxFactory": "createElement",
+    "jsxFragmentFactory": "Fragment"
+  },
+  "include": [
+${include}
+  ]
+}
+`
+}
+
+/**
+ * Build the file list for an app named `name`.
+ *
+ * `range` is threaded in rather than read from disk so this stays pure — the
+ * caller resolves it from the running package's own version.
+ */
+export function templateFiles(
+  name: string,
+  range: string,
+  options: TemplateOptions = { orm: true, plugins: [] },
+): TemplateFile[] {
+  const { orm, plugins } = options
+
+  const dependencies: Record<string, string> = {
+    '@bakery-framework/cli': range,
+    '@bakery-framework/core': range,
+  }
+  if (orm) dependencies['@bakery-framework/orm'] = range
+  for (const id of plugins) {
+    dependencies[PLUGINS[id].pkg] = range
+    Object.assign(dependencies, PLUGINS[id].peers ?? {})
+  }
+
+  const pkg = {
+    name,
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+    scripts: {
+      dev: 'bakery --dev',
+      start: 'bakery',
+      ...(orm ? { 'db:sync': 'bun run scripts/db-sync.ts' } : {}),
+    },
+    // Sorted, because the key order here is otherwise "whichever plugin was
+    // listed first", and a generated file that differs run to run is a diff
+    // nobody can read.
+    dependencies: Object.fromEntries(
+      Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b)),
+    ),
+  }
+
+  const files: TemplateFile[] = [
+    { path: 'package.json', contents: `${JSON.stringify(pkg, null, 2)}\n` },
+    { path: 'tsconfig.json', contents: tsconfig(orm) },
+    { path: '.gitignore', contents: gitignore(orm) },
+    { path: 'README.md', contents: readme(name, orm, plugins) },
+    { path: 'server.config.ts', contents: serverConfig(plugins) },
+    {
+      path: 'src/index.tsx',
+      contents: INDEX_PAGE.replaceAll('{{name}}', name),
+    },
+    { path: 'src/api/notes.ts', contents: orm ? API_ROUTE : API_ROUTE_NO_ORM },
+    { path: 'src/script.ts', contents: CLIENT_SCRIPT },
+  ]
+
+  if (orm) {
+    files.push(
+      { path: 'scripts/db-sync.ts', contents: DB_SYNC_SCRIPT },
+      { path: 'orm/tables.ts', contents: ORM_SCHEMA },
+      { path: 'orm/views.ts', contents: ORM_VIEWS },
+      { path: 'orm/indexes.ts', contents: ORM_INDEXES },
+      { path: 'orm/index.ts', contents: ORM_INDEX },
+    )
+  }
+
+  return files
+}