@beechcms/core 0.9.0 → 0.9.1

package/dist/engine/policies.js

@@ -1,168 +0,0 @@
-// SPDX-License-Identifier: MIT
-// Copyright (c) 2024–2026 Flavio De Musso
-/**
- * Computes an un-salted SHA-256 hex digest of a string value.
- * Used for basic digest operations.
- * @param value - The raw string value to hash.
- * @returns A Promise resolving to a 64-character hex string.
- */
-export async function sha256hex(value) {
-    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
-    return Array.from(new Uint8Array(buf))
-        .map((b) => b.toString(16).padStart(2, '0'))
-        .join('');
-}
-/**
- * Verifies if a candidate string matches a stored SHA-256 hash digest.
- * @param stored - The expected 64-character SHA-256 hex digest.
- * @param candidate - The raw candidate string to verify.
- * @returns A Promise resolving to true if candidate matches stored digest, false otherwise.
- */
-export async function verifyHashField(stored, candidate) {
-    return stored === (await sha256hex(candidate));
-}
-/** Normalizes raw policy strings to canonical DataClassification enum. */
-export function normalizeClassification(raw) {
-    if (!raw)
-        return 'public';
-    const lower = raw.toLowerCase();
-    if (lower === 'confidential')
-        return 'confidential';
-    if (lower === 'restricted' || lower === 'hash')
-        return 'restricted';
-    if (lower === 'encrypt')
-        return 'confidential';
-    if (lower === 'internal')
-        return 'internal';
-    return 'public';
-}
-/**
- * Resolves the 4-tier DataClassification for a branch, bundling its storage
- * strategy at rest and its API visibility rules (public vs auth context).
- * @param branch - The seed branch definition to inspect.
- * @returns The resolved classification details and visibility rules.
- */
-export function resolveClassification(branch) {
-    const rawClassification = branch.policies?.classification ?? branch.policies?.privacy;
-    const classification = normalizeClassification(rawClassification);
-    switch (classification) {
-        case 'confidential':
-            return {
-                classification: 'confidential',
-                storage: 'encrypt',
-                publicVisibility: 'hidden',
-                authVisibility: 'full',
-            };
-        case 'restricted':
-            return {
-                classification: 'restricted',
-                storage: 'hash',
-                publicVisibility: 'hidden',
-                authVisibility: 'hidden',
-            };
-        case 'internal':
-            return {
-                classification: 'internal',
-                storage: 'plain',
-                publicVisibility: 'hidden',
-                authVisibility: 'full',
-            };
-        case 'public':
-        default:
-            return {
-                classification: 'public',
-                storage: 'plain',
-                publicVisibility: 'full',
-                authVisibility: 'full',
-            };
-    }
-}
-/**
- * Resolves branch policies applying all defaults and classification rules.
- * @param branch - The seed branch definition to inspect.
- * @returns Complete required policies object for the branch.
- */
-export function resolvePolicies(branch) {
-    const resolved = resolveClassification(branch);
-    const isRepeater = branch.type === 'repeater';
-    const isEncryptedOrHashed = resolved.storage !== 'plain';
-    const defaultVisibility = resolved.authVisibility;
-    const isPublicAllowed = branch.policies?.public ?? (resolved.publicVisibility === 'full');
-    const defaultFilter = isRepeater || resolved.storage === 'hash' ? false : branch.policies?.filter ?? true;
-    const defaultSort = isRepeater || isEncryptedOrHashed ? false : branch.policies?.sort ?? true;
-    const defaultSearch = isRepeater || isEncryptedOrHashed ? false : branch.policies?.search ?? true;
-    // publicEdit default: true for public fields (unless public: false), false for confidential/internal/restricted
-    const defaultPublicEdit = resolved.classification === 'public'
-        ? (branch.policies?.publicEdit ?? isPublicAllowed)
-        : (branch.policies?.publicEdit ?? false);
-    return {
-        classification: resolved.classification,
-        privacy: resolved.storage,
-        visibility: branch.policies?.visibility ?? defaultVisibility,
-        search: defaultSearch,
-        filter: defaultFilter,
-        sort: defaultSort,
-        public: isPublicAllowed,
-        publicEdit: defaultPublicEdit,
-    };
-}
-const SYSTEM_FIELDS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at', 'version', 'has_pending_draft']);
-/**
- * Filters entry payload fields based on the caller's {@link ActorContext} and branch classification tier.
- *
- * Rules:
- * - Public actor: receives `public` fields; `internal`, `confidential`, and `restricted` fields are omitted.
- * - Authenticated actor: receives `public`, `internal`, and `confidential` fields; `restricted` fields are ALWAYS omitted.
- * - System actor: receives all fields including `restricted` (used for internal worker/automation orchestration).
- *
- * @param data - Raw record fields object.
- * @param seed - Content type seed definition containing branch definitions.
- * @param actor - Context of the caller requesting the entry payload (defaults to authenticated).
- * @returns Filtered data record containing only authorized fields for the given actor context.
- */
-export function filterEntryForActor(data, seed, actor = { type: 'authenticated' }) {
-    const result = {};
-    for (const [key, value] of Object.entries(data)) {
-        if (SYSTEM_FIELDS.has(key)) {
-            result[key] = value;
-            continue;
-        }
-        const branch = seed.branches.find((b) => b.alias === key);
-        if (!branch) {
-            // Pass through unknown/extra fields unless actor is public
-            if (actor.type !== 'public') {
-                result[key] = value;
-            }
-            continue;
-        }
-        const resolved = resolveClassification(branch);
-        const isPublicActor = actor.type === 'public';
-        const isSystemActor = actor.type === 'system';
-        // System actor sees all fields including restricted
-        if (isSystemActor) {
-            result[key] = value;
-            continue;
-        }
-        // Public actor check
-        if (isPublicActor) {
-            if (resolved.publicVisibility === 'hidden')
-                continue;
-        }
-        else {
-            // Authenticated actor check
-            if (resolved.authVisibility === 'hidden')
-                continue;
-        }
-        // Explicit visibility override check
-        if (branch.policies?.visibility === 'hidden')
-            continue;
-        // Masking rule check
-        if (branch.policies?.visibility === 'masked') {
-            result[key] = typeof value === 'string' && value.length > 0 ? '••••••••' : null;
-        }
-        else {
-            result[key] = value;
-        }
-    }
-    return result;
-}

