@beechcms/core 0.8.0 → 0.9.0

package/dist/engine/privacy/privacy.service.js

@@ -0,0 +1,138 @@
+// 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('');
+    }
+}
+/** Thrown when a protected field is processed but no master key is configured. */
+export class PrivacyNotConfiguredError extends Error {
+    constructor() {
+        super('PRIVACY_MASTER_KEY is not configured: cannot encrypt or hash protected fields');
+        this.name = 'PrivacyNotConfiguredError';
+    }
+}
+/**
+ * Fail-closed {@link IPrivacyService} for installs without a master key.
+ * Never returns plaintext as protected output; legacy non-`v1:` values still read through.
+ */
+export class UnconfiguredPrivacyService {
+    async encrypt(_plaintext) {
+        throw new PrivacyNotConfiguredError();
+    }
+    async decrypt(ciphertext) {
+        if (ciphertext?.startsWith('v1:'))
+            throw new PrivacyNotConfiguredError();
+        return ciphertext;
+    }
+    async hash(_plaintext) {
+        throw new PrivacyNotConfiguredError();
+    }
+}

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

@@ -1 +1 @@
-{"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;gBACS,SAAS,EAAE,MAAM;IAO7B;;;OAGG;YACW,SAAS;IAmBvB;;OAEG;YACW,UAAU;IAexB;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAcjD;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBlD;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAa/C"}
+{"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/query/active-clause.d.ts

@@ -0,0 +1,19 @@
+import type { Seed, TrashedMode } from '../types.js';
+/**
+ * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if the
+ * seed does not use soft delete or mode is 'any'.
+ *
+ * @param seed - The seed schema definition.
+ * @param mode - 'active' (default), 'trashed', or 'any'.
+ * @param tableAlias - Optional table or alias qualifier prefix.
+ */
+export declare function activeCondition(seed: Seed, mode?: TrashedMode, tableAlias?: string): string | null;
+/**
+ * Returns ` AND <activeCondition>` for a soft-delete seed, or `''` otherwise.
+ *
+ * @param seed - The seed schema definition.
+ * @param mode - 'active' (default), 'trashed', or 'any'.
+ * @param tableAlias - Optional table or alias qualifier prefix.
+ */
+export declare function activeClause(seed: Seed, mode?: TrashedMode, tableAlias?: string): string;
+//# sourceMappingURL=active-clause.d.ts.map

package/dist/engine/query/active-clause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-clause.d.ts","sourceRoot":"","sources":["../../../src/engine/query/active-clause.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAGR"}

package/dist/engine/query/active-clause.js

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if the
+ * seed does not use soft delete or mode is 'any'.
+ *
+ * @param seed - The seed schema definition.
+ * @param mode - 'active' (default), 'trashed', or 'any'.
+ * @param tableAlias - Optional table or alias qualifier prefix.
+ */
+export function activeCondition(seed, mode = 'active', tableAlias) {
+    if (!seed.softDelete || mode === 'any')
+        return null;
+    const col = tableAlias ? `${tableAlias}.deleted_at` : 'deleted_at';
+    return mode === 'trashed' ? `${col} IS NOT NULL` : `${col} IS NULL`;
+}
+/**
+ * Returns ` AND <activeCondition>` for a soft-delete seed, or `''` otherwise.
+ *
+ * @param seed - The seed schema definition.
+ * @param mode - 'active' (default), 'trashed', or 'any'.
+ * @param tableAlias - Optional table or alias qualifier prefix.
+ */
+export function activeClause(seed, mode = 'active', tableAlias) {
+    const cond = activeCondition(seed, mode, tableAlias);
+    return cond ? ` AND ${cond}` : '';
+}

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

@@ -0,0 +1,36 @@
+import type { Seed, FilterGroup, 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;
+/**
+ * Lists the filter groups `buildSelectQuery` would silently leave out of the WHERE clause: an unknown
+ * column, or a condition whose value cannot be bound for the field type (empty or unparsable
+ * number/date, `in`/`not_in` value that is not an array). An empty `in` is not listed:
+ * it compiles to constant false and still constrains the read. A caller that needs the filter to constrain the read
+ * (e.g. automations resolving placeholders at run time) uses this to refuse the query instead of
+ * running it unconstrained.
+ *
+ * @param seed The seed the filters apply to.
+ * @param filters The filter groups to check.
+ * @returns The groups that would be dropped, in input order.
+ */
+export declare function findUnappliedFilters(seed: Seed, filters: FilterGroup[]): FilterGroup[];
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/engine/query/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAGJ,WAAW,EAGX,aAAa,EAEb,kBAAkB,EACnB,MAAM,aAAa,CAAC;AA8FrB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAgH5F;AAGD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAKtF"}

package/dist/engine/query/query.js

@@ -0,0 +1,393 @@
+import { tableName, ftsTableName, isValidColumn, indexableSearchBranches, SYSTEM_COLUMNS } from '../ddl/ddl.js';
+import { resolveClassification } from '../privacy/policies.js';
+import { isLocaleCode, isLocalizedBranch } from '../localization/localization.js';
+import { activeCondition } from './active-clause.js';
+import { isSingleChoiceTags, tagOptionValues } from '../seeds/tag-options.js';
+import { normalizeTagValue, TAG_OPTIONS_MAX_COUNT } from '../seeds/tag-value.js';
+/** SQLite GLOB twins of `LOCALE_CODE_RE` (`it`, `ast`, `pt-BR`, `es-419`, …). Keep both in sync. */
+const LOCALE_KEY_GLOBS = [
+    '[a-z][a-z]',
+    '[a-z][a-z][a-z]',
+    '[a-z][a-z]-[A-Z][A-Z]',
+    '[a-z][a-z][a-z]-[A-Z][A-Z]',
+    '[a-z][a-z]-[0-9][0-9][0-9]',
+    '[a-z][a-z][a-z]-[0-9][0-9][0-9]',
+];
+/** A locale code checked for inlining into SQL. The grammar check IS the injection guard — never skip it. */
+function inlineLocale(code) {
+    if (!isLocaleCode(code))
+        throw new TypeError(`Invalid locale code '${code}'`);
+    return code;
+}
+/**
+ * SQL twin of `resolveLocalizedValue`: the value of a localized column in `locale.code`. Self-contained
+ * (no bindings), because `buildFilterCondition` may interpolate a column more than once per clause.
+ * The nested CASE is deliberate: SQLite does not guarantee AND short-circuits, and `json_type` /
+ * `json_each` raise on malformed JSON (a legacy plain-text value).
+ * Dictionary detection mirrors `isStoredLocaleDictionary`: a non-empty object whose keys all match the
+ * locale grammar, and — for `json` only — at least one registered locale key.
+ */
+function localizedColumnSql(column, branch, locale) {
+    const keyIsLocale = LOCALE_KEY_GLOBS.map((glob) => `key GLOB '${glob}'`).join(' OR ');
+    const conditions = [
+        `json_type(${column}) = 'object'`,
+        `EXISTS (SELECT 1 FROM json_each(${column}))`,
+        `NOT EXISTS (SELECT 1 FROM json_each(${column}) WHERE NOT (${keyIsLocale}))`,
+    ];
+    if (branch.type === 'json') {
+        const registered = locale.config.locales.map((code) => `'${inlineLocale(code)}'`).join(', ');
+        conditions.push(`EXISTS (SELECT 1 FROM json_each(${column}) WHERE key IN (${registered}))`);
+    }
+    const path = (code) => `'$."${inlineLocale(code)}"'`;
+    const resolved = `COALESCE(` +
+        `NULLIF(json_extract(${column}, ${path(locale.code)}), ''), ` +
+        `NULLIF(json_extract(${column}, ${path(locale.config.defaultLocale)}), ''), ` +
+        `(SELECT value FROM json_each(${column}) WHERE value IS NOT NULL AND value != '' LIMIT 1))`;
+    return `(CASE WHEN json_valid(${column}) THEN ` +
+        `(CASE WHEN ${conditions.join(' AND ')} THEN ${resolved} ELSE ${column} END) ` +
+        `ELSE ${column} END)`;
+}
+/**
+ * The SQL reference for `alias` in WHERE / ORDER BY: table-qualified system column, localized expression
+ * when `locale` is set, bare alias otherwise (unchanged pre-localization behaviour).
+ */
+function columnSql(seed, table, alias, locale) {
+    if (SYSTEM_COLUMNS.has(alias))
+        return `${table}.${alias}`;
+    const branch = seed.branches.find((b) => b.alias === alias);
+    if (locale && branch && isLocalizedBranch(branch)) {
+        return localizedColumnSql(`${table}.${alias}`, branch, locale);
+    }
+    return alias;
+}
+/** A multiple-choice `tags` column has no meaningful order, so `orderBy` on it is ignored. */
+function isMultipleChoiceTagsColumn(seed, alias) {
+    const branch = seed.branches.find((b) => b.alias === alias);
+    return branch?.type === 'tags' && !isSingleChoiceTags(branch);
+}
+/**
+ * ORDER BY clause for a single-choice tags column: empty values (`NULL`, `[]`) always last, then the option
+ * position (a value outside the options ranks after every option) or, without options, the value alphabetically.
+ * Option values are pushed to `bindings`.
+ */
+function tagsOrderClause(col, branch, dir, bindings) {
+    const head = `(CASE WHEN json_valid(${col}) THEN json_extract(${col}, '$[0]') END)`;
+    const options = tagOptionValues(branch);
+    let rank = head;
+    if (options.length > 0) {
+        const branches = options.map((_, position) => `WHEN ? THEN ${position}`).join(' ');
+        rank = `CASE ${head} ${branches} ELSE ${options.length} END`;
+        bindings.push(...options);
+    }
+    return ` ORDER BY (${head} IS NULL) ASC, ${rank} ${dir}`;
+}
+/**
+ * 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);
+    }
+    // Soft delete: 'active' is the default, so a caller that forgets the option can never
+    // observe a trashed row — including the Public API, relation expansion and subqueries,
+    // which all reach SQL only through repository.findMany.
+    if (seed.softDelete) {
+        const trashed = options.trashed ?? 'active';
+        const cond = activeCondition(seed, trashed, table);
+        if (cond) {
+            whereClauses.push(cond);
+        }
+    }
+    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 = columnSql(seed, table, group.column, options.locale);
+        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 {
+                    throw new TypeError(`Invalid filter: operator '${op}' is not supported for encrypted field '${group.column}'`);
+                }
+            }
+            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) && !isMultipleChoiceTagsColumn(seed, orderBy.column)) {
+            const dir = orderBy.dir === 'DESC' ? 'DESC' : 'ASC';
+            const col = columnSql(seed, table, orderBy.column, options.locale);
+            const orderedBranch = seed.branches.find((b) => b.alias === orderBy.column);
+            sql += orderedBranch && isSingleChoiceTags(orderedBranch)
+                ? tagsOrderClause(col, orderedBranch, dir, bindings)
+                : ` 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 };
+}
+/**
+ * Lists the filter groups `buildSelectQuery` would silently leave out of the WHERE clause: an unknown
+ * column, or a condition whose value cannot be bound for the field type (empty or unparsable
+ * number/date, `in`/`not_in` value that is not an array). An empty `in` is not listed:
+ * it compiles to constant false and still constrains the read. A caller that needs the filter to constrain the read
+ * (e.g. automations resolving placeholders at run time) uses this to refuse the query instead of
+ * running it unconstrained.
+ *
+ * @param seed The seed the filters apply to.
+ * @param filters The filter groups to check.
+ * @returns The groups that would be dropped, in input order.
+ */
+export function findUnappliedFilters(seed, filters) {
+    return filters.filter((group) => !isValidColumn(seed, group.column)
+        || group.conditions.some((cond) => buildFilterCondition('col', group.type, cond, []) === null));
+}
+/**
+ * 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;
+}
+/** On a `tags` column, equality-like operators test membership; `negated` ones are the complement. */
+const TAGS_MEMBERSHIP_OPS = {
+    eq: { op: 'has_tag', negated: false },
+    contains: { op: 'has_tag', negated: false },
+    in: { op: 'has_any_tag', negated: false },
+    neq: { op: 'has_tag', negated: true },
+    not_contains: { op: 'has_tag', negated: true },
+    not_in: { op: 'has_any_tag', negated: true },
+};
+function buildTagsMembershipCondition(col, op, value, bindings) {
+    const { op: membershipOp, negated } = TAGS_MEMBERSHIP_OPS[op];
+    const isSetOp = membershipOp === 'has_any_tag';
+    let tags;
+    if (isSetOp) {
+        if (!Array.isArray(value))
+            return null;
+        tags = value.filter((v) => typeof v === 'string' || typeof v === 'number').map(String);
+        // Same rule as in/not_in: an empty set matches nothing, its negation adds no clause.
+        if (tags.length === 0)
+            return negated ? null : '0';
+    }
+    else {
+        if (typeof value !== 'string' && typeof value !== 'number')
+            return null;
+        tags = [String(value)];
+    }
+    const condition = buildFilterCondition(col, 'tags', { op: membershipOp, value: isSetOp ? tags : tags[0] }, bindings);
+    return negated && condition ? `NOT (${condition})` : condition;
+}
+/**
+ * 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' || type === 'repeater') {
+            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 (type === 'tags' && Object.hasOwn(TAGS_MEMBERSHIP_OPS, op)) {
+        return buildTagsMembershipCondition(col, op, value, bindings);
+    }
+    if (op === 'in' || op === 'not_in') {
+        if (!Array.isArray(value))
+            return null;
+        const normalizedValues = value
+            .map((v) => normalizeFilterValue(type, v))
+            .filter((v) => v !== null);
+        // Membership in an empty set is false, not "no constraint"; dropping it would widen the result set.
+        // `not_in` over an empty set is vacuously true, so it adds no clause.
+        if (normalizedValues.length === 0)
+            return op === 'in' ? '0' : 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 requested = [...new Set((op === 'has_tag' ? [value] : Array.isArray(value) ? value : [value]).map(t => String(t)))];
+        if (requested.length === 0)
+            return null;
+        // One bound parameter per tag and D1 allows 100 per statement: an oversized set is a malformed filter.
+        if (requested.length > TAG_OPTIONS_MAX_COUNT)
+            return null;
+        // A stored `tags` value is always normalized, so the needle is too. One that cannot be normalized
+        // (blank, too long, ill-formed) matches nothing, and `has_all_tags` over it can never be satisfied.
+        let tags = requested;
+        if (type === 'tags') {
+            const normalized = requested.flatMap((t) => {
+                const result = normalizeTagValue(t);
+                return result.ok && result.value.length > 0 ? [result.value] : [];
+            });
+            if (normalized.length === 0 || (op === 'has_all_tags' && normalized.length < requested.length))
+                return '0';
+            tags = [...new Set(normalized)];
+        }
+        // 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/query/relations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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/query/relations.d.ts.map

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