@beechcms/cms 0.4.0-preview.12 → 0.4.0-preview.13

package/README.md

@@ -1,107 +1,107 @@
-![beechLogoDark.png](docs/images/beechLogoDark.png)
-
-**BeechCMS** is a precision-engineered, solo-developer headless CMS built for developers who deliver high-performance websites for clients with **zero infrastructure overhead**.
-
-The pitch is simple: you build the site, you hand it over, and your client can manage their own content forever — with **zero hosting costs**. No monthly subscriptions, no server bills, no maintenance contract needed just to keep the lights on.
-
-This is possible because BeechCMS runs entirely on **Cloudflare's free tier** — Workers for the API, D1 (SQLite at the edge) for the database, and R2 for media storage. A Cloudflare account is all the infrastructure a client ever needs.
-
----
-
-## Why Beech?
-
-### Zero running costs for your clients
-
-Cloudflare's free tier covers D1, R2, and Workers for the vast majority of real-world content sites. You deliver a fully self-managed product — dashboard, API, media uploads — and the client pays nothing to keep it running. That's a compelling offer.
-
-### Native SQL Performance
-Unlike other "flexible" CMSs that store data in slow JSON blobs, Beech generates **dedicated SQL tables** for every content type. Enjoy native B-Tree indexing, `REAL` and `INTEGER` types for mathematical operations, and ultra-fast queries.
-
-### Schema-as-Code
-Define your content model once in TypeScript. The **Botanical Engine** compiles your definitions into deterministic SQL DDL. Run `beech seed:load` and your database schema is automatically synchronized. No manual migrations, no manual SQL, no schema drift.
-
-### Works as a dependency, not a boilerplate
-
-Your project is four files. The BeechCMS engine, dashboard, and API live inside `node_modules/@beechcms/api`. Update with `npm update @beechcms/api`.
-
----
-
-## Getting Started
-
-```bash
-npx @beechcms/cms
-```
-
-The interactive wizard scaffolds a ready-to-use project in seconds. For everything from configuration to deployment, see the **[Developer Guide](./docs/guide.md)**.
-
----
-
-## The Botanical Engine
-
-The heart of BeechCMS is the **Botanical Engine**, a high-performance **Schema Compiler** that bridges the gap between TypeScript definitions and SQL infrastructure.
-
-Instead of generic document storage, the Engine analyzes your **Seeds** (content types) and compiles them into **dedicated SQL tables** within Cloudflare D1. Every field you define becomes a native, type-safe SQL column, allowing for:
-
-- **Native Performance**: Real B-Tree indices and FTS5 virtual tables for ultra-fast filtering and full-text search.
-- **Data Integrity**: Native SQL types (REAL, INTEGER, TEXT) with CHECK constraints for robust data handling.
-- **Zero-Manual SQL**: Deterministic DDL generation—I define the schema in code, and the Engine handles the database synchronization.
-
----
-
-## Tech Stack
-
-| Layer | Technology |
-|---|---|
-| Edge runtime | Cloudflare Workers (V8 Isolates) |
-| API framework | Hono v4 |
-| Database | Cloudflare D1 (SQLite at the edge) |
-| Object storage | Cloudflare R2 (zero egress cost) |
-| Shared logic | `@beechcms/core` — Botanical Engine, types, validation |
-| Dashboard | React 19 + Vite 7 |
-| UI | Tailwind CSS v4 + Shadcn/ui |
-| Server state | TanStack Query v5 |
-| Rich text | TipTap v3 + KaTeX |
-| Auth | `jose` JWT + bcryptjs |
-| Validation | Zod v4 |
-| Testing | Vitest v3 |
-| Build orchestration | Turborepo v2 |
-
-
----
-## Documentation
-
-| Document | Description |
-|---|---|
-| [Developer Guide](./docs/guide.md) | End-to-end guide: scaffolding, seeds, API consumption, deployment |
-| [Architecture](./docs/nuovidocs/architecture.md) | Monorepo topology, Botanical Engine data flow, D1 model |
-| [API Reference](./docs/nuovidocs/api-reference.md) | Auth, Content CRUD, Media Engine, Public API, rate limiting |
-| [Frontend Guide](./docs/nuovidocs/frontend-guide.md) | FieldRenderer registry, TanStack Query patterns, adding field types |
-| [System Map](./docs/SYSTEM_MAP.md) | Folder structure, conventions, and architectural constraints |
-
----
-# Faq about BeechCMS
-## Why "Beech"?
-
-One afternoon I was staring at half a CMS with no name. I'd spent weeks building my desk setup — monitors, peripherals, the works — and the last thing I added was a beech wood desktop. I cut it, shaped it, sanded it, finished it until it was exactly right.
-
-I was sitting at that desk trying to think of a name, looked to the side, and saw the wood. Beech. And then it clicked — seeds, branches, the forest, the fruit. The whole metaphor was already there in the project: content types are seeds, fields are branches, the data that grows from them is the fruit. The name took about three seconds.
-
-Sometimes the best names aren't invented. They're found.
-
-## Why I Built This
-
-In 2025 I lost a €2,000 contract for a React showcase site for a construction company. The client needed two things beyond a static site: a blog where they could post photos of new builds, and a contact form. Simple requests — but they turned the project into a problem.
-
-The tools that existed were either too heavy (WordPress, which the client had already had a bad experience with), too expensive once you added hosting and a managed database, or simply not designed to work alongside a modern React frontend without standing up a dedicated backend. The monthly running costs pushed my quote above what a larger agency — one that already had its own internal tooling — could offer. I lost the contract.
-
-That was the moment I understood the real gap. Small agencies and freelancers don't lose on talent or quality. They lose because they don't have the same leverage as larger competitors who've already amortized the cost of building their own CMS. I decided to build mine.
-
-**Why Cloudflare?** I was already looking for an alternative to Vercel that didn't require a paid plan for commercial projects. When I discovered that Cloudflare's free tier included not just Workers but also D1 (a relational database at the edge) and R2 (S3-compatible object storage), the whole architecture became clear. A full CMS backend — API, database, media storage, auth — with zero monthly cost for the client.
-
-**Why the Botanical Engine?** I built the Botanical Engine as a high-performance **Schema Compiler**. It bridges the gap between the flexibility of a CMS and the power of a relational database. Instead of storing data in generic blobs, it compiles TypeScript definitions into native SQL tables and columns. This ensures rigid data integrity (crucial for things like financial records) and unlocks massive performance gains by leveraging native D1 indexing. This true relational model maintains the simplicity of "Schema-as-Code" while allowing for advanced features like cross-seed relations and complex aggregations.
-
-**What I learned building it.** BeechCMS is my first serious serverless project. I had no prior experience with Cloudflare Workers, edge computing, or D1. Everything I know about this stack I learned by building this — reading documentation, hitting limits, understanding why they exist, and finding the right abstractions. The project is currently in active development toward a public 1.0 release and is already available on npm.
-
----
-
-_BeechCMS — Precision-engineered content infrastructure for the edge._
+![beechLogoDark.png](docs/images/beechLogoDark.png)
+
+**BeechCMS** is a precision-engineered, solo-developer headless CMS built for developers who deliver high-performance websites for clients with **zero infrastructure overhead**.
+
+The pitch is simple: you build the site, you hand it over, and your client can manage their own content forever — with **zero hosting costs**. No monthly subscriptions, no server bills, no maintenance contract needed just to keep the lights on.
+
+This is possible because BeechCMS runs entirely on **Cloudflare's free tier** — Workers for the API, D1 (SQLite at the edge) for the database, and R2 for media storage. A Cloudflare account is all the infrastructure a client ever needs.
+
+---
+
+## Why Beech?
+
+### Zero running costs for your clients
+
+Cloudflare's free tier covers D1, R2, and Workers for the vast majority of real-world content sites. You deliver a fully self-managed product — dashboard, API, media uploads — and the client pays nothing to keep it running. That's a compelling offer.
+
+### Native SQL Performance
+Unlike other "flexible" CMSs that store data in slow JSON blobs, Beech generates **dedicated SQL tables** for every content type. Enjoy native B-Tree indexing, `REAL` and `INTEGER` types for mathematical operations, and ultra-fast queries.
+
+### Schema-as-Code
+Define your content model once in TypeScript. The **Botanical Engine** compiles your definitions into deterministic SQL DDL. Run `beech seed:load` and your database schema is automatically synchronized. No manual migrations, no manual SQL, no schema drift.
+
+### Works as a dependency, not a boilerplate
+
+Your project is four files. The BeechCMS engine, dashboard, and API live inside `node_modules/@beechcms/api`. Update with `npm update @beechcms/api`.
+
+---
+
+## Getting Started
+
+```bash
+npx @beechcms/cms
+```
+
+The interactive wizard scaffolds a ready-to-use project in seconds. For everything from configuration to deployment, see the **[Developer Guide](./docs/guide.md)**.
+
+---
+
+## The Botanical Engine
+
+The heart of BeechCMS is the **Botanical Engine**, a high-performance **Schema Compiler** that bridges the gap between TypeScript definitions and SQL infrastructure.
+
+Instead of generic document storage, the Engine analyzes your **Seeds** (content types) and compiles them into **dedicated SQL tables** within Cloudflare D1. Every field you define becomes a native, type-safe SQL column, allowing for:
+
+- **Native Performance**: Real B-Tree indices and FTS5 virtual tables for ultra-fast filtering and full-text search.
+- **Data Integrity**: Native SQL types (REAL, INTEGER, TEXT) with CHECK constraints for robust data handling.
+- **Zero-Manual SQL**: Deterministic DDL generation—I define the schema in code, and the Engine handles the database synchronization.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Edge runtime | Cloudflare Workers (V8 Isolates) |
+| API framework | Hono v4 |
+| Database | Cloudflare D1 (SQLite at the edge) |
+| Object storage | Cloudflare R2 (zero egress cost) |
+| Shared logic | `@beechcms/core` — Botanical Engine, types, validation |
+| Dashboard | React 19 + Vite 7 |
+| UI | Tailwind CSS v4 + Shadcn/ui |
+| Server state | TanStack Query v5 |
+| Rich text | TipTap v3 + KaTeX |
+| Auth | `jose` JWT + bcryptjs |
+| Validation | Zod v4 |
+| Testing | Vitest v3 |
+| Build orchestration | Turborepo v2 |
+
+
+---
+## Documentation
+
+| Document | Description |
+|---|---|
+| [Developer Guide](./docs/guide.md) | End-to-end guide: scaffolding, seeds, API consumption, deployment |
+| [Architecture](./docs/nuovidocs/architecture.md) | Monorepo topology, Botanical Engine data flow, D1 model |
+| [API Reference](./docs/nuovidocs/api-reference.md) | Auth, Content CRUD, Media Engine, Public API, rate limiting |
+| [Frontend Guide](./docs/nuovidocs/frontend-guide.md) | FieldRenderer registry, TanStack Query patterns, adding field types |
+| [System Map](./docs/SYSTEM_MAP.md) | Folder structure, conventions, and architectural constraints |
+
+---
+# Faq about BeechCMS
+## Why "Beech"?
+
+One afternoon I was staring at half a CMS with no name. I'd spent weeks building my desk setup — monitors, peripherals, the works — and the last thing I added was a beech wood desktop. I cut it, shaped it, sanded it, finished it until it was exactly right.
+
+I was sitting at that desk trying to think of a name, looked to the side, and saw the wood. Beech. And then it clicked — seeds, branches, the forest, the fruit. The whole metaphor was already there in the project: content types are seeds, fields are branches, the data that grows from them is the fruit. The name took about three seconds.
+
+Sometimes the best names aren't invented. They're found.
+
+## Why I Built This
+
+In 2025 I lost a €2,000 contract for a React showcase site for a construction company. The client needed two things beyond a static site: a blog where they could post photos of new builds, and a contact form. Simple requests — but they turned the project into a problem.
+
+The tools that existed were either too heavy (WordPress, which the client had already had a bad experience with), too expensive once you added hosting and a managed database, or simply not designed to work alongside a modern React frontend without standing up a dedicated backend. The monthly running costs pushed my quote above what a larger agency — one that already had its own internal tooling — could offer. I lost the contract.
+
+That was the moment I understood the real gap. Small agencies and freelancers don't lose on talent or quality. They lose because they don't have the same leverage as larger competitors who've already amortized the cost of building their own CMS. I decided to build mine.
+
+**Why Cloudflare?** I was already looking for an alternative to Vercel that didn't require a paid plan for commercial projects. When I discovered that Cloudflare's free tier included not just Workers but also D1 (a relational database at the edge) and R2 (S3-compatible object storage), the whole architecture became clear. A full CMS backend — API, database, media storage, auth — with zero monthly cost for the client.
+
+**Why the Botanical Engine?** I built the Botanical Engine as a high-performance **Schema Compiler**. It bridges the gap between the flexibility of a CMS and the power of a relational database. Instead of storing data in generic blobs, it compiles TypeScript definitions into native SQL tables and columns. This ensures rigid data integrity (crucial for things like financial records) and unlocks massive performance gains by leveraging native D1 indexing. This true relational model maintains the simplicity of "Schema-as-Code" while allowing for advanced features like cross-seed relations and complex aggregations.
+
+**What I learned building it.** BeechCMS is my first serious serverless project. I had no prior experience with Cloudflare Workers, edge computing, or D1. Everything I know about this stack I learned by building this — reading documentation, hitting limits, understanding why they exist, and finding the right abstractions. The project is currently in active development toward a public 1.0 release and is already available on npm.
+
+---
+
+_BeechCMS — Precision-engineered content infrastructure for the edge._

