@beechcms/core 0.8.0 → 0.8.1

package/dist/engine/schema-fingerprint.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module engine/schema-fingerprint
+ * A deterministic name for "the shape this API answers in".
+ *
+ * Computed from live seed definitions (`introspectSeedDefinitions`), embedded in generated client
+ * types at build time (sprint 3), returned on every public response as `X-Schema-Revision`
+ * (sprint 4), and compared by the client at request time (sprint 5). Both ends MUST compute it
+ * with this function — two implementations would be free to disagree, and a drift detector whose
+ * ends disagree is worse than none.
+ *
+ * What is hashed is a CONTRACT PROJECTION, not the whole seed definition: labels, hints, dashboard
+ * icons and layout cannot change a single response byte, and hashing them would fire a hard
+ * `BeechProblem` in someone else's production client over a typo fix.
+ */
+import { canonicalStringify } from '../common/canonical-json.js';
+import { resolvePolicies } from './policies.js';
+/**
+ * Bumped ONLY when the projection below or the canonical byte format changes — i.e. when
+ * fingerprints computed by two builds are no longer comparable. It is carried in the fingerprint
+ * string itself so a version skew reads as a mismatch instead of as an accidental match.
+ */
+export const SCHEMA_FINGERPRINT_VERSION = 1;
+function projectBranch(branch) {
+    const policies = resolvePolicies(branch);
+    return {
+        alias: branch.alias,
+        type: branch.type,
+        ...(branch.format !== undefined ? { format: branch.format } : {}),
+        ...(branch.multiple !== undefined ? { multiple: branch.multiple } : {}),
+        // Option order is the contract: it is the order a select renders and a union type lists.
+        ...(branch.options !== undefined ? { options: [...branch.options] } : {}),
+        requiredOnCreate: branch.requiredOnCreate ?? false,
+        requiredOnUpdate: branch.requiredOnUpdate ?? false,
+        ...(branch.targetSeed !== undefined ? { targetSeed: branch.targetSeed } : {}),
+        visibility: policies.visibility,
+        publicRead: policies.public,
+        publicEdit: policies.publicEdit,
+        ...(branch.minItems !== undefined ? { minItems: branch.minItems } : {}),
+        ...(branch.maxItems !== undefined ? { maxItems: branch.maxItems } : {}),
+        // Spread only when true so every schema without localized branches keeps its fingerprint.
+        ...(branch.localized === true ? { localized: true } : {}),
+        ...(branch.fields ? { fields: branch.fields.map(projectBranch) } : {}),
+    };
+}
+/**
+ * Reduces seeds to what a response shape depends on.
+ *
+ * Deliberately EXCLUDED, and each for a reason a future reader must not "fix":
+ * - `id` (`br_XX`) — a stable internal handle; it never appears in a payload, and minting order
+ *   differs between an environment built by migration and one grown through the dashboard.
+ * - `label`, `labelPlural`, `hint`, `dashboard`, `layout` — presentation, never response shape.
+ * - `retentionDays`, `onDelete`, `policies.search|filter|sort`, `numberOptions`, `fileOptions`,
+ *   `policies.classification|privacy` — behaviour and storage concerns that leave the response
+ *   shape identical. (`privacy` DOES change a stored value's encoding, but the API type stays
+ *   `string`; drift there is a data concern, not a type concern.)
+ * - anything physical (column order, index names) — see the VETO Audit.
+ *
+ * Seeds are sorted by slug; BRANCH ORDER IS PRESERVED, because it is the declared field order the
+ * generated types and the dashboard form both follow.
+ */
+export function projectSchemaContract(seeds) {
+    return {
+        fingerprintVersion: SCHEMA_FINGERPRINT_VERSION,
+        seeds: [...seeds]
+            .sort((a, b) => a.slug.localeCompare(b.slug))
+            .map(seed => ({
+            slug: seed.slug,
+            displayNameAlias: seed.displayNameAlias,
+            allowDrafts: seed.allowDrafts ?? false,
+            allowPublicRead: seed.allowPublicRead ?? false,
+            allowPublicPost: seed.allowPublicPost ?? false,
+            allowPublicEdit: seed.allowPublicEdit ?? false,
+            branches: seed.branches.map(projectBranch),
+        })),
+    };
+}
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * `v{VERSION}:{32 lowercase hex}` — SHA-256 over the canonical JSON of the contract projection,
+ * truncated to 128 bits.
+ *
+ * Truncation is deliberate: this value travels on EVERY public response as `X-Schema-Revision`,
+ * and 128 bits of a SHA-256 digest carries no realistic collision risk for a value space of a few
+ * hundred schema revisions. It is a revision marker, never a security token.
+ *
+ * Web Crypto only — the same API the Worker and Node ≥ 18 both expose, as `webhook-crypto.ts`
+ * already relies on. `@beechcms/core` gains no dependency.
+ */
+export async function computeSchemaFingerprint(seeds) {
+    const bytes = new TextEncoder().encode(canonicalStringify(projectSchemaContract(seeds)));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return `v${SCHEMA_FINGERPRINT_VERSION}:${toHex(digest).slice(0, 32)}`;
+}

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

