@beechcms/core 0.8.0 → 0.8.1

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

@@ -0,0 +1,364 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { AUTOMATION_RESERVED_WORDS } from '../../automations/automations-grammar-words.js';
+import { SYSTEM_COLUMNS } from '../ddl/ddl.js';
+import { LOCALIZABLE_BRANCH_TYPES } from '../localization/localization.js';
+import { resolveClassification } from '../privacy/policies.js';
+import { sortSeedsByDependencies } from './seed-registry.js';
+import { SQL_RESERVED_WORDS } from '../sql-reserved-words.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_]*$/;
+/**
+ * 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 const SEED_SLUG_RE = /^[a-z0-9_]+$/;
+export const SLUG_RE = SEED_SLUG_RE;
+/**
+ * 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);
+            const cycleMatch = msg.match(/Cyclic dependency detected among seeds: (.*)/);
+            if (cycleMatch) {
+                const cycleSlugs = cycleMatch[1].split(', ');
+                for (const slug of cycleSlugs) {
+                    result.push({ slug, messages: [msg], fatal: true });
+                }
+            }
+            else {
+                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 (SYSTEM_COLUMNS.has(branch.alias)) {
+                messages.push(`branch '${branch.alias}' collides with reserved system column. ` +
+                    `System columns (id, slug, status, created_at, updated_at) cannot be used as branch aliases.`);
+            }
+            else if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
+                messages.push(`branch '${branch.alias}' uses reserved alias. ` +
+                    `This word is used by the automation template grammar.`);
+            }
+            else if (SQL_RESERVED_WORDS.has(branch.alias.toLowerCase())) {
+                messages.push(`branch '${branch.alias}' uses SQL reserved keyword. ` +
+                    `Please pick a different alias to prevent database errors.`);
+            }
+        }
+        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 });
+        }
+    }
+    // ── Fatal 12: displayNameAlias format validation ───────────────────────────
+    for (const seed of seeds) {
+        if (typeof seed.displayNameAlias !== 'string' || !BRANCH_ALIAS_RE.test(seed.displayNameAlias)) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `displayNameAlias '${seed.displayNameAlias}' is invalid. Expected format ${BRANCH_ALIAS_RE.source} ` +
+                        `(lowercase letter followed by alphanumeric characters or underscores).`,
+                ],
+                fatal: true,
+            });
+        }
+        else if (SYSTEM_COLUMNS.has(seed.displayNameAlias)) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `displayNameAlias '${seed.displayNameAlias}' collides with reserved system column. ` +
+                        `System columns (id, slug, status, created_at, updated_at) cannot be used as displayNameAlias.`,
+                ],
+                fatal: true,
+            });
+        }
+        else if (SQL_RESERVED_WORDS.has(seed.displayNameAlias.toLowerCase())) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `displayNameAlias '${seed.displayNameAlias}' uses SQL reserved keyword. ` +
+                        `Please pick a different alias to prevent database errors.`,
+                ],
+                fatal: true,
+            });
+        }
+    }
+    // ── Fatal 13: retentionDays validation ─────────────────────────────────────
+    for (const seed of seeds) {
+        if (seed.retentionDays !== undefined && (!Number.isInteger(seed.retentionDays) || seed.retentionDays <= 0)) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `retentionDays must be a positive integer >= 1 (got ${seed.retentionDays}).`,
+                ],
+                fatal: true,
+            });
+        }
+    }
+    // ── Fatal 14: publicEdit validation ─────────────────────────────────────────
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (branch.policies?.publicEdit !== undefined && typeof branch.policies.publicEdit !== 'boolean') {
+                messages.push(`branch '${branch.alias}': policies.publicEdit must be a boolean`);
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    // ── Fatal 15: seed slug format validation ─────────────────────────────────
+    for (const seed of seeds) {
+        if (typeof seed.slug !== 'string' || !SEED_SLUG_RE.test(seed.slug)) {
+            result.push({
+                slug: seed.slug,
+                messages: [
+                    `slug '${seed.slug}' is invalid. Expected format ${SEED_SLUG_RE.source} ` +
+                        `(lowercase letters, numbers, and underscores only).`,
+                ],
+                fatal: true,
+            });
+        }
+    }
+    // ── Fatal 16: softDelete type validation ────────────────────────────────────
+    for (const seed of seeds) {
+        if (seed.softDelete !== undefined && typeof seed.softDelete !== 'boolean') {
+            result.push({
+                slug: seed.slug,
+                messages: [`softDelete must be a boolean (got ${typeof seed.softDelete}).`],
+                fatal: true,
+            });
+        }
+    }
+    // ── Fatal 17: field-level localization constraints ─────────────────────────
+    // A localized value is a readable locale dictionary. Encrypted or hashed storage turns it into an
+    // opaque blob: per-locale extraction would be meaningless and would break decryption. Repeater
+    // sub-fields are excluded by domain rule, whatever their type.
+    for (const seed of seeds) {
+        const messages = [];
+        for (const branch of seed.branches) {
+            if (branch.localized !== undefined && typeof branch.localized !== 'boolean') {
+                messages.push(`branch '${branch.alias}': localized must be a boolean`);
+            }
+            else if (branch.localized === true) {
+                if (!LOCALIZABLE_BRANCH_TYPES.has(branch.type)) {
+                    messages.push(`branch '${branch.alias}': localized is only supported on text, richtext and json branches ` +
+                        `(got '${branch.type}').`);
+                }
+                else {
+                    const { classification, storage } = resolveClassification(branch);
+                    if (storage !== 'plain') {
+                        messages.push(`branch '${branch.alias}': localized cannot be combined with '${classification}' classification ` +
+                            `(values are stored ${storage === 'encrypt' ? 'encrypted' : 'hashed'}).`);
+                    }
+                }
+            }
+            for (const sub of branch.fields ?? []) {
+                if (sub.localized !== undefined && sub.localized !== false) {
+                    messages.push(`branch '${branch.alias}': sub-field '${sub.alias}' cannot be localized. ` +
+                        `Repeater sub-fields are never localized.`);
+                }
+            }
+        }
+        if (messages.length > 0)
+            result.push({ slug: seed.slug, messages, fatal: true });
+    }
+    return result;
+}
+/** Convenience: true iff no fatal issues. */
+export function isSeedSetValid(seeds) {
+    return validateSeedDefinitions(seeds).every(i => !i.fatal);
+}

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