package/bin/cli.mjs

@@ -1,129 +1,188 @@
-#!/usr/bin/env node
-// @ts-check
-
-import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-
-const [,, command, ...args] = process.argv
-
-const COMMANDS = {
-  build:        cmdBuild,
-  'seed:load':  cmdSeedLoad,
-}
-
-function help() {
-  console.log(`
-  beech <command> [options]
-
-  Commands:
-    build           Rebuild @beechcms/core after editing seeds.ts
-    seed:load       Create/update DB tables from SEED_REGISTRY
-      --dry-run       Print SQL without executing
-      --diff          Show schema differences vs current DB
-      --remote        Execute against remote D1 (default: local)
-      --db <name>     Override D1 database name
-
-  Run npx @beechcms/cms to scaffold a new project.
-`)
-}
-
-function cmdBuild() {
-  console.log(
-    '\nNo build step needed for BeechCMS projects.\n' +
-    'Edit seeds.ts then run `npx beech seed:load` to sync schema changes to D1.\n'
-  )
-}
-
-async function tryLoadLocalRegistry() {
-  const cwd = process.cwd()
-
-  // Try compiled JS first (root or apps/api)
-  const searchDirs = [cwd, resolve(cwd, 'apps', 'api')]
-  for (const dir of searchDirs) {
-    for (const name of ['seeds.js', 'seeds.mjs', 'seed.js', 'seed.mjs']) {
-      const p = resolve(dir, name)
-      if (existsSync(p)) {
-        try {
-          const mod = await import(pathToFileURL(p).href)
-          if (mod.SEED_REGISTRY && typeof mod.SEED_REGISTRY === 'object') {
-            return mod.SEED_REGISTRY
-          }
-          if (Array.isArray(mod.seeds)) {
-            return Object.fromEntries(mod.seeds.map(s => [s.slug, s]))
-          }
-          if (Array.isArray(mod.default)) {
-            return Object.fromEntries(mod.default.map(s => [s.slug, s]))
-          }
-        } catch {}
-      }
-    }
-  }
-
-  // Try seeds.ts / seed.ts (root or apps/api)
-  let tsPath = null
-  for (const dir of searchDirs) {
-    const p = existsSync(resolve(dir, 'seeds.ts')) 
-      ? resolve(dir, 'seeds.ts') 
-      : resolve(dir, 'seed.ts')
-    if (existsSync(p)) {
-      tsPath = p
-      break
-    }
-  }
-
-  if (tsPath) {
-    const result = spawnSync(process.execPath, [
-      '--experimental-strip-types',
-      '--input-type=module',
-      '--eval',
-      `
-import * as mod from ${JSON.stringify(pathToFileURL(tsPath).href)};
-let out = null;
-if (mod.SEED_REGISTRY && typeof mod.SEED_REGISTRY === 'object') out = mod.SEED_REGISTRY;
-else if (Array.isArray(mod.seeds)) out = Object.fromEntries(mod.seeds.map(s => [s.slug, s]));
-else if (Array.isArray(mod.default)) out = Object.fromEntries(mod.default.map(s => [s.slug, s]));
-if (out) process.stdout.write(JSON.stringify(out));
-      `.trim(),
-    ], { encoding: 'utf-8' })
-    
-    if (result.status === 0 && result.stdout) {
-      try { return JSON.parse(result.stdout) } catch (err) {
-        console.error('  Failed to parse seeds.ts output:', err)
-      }
-    } else if (result.status !== 0) {
-      console.error('  Error loading seeds.ts:')
-      console.error(result.stderr || result.stdout || 'Unknown error')
-      if (process.version.slice(1).split('.')[0] < 22) {
-        console.warn('  Note: Node.js 22.6+ is required to load .ts files directly. Current version:', process.version)
-      }
-    }
-  }
-
-  return null
-}
-
-async function cmdSeedLoad(args) {
-  const dryRun = args.includes('--dry-run')
-  const diff   = args.includes('--diff')
-  const remote = args.includes('--remote')
-  const dbIdx  = args.indexOf('--db')
-  const db     = dbIdx !== -1 ? args[dbIdx + 1] : undefined
-
-  const registry = await tryLoadLocalRegistry()
-
-  const { seedLoad } = await import('@beechcms/cli')
-  await seedLoad({ dryRun, diff, local: !remote, db, registry })
-}
-
-const handler = COMMANDS[command]
-if (!handler) {
-  help()
-  if (command) process.exit(1)
-} else if (args.includes('--help') || args.includes('-h')) {
-  help()
-} else {
-  await handler(args)
-}
+#!/usr/bin/env node
+// @ts-check
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+
+const [,, command, ...args] = process.argv
+
+const COMMANDS = {
+  build:          cmdBuild,
+  'seed:load':    cmdSeedLoad,
+  'seed:create':  cmdSeedCreate,
+  'init':         cmdInit,
+  'validate':     cmdValidate,
+  'deploy':       cmdDeploy,
+}
+
+function help() {
+  console.log(`
+  beech <command> [options]
+
+  Commands:
+    init            Check project files and optionally initialise the database
+      --db            Also initialise the D1 database (system tables)
+      --remote        Target remote D1 instead of local (default: local)
+      --db-name <n>   Override D1 database name
+
+    build           Rebuild @beechcms/core after editing seeds.ts
+
+    validate        Validate SEED_REGISTRY for common errors (duplicate aliases,
+                    missing displayNameAlias, duplicate slugs). Exit code 1 on errors.
+
+    seed:load       Create/update content tables from SEED_REGISTRY
+      --dry-run       Print SQL without executing
+      --diff          Show schema differences vs current DB
+      --remote        Execute against remote D1 (default: local)
+      --db <name>     Override D1 database name
+
+    seed:create     Interactive wizard — generate a new Seed definition and append
+                    it to seeds.ts, including SEED_REGISTRY entry
+
+    deploy          Deploy Worker, sync remote schema, and verify /admin
+      --skip-seed     Skip remote seed:load step
+      --skip-check    Skip /admin reachability check
+
+  Scaffold a new project (interactive, or pass --yes for non-interactive defaults):
+    npm create @beechcms/cms [project-name] [--yes] [--with-examples]
+
+  Golden path (local):
+    npx beech init --db --local
+    npx beech seed:load --local
+    npx wrangler dev
+
+  Golden path (deploy):
+    npx beech deploy
+    npx beech init --db --remote   # verify remote DB post-deploy
+`)
+}
+
+function cmdBuild() {
+  console.log(
+    '\nNo build step needed for BeechCMS projects.\n' +
+    'Edit seeds.ts then run `npx beech seed:load` to sync schema changes to D1.\n'
+  )
+}
+
+async function tryLoadLocalRegistry() {
+  const cwd = process.cwd()
+
+  // Try compiled JS first (root or apps/api)
+  const searchDirs = [cwd, resolve(cwd, 'apps', 'api')]
+  for (const dir of searchDirs) {
+    for (const name of ['seeds.js', 'seeds.mjs', 'seed.js', 'seed.mjs']) {
+      const p = resolve(dir, name)
+      if (existsSync(p)) {
+        try {
+          const mod = await import(pathToFileURL(p).href)
+          if (mod.SEED_REGISTRY && typeof mod.SEED_REGISTRY === 'object') {
+            return mod.SEED_REGISTRY
+          }
+          if (Array.isArray(mod.seeds)) {
+            return Object.fromEntries(mod.seeds.map(s => [s.slug, s]))
+          }
+          if (Array.isArray(mod.default)) {
+            return Object.fromEntries(mod.default.map(s => [s.slug, s]))
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // Try seeds.ts / seed.ts (root or apps/api)
+  let tsPath = null
+  for (const dir of searchDirs) {
+    const p = existsSync(resolve(dir, 'seeds.ts')) 
+      ? resolve(dir, 'seeds.ts') 
+      : resolve(dir, 'seed.ts')
+    if (existsSync(p)) {
+      tsPath = p
+      break
+    }
+  }
+
+  if (tsPath) {
+    const result = spawnSync(process.execPath, [
+      '--experimental-strip-types',
+      '--input-type=module',
+      '--eval',
+      `
+import * as mod from ${JSON.stringify(pathToFileURL(tsPath).href)};
+let out = null;
+if (mod.SEED_REGISTRY && typeof mod.SEED_REGISTRY === 'object') out = mod.SEED_REGISTRY;
+else if (Array.isArray(mod.seeds)) out = Object.fromEntries(mod.seeds.map(s => [s.slug, s]));
+else if (Array.isArray(mod.default)) out = Object.fromEntries(mod.default.map(s => [s.slug, s]));
+if (out) process.stdout.write(JSON.stringify(out));
+      `.trim(),
+    ], { encoding: 'utf-8' })
+    
+    if (result.status === 0 && result.stdout) {
+      try { return JSON.parse(result.stdout) } catch (err) {
+        console.error('  Failed to parse seeds.ts output:', err)
+      }
+    } else if (result.status !== 0) {
+      console.error('  Error loading seeds.ts:')
+      console.error(result.stderr || result.stdout || 'Unknown error')
+      if (process.version.slice(1).split('.')[0] < 22) {
+        console.warn('  Note: Node.js 22.6+ is required to load .ts files directly. Current version:', process.version)
+      }
+    }
+  }
+
+  return null
+}
+
+async function cmdInit(args) {
+  const initDb  = args.includes('--db')
+  const remote  = args.includes('--remote')
+  const dbIdx   = args.indexOf('--db-name')
+  const db      = dbIdx !== -1 ? args[dbIdx + 1] : undefined
+
+  const { init } = await import('@beechcms/cli')
+  await init({ initDb, local: !remote, db })
+}
+
+async function cmdSeedLoad(args) {
+  const dryRun = args.includes('--dry-run')
+  const diff   = args.includes('--diff')
+  const remote = args.includes('--remote')
+  const dbIdx  = args.indexOf('--db')
+  const db     = dbIdx !== -1 ? args[dbIdx + 1] : undefined
+
+  const registry = await tryLoadLocalRegistry()
+
+  const { seedLoad } = await import('@beechcms/cli')
+  await seedLoad({ dryRun, diff, local: !remote, db, registry })
+}
+
+async function cmdValidate(args) {
+  const registry = await tryLoadLocalRegistry()
+  const { validate } = await import('@beechcms/cli')
+  await validate({ registry })
+}
+
+async function cmdSeedCreate(_args) {
+  const { seedCreate } = await import('@beechcms/cli')
+  await seedCreate({})
+}
+
+async function cmdDeploy(args) {
+  const skipSeed  = args.includes('--skip-seed')
+  const skipCheck = args.includes('--skip-check')
+  const registry  = skipSeed ? null : await tryLoadLocalRegistry()
+  const { deploy } = await import('@beechcms/cli')
+  await deploy({ registry, skipSeed, skipCheck })
+}
+
+const handler = COMMANDS[command]
+if (!handler) {
+  help()
+  if (command) process.exit(1)
+} else if (args.includes('--help') || args.includes('-h')) {
+  help()
+} else {
+  await handler(args)
+}