create-bakery 2.0.0-alpha.9 → 2.0.0-rc.1

package/README.md

@@ -25,7 +25,7 @@ bun run dev
 | `-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
+*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
@@ -34,16 +34,16 @@ is not undoable. A bare `.git` directory is ignored, so
 
 ## Notes
 
-- **Bun only** — the generated app depends on Bun APIs throughout.
+- **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).
+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
+**Not an OSI-approved license.** 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
+license grants is unchanged: use it, modify it, ship it inside your own product.
+If your organization only permits OSI-approved dependencies, this will not pass
 that check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bakery",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0-rc.1",
   "description": "Scaffold a Bakery app: bun create bakery <directory>",
   "keywords": [
     "bakery",
@@ -39,6 +39,6 @@
     "!src/tests"
   ],
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   }
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   dependencyRange,
   isValidAppName,
   PLUGIN_IDS,
+  PLUGINS_NEEDING_ORM,
   type PluginId,
   type TemplateFile,
   templateFiles,
@@ -22,7 +23,7 @@ import {
  *
  * 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
+ * a single file, and the framework it scaffolds is the last thing it should
  * drag along.
  */
 
@@ -60,7 +61,7 @@ type Options = {
   dir: string
   name: string
   install: boolean
-  /** `null` means "not specified" — ask, or fall back to the default. */
+  /** `null` means "not specified". Ask, or fall back to the default. */
   orm: boolean | null
   plugins: PluginId[] | null
   yes: boolean
@@ -70,14 +71,14 @@ type Options = {
  * 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
+ * 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
+  // 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: [] }
 
@@ -108,7 +109,7 @@ function parsePlugins(
  * 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
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: argv dispatcher, one branch per flag
 export function parseArgs(
   argv: string[],
 ): { ok: true; options: Options } | { ok: false; message: string } {
@@ -173,7 +174,7 @@ export function parseArgs(
   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.
+  // is the containing folder's name, which is the name the user means.
   const resolved = resolve(dir)
   const appName = name ?? basename(resolved)
 
@@ -197,8 +198,7 @@ export function parseArgs(
  * 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
+ * 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
@@ -227,12 +227,22 @@ export async function resolveChoices(
         { id: 'vue', label: 'vue', hint: 'single-file components' },
         { id: 'analytics', label: 'analytics', hint: 'request metrics' },
         { id: 'dashboard', label: 'dashboard', hint: 'admin console' },
+        { id: 'db-explorer', label: 'db-explorer', hint: 'browse and edit rows' },
       ])
       if (chosen === null) return null
       plugins = PLUGIN_IDS.filter(id => chosen.includes(id))
     }
   }
 
+  // The explorer browses and edits whatever the ORM is connected to, so
+  // scaffolding it without `orm/` produces an app whose headline feature has
+  // nothing to show. Turned on rather than refused: the two are asked for
+  // separately, and a generated app that boots is better than a prompt that
+  // argues with the answer it was just given.
+  if (!orm && plugins.some(id => PLUGINS_NEEDING_ORM.includes(id))) {
+    orm = true
+  }
+
   return { orm, plugins }
 }
 
@@ -241,7 +251,7 @@ export async function resolveChoices(
  * 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
+ * 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.
@@ -254,7 +264,7 @@ export async function isScaffoldable(dir: string): Promise<boolean> {
     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 —
+    // 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
   }
@@ -305,7 +315,7 @@ async function main(): Promise<number> {
   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.',
+        'existing directory. Pick an empty one, or empty this one first.',
     )
     return 1
   }
@@ -340,7 +350,7 @@ async function main(): Promise<number> {
     const code = await proc.exited
     if (code !== 0) {
       console.log(
-        '\nbun install failed. The app is written — run it again in ' +
+        '\nbun install failed. The app is written. Run it again in ' +
           `${dir} once the problem is fixed.`,
       )
       return code

package/src/prompt.ts

@@ -2,7 +2,7 @@
  * 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
+ * **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.
  *
@@ -185,7 +185,7 @@ export async function confirm(
   return null
 }
 
-/** Returns the chosen ids, or `null` if the user cancelled. */
+/** Returns the chosen ids, or `null` if the user canceled. */
 export async function multiselect(
   question: string,
   choices: Choice[],

package/src/template.ts

@@ -6,12 +6,12 @@
  * 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
+ * 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
+ * have to differ: real dependency ranges instead of `workspace:*`, the
  * `bakery` bin instead of a relative path into the repo, and a `.gitignore`.
  */
 
@@ -22,7 +22,12 @@ export type TemplateFile = {
 }
 
 /** The plugins `--plugins` accepts, in the order they are registered. */
-export const PLUGIN_IDS = ['vue', 'analytics', 'dashboard'] as const
+export const PLUGIN_IDS = [
+  'vue',
+  'analytics',
+  'dashboard',
+  'db-explorer',
+] as const
 export type PluginId = (typeof PLUGIN_IDS)[number]
 
 export type TemplateOptions = {
@@ -38,7 +43,7 @@ export type TemplateOptions = {
  * `@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