@@ -0,0 +1 @@
+{"version":3,"file":"seeds.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seeds.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC;;;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/engine/seeds/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/engine/validation/emptiness.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Checks if a value is effectively empty (e.g. null, undefined, empty string, empty array, or empty rich text).
+ *
+ * Shared by top-level required-field detection (`index.ts`) and repeater item validation
+ * (`schema-builders.ts`) so both tiers apply the same emptiness rule to required fields.
+ *
+ * @param value - The value to check.
+ * @param branchType - The type of the branch being checked.
+ * @returns True if effectively empty, false otherwise.
+ */
+export declare function isEffectivelyEmpty(value: unknown, branchType?: string): boolean;
+//# sourceMappingURL=emptiness.d.ts.map

package/dist/engine/validation/emptiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emptiness.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/emptiness.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAY/E"}

package/dist/engine/validation/emptiness.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { isRichtextEnvelopeV1 } from '../../content/richtext/richtext.js';
+import { cleanString, isPlainObject } from './primitives.js';
+import { isRichtextDocEmpty } from './richtext-sanitizer.js';
+/**
+ * Checks if a value is effectively empty (e.g. null, undefined, empty string, empty array, or empty rich text).
+ *
+ * Shared by top-level required-field detection (`index.ts`) and repeater item validation
+ * (`schema-builders.ts`) so both tiers apply the same emptiness rule to required fields.
+ *
+ * @param value - The value to check.
+ * @param branchType - The type of the branch being checked.
+ * @returns True if effectively empty, false otherwise.
+ */
+export function isEffectivelyEmpty(value, branchType) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return cleanString(value).length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (isPlainObject(value)) {
+        // Richtext envelope: delegate to the richtext emptiness check.
+        if (isRichtextEnvelopeV1(value))
+            return isRichtextDocEmpty(value.doc);
+        // Raw TipTap doc root: only delegate for richtext branches to avoid misclassifying generic json fields.
+        if (branchType === 'richtext' && value.type === 'doc')
+            return isRichtextDocEmpty(value);
+        return Object.keys(value).length === 0;
+    }
+    return false;
+}

package/dist/engine/validation/index.d.ts

@@ -91,7 +91,7 @@ export type ResolvedOptions = {
     idGenerator: IIdGenerator | undefined;
 };
 /** Set of valid content status values. */
