@beechcms/core 0.9.3 → 0.9.5

package/dist/engine/seed-ddl-destructive.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { junctionTableName, generateFtsTable, generateFtsTriggers } from './engine.js';
+const BRANCH_SQL_TYPE = {
+    text: 'TEXT',
+    number: 'REAL',
+    boolean: 'INTEGER',
+    date: 'INTEGER',
+    json: 'TEXT',
+    richtext: 'TEXT',
+    file: 'TEXT',
+    tags: 'TEXT',
+    relation: 'TEXT',
+    repeater: 'TEXT',
+};
+/** Branch types that receive a B-tree index in generateIndexes (used by retype to drop/recreate). */
+const INDEXABLE_TYPES = new Set(['text', 'number', 'date', 'boolean', 'relation']);
+function searchBranches(seed) {
+    return seed.branches.filter(b => (b.type === 'text' || b.type === 'richtext') && b.policies?.search !== false);
+}
+function ftsTriggerDrops(slug) {
+    return [
+        `DROP TRIGGER IF EXISTS fts_${slug}_insert;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_update;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_delete;`,
+        `DROP TABLE IF EXISTS fts_${slug};`,
+    ];
+}
+/**
+ * Ordered DROP TABLE statements for a full hard-delete of a seed's tables.
+ * Order: junction drafts → junctions → FTS triggers → FTS table → drafts → main table.
+ * All statements use IF EXISTS (idempotent).
+ */
+export function generateDropTable(seed) {
+    const stmts = [];
+    const { slug } = seed;
+    for (const branch of seed.branches) {
+        if (branch.type !== 'relation' || branch.multiple !== true)
+            continue;
+        const jt = junctionTableName(slug, branch.alias);
+        stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    stmts.push(...ftsTriggerDrops(slug));
+    stmts.push(`DROP TABLE IF EXISTS content_${slug}_drafts;`);
+    stmts.push(`DROP TABLE IF EXISTS content_${slug};`);
+    return stmts;
+}
+/**
+ * DROP COLUMN statements for a single branch (by alias).
+ * For multi-relation branches: drops the junction tables (no column on parent).
+ * For regular branches: drops from main table + drafts table (if allowDrafts).
+ * Does NOT include FTS handling — callers must prepend ftsTriggerDrops() and
+ * append planFtsRebuild() when the branch is searchable.
+ */
+export function generateDropColumn(seed, alias) {
+    const stmts = [];
+    const { slug } = seed;
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${slug}'`);
+    if (branch.type === 'relation' && branch.multiple === true) {
+        const jt = junctionTableName(slug, alias);
+        if (seed.allowDrafts)
+            stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    else {
+        stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+        if (seed.allowDrafts)
+            stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+    }
+    return stmts;
+}
+/**
+ * RENAME COLUMN statements for a branch alias change.
+ * Updates main table + drafts (if allowDrafts).
+ * Does NOT handle FTS — callers must rebuild FTS separately (SQLite auto-updates
+ * trigger bodies on RENAME but the FTS virtual-table columns keep the old name).
+ */
+export function generateRenameColumn(seed, fromAlias, toAlias) {
+    const stmts = [];
+    const { slug } = seed;
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    }
+    return stmts;
+}
+/**
+ * Full FTS rebuild: drop triggers + FTS table, then recreate them, then backfill.
+ * Returns an empty array if the seed has no searchable branches.
+ * The drop steps use IF EXISTS so this is safe to call even if FTS was already dropped.
+ */
+export function planFtsRebuild(seed) {
+    const rtBranches = searchBranches(seed);
+    if (rtBranches.length === 0)
+        return [];
+    const { slug } = seed;
+    const stmts = [...ftsTriggerDrops(slug)];
+    const ftsTable = generateFtsTable(seed);
+    if (ftsTable)
+        stmts.push(ftsTable);
+    stmts.push(...generateFtsTriggers(seed));
+    const cols = rtBranches.map(b => b.alias);
+    stmts.push(`INSERT INTO fts_${slug}(entry_id, ${cols.join(', ')}) SELECT id, ${cols.join(', ')} FROM content_${slug};`);
+    return stmts;
+}
+/**
+ * Generates statements to change a branch's SQL storage type using the
+ * add-new-column / copy / drop-old / rename approach.
+ * Includes FTS rebuild statements when the branch is (or becomes) searchable.
+ * `updatedSeed` must already reflect the new type on the renamed branch.
+ */
+export function planRetypeColumn(seed, alias, newType, updatedSeed) {
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${seed.slug}'`);
+    const { slug } = seed;
+    const newSqlType = BRANCH_SQL_TYPE[newType];
+    const tmpAlias = `${alias}_migrate`;
+    const stmts = [];
+    // Always drop FTS first to avoid "column referenced in trigger" errors on DROP COLUMN.
+    stmts.push(...ftsTriggerDrops(slug));
+    // Drop the branch index if it exists on the old column (required before DROP COLUMN).
+    if (INDEXABLE_TYPES.has(branch.type) && branch.policies?.filter !== false) {
+        stmts.push(`DROP INDEX IF EXISTS idx_${slug}_${alias};`);
+    }
+    // Main table: add migration column, copy data, drop old, rename.
+    stmts.push(`ALTER TABLE content_${slug} ADD COLUMN ${tmpAlias} ${newSqlType};`);
+    stmts.push(`UPDATE content_${slug} SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+    stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    // Recreate index for the renamed column if the new type warrants it.
+    if (INDEXABLE_TYPES.has(newType) && branch.policies?.filter !== false) {
+        stmts.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_${alias} ON content_${slug}(${alias});`);
+    }
+    // Drafts table (no indexes to worry about).
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts ADD COLUMN ${tmpAlias} ${newSqlType};`);
+        stmts.push(`UPDATE content_${slug}_drafts SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    }
+    // Rebuild FTS if the seed has searchable branches in the updated definition.
+    const rebuild = planFtsRebuild(updatedSeed);
+    stmts.push(...rebuild);
+    return { statements: stmts, ftsRebuildNeeded: rebuild.length > 0 };
+}

