@beechcms/core 0.7.0 → 0.8.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../src/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAG9C,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;IA4BzB,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,CAsE1E"}

package/dist/seed-registry.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { AUTOMATION_RESERVED_WORDS } from './automations-grammar-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 (!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) {
+            // 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) {
+        // Cycle exists — collect participating slugs (those with in-degree > 0 after BFS)
+        const cycle = [...inDegree.entries()]
+            .filter(([, deg]) => deg > 0)
+            .map(([slug]) => slug)
+            .sort();
+        throw new Error(`Cyclic dependency detected among seeds: ${cycle.join(', ')}`);
+    }
+    return result;
+}

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

@@ -1,4 +1,4 @@
-import type { Seed, Branch } from './engine/types.js';
+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). */

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

@@ -1 +1 @@
-{"version":3,"file":"seed-types-generator.d.ts","sourceRoot":"","sources":["../src/seed-types-generator.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAerD,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;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CASvD"}
+{"version":3,"file":"seed-types-generator.d.ts","sourceRoot":"","sources":["../src/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;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CASvD"}

package/dist/seed-validation.d.ts

@@ -0,0 +1,23 @@
+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;
+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/seed-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../src/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAErD,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,CA0N5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}

package/dist/seed-validation.js

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { AUTOMATION_RESERVED_WORDS } from './automations-grammar-words.js';
+import { sortSeedsByDependencies } from './seed-registry.js';
+const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
+/**
+ * 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 const BRANCH_ALIAS_RE = /^[a-z][a-zA-Z0-9_]*$/;
+/**
+ * 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 function validateSeedDefinitions(seeds) {
+    const result = [];
+    // ── Fatal 1: unknown relation targets ────────────────────────────────────
+    const slugSet = new Set(seeds.map(s => s.slug));
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (branch.type === 'relation' && branch.targetSeed) {
+                if (!slugSet.has(branch.targetSeed)) {
+                    messages.push(`branch '${branch.alias}' targets unknown seed '${branch.targetSeed}'`);
+                }
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 2: multi-relation with SET NULL ────────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (branch.type === 'relation' && branch.multiple === true && branch.onDelete === 'SET NULL') {
+                messages.push(`Branch '${branch.alias}': multi-relations cannot use ON DELETE SET NULL. ` +
+                    `Use 'CASCADE' or 'RESTRICT'.`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 3: junction table name collisions / length ─────────────────────
+    {
+        const junctionNames = new Set();
+        for (const seed of seeds) {
+            const messages = [];
+            for (const branch of seed.branches) {
+                if (branch.type !== 'relation' || branch.multiple !== true)
+                    continue;
+                const name = `rel_${seed.slug}_${branch.alias}`;
+                if (name.length > 256) {
+                    messages.push(`Junction table name '${name}' exceeds 256 characters (${name.length})`);
+                }
+                if (junctionNames.has(name)) {
+                    messages.push(`Junction table name collision: '${name}' already used by another seed/branch`);
+                }
+                junctionNames.add(name);
+            }
+            if (messages.length > 0)
+                result.push({ slug: seed.slug, messages, fatal: true });
+        }
+    }
+    // ── Fatal 4: dependency cycles ────────────────────────────────────────────
+    const hasUnknownTargets = result.some(e => e.fatal);
+    if (!hasUnknownTargets) {
+        try {
+            sortSeedsByDependencies(seeds);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            result.push({ slug: '<graph>', messages: [msg], fatal: true });
+        }
+    }
+    // ── Fatal 5: branch id format / uniqueness ───────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        const idsInSeed = new Set();
+        for (const branch of seed.branches) {
+            if (!branch.id || !BRANCH_ID_RE.test(branch.id)) {
+                messages.push(`branch '${branch.alias}' has invalid id '${branch.id}'. Expected format ^br_[A-Za-z0-9]+$.`);
+            }
+            else if (idsInSeed.has(branch.id)) {
+                messages.push(`duplicate branch id '${branch.id}'`);
+            }
+            if (branch.id)
+                idsInSeed.add(branch.id);
+            // Alias becomes a raw SQL column name — reject anything outside the safe
+            // identifier charset before it can reach DDL/query string interpolation.
+            if (typeof branch.alias !== 'string' || !BRANCH_ALIAS_RE.test(branch.alias)) {
+                messages.push(`branch alias '${branch.alias}' is invalid. Expected format ${BRANCH_ALIAS_RE.source} ` +
+                    `(lowercase letter followed by alphanumeric characters or underscores).`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 6: reserved aliases ─────────────────────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
+                messages.push(`branch '${branch.alias}' uses reserved alias. ` +
+                    `This word is used by the automation template grammar.`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 10: repeater sub-field constraints ─────────────────────────────
+    {
+        const REPEATER_DISALLOWED_SUBTYPES = new Set(['repeater', 'relation', 'file']);
+        for (const seed of seeds) {
+            const messages = [];
+            for (const branch of seed.branches) {
+                if (branch.type !== 'repeater')
+                    continue;
+                const subIds = new Set();
+                const subAliases = new Set();
+                for (const sub of branch.fields ?? []) {
+                    if (REPEATER_DISALLOWED_SUBTYPES.has(sub.type)) {
+                        messages.push(`branch '${branch.alias}': sub-field '${sub.alias}' has disallowed type '${sub.type}'. ` +
+                            `Repeater sub-fields cannot be 'repeater', 'relation', or 'file' in v1.`);
+                    }
+                    if (!sub.id || !BRANCH_ID_RE.test(sub.id)) {
+                        messages.push(`branch '${branch.alias}': sub-field '${sub.alias}' has invalid id '${sub.id}'. ` +
+                            `Expected format ^br_[A-Za-z0-9]+$.`);
+                    }
+                    else if (subIds.has(sub.id)) {
+                        messages.push(`branch '${branch.alias}': duplicate sub-field id '${sub.id}'`);
+                    }
+                    if (sub.id)
+                        subIds.add(sub.id);
+                    if (typeof sub.alias !== 'string' || !BRANCH_ALIAS_RE.test(sub.alias)) {
+                        messages.push(`branch '${branch.alias}': sub-field alias '${sub.alias}' is invalid. ` +
+                            `Expected format ${BRANCH_ALIAS_RE.source}.`);
+                    }
+                    else if (subAliases.has(sub.alias)) {
+                        messages.push(`branch '${branch.alias}': duplicate sub-field alias '${sub.alias}'`);
+                    }
+                    subAliases.add(sub.alias);
+                }
+            }
+            if (messages.length > 0)
+                result.push({ slug: seed.slug, messages, fatal: true });
+        }
+    }
+    // ── Warning 7: duplicate slug ─────────────────────────────────────────────
+    {
+        const slugsSeen = new Set();
+        for (const seed of seeds) {
+            const messages = [];
+            if (slugsSeen.has(seed.slug)) {
+                messages.push(`duplicate slug "${seed.slug}" — each seed must have a unique slug`);
+            }
+            slugsSeen.add(seed.slug);
+            if (messages.length > 0)
+                result.push({ slug: seed.slug, messages, fatal: false });
+        }
+    }
+    // ── Warning 8: duplicate branch alias within a seed ───────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        const aliasesSeen = new Set();
+        for (const branch of seed.branches) {
+            if (aliasesSeen.has(branch.alias)) {
+                messages.push(`duplicate branch alias "${branch.alias}"`);
+            }
+            aliasesSeen.add(branch.alias);
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: false });
+    }
+    // ── Warning 9: displayNameAlias not in branches ───────────────────────────
+    for (const seed of seeds) {
+        const allAliases = new Set(seed.branches.map(b => b.alias));
+        if (!allAliases.has(seed.displayNameAlias)) {
+            result.push({
+                slug: seed.slug,
+                messages: [`displayNameAlias "${seed.displayNameAlias}" not found in branches`],
+                fatal: false,
+            });
+        }
+    }
+    // ── Fatal 11 / Warning 10: repeater cardinality bounds ───────────────────
+    {
+        for (const seed of seeds) {
+            const fatals = [];
+            const warnings = [];
+            for (const branch of seed.branches) {
+                const hasBounds = branch.minItems !== undefined || branch.maxItems !== undefined;
+                if (!hasBounds)
+                    continue;
+                if (branch.type !== 'repeater') {
+                    warnings.push(`branch '${branch.alias}': minItems/maxItems are ignored on type ` +
+                        `'${branch.type}' (repeater-only).`);
+                    continue;
+                }
+                for (const [key, val] of [['minItems', branch.minItems], ['maxItems', branch.maxItems]]) {
+                    if (val !== undefined && (!Number.isInteger(val) || val < 0)) {
+                        fatals.push(`branch '${branch.alias}': ${key} must be a non-negative integer (got ${val}).`);
+                    }
+                }
+                if (Number.isInteger(branch.minItems) && Number.isInteger(branch.maxItems) &&
+                    branch.minItems > branch.maxItems) {
+                    fatals.push(`branch '${branch.alias}': minItems (${branch.minItems}) must be <= maxItems (${branch.maxItems}).`);
+                }
+            }
+            if (fatals.length > 0)
+                result.push({ slug: seed.slug, messages: fatals, fatal: true });
+            if (warnings.length > 0)
+                result.push({ slug: seed.slug, messages: warnings, fatal: false });
+        }
+    }
+    return result;
+}
+/** Convenience: true iff no fatal issues. */
+export function isSeedSetValid(seeds) {
+    return validateSeedDefinitions(seeds).every(i => !i.fatal);
+}

package/dist/seed.repository.d.ts

@@ -0,0 +1,37 @@
+import type { Seed } from './types.js';
+export interface SeedRecord {
+    slug: string;
+    definition: Seed;
+    status: 'active' | 'deleted';
+    source: 'code' | 'runtime';
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Persistence contract for runtime Seed definitions.
+ * Implemented by D1SeedRepository in apps/api/src/shared/seed.repository.d1.ts.
+ *
+ * `listActive()` returns only status='active' rows — this is what the registry is
+ * hydrated from. `getRegistryVersion` / `bumpRegistryVersion` back the multi-isolate
+ * cache token (see docs/Sprints/runtime-seeds/00-overview.md).
+ */
+export interface ISeedRepository {
+    /** All active seed definitions, ordered by created_at ASC. */
+    listActive(): Promise<Seed[]>;
+    /** Every row including soft-deleted ones (for admin/diff use). */
+    listAll(): Promise<SeedRecord[]>;
+    /** Single active-or-deleted record by slug, or null. */
+    get(slug: string): Promise<SeedRecord | null>;
+    /** Insert or replace a definition. Sets source on insert; preserves it on update unless given. */
+    upsert(slug: string, definition: Seed, source?: 'code' | 'runtime'): Promise<void>;
+    /** Soft-delete: set status='deleted'. Table is NOT dropped (additive-only). */
+    softDelete(slug: string): Promise<void>;
+    /** Hard-delete (sprint 06): permanently remove the `seeds` row. The caller is
+     *  responsible for dropping the backing tables first via ISchemaMutator. */
+    hardDelete(slug: string): Promise<void>;
+    /** Current cache token. */
+    getRegistryVersion(): Promise<number>;
+    /** Atomically increment and return the new token. Call after any write. */
+    bumpRegistryVersion(): Promise<number>;
+}
+//# sourceMappingURL=seed.repository.d.ts.map

package/dist/seed.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.repository.d.ts","sourceRoot":"","sources":["../src/seed.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,IAAI,CAAA;IAChB,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,UAAU,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IAC7B,kEAAkE;IAClE,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAChC,wDAAwD;IACxD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC7C,kGAAkG;IAClG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClF,+EAA+E;IAC/E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC;gFAC4E;IAC5E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,2BAA2B;IAC3B,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACrC,2EAA2E;IAC3E,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACvC"}

package/dist/seed.repository.js

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

package/dist/seeds.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Seed Registry: configurazione degli schemi di contenuto.
+ * In v0.4.0 ogni Seed genera una tabella `content_{slug}` con colonne reali.
+ * `branch.alias` è il nome della colonna SQL.
+ */
+import type { Seed } from './types.js';
+/**
+ * Registro globale dei Seed.
+ * In produzione, questo viene popolato dalle definizioni dell'utente.
+ */
+export declare const SEED_REGISTRY: Record<string, Seed>;
+/**
+ * Registra un set di Seed nel registro globale.
+ */
+export declare function registerSeeds(seeds: Seed[]): void;
+/**
+ * Ritorna il Seed per lo slug dato, o null se non esiste.
+ */
+export declare function getSeed(slug: string): Seed | null;
+//# sourceMappingURL=seeds.d.ts.map

package/dist/seeds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../src/seeds.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAM,CAAA;AAErD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,QAI1C;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjD"}

package/dist/seeds.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Registro globale dei Seed.
+ * In produzione, questo viene popolato dalle definizioni dell'utente.
+ */
+export const SEED_REGISTRY = {};
+/**
+ * Registra un set di Seed nel registro globale.
+ */
+export function registerSeeds(seeds) {
+    seeds.forEach(seed => {
+        SEED_REGISTRY[seed.slug] = seed;
+    });
+}
+/**
+ * Ritorna il Seed per lo slug dato, o null se non esiste.
+ */
+export function getSeed(slug) {
+    return SEED_REGISTRY[slug] ?? null;
+}

package/dist/site-settings.repository.d.ts

@@ -0,0 +1,16 @@
+export interface SiteSettings {
+    siteTitle: string;
+    defaultLanguage: string;
+    timezone: string;
+    currency: string;
+    companyName: string | null;
+    companyWebsite: string | null;
+    companyAbbreviation: string | null;
+}
+export interface ISiteSettingsRepository {
+    /** Returns all stored settings, applying sensible defaults for missing keys. */
+    getAll(): Promise<SiteSettings>;
+    /** Upserts the provided keys. Partial update — unspecified keys are untouched. */
+    setMany(values: Partial<SiteSettings>): Promise<void>;
+}
+//# sourceMappingURL=site-settings.repository.d.ts.map

package/dist/site-settings.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-settings.repository.d.ts","sourceRoot":"","sources":["../src/site-settings.repository.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAA;IAC/B,kFAAkF;IAClF,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtD"}

package/dist/site-settings.repository.js

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

package/dist/slug-utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Utility per la gestione degli slug.
+ * Condivisa tra Dashboard e API pubbliche.
+ */
+/**
+ * Converte una stringa in uno slug URL-safe.
+ * Limita la lunghezza a 15 caratteri come richiesto.
+ */
+export declare function slugify(value: string): string;
+/**
+ * Genera uno slug da un input (es. titolo o nome) o un fallback UUID.
+ */
+export declare function generateEntrySlug(input: {
+    slug?: string;
+    title?: unknown;
+    name?: unknown;
+}): string;
+//# sourceMappingURL=slug-utils.d.ts.map

package/dist/slug-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug-utils.d.ts","sourceRoot":"","sources":["../src/slug-utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU7C;AAGD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CASnG"}

package/dist/slug-utils.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Utility per la gestione degli slug.
+ * Condivisa tra Dashboard e API pubbliche.
+ */
+/**
+ * Converte una stringa in uno slug URL-safe.
+ * Limita la lunghezza a 15 caratteri come richiesto.
+ */
+export function slugify(value) {
+    return value
+        .normalize('NFKD') // Normalizza caratteri accentati
+        .replace(/[^\w\s-]/g, '') // Rimuove tutto ciò che non è alfanumerico
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_-]+/g, '-') // Sostituisce spazi e underscore con trattino
+        .replace(/^-+|-+$/g, '') // Rimuove trattini all'inizio o alla fine
+        .slice(0, 15) // Limita a 15 caratteri
+        .replace(/-+$/g, ''); // Rimuove trattini rimasti alla fine dopo il taglio
+}
+/**
+ * Genera uno slug da un input (es. titolo o nome) o un fallback UUID.
+ */
+export function generateEntrySlug(input) {
+    const candidate = (typeof input.slug === 'string' && input.slug) ||
+        (typeof input.title === 'string' && input.title) ||
+        (typeof input.name === 'string' && input.name) ||
+        Math.random().toString(36).slice(2, 10); // Fallback compatto se crypto non disponibile (o slice 8)
+    const normalized = slugify(candidate);
+    return normalized || Math.random().toString(36).slice(2, 10);
+}