@beechcms/core 0.5.0 → 0.6.0-preview.2

package/dist/seed-layout.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import type { Seed, Branch } from './types.js';
+/** Reference to a Seed branch by its stable id (e.g. 'br_03').
+ *  Aliases can be renamed — ids cannot. When the id does not match any
+ *  branch on the Seed at read time, the field is silently stripped (auto-cleanup). */
+export interface LayoutField {
+    branchId: string;
+}
+export interface LayoutColumn {
+    id: string;
+    fields: LayoutField[];
+}
+export interface LayoutSection {
+    id: string;
+    label?: string;
+    hideLabel?: boolean;
+    hideBorder?: boolean;
+    collapsible?: boolean;
+    /** Max 4 columns. Enforced by validator. */
+    columns: LayoutColumn[];
+}
+export interface LayoutTab {
+    id: string;
+    label: string;
+    sections: LayoutSection[];
+}
+export interface FormLayout {
+    /** Format version — bump when introducing breaking changes. */
+    version: 1;
+    tabs: LayoutTab[];
+}
+/** Branch types that must occupy a section alone, full width. */
+export declare const FULL_WIDTH_BRANCH_TYPES: Set<import("./types.js").BranchType>;
+/** Returns true when a branch is a gallery (file + multiple/asset-list). */
+export declare function isGalleryBranch(branch: Branch): boolean;
+/** Branch types currently unsupported in the Layout Builder. */
+export declare const UNSUPPORTED_BRANCH_TYPES: Set<import("./types.js").BranchType>;
+/** Aliases that are NEVER included in the editor form (handled by other UI). */
+export declare const SYSTEM_ALIASES: Set<string>;
+/** True when the branch is eligible to appear in the layout at all. */
+export declare function isLayoutableBranch(branch: Branch): boolean;
+/** True when the branch must occupy a dedicated full-width section. */
+export declare function isFullWidthBranch(branch: Branch): boolean;
+/** Branches considered SEO fields. Matches the existing rule in entry-editor.tsx. */
+export declare function isSeoBranch(branch: Branch): boolean;
+export declare const layoutFieldSchema: z.ZodObject<{
+    branchId: z.ZodString;
+}, z.core.$strip>;
+export declare const layoutColumnSchema: z.ZodObject<{
+    id: z.ZodString;
+    fields: z.ZodArray<z.ZodObject<{
+        branchId: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const layoutSectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    hideLabel: z.ZodOptional<z.ZodBoolean>;
+    hideBorder: z.ZodOptional<z.ZodBoolean>;
+    collapsible: z.ZodOptional<z.ZodBoolean>;
+    columns: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        fields: z.ZodArray<z.ZodObject<{
+            branchId: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const layoutTabSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    sections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        hideLabel: z.ZodOptional<z.ZodBoolean>;
+        hideBorder: z.ZodOptional<z.ZodBoolean>;
+        collapsible: z.ZodOptional<z.ZodBoolean>;
+        columns: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            fields: z.ZodArray<z.ZodObject<{
+                branchId: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const formLayoutSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    tabs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        sections: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            hideLabel: z.ZodOptional<z.ZodBoolean>;
+            hideBorder: z.ZodOptional<z.ZodBoolean>;
+            collapsible: z.ZodOptional<z.ZodBoolean>;
+            columns: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                fields: z.ZodArray<z.ZodObject<{
+                    branchId: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function generateDefaultLayout(seed: Seed, opts?: {
+    newId: () => string;
+}): FormLayout;
+export type ValidateLayoutResult = {
+    ok: true;
+    cleaned: FormLayout;
+} | {
+    ok: false;
+    errors: string[];
+    cleaned: FormLayout;
+};
+export declare function validateLayoutAgainstSeed(layout: FormLayout, seed: Seed): ValidateLayoutResult;
+//# sourceMappingURL=seed-layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed-layout.d.ts","sourceRoot":"","sources":["../src/seed-layout.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAO9C;;sFAEsF;AACtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4CAA4C;IAC5C,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,aAAa,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,OAAO,EAAE,CAAC,CAAA;IACV,IAAI,EAAE,SAAS,EAAE,CAAA;CAClB;AAMD,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,sCAAwC,CAAA;AAE5E,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,sCAAoC,CAAA;AAEzE,gFAAgF;AAChF,eAAO,MAAM,cAAc,aAEzB,CAAA;AAEF,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK1D;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAMD,eAAO,MAAM,iBAAiB;;iBAAgE,CAAA;AAC9F,eAAO,MAAM,kBAAkB;;;;;iBAG7B,CAAA;AACF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;iBAO9B,CAAA;AACF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;iBAI1B,CAAA;AACF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;iBAG3B,CAAA;AAiDF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,MAAM,CAAA;CAAE,GAC7B,UAAU,CAmBZ;AAMD,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAA;AAExD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,IAAI,GACT,oBAAoB,CAsDtB"}

package/dist/seed-layout.js

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { z } from 'zod';
+import { findBranchById } from './seed-registry.js';
+// ---------------------------------------------------------------------------
+// Branch-type rules used by both the default generator and the validator.
+// ---------------------------------------------------------------------------
+/** Branch types that must occupy a section alone, full width. */
+export const FULL_WIDTH_BRANCH_TYPES = new Set(['richtext']);
+/** Returns true when a branch is a gallery (file + multiple/asset-list). */
+export function isGalleryBranch(branch) {
+    return branch.type === 'file'
+        && (branch.multiple === true || branch.format === 'asset-list');
+}
+/** Branch types currently unsupported in the Layout Builder. */
+export const UNSUPPORTED_BRANCH_TYPES = new Set(['json']);
+/** Aliases that are NEVER included in the editor form (handled by other UI). */
+export const SYSTEM_ALIASES = new Set([
+    'id', 'slug', 'status', 'created_at', 'updated_at',
+]);
+/** True when the branch is eligible to appear in the layout at all. */
+export function isLayoutableBranch(branch) {
+    if (SYSTEM_ALIASES.has(branch.alias))
+        return false;
+    if (branch.policies?.visibility === 'hidden')
+        return false;
+    if (UNSUPPORTED_BRANCH_TYPES.has(branch.type))
+        return false;
+    return true;
+}
+/** True when the branch must occupy a dedicated full-width section. */
+export function isFullWidthBranch(branch) {
+    return FULL_WIDTH_BRANCH_TYPES.has(branch.type) || isGalleryBranch(branch);
+}
+/** Branches considered SEO fields. Matches the existing rule in entry-editor.tsx. */
+export function isSeoBranch(branch) {
+    return branch.alias.startsWith('meta');
+}
+// ---------------------------------------------------------------------------
+// Zod schema for shape validation
+// ---------------------------------------------------------------------------
+export const layoutFieldSchema = z.object({ branchId: z.string().regex(/^br_[A-Za-z0-9]+$/) });
+export const layoutColumnSchema = z.object({
+    id: z.string().min(1),
+    fields: z.array(layoutFieldSchema),
+});
+export const layoutSectionSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().optional(),
+    hideLabel: z.boolean().optional(),
+    hideBorder: z.boolean().optional(),
+    collapsible: z.boolean().optional(),
+    columns: z.array(layoutColumnSchema).min(1).max(4),
+});
+export const layoutTabSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1).max(60),
+    sections: z.array(layoutSectionSchema).min(1),
+});
+export const formLayoutSchema = z.object({
+    version: z.literal(1),
+    tabs: z.array(layoutTabSchema).min(1).max(8),
+});
+// ---------------------------------------------------------------------------
+// Default layout generator
+// ---------------------------------------------------------------------------
+const DEFAULT_COLUMNS_PER_SECTION = 3;
+const defaultIdFactory = () => crypto.randomUUID();
+function buildSectionsForBranches(branches, newId) {
+    const sections = [];
+    let currentColumns = [];
+    function flushCompact() {
+        if (currentColumns.length === 0)
+            return;
+        sections.push({ id: newId(), columns: currentColumns });
+        currentColumns = [];
+    }
+    for (const branch of branches) {
+        if (isFullWidthBranch(branch)) {
+            flushCompact();
+            sections.push({
+                id: newId(),
+                label: branch.label,
+                hideLabel: true,
+                columns: [{ id: newId(), fields: [{ branchId: branch.id }] }],
+            });
+        }
+        else {
+            currentColumns.push({ id: newId(), fields: [{ branchId: branch.id }] });
+            if (currentColumns.length >= DEFAULT_COLUMNS_PER_SECTION) {
+                flushCompact();
+            }
+        }
+    }
+    flushCompact();
+    if (sections.length === 0) {
+        sections.push({ id: newId(), columns: [{ id: newId(), fields: [] }] });
+    }
+    return sections;
+}
+export function generateDefaultLayout(seed, opts) {
+    const newId = opts?.newId ?? defaultIdFactory;
+    const layoutable = seed.branches.filter(isLayoutableBranch);
+    const seo = layoutable.filter(isSeoBranch);
+    const main = layoutable.filter((b) => !isSeoBranch(b));
+    const dataTab = {
+        id: newId(),
+        label: 'Data',
+        sections: buildSectionsForBranches(main, newId),
+    };
+    const seoTab = {
+        id: newId(),
+        label: 'SEO',
+        sections: buildSectionsForBranches(seo, newId),
+    };
+    return { version: 1, tabs: [dataTab, seoTab] };
+}
+export function validateLayoutAgainstSeed(layout, seed) {
+    const errors = [];
+    const seenBranchIds = new Set();
+    const cleanedTabs = layout.tabs.map((tab) => ({
+        ...tab,
+        sections: tab.sections.map((section) => ({
+            ...section,
+            columns: section.columns.map((col) => ({
+                ...col,
+                fields: (col.fields ?? []).filter((f) => {
+                    const branch = findBranchById(seed, f.branchId);
+                    if (!branch)
+                        return false;
+                    if (UNSUPPORTED_BRANCH_TYPES.has(branch.type) || SYSTEM_ALIASES.has(branch.alias))
+                        return false;
+                    return true;
+                }),
+            })),
+        })),
+    }));
+    // Duplicate and full-width constraint checks on cleaned layout
+    for (const tab of cleanedTabs) {
+        for (const section of tab.sections) {
+            const fieldsInSection = [];
+            for (const col of section.columns) {
+                for (const f of col.fields) {
+                    const branch = findBranchById(seed, f.branchId);
+                    if (!branch)
+                        continue;
+                    if (seenBranchIds.has(f.branchId)) {
+                        errors.push(`Branch '${branch.alias}' (id=${f.branchId}) appears more than once in the layout.`);
+                    }
+                    else {
+                        seenBranchIds.add(f.branchId);
+                        fieldsInSection.push(branch);
+                    }
+                }
+            }
+            // Full-width branches must occupy a dedicated section
+            const fullWidthInSection = fieldsInSection.filter(isFullWidthBranch);
+            if (fullWidthInSection.length > 0 && fieldsInSection.length > fullWidthInSection.length) {
+                for (const fw of fullWidthInSection) {
+                    errors.push(`Branch '${fw.alias}' (type=${fw.type}) must occupy a dedicated section and cannot share it with other fields.`);
+                }
+            }
+        }
+    }
+    const cleaned = { ...layout, tabs: cleanedTabs };
+    if (errors.length > 0)
+        return { ok: false, errors, cleaned };
+    return { ok: true, cleaned };
+}