+ * scaffolded app is an application: it should pin what it needs rather than
  * inherit an unmet peer warning.
  */
 const PLUGINS: Record<
@@ -65,8 +70,32 @@ const PLUGINS: Record<
     // because it is a local demo; a generated app is not.
     call: 'dashboardPlugin()',
   },
+  'db-explorer': {
+    pkg: '@bakery-framework/plugin-db-explorer',
+    import: 'dbExplorerPlugin',
+    // Same rule as the dashboard and for a stronger reason: this one edits
+    // rows. With no `users` and no `authorize` the explorer allows loopback in
+    // development and denies in production, so a generated app is never born
+    // able to write to its database from a browser on the internet.
+    //
+    // It does not share the dashboard's door. Access here is a *level* per
+    // caller rather than a yes, which is why configuring one grants nothing in
+    // the other. See `docs/plugins/db-explorer.md`.
+    call: 'dbExplorerPlugin()',
+  },
 }
 
+/**
+ * Plugins that cannot work without the ORM.
+ *
+ * `db-explorer` browses and edits whatever the ORM is connected to, so
+ * scaffolding it without `orm/` produces an app whose headline feature has
+ * nothing to show. The scaffolder turns the ORM on rather than refusing: the
+ * two are asked for separately and a generated app that boots is better than
+ * a prompt that argues.
+ */
+export const PLUGINS_NEEDING_ORM: readonly PluginId[] = ['db-explorer']
+
 /**
  * The version range the generated `package.json` asks for.
  *
@@ -82,14 +111,14 @@ export function dependencyRange(ownVersion: string): string {
 /**
  * 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
+ * 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
+ * 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 {
@@ -116,7 +145,7 @@ export default defineConfig({
 
   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 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` +
@@ -142,7 +171,7 @@ const INDEX_PAGE = `export default function Home() {
       </head>
       <body>
         <h1>{{name}}</h1>
-        <p>Edit <code>src/index.tsx</code> and save — the page reloads itself.</p>
+        <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>
@@ -162,12 +191,12 @@ import DB from '@bakery-framework/orm'
 //
 //   export default defineRoute({ body: mySchema }, async (req, body) => …)
 //
-// The body option takes a Standard Schema (zod, valibot, arktype — Bakery
+// The body option takes a Standard Schema (zod, valibot, arktype, Bakery
 // bundles none of them), or a plain function returning the parsed value or
 // throwing. A rejection answers 400 through the same JSON envelope as
 // everything else.
 // posts.authorId is a foreign key into users, so a post cannot be inserted
-// before its author exists — the database refuses a dangling id, which is the
+// before its author exists: the database refuses a dangling id, which is the
 // entire point of the constraint. A real app takes the author from the session;
 // this creates one on demand so the route works on a freshly synced database.
 async function authorId(): Promise<number> {
@@ -203,14 +232,14 @@ export default defineRoute<{ title: string; slug: string; body: string }>(
 /**
  * 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
+ * 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
+// 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 }[] = []
 
@@ -266,7 +295,7 @@ 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
+ * are just permissive `any`, which is a quiet enough failure that it is worth
  * generating rather than documenting.
  */
 
