@beechcms/cli 0.5.0 → 0.6.0-preview.1

package/src/commands/seed-create.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+
 import pc from 'picocolors'
 import { createInterface } from 'node:readline/promises'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'

package/src/commands/seed-load.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+
 import pc from 'picocolors'
 import {
   SEED_REGISTRY,
@@ -6,9 +9,13 @@ import {
   generateIndexes,
   generateFtsTable,
   generateFtsTriggers,
+  generateJunctionTable,
+  generateJunctionIndexes,
+  generateJunctionDraftTable,
+  sortSeedsByDependencies,
   type Seed,
 } from '@beechcms/core'
-import { executeD1File, findWranglerConfig, resolveDbName, type WranglerOptions } from '../lib/wrangler.js'
+import { executeD1File, findWranglerConfig, resolveDbName, queryD1, sqlQuote, type WranglerOptions } from '../lib/wrangler.js'
 import { diffSeed } from '../lib/schema-diff.js'
 import { validateSeeds } from './validate.js'
 
@@ -20,6 +27,18 @@ export interface SeedLoadOptions {
   registry?: Record<string, Seed> | null
 }
 
+export function buildSeedRegistrationSql(seed: Seed): string {
+  const json = sqlQuote(JSON.stringify(seed))
+  return [
+    `INSERT INTO seeds (slug, definition, status, source, created_at, updated_at)`,
+    `VALUES (${sqlQuote(seed.slug)}, ${json}, 'active', 'code', unixepoch(), unixepoch())`,
+    `ON CONFLICT(slug) DO UPDATE SET definition = excluded.definition, status = 'active', updated_at = excluded.updated_at;`,
+  ].join('\n')
+}
+
+const SEED_META_BUMP_SQL =
+  `UPDATE seed_meta SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT) WHERE id = 'registry_version';`
+
 function buildStatements(seed: Seed): string[] {
   const stmts: string[] = [generateCreateTable(seed), ...generateIndexes(seed)]
 
@@ -31,11 +50,20 @@ function buildStatements(seed: Seed): string[] {
     stmts.push(fts, ...generateFtsTriggers(seed))
   }
 
+  // Many-to-many: junction table + indexes after parent table exists (topological order
+  // from sortSeedsByDependencies guarantees the target table also exists at this point).
+  for (const branch of seed.branches) {
+    if (branch.type !== 'relation' || branch.multiple !== true) continue
+    stmts.push(generateJunctionTable(seed, branch), ...generateJunctionIndexes(seed, branch))
+    const draftJunction = generateJunctionDraftTable(seed, branch)
+    if (draftJunction) stmts.push(draftJunction)
+  }
+
   return stmts
 }
 
 async function runDiff(options: WranglerOptions, registry: Record<string, Seed>): Promise<void> {
-  const seeds = Object.values(registry)
+  const seeds = sortSeedsByDependencies(Object.values(registry))
   console.log(pc.cyan('\n  Diffing schema…\n'))
 
   let allOk = true
@@ -64,6 +92,12 @@ async function runDiff(options: WranglerOptions, registry: Record<string, Seed>)
         console.log(pc.dim(`    ~ orphaned column: "${col.name}" (${col.actualType}) — exists in DB but not in seeds.ts`))
       } else if (col.status === 'type_mismatch') {
         console.log(pc.red(`    ≠ type mismatch:  ${col.name} (expected ${col.expectedType}, got ${col.actualType})`))
+      } else if (col.status === 'fk_missing') {
+        console.log(pc.red(`    ⤬ missing FK: ${col.name} → content_${col.expectedTarget}(id)`))
+      } else if (col.status === 'fk_mismatch') {
+        console.log(pc.yellow(`    ⤬ FK mismatch: ${col.name} expected ${col.expected}, got ${col.actual}`))
+      } else if (col.status === 'index_missing') {
+        console.log(pc.yellow(`    ⊘ missing index on ${col.name}`))
       }
     }
   }