package/dist/seed-layout.repository.d.ts

@@ -0,0 +1,18 @@
+import type { FormLayout } from './seed-layout.js';
+export interface SeedLayoutRecord {
+    slug: string;
+    layout: FormLayout;
+    updatedAt: number;
+    updatedBy: string;
+}
+export interface ISeedLayoutRepository {
+    /** Return the stored layout for a seed, or null if none was ever saved. */
+    get(slug: string): Promise<SeedLayoutRecord | null>;
+    /** Return all stored layouts, keyed by slug — used by GET /api/schema to enrich. */
+    getAllAsMap(): Promise<Map<string, FormLayout>>;
+    /** Upsert. `updatedBy` is the writer's user id. */
+    upsert(slug: string, layout: FormLayout, updatedBy: string): Promise<void>;
+    /** Remove the stored row — used by the "Reset" action. */
+    remove(slug: string): Promise<void>;
+}
+//# sourceMappingURL=seed-layout.repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed-layout.repository.d.ts","sourceRoot":"","sources":["../src/seed-layout.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,UAAU,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IACnD,oFAAoF;IACpF,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;IAC/C,mDAAmD;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1E,0DAA0D;IAC1D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpC"}

package/dist/seed-layout.repository.js

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

package/dist/seed-registry.d.ts