@@ -330,7 +359,7 @@ function gitignore(orm: boolean): string {
 
   return `node_modules
 
-# Disposable — the framework deletes it wholesale on every version bump and
+# Disposable: the framework deletes it wholesale on every version bump and
 # dev<->prod switch.
 .cache
 ${data}`
@@ -343,7 +372,7 @@ function readme(name: string, orm: boolean, plugins: PluginId[]): string {
 
   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/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"
     : ''
 
@@ -354,6 +383,11 @@ function readme(name: string, orm: boolean, plugins: PluginId[]): string {
         ? '\n\nThe dashboard is loopback-only in development and denied in production ' +
           'until you give it an `authorize` predicate.'
         : '') +
+      (plugins.includes('db-explorer')
+        ? '\n\nThe database explorer is served at `/_db` and follows the same rule, ' +
+          'with its own access model: a level per caller rather than a yes. ' +
+          'Configuring the dashboard grants nothing there.'
+        : '') +
       (plugins.includes('vue')
         ? '\n\n`vue` and `@vue/compiler-sfc` are direct dependencies rather than ' +
           'unmet peers, so `.vue` pages compile straight after install.'
@@ -364,7 +398,7 @@ function readme(name: string, orm: boolean, plugins: PluginId[]): string {
   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 ' +
+      'which is per process. Add `@bakery-framework/orm` when you want them to outlive a ' +
       'restart or survive `--threads`.\n'
 
   return `# ${name}
@@ -382,7 +416,7 @@ ${noOrm}
 
 | Path | What it is |
 | --- | --- |
-| \`src/\` | Served. Every file is a route — \`src/index.tsx\` is \`/\`, \`src/api/notes.ts\` is \`/api/notes\`. |
+| \`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.
@@ -394,7 +428,7 @@ ${pluginSection}
  * every page in the generated app.
  *
  * `@bakery-framework/core/tsconfig.server.json` already sets them, and `tsc` picks them up
- * from there — but **Bun's runtime does not follow `extends` into a package
+ * 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
@@ -414,7 +448,7 @@ function tsconfig(orm: boolean): string {
     .join(',\n')
 
   return `{
-  "$comment": "The three jsx* options are also set by @bakery-framework/core/tsconfig.server.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.",
+  "$comment": "The three jsx* options are also set by @bakery-framework/core/tsconfig.server.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.server.json",
   "compilerOptions": {
     "jsx": "react",
@@ -431,7 +465,7 @@ ${include}
 /**
  * Build the file list for an app named `name`.
  *
- * `range` is threaded in rather than read from disk so this stays pure — the
+ * `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(
@@ -460,7 +494,16 @@ export function templateFiles(
       dev: 'bakery --dev',
       start: 'bakery',
       typecheck: 'tsc --noEmit',
-      ...(orm ? { 'db:sync': 'bun run scripts/db-sync.ts' } : {}),
+      ...(orm
+        ? {
+            'db:sync': 'bun run scripts/db-sync.ts',
+            // The codegen entry point: write the schema *from* the database,
+            // touching no tables. `--migrate` is the sync engine's adoption
+            // flag; naming it here is what makes generation discoverable as a
+            // command rather than folklore about a flag.
+            'db:codegen': 'bun run scripts/db-sync.ts --migrate',
+          }
+        : {}),
     },
     // 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
@@ -470,21 +513,21 @@ export function templateFiles(
     ),
     // `bun-types` is not optional, and its absence is invisible until you run
     // tsc. `@bakery-framework/core/tsconfig.server.json` sets
-    // `"types": ["bun-types"]` — it has to, that is what makes `Bun.*` a type
-    // error in browser code — but core declares no dependencies at all, so
+    // `"types": ["bun-types"]`. It has to, that is what makes `Bun.*` a type
+    // error in browser code, but core declares no dependencies at all, so
     // nothing installs the package the setting names. In this repo it resolves
     // from a *root* devDependency, which is why the gap was invisible from
     // inside the workspace: a generated app typechecked here and died with
     // `TS2688: Cannot find type definition file for 'bun-types'` anywhere else.
     //
-    // An app owning its own toolchain is the right shape regardless — the
+    // An app owning its own toolchain is the right shape regardless: the
     // alternative is core taking a dependency, and having none is a property
     // worth more than this convenience.
     devDependencies: {
-      'bun-types': '^1.3.14',
+      'bun-types': '^1.4.0',
       // **`^5`, not `^7`, and the reason is `vue-tsc`.** TypeScript 7 is the
       // native port and does not ship `typescript/lib/tsc`, which `vue-tsc`
-      // requires to patch — so a Vue app that installs TS 7 gets
+      // requires to patch, so a Vue app that installs TS 7 gets
       // `Cannot find module 'typescript/lib/tsc'` the first time it typechecks
       // an SFC. Measured on a real app: 7.0.2 crashes, 5.9.3 runs.
       //