package/dist/engine/seed-ddl.d.ts

@@ -0,0 +1,43 @@
+import type { Seed } from './types.js';
+/**
+ * Full create-from-scratch statement set for a seed. Mirrors the CLI's buildStatements.
+ * Order: parent table → indexes → draft table → FTS table → FTS triggers →
+ * per multi-relation: junction table → junction indexes → junction draft table.
+ * Callers that create several seeds must order seeds with sortSeedsByDependencies
+ * first so relation FK targets exist.
+ */
+export declare function planCreateSeed(seed: Seed): string[];
+export interface ExtendPlan {
+    statements: string[];
+    ftsRebuildNeeded: boolean;
+}
+/**
+ * Additive extension: given the columns that already exist on content_{slug}
+ * (from PRAGMA table_info, passed in by the caller), return ONLY the statements
+ * needed to add new branches — ADD COLUMN + indexes, plus junction tables for
+ * new multi-relation branches. Never drops or renames.
+ *
+ * FTS: SQLite cannot ALTER an fts5 table's columns. If a new text/richtext
+ * searchable branch was added, ftsRebuildNeeded=true signals the caller
+ * (sprint 03) to handle it — no DROP is emitted.
+ *
+ * Draft tables: pass `existingDraftColumns` (PRAGMA table_info on content_{slug}_drafts) to have the
+ * `live_snapshot_at` system column added retroactively; omit it to skip that check entirely.
+ */
+export declare function planExtendSeed(seed: Seed, existingColumns: Set<string>, existingDraftColumns?: Set<string> | null): ExtendPlan;
+/**
+ * Destructive FTS rebuild (sprint 06). SQLite cannot ALTER an fts5 table's
+ * columns, so when a searchable branch is added, renamed, retyped, or dropped
+ * the only correct fix is to drop and recreate the `fts_{slug}` virtual table
+ * (and its insert/update/delete triggers), then backfill from `content_{slug}`.
+ *
+ * Returns an empty array when the seed has no searchable branches — in that
+ * case the caller should instead drop any leftover FTS table via
+ * generateDropTable's FTS statements. The returned statements are destructive
+ * and must run through ISchemaMutator.execDestructive, never execDdl.
+ *
+ * Order: drop triggers → drop fts table → recreate table → recreate triggers →
+ * backfill existing rows.
+ */
+export declare function planFtsRebuild(seed: Seed): string[];
+//# sourceMappingURL=seed-ddl.d.ts.map