@@ -77,7 +111,7 @@ async function runDiff(options: WranglerOptions, registry: Record<string, Seed>)
 }
 
 async function runLoad(options: WranglerOptions, dryRun: boolean, registry: Record<string, Seed>): Promise<void> {
-  const seeds = Object.values(registry)
+  const seeds = sortSeedsByDependencies(Object.values(registry))
 
   if (dryRun) {
     console.log(pc.cyan('\n  -- dry-run: SQL that would be executed\n'))
@@ -87,14 +121,18 @@ async function runLoad(options: WranglerOptions, dryRun: boolean, registry: Reco
       for (const stmt of stmts) {
         console.log(stmt + '\n')
       }
+      console.log(pc.dim(`  -- register ${seed.slug} in seeds table`))
+      console.log(buildSeedRegistrationSql(seed) + '\n')
     }
+    console.log(pc.dim('  -- bump registry_version'))
+    console.log(SEED_META_BUMP_SQL + '\n')
     return
   }
 
   console.log(pc.cyan(`\n  Loading seeds into ${options.local ? 'local' : 'remote'} D1 (${options.db})…\n`))
 
   for (const seed of seeds) {
-    const stmts = buildStatements(seed)
+    const stmts = [...buildStatements(seed), buildSeedRegistrationSql(seed)]
     const sql = stmts.join('\n\n') + '\n'
     process.stdout.write(`  ${pc.dim('→')} content_${seed.slug}… `)
     const ok = executeD1File(sql, options)
@@ -117,7 +155,12 @@ async function runLoad(options: WranglerOptions, dryRun: boolean, registry: Reco
     console.log(pc.green('done'))
   }
 
+  // Bump registry_version so live isolates re-hydrate
+  executeD1File(SEED_META_BUMP_SQL, options)
+
   console.log(pc.green('\n  All seeds loaded.\n'))
+  console.log(pc.dim('  Definitions registered in the database.'))
+  console.log(pc.dim('  seed.ts is no longer required at runtime — you may keep it for code-first edits or delete it.\n'))
 }
 
 export async function seedLoad(args: SeedLoadOptions): Promise<void> {
@@ -131,8 +174,25 @@ export async function seedLoad(args: SeedLoadOptions): Promise<void> {
   }
 
   const validationErrors = validateSeeds(registry)
-  if (validationErrors.length > 0) {
-    const total = validationErrors.reduce((n, e) => n + e.messages.length, 0)
+  const fatalErrors = validationErrors.filter(e => e.fatal)
+  const warnings = validationErrors.filter(e => !e.fatal)
+
+  if (fatalErrors.length > 0) {
+    const total = fatalErrors.reduce((n, e) => n + e.messages.length, 0)
+    const s = total !== 1 ? 's' : ''
+    console.log(pc.red(`\n  ✗ Seed validation found ${total} fatal error${s}. Cannot load schema.\n`))
+    for (const e of fatalErrors) {
+      console.log(pc.red(`  ✗ ${e.slug}`))
+      for (const msg of e.messages) {
+        console.log(pc.red(`      → ${msg}`))
+      }
+    }
+    console.log('')
+    process.exit(1)
+  }
+
+  if (warnings.length > 0) {
+    const total = warnings.reduce((n, e) => n + e.messages.length, 0)
     const s = total !== 1 ? 's' : ''
     console.log(pc.yellow(`\n  ⚠ Seed validation found ${total} issue${s}. Schema changes will still be applied.\n`))
     console.log(pc.dim('  Run "npx beech validate" for details.\n'))
@@ -147,6 +207,26 @@ export async function seedLoad(args: SeedLoadOptions): Promise<void> {
     configPath,
   }
 
+  if (!args.dryRun && !args.diff) {
+    try {
+      const rows = queryD1<{ name: string }>(
+        `SELECT name FROM sqlite_master WHERE type='table' AND name IN ('seeds','seed_meta')`,
+        options
+      )
+      if (rows.length < 2) {
+        console.log(pc.red('\n  ✗ System tables not found (seeds, seed_meta)\n'))
+        console.log(pc.dim('  Run `beech init --db` first to initialise the database.'))
+        const flag = args.local ? ' --local' : ''
+        console.log(pc.cyan(`\n  → Run: npx beech init --db${flag}\n`))
+        process.exit(1)
+      }
+    } catch {
+      console.log(pc.red('\n  ✗ Could not query the database\n'))
+      console.log(pc.dim('  Run `beech init --db` first to initialise the database.'))
+      process.exit(1)
+    }
+  }
+
   if (args.diff) {
     await runDiff(options, registry)
   } else {

package/src/commands/update.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+
 import pc from 'picocolors'
 import { spawnSync } from 'node:child_process'
 

package/src/commands/validate.ts

@@ -1,6 +1,9 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+
 import pc from 'picocolors'
 import type { Seed } from '@beechcms/core'
-import { SEED_REGISTRY } from '@beechcms/core'
+import { SEED_REGISTRY, validateSeedDefinitions } from '@beechcms/core'
 
 export interface ValidateOptions {
   registry?: Record<string, Seed> | null
@@ -9,39 +12,12 @@ export interface ValidateOptions {
 export interface SeedValidationError {
   slug: string
   messages: string[]
+  /** true = abort seed:load; false = warning only */
+  fatal: boolean
 }
 
 export function validateSeeds(registry: Record<string, Seed>): SeedValidationError[] {
-  const result: SeedValidationError[] = []
-  const slugsSeen = new Set<string>()
-
-  for (const seed of Object.values(registry)) {
-    const messages: string[] = []
-
-    if (slugsSeen.has(seed.slug)) {
-      messages.push(`duplicate slug "${seed.slug}" — each seed must have a unique slug`)
-    }
-    slugsSeen.add(seed.slug)
-
-    const aliasesSeen = new Set<string>()
-    for (const branch of seed.branches) {
-      if (aliasesSeen.has(branch.alias)) {
-        messages.push(`duplicate branch alias "${branch.alias}"`)
-      }
-      aliasesSeen.add(branch.alias)
-    }
-
-    const allAliases = new Set(seed.branches.map(b => b.alias))
-    if (!allAliases.has(seed.displayNameAlias)) {
-      messages.push(`displayNameAlias "${seed.displayNameAlias}" not found in branches`)
-    }
-
-    if (messages.length > 0) {
-      result.push({ slug: seed.slug, messages })
-    }
-  }
-
-  return result
+  return validateSeedDefinitions(Object.values(registry))
 }
 
 export async function validate(args: ValidateOptions): Promise<void> {
@@ -55,28 +31,49 @@ export async function validate(args: ValidateOptions): Promise<void> {
   console.log(pc.cyan('\n  beech validate — checking seeds\n'))
 
   const errors = validateSeeds(registry)
-  const errorMap = new Map(errors.map(e => [e.slug, e.messages]))
+  const fatalErrors = errors.filter(e => e.fatal)
+  const warnings = errors.filter(e => !e.fatal)
+
+  // Print fatal errors first
+  for (const e of fatalErrors) {
+    console.log(pc.red(`  ✗ ${e.slug} (fatal)`))
+    for (const msg of e.messages) {
+      console.log(pc.red(`      → ${msg}`))
+    }
+  }
+
+  // Print per-seed warnings
+  const warningMap = new Map(warnings.map(e => [e.slug, e.messages]))
+  const allWarningSlugsSeen = new Set(warnings.map(e => e.slug))
 
-  let totalIssues = 0
   for (const seed of Object.values(registry)) {
-    const msgs = errorMap.get(seed.slug)
+    const msgs = warningMap.get(seed.slug)
     if (!msgs) {
-      console.log(pc.green(`  ✓ ${seed.slug}`))
+      if (!allWarningSlugsSeen.has(seed.slug)) {
+        // only print ✓ if no fatal error for this slug either
+        const hasFatal = fatalErrors.some(e => e.slug === seed.slug)
+        if (!hasFatal) console.log(pc.green(`  ✓ ${seed.slug}`))
+      }
     } else {
-      totalIssues += msgs.length
-      console.log(pc.red(`  ✗ ${seed.slug}`))
+      console.log(pc.yellow(`  ⚠ ${seed.slug}`))
       for (const msg of msgs) {
-        console.log(pc.red(`      → ${msg}`))
+        console.log(pc.yellow(`      → ${msg}`))
       }
     }
   }
 
   console.log('')
 
-  if (totalIssues > 0) {
-    const s = totalIssues !== 1 ? 's' : ''
-    console.log(pc.red(`  Found ${totalIssues} issue${s}. Fix the seeds above before loading.\n`))
+  const totalFatal = fatalErrors.reduce((n, e) => n + e.messages.length, 0)
+  const totalWarnings = warnings.reduce((n, e) => n + e.messages.length, 0)
+
+  if (totalFatal > 0) {
+    const s = totalFatal !== 1 ? 's' : ''
+    console.log(pc.red(`  Found ${totalFatal} fatal error${s}. Fix before loading.\n`))
     process.exit(1)
+  } else if (totalWarnings > 0) {
+    const s = totalWarnings !== 1 ? 's' : ''
+    console.log(pc.yellow(`  Found ${totalWarnings} warning${s}. Review seeds above.\n`))
   } else {
     console.log(pc.green('  All seeds valid.\n'))
   }

package/src/index.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+
 export { seedLoad } from './commands/seed-load.js'
 export type { SeedLoadOptions } from './commands/seed-load.js'
 export { init } from './commands/init.js'
@@ -8,5 +11,7 @@ export { seedCreate } from './commands/seed-create.js'
 export type { SeedCreateOptions } from './commands/seed-create.js'
 export { deploy } from './commands/deploy.js'
 export type { DeployOptions } from './commands/deploy.js'
+export { onboard } from './commands/onboard.js'
+export type { OnboardOptions } from './commands/onboard.js'
 export { update } from './commands/update.js'
 export type { UpdateOptions } from './commands/update.js'

package/src/lib/schema-diff.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+
 import type { Seed } from '@beechcms/core'
 import { getExpectedColumns, type SchemaColumn } from '@beechcms/core'
 import type { WranglerOptions, D1Row } from './wrangler.js'
@@ -10,11 +13,33 @@ interface PragmaRow extends D1Row {
   pk: number
 }
 
+interface FkRow extends D1Row {
+  id: number
+  seq: number
+  table: string
+  from: string
+  to: string
+  on_update: string
+  on_delete: string
+  match: string
+}
+
+interface IndexRow extends D1Row {
+  seq: number
+  name: string
+  unique: number
+}
+
 export interface ColumnDiff {
   name: string
-  status: 'ok' | 'missing' | 'extra' | 'type_mismatch'
+  status: 'ok' | 'missing' | 'extra' | 'type_mismatch' | 'fk_missing' | 'fk_mismatch' | 'index_missing'
   expectedType?: string
   actualType?: string
+  /** For fk_missing/fk_mismatch: expected FK target table */
+  expectedTarget?: string
+  /** For fk_mismatch: what the DB actually has */
+  expected?: string
+  actual?: string
 }
 
 export interface SeedDiff {
@@ -43,12 +68,13 @@ export async function diffSeed(seed: Seed, options: WranglerOptions): Promise<Se
 
   const columns: ColumnDiff[] = []
 
+  // ── Column presence + type checks ────────────────────────────────────────
   for (const col of expected) {
-    const actual = actualMap.get(col.name)
-    if (!actual) {
+    const actualRow = actualMap.get(col.name)
+    if (!actualRow) {
       columns.push({ name: col.name, status: 'missing', expectedType: col.sqlType })
-    } else if (actual.type.toUpperCase() !== col.sqlType) {
-      columns.push({ name: col.name, status: 'type_mismatch', expectedType: col.sqlType, actualType: actual.type })
+    } else if (actualRow.type.toUpperCase() !== col.sqlType) {
+      columns.push({ name: col.name, status: 'type_mismatch', expectedType: col.sqlType, actualType: actualRow.type })
     } else {
       columns.push({ name: col.name, status: 'ok' })
     }
@@ -60,5 +86,65 @@ export async function diffSeed(seed: Seed, options: WranglerOptions): Promise<Se
     }
   }
 
+  // ── FK + index checks for relation branches ──────────────────────────────
+  const relationBranches = seed.branches.filter(b => b.type === 'relation' && b.targetSeed)
+
+  if (relationBranches.length > 0) {
+    let fkList: FkRow[] = []
+    let indexList: IndexRow[] = []
+    try {
+      fkList = queryD1<FkRow>(`PRAGMA foreign_key_list(${tableName})`, options)
+      indexList = queryD1<IndexRow>(`PRAGMA index_list(${tableName})`, options)
+    } catch {
+      // If PRAGMA fails (table may not exist yet), skip FK checks
+    }
+
+    // Build maps for fast lookup
+    // fkList has one row per FK column; `from` = local col, `table` = referenced table
+    const fkByCol = new Map<string, FkRow>()
+    for (const fk of fkList) {
+      fkByCol.set(fk.from, fk)
+    }
+    const indexNames = new Set(indexList.map(i => i.name))
+
+    for (const branch of relationBranches) {
+      const expectedFkTable = `content_${branch.targetSeed}`
+      const expectedOnDelete = (branch.onDelete ?? 'SET NULL').toUpperCase()
+      const expectedIndexName = `idx_${seed.slug}_${branch.alias}`
+
+      // Find column diff entry for this branch (already evaluated above)
+      const colDiff = columns.find(c => c.name === branch.alias)
+      if (!colDiff || colDiff.status === 'missing') continue // already flagged
+
+      const fk = fkByCol.get(branch.alias)
+
+      if (!fk) {
+        // Column exists but no FK
+        colDiff.status = 'fk_missing'
+        colDiff.expectedTarget = branch.targetSeed
+      } else {
+        const actualTable = fk.table
+        const actualOnDelete = fk.on_delete.toUpperCase()
+        if (actualTable !== expectedFkTable || actualOnDelete !== expectedOnDelete) {
+          colDiff.status = 'fk_mismatch'
+          colDiff.expected = `→ ${expectedFkTable}(id) ON DELETE ${expectedOnDelete}`
+          colDiff.actual = `→ ${actualTable}(id) ON DELETE ${actualOnDelete}`
+          colDiff.expectedTarget = branch.targetSeed
+        }
+      }
+
+      // Check index separately (can coexist with fk status)
+      if (!indexNames.has(expectedIndexName)) {
+        // Only add index_missing if the column is otherwise OK (FK issue takes precedence)
+        if (colDiff.status === 'ok') {
+          colDiff.status = 'index_missing'
+        } else {
+          // Append index info to the existing diff row as a separate entry
+          columns.push({ name: branch.alias, status: 'index_missing' })
+        }
+      }
+    }
+  }
+
   return { slug: seed.slug, tableExists: true, columns }
 }

package/src/lib/wrangler.ts

@@ -1,4 +1,7 @@
-import { spawnSync } from 'node:child_process'
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process'
 import { writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
@@ -40,10 +43,25 @@ export function executeD1File(sql: string, options: WranglerOptions): boolean {
   }
 }
 
-/** Esegue una query SQL e ritorna i risultati come array di oggetti (--json). */
+/**
+ * Esegue una query SQL e ritorna i risultati come array di oggetti (--json).
+ *
+ * Passa il SQL via file temporaneo (`--file`) anziché `--command`: su Windows,
+ * `spawnSync` con `shell: true` non preserva le virgolette/spazi/virgole interni
+ * a un argomento inline, e wrangler riceve il comando spezzato in token sciolti
+ * ("Unknown arguments: name, FROM, sqlite_master, …"). Il file evita del tutto
+ * il riquoting della shell — stesso approccio di `executeD1File`.
+ */
 export function queryD1<T extends D1Row = D1Row>(sql: string, options: WranglerOptions): T[] {
-  const args = ['d1', 'execute', options.db, '--command', sql, '--json', ...buildArgs(options)]
-  const result = spawnSync('npx', ['wrangler', ...args], { encoding: 'utf-8', cwd: process.cwd(), shell: true })
+  const tmpFile = join(tmpdir(), `beech-query-${Date.now()}.sql`)
+  let result: SpawnSyncReturns<string>
+  try {
+    writeFileSync(tmpFile, sql, 'utf-8')
+    const args = ['d1', 'execute', options.db, '--file', tmpFile, '--json', ...buildArgs(options)]
+    result = spawnSync('npx', ['wrangler', ...args], { encoding: 'utf-8', cwd: process.cwd(), shell: true })
+  } finally {
+    try { rmSync(tmpFile) } catch {}
+  }
 
   if (result.status !== 0) {
     throw new Error(`wrangler d1 execute failed:\n${result.stderr}`)
@@ -76,6 +94,11 @@ export function findWranglerConfig(): string | null {
   return null
 }
 
+/** Wraps a string value in single quotes, escaping internal single quotes for SQL literals. */
+export function sqlQuote(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`
+}
+
 /** Risolve il nome del database D1 da wrangler.jsonc (stripping JSONC comments). */
 export function resolveDbName(configPath: string | null): string {
   if (!configPath) return 'beech-db'