package/dist/engine/privacy.service.d.ts

@@ -1,65 +0,0 @@
-/**
- * Contract for the Application-Level Encryption (ALE) and hashing privacy service.
- * Used by the Botanical Engine to secure fields classified as `confidential` or `restricted`.
- */
-export interface IPrivacyService {
-    /**
-     * Symmetrically encrypts a plaintext string using AES-256-GCM.
-     * @param plaintext - The raw string value to encrypt.
-     * @returns A Promise resolving to formatted ciphertext (`v1:<iv_base64>:<ciphertext_base64>`).
-     */
-    encrypt(plaintext: string): Promise<string>;
-    /**
-     * Decrypts a formatted AES-256-GCM ciphertext payload.
-     * @param ciphertext - The formatted ciphertext string (`v1:<iv_base64>:<ciphertext_base64>`).
-     * @returns A Promise resolving to the original plaintext string.
-     * @throws Error if the ciphertext format is invalid or decryption fails (authentication tag mismatch).
-     */
-    decrypt(ciphertext: string): Promise<string>;
-    /**
-     * Computes a deterministic HMAC SHA-256 digest of a plaintext string.
-     * Used for blind-indexing and one-way field digests (`restricted` classification).
-     * @param plaintext - The raw string value to hash.
-     * @returns A Promise resolving to a 64-character hexadecimal digest string.
-     */
-    hash(plaintext: string): Promise<string>;
-}
-/**
- * Concrete Edge-native implementation of {@link IPrivacyService}.
- * Employs Web Crypto API (`crypto.subtle`) for zero-dependency execution in Cloudflare Workers.
- */
-export declare class PrivacyService implements IPrivacyService {
-    private readonly masterKey;
-    private aesKeyPromise?;
-    private hmacKeyPromise?;
-    /**
-     * Initializes the PrivacyService with a Master Encryption Key.
-     * @param masterKey - Secret key used to derive cryptographic keys for AES-GCM and HMAC.
-     * @throws Error if `masterKey` is empty or undefined.
-     */
-    constructor(masterKey: string);
-    /**
-     * Lazy-loads and caches the derived AES-256-GCM {@link CryptoKey}.
-     * Derives a 256-bit key from `masterKey` via SHA-256 digest.
-     */
-    private getAesKey;
-    /**
-     * Lazy-loads and caches the derived HMAC SHA-256 {@link CryptoKey}.
-     */
-    private getHmacKey;
-    /**
-     * Encrypts a plaintext string with AES-256-GCM and a fresh 96-bit (12-byte) IV.
-     * Output is formatted as `v1:<iv_base64>:<ciphertext_base64>`.
-     */
-    encrypt(plaintext: string): Promise<string>;
-    /**
-     * Decrypts a `v1:<iv_base64>:<ciphertext_base64>` string back to its plaintext value.
-     * If the input string is not prefixed with `v1:`, returns the raw string as unencrypted legacy data.
-     */
-    decrypt(ciphertext: string): Promise<string>;
-    /**
-     * Computes a deterministic HMAC SHA-256 hex digest for blind index generation.
-     */
-    hash(plaintext: string): Promise<string>;
-}
-//# sourceMappingURL=privacy.service.d.ts.map