package/dist/engine/seed-ddl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-ddl.d.ts","sourceRoot":"","sources":["../../src/engine/seed-ddl.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAgBtC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAanD;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,oBAAoB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACxC,UAAU,CAmCZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CA0BnD"}

package/dist/engine/seed-ddl.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { generateCreateTable, generateDraftTable, generateIndexes, generateFtsTable, generateFtsTriggers, generateAddColumn, generateAddDraftSnapshotColumn, generateJunctionTable, generateJunctionIndexes, generateJunctionDraftTable, generateEnableSoftDelete, indexableSearchBranches, } from './engine.js';
+/**
+ * Full create-from-scratch statement set for a seed. Mirrors the CLI's buildStatements.
+ * Order: parent table → indexes → draft table → FTS table → FTS triggers →
+ * per multi-relation: junction table → junction indexes → junction draft table.
+ * Callers that create several seeds must order seeds with sortSeedsByDependencies
+ * first so relation FK targets exist.
+ */
+export function planCreateSeed(seed) {
+    const stmts = [generateCreateTable(seed), ...generateIndexes(seed)];
+    const draft = generateDraftTable(seed);
+    if (draft)
+        stmts.push(draft);
+    const fts = generateFtsTable(seed);
+    if (fts)
+        stmts.push(fts, ...generateFtsTriggers(seed));
+    for (const branch of seed.branches) {
+        if (branch.type !== 'relation' || branch.multiple !== true)
+            continue;
+        stmts.push(generateJunctionTable(seed, branch), ...generateJunctionIndexes(seed, branch));
+        const dj = generateJunctionDraftTable(seed, branch);
+        if (dj)
+            stmts.push(dj);
+    }
+    return stmts;
+}
+/**
+ * Additive extension: given the columns that already exist on content_{slug}
+ * (from PRAGMA table_info, passed in by the caller), return ONLY the statements
+ * needed to add new branches — ADD COLUMN + indexes, plus junction tables for
+ * new multi-relation branches. Never drops or renames.
+ *
+ * FTS: SQLite cannot ALTER an fts5 table's columns. If a new text/richtext
+ * searchable branch was added, ftsRebuildNeeded=true signals the caller
+ * (sprint 03) to handle it — no DROP is emitted.
+ *
+ * Draft tables: pass `existingDraftColumns` (PRAGMA table_info on content_{slug}_drafts) to have the
+ * `live_snapshot_at` system column added retroactively; omit it to skip that check entirely.
+ */
+export function planExtendSeed(seed, existingColumns, existingDraftColumns) {
+    const statements = [];
+    let ftsRebuildNeeded = false;
+    for (const branch of seed.branches) {
+        if (branch.type === 'relation' && branch.multiple === true) {
+            // junction table is CREATE IF NOT EXISTS — safe to re-emit
+            statements.push(generateJunctionTable(seed, branch), ...generateJunctionIndexes(seed, branch));
+            const dj = generateJunctionDraftTable(seed, branch);
+            if (dj)
+                statements.push(dj);
+            continue;
+        }
+        if (existingColumns.has(branch.alias))
+            continue;
+        statements.push(generateAddColumn(seed, branch));
+        if ((branch.type === 'text' || branch.type === 'richtext') && branch.policies?.search !== false) {
+            ftsRebuildNeeded = true;
+        }
+    }
+    // System column, not a branch: the branch loop above can never emit it.
+    if (seed.softDelete && !existingColumns.has('deleted_at')) {
+        statements.push(...generateEnableSoftDelete(seed));
+    }
+    // Draft-table system column. Emitted only when the caller actually introspected
+    // content_{slug}_drafts: `undefined` means "not introspected" and `null` means "table absent",
+    // and in both cases emitting a non-idempotent ADD COLUMN would abort the caller's whole DDL batch.
+    if (seed.allowDrafts &&
+        existingDraftColumns != null &&
+        !existingDraftColumns.has('live_snapshot_at')) {
+        statements.push(generateAddDraftSnapshotColumn(seed));
+    }
+    // CREATE INDEX IF NOT EXISTS — idempotent, safe to re-run
+    statements.push(...generateIndexes(seed));
+    return { statements, ftsRebuildNeeded };
+}
+/**
+ * Destructive FTS rebuild (sprint 06). SQLite cannot ALTER an fts5 table's
+ * columns, so when a searchable branch is added, renamed, retyped, or dropped
+ * the only correct fix is to drop and recreate the `fts_{slug}` virtual table
+ * (and its insert/update/delete triggers), then backfill from `content_{slug}`.
+ *
+ * Returns an empty array when the seed has no searchable branches — in that
+ * case the caller should instead drop any leftover FTS table via
+ * generateDropTable's FTS statements. The returned statements are destructive
+ * and must run through ISchemaMutator.execDestructive, never execDdl.
+ *
+ * Order: drop triggers → drop fts table → recreate table → recreate triggers →
+ * backfill existing rows.
+ */
+export function planFtsRebuild(seed) {
+    const branches = indexableSearchBranches(seed);
+    if (branches.length === 0)
+        return [];
+    const slug = seed.slug;
+    const ftsTable = `fts_${slug}`;
+    const contentTable = `content_${slug}`;
+    const cols = branches.map(b => b.alias);
+    const ftsTableDdl = generateFtsTable(seed);
+    const triggers = generateFtsTriggers(seed);
+    // generateFtsTable/Triggers return non-null here (branches.length > 0 checked).
+    if (!ftsTableDdl)
+        return [];
+    const ftsColList = ['entry_id', ...cols].join(', ');
+    const selectList = ['id', ...cols].join(', ');
+    return [
+        `DROP TRIGGER IF EXISTS fts_${slug}_insert;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_update;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_delete;`,
+        `DROP TABLE IF EXISTS ${ftsTable};`,
+        ftsTableDdl,
+        ...triggers,
+        `INSERT INTO ${ftsTable}(${ftsColList}) SELECT ${selectList} FROM ${contentTable};`,
+    ];
+}