@@ -1,4 +1,4 @@
-import type { Seed } from './types.js';
+import type { Seed, Branch } from './types.js';
 export interface ISeedRegistry {
     /**
      * Returns all seeds as a flat array, preserving insertion order.
@@ -46,4 +46,26 @@ export declare class SeedRegistry implements ISeedRegistry {
  */
 export declare class InMemorySeedRegistry extends SeedRegistry {
 }
+/** Finds a branch by its stable id within a Seed. Returns null if not found. */
+export declare function findBranchById(seed: Seed, id: string): Branch | null;
+/**
+ * Returns the next free branch id for a seed in the form `br_NN` (zero-padded to 2,
+ * growing as needed). Scans existing ids, never reuses a number already present —
+ * even if a branch was removed, its id is not recycled (ids must be globally stable
+ * for the life of the seed so layouts/automations/FTS triggers never collide).
+ */
+export declare function nextBranchId(seed: Pick<Seed, 'branches'>): string;
+/**
+ * Returns the input seeds reordered so that every seed appears AFTER all the
+ * seeds it depends on (its `relation` branch targets). Pure function — does
+ * not read from any global registry.
+ *
+ * Uses Kahn's algorithm (BFS on in-degree) for cycle detection and topological
+ * ordering. Sprint 3 (CLI / migration runner) consumes this to create tables in
+ * the correct order without disabling SQLite FK constraints.
+ *
+ * @throws {Error} When a relation targets an unknown slug not in `seeds`.
+ * @throws {Error} When a cyclic dependency is detected, listing involved slugs.
+ */
+export declare function sortSeedsByDependencies(seeds: ReadonlyArray<Seed>): Seed[];
 //# sourceMappingURL=seed-registry.d.ts.map

package/dist/seed-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../src/seed-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAGtC,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,IAAI,IAAI,EAAE,CAAA;IAEb;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9B;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,IAAI,IAAI,EAAE,CAAA;IAExB;;;OAGG;IACH,YAAY,IAAI,IAAI,EAAE,CAAA;CACvB;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,KAAK,EAAE,IAAI,EAAE;IAezB,GAAG,IAAI,IAAI,EAAE;IAIb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI9B,kBAAkB,IAAI,IAAI,EAAE;IAI5B,cAAc,IAAI,IAAI,EAAE;IAIxB,YAAY,IAAI,IAAI,EAAE;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG"}
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../src/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAG9C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,IAAI,IAAI,EAAE,CAAA;IAEb;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9B;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,IAAI,IAAI,EAAE,CAAA;IAExB;;;OAGG;IACH,YAAY,IAAI,IAAI,EAAE,CAAA;CACvB;AAID,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,KAAK,EAAE,IAAI,EAAE;IA4BzB,GAAG,IAAI,IAAI,EAAE;IAIb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI9B,kBAAkB,IAAI,IAAI,EAAE;IAI5B,cAAc,IAAI,IAAI,EAAE;IAIxB,YAAY,IAAI,IAAI,EAAE;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG;AAEzD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,MAAM,CAQjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAsE1E"}

package/dist/seed-registry.js

@@ -1,14 +1,26 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
 import { AUTOMATION_RESERVED_WORDS } from './automations-grammar-words.js';
+const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
 export class SeedRegistry {
     seedMap;
     orderedSeeds;
     constructor(seeds) {
         for (const seed of seeds) {
+            const idsInSeed = new Set();
             for (const branch of seed.branches) {
                 if (AUTOMATION_RESERVED_WORDS.has(branch.alias)) {
                     throw new Error(`Seed "${seed.slug}" uses reserved alias "${branch.alias}". `
                         + `Pick a different alias — this word is used by the automation template grammar.`);
                 }
+                if (!branch.id || !BRANCH_ID_RE.test(branch.id)) {
+                    throw new Error(`Seed "${seed.slug}" branch "${branch.alias}" has invalid id "${branch.id}". `
+                        + `Expected format ^br_[A-Za-z0-9]+$.`);
+                }
+                if (idsInSeed.has(branch.id)) {
+                    throw new Error(`Seed "${seed.slug}" has duplicate branch id "${branch.id}".`);
+                }
+                idsInSeed.add(branch.id);
             }
         }
         this.orderedSeeds = seeds;
@@ -36,3 +48,96 @@ export class SeedRegistry {
  */
 export class InMemorySeedRegistry extends SeedRegistry {
 }
+/** Finds a branch by its stable id within a Seed. Returns null if not found. */
+export function findBranchById(seed, id) {
+    return seed.branches.find(b => b.id === id) ?? null;
+}
+/**
+ * Returns the next free branch id for a seed in the form `br_NN` (zero-padded to 2,
+ * growing as needed). Scans existing ids, never reuses a number already present —
+ * even if a branch was removed, its id is not recycled (ids must be globally stable
+ * for the life of the seed so layouts/automations/FTS triggers never collide).
+ */
+export function nextBranchId(seed) {
+    let max = 0;
+    for (const b of seed.branches) {
+        const m = /^br_0*([0-9]+)$/.exec(b.id);
+        if (m)
+            max = Math.max(max, parseInt(m[1], 10));
+    }
+    const n = max + 1;
+    return `br_${String(n).padStart(2, '0')}`;
+}
+/**
+ * Returns the input seeds reordered so that every seed appears AFTER all the
+ * seeds it depends on (its `relation` branch targets). Pure function — does
+ * not read from any global registry.
+ *
+ * Uses Kahn's algorithm (BFS on in-degree) for cycle detection and topological
+ * ordering. Sprint 3 (CLI / migration runner) consumes this to create tables in
+ * the correct order without disabling SQLite FK constraints.
+ *
+ * @throws {Error} When a relation targets an unknown slug not in `seeds`.
+ * @throws {Error} When a cyclic dependency is detected, listing involved slugs.
+ */
+export function sortSeedsByDependencies(seeds) {
+    const slugSet = new Set(seeds.map(s => s.slug));
+    // Validate all relation targets exist in the input array
+    for (const seed of seeds) {
+        for (const branch of seed.branches) {
+            if (branch.type === 'relation' && branch.targetSeed) {
+                if (!slugSet.has(branch.targetSeed)) {
+                    throw new Error(`Seed '${seed.slug}' relates to unknown target '${branch.targetSeed}'`);
+                }
+            }
+        }
+    }
+    // Build adjacency: inDegree[slug] = number of dependencies
+    //                  dependents[slug] = slugs that depend on slug
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const seed of seeds) {
+        if (!inDegree.has(seed.slug))
+            inDegree.set(seed.slug, 0);
+        if (!dependents.has(seed.slug))
+            dependents.set(seed.slug, []);
+    }
+    for (const seed of seeds) {
+        // Deduplicate targets to avoid inflating inDegree on multi-branch refs to same seed
+        const targets = new Set(seed.branches
+            .filter(b => b.type === 'relation' && b.targetSeed)
+            .map(b => b.targetSeed));
+        for (const target of targets) {
+            // seed depends on target → increment seed's in-degree
+            inDegree.set(seed.slug, (inDegree.get(seed.slug) ?? 0) + 1);
+            dependents.get(target).push(seed.slug);
+        }
+    }
+    // Kahn's BFS: start with seeds that have no dependencies
+    const seedBySlug = new Map(seeds.map(s => [s.slug, s]));
+    const queue = [];
+    for (const [slug, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(slug);
+    }
+    const result = [];
+    while (queue.length > 0) {
+        const slug = queue.shift();
+        result.push(seedBySlug.get(slug));
+        for (const dependent of dependents.get(slug) ?? []) {
+            const newDeg = (inDegree.get(dependent) ?? 0) - 1;
+            inDegree.set(dependent, newDeg);
+            if (newDeg === 0)
+                queue.push(dependent);
+        }
+    }
+    if (result.length !== seeds.length) {
+        // Cycle exists — collect participating slugs (those with in-degree > 0 after BFS)
+        const cycle = [...inDegree.entries()]
+            .filter(([, deg]) => deg > 0)
+            .map(([slug]) => slug)
+            .sort();
+        throw new Error(`Cyclic dependency detected among seeds: ${cycle.join(', ')}`);
+    }
+    return result;
+}

package/dist/seed-validation.d.ts

@@ -0,0 +1,23 @@
+import type { Seed } from './types.js';
+/**
+ * Allowed charset for a branch alias. An alias becomes a raw SQL column name in
+ * CREATE TABLE / ADD COLUMN / CREATE INDEX and in SELECT/WHERE/ORDER BY clauses
+ * (see engine.ts), so it MUST be restricted to a safe identifier charset to
+ * prevent DDL/query injection. Exported so the seeds API rename route reuses the
+ * exact same guard — do not inline a divergent copy.
+ */
+export declare const BRANCH_ALIAS_RE: RegExp;
+export interface SeedValidationIssue {
+    slug: string;
+    messages: string[];
+    fatal: boolean;
+}
+/**
+ * Pure, console-free, throw-free validation of a seed set.
+ * The single seed being created/edited should be validated in the context of
+ * the full active set: call validateSeedDefinitions([...otherActiveSeeds, edited]).
+ */
+export declare function validateSeedDefinitions(seeds: Seed[]): SeedValidationIssue[];
+/** Convenience: true iff no fatal issues. */
+export declare function isSeedSetValid(seeds: Seed[]): boolean;
+//# sourceMappingURL=seed-validation.d.ts.map

package/dist/seed-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../src/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAErD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,mBAAmB,EAAE,CA0N5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}