package/dist/engine/privacy.service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"privacy.service.d.ts","sourceRoot":"","sources":["../../src/engine/privacy.service.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE5C;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACzC;AA4BD;;;GAGG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,aAAa,CAAC,CAAoB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAoB;IAE3C;;;;OAIG;IACH,YAAY,SAAS,EAAE,MAAM,EAK5B;IAED;;;OAGG;YACW,SAAS;IAmBvB;;OAEG;YACW,UAAU;IAexB;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYhD;IAED;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBjD;IAED;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAY7C;CACF"}

package/dist/engine/privacy.service.js

@@ -1,114 +0,0 @@
-// SPDX-License-Identifier: MIT
-// Copyright (c) 2024–2026 Flavio De Musso
-/**
- * Converts a Uint8Array byte sequence to a Base64-encoded string.
- * Native Edge-compatible implementation without Node.js Buffer dependencies.
- */
-function bytesToBase64(bytes) {
-    let binary = '';
-    const len = bytes.byteLength;
-    for (let i = 0; i < len; i++) {
-        binary += String.fromCharCode(bytes[i]);
-    }
-    return btoa(binary);
-}
-/**
- * Converts a Base64-encoded string back to a Uint8Array byte sequence.
- * Native Edge-compatible implementation without Node.js Buffer dependencies.
- */
-function base64ToBytes(base64) {
-    const binary = atob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) {
-        bytes[i] = binary.charCodeAt(i);
-    }
-    return bytes;
-}
-/**
- * Concrete Edge-native implementation of {@link IPrivacyService}.
- * Employs Web Crypto API (`crypto.subtle`) for zero-dependency execution in Cloudflare Workers.
- */
-export class PrivacyService {
-    masterKey;
-    aesKeyPromise;
-    hmacKeyPromise;
-    /**
-     * Initializes the PrivacyService with a Master Encryption Key.
-     * @param masterKey - Secret key used to derive cryptographic keys for AES-GCM and HMAC.
-     * @throws Error if `masterKey` is empty or undefined.
-     */
-    constructor(masterKey) {
-        if (!masterKey) {
-            throw new Error('PrivacyService requires a non-empty masterKey');
-        }
-        this.masterKey = masterKey;
-    }
-    /**
-     * Lazy-loads and caches the derived AES-256-GCM {@link CryptoKey}.
-     * Derives a 256-bit key from `masterKey` via SHA-256 digest.
-     */
-    async getAesKey() {
-        if (!this.aesKeyPromise) {
-            this.aesKeyPromise = (async () => {
-                const keyData = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(this.masterKey));
-                return crypto.subtle.importKey('raw', keyData, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
-            })();
-        }
-        return this.aesKeyPromise;
-    }
-    /**
-     * Lazy-loads and caches the derived HMAC SHA-256 {@link CryptoKey}.
-     */
-    async getHmacKey() {
-        if (!this.hmacKeyPromise) {
-            this.hmacKeyPromise = (async () => {
-                return crypto.subtle.importKey('raw', new TextEncoder().encode(this.masterKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
-            })();
-        }
-        return this.hmacKeyPromise;
-    }
-    /**
-     * Encrypts a plaintext string with AES-256-GCM and a fresh 96-bit (12-byte) IV.
-     * Output is formatted as `v1:<iv_base64>:<ciphertext_base64>`.
-     */
-    async encrypt(plaintext) {
-        const key = await this.getAesKey();
-        const iv = crypto.getRandomValues(new Uint8Array(12));
-        const encodedText = new TextEncoder().encode(plaintext);
-        const encryptedBuffer = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, key, encodedText);
-        const ivBase64 = bytesToBase64(iv);
-        const ciphertextBase64 = bytesToBase64(new Uint8Array(encryptedBuffer));
-        return `v1:${ivBase64}:${ciphertextBase64}`;
-    }
-    /**
-     * Decrypts a `v1:<iv_base64>:<ciphertext_base64>` string back to its plaintext value.
-     * If the input string is not prefixed with `v1:`, returns the raw string as unencrypted legacy data.
-     */
-    async decrypt(ciphertext) {
-        if (!ciphertext || !ciphertext.startsWith('v1:')) {
-            return ciphertext;
-        }
-        const parts = ciphertext.split(':');
-        if (parts.length !== 3) {
-            throw new Error('Invalid ciphertext format');
-        }
-        const [, ivBase64, cipherBase64] = parts;
-        const iv = base64ToBytes(ivBase64);
-        const cipherBytes = base64ToBytes(cipherBase64);
-        const key = await this.getAesKey();
-        const decryptedBuffer = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: iv }, key, cipherBytes);
-        return new TextDecoder().decode(decryptedBuffer);
-    }
-    /**
-     * Computes a deterministic HMAC SHA-256 hex digest for blind index generation.
-     */
-    async hash(plaintext) {
-        const key = await this.getHmacKey();
-        const encodedText = new TextEncoder().encode(plaintext);
-        const signatureBuffer = await crypto.subtle.sign('HMAC', key, encodedText);
-        const hashBytes = new Uint8Array(signatureBuffer);
-        return Array.from(hashBytes)
-            .map((b) => b.toString(16).padStart(2, '0'))
-            .join('');
-    }
-}

