@beechcms/core 0.8.0 → 0.8.1

package/dist/file-types.d.ts

@@ -0,0 +1,13 @@
+export type FileAccept = 'image' | 'document' | 'any';
+export declare const IMAGE_EXTENSIONS: Set<string>;
+export declare const BLOCKED_IMAGE_EXTENSIONS: Set<string>;
+export declare const DOCUMENT_EXTENSIONS: Set<string>;
+export declare const ARCHIVE_EXTENSIONS: Set<string>;
+export declare const IMAGE_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/gif", "image/webp", "image/avif", "image/bmp", "image/x-icon", "image/vnd.microsoft.icon"];
+export declare const BLOCKED_IMAGE_MIME_TYPES: readonly ["image/svg+xml", "image/svg"];
+export declare const DOCUMENT_MIME_TYPES: readonly ["application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "text/plain", "text/csv", "text/markdown"];
+export declare const ARCHIVE_MIME_TYPES: readonly ["application/zip", "application/x-zip-compressed", "application/x-7z-compressed", "application/x-tar", "application/gzip", "application/json"];
+export declare function extensionFromUrl(url: string): string | null;
+export declare function isExtensionAccepted(ext: string | null, accept: FileAccept): boolean;
+export declare function isMimeAccepted(mime: string, accept: FileAccept): boolean;
+//# sourceMappingURL=file-types.d.ts.map

package/dist/file-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-types.d.ts","sourceRoot":"","sources":["../src/file-types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,CAAA;AAKrD,eAAO,MAAM,gBAAgB,aAAuE,CAAA;AACpG,eAAO,MAAM,wBAAwB,aAA2B,CAAA;AAChE,eAAO,MAAM,mBAAmB,aAAoF,CAAA;AACpH,eAAO,MAAM,kBAAkB,aAA8C,CAAA;AAI7E,eAAO,MAAM,gBAAgB,wIASnB,CAAA;AAGV,eAAO,MAAM,wBAAwB,yCAA0C,CAAA;AAC/E,eAAO,MAAM,mBAAmB,yXAWtB,CAAA;AACV,eAAO,MAAM,kBAAkB,0JAOrB,CAAA;AAEV,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS3D;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAMnF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAcxE"}

package/dist/file-types.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+// SVG is intentionally excluded: SVG can embed <script> tags and is rendered
+// inline by browsers when served as image/svg+xml on a same-origin route,
+// creating a stored XSS vector (see security audit finding #4).
+export const IMAGE_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'bmp', 'ico']);
+export const BLOCKED_IMAGE_EXTENSIONS = new Set(['svg', 'svgz']);
+export const DOCUMENT_EXTENSIONS = new Set(['pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'txt', 'csv', 'md']);
+export const ARCHIVE_EXTENSIONS = new Set(['zip', '7z', 'tar', 'gz', 'json']);
+// Explicitly enumerate safe image MIME types instead of using the wildcard
+// `image/*` prefix, which would permit `image/svg+xml` and other XSS vectors.
+export const IMAGE_MIME_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+    'image/avif',
+    'image/bmp',
+    'image/x-icon',
+    'image/vnd.microsoft.icon',
+];
+// Blocked image MIME types — listed explicitly so upload code can reject them
+// with a clear error rather than a generic "file type not allowed".
+export const BLOCKED_IMAGE_MIME_TYPES = ['image/svg+xml', 'image/svg'];
+export const DOCUMENT_MIME_TYPES = [
+    'application/pdf',
+    'application/msword',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.ms-excel',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.ms-powerpoint',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    'text/plain',
+    'text/csv',
+    'text/markdown',
+];
+export const ARCHIVE_MIME_TYPES = [
+    'application/zip',
+    'application/x-zip-compressed',
+    'application/x-7z-compressed',
+    'application/x-tar',
+    'application/gzip',
+    'application/json',
+];
+export function extensionFromUrl(url) {
+    try {
+        const path = new URL(url).pathname;
+        const dot = path.lastIndexOf('.');
+        if (dot < 0 || dot === path.length - 1)
+            return null;
+        return path.slice(dot + 1).toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+export function isExtensionAccepted(ext, accept) {
+    if (accept === 'any')
+        return true;
+    if (ext == null)
+        return false;
+    if (accept === 'image')
+        return IMAGE_EXTENSIONS.has(ext);
+    if (accept === 'document')
+        return DOCUMENT_EXTENSIONS.has(ext);
+    return false;
+}
+export function isMimeAccepted(mime, accept) {
+    // Normalise: strip parameters (e.g. "image/jpeg; charset=utf-8" → "image/jpeg")
+    const normalised = mime.split(';')[0].trim().toLowerCase();
+    // Unconditionally reject SVG regardless of accept mode — SVG can carry
+    // embedded scripts and is rendered by browsers when served inline.
+    if (BLOCKED_IMAGE_MIME_TYPES.includes(normalised))
+        return false;
+    if (accept === 'any') {
+        return IMAGE_MIME_TYPES.includes(normalised)
+            || DOCUMENT_MIME_TYPES.includes(normalised)
+            || ARCHIVE_MIME_TYPES.includes(normalised);
+    }
+    if (accept === 'image')
+        return IMAGE_MIME_TYPES.includes(normalised);
+    if (accept === 'document')
+        return DOCUMENT_MIME_TYPES.includes(normalised);
+    return false;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,29 @@
+import type { ContentRepository } from './content.repository.js';
+import type { Seed } from './types.js';
+export interface HookActor {
+    id: string;
+    role?: string;
+    email?: string;
+}
+export interface HookContext {
+    seed: Seed;
+    /** Canale lecito per side-effect sui contenuti dagli hook (rispetta la Botanical Engine). */
+    repository: ContentRepository;
+    /** Utente che esegue l'operazione, estratto dal JWT. Assente per operazioni di sistema/cron. */
+    actor?: HookActor;
+    /**
+     * Escape hatch per la connessione nativa (D1Database in prod, better-sqlite3 nei test).
+     * Tipizzato `unknown` per non accoppiare @beechcms/core a Cloudflare. Usare con cautela:
+     * scrivere qui bypassa la Botanical Engine.
+     */
+    db: unknown;
+}
+export interface BeechHooks {
+    beforeCreate?: (data: Record<string, any>, ctx: HookContext) => Promise<Record<string, any> | void> | Record<string, any> | void;
+    beforeUpdate?: (id: string, patches: Record<string, any>, ctx: HookContext) => Promise<Record<string, any> | void> | Record<string, any> | void;
+    beforeDelete?: (id: string, ctx: HookContext) => Promise<void> | void;
+    afterCreate?: (entry: Record<string, any>, ctx: HookContext) => Promise<void> | void;
+    afterUpdate?: (entry: Record<string, any>, ctx: HookContext) => Promise<void> | void;
+    afterDelete?: (id: string, ctx: HookContext) => Promise<void> | void;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAA;IACV,6FAA6F;IAC7F,UAAU,EAAE,iBAAiB,CAAA;IAC7B,gGAAgG;IAChG,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;;OAIG;IACH,EAAE,EAAE,OAAO,CAAA;CACZ;AAED,MAAM,WAAW,UAAU;IAGzB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;IAChI,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;IAC/I,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAGrE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACpF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACpF,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACrE"}

package/dist/hooks.js

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

package/dist/id-generator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Identifier abstraction. Hides direct calls to {@link crypto.randomUUID}
+ * so callers can swap in deterministic generators during tests for stable
+ * snapshot assertions and predictable insert ordering.
+ */
+export interface IIdGenerator {
+    /**
+     * Generates a new universally unique identifier.
+     * Production implementation delegates to crypto.randomUUID().
+     * Test implementations return deterministic values for snapshot assertions.
+     */
+    uuid(): string;
+    /**
+     * Returns true when `value` has the exact shape produced by `uuid()`.
+     * The ONLY place in the codebase that knows the id format. Never inline
+     * a regex; always go through this method when validating a relation id,
+     * a route param, or any user-supplied id.
+     */
+    isValid(value: unknown): value is string;
+}
+/**
+ * Production singleton. Delegates to the host runtime CSPRNG-backed UUID
+ * generator. Stateless and therefore safe to share across requests.
+ */
+export declare const SystemIdGenerator: IIdGenerator;
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../src/id-generator.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,IAAI,IAAI,MAAM,CAAA;IAEd;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAA;CACzC;AAMD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,YAI/B,CAAA"}

package/dist/id-generator.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+// Internal — never exported. Callers depend on the interface, not the shape.
+const SYSTEM_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Production singleton. Delegates to the host runtime CSPRNG-backed UUID
+ * generator. Stateless and therefore safe to share across requests.
+ */
+export const SystemIdGenerator = {
+    uuid: () => crypto.randomUUID(),
+    isValid: (value) => typeof value === 'string' && SYSTEM_ID_REGEX.test(value),
+};

package/dist/idempotency.repository.d.ts

@@ -0,0 +1,13 @@
+export interface IdempotencyRecord {
+    key: string;
+    fingerprint: string;
+    responseStatus: number;
+    responseBody: string;
+    expiresAt: number;
+}
+export interface IdempotencyRepository {
+    lookup(key: string): Promise<IdempotencyRecord | null>;
+    store(record: IdempotencyRecord): Promise<void>;
+    cleanup(now: number): Promise<void>;
+}
+//# sourceMappingURL=idempotency.repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.repository.d.ts","sourceRoot":"","sources":["../src/idempotency.repository.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;IACtD,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC"}

package/dist/idempotency.repository.js

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

package/dist/kanban-position.repository.d.ts

@@ -0,0 +1,19 @@
+export interface KanbanPositionRecord {
+    entryId: string;
+    position: string;
+}
+/**
+ * Persistence contract for card ordering. The ONLY gateway to `kanban_positions`.
+ * Handlers and the dashboard never touch the table directly (Botanical invariant).
+ */
+export interface IKanbanPositionRepository {
+    /** entryId → position for one column axis (entries without a row are omitted). */
+    getColumn(seedSlug: string, axisBranchId: string): Promise<Map<string, string>>;
+    /** Single-row upsert — exactly one write per drag (KB-S04b). */
+    setPosition(seedSlug: string, entryId: string, axisBranchId: string, position: string): Promise<void>;
+    /** Remove an entry's position row (e.g. entry deleted). */
+    remove(seedSlug: string, entryId: string, axisBranchId: string): Promise<void>;
+    /** Async rebalance (KB-S04f): rewrite a whole column's positions in one batch. */
+    rebalance(seedSlug: string, axisBranchId: string, ordered: KanbanPositionRecord[]): Promise<void>;
+}
+//# sourceMappingURL=kanban-position.repository.d.ts.map

package/dist/kanban-position.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kanban-position.repository.d.ts","sourceRoot":"","sources":["../src/kanban-position.repository.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/E,gEAAgE;IAChE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrG,2DAA2D;IAC3D,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9E,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClG"}

package/dist/kanban-position.repository.js

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

package/dist/kanban.d.ts

@@ -0,0 +1,75 @@
+import type { Seed, Branch, FilterGroup } from './types.js';
+/** Branch types that can form a discrete, finite set of columns (KB §2). */
+export type KanbanAxisBranchType = 'text' | 'tags' | 'boolean';
+/** A branch eligible to be the kanban axis. */
+export interface KanbanAxisCandidate {
+    /** Stable branch id (br_XX) — persisted as the axis key. Never the alias. */
+    branchId: string;
+    alias: string;
+    label: string;
+    type: KanbanAxisBranchType;
+}
+/** A single column on the board, in deterministic display order (Q2). */
+export interface KanbanColumnDescriptor {
+    /** The discrete axis value. `null` ⇒ the always-last "Senza valore" column. */
+    value: string | null;
+    label: string;
+}
+/** Per-seed, dashboard-side kanban view preferences. Persisted in
+ *  seed_layouts.view_config (KB-S02). NOT part of FormLayout. */
+export interface KanbanConfig {
+    /** Chosen axis branch id, or null when the user has not configured one (KB-U02). */
+    axisBranchId: string | null;
+    /** Card sort inside columns. null ⇒ manual order via kanban_positions (KB-U22b). */
+    sort: {
+        branchId: string;
+        dir: 'ASC' | 'DESC';
+    } | null;
+    /** Axis values the user chose to hide when columns exceed the cap (KB-U06c). */
+    hiddenColumnValues?: string[];
+}
+export type KanbanIncompatibleReason = 'drafts-enabled' | 'no-candidate-branch';
+export interface KanbanCompatibility {
+    compatible: boolean;
+    reason?: KanbanIncompatibleReason;
+    candidates: KanbanAxisCandidate[];
+}
+/**
+ * Determines whether a seed can be displayed as a Kanban board, and which
+ * branches may serve as the column axis. Pure — no I/O. (KB-S01)
+ *
+ * Q3: seeds with `allowDrafts: true` are NOT kanban-compatible.
+ */
+export declare function resolveKanbanConfig(seed: Seed): KanbanCompatibility;
+/**
+ * Deterministic, stable column order for a chosen axis (Q2). The "Senza valore"
+ * (value: null) column is always appended last. Values out of `options` are NOT
+ * given their own column (KB-U25) — the board folds them into "Senza valore".
+ *
+ * @param distinctTagValues unique tag values observed in data (tags axis without options).
+ */
+export declare function resolveKanbanColumns(branch: Branch, distinctTagValues?: string[]): KanbanColumnDescriptor[];
+/**
+ * Pure: the FilterGroup selecting one kanban column's entries for a given axis branch.
+ * `value: null` ⇒ "Senza valore" — entries where the axis field is NULL or empty (KB-U25).
+ * Boolean descriptor values 'true'/'false' are coerced to actual booleans for the engine.
+ */
+/** Body of PATCH /:slug/:id/kanban-move. The server applies the axis change (if any)
+ *  AND the position upsert atomically (KB-S04e). */
+export interface KanbanMoveBody {
+    /** Axis branch id (br_XX). Identifies which kanban_positions row + which branch to patch. */
+    axisBranchId: string;
+    /** New fractional-index key for this entry in the destination column (KB-S04b/d). */
+    position: string;
+    /** Present only on a cross-column move (axis value changed). Omit for same-column reorder. */
+    axis?: {
+        kind: 'scalar';
+        value: string | null;
+    } | {
+        kind: 'tags';
+        oldValue: string | null;
+        newValue: string | null;
+    };
+}
+export declare function kanbanColumnFilter(branch: Branch, value: string | null): FilterGroup;
+//# sourceMappingURL=kanban.d.ts.map

package/dist/kanban.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kanban.d.ts","sourceRoot":"","sources":["../src/kanban.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D,4EAA4E;AAC5E,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;AAE9D,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,oBAAoB,CAAA;CAC3B;AAED,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,EAAE,MAAM,CAAA;CACd;AAED;iEACiE;AACjE,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,oFAAoF;IACpF,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACtD,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC9B;AAED,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,GAAG,qBAAqB,CAAA;AAE/E,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,wBAAwB,CAAA;IACjC,UAAU,EAAE,mBAAmB,EAAE,CAAA;CAClC;AAgBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,mBAAmB,CAanE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,iBAAiB,GAAE,MAAM,EAAO,GAC/B,sBAAsB,EAAE,CAiB1B;AAED;;;;GAIG;AACH;oDACoD;AACpD,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,YAAY,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAA;IAChB,8FAA8F;IAC9F,IAAI,CAAC,EACD;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GACxC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CACvE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,CAYpF"}

package/dist/kanban.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Branch types that are explicitly never an axis (KB §2). */
+const NON_AXIS_TYPES = new Set([
+    'richtext', 'file', 'number', 'date', 'json', 'relation', 'repeater',
+]);
+function isAxisCandidate(b) {
+    if (b.alias === 'status')
+        return null; // system status excluded (KB §2)
+    if (NON_AXIS_TYPES.has(b.type))
+        return null;
+    if (b.type === 'text')
+        return (b.options && b.options.length > 0) ? 'text' : null;
+    if (b.type === 'tags')
+        return 'tags';
+    if (b.type === 'boolean')
+        return 'boolean';
+    return null;
+}
+/**
+ * Determines whether a seed can be displayed as a Kanban board, and which
+ * branches may serve as the column axis. Pure — no I/O. (KB-S01)
+ *
+ * Q3: seeds with `allowDrafts: true` are NOT kanban-compatible.
+ */
+export function resolveKanbanConfig(seed) {
+    if (seed.allowDrafts) {
+        return { compatible: false, reason: 'drafts-enabled', candidates: [] };
+    }
+    const candidates = [];
+    for (const b of seed.branches) {
+        const type = isAxisCandidate(b);
+        if (type)
+            candidates.push({ branchId: b.id, alias: b.alias, label: b.label, type });
+    }
+    if (candidates.length === 0) {
+        return { compatible: false, reason: 'no-candidate-branch', candidates: [] };
+    }
+    return { compatible: true, candidates };
+}
+/**
+ * Deterministic, stable column order for a chosen axis (Q2). The "Senza valore"
+ * (value: null) column is always appended last. Values out of `options` are NOT
+ * given their own column (KB-U25) — the board folds them into "Senza valore".
+ *
+ * @param distinctTagValues unique tag values observed in data (tags axis without options).
+ */
+export function resolveKanbanColumns(branch, distinctTagValues = []) {
+    const cols = [];
+    if (branch.type === 'boolean') {
+        cols.push({ value: 'false', label: 'No' }, { value: 'true', label: 'Sì' }); // [false, true]
+    }
+    else if (branch.type === 'text' && branch.options?.length) {
+        for (const o of branch.options)
+            cols.push({ value: o, label: o }); // options order
+    }
+    else if (branch.type === 'tags') {
+        const ordered = branch.options?.length
+            ? branch.options
+            : [...distinctTagValues].sort((a, b) => a.localeCompare(b)); // alphabetical
+        for (const o of ordered)
+            cols.push({ value: o, label: o });
+    }
+    const isRequired = Boolean(branch.requiredOnCreate || branch.requiredOnUpdate);
+    if (!isRequired) {
+        cols.push({ value: null, label: `Senza ${branch.label}` }); // always last if not required
+    }
+    return cols;
+}
+export function kanbanColumnFilter(branch, value) {
+    if (value === null) {
+        const type = branch.type === 'boolean' ? 'boolean' : branch.type === 'tags' ? 'tags' : 'text';
+        return { column: branch.alias, type, conditions: [{ op: 'is_empty', value: null }] };
+    }
+    if (branch.type === 'boolean') {
+        return { column: branch.alias, type: 'boolean', conditions: [{ op: 'eq', value: value === 'true' }] };
+    }
+    if (branch.type === 'tags') {
+        return { column: branch.alias, type: 'tags', conditions: [{ op: 'has_tag', value }] };
+    }
+    return { column: branch.alias, type: 'select', conditions: [{ op: 'eq', value }] };
+}

package/dist/layout-permissions.d.ts

@@ -0,0 +1,3 @@
+export declare const ROLES_ALLOWED_TO_EDIT_LAYOUT: ReadonlyArray<string>;
+export declare function canEditLayout(role: string | undefined | null): boolean;
+//# sourceMappingURL=layout-permissions.d.ts.map

package/dist/layout-permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-permissions.d.ts","sourceRoot":"","sources":["../src/layout-permissions.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,4BAA4B,EAAE,aAAa,CAAC,MAAM,CAAa,CAAA;AAE5E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAGtE"}

package/dist/layout-permissions.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+// NOTE: change this list to extend write-access to other roles
+// (e.g. add 'editor', or introduce a fine-grained 'layout:edit' permission).
+// Single source of truth — used by both API guards and dashboard buttons.
+export const ROLES_ALLOWED_TO_EDIT_LAYOUT = ['admin'];
+export function canEditLayout(role) {
+    if (!role)
+        return false;
+    return ROLES_ALLOWED_TO_EDIT_LAYOUT.includes(role);
+}

package/dist/media/image-transformer.d.ts

@@ -0,0 +1,34 @@
+/** Pixel dimensions of an image. */
+export interface MediaDimensions {
+    readonly width: number;
+    readonly height: number;
+}
+/** Output MIME types the transform path may emit. AVIF is deliberately absent (v1). */
+export type ImageOutputMime = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+/**
+ * A fully resolved transformation. Every number here comes from a pre-registered preset or from
+ * MEDIA_QUALITY_VALUES — never from the request.
+ */
+export interface ImageTransformSpec {
+    readonly width: number;
+    /** Present for crop presets only; scale presets derive height from the source aspect ratio. */
+    readonly height?: number;
+    readonly fit: 'cover' | 'scale-down';
+    readonly outputMime: ImageOutputMime;
+    readonly quality: number;
+}
+export interface TransformedImage {
+    readonly body: ReadableStream<Uint8Array>;
+    readonly contentType: string;
+}
+/**
+ * Port for edge image transformation. The API injects a Cloudflare Images adapter when the
+ * `IMAGES` binding exists and `null` otherwise; handlers never see the binding itself.
+ */
+export interface IImageTransformer {
+    /** Reads the source's pixel dimensions. Rejects when the stream is not a raster image. */
+    probe(source: ReadableStream<Uint8Array>): Promise<MediaDimensions>;
+    /** Applies the spec and returns the encoded variant. */
+    transform(source: ReadableStream<Uint8Array>, spec: ImageTransformSpec): Promise<TransformedImage>;
+}
+//# sourceMappingURL=image-transformer.d.ts.map

package/dist/media/image-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-transformer.d.ts","sourceRoot":"","sources":["../../src/media/image-transformer.ts"],"names":[],"mappings":"AAGA,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,uFAAuF;AACvF,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,CAAA;AAErF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACnE,wDAAwD;IACxD,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACnG"}

package/dist/media/image-transformer.js

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

package/dist/media/media-transform.d.ts

@@ -0,0 +1,88 @@
+import type { ImageOutputMime, ImageTransformSpec, MediaDimensions } from './image-transformer.js';
+/** Default ceiling, in pixels, on either side of a derived variant. Covers native 32:9 ultrawide panels. */
+export declare const DEFAULT_MEDIA_MAX_DIMENSION = 5120;
+/** MEDIA_MAX_DIMENSION may lower the ceiling freely but raise it only this far. */
+export declare const ABSOLUTE_MAX_MEDIA_DIMENSION = 8192;
+export type MediaOutputFormat = 'original' | 'webp' | 'jpeg';
+export type MediaQuality = 'low' | 'medium' | 'high';
+export declare const MEDIA_OUTPUT_FORMATS: readonly MediaOutputFormat[];
+export declare const MEDIA_QUALITIES: readonly MediaQuality[];
+export declare const DEFAULT_MEDIA_FORMAT: MediaOutputFormat;
+export declare const DEFAULT_MEDIA_QUALITY: MediaQuality;
+/** Encoder quality per enum value. `medium` ≈ 82 per the brief. */
+export declare const MEDIA_QUALITY_VALUES: Readonly<Record<MediaQuality, number>>;
+export type MediaPreset = {
+    readonly kind: 'crop';
+    readonly width: number;
+    readonly height: number;
+} | {
+    readonly kind: 'scale';
+    readonly width: number;
+};
+export type MediaPresetCatalog = ReadonlyMap<string, MediaPreset>;
+export declare const DEFAULT_MEDIA_SCALE_WIDTHS: readonly [320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560, 3840, 5120];
+export declare const DEFAULT_MEDIA_PRESETS: Readonly<Record<string, MediaPreset>>;
+/** Raster sources the transform path accepts. Everything else — SVG, PDF, video, AVIF, BMP, ICO — is refused. */
+export declare const TRANSFORMABLE_MEDIA_MIME_TYPES: readonly ImageOutputMime[];
+/** Parameters of the discarded free-form contract. Their presence is an error, never ignored. */
+export declare const FORBIDDEN_MEDIA_TRANSFORM_PARAMS: readonly string[];
+export type MediaTransformErrorCode = 'media_param_forbidden' | 'media_param_duplicated' | 'media_preset_required' | 'media_format_invalid' | 'media_quality_invalid' | 'media_preset_unknown' | 'media_not_transformable' | 'media_dimension_exceeded';
+export interface MediaTransformRequest {
+    readonly preset: string;
+    readonly format: MediaOutputFormat;
+    readonly quality: MediaQuality;
+}
+export type MediaTransformQuery = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'invalid';
+    readonly code: MediaTransformErrorCode;
+} | {
+    readonly kind: 'transform';
+    readonly request: MediaTransformRequest;
+};
+/** Thrown by buildMediaPresetCatalog on any malformed MEDIA_PRESETS entry. Fail closed, never fall back. */
+export declare class MediaPresetCatalogError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * Classifies a media query string. Pure: does not consult the catalog (that is env-dependent and
+ * resolved by the caller), so an unknown-but-well-formed preset name returns `transform`.
+ */
+export declare function parseMediaTransformQuery(params: URLSearchParams): MediaTransformQuery;
+/**
+ * Canonical query for a request: fixed order preset → format → quality, defaults omitted.
+ * `@beechcms/client` emits exactly this string; the server recomputes it and never trusts the client's.
+ */
+export declare function canonicalMediaTransformQuery(request: MediaTransformRequest): string;
+/**
+ * Builds the active catalog: DEFAULT_MEDIA_PRESETS merged by name with `overrides`
+ * (the parsed MEDIA_PRESETS JSON). An override value of `null` removes a preset.
+ * Defaults larger than `maxDimension` are dropped (they could only ever 400); an operator-supplied
+ * preset larger than `maxDimension` is an error.
+ *
+ * @throws {MediaPresetCatalogError} on any malformed override.
+ */
+export declare function buildMediaPresetCatalog(overrides: unknown, maxDimension: number): MediaPresetCatalog;
+export declare function isTransformableMime(mime: string | null | undefined): boolean;
+/**
+ * Output dimensions of a scale preset (`fit=scale-down`: never upscales). Returns `null` when either
+ * side would exceed `maxDimension` — the pathological-aspect-ratio guard of brief §4. Never truncates.
+ */
+export declare function deriveScaleOutput(presetWidth: number, source: MediaDimensions, maxDimension: number): MediaDimensions | null;
+/** Identity of a preset's *definition*, so redefining a name never reuses an old variant. */
+export declare function mediaPresetSignature(preset: MediaPreset): string;
+/** Precondition: `isTransformableMime(sourceMime)` is true. */
+export declare function buildImageTransformSpec(preset: MediaPreset, request: MediaTransformRequest, sourceMime: string): ImageTransformSpec;
+/**
+ * Strong ETag of a variant: source identity (key + size — keys are never overwritten) plus the
+ * canonical request plus the preset definition. Format: `"mv1-<32 hex>"`.
+ */
+export declare function computeMediaVariantEtag(source: {
+    readonly key: string;
+    readonly size: number;
+}, request: MediaTransformRequest, preset: MediaPreset): Promise<string>;
+/** RFC 9110 §13.1.2: `*` matches; otherwise weak comparison against a comma-separated list. */
+export declare function ifNoneMatchMatches(header: string | null | undefined, etag: string | null | undefined): boolean;
+//# sourceMappingURL=media-transform.d.ts.map

package/dist/media/media-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-transform.d.ts","sourceRoot":"","sources":["../../src/media/media-transform.ts"],"names":[],"mappings":"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"}