-declare const STATUS_VALUES: readonly ["draft", "review", "published"];
+declare const STATUS_VALUES: readonly ['draft', 'review', 'published'];
 /**
  * Validates and sanitizes a seed payload against its schema definition.
  *

package/dist/engine/validation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAA;IAChB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC/B;;;OAGG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,+EAA+E;IAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,8FAA8F;IAC9F,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,4FAA4F;IAC5F,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC9B,2BAA2B,EAAE,OAAO,CAAA;IACpC,qBAAqB,EAAE,OAAO,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,YAAY,GAAG,SAAS,CAAA;CACtC,CAAA;AAKD,0CAA0C;AAC1C,QAAA,MAAM,aAAa,2CAA4C,CAAA;AA+R/D;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CAqD3B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAE5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAA;IAChB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC/B;;;OAGG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,+EAA+E;IAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,8FAA8F;IAC9F,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,4FAA4F;IAC5F,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC9B,2BAA2B,EAAE,OAAO,CAAA;IACpC,qBAAqB,EAAE,OAAO,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,YAAY,GAAG,SAAS,CAAA;CACtC,CAAA;AAKD,0CAA0C;AAC1C,QAAA,MAAM,aAAa,YAAI,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAA;AA+R/D;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CAqD3B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAE5F"}

package/dist/engine.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Botanical Engine: Schema Compiler + Query Builder.
+ *
+ * In v0.4.0 each Seed has a dedicated SQL table (`content_{slug}`) with
+ * real typed columns. This module generates the DDL and builds parameterized queries.
+ * It does not know about HTTP, auth, or UI — it's a pure TypeScript library.
+ */
+import type { Seed, Branch, SelectOptions, ParameterizedQuery } from './types.js';
+export declare function indexableSearchBranches(seed: Seed): Branch[];
+/**
+ * Generates `CREATE TABLE IF NOT EXISTS content_{slug}` with system columns
+ * + one column per Branch. Pure function: same Seed → same SQL.
+ */
+export declare function generateCreateTable(seed: Seed): string;
+/**
+ * Generates the drafts table `content_{slug}_drafts` for Seeds with `allowDrafts: true`.
+ * All branch columns are nullable (drafts are partial).
+ * Returns null if the Seed does not have `allowDrafts: true`.
+ */
+export declare function generateDraftTable(seed: Seed): string | null;
+/**
+ * Generates `ALTER TABLE content_{slug} ADD COLUMN {alias} {type}`.
+ * New columns are always nullable (SQLite limit on ALTER TABLE).
+ */
+export declare function generateAddColumn(seed: Seed, branch: Branch): string;
+/**
+ * Generates B-tree indexes for status, created_at and every filterable Branch
+ * with an indexable type (text, number, date, boolean).
+ */
+export declare function generateIndexes(seed: Seed): string[];
+/**
+ * Generates the FTS5 virtual table for indexable text/richtext Branches.
+ * Returns null if the Seed has no branches with search enabled.
+ */
+export declare function generateFtsTable(seed: Seed): string | null;
+/**
+ * Generates the 3 SQLite triggers (insert/update/delete) that keep the FTS
+ * automatically synchronized — eliminates the need for manual syncFts.
+ * Returns an empty array if the Seed has no indexable branches.
+ */
+export declare function generateFtsTriggers(seed: Seed): string[];
+/**
+ * Builds a parameterized SELECT on `content_{slug}`.
+ * Never uses json_extract — every column is a real column.
+ * Unknown columns in filters/orderBy are ignored (fail-closed).
+ */
+export declare function buildSelectQuery(seed: Seed, options?: SelectOptions): ParameterizedQuery;
+export interface SchemaColumn {
+    name: string;
+    sqlType: 'TEXT' | 'REAL' | 'INTEGER';
+    notNull: boolean;
+    isPk: boolean;
+}
+/**
+ * Returns the list of expected columns for a Seed's table.
+ * Used by `beech seed:load --diff` to compare current vs expected schema.
+ */
+export declare function getExpectedColumns(seed: Seed): SchemaColumn[];
+/**
+ * Serializes a value for writing to the DB.
+ * boolean → 0/1 | date → Unix timestamp | json/asset-list → JSON string
+ */
+export declare function serializeForDb(branch: Branch, value: unknown): string | number | null;
+/**
+ * Returns the junction table name for a many-to-many relation branch.
+ * Format: `rel_<seedSlug>_<branchAlias>`.
+ */
+export declare function junctionTableName(seedSlug: string, branchAlias: string): string;
+/**
+ * Generates `CREATE TABLE IF NOT EXISTS rel_<seed>_<alias>` for a multi-relation
+ * branch. The parent FK always cascades (parent lifecycle owns the edge);
+ * the target FK uses `branch.onDelete` (default CASCADE).
+ *
+ * @throws {Error} when called on a non-multi-relation branch
+ * @throws {Error} when `branch.targetSeed` is missing
+ */
+export declare function generateJunctionTable(seed: Seed, branch: Branch): string;
+/**
+ * Generates the two B-tree indexes for a junction table:
+ * one on `parent_id` (list entries by parent) and one on `target_id`
+ * (cascade checks from target side).
+ */
+export declare function generateJunctionIndexes(seed: Seed, branch: Branch): string[];
+/**
+ * Generates the drafts junction table `rel_<seed>_<alias>_drafts` for a
+ * many-to-many relation branch. Note: no FK on `target_id` — targets may be
+ * deleted between draft save and publish; the FK would be wrong here.
+ * Returns null when `seed.allowDrafts` is falsy.
+ */
+export declare function generateJunctionDraftTable(seed: Seed, branch: Branch): string | null;
+/**
+ * Returns every `DROP TABLE IF EXISTS` needed to fully remove a content type:
+ * the main `content_{slug}` table, its `fts_{slug}` virtual table, the
+ * `content_{slug}_drafts` mirror (when drafts are enabled), and each
+ * multi-relation junction table `rel_{slug}_{alias}` (+ its `_drafts` mirror).
+ *
+ * FTS triggers reference the main table; dropping the main table also drops
+ * its triggers in SQLite, but we drop the FTS table explicitly so no orphaned
+ * virtual table survives. Order: junction (children) → drafts → fts → main.
+ */
+export declare function generateDropTable(seed: Seed): string[];
+/**
+ * Returns the `DROP COLUMN` statements for removing a single field.
+ *
+ * - For a multi-relation branch (no column on the parent table) it drops the
+ *   junction table `rel_{slug}_{alias}` (+ `_drafts`) instead.
+ * - For a normal branch it drops the column from `content_{slug}` and, when
+ *   drafts are enabled, the mirror column from `content_{slug}_drafts`.
+ * - For an orphan column (no matching branch in the definition) it falls back
+ *   to a plain `ALTER TABLE … DROP COLUMN`, never touching drafts.
+ *
+ * Callers must rebuild FTS separately (planFtsRebuild) when the dropped column
+ * was searchable, since SQLite cannot ALTER an fts5 table's columns.
+ */
+export declare function generateDropColumn(seed: Seed, alias: string): string[];
+/**
+ * Returns the `RENAME COLUMN` statements for renaming a field's alias while
+ * keeping the stable `branch.id`. Renames the column on `content_{slug}` and,
+ * when drafts are enabled, the mirror column on `content_{slug}_drafts`.
+ *
+ * For a multi-relation branch the alias is part of the junction table name, so
+ * the junction table (+ `_drafts`) is renamed instead of a column.
+ *
+ * Callers must rebuild FTS separately (planFtsRebuild) when the renamed column
+ * was searchable.
+ */
+export declare function generateRenameColumn(seed: Seed, from: string, to: string): string[];
+/**
+ * Returns the add/copy/drop/rename statements that change a column's SQL type
+ * in place, preserving data via `CAST`. This is the documented simpler
+ * alternative to SQLite's full 12-step table rebuild.
+ *
+ * The `branch` passed in is the *target* definition (already carrying the new
+ * `type`); its SQL type is read from BRANCH_TYPE_SQL. Multi-relation branches
+ * have no column to retype and are rejected. Mirrors the change onto the drafts
+ * table when drafts are enabled. Callers rebuild FTS separately when needed.
+ */
+export declare function generateRetypeColumn(seed: Seed, branch: Branch): string[];
+/**
+ * Deserializes a value read from the DB for the API response.
+ * 0/1 → boolean | Unix timestamp → ISO 8601 | JSON string → object
+ */
+export declare function deserializeFromDb(branch: Branch, value: unknown): unknown;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EACV,IAAI,EACJ,MAAM,EAKN,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAsCnB,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAI5D;AAkED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CA0BtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAyB5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAuBpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAc1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAgCxD;AAID;;;;GAIG;AAGH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAsF5F;AAgHD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,EAAE,CAiB7D;AAID;;;GAGG;AAEH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAwCrF;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAkBxE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAapF;AAcD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CA0BtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBzE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAqCzE"}