@@ -1 +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"}
+{"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;IAErC,YAAY,KAAK,EAAE,IAAI,EAAE,EAgCxB;IAED,GAAG,IAAI,IAAI,EAAE,CAEZ;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE7B;IAED,kBAAkB,IAAI,IAAI,EAAE,CAE3B;IAED,cAAc,IAAI,IAAI,EAAE,CAEvB;IAED,YAAY,IAAI,IAAI,EAAE,CAErB;CACF;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/seeds/define-seed.d.ts

@@ -0,0 +1,3 @@
+import type { Seed } from '../types.js';
+export declare function defineSeed(seed: Seed): Seed;
+//# sourceMappingURL=define-seed.d.ts.map

package/dist/engine/seeds/define-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-seed.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/define-seed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE3C"}

package/dist/engine/seeds/define-seed.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export function defineSeed(seed) {
+    return seed;
+}

package/dist/engine/seeds/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/seeds/seed-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAI/C,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/seeds/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/seeds/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/seeds/seed-types-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-types-generator.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAe/C,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"}

package/dist/engine/seeds/seed-types-generator.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+const HEADER = '// Questo file è generato automaticamente da BeechCMS CLI. Non modificarlo direttamente.\n';
+/** System columns emitted by generateCreateTable — always present, never optional. */
+const SYSTEM_FIELDS = `  id: string\n` +
+    `  slug: string\n` +
+    `  status: 'draft' | 'review' | 'published' | 'archived'\n`;
+const SYSTEM_TIMESTAMPS = `  created_at: number\n` +
+    `  updated_at: number\n`;
+/** slug/alias → PascalCase identifier. 'blog-posts' → 'BlogPosts'. */
+export function pascalCase(input) {
+    return input
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('');
+}
+function literalUnion(options) {
+    return options.map(o => `'${o.replace(/'/g, "\\'")}'`).join(' | ');
+}
+/** Maps a single Branch to its TypeScript type expression (no optional marker). */
+export function tsTypeForBranch(branch) {
+    switch (branch.type) {
+        case 'number':
+        case 'date':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'json':
+            return 'unknown';
+        case 'text':
+        case 'richtext':
+        case 'file': {
+            const base = branch.type === 'text' && branch.options?.length
+                ? literalUnion(branch.options)
+                : 'string';
+            return branch.type === 'file' && branch.multiple ? `${base}[]` : base;
+        }
+        case 'tags': {
+            const base = branch.options?.length ? `(${literalUnion(branch.options)})` : 'string';
+            return `${base}[]`;
+        }
+        case 'relation':
+            return branch.multiple ? 'string[]' : 'string';
+        case 'repeater': {
+            const inner = (branch.fields ?? [])
+                .map(f => `${propName(f)}${optional(f)}: ${tsTypeForBranch(f)}`)
+                .join('; ');
+            return `Array<{ ${inner} }>`;
+        }
+        default: {
+            // Exhaustiveness guard — fails the build if BranchType gains a member.
+            const _never = branch.type;
+            return _never;
+        }
+    }
+}
+function optional(branch) {
+    return branch.requiredOnCreate ? '' : '?';
+}
+function propName(branch) {
+    // alias is a valid SQL column; quote only if not a plain identifier.
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(branch.alias) ? branch.alias : `'${branch.alias}'`;
+}
+/** Emits one exported interface for a single Seed. */
+export function interfaceForSeed(seed) {
+    const name = pascalCase(seed.slug);
+    const props = seed.branches
+        .map(b => `  ${propName(b)}${optional(b)}: ${tsTypeForBranch(b)}`)
+        .join('\n');
+    return (`export interface ${name} {\n` +
+        SYSTEM_FIELDS +
+        (props ? props + '\n' : '') +
+        SYSTEM_TIMESTAMPS +
+        `}\n`);
+}
+/** `v{version}:{32 hex}` — the exact shape `computeSchemaFingerprint` returns. */
+const FINGERPRINT_RE = /^v\d+:[0-9a-f]{32}$/;
+/**
+ * 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 function generateSeedTypes(seeds, options = {}) {
+    const sorted = [...seeds].sort((a, b) => a.slug.localeCompare(b.slug));
+    const interfaces = sorted.map(interfaceForSeed).join('\n');
+    const registryProps = sorted
+        .map(s => `  ${propName({ alias: s.slug })}: ${pascalCase(s.slug)}`)
+        .join('\n');
+    const databaseRegistry = `export interface BeechDatabase {\n` +
+        (registryProps ? registryProps + '\n' : '') +
+        `}\n\n` +
+        `export type SeedRegistryTypes = BeechDatabase\n`;
+    return `${HEADER}\n${fingerprintBlock(options.fingerprint)}${interfaces}\n${databaseRegistry}`;
+}
+/**
+ * Emits the fingerprint constant, or nothing.
+ *
+ * The value is interpolated into source, so its shape is verified first: a fingerprint carrying a
+ * quote or a newline would emit a file that does not parse, and the failure would surface in the
+ * consumer's build rather than here.
+ */
+function fingerprintBlock(fingerprint) {
+    if (fingerprint === undefined)
+        return '';
+    if (!FINGERPRINT_RE.test(fingerprint)) {
+        throw new Error(`Refusing to embed '${fingerprint}' as a schema fingerprint: expected the v{n}:{32 hex} form produced by computeSchemaFingerprint().`);
+    }
+    return (`/**\n` +
+        ` * Schema revision these types were generated from. \`@beechcms/client\` compares it against the\n` +
+        ` * \`X-Schema-Revision\` response header; a mismatch means the backend schema moved and this file\n` +
+        ` * must be regenerated with \`beech types generate\`.\n` +
+        ` */\n` +
+        `export const SCHEMA_FINGERPRINT = '${fingerprint}'\n\n`);
+}

package/dist/engine/seeds/seed-validation.d.ts

@@ -0,0 +1,30 @@
+import type { Seed } from '../types.js';
+/**
+ * Allowed charset for a branch alias. An alias becomes a raw SQL column name in
+ * CREATE TABLE / ADD COLUMN / CREATE INDEX and in SELECT/WHERE/ORDER BY clauses
+ * (see engine.ts), so it MUST be restricted to a safe identifier charset to
+ * prevent DDL/query injection. Exported so the seeds API rename route reuses the
+ * exact same guard — do not inline a divergent copy.
+ */
+export declare const BRANCH_ALIAS_RE: RegExp;
+/**
+ * Allowed charset for a seed slug identifier.
+ * Must consist solely of lowercase ASCII letters, digits, and underscores.
+ * Exported so route handlers and validation functions reuse the exact same guard.
+ */
+export declare const SEED_SLUG_RE: RegExp;
+export declare const SLUG_RE: RegExp;
+export interface SeedValidationIssue {
+    slug: string;
+    messages: string[];
+    fatal: boolean;
+}
+/**
+ * Pure, console-free, throw-free validation of a seed set.
+ * The single seed being created/edited should be validated in the context of
+ * the full active set: call validateSeedDefinitions([...otherActiveSeeds, edited]).
+ */
+export declare function validateSeedDefinitions(seeds: Seed[]): SeedValidationIssue[];
+/** Convenience: true iff no fatal issues. */
+export declare function isSeedSetValid(seeds: Seed[]): boolean;
+//# sourceMappingURL=seed-validation.d.ts.map

package/dist/engine/seeds/seed-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAUvC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAErD;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAiB,CAAA;AAC1C,eAAO,MAAM,OAAO,QAAe,CAAA;AAGnC,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,mBAAmB,EAAE,CAkW5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}