package/dist/engine/seed-registry.d.ts

@@ -0,0 +1,71 @@
+import type { Seed, Branch } from './types.js';
+export interface ISeedRegistry {
+    /**
+     * Returns all seeds as a flat array, preserving insertion order.
+     * Decouples callers from the internal storage shape so the registry
+     * implementation can change without touching every route handler.
+     */
+    all(): Seed[];
+    /**
+     * Returns the seed with the given slug, or null if not found.
+     * Provides a single lookup point that can be overridden in tests
+     * without rebuilding the full registry object.
+     */
+    get(slug: string): Seed | null;
+    /**
+     * Returns seeds that are visible in the dashboard sidebar.
+     * A seed is visible when dashboard.hidden is not explicitly true.
+     * Eliminates the seeds.filter(s => !s.dashboard?.hidden) pattern
+     * that would otherwise be duplicated across route handlers.
+     */
+    visibleInDashboard(): Seed[];
+    /**
+     * Returns seeds that have allowPublicRead enabled.
+     * Eliminates the seeds.filter(s => s.allowPublicRead) pattern.
+     */
+    publicReadable(): Seed[];
+    /**
+     * Returns seeds that have the draft workflow enabled.
+     * Eliminates the seeds.filter(s => s.allowDrafts) pattern.
+     */
+    draftEnabled(): Seed[];
+}
+export declare class SeedRegistry implements ISeedRegistry {
+    private readonly seedMap;
+    private readonly orderedSeeds;
+    constructor(seeds: Seed[]);
+    all(): Seed[];
+    get(slug: string): Seed | null;
+    visibleInDashboard(): Seed[];
+    publicReadable(): Seed[];
+    draftEnabled(): Seed[];
+}
+/**
+ * Named subclass of SeedRegistry for use in test suites.
+ * Gives tests a semantic name without requiring any dependency on factory.ts.
+ */
+export declare class InMemorySeedRegistry extends SeedRegistry {
+}
+/** Finds a branch by its stable id within a Seed. Returns null if not found. */
+export declare function findBranchById(seed: Seed, id: string): Branch | null;
+/**
+ * Returns the next free branch id for a seed in the form `br_NN` (zero-padded to 2,
+ * growing as needed). Scans existing ids, never reuses a number already present —
+ * even if a branch was removed, its id is not recycled (ids must be globally stable
+ * for the life of the seed so layouts/automations/FTS triggers never collide).
+ */
+export declare function nextBranchId(seed: Pick<Seed, 'branches'>): string;
+/**
+ * Returns the input seeds reordered so that every seed appears AFTER all the
+ * seeds it depends on (its `relation` branch targets). Pure function — does
+ * not read from any global registry.
+ *
+ * Uses Kahn's algorithm (BFS on in-degree) for cycle detection and topological
+ * ordering. Sprint 3 (CLI / migration runner) consumes this to create tables in
+ * the correct order without disabling SQLite FK constraints.
+ *
+ * @throws {Error} When a relation targets an unknown slug not in `seeds`.
+ * @throws {Error} When a cyclic dependency is detected, listing involved slugs.
+ */
+export declare function sortSeedsByDependencies(seeds: ReadonlyArray<Seed>): Seed[];
+//# sourceMappingURL=seed-registry.d.ts.map

package/dist/engine/seed-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../../src/engine/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAI9C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,IAAI,IAAI,EAAE,CAAA;IAEb;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9B;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,IAAI,IAAI,EAAE,CAAA;IAExB;;;OAGG;IACH,YAAY,IAAI,IAAI,EAAE,CAAA;CACvB;AAID,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,KAAK,EAAE,IAAI,EAAE;IAkCzB,GAAG,IAAI,IAAI,EAAE;IAIb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI9B,kBAAkB,IAAI,IAAI,EAAE;IAI5B,cAAc,IAAI,IAAI,EAAE;IAIxB,YAAY,IAAI,IAAI,EAAE;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG;AAEzD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,MAAM,CAQjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CA0F1E"}

package/dist/engine/seed-registry.js

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { AUTOMATION_RESERVED_WORDS } from '../automations/automations-grammar-words.js';
+import { SQL_RESERVED_WORDS } from './sql-reserved-words.js';
+const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
+export class SeedRegistry {
+    seedMap;
+    orderedSeeds;
+    constructor(seeds) {
+        for (const seed of seeds) {
+            const idsInSeed = new Set();
+            for (const branch of seed.branches) {
+                if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
+                    throw new Error(`Seed "${seed.slug}" uses reserved alias "${branch.alias}". `
+                        + `Pick a different alias — this word is used by the automation template grammar.`);
+                }
+                if (SQL_RESERVED_WORDS.has(branch.alias.toLowerCase())) {
+                    throw new Error(`Seed "${seed.slug}" uses SQL reserved keyword "${branch.alias}". `
+                        + `Please pick a different alias to prevent database errors.`);
+                }
+                if (!branch.id || !BRANCH_ID_RE.test(branch.id)) {
+                    throw new Error(`Seed "${seed.slug}" branch "${branch.alias}" has invalid id "${branch.id}". `
+                        + `Expected format ^br_[A-Za-z0-9]+$.`);
+                }
+                if (idsInSeed.has(branch.id)) {
+                    throw new Error(`Seed "${seed.slug}" has duplicate branch id "${branch.id}".`);
+                }
+                idsInSeed.add(branch.id);
+            }
+        }
+        this.orderedSeeds = seeds;
+        this.seedMap = new Map(seeds.map(seed => [seed.slug, seed]));
+    }
+    all() {
+        return this.orderedSeeds;
+    }
+    get(slug) {
+        return this.seedMap.get(slug) ?? null;
+    }
+    visibleInDashboard() {
+        return this.orderedSeeds.filter(seed => seed.dashboard?.hidden !== true);
+    }
+    publicReadable() {
+        return this.orderedSeeds.filter(seed => seed.allowPublicRead === true);
+    }
+    draftEnabled() {
+        return this.orderedSeeds.filter(seed => seed.allowDrafts === true);
+    }
+}
+/**
+ * Named subclass of SeedRegistry for use in test suites.
+ * Gives tests a semantic name without requiring any dependency on factory.ts.
+ */
+export class InMemorySeedRegistry extends SeedRegistry {
+}
+/** Finds a branch by its stable id within a Seed. Returns null if not found. */
+export function findBranchById(seed, id) {
+    return seed.branches.find(b => b.id === id) ?? null;
+}
+/**
+ * Returns the next free branch id for a seed in the form `br_NN` (zero-padded to 2,
+ * growing as needed). Scans existing ids, never reuses a number already present —
+ * even if a branch was removed, its id is not recycled (ids must be globally stable
+ * for the life of the seed so layouts/automations/FTS triggers never collide).
+ */
+export function nextBranchId(seed) {
+    let max = 0;
+    for (const b of seed.branches) {
+        const m = /^br_0*([0-9]+)$/.exec(b.id);
+        if (m)
+            max = Math.max(max, parseInt(m[1], 10));
+    }
+    const n = max + 1;
+    return `br_${String(n).padStart(2, '0')}`;
+}
+/**
+ * Returns the input seeds reordered so that every seed appears AFTER all the
+ * seeds it depends on (its `relation` branch targets). Pure function — does
+ * not read from any global registry.
+ *
+ * Uses Kahn's algorithm (BFS on in-degree) for cycle detection and topological
+ * ordering. Sprint 3 (CLI / migration runner) consumes this to create tables in
+ * the correct order without disabling SQLite FK constraints.
+ *
+ * @throws {Error} When a relation targets an unknown slug not in `seeds`.
+ * @throws {Error} When a cyclic dependency is detected, listing involved slugs.
+ */
+export function sortSeedsByDependencies(seeds) {
+    const slugSet = new Set(seeds.map(s => s.slug));
+    // Validate all relation targets exist in the input array
+    for (const seed of seeds) {
+        for (const branch of seed.branches) {
+            if (branch.type === 'relation' && branch.targetSeed) {
+                if (!slugSet.has(branch.targetSeed)) {
+                    throw new Error(`Seed '${seed.slug}' relates to unknown target '${branch.targetSeed}'`);
+                }
+            }
+        }
+    }
+    // Build adjacency: inDegree[slug] = number of dependencies
+    //                  dependents[slug] = slugs that depend on slug
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const seed of seeds) {
+        if (!inDegree.has(seed.slug))
+            inDegree.set(seed.slug, 0);
+        if (!dependents.has(seed.slug))
+            dependents.set(seed.slug, []);
+    }
+    for (const seed of seeds) {
+        // Deduplicate targets to avoid inflating inDegree on multi-branch refs to same seed
+        const targets = new Set(seed.branches
+            .filter(b => b.type === 'relation' && b.targetSeed)
+            .map(b => b.targetSeed));
+        for (const target of targets) {
+            if (target === seed.slug)
+                continue; // self-reference needs no ordering
+            // seed depends on target → increment seed's in-degree
+            inDegree.set(seed.slug, (inDegree.get(seed.slug) ?? 0) + 1);
+            dependents.get(target).push(seed.slug);
+        }
+    }
+    // Kahn's BFS: start with seeds that have no dependencies
+    const seedBySlug = new Map(seeds.map(s => [s.slug, s]));
+    const queue = [];
+    for (const [slug, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(slug);
+    }
+    const result = [];
+    while (queue.length > 0) {
+        const slug = queue.shift();
+        result.push(seedBySlug.get(slug));
+        for (const dependent of dependents.get(slug) ?? []) {
+            const newDeg = (inDegree.get(dependent) ?? 0) - 1;
+            inDegree.set(dependent, newDeg);
+            if (newDeg === 0)
+                queue.push(dependent);
+        }
+    }
+    if (result.length !== seeds.length) {
+        // Isolate true cycle members
+        const stuck = new Set([...inDegree.entries()]
+            .filter(([, deg]) => deg > 0)
+            .map(([slug]) => slug));
+        const cycleNodes = [...stuck].filter(slug => {
+            const visited = new Set();
+            const queue = [...(dependents.get(slug) ?? [])].filter(s => stuck.has(s));
+            while (queue.length > 0) {
+                const curr = queue.shift();
+                if (curr === slug)
+                    return true;
+                if (!visited.has(curr)) {
+                    visited.add(curr);
+                    for (const next of dependents.get(curr) ?? []) {
+                        if (stuck.has(next))
+                            queue.push(next);
+                    }
+                }
+            }
+            return false;
+        });
+        const cycle = (cycleNodes.length > 0 ? cycleNodes : [...stuck]).sort();
+        throw new Error(`Cyclic dependency detected among seeds: ${cycle.join(', ')}`);
+    }
+    return result;
+}

package/dist/engine/seed-types-generator.d.ts

@@ -0,0 +1,25 @@
+import type { Seed, Branch } from './types.js';
+/** slug/alias → PascalCase identifier. 'blog-posts' → 'BlogPosts'. */
+export declare function pascalCase(input: string): string;
+/** Maps a single Branch to its TypeScript type expression (no optional marker). */
+export declare function tsTypeForBranch(branch: Branch): string;
+/** Emits one exported interface for a single Seed. */
+export declare function interfaceForSeed(seed: Seed): string;
+/** Options that affect the emitted module beyond the seed interfaces themselves. */
+export interface SeedTypesOptions {
+    /**
+     * Schema fingerprint to embed as `SCHEMA_FINGERPRINT`, from `computeSchemaFingerprint`.
+     * Omitted ⇒ no constant is emitted and the output is byte-identical to a pre-fingerprint build,
+     * which is what keeps the legacy `beech gen-types` aliases non-breaking.
+     */
+    fingerprint?: string;
+}
+/**
+ * Pure entry point. Deterministic: sorts seeds by slug for stable diffs.
+ *
+ * The embedded fingerprint is the client's half of the drift check: `@beechcms/client` compares it
+ * against the `X-Schema-Revision` header the API returns and raises an actionable error on a
+ * mismatch, instead of trusting a stale response shape.
+ */
+export declare function generateSeedTypes(seeds: Seed[], options?: SeedTypesOptions): string;
+//# sourceMappingURL=seed-types-generator.d.ts.map

package/dist/engine/seed-types-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-types-generator.d.ts","sourceRoot":"","sources":["../../src/engine/seed-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAe9C,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMhD;AAMD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoCtD;AAWD,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYnD;AAKD,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAcvF"}