package/dist/engine/query.d.ts

@@ -1,23 +0,0 @@
-import type { Seed, SelectOptions, ParameterizedQuery } from './types.js';
-/**
- * Builds a parameterized SQL SELECT query and bindings for a given Seed based on search, filtering, status, and ordering options.
- *
- * If `options.isCount` is set to `true`, it generates a counting query (`COUNT(*) as total`) rather than returning database rows.
- * In count mode, column projections (`fields`), ordering (`orderBy` / `kanbanOrder`), and pagination (`LIMIT` / `OFFSET`) clauses and
- * bindings are omitted, while join and filtering clauses are preserved.
- *
- * @param seed The seed definition.
- * @param options Query configuration options.
- * @returns The SQL query string and bindings.
- * @example
- * ```ts
- * const { sql, bindings } = buildSelectQuery(postSeed, {
- *   status: 'published',
- *   filters: [{ column: 'title', type: 'text', conditions: [{ op: 'contains', value: 'cms' }] }],
- *   orderBy: { column: 'created_at', dir: 'DESC' },
- *   pagination: { limit: 20, offset: 0 },
- * })
- * ```
- */
-export declare function buildSelectQuery(seed: Seed, options?: SelectOptions): ParameterizedQuery;
-//# sourceMappingURL=query.d.ts.map

package/dist/engine/query.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/engine/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAMJ,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAoG5F"}

package/dist/engine/query.js

@@ -1,236 +0,0 @@
-import { tableName, ftsTableName, isValidColumn, indexableSearchBranches, SYSTEM_COLUMNS } from './ddl.js';
-import { resolveClassification } from './policies.js';
-/**
- * Builds a parameterized SQL SELECT query and bindings for a given Seed based on search, filtering, status, and ordering options.
- *
- * If `options.isCount` is set to `true`, it generates a counting query (`COUNT(*) as total`) rather than returning database rows.
- * In count mode, column projections (`fields`), ordering (`orderBy` / `kanbanOrder`), and pagination (`LIMIT` / `OFFSET`) clauses and
- * bindings are omitted, while join and filtering clauses are preserved.
- *
- * @param seed The seed definition.
- * @param options Query configuration options.
- * @returns The SQL query string and bindings.
- * @example
- * ```ts
- * const { sql, bindings } = buildSelectQuery(postSeed, {
- *   status: 'published',
- *   filters: [{ column: 'title', type: 'text', conditions: [{ op: 'contains', value: 'cms' }] }],
- *   orderBy: { column: 'created_at', dir: 'DESC' },
- *   pagination: { limit: 20, offset: 0 },
- * })
- * ```
- */
-export function buildSelectQuery(seed, options = {}) {
-    const table = tableName(seed);
-    const { filters = [], orderBy, pagination, status, search, fields } = options;
-    const bindings = [];
-    const whereClauses = [];
-    let joinClause = '';
-    let kanbanOrderClause = '';
-    if (options.kanbanOrder) {
-        joinClause = `LEFT JOIN kanban_positions kp` +
-            ` ON kp.seed_slug = ? AND kp.entry_id = ${table}.id AND kp.axis_branch_id = ?`;
-        bindings.push(options.kanbanOrder.seedSlug, options.kanbanOrder.axisBranchId);
-        kanbanOrderClause = ` ORDER BY (kp.position IS NULL) ASC, kp.position ASC`;
-    }
-    const rtBranches = indexableSearchBranches(seed);
-    if (search && rtBranches.length > 0) {
-        const ftsTable = ftsTableName(seed);
-        joinClause += (joinClause ? ' ' : '') + `INNER JOIN ${ftsTable} ON ${ftsTable}.entry_id = ${table}.id`;
-        whereClauses.push(`${ftsTable} MATCH ?`);
-        bindings.push(`"${search.replace(/"/g, '""')}"*`);
-    }
-    if (status !== undefined && status !== null) {
-        whereClauses.push(`${table}.status = ?`);
-        bindings.push(status);
-    }
-    const groupClauses = [];
-    for (const group of filters) {
-        if (!isValidColumn(seed, group.column))
-            continue;
-        const branch = seed.branches.find(b => b.alias === group.column);
-        const isEncrypted = branch ? resolveClassification(branch).storage === 'encrypt' : false;
-        const col = SYSTEM_COLUMNS.has(group.column)
-            ? `${table}.${group.column}`
-            : group.column;
-        const condClauses = [];
-        for (const cond of group.conditions) {
-            if (isEncrypted) {
-                const { op } = cond;
-                if (op === 'eq' || op === 'neq' || op === 'in' || op === 'not_in') {
-                    const targetCol = `${table}.${group.column}_bidx`;
-                    const clause = buildFilterCondition(targetCol, group.type, cond, bindings);
-                    if (clause)
-                        condClauses.push(clause);
-                }
-                else if (op === 'is_empty' || op === 'is_not_empty') {
-                    const clause = buildFilterCondition(col, group.type, cond, bindings);
-                    if (clause)
-                        condClauses.push(clause);
-                }
-            }
-            else {
-                const clause = buildFilterCondition(col, group.type, cond, bindings);
-                if (clause)
-                    condClauses.push(clause);
-            }
-        }
-        if (condClauses.length > 0) {
-            groupClauses.push(condClauses.length > 1 ? `(${condClauses.join(' AND ')})` : condClauses[0]);
-        }
-    }
-    if (groupClauses.length > 0) {
-        const joiner = options.filterLogic === 'OR' ? ' OR ' : ' AND ';
-        whereClauses.push(groupClauses.length > 1 ? `(${groupClauses.join(joiner)})` : groupClauses[0]);
-    }
-    let selectCols = options.isCount ? 'COUNT(*) as total' : `${table}.*`;
-    if (!options.isCount && fields && fields.length > 0) {
-        const valid = fields.filter(f => isValidColumn(seed, f));
-        if (valid.length > 0) {
-            selectCols = valid
-                .map(f => (SYSTEM_COLUMNS.has(f) ? `${table}.${f}` : f))
-                .join(', ');
-        }
-    }
-    if (!options.isCount && options.kanbanOrder)
-        selectCols += ', kp.position';
-    let sql = `SELECT ${selectCols} FROM ${table}`;
-    if (joinClause)
-        sql += ` ${joinClause}`;
-    if (whereClauses.length > 0)
-        sql += ` WHERE ${whereClauses.join(' AND ')}`;
-    if (!options.isCount) {
-        if (kanbanOrderClause) {
-            sql += kanbanOrderClause;
-        }
-        else if (orderBy && isValidColumn(seed, orderBy.column)) {
-            const dir = orderBy.dir === 'DESC' ? 'DESC' : 'ASC';
-            const col = SYSTEM_COLUMNS.has(orderBy.column)
-                ? `${table}.${orderBy.column}`
-                : orderBy.column;
-            sql += ` ORDER BY ${col} ${dir}`;
-        }
-        else {
-            sql += ` ORDER BY ${table}.created_at DESC`;
-        }
-        if (pagination) {
-            sql += ` LIMIT ? OFFSET ?`;
-            bindings.push(pagination.limit, pagination.offset);
-        }
-    }
-    return { sql, bindings };
-}
-/**
- * Normalizes user-provided filter values to a format appropriate for SQL execution.
- *
- * @param type The type of the filter.
- * @param value The value to normalize.
- * @returns The normalized value, or null.
- */
-function normalizeFilterValue(type, value) {
-    if (value === null || value === undefined)
-        return null;
-    if (type === 'date') {
-        if (typeof value === 'number')
-            return value;
-        if (typeof value === 'string' && value.trim() !== '') {
-            const d = new Date(value);
-            return Number.isNaN(d.getTime()) ? null : Math.floor(d.getTime() / 1000);
-        }
-        return null;
-    }
-    if (type === 'boolean') {
-        return value ? 1 : 0;
-    }
-    if (type === 'number') {
-        if (typeof value === 'number')
-            return value;
-        if (typeof value === 'string' && value.trim() !== '') {
-            const n = Number(value);
-            return Number.isNaN(n) ? null : n;
-        }
-        return null;
-    }
-    return value;
-}
-/**
- * Translates a filter condition into its SQL clause and adds parameters to the bindings list.
- *
- * @param col The column name in the table.
- * @param type The type of the filter.
- * @param cond The condition containing the operator and value.
- * @param bindings The array of bindings where parameterized values are appended.
- * @returns The SQL condition fragment, or null if invalid.
- */
-function buildFilterCondition(col, type, cond, bindings) {
-    const { op, value } = cond;
-    if (op === 'is_empty' || op === 'is_not_empty') {
-        const isEmpty = op === 'is_empty';
-        if (type === 'text') {
-            return isEmpty ? `(${col} IS NULL OR ${col} = '')` : `(${col} IS NOT NULL AND ${col} != '')`;
-        }
-        if (type === 'tags' || type === 'json') {
-            return isEmpty
-                ? `(${col} IS NULL OR ${col} = '[]' OR ${col} = '{}')`
-                : `(${col} IS NOT NULL AND ${col} != '[]' AND ${col} != '{}')`;
-        }
-        return isEmpty ? `${col} IS NULL` : `${col} IS NOT NULL`;
-    }
-    if (op === 'in' || op === 'not_in') {
-        if (!Array.isArray(value) || value.length === 0)
-            return null;
-        const normalizedValues = value
-            .map((v) => normalizeFilterValue(type, v))
-            .filter((v) => v !== null);
-        if (normalizedValues.length === 0)
-            return null;
-        const placeholders = normalizedValues.map(() => '?').join(', ');
-        bindings.push(...normalizedValues);
-        return `${col} ${op === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`;
-    }
-    if (op === 'has_tag' || op === 'has_any_tag' || op === 'has_all_tags') {
-        if (type !== 'tags' && type !== 'json')
-            return null;
-        const tags = (op === 'has_tag' ? [value] : Array.isArray(value) ? value : [value])
-            .map(t => String(t));
-        if (tags.length === 0)
-            return null;
-        // json_each on array → value is the element; on object → key is the property name.
-        // Tags stored as ["photo"] (array) or {"photo":"#3b82f6"} (object) must both match.
-        const tagRef = `CASE json_type(${col}) WHEN 'array' THEN value ELSE key END`;
-        if (op === 'has_tag' || op === 'has_any_tag') {
-            const placeholders = tags.map(() => '?').join(', ');
-            bindings.push(...tags);
-            return `EXISTS (SELECT 1 FROM json_each(${col}) WHERE ${tagRef} IN (${placeholders}))`;
-        }
-        const clauses = tags.map(() => `EXISTS (SELECT 1 FROM json_each(${col}) WHERE ${tagRef} = ?)`);
-        bindings.push(...tags);
-        return `(${clauses.join(' AND ')})`;
-    }
-    const normalized = normalizeFilterValue(type, value);
-    if (normalized === null)
-        return null;
-    if (op === 'eq' || op === 'neq') {
-        const sqlOp = op === 'eq' ? '=' : '!=';
-        bindings.push(normalized);
-        return `${col} ${sqlOp} ?`;
-    }
-    if (op === 'contains' || op === 'not_contains' || op === 'starts_with' || op === 'ends_with') {
-        const sqlOp = op === 'not_contains' ? 'NOT LIKE' : 'LIKE';
-        let pattern = String(value);
-        if (op === 'contains' || op === 'not_contains')
-            pattern = `%${pattern}%`;
-        else if (op === 'starts_with')
-            pattern = `${pattern}%`;
-        else if (op === 'ends_with')
-            pattern = `%${pattern}`;
-        bindings.push(pattern);
-        return `${col} ${sqlOp} ?`;
-    }
-    const mathOps = { gt: '>', gte: '>=', lt: '<', lte: '<=' };
-    if (mathOps[op]) {
-        bindings.push(normalized);
-        return `${col} ${mathOps[op]} ?`;
-    }
-    return null;
-}

package/dist/engine/relations.d.ts

@@ -1,28 +0,0 @@
-/**
- * Back-reference helpers for the Beech CMS relation system.
- *
- * `buildBackrefMap` is a pure function that iterates the seed registry once
- * and builds a lookup map: targetSlug → sources that point to it.
- * Build this once at app factory time and cache it for the process lifetime.
- */
-import type { Seed } from './types.js';
-export interface BackrefSource {
-    /** Slug of the seed that owns the relation branch */
-    sourceSlug: string;
-    /** `branch.alias` — the FK column name (single) or join-table name suffix (multi) */
-    branchAlias: string;
-    /** `branch.label` — human label for UI grouping */
-    branchLabel: string;
-    /** 'single' for direct FK, 'multi' for many-to-many join table */
-    relationship: 'single' | 'multi';
-    /** True when branch.onDelete === 'RESTRICT' — used to disable Delete button */
-    restricts: boolean;
-}
-/** Map: targetSlug → every source that points to it */
-export type BackrefMap = Map<string, BackrefSource[]>;
-/**
- * Builds the back-reference map from an array of seeds.
- * Pure function — no side-effects, safe to call at startup and cache forever.
- */
-export declare function buildBackrefMap(seeds: Seed[]): BackrefMap;
-//# sourceMappingURL=relations.d.ts.map

package/dist/engine/relations.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../src/engine/relations.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAA;IAChC,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAA;AAErD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAoBzD"}

package/dist/engine/relations.js

@@ -1,25 +0,0 @@
-// SPDX-License-Identifier: MIT
-// Copyright (c) 2024–2026 Flavio De Musso
-/**
- * Builds the back-reference map from an array of seeds.
- * Pure function — no side-effects, safe to call at startup and cache forever.
- */
-export function buildBackrefMap(seeds) {
-    const map = new Map();
-    for (const seed of seeds) {
-        for (const branch of seed.branches) {
-            if (branch.type !== 'relation' || !branch.targetSeed)
-                continue;
-            const existing = map.get(branch.targetSeed) ?? [];
-            existing.push({
-                sourceSlug: seed.slug,
-                branchAlias: branch.alias,
-                branchLabel: branch.label,
-                relationship: branch.multiple === true ? 'multi' : 'single',
-                restricts: branch.onDelete === 'RESTRICT',
-            });
-            map.set(branch.targetSeed, existing);
-        }
-    }
-    return map;
-}