@beechcms/core 0.8.0 → 0.8.1

package/dist/schema/define.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module schema/define
+ * Authoring DSL for `beech.schema.ts`. Pure, allocation-only helpers: they give the author
+ * inference and autocomplete, and they never validate, throw, or touch I/O.
+ */
+import { MANIFEST_VERSION } from './manifest.types.js';
+function isFieldGroup(input) {
+    return Array.isArray(input.branches);
+}
+/**
+ * Declares the root manifest. Seeds are stored in authoring order here; canonical ordering is
+ * applied by `toCanonicalJson`, so a reordered manifest file produces byte-identical canonical JSON.
+ */
+export function defineSchema(input) {
+    return { version: MANIFEST_VERSION, seeds: input.seeds };
+}
+/**
+ * Declares one content type, flattening any `defineGroup()` bundles into the branch list.
+ * Branch ORDER is preserved: it is the physical column order `planCreateSeed` will emit.
+ */
+export function defineSeed(input) {
+    const branches = [];
+    for (const item of input.branches) {
+        if (isFieldGroup(item))
+            branches.push(...item.branches);
+        else
+            branches.push(item);
+    }
+    return { ...input, branches };
+}
+/** Declares a reusable field bundle. Expanded at author time by `defineSeed`; never persisted. */
+export function defineGroup(name, branches) {
+    return { name, branches };
+}
+function field(type) {
+    return (input) => ({ ...input, type });
+}
+/**
+ * Typed field constructors. `relation` and `repeater` narrow their input because the engine treats
+ * `targetSeed` / `fields` as required for those types — making the compiler enforce what
+ * `validateSeedDefinitions` would otherwise only catch at apply time.
+ */
+export const defineField = {
+    text: field('text'),
+    number: field('number'),
+    boolean: field('boolean'),
+    json: field('json'),
+    date: field('date'),
+    richtext: field('richtext'),
+    file: field('file'),
+    tags: field('tags'),
+    relation: (input) => ({ ...input, type: 'relation' }),
+    repeater: (input) => ({ ...input, type: 'repeater' }),
+};

package/dist/schema/emit.d.ts

@@ -0,0 +1,14 @@
+import type { BeechSchemaManifest } from './manifest.types.js';
+/**
+ * Emits the full module source for a `beech.schema.ts`.
+ *
+ * Seeds are sorted by slug so two exports of the same database are byte-identical and a Git diff
+ * shows schema change only. `version` is NOT passed to `defineSchema` — the DSL adds it, and an
+ * excess property would fail the consumer's own typecheck.
+ *
+ * @throws CanonicalSerializationError when a seed carries a value that cannot survive a JSON
+ * round-trip. That can only happen if a non-serializable value reached the `seeds` table, which is
+ * a corrupt-state fault worth surfacing, not worth silently dropping.
+ */
+export declare function emitManifestModule(manifest: BeechSchemaManifest): string;
+//# sourceMappingURL=emit.d.ts.map

package/dist/schema/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/schema/emit.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAU9D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CASxE"}

package/dist/schema/emit.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module schema/emit
+ * Renders a manifest as the source of a `beech.schema.ts` module — the inverse of the authoring DSL.
+ *
+ * The seed payload is embedded as the FROZEN canonical JSON literal (sprint 1's serializer), not as
+ * a tree of `defineField.*` calls. Three reasons a future reader must not "improve" this:
+ *  1. a call-tree emitter is a second serializer for the manifest shape, free to drift from
+ *     `define.ts` the moment a branch type is added;
+ *  2. the bytes here must match what `toCanonicalJson` produces, because that is what the validator
+ *     and the diff compare — one format, one producer;
+ *  3. a JSON object literal IS a valid TypeScript expression, so the emitted file typechecks in the
+ *     consumer's project with zero extra machinery.
+ *
+ * A hand-authored manifest using the full DSL round-trips through this emitter unchanged in meaning:
+ * `defineSchema`/`defineSeed`/`defineField` all erase to the same `BeechSchemaManifest`.
+ */
+import { canonicalStringify } from '../common/canonical-json.js';
+/** Header written at the top of every exported manifest. */
+const HEADER = `// Generated by \`beech schema export\` from live D1 state.\n` +
+    `//\n` +
+    `// This file is DESIRED STATE, not runtime authority: the Worker never imports it and no deploy\n` +
+    `// applies it. Edit it, review the diff in Git, then reconcile with \`beech schema plan\` /\n` +
+    `// \`beech schema apply\`. Re-export at any time to refresh the snapshot.\n`;
+/**
+ * Emits the full module source for a `beech.schema.ts`.
+ *
+ * Seeds are sorted by slug so two exports of the same database are byte-identical and a Git diff
+ * shows schema change only. `version` is NOT passed to `defineSchema` — the DSL adds it, and an
+ * excess property would fail the consumer's own typecheck.
+ *
+ * @throws CanonicalSerializationError when a seed carries a value that cannot survive a JSON
+ * round-trip. That can only happen if a non-serializable value reached the `seeds` table, which is
+ * a corrupt-state fault worth surfacing, not worth silently dropping.
+ */
+export function emitManifestModule(manifest) {
+    const seeds = [...manifest.seeds].sort((a, b) => a.slug.localeCompare(b.slug));
+    const literal = canonicalStringify({ seeds }).trimEnd();
+    return (`${HEADER}\n` +
+        `import { defineSchema } from '@beechcms/core/schema'\n\n` +
+        `export default defineSchema(${literal})\n`);
+}

package/dist/schema/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module schema
+ * Authoring surface for `beech.schema.ts`. Imported by authoring tools and the CLI — NEVER by the
+ * Worker, which is why this module is a separate subpath and is absent from `src/index.ts`.
+ */
+export * from './manifest.types.js';
+export * from './define.js';
+export * from './canonical.js';
+export * from './manifest-seeds.js';
+export * from './manifest-validation.js';
+export * from './emit.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qBAAqB,CAAA;AACnC,cAAc,0BAA0B,CAAA;AACxC,cAAc,WAAW,CAAA"}

package/dist/schema/index.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module schema
+ * Authoring surface for `beech.schema.ts`. Imported by authoring tools and the CLI — NEVER by the
+ * Worker, which is why this module is a separate subpath and is absent from `src/index.ts`.
+ */
+export * from './manifest.types.js';
+export * from './define.js';
+export * from './canonical.js';
+export * from './manifest-seeds.js';
+export * from './manifest-validation.js';
+export * from './emit.js';

package/dist/schema/manifest-seeds.d.ts

@@ -0,0 +1,12 @@
+import type { BeechSchemaManifest } from './manifest.types.js';
+import type { Seed } from '../engine/types.js';
+/** Manifest → engine `Seed[]`, ready for `validateSeedDefinitions` or an MCP plan candidate. */
+export declare function manifestToSeeds(manifest: BeechSchemaManifest): Seed[];
+/**
+ * Engine `Seed[]` → manifest, for a future `beech schema export`.
+ *
+ * `layout` is stripped: it is server-populated presentation state, not schema. Seeds are sorted by
+ * slug so an export is diffable; branch order is preserved because it is the physical column order.
+ */
+export declare function seedsToManifest(seeds: Seed[]): BeechSchemaManifest;
+//# sourceMappingURL=manifest-seeds.d.ts.map

package/dist/schema/manifest-seeds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-seeds.d.ts","sourceRoot":"","sources":["../../src/schema/manifest-seeds.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAgC,MAAM,qBAAqB,CAAA;AAC5F,OAAO,KAAK,EAAU,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAuBtD,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,EAAE,CAKrE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,mBAAmB,CAMlE"}

package/dist/schema/manifest-seeds.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module schema/manifest-seeds
+ * Bridges the manifest shape and the engine's `Seed` shape, in both directions.
+ */
+import { nextBranchId } from '../engine/seeds/seed-registry.js';
+import { MANIFEST_VERSION } from './manifest.types.js';
+/**
+ * Fills in ids for branches authored without one, in declaration order.
+ *
+ * These ids are AUTHORING-LOCAL and non-authoritative — they exist so `validateSeedDefinitions`,
+ * which fatals on a missing id, has a complete `Seed` to check. At plan/apply time the stored id
+ * wins: `normalizeCandidate()` in the API's MCP slice matches by alias against the stored
+ * definition before minting anything. Never persist an id minted here as if it were stable.
+ */
+function withBranchIds(branches) {
+    const accumulated = [];
+    for (const branch of branches) {
+        const resolved = {
+            ...branch,
+            id: branch.id ?? nextBranchId({ branches: accumulated }),
+            ...(branch.fields ? { fields: withBranchIds(branch.fields) } : {}),
+        };
+        accumulated.push(resolved);
+    }
+    return accumulated;
+}
+/** Manifest → engine `Seed[]`, ready for `validateSeedDefinitions` or an MCP plan candidate. */
+export function manifestToSeeds(manifest) {
+    return manifest.seeds.map((seed) => ({
+        ...seed,
+        branches: withBranchIds(seed.branches),
+    }));
+}
+/**
+ * Engine `Seed[]` → manifest, for a future `beech schema export`.
+ *
+ * `layout` is stripped: it is server-populated presentation state, not schema. Seeds are sorted by
+ * slug so an export is diffable; branch order is preserved because it is the physical column order.
+ */
+export function seedsToManifest(seeds) {
+    const sorted = [...seeds].sort((a, b) => a.slug.localeCompare(b.slug));
+    return {
+        version: MANIFEST_VERSION,
+        seeds: sorted.map(({ layout: _layout, ...seed }) => seed),
+    };
+}

package/dist/schema/manifest-validation.d.ts

@@ -0,0 +1,13 @@
+import type { SeedValidationIssue } from '../engine/seeds/seed-validation.js';
+import type { BeechSchemaManifest } from './manifest.types.js';
+/**
+ * Validates a manifest end to end:
+ *  1. format version is one this build understands;
+ *  2. every value survives canonical serialization (no callbacks or executable code persisted);
+ *  3. the derived `Seed[]` passes the engine's whole-set validation — including cross-seed relation
+ *     targets, which is exactly why this is a manifest-level and not a seed-level function.
+ *
+ * Returns issues; never throws. A caller decides whether a non-fatal issue blocks.
+ */
+export declare function validateManifest(manifest: BeechSchemaManifest): SeedValidationIssue[];
+//# sourceMappingURL=manifest-validation.d.ts.map

package/dist/schema/manifest-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-validation.d.ts","sourceRoot":"","sources":["../../src/schema/manifest-validation.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AAI7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,mBAAmB,EAAE,CAqBrF"}

package/dist/schema/manifest-validation.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module schema/manifest-validation
+ * Whole-manifest validation. Reuses the engine's `validateSeedDefinitions` rather than
+ * reimplementing it: a manifest that passes here is a candidate set the API would also accept.
+ */
+import { validateSeedDefinitions } from '../engine/seeds/seed-validation.js';
+import { MANIFEST_VERSION } from './manifest.types.js';
+import { toCanonicalJson, ManifestSerializationError } from './canonical.js';
+import { manifestToSeeds } from './manifest-seeds.js';
+/**
+ * Validates a manifest end to end:
+ *  1. format version is one this build understands;
+ *  2. every value survives canonical serialization (no callbacks or executable code persisted);
+ *  3. the derived `Seed[]` passes the engine's whole-set validation — including cross-seed relation
+ *     targets, which is exactly why this is a manifest-level and not a seed-level function.
+ *
+ * Returns issues; never throws. A caller decides whether a non-fatal issue blocks.
+ */
+export function validateManifest(manifest) {
+    if (manifest.version !== MANIFEST_VERSION) {
+        return [{
+                slug: '*',
+                fatal: true,
+                messages: [
+                    `unsupported manifest version ${String(manifest.version)}; this build understands ${MANIFEST_VERSION}.`,
+                ],
+            }];
+    }
+    try {
+        toCanonicalJson(manifest);
+    }
+    catch (error) {
+        if (error instanceof ManifestSerializationError) {
+            return [{ slug: '*', fatal: true, messages: [error.message] }];
+        }
+        throw error;
+    }
+    return validateSeedDefinitions(manifestToSeeds(manifest));
+}

package/dist/schema/manifest.types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module schema/manifest.types
+ * Data shapes for the `beech.schema.ts` desired-state manifest. Pure types — no runtime logic.
+ *
+ * A manifest is NOT a runtime authority: D1 remains the sole runtime source of truth. These types
+ * describe an artifact that is authored, reviewed in Git, and reconciled through an explicit
+ * plan/apply step.
+ */
+import type { Branch, Seed } from '../engine/types.js';
+/**
+ * Manifest format version. Bumped ONLY on a breaking change to the manifest shape — never on an
+ * additive field. `fromCanonicalJson` refuses any other value rather than guessing.
+ */
+export declare const MANIFEST_VERSION = 1;
+/**
+ * A field as written by hand in a manifest.
+ *
+ * `id` is optional at authoring time: nobody hand-writes `br_07`, and an author-invented id would
+ * collide with the ids the engine already minted. It is filled in by `manifestToSeeds()` purely so
+ * validation has a complete `Seed`; the AUTHORITATIVE assignment happens at plan/apply time, where
+ * `normalizeCandidate()` preserves the stored id by alias match before minting a new one.
+ * `fields` is recursive for `repeater` sub-fields, which carry the same rule.
+ */
+export type ManifestBranch = Omit<Branch, 'id' | 'fields'> & {
+    id?: string;
+    fields?: ManifestBranch[];
+};
+/**
+ * A content type as written in a manifest.
+ *
+ * `layout` is deliberately absent: it is typed `unknown`, is populated server-side by
+ * `GET /api/schema`, and is not a schema concern. Round-tripping it would make a future
+ * `beech schema diff` report permanent false drift.
+ */
+export type ManifestSeed = Omit<Seed, 'branches' | 'layout'> & {
+    branches: ManifestBranch[];
+};
+/**
+ * A reusable bundle of fields (e.g. an SEO block shared by several seeds).
+ *
+ * Author-time only: `defineSeed()` splices `branches` into the seed's own list and the group leaves
+ * ZERO trace in canonical JSON. It is a macro, not a persisted concept — there is exactly one
+ * grouping mechanism in D1, and this is not it.
+ */
+export interface FieldGroup {
+    name: string;
+    branches: ManifestBranch[];
+}
+/** The root artifact: the whole desired schema state. */
+export interface BeechSchemaManifest {
+    version: typeof MANIFEST_VERSION;
+    seeds: ManifestSeed[];
+}
+//# sourceMappingURL=manifest.types.d.ts.map

package/dist/schema/manifest.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.types.d.ts","sourceRoot":"","sources":["../../src/schema/manifest.types.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAC3D,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;CAC1B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC,GAAG;IAC7D,QAAQ,EAAE,cAAc,EAAE,CAAA;CAC3B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,cAAc,EAAE,CAAA;CAC3B;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,gBAAgB,CAAA;IAChC,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB"}

package/dist/schema/manifest.types.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Manifest format version. Bumped ONLY on a breaking change to the manifest shape — never on an
+ * additive field. `fromCanonicalJson` refuses any other value rather than guessing.
+ */
+export const MANIFEST_VERSION = 1;

package/dist/schema-mutator.d.ts

@@ -0,0 +1,26 @@
+/** Executes additive schema DDL against the live database and introspects columns.
+ *  Implemented by D1SchemaMutator in apps/api/src/shared/schema-mutator.d1.ts.
+ *  This is the ONLY sanctioned channel for runtime DDL — handlers never touch env.DB. */
+export interface ISchemaMutator {
+    /** Column names currently on a table, or null if the table does not exist. */
+    getColumns(table: string): Promise<Set<string> | null>;
+    /** Runs the given DDL statements in order as a single D1 batch.
+     *  All statements must be additive (CREATE … IF NOT EXISTS / ALTER … ADD COLUMN /
+     *  CREATE INDEX IF NOT EXISTS). Throws on the first failing statement. */
+    execDdl(statements: string[]): Promise<void>;
+    /** `DROP TABLE IF EXISTS {table}`. */
+    dropTable(table: string): Promise<void>;
+    /** `ALTER TABLE {table} DROP COLUMN {column}`. */
+    dropColumn(table: string, column: string): Promise<void>;
+    /** `ALTER TABLE {table} RENAME COLUMN {from} TO {to}`. */
+    renameColumn(table: string, from: string, to: string): Promise<void>;
+    /** Runs a multi-statement destructive batch atomically (FTS rebuild,
+     *  type-change column rebuild, full type drop). The caller assembles the
+     *  statements; the impl validates identifiers and runs them as one D1 batch. */
+    execDestructive(statements: string[]): Promise<void>;
+    /** Reads all rows from a table for the specified columns only.
+     *  Used before DROP TABLE to collect R2 keys for media cleanup.
+     *  All identifiers are validated against `^[A-Za-z0-9_]+$`. */
+    fetchRows(table: string, columns: string[]): Promise<Record<string, unknown>[]>;
+}
+//# sourceMappingURL=schema-mutator.d.ts.map

package/dist/schema-mutator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-mutator.d.ts","sourceRoot":"","sources":["../src/schema-mutator.ts"],"names":[],"mappings":"AAGA;;yFAEyF;AACzF,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAA;IACtD;;8EAE0E;IAC1E,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAS5C,sCAAsC;IACtC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvC,kDAAkD;IAClD,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,0DAA0D;IAC1D,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpE;;oFAEgF;IAChF,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpD;;mEAE+D;IAC/D,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAA;CAChF"}

package/dist/schema-mutator.js

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

package/dist/seed-ddl-destructive.d.ts

@@ -0,0 +1,40 @@
+import type { Seed, BranchType } from './types.js';
+/**
+ * Ordered DROP TABLE statements for a full hard-delete of a seed's tables.
+ * Order: junction drafts → junctions → FTS triggers → FTS table → drafts → main table.
+ * All statements use IF EXISTS (idempotent).
+ */
+export declare function generateDropTable(seed: Seed): string[];
+/**
+ * DROP COLUMN statements for a single branch (by alias).
+ * For multi-relation branches: drops the junction tables (no column on parent).
+ * For regular branches: drops from main table + drafts table (if allowDrafts).
+ * Does NOT include FTS handling — callers must prepend ftsTriggerDrops() and
+ * append planFtsRebuild() when the branch is searchable.
+ */
+export declare function generateDropColumn(seed: Seed, alias: string): string[];
+/**
+ * RENAME COLUMN statements for a branch alias change.
+ * Updates main table + drafts (if allowDrafts).
+ * Does NOT handle FTS — callers must rebuild FTS separately (SQLite auto-updates
+ * trigger bodies on RENAME but the FTS virtual-table columns keep the old name).
+ */
+export declare function generateRenameColumn(seed: Seed, fromAlias: string, toAlias: string): string[];
+/**
+ * Full FTS rebuild: drop triggers + FTS table, then recreate them, then backfill.
+ * Returns an empty array if the seed has no searchable branches.
+ * The drop steps use IF EXISTS so this is safe to call even if FTS was already dropped.
+ */
+export declare function planFtsRebuild(seed: Seed): string[];
+export interface RetypeColumnPlan {
+    statements: string[];
+    ftsRebuildNeeded: boolean;
+}
+/**
+ * Generates statements to change a branch's SQL storage type using the
+ * add-new-column / copy / drop-old / rename approach.
+ * Includes FTS rebuild statements when the branch is (or becomes) searchable.
+ * `updatedSeed` must already reflect the new type on the renamed branch.
+ */
+export declare function planRetypeColumn(seed: Seed, alias: string, newType: BranchType, updatedSeed: Seed): RetypeColumnPlan;
+//# sourceMappingURL=seed-ddl-destructive.d.ts.map

package/dist/seed-ddl-destructive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-ddl-destructive.d.ts","sourceRoot":"","sources":["../src/seed-ddl-destructive.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAU,UAAU,EAAE,MAAM,YAAY,CAAA;AAkC1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAgBtD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBtE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ7F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAiBnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,IAAI,GAChB,gBAAgB,CAyClB"}

package/dist/seed-ddl-destructive.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { junctionTableName, generateFtsTable, generateFtsTriggers } from './engine.js';
+const BRANCH_SQL_TYPE = {
+    text: 'TEXT',
+    number: 'REAL',
+    boolean: 'INTEGER',
+    date: 'INTEGER',
+    json: 'TEXT',
+    richtext: 'TEXT',
+    file: 'TEXT',
+    tags: 'TEXT',
+    relation: 'TEXT',
+    repeater: 'TEXT',
+};
+/** Branch types that receive a B-tree index in generateIndexes (used by retype to drop/recreate). */
+const INDEXABLE_TYPES = new Set(['text', 'number', 'date', 'boolean', 'relation']);
+function searchBranches(seed) {
+    return seed.branches.filter(b => (b.type === 'text' || b.type === 'richtext') && b.policies?.search !== false);
+}
+function ftsTriggerDrops(slug) {
+    return [
+        `DROP TRIGGER IF EXISTS fts_${slug}_insert;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_update;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_delete;`,
+        `DROP TABLE IF EXISTS fts_${slug};`,
+    ];
+}
+/**
+ * Ordered DROP TABLE statements for a full hard-delete of a seed's tables.
+ * Order: junction drafts → junctions → FTS triggers → FTS table → drafts → main table.
+ * All statements use IF EXISTS (idempotent).
+ */
+export function generateDropTable(seed) {
+    const stmts = [];
+    const { slug } = seed;
+    for (const branch of seed.branches) {
+        if (branch.type !== 'relation' || branch.multiple !== true)
+            continue;
+        const jt = junctionTableName(slug, branch.alias);
+        stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    stmts.push(...ftsTriggerDrops(slug));
+    stmts.push(`DROP TABLE IF EXISTS content_${slug}_drafts;`);
+    stmts.push(`DROP TABLE IF EXISTS content_${slug};`);
+    return stmts;
+}
+/**
+ * DROP COLUMN statements for a single branch (by alias).
+ * For multi-relation branches: drops the junction tables (no column on parent).
+ * For regular branches: drops from main table + drafts table (if allowDrafts).
+ * Does NOT include FTS handling — callers must prepend ftsTriggerDrops() and
+ * append planFtsRebuild() when the branch is searchable.
+ */
+export function generateDropColumn(seed, alias) {
+    const stmts = [];
+    const { slug } = seed;
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${slug}'`);
+    if (branch.type === 'relation' && branch.multiple === true) {
+        const jt = junctionTableName(slug, alias);
+        if (seed.allowDrafts)
+            stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    else {
+        stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+        if (seed.allowDrafts)
+            stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+    }
+    return stmts;
+}
+/**
+ * RENAME COLUMN statements for a branch alias change.
+ * Updates main table + drafts (if allowDrafts).
+ * Does NOT handle FTS — callers must rebuild FTS separately (SQLite auto-updates
+ * trigger bodies on RENAME but the FTS virtual-table columns keep the old name).
+ */
+export function generateRenameColumn(seed, fromAlias, toAlias) {
+    const stmts = [];
+    const { slug } = seed;
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    }
+    return stmts;
+}
+/**
+ * Full FTS rebuild: drop triggers + FTS table, then recreate them, then backfill.
+ * Returns an empty array if the seed has no searchable branches.
+ * The drop steps use IF EXISTS so this is safe to call even if FTS was already dropped.
+ */
+export function planFtsRebuild(seed) {
+    const rtBranches = searchBranches(seed);
+    if (rtBranches.length === 0)
+        return [];
+    const { slug } = seed;
+    const stmts = [...ftsTriggerDrops(slug)];
+    const ftsTable = generateFtsTable(seed);
+    if (ftsTable)
+        stmts.push(ftsTable);
+    stmts.push(...generateFtsTriggers(seed));
+    const cols = rtBranches.map(b => b.alias);
+    stmts.push(`INSERT INTO fts_${slug}(entry_id, ${cols.join(', ')}) SELECT id, ${cols.join(', ')} FROM content_${slug};`);
+    return stmts;
+}
+/**
+ * Generates statements to change a branch's SQL storage type using the
+ * add-new-column / copy / drop-old / rename approach.
+ * Includes FTS rebuild statements when the branch is (or becomes) searchable.
+ * `updatedSeed` must already reflect the new type on the renamed branch.
+ */
+export function planRetypeColumn(seed, alias, newType, updatedSeed) {
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${seed.slug}'`);
+    const { slug } = seed;
+    const newSqlType = BRANCH_SQL_TYPE[newType];
+    const tmpAlias = `${alias}_migrate`;
+    const stmts = [];
+    // Always drop FTS first to avoid "column referenced in trigger" errors on DROP COLUMN.
+    stmts.push(...ftsTriggerDrops(slug));
+    // Drop the branch index if it exists on the old column (required before DROP COLUMN).
+    if (INDEXABLE_TYPES.has(branch.type) && branch.policies?.filter !== false) {
+        stmts.push(`DROP INDEX IF EXISTS idx_${slug}_${alias};`);
+    }
+    // Main table: add migration column, copy data, drop old, rename.
+    stmts.push(`ALTER TABLE content_${slug} ADD COLUMN ${tmpAlias} ${newSqlType};`);
+    stmts.push(`UPDATE content_${slug} SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+    stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    // Recreate index for the renamed column if the new type warrants it.
+    if (INDEXABLE_TYPES.has(newType) && branch.policies?.filter !== false) {
+        stmts.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_${alias} ON content_${slug}(${alias});`);
+    }
+    // Drafts table (no indexes to worry about).
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts ADD COLUMN ${tmpAlias} ${newSqlType};`);
+        stmts.push(`UPDATE content_${slug}_drafts SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    }
+    // Rebuild FTS if the seed has searchable branches in the updated definition.
+    const rebuild = planFtsRebuild(updatedSeed);
+    stmts.push(...rebuild);
+    return { statements: stmts, ftsRebuildNeeded: rebuild.length > 0 };
+}

package/dist/seed-ddl.d.ts

@@ -0,0 +1,40 @@
+import type { Seed } from './types.js';
+/**
+ * Full create-from-scratch statement set for a seed. Mirrors the CLI's buildStatements.
+ * Order: parent table → indexes → draft table → FTS table → FTS triggers →
+ * per multi-relation: junction table → junction indexes → junction draft table.
+ * Callers that create several seeds must order seeds with sortSeedsByDependencies
+ * first so relation FK targets exist.
+ */
+export declare function planCreateSeed(seed: Seed): string[];
+export interface ExtendPlan {
+    statements: string[];
+    ftsRebuildNeeded: boolean;
+}
+/**
+ * Additive extension: given the columns that already exist on content_{slug}
+ * (from PRAGMA table_info, passed in by the caller), return ONLY the statements
+ * needed to add new branches — ADD COLUMN + indexes, plus junction tables for
+ * new multi-relation branches. Never drops or renames.
+ *
+ * FTS: SQLite cannot ALTER an fts5 table's columns. If a new text/richtext
+ * searchable branch was added, ftsRebuildNeeded=true signals the caller
+ * (sprint 03) to handle it — no DROP is emitted.
+ */
+export declare function planExtendSeed(seed: Seed, existingColumns: Set<string>): ExtendPlan;
+/**
+ * Destructive FTS rebuild (sprint 06). SQLite cannot ALTER an fts5 table's
+ * columns, so when a searchable branch is added, renamed, retyped, or dropped
+ * the only correct fix is to drop and recreate the `fts_{slug}` virtual table
+ * (and its insert/update/delete triggers), then backfill from `content_{slug}`.
+ *
+ * Returns an empty array when the seed has no searchable branches — in that
+ * case the caller should instead drop any leftover FTS table via
+ * generateDropTable's FTS statements. The returned statements are destructive
+ * and must run through ISchemaMutator.execDestructive, never execDdl.
+ *
+ * Order: drop triggers → drop fts table → recreate table → recreate triggers →
+ * backfill existing rows.
+ */
+export declare function planFtsRebuild(seed: Seed): string[];
+//# sourceMappingURL=seed-ddl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed-ddl.d.ts","sourceRoot":"","sources":["../src/seed-ddl.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AActC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAanD;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,UAAU,CAqBnF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CA0BnD"}