@createcms/core 0.1.1

package/dist/bin/createcms.js

@@ -0,0 +1,3082 @@
+#!/usr/bin/env node
+import { cac } from 'cac';
+import kleur from 'kleur';
+import path from 'node:path';
+import { mkdir, writeFile, access, readFile } from 'node:fs/promises';
+import { createJiti } from 'jiti';
+import { readFileSync, mkdirSync, writeFileSync, readdirSync } from 'node:fs';
+import Module from 'node:module';
+import { tmpdir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import ora from 'ora';
+import prompts from 'prompts';
+
+function toSnakeCase(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/[-\s]+/g, '_').toLowerCase();
+}
+function cloneColumns(columns) {
+    return Object.fromEntries(Object.entries(columns).map(([key, value])=>[
+            key,
+            {
+                ...value
+            }
+        ]));
+}
+function cloneIndexes(indexes) {
+    return Object.fromEntries(Object.entries(indexes).map(([key, value])=>[
+            key,
+            {
+                ...value,
+                columns: [
+                    ...value.columns
+                ]
+            }
+        ]));
+}
+function cloneEnum(enumDef) {
+    return {
+        ...enumDef,
+        key: '',
+        dbName: '',
+        values: [
+            ...enumDef.values
+        ]
+    };
+}
+function mergeSchemaSources(sources) {
+    const enums = {};
+    const tables = {};
+    for (const source of sources){
+        const sourceEnums = source.schema.enums ?? {};
+        for (const [enumKey, enumDef] of Object.entries(sourceEnums)){
+            if (enums[enumKey]) {
+                throw new Error(`Duplicate enum "${enumKey}" declared by "${source.name}".`);
+            }
+            const resolved = cloneEnum(enumDef);
+            resolved.key = enumKey;
+            resolved.dbName = enumDef.enumName ?? toSnakeCase(enumKey);
+            enums[enumKey] = resolved;
+        }
+        const sourceTables = source.schema.tables ?? {};
+        for (const [tableKey, tableDef] of Object.entries(sourceTables)){
+            if (tables[tableKey]) {
+                throw new Error(`Duplicate table "${tableKey}" declared by "${source.name}".`);
+            }
+            const resolved = {
+                key: tableKey,
+                dbName: tableDef.tableName ?? toSnakeCase(tableKey),
+                indexPrefix: tableDef.indexPrefix,
+                columns: cloneColumns(tableDef.columns),
+                indexes: cloneIndexes(Object.fromEntries(Object.entries(tableDef.indexes ?? {}).map(([indexKey, indexDef])=>[
+                        indexKey,
+                        {
+                            ...indexDef,
+                            columns: [
+                                ...indexDef.columns
+                            ]
+                        }
+                    ]))),
+                compositePrimaryKey: tableDef.compositePrimaryKey ? {
+                    columns: [
+                        ...tableDef.compositePrimaryKey.columns
+                    ]
+                } : undefined,
+                foreignKeys: tableDef.foreignKeys ? tableDef.foreignKeys.map((fk)=>({
+                        ...fk,
+                        columns: [
+                            ...fk.columns
+                        ],
+                        foreignColumns: [
+                            ...fk.foreignColumns
+                        ]
+                    })) : undefined
+            };
+            tables[tableKey] = resolved;
+        }
+    }
+    // Phase 2: Apply extensions
+    for (const source of sources){
+        const sourceExtensions = source.schema.extend ?? {};
+        for (const [targetTableKey, extension] of Object.entries(sourceExtensions)){
+            const targetTable = tables[targetTableKey];
+            if (!targetTable) {
+                throw new Error(`Schema source "${source.name}" extends unknown table "${targetTableKey}".`);
+            }
+            for (const [columnKey, columnDef] of Object.entries(extension.columns)){
+                if (targetTable.columns[columnKey]) {
+                    throw new Error(`Schema source "${source.name}" tried to add duplicate column "${columnKey}" to "${targetTableKey}".`);
+                }
+                targetTable.columns[columnKey] = {
+                    ...columnDef
+                };
+            }
+            for (const [indexKey, indexDef] of Object.entries(extension.indexes ?? {})){
+                if (targetTable.indexes[indexKey]) {
+                    throw new Error(`Schema source "${source.name}" tried to add duplicate index "${indexKey}" to "${targetTableKey}".`);
+                }
+                targetTable.indexes[indexKey] = {
+                    ...indexDef,
+                    columns: [
+                        ...indexDef.columns
+                    ]
+                };
+            }
+        }
+    }
+    // Phase 3: Validation
+    const enumDbNames = new Set();
+    for (const enumDef of Object.values(enums)){
+        if (enumDbNames.has(enumDef.dbName)) {
+            throw new Error(`Duplicate enum database name "${enumDef.dbName}".`);
+        }
+        enumDbNames.add(enumDef.dbName);
+    }
+    const tableDbNames = new Set();
+    for (const table of Object.values(tables)){
+        if (tableDbNames.has(table.dbName)) {
+            throw new Error(`Duplicate table database name "${table.dbName}".`);
+        }
+        tableDbNames.add(table.dbName);
+        for (const [columnKey, columnDef] of Object.entries(table.columns)){
+            if (typeof columnDef.type === 'object') {
+                const enumName = columnDef.type.enum;
+                if (!enums[enumName]) {
+                    throw new Error(`Column "${table.key}.${columnKey}" references unknown enum "${enumName}".`);
+                }
+            }
+            if (columnDef.references) {
+                const referencedTable = tables[columnDef.references.table];
+                if (!referencedTable) {
+                    throw new Error(`Column "${table.key}.${columnKey}" references unknown table "${columnDef.references.table}".`);
+                }
+                if (!referencedTable.columns[columnDef.references.column]) {
+                    throw new Error(`Column "${table.key}.${columnKey}" references unknown column "${columnDef.references.table}.${columnDef.references.column}".`);
+                }
+            }
+        }
+        for (const [indexKey, indexDef] of Object.entries(table.indexes)){
+            for (const columnName of indexDef.columns){
+                if (!table.columns[columnName]) {
+                    throw new Error(`Index "${table.key}.${indexKey}" references unknown column "${columnName}".`);
+                }
+            }
+        }
+        if (table.foreignKeys) {
+            for (const fk of table.foreignKeys){
+                for (const col of fk.columns){
+                    if (!table.columns[col]) {
+                        throw new Error(`Foreign key in "${table.key}" references unknown local column "${col}".`);
+                    }
+                }
+                const refTable = tables[fk.foreignTable];
+                if (!refTable) {
+                    throw new Error(`Foreign key in "${table.key}" references unknown table "${fk.foreignTable}".`);
+                }
+                for (const col of fk.foreignColumns){
+                    if (!refTable.columns[col]) {
+                        throw new Error(`Foreign key in "${table.key}" references unknown column "${fk.foreignTable}.${col}".`);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        enums,
+        tables
+    };
+}
+
+function quote(value) {
+    return JSON.stringify(value);
+}
+function toPascalCase(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_\-\s]+/g, ' ').split(' ').filter(Boolean).map((part)=>part.charAt(0).toUpperCase() + part.slice(1)).join('');
+}
+function singularize(value) {
+    if (value.endsWith('ies')) {
+        return `${value.slice(0, -3)}y`;
+    }
+    if (value.endsWith('ches') || value.endsWith('shes') || value.endsWith('xes') || value.endsWith('zes')) {
+        return value.slice(0, -2);
+    }
+    if (value.endsWith('s') && !value.endsWith('ss')) {
+        return value.slice(0, -1);
+    }
+    return value;
+}
+function emitLiteral(value) {
+    return JSON.stringify(value.value);
+}
+function emitDefault(defaultValue) {
+    switch(defaultValue.kind){
+        case 'literal':
+            return {
+                code: `.default(${emitLiteral(defaultValue)})`,
+                needsSql: false
+            };
+        case 'sql':
+            return {
+                code: `.default(sql.raw(${quote(defaultValue.value)}))`,
+                needsSql: true
+            };
+    }
+}
+function emitEnum(enumDef) {
+    const values = `[${enumDef.values.map(quote).join(', ')}]`;
+    return `export const ${enumDef.key}Enum = cms.enum(${quote(enumDef.dbName)}, ${values});`;
+}
+function emitColumn(table, columnKey, columnDef) {
+    const columnName = columnDef.columnName ?? toSnakeCase(columnKey);
+    let builder = '';
+    let needsTsvector = false;
+    if (typeof columnDef.type === 'string') {
+        if (columnDef.type === 'tsvector') {
+            builder = `tsvectorColumn(${quote(columnName)})`;
+            needsTsvector = true;
+        } else {
+            builder = `${columnDef.type}(${quote(columnName)})`;
+        }
+    } else {
+        builder = `${columnDef.type.enum}Enum(${quote(columnName)})`;
+    }
+    let needsSql = false;
+    let needsAnyPgColumn = false;
+    if (columnDef.jsonType && typeof columnDef.type === 'string' && columnDef.type === 'jsonb') {
+        builder += `.$type<${columnDef.jsonType}>()`;
+    }
+    if (columnDef.primaryKey) {
+        builder += '.primaryKey()';
+    }
+    if (columnDef.notNull) {
+        builder += '.notNull()';
+    }
+    if (columnDef.unique) {
+        builder += '.unique()';
+    }
+    if (columnDef.defaultNow) {
+        builder += '.defaultNow()';
+    }
+    if (columnDef.defaultId) {
+        if (!columnDef.defaultIdPrefix) {
+            throw new Error(`Column "${columnKey}" has defaultId but no defaultIdPrefix`);
+        }
+        builder += `.$defaultFn(() => newId(${quote(columnDef.defaultIdPrefix)}))`;
+    }
+    if (columnDef.default) {
+        const emitted = emitDefault(columnDef.default);
+        builder += emitted.code;
+        needsSql ||= emitted.needsSql;
+    }
+    if (columnDef.references) {
+        const options = [];
+        if (columnDef.references.onDelete) {
+            options.push(`onDelete: ${quote(columnDef.references.onDelete)}`);
+        }
+        if (columnDef.references.onUpdate) {
+            options.push(`onUpdate: ${quote(columnDef.references.onUpdate)}`);
+        }
+        const suffix = options.length > 0 ? `, { ${options.join(', ')} }` : '';
+        const isSelfReference = columnDef.references.table === table.key;
+        const refCallback = isSelfReference ? `(): AnyPgColumn => ${columnDef.references.table}.${columnDef.references.column}` : `() => ${columnDef.references.table}.${columnDef.references.column}`;
+        needsAnyPgColumn ||= isSelfReference;
+        builder += `.references(${refCallback}${suffix})`;
+    }
+    return {
+        code: `    ${columnKey}: ${builder},`,
+        needsSql,
+        needsAnyPgColumn,
+        needsTsvector
+    };
+}
+function emitIndexes(table) {
+    const entries = Object.entries(table.indexes);
+    if (entries.length === 0) {
+        return [];
+    }
+    const prefix = table.indexPrefix ?? table.dbName;
+    return entries.map(([indexKey, indexDef])=>{
+        const factory = indexDef.unique ? 'uniqueIndex' : 'index';
+        const columns = indexDef.columns.map((column)=>`table.${column}`).join(', ');
+        let line;
+        if (indexDef.using && indexDef.using !== 'btree') {
+            line = `    ${factory}(${quote(`${prefix}_${toSnakeCase(indexKey)}`)}).using(${quote(indexDef.using)}, ${columns})`;
+        } else {
+            line = `    ${factory}(${quote(`${prefix}_${toSnakeCase(indexKey)}`)}).on(${columns})`;
+        }
+        if (indexDef.where) {
+            line += `.where(sql\`${indexDef.where}\`)`;
+        }
+        return `${line},`;
+    });
+}
+function emitCompositePrimaryKey(table) {
+    if (!table.compositePrimaryKey) return null;
+    const columns = table.compositePrimaryKey.columns.map((col)=>`table.${col}`).join(', ');
+    return `    primaryKey({ columns: [${columns}] }),`;
+}
+function emitTableLevelForeignKeys(table) {
+    if (!table.foreignKeys || table.foreignKeys.length === 0) {
+        return {
+            lines: [],
+            needsForeignKeyImport: false
+        };
+    }
+    const lines = table.foreignKeys.map((fk)=>{
+        const localCols = fk.columns.map((c)=>`table.${c}`).join(', ');
+        const isSelfReference = fk.foreignTable === table.key;
+        const foreignCols = fk.foreignColumns.map((c)=>`${isSelfReference ? 'table' : fk.foreignTable}.${c}`).join(', ');
+        const parts = [
+            `      columns: [${localCols}],`,
+            `      foreignColumns: [${foreignCols}],`
+        ];
+        if (fk.name) {
+            parts.push(`      name: ${quote(fk.name)},`);
+        }
+        let chain = '';
+        if (fk.onDelete) {
+            chain += `.onDelete(${quote(fk.onDelete)})`;
+        }
+        if (fk.onUpdate) {
+            chain += `.onUpdate(${quote(fk.onUpdate)})`;
+        }
+        return `    foreignKey({\n${parts.join('\n')}\n    })${chain},`;
+    });
+    return {
+        lines,
+        needsForeignKeyImport: true
+    };
+}
+function emitTableTypeAliases(table) {
+    const baseName = toPascalCase(singularize(table.key));
+    return `export type ${baseName} = typeof ${table.key}.$inferSelect;
+export type New${baseName} = typeof ${table.key}.$inferInsert;`;
+}
+function emitTable(table) {
+    let needsSql = false;
+    let needsAnyPgColumn = false;
+    let needsForeignKeyImport = false;
+    let needsPrimaryKeyImport = false;
+    let needsTsvector = false;
+    const emittedColumns = Object.entries(table.columns).map(([columnKey, columnDef])=>{
+        const emitted = emitColumn(table, columnKey, columnDef);
+        needsSql ||= emitted.needsSql;
+        needsAnyPgColumn ||= emitted.needsAnyPgColumn;
+        needsTsvector ||= emitted.needsTsvector;
+        return emitted.code;
+    });
+    const indexes = emitIndexes(table);
+    for (const idx of Object.values(table.indexes)){
+        if (idx.where) needsSql = true;
+    }
+    const compositePK = emitCompositePrimaryKey(table);
+    if (compositePK) needsPrimaryKeyImport = true;
+    const { lines: fkLines, needsForeignKeyImport: needsFK } = emitTableLevelForeignKeys(table);
+    needsForeignKeyImport = needsFK;
+    const tableFactory = 'cms.table';
+    const callbackLines = [
+        ...compositePK ? [
+            compositePK
+        ] : [],
+        ...fkLines,
+        ...indexes
+    ];
+    const callback = callbackLines.length > 0 ? `,
+  (table) => [
+${callbackLines.join('\n')}
+  ]` : '';
+    return {
+        code: `export const ${table.key} = ${tableFactory}(
+  ${quote(table.dbName)},
+  {
+${emittedColumns.join('\n')}
+  }${callback},
+);`,
+        needsSql,
+        needsAnyPgColumn,
+        needsForeignKeyImport,
+        needsPrimaryKeyImport,
+        needsTsvector
+    };
+}
+function emitDrizzleSchema(schema, options) {
+    const pgCoreImports = new Set([
+        'pgSchema'
+    ]);
+    let needsSql = false;
+    let needsAnyPgColumn = false;
+    let needsForeignKeyImport = false;
+    let needsPrimaryKeyImport = false;
+    let needsTsvector = false;
+    const enums = Object.values(schema.enums).sort((a, b)=>a.key.localeCompare(b.key));
+    const tables = Object.values(schema.tables).sort((a, b)=>a.key.localeCompare(b.key));
+    for (const table of tables){
+        for (const column of Object.values(table.columns)){
+            if (typeof column.type === 'string') {
+                if (column.type !== 'tsvector') {
+                    pgCoreImports.add(column.type);
+                }
+            }
+            if (column.default?.kind === 'sql') {
+                needsSql = true;
+            }
+        }
+        if (Object.keys(table.indexes).length > 0) {
+            pgCoreImports.add('index');
+        }
+        if (Object.values(table.indexes).some((indexDef)=>indexDef.unique)) {
+            pgCoreImports.add('uniqueIndex');
+        }
+        if (Object.values(table.indexes).some((indexDef)=>indexDef.where)) {
+            needsSql = true;
+        }
+    }
+    const enumBlocks = enums.map(emitEnum);
+    const tableBlocks = tables.map((table)=>{
+        const emitted = emitTable(table);
+        needsSql ||= emitted.needsSql;
+        needsAnyPgColumn ||= emitted.needsAnyPgColumn;
+        needsForeignKeyImport ||= emitted.needsForeignKeyImport;
+        needsPrimaryKeyImport ||= emitted.needsPrimaryKeyImport;
+        needsTsvector ||= emitted.needsTsvector;
+        return emitted.code;
+    });
+    const typeBlocks = tables.map(emitTableTypeAliases);
+    if (needsForeignKeyImport) pgCoreImports.add('foreignKey');
+    if (needsPrimaryKeyImport) pgCoreImports.add('primaryKey');
+    if (needsTsvector) pgCoreImports.add('customType');
+    const imports = [];
+    if (needsSql) {
+        imports.push(`import { sql } from 'drizzle-orm';`);
+    }
+    imports.push(`import { ${Array.from(pgCoreImports).sort().join(', ')} } from 'drizzle-orm/pg-core';`);
+    if (needsAnyPgColumn) {
+        imports.push(`import type { AnyPgColumn } from 'drizzle-orm/pg-core';`);
+    }
+    const needsNewId = tables.some((table)=>Object.values(table.columns).some((col)=>col.defaultId));
+    if (needsNewId) {
+        imports.push(options?.nanoidImport ?? `import { newId } from '@createcms/core/nanoid';`);
+    }
+    const tsvectorDef = needsTsvector ? `\nconst tsvectorColumn = customType<{ data: string }>({
+  dataType() { return 'tsvector'; },
+});\n` : '';
+    const schemaExport = `export const schema = {
+${tables.map((table)=>`  ${table.key},`).join('\n')}
+${enums.map((enumDef)=>`  ${enumDef.key}Enum,`).join('\n')}
+};`;
+    return `/* eslint-disable */
+/**
+ * This file is generated by createcms.
+ * Do not edit manually.
+ */
+
+${imports.join('\n')}
+
+export const cms = pgSchema('cms');
+${tsvectorDef}${enumBlocks.join('\n\n')}
+${enumBlocks.length > 0 && tableBlocks.length > 0 ? '\n' : ''}${tableBlocks.join('\n\n')}
+
+${schemaExport}
+
+${typeBlocks.join('\n\n')}
+`;
+}
+
+async function generateSchema(config) {
+    const merged = mergeSchemaSources(config.sources);
+    const output = emitDrizzleSchema(merged, config.emit);
+    const outputPath = path.resolve(config.outputPath);
+    await mkdir(path.dirname(outputPath), {
+        recursive: true
+    });
+    await writeFile(outputPath, output, 'utf8');
+    return {
+        outputPath,
+        schema: merged,
+        output
+    };
+}
+
+function defineCoreSchema(schema) {
+    return {
+        ...schema
+    };
+}
+
+const coreSchema = defineCoreSchema({
+    enums: {
+        approvalStatus: {
+            enumName: 'approval_status',
+            values: [
+                'pending',
+                'approved',
+                'rejected'
+            ]
+        },
+        assetStatus: {
+            enumName: 'asset_status',
+            values: [
+                'private',
+                'public'
+            ]
+        },
+        mergeRequestStatus: {
+            enumName: 'merge_request_status',
+            values: [
+                'open',
+                'merged',
+                'closed'
+            ]
+        },
+        conflictResolution: {
+            enumName: 'conflict_resolution',
+            values: [
+                'source',
+                'target',
+                'manual'
+            ]
+        },
+        commentThreadTarget: {
+            enumName: 'comment_thread_target',
+            values: [
+                'mergeRequest',
+                'block'
+            ]
+        },
+        commentThreadStatus: {
+            enumName: 'comment_thread_status',
+            values: [
+                'open',
+                'resolved'
+            ]
+        },
+        commentMessageType: {
+            enumName: 'comment_message_type',
+            values: [
+                'comment',
+                'system'
+            ]
+        },
+        commentSystemType: {
+            enumName: 'comment_system_type',
+            values: [
+                'threadResolved',
+                'threadReopened'
+            ]
+        },
+        notificationType: {
+            enumName: 'notification_type',
+            values: [
+                'mention',
+                'comment',
+                'threadResolved',
+                'approvalRequested',
+                'approvalApproved',
+                'approvalRejected',
+                'mergeRequestOpened',
+                'mergeRequestMerged',
+                'mergeRequestClosed',
+                'mergeRequestReopened',
+                'published',
+                'custom'
+            ]
+        },
+        // A redirect endpoint (source or target) is either a page REFERENCE (rootId,
+        // resolves to the page's current path — follows moves) or a literal PATH.
+        // 'regex' is reserved for a later version (unindexed ordered scan).
+        redirectEndpointType: {
+            enumName: 'redirect_endpoint_type',
+            values: [
+                'page',
+                'path'
+            ]
+        },
+        // The kind of content a `content_usages` row indexes. One generalist index
+        // (version-keyed, insert-only, branch-head liveness) backs all three: assets
+        // (GC reclaim + media-library UI), variables (in-use guard + revalidation),
+        // and reusable-block references (delete guard + usage UI). 'reference' is
+        // populated from RB1 on; the enum carries it now so RB1 needs no enum change.
+        contentUsageTarget: {
+            enumName: 'content_usage_target',
+            values: [
+                'asset',
+                'variable',
+                'reference'
+            ]
+        }
+    },
+    tables: {
+        // ========================================================================
+        // ROOTS
+        // ========================================================================
+        roots: {
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'root'
+                },
+                collection: {
+                    type: 'text',
+                    notNull: true
+                },
+                parentRootId: {
+                    type: 'text'
+                },
+                slug: {
+                    type: 'text'
+                },
+                sortOrder: {
+                    type: 'integer',
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: 0
+                    }
+                },
+                createdBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                archivedAt: {
+                    type: 'timestamp'
+                },
+                lastPrunedAt: {
+                    type: 'timestamp'
+                }
+            },
+            foreignKeys: [
+                {
+                    columns: [
+                        'parentRootId'
+                    ],
+                    foreignTable: 'roots',
+                    foreignColumns: [
+                        'id'
+                    ],
+                    name: 'roots_parent_fk',
+                    onDelete: 'cascade'
+                }
+            ],
+            indexes: {
+                collectionIdx: {
+                    columns: [
+                        'collection'
+                    ]
+                },
+                parentRootIdx: {
+                    columns: [
+                        'parentRootId'
+                    ]
+                },
+                // Lookup index for resolvePathToRootId's slug-chain CTE. NON-unique on
+                // purpose: a core GLOBAL unique on (collection, parentRootId, slug) cannot
+                // be loosened by a plugin (merge.ts only ADDS), so it would forbid the
+                // i18n plugin from allowing the SAME slug across languages (en/blog +
+                // de/blog). Uniqueness is the app-level authority (validateSlugUniqueness,
+                // called on every slug write) plus, under a scoping plugin, a per-scope
+                // partial unique. See I18N_DESIGN.md §3 (the redirects "Option B" move).
+                slugIdx: {
+                    columns: [
+                        'collection',
+                        'parentRootId',
+                        'slug'
+                    ]
+                },
+                // Pruning GC round-robin: pick the least-recently-pruned live roots.
+                archivedAtIdx: {
+                    columns: [
+                        'archivedAt'
+                    ]
+                },
+                lastPrunedAtIdx: {
+                    columns: [
+                        'lastPrunedAt'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // COMMITS
+        // ========================================================================
+        commits: {
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'commit'
+                },
+                rootId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'roots',
+                        column: 'id'
+                    }
+                },
+                parentCommitId: {
+                    type: 'text'
+                },
+                mergeSourceCommitId: {
+                    type: 'text'
+                },
+                message: {
+                    type: 'text'
+                },
+                createdBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            foreignKeys: [
+                {
+                    columns: [
+                        'parentCommitId'
+                    ],
+                    foreignTable: 'commits',
+                    foreignColumns: [
+                        'id'
+                    ],
+                    name: 'commits_parent_fk'
+                },
+                {
+                    columns: [
+                        'mergeSourceCommitId'
+                    ],
+                    foreignTable: 'commits',
+                    foreignColumns: [
+                        'id'
+                    ],
+                    name: 'commits_merge_source_fk'
+                }
+            ],
+            indexes: {
+                parentIdx: {
+                    columns: [
+                        'parentCommitId'
+                    ]
+                },
+                mergeSourceIdx: {
+                    columns: [
+                        'mergeSourceCommitId'
+                    ]
+                },
+                rootCreatedIdx: {
+                    columns: [
+                        'rootId',
+                        'createdAt'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // BRANCHES
+        // ========================================================================
+        branches: {
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'branch'
+                },
+                rootId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'roots',
+                        column: 'id'
+                    }
+                },
+                name: {
+                    type: 'text',
+                    notNull: true
+                },
+                headCommitId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commits',
+                        column: 'id'
+                    }
+                },
+                createdBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                rootIdIdx: {
+                    columns: [
+                        'rootId'
+                    ]
+                },
+                rootNameUnique: {
+                    columns: [
+                        'rootId',
+                        'name'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // BLOCK_VERSIONS
+        // ========================================================================
+        blockVersions: {
+            tableName: 'block_versions',
+            indexPrefix: 'bv',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'blockVersion'
+                },
+                blockId: {
+                    type: 'text',
+                    notNull: true
+                },
+                rootId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'roots',
+                        column: 'id'
+                    }
+                },
+                commitId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commits',
+                        column: 'id'
+                    }
+                },
+                type: {
+                    type: 'text',
+                    notNull: true
+                },
+                properties: {
+                    type: 'jsonb',
+                    notNull: true,
+                    jsonType: 'Record<string, unknown>'
+                },
+                children: {
+                    type: 'jsonb',
+                    notNull: true,
+                    jsonType: 'string[]',
+                    default: {
+                        kind: 'literal',
+                        value: []
+                    }
+                },
+                deleted: {
+                    type: 'boolean',
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: false
+                    }
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                blockIdIdx: {
+                    columns: [
+                        'blockId'
+                    ]
+                },
+                commitIdIdx: {
+                    columns: [
+                        'commitId'
+                    ]
+                },
+                rootIdIdx: {
+                    columns: [
+                        'rootId'
+                    ]
+                },
+                blockCommitUnique: {
+                    columns: [
+                        'blockId',
+                        'commitId'
+                    ],
+                    unique: true
+                },
+                propertiesGin: {
+                    columns: [
+                        'properties'
+                    ],
+                    using: 'gin'
+                }
+            }
+        },
+        // ========================================================================
+        // COMMIT_SNAPSHOTS
+        // ========================================================================
+        commitSnapshots: {
+            tableName: 'commit_snapshots',
+            indexPrefix: 'cs',
+            columns: {
+                commitId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commits',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                blockId: {
+                    type: 'text',
+                    notNull: true
+                },
+                blockVersionId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'blockVersions',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                }
+            },
+            compositePrimaryKey: {
+                columns: [
+                    'commitId',
+                    'blockId'
+                ]
+            },
+            indexes: {
+                blockVersionIdx: {
+                    columns: [
+                        'blockVersionId'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // PUBLICATIONS
+        // ========================================================================
+        publications: {
+            columns: {
+                rootId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'roots',
+                        column: 'id'
+                    }
+                },
+                branchId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'branches',
+                        column: 'id'
+                    }
+                },
+                commitId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commits',
+                        column: 'id'
+                    }
+                },
+                publishedBy: {
+                    type: 'text',
+                    notNull: true
+                },
+                publishedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            compositePrimaryKey: {
+                columns: [
+                    'rootId',
+                    'branchId'
+                ]
+            },
+            indexes: {
+                branchIdx: {
+                    columns: [
+                        'branchId'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // MERGE_REQUESTS
+        // ========================================================================
+        mergeRequests: {
+            tableName: 'merge_requests',
+            indexPrefix: 'mr',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'mergeRequest'
+                },
+                rootId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'roots',
+                        column: 'id'
+                    }
+                },
+                sourceBranchId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'branches',
+                        column: 'id'
+                    }
+                },
+                targetBranchId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'branches',
+                        column: 'id'
+                    }
+                },
+                sourceCommitId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commits',
+                        column: 'id'
+                    }
+                },
+                baseCommitId: {
+                    type: 'text',
+                    references: {
+                        table: 'commits',
+                        column: 'id'
+                    }
+                },
+                mergeCommitId: {
+                    type: 'text',
+                    references: {
+                        table: 'commits',
+                        column: 'id'
+                    }
+                },
+                status: {
+                    type: {
+                        enum: 'mergeRequestStatus'
+                    },
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: 'open'
+                    }
+                },
+                title: {
+                    type: 'text'
+                },
+                description: {
+                    type: 'text'
+                },
+                createdBy: {
+                    type: 'text',
+                    notNull: true
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                rootIdx: {
+                    columns: [
+                        'rootId'
+                    ]
+                },
+                sourceBranchIdx: {
+                    columns: [
+                        'sourceBranchId'
+                    ]
+                },
+                targetBranchIdx: {
+                    columns: [
+                        'targetBranchId'
+                    ]
+                },
+                statusIdx: {
+                    columns: [
+                        'status'
+                    ]
+                },
+                openSourceTargetUnique: {
+                    columns: [
+                        'sourceBranchId',
+                        'targetBranchId'
+                    ],
+                    unique: true,
+                    where: "status = 'open'"
+                }
+            }
+        },
+        // ========================================================================
+        // MERGE_CONFLICTS
+        // ========================================================================
+        mergeConflicts: {
+            tableName: 'merge_conflicts',
+            indexPrefix: 'mc',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'mergeConflict'
+                },
+                mergeRequestId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'mergeRequests',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                blockId: {
+                    type: 'text',
+                    notNull: true
+                },
+                sourceVersionId: {
+                    type: 'text',
+                    references: {
+                        table: 'blockVersions',
+                        column: 'id'
+                    }
+                },
+                targetVersionId: {
+                    type: 'text',
+                    references: {
+                        table: 'blockVersions',
+                        column: 'id'
+                    }
+                },
+                baseVersionId: {
+                    type: 'text',
+                    references: {
+                        table: 'blockVersions',
+                        column: 'id'
+                    }
+                },
+                resolution: {
+                    type: {
+                        enum: 'conflictResolution'
+                    }
+                },
+                resolvedVersionId: {
+                    type: 'text',
+                    references: {
+                        table: 'blockVersions',
+                        column: 'id'
+                    }
+                },
+                resolvedBy: {
+                    type: 'text'
+                },
+                resolvedAt: {
+                    type: 'timestamp'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                mergeRequestIdx: {
+                    columns: [
+                        'mergeRequestId'
+                    ]
+                },
+                mergeBlockUnique: {
+                    columns: [
+                        'mergeRequestId',
+                        'blockId'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // APPROVALS
+        // ========================================================================
+        approvals: {
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'approval'
+                },
+                mergeRequestId: {
+                    type: 'text',
+                    references: {
+                        table: 'mergeRequests',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                branchId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'branches',
+                        column: 'id'
+                    }
+                },
+                commitId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commits',
+                        column: 'id'
+                    }
+                },
+                status: {
+                    type: {
+                        enum: 'approvalStatus'
+                    },
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: 'pending'
+                    }
+                },
+                requestedBy: {
+                    type: 'text',
+                    notNull: true
+                },
+                requestedReviewer: {
+                    type: 'text',
+                    notNull: true
+                },
+                reviewedBy: {
+                    type: 'text'
+                },
+                message: {
+                    type: 'text'
+                },
+                rejectionReason: {
+                    type: 'text'
+                },
+                reviewedAt: {
+                    type: 'timestamp'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                mrIdx: {
+                    columns: [
+                        'mergeRequestId'
+                    ]
+                },
+                branchIdx: {
+                    columns: [
+                        'branchId'
+                    ]
+                },
+                branchCommitIdx: {
+                    columns: [
+                        'branchId',
+                        'commitId'
+                    ]
+                },
+                statusIdx: {
+                    columns: [
+                        'status'
+                    ]
+                },
+                requestedReviewerIdx: {
+                    columns: [
+                        'requestedReviewer'
+                    ]
+                },
+                targetReviewerUnique: {
+                    columns: [
+                        'mergeRequestId',
+                        'branchId',
+                        'commitId',
+                        'requestedReviewer'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // ASSET_FOLDERS
+        // ========================================================================
+        assetFolders: {
+            tableName: 'asset_folders',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'assetFolder'
+                },
+                name: {
+                    type: 'text',
+                    notNull: true
+                },
+                parentId: {
+                    type: 'text'
+                },
+                createdBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            foreignKeys: [
+                {
+                    columns: [
+                        'parentId'
+                    ],
+                    foreignTable: 'assetFolders',
+                    foreignColumns: [
+                        'id'
+                    ],
+                    name: 'asset_folders_parent_fk',
+                    onDelete: 'cascade'
+                }
+            ],
+            indexes: {
+                parentIdx: {
+                    columns: [
+                        'parentId'
+                    ]
+                },
+                nameUnique: {
+                    columns: [
+                        'parentId',
+                        'name'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // ASSETS
+        // ========================================================================
+        assets: {
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'asset'
+                },
+                slug: {
+                    type: 'text',
+                    notNull: true
+                },
+                mimeType: {
+                    type: 'text',
+                    notNull: true
+                },
+                size: {
+                    type: 'integer',
+                    notNull: true
+                },
+                objectKey: {
+                    type: 'text',
+                    notNull: true
+                },
+                status: {
+                    type: {
+                        enum: 'assetStatus'
+                    },
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: 'private'
+                    }
+                },
+                folderId: {
+                    type: 'text',
+                    references: {
+                        table: 'assetFolders',
+                        column: 'id',
+                        onDelete: 'set null'
+                    }
+                },
+                variantOf: {
+                    type: 'text',
+                    references: {
+                        table: 'assets',
+                        column: 'id',
+                        onDelete: 'set null'
+                    }
+                },
+                uploadedBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                archivedAt: {
+                    type: 'timestamp'
+                }
+            },
+            indexes: {
+                folderIdx: {
+                    columns: [
+                        'folderId'
+                    ]
+                },
+                statusIdx: {
+                    columns: [
+                        'status'
+                    ]
+                },
+                variantOfIdx: {
+                    columns: [
+                        'variantOf'
+                    ]
+                },
+                objectKeyUnique: {
+                    columns: [
+                        'objectKey'
+                    ],
+                    unique: true
+                },
+                slugUnique: {
+                    columns: [
+                        'slug'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // COMMENT_THREADS
+        // ========================================================================
+        commentThreads: {
+            tableName: 'comment_threads',
+            indexPrefix: 'ct',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'commentThread'
+                },
+                rootId: {
+                    type: 'text',
+                    references: {
+                        table: 'roots',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                collection: {
+                    type: 'text',
+                    notNull: true
+                },
+                targetType: {
+                    type: {
+                        enum: 'commentThreadTarget'
+                    },
+                    notNull: true
+                },
+                mergeRequestId: {
+                    type: 'text',
+                    references: {
+                        table: 'mergeRequests',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                blockId: {
+                    type: 'text'
+                },
+                commitId: {
+                    type: 'text',
+                    references: {
+                        table: 'commits',
+                        column: 'id',
+                        onDelete: 'set null'
+                    }
+                },
+                status: {
+                    type: {
+                        enum: 'commentThreadStatus'
+                    },
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: 'open'
+                    }
+                },
+                resolvedBy: {
+                    type: 'text'
+                },
+                resolvedAt: {
+                    type: 'timestamp'
+                },
+                createdBy: {
+                    type: 'text',
+                    notNull: true
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                deletedAt: {
+                    type: 'timestamp'
+                }
+            },
+            indexes: {
+                collectionIdx: {
+                    columns: [
+                        'collection',
+                        'createdAt'
+                    ]
+                },
+                mrIdx: {
+                    columns: [
+                        'mergeRequestId',
+                        'createdAt'
+                    ]
+                },
+                blockIdx: {
+                    columns: [
+                        'blockId',
+                        'createdAt'
+                    ]
+                },
+                commitIdx: {
+                    columns: [
+                        'commitId',
+                        'createdAt'
+                    ]
+                },
+                rootIdx: {
+                    columns: [
+                        'rootId',
+                        'createdAt'
+                    ]
+                },
+                statusIdx: {
+                    columns: [
+                        'status'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // COMMENT_MESSAGES
+        // ========================================================================
+        commentMessages: {
+            tableName: 'comment_messages',
+            indexPrefix: 'cm',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'commentMessage'
+                },
+                threadId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commentThreads',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                parentMessageId: {
+                    type: 'text'
+                },
+                authorId: {
+                    type: 'text'
+                },
+                messageType: {
+                    type: {
+                        enum: 'commentMessageType'
+                    },
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: 'comment'
+                    }
+                },
+                systemType: {
+                    type: {
+                        enum: 'commentSystemType'
+                    }
+                },
+                body: {
+                    type: 'text'
+                },
+                meta: {
+                    type: 'jsonb',
+                    jsonType: 'Record<string, unknown>'
+                },
+                editedAt: {
+                    type: 'timestamp'
+                },
+                deletedAt: {
+                    type: 'timestamp'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            foreignKeys: [
+                {
+                    columns: [
+                        'parentMessageId'
+                    ],
+                    foreignTable: 'commentMessages',
+                    foreignColumns: [
+                        'id'
+                    ],
+                    name: 'comment_messages_parent_fk',
+                    onDelete: 'set null'
+                }
+            ],
+            indexes: {
+                threadIdx: {
+                    columns: [
+                        'threadId',
+                        'createdAt'
+                    ]
+                },
+                parentIdx: {
+                    columns: [
+                        'parentMessageId'
+                    ]
+                },
+                typeIdx: {
+                    columns: [
+                        'messageType',
+                        'systemType'
+                    ]
+                },
+                authorIdx: {
+                    columns: [
+                        'authorId',
+                        'createdAt'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // COMMENT_MENTIONS
+        // ========================================================================
+        commentMentions: {
+            tableName: 'comment_mentions',
+            indexPrefix: 'cmn',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'commentMention'
+                },
+                messageId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commentMessages',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                threadId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'commentThreads',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                mentionedUserId: {
+                    type: 'text',
+                    notNull: true
+                },
+                mentionedBy: {
+                    type: 'text',
+                    notNull: true
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                userIdx: {
+                    columns: [
+                        'mentionedUserId',
+                        'createdAt'
+                    ]
+                },
+                messageIdx: {
+                    columns: [
+                        'messageId'
+                    ]
+                },
+                threadUserIdx: {
+                    columns: [
+                        'threadId',
+                        'mentionedUserId'
+                    ]
+                },
+                messageUserUnique: {
+                    columns: [
+                        'messageId',
+                        'mentionedUserId'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // ASSET_REFERENCES
+        // ========================================================================
+        // ========================================================================
+        // CONTENT_USAGES — One generalist materialized index for ALL content-derived
+        // usage: assets, variables, and reusable-block references. Replaces the old
+        // per-domain asset_references + variable_usages tables (structurally one
+        // pattern). Keyed by the IMMUTABLE blockVersionId: a block diverges per
+        // branch into distinct, append-only versions, so a version-keyed row never
+        // drifts. Rows are inserted ONCE when a version is created (never re-synced)
+        // and removed only by FK cascade when the version (or its root) is pruned.
+        // LIVENESS is decided by joining to branch-HEAD snapshots, never a stored
+        // flag — a superseded version simply stops counting. `targetKey` is
+        // POLYMORPHIC (assetId | variableKey | referencedRootId) and intentionally
+        // carries NO FK: correctness comes from the liveness join, not a per-target
+        // cascade (verified — asset GC reclaim + hardDeleteRoot depend on the
+        // blockVersionId/rootId keys + the join). This is the single source of truth
+        // for the destructive GC/guards AND the usage UIs.
+        contentUsages: {
+            tableName: 'content_usages',
+            indexPrefix: 'cu',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'contentUsage'
+                },
+                targetKind: {
+                    type: {
+                        enum: 'contentUsageTarget'
+                    },
+                    notNull: true
+                },
+                // assetId | variableKey | referencedRootId — discriminated by targetKind.
+                targetKey: {
+                    type: 'text',
+                    notNull: true
+                },
+                blockVersionId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'blockVersions',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                // rootId/blockId are the denormalized HOST root/block for fast UI
+                // grouping and for the prune-by-rootId path; rootId also cascades.
+                rootId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'roots',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                blockId: {
+                    type: 'text',
+                    notNull: true
+                },
+                propertyKey: {
+                    type: 'text',
+                    notNull: true
+                }
+            },
+            indexes: {
+                versionTargetPropUnique: {
+                    columns: [
+                        'blockVersionId',
+                        'targetKind',
+                        'targetKey',
+                        'propertyKey'
+                    ],
+                    unique: true
+                },
+                targetIdx: {
+                    columns: [
+                        'targetKind',
+                        'targetKey'
+                    ]
+                },
+                blockVersionIdx: {
+                    columns: [
+                        'blockVersionId'
+                    ]
+                },
+                rootIdx: {
+                    columns: [
+                        'rootId'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // VARIABLES — User-editable key-value pairs for content substitution
+        // ========================================================================
+        variables: {
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'variable'
+                },
+                key: {
+                    type: 'text',
+                    notNull: true
+                },
+                value: {
+                    type: 'text',
+                    notNull: true
+                },
+                description: {
+                    type: 'text'
+                },
+                createdBy: {
+                    type: 'text'
+                },
+                updatedBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                keyUnique: {
+                    columns: [
+                        'key'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // TEMPLATES — Default-value formulas per collection/block/property
+        // ========================================================================
+        templates: {
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'template'
+                },
+                collection: {
+                    type: 'text',
+                    notNull: true
+                },
+                blockType: {
+                    type: 'text',
+                    notNull: true
+                },
+                propertyKey: {
+                    type: 'text',
+                    notNull: true
+                },
+                template: {
+                    type: 'text',
+                    notNull: true
+                },
+                description: {
+                    type: 'text'
+                },
+                createdBy: {
+                    type: 'text'
+                },
+                updatedBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                collectionBlockPropUnique: {
+                    columns: [
+                        'collection',
+                        'blockType',
+                        'propertyKey'
+                    ],
+                    unique: true
+                },
+                collectionIdx: {
+                    columns: [
+                        'collection'
+                    ]
+                },
+                collectionBlockIdx: {
+                    columns: [
+                        'collection',
+                        'blockType'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // TEMPLATE_VARIABLE_USAGES — Tracks which variables are used in templates
+        // ========================================================================
+        templateVariableUsages: {
+            tableName: 'template_variable_usages',
+            indexPrefix: 'tvu',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'tplVarUsage'
+                },
+                variableKey: {
+                    type: 'text',
+                    notNull: true
+                },
+                templateId: {
+                    type: 'text',
+                    notNull: true,
+                    references: {
+                        table: 'templates',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                }
+            },
+            indexes: {
+                keyTemplateUnique: {
+                    columns: [
+                        'variableKey',
+                        'templateId'
+                    ],
+                    unique: true
+                },
+                variableKeyIdx: {
+                    columns: [
+                        'variableKey'
+                    ]
+                },
+                templateIdIdx: {
+                    columns: [
+                        'templateId'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // SEARCH_INDEX — Materialized full-text search index across all entities
+        // ========================================================================
+        searchIndex: {
+            tableName: 'search_index',
+            indexPrefix: 'si',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'si'
+                },
+                entityType: {
+                    type: 'text',
+                    notNull: true
+                },
+                entityId: {
+                    type: 'text',
+                    notNull: true
+                },
+                collection: {
+                    type: 'text'
+                },
+                rootId: {
+                    type: 'text'
+                },
+                contentVector: {
+                    type: 'tsvector',
+                    notNull: true
+                },
+                title: {
+                    type: 'text'
+                },
+                snippet: {
+                    type: 'text'
+                },
+                meta: {
+                    type: 'jsonb',
+                    jsonType: 'Record<string, unknown>'
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                vectorGin: {
+                    columns: [
+                        'contentVector'
+                    ],
+                    using: 'gin'
+                },
+                entityTypeIdx: {
+                    columns: [
+                        'entityType'
+                    ]
+                },
+                collectionIdx: {
+                    columns: [
+                        'collection'
+                    ]
+                },
+                rootIdx: {
+                    columns: [
+                        'rootId'
+                    ]
+                },
+                entityUnique: {
+                    columns: [
+                        'entityType',
+                        'entityId'
+                    ],
+                    unique: true
+                }
+            }
+        },
+        // ========================================================================
+        // NOTIFICATIONS — In-app notification inbox per user
+        // ========================================================================
+        notifications: {
+            tableName: 'notifications',
+            indexPrefix: 'ntf',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'notification'
+                },
+                recipientId: {
+                    type: 'text',
+                    notNull: true
+                },
+                actorId: {
+                    type: 'text'
+                },
+                type: {
+                    type: {
+                        enum: 'notificationType'
+                    },
+                    notNull: true
+                },
+                title: {
+                    type: 'text',
+                    notNull: true
+                },
+                body: {
+                    type: 'text'
+                },
+                resourceType: {
+                    type: 'text'
+                },
+                resourceId: {
+                    type: 'text'
+                },
+                collection: {
+                    type: 'text'
+                },
+                meta: {
+                    type: 'jsonb',
+                    jsonType: 'Record<string, unknown>'
+                },
+                readAt: {
+                    type: 'timestamp'
+                },
+                archivedAt: {
+                    type: 'timestamp'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                }
+            },
+            indexes: {
+                recipientCreatedIdx: {
+                    columns: [
+                        'recipientId',
+                        'createdAt'
+                    ]
+                },
+                recipientUnreadIdx: {
+                    columns: [
+                        'recipientId',
+                        'readAt'
+                    ]
+                },
+                resourceIdx: {
+                    columns: [
+                        'resourceType',
+                        'resourceId'
+                    ]
+                },
+                typeIdx: {
+                    columns: [
+                        'type'
+                    ]
+                }
+            }
+        },
+        // ========================================================================
+        // REDIRECTS — SEO 301/302 mapping (see REDIRECTS_DESIGN.md)
+        // ========================================================================
+        // Source and target are each a page REFERENCE (rootId → current path,
+        // follows moves) or a literal PATH. Auto-created on rename/move/archive,
+        // or managed manually. Resolved by the consumer before serving content.
+        redirects: {
+            tableName: 'redirects',
+            indexPrefix: 'rdr',
+            columns: {
+                id: {
+                    type: 'text',
+                    primaryKey: true,
+                    defaultId: true,
+                    defaultIdPrefix: 'redirect'
+                },
+                collection: {
+                    type: 'text',
+                    notNull: true
+                },
+                sourceType: {
+                    type: {
+                        enum: 'redirectEndpointType'
+                    },
+                    notNull: true
+                },
+                // 'page' source: redirect away from this live page (follows its slug).
+                sourceRootId: {
+                    type: 'text',
+                    references: {
+                        table: 'roots',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                // 'path' source: the exact (normalized) old/dead path.
+                sourcePath: {
+                    type: 'text'
+                },
+                targetType: {
+                    type: {
+                        enum: 'redirectEndpointType'
+                    },
+                    notNull: true
+                },
+                // 'page' target: resolves to the root's CURRENT published path.
+                targetRootId: {
+                    type: 'text',
+                    references: {
+                        table: 'roots',
+                        column: 'id',
+                        onDelete: 'cascade'
+                    }
+                },
+                // 'path' target: literal / external destination.
+                targetPath: {
+                    type: 'text'
+                },
+                statusCode: {
+                    type: 'integer',
+                    notNull: true,
+                    default: {
+                        kind: 'literal',
+                        value: 301
+                    }
+                },
+                createdBy: {
+                    type: 'text'
+                },
+                createdAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                updatedAt: {
+                    type: 'timestamp',
+                    notNull: true,
+                    defaultNow: true
+                },
+                archivedAt: {
+                    type: 'timestamp'
+                }
+            },
+            indexes: {
+                // Exact path-source lookup (collection + path). NON-unique on purpose:
+                // uniqueness of a source is enforced at the APPLICATION level
+                // (assertSourceUnique + the auto-create pre-check), scope-filtered where a
+                // scoping plugin is active. A core DB-unique on (collection, sourcePath)
+                // would be GLOBAL — it cannot be loosened by a plugin (merge.ts only ADDS
+                // indexes), so two scopes could never share a path. A scoping
+                // plugin instead adds its own PARTIAL UNIQUE on its scope column(s) + (collection,
+                // sourcePath), which is the real DB guarantee when scoping is on.
+                collectionSourcePathIdx: {
+                    columns: [
+                        'collection',
+                        'sourcePath'
+                    ]
+                },
+                // Page-source lookup: does this live root redirect away? NON-unique for
+                // the same reason (per-scope uniqueness is the plugin's job).
+                sourceRootIdx: {
+                    columns: [
+                        'sourceRootId'
+                    ]
+                },
+                collectionIdx: {
+                    columns: [
+                        'collection'
+                    ]
+                },
+                archivedAtIdx: {
+                    columns: [
+                        'archivedAt'
+                    ]
+                }
+            }
+        }
+    }
+});
+
+/** Returns true if a file/path exists and is accessible. */ async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+
+const CONFIG_CANDIDATES = [
+    'cms.ts',
+    'cms.js',
+    'src/cms.ts',
+    'src/cms.js',
+    'src/lib/cms.ts',
+    'src/lib/cms.js',
+    'lib/cms.ts',
+    'lib/cms.js'
+];
+async function discoverConfig(cwd) {
+    for (const candidate of CONFIG_CANDIDATES){
+        const fullPath = path.resolve(cwd, candidate);
+        if (await fileExists(fullPath)) {
+            return fullPath;
+        }
+    }
+    return undefined;
+}
+
+const STUB_CODE = `
+const handler = {
+  get(_, prop) {
+    if (prop === Symbol.toPrimitive) return () => '';
+    if (prop === 'then') return undefined;
+    return stub;
+  },
+  apply() { return stub; },
+  construct() { return stub; },
+};
+const stub = new Proxy(function(){}, handler);
+export default stub;
+export { stub as auth, stub as db, stub as headers, stub as cookies };
+`;
+const SHIM_CODE = `
+export const createCMS = (definition) => ({
+  ...definition,
+  router: {},
+  api: {},
+  collections: definition.collections || {},
+  $plugins: definition.plugins || [],
+  $schema: definition.schema,
+});
+// Config authoring helpers are pure identity functions at runtime (see
+// core/define.ts). The shim re-implements them so a config that imports the
+// idiomatic \`defineCollection\` / \`defineCollections\` / \`defineAuthMiddleware\`
+// API loads during \`createcms generate\` without pulling in the real package.
+export const defineCollection = (collection) => collection;
+export const defineCollections = (collections) => collections;
+export const defineAuthMiddleware = (middleware) => middleware;
+export default { createCMS, defineCollection, defineCollections, defineAuthMiddleware };
+`;
+function ensureFile(dir, name, code) {
+    const filePath = path.join(dir, name);
+    try {
+        mkdirSync(dir, {
+            recursive: true
+        });
+        writeFileSync(filePath, code, 'utf8');
+    } catch  {
+    // best-effort
+    }
+    return filePath;
+}
+function readTsconfigPaths(cwd) {
+    const alias = {};
+    try {
+        const raw = readFileSync(path.join(cwd, 'tsconfig.json'), 'utf8');
+        const stripped = raw.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, '');
+        const tsconfig = JSON.parse(stripped);
+        const paths = tsconfig.compilerOptions?.paths;
+        const baseUrl = tsconfig.compilerOptions?.baseUrl ?? '.';
+        const base = path.resolve(cwd, baseUrl);
+        if (paths) {
+            for (const [pattern, targets] of Object.entries(paths)){
+                if (targets.length > 0) {
+                    const key = pattern.replace(/\/\*$/, '');
+                    const target = targets[0].replace(/\/\*$/, '');
+                    alias[key] = path.resolve(base, target);
+                }
+            }
+        }
+    } catch  {
+    // No tsconfig or invalid — skip
+    }
+    return alias;
+}
+/**
+ * Scans node_modules directories upward from cwd and collects all
+ * installed package names. These will be aliased to the stub so
+ * jiti never loads them (preventing side effects).
+ */ function collectInstalledPackages(cwd) {
+    const packages = new Set();
+    let dir = cwd;
+    while(true){
+        const nmDir = path.join(dir, 'node_modules');
+        try {
+            for (const entry of readdirSync(nmDir)){
+                if (entry.startsWith('.')) continue;
+                if (entry.startsWith('@')) {
+                    const scopeDir = path.join(nmDir, entry);
+                    try {
+                        for (const pkg of readdirSync(scopeDir)){
+                            if (!pkg.startsWith('.')) packages.add(`${entry}/${pkg}`);
+                        }
+                    } catch  {
+                    // not readable
+                    }
+                } else {
+                    packages.add(entry);
+                }
+            }
+        } catch  {
+        // no node_modules here
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return [
+        ...packages
+    ];
+}
+/**
+ * CJS fallback patch: catches any require() that still slips through
+ * jiti's alias system and redirects to the stub.
+ */ function patchModuleResolution(stubPath) {
+    const original = Module._resolveFilename;
+    Module._resolveFilename = function(request, parent, isMain, options) {
+        try {
+            return original.call(this, request, parent, isMain, options);
+        } catch  {
+            return stubPath;
+        }
+    };
+    return ()=>{
+        Module._resolveFilename = original;
+    };
+}
+/**
+ * Resolves the real @createcms/core dist directory by locating one of
+ * its exported subpaths and walking up to the dist root.
+ */ function resolveRealCmsDistDir(cwd) {
+    try {
+        const req = Module.createRequire(path.join(cwd, '_'));
+        // Resolve a known export — ./nanoid maps to dist/nanoid.js
+        const nanoidPath = req.resolve('@createcms/core/nanoid');
+        // nanoidPath = <pkg>/dist/nanoid.js → dirname = <pkg>/dist
+        return path.dirname(nanoidPath);
+    } catch  {
+        return null;
+    }
+}
+async function loadCMSConfig(configPath) {
+    const cwd = path.dirname(configPath);
+    const tsconfigAlias = readTsconfigPaths(cwd);
+    const tmpDir = path.join(tmpdir(), 'createcms-stubs');
+    const stubPath = ensureFile(tmpDir, 'module-stub.mjs', STUB_CODE);
+    const shimPath = ensureFile(tmpDir, 'cms-shim.mjs', SHIM_CODE);
+    // Build alias map: stub every installed package, then override
+    // @createcms/core with the lightweight shim
+    const allPackages = collectInstalledPackages(cwd);
+    const alias = {};
+    for (const pkg of allPackages){
+        alias[pkg] = stubPath;
+    }
+    alias['@createcms/core'] = shimPath;
+    // Jiti treats aliases as prefix replacements, so @createcms/core/plugins/server
+    // would resolve to <shimPath>/plugins/server (which doesn't exist).
+    // We need explicit aliases for subpaths that must resolve to the real package
+    // so the generator can load plugin schemas.
+    const cmsDistDir = resolveRealCmsDistDir(cwd);
+    if (cmsDistDir) {
+        for (const key of Object.keys(alias)){
+            if (key.startsWith('@createcms/core/')) {
+                delete alias[key];
+            }
+        }
+        // Map import specifiers → dist entry points
+        const subpathMap = {
+            'plugins/server': 'plugins/server.js',
+            'plugins/client': 'plugins/client.js',
+            'plugins/multi-tenant': 'plugins/multi-tenant/index.js',
+            'plugins/ab-test': 'plugins/ab-test/index.js',
+            'plugins/ab-test/client': 'plugins/ab-test/client.js',
+            'plugins/media-optimize': 'plugins/media-optimize/index.js',
+            plugins: 'plugins/index.js',
+            nanoid: 'nanoid.js'
+        };
+        for (const [specifier, distRelative] of Object.entries(subpathMap)){
+            alias[`@createcms/core/${specifier}`] = path.join(cmsDistDir, distRelative);
+        }
+    }
+    // tsconfig paths override everything (e.g. @/* → ./src/*)
+    Object.assign(alias, tsconfigAlias);
+    const restore = patchModuleResolution(stubPath);
+    try {
+        const jiti = createJiti(pathToFileURL(configPath).href, {
+            interopDefault: true,
+            moduleCache: false,
+            alias
+        });
+        const mod = await jiti.import(configPath);
+        // jiti with interopDefault may nest the exports — try multiple paths
+        const instance = mod.cms ?? mod.default ?? mod;
+        if (!instance || typeof instance !== 'object') {
+            throw new Error(`No CMS instance found. Export your createCMS() result as default or named "cms" from ${configPath}`);
+        }
+        return instance;
+    } finally{
+        restore();
+    }
+}
+
+function printMeta(label, value) {
+    console.log(`  ${kleur.bold().gray(label)} ${value}`);
+}
+function createSpinner(text) {
+    return ora({
+        text: `  ${text}`,
+        color: 'cyan'
+    });
+}
+async function confirmOverwrite(filePath) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(`\n  ${kleur.red('Error:')} Output file already exists and no interactive terminal is available.`);
+        printMeta('file', filePath);
+        printMeta('hint', 'Delete the file first or run the command in an interactive terminal.');
+        return false;
+    }
+    console.log();
+    console.log(`  ${kleur.yellow('!')} ${kleur.bold('Output file already exists.')}`);
+    printMeta('file', filePath);
+    const response = await prompts({
+        type: 'confirm',
+        name: 'overwrite',
+        message: 'Overwrite existing file?',
+        initial: false
+    }, {
+        onCancel: ()=>false
+    });
+    return response.overwrite === true;
+}
+
+function collectSchemaSources(config) {
+    const sources = [
+        {
+            name: 'core',
+            schema: coreSchema
+        }
+    ];
+    if (config.$plugins) {
+        for (const plugin of config.$plugins){
+            if (plugin.schema) {
+                sources.push({
+                    name: `plugin:${plugin.id}`,
+                    schema: plugin.schema
+                });
+            }
+        }
+    }
+    return sources;
+}
+function registerGenerateCommand(cli) {
+    cli.command('generate [config]', 'Generate the Drizzle schema from your CMS config').option('--output <path>', 'Override the output file path').action(async (configArg, options)=>{
+        const cwd = process.cwd();
+        const spinner = createSpinner('Looking for config');
+        spinner.start();
+        let configPath;
+        if (configArg) {
+            configPath = path.resolve(cwd, configArg);
+        } else {
+            const discovered = await discoverConfig(cwd);
+            if (!discovered) {
+                spinner.fail('No cms.ts found. Searched cms.ts, src/cms.ts, src/lib/cms.ts. Pass a path: createcms generate ./path/to/cms.ts');
+                process.exit(1);
+            }
+            configPath = discovered;
+        }
+        spinner.succeed(`  Found: ${configPath}`);
+        const loadSpinner = createSpinner('Loading CMS config');
+        loadSpinner.start();
+        let config;
+        try {
+            config = await loadCMSConfig(configPath);
+        } catch (err) {
+            loadSpinner.fail('  Failed to load CMS config');
+            throw err;
+        }
+        loadSpinner.succeed('  Config loaded');
+        const outputPath = path.resolve(cwd, options?.output ?? config.$schema?.output ?? './cms-schema.ts');
+        console.log();
+        printMeta('config', kleur.dim(configPath));
+        printMeta('output', kleur.dim(outputPath));
+        const sources = collectSchemaSources(config);
+        const pluginCount = sources.length - 1;
+        if (pluginCount > 0) {
+            printMeta('plugins', kleur.dim(sources.filter((s)=>s.name !== 'core').map((s)=>s.name.replace('plugin:', '')).join(', ')));
+        }
+        if (await fileExists(outputPath)) {
+            const shouldOverwrite = await confirmOverwrite(outputPath);
+            if (!shouldOverwrite) {
+                console.log(`\n  ${kleur.yellow('Generation cancelled.')}`);
+                return;
+            }
+        }
+        const genSpinner = createSpinner('Generating schema');
+        genSpinner.start();
+        try {
+            const result = await generateSchema({
+                sources,
+                outputPath
+            });
+            genSpinner.succeed('  Schema generated');
+            console.log();
+            printMeta('file', kleur.green(result.outputPath));
+            printMeta('tables', kleur.green(String(Object.keys(result.schema.tables).length)));
+            printMeta('enums', kleur.green(String(Object.keys(result.schema.enums).length)));
+            console.log();
+        } catch (error) {
+            genSpinner.fail('  Schema generation failed');
+            throw error;
+        }
+    });
+}
+
+// ============================================================================
+// `createcms init` scaffold templates + collection presets
+// ============================================================================
+//
+// Plain string templates (bundled into dist by bunchee — NOT read from disk at
+// runtime). They target a Next.js App Router project using the create-next-app
+// `--src-dir` layout (files under `src/`, the `@/*` → `./src/*` path alias).
+// db wiring is intentionally left to the consumer (`@/lib/db`) — `init` only
+// scaffolds the CMS side.
+/**
+ * A ready-made collection the consumer can scaffold via `createcms init
+ * --preset <name>`. The scaffolded collection file is editable code the
+ * consumer OWNS (presets are a starting point, not a maintained import).
+ */ const pagesCollection = ()=>`import type { CollectionDefinition } from '@createcms/core';
+
+export const pagesCollection = {
+  label: 'Pages',
+  description: 'Marketing and content pages.',
+  slug: { enabled: true, root: '/' },
+  root: {
+    properties: {
+      title: {
+        type: 'string',
+        label: 'Title',
+        required: true,
+        defaultValue: 'Untitled page',
+      },
+    },
+  },
+  blocks: {
+    richText: {
+      label: 'Rich Text',
+      description: 'A block of formatted text.',
+      properties: {
+        content: { type: 'richText', label: 'Content', required: true },
+      },
+    },
+  },
+} as const satisfies CollectionDefinition;
+
+export type PagesCollection = typeof pagesCollection;
+`;
+const postsCollection = ()=>`import type { CollectionDefinition } from '@createcms/core';
+
+export const postsCollection = {
+  label: 'Blog Posts',
+  description: 'Articles and updates.',
+  slug: { enabled: true, root: '/blog' },
+  root: {
+    properties: {
+      title: {
+        type: 'string',
+        label: 'Title',
+        required: true,
+        defaultValue: 'Untitled post',
+      },
+      excerpt: {
+        type: 'string',
+        label: 'Excerpt',
+        placeholder: 'A short summary shown in listings.',
+      },
+      publishedAt: { type: 'date', label: 'Published at' },
+      draft: { type: 'boolean', label: 'Draft', defaultValue: false },
+    },
+  },
+  blocks: {
+    richText: {
+      label: 'Rich Text',
+      description: 'A block of formatted text.',
+      properties: {
+        content: { type: 'richText', label: 'Content', required: true },
+      },
+    },
+    image: {
+      label: 'Image',
+      description: 'A figure with optional caption.',
+      properties: {
+        src: { type: 'image', label: 'Image', required: true },
+        alt: { type: 'string', label: 'Alt text', required: true },
+        caption: { type: 'string', label: 'Caption' },
+      },
+    },
+  },
+} as const satisfies CollectionDefinition;
+
+export type PostsCollection = typeof postsCollection;
+`;
+const docsCollection = ()=>`import type { CollectionDefinition } from '@createcms/core';
+
+export const docsCollection = {
+  label: 'Docs',
+  description: 'Nested documentation pages.',
+  slug: { enabled: true, root: '/docs', nested: true, normalize: true },
+  root: {
+    properties: {
+      title: {
+        type: 'string',
+        label: 'Title',
+        required: true,
+        defaultValue: 'Untitled page',
+      },
+    },
+  },
+  blocks: {
+    richText: {
+      label: 'Rich Text',
+      description: 'A block of formatted text.',
+      properties: {
+        content: { type: 'richText', label: 'Content', required: true },
+      },
+    },
+    callout: {
+      label: 'Callout',
+      description: 'A highlighted note.',
+      properties: {
+        variant: {
+          type: 'select',
+          label: 'Variant',
+          defaultValue: 'info',
+          options: [
+            { label: 'Info', value: 'info' },
+            { label: 'Warning', value: 'warning' },
+            { label: 'Tip', value: 'tip' },
+          ],
+        },
+        content: { type: 'richText', label: 'Content', required: true },
+      },
+    },
+  },
+} as const satisfies CollectionDefinition;
+
+export type DocsCollection = typeof docsCollection;
+`;
+/** The shipped presets, keyed by `--preset <name>`. */ const PRESETS = {
+    pages: {
+        name: 'pages',
+        description: 'Marketing & content pages (the default).',
+        fileName: 'pages',
+        exportName: 'pagesCollection',
+        collectionKey: 'pages',
+        collection: pagesCollection
+    },
+    blog: {
+        name: 'blog',
+        description: 'A blog: posts with excerpt, date, cover image + rich text.',
+        fileName: 'posts',
+        exportName: 'postsCollection',
+        collectionKey: 'posts',
+        collection: postsCollection
+    },
+    docs: {
+        name: 'docs',
+        description: 'Nested documentation pages with callouts.',
+        fileName: 'docs',
+        exportName: 'docsCollection',
+        collectionKey: 'docs',
+        collection: docsCollection
+    }
+};
+const DEFAULT_PRESET = 'pages';
+/** `src/lib/cms.ts` — the createCMS config, wired to the chosen preset. */ const cmsConfigTemplate = (preset)=>`import { createCMS } from '@createcms/core';
+
+import { ${preset.exportName} } from '@/cms/collections/${preset.fileName}';
+// TODO: point this at YOUR Drizzle client (a DrizzleInstance). createcms does
+// not scaffold the database client — wire your own (see https://orm.drizzle.team).
+import { db } from '@/lib/db';
+
+export const cms = createCMS({
+  db,
+  // Where \`createcms generate\` writes the Drizzle schema for the CMS tables.
+  schema: {
+    output: './src/db/schema/cms.ts',
+  },
+  collections: {
+    ${preset.collectionKey}: ${preset.exportName},
+  },
+  // Media uploads target any S3-compatible bucket. Fill from your environment.
+  media: {
+    provider: 'aws',
+    region: process.env.S3_REGION!,
+    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+    bucketName: process.env.S3_BUCKET!,
+    publicUrl: process.env.S3_PUBLIC_URL!,
+  },
+  // Published content is public; everything else requires auth. Replace the
+  // TODO with your real session/permission check (return {} to allow, throw to
+  // deny).
+  authMiddleware: async (ctx) => {
+    if (ctx.permissionResource === 'publishedContent') return {};
+    // TODO: resolve the signed-in user / permissions here.
+    throw new Error('Unauthorized');
+  },
+});
+`;
+/** `src/app/api/cms/[[...rest]]/route.ts` — mounts the CMS HTTP router. */ const routeHandlerTemplate = ()=>`import { cms } from '@/lib/cms';
+
+const { handler } = cms.router;
+
+export const GET = handler;
+export const POST = handler;
+`;
+/** `.env.example` — the env vars the scaffolded config reads. */ const envExampleTemplate = ()=>`# The CMS database — any Postgres connection string.
+DATABASE_URL=
+
+# Media uploads — any S3-compatible bucket.
+S3_REGION=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_BUCKET=
+S3_PUBLIC_URL=
+`;
+/** The npm script `init` adds to package.json. */ const GENERATE_SCRIPT = {
+    name: 'cms:generate',
+    command: 'createcms generate'
+};
+/**
+ * The files `init` scaffolds for a chosen preset, relative to the project root.
+ * Order is display order. Paths assume the `src/` layout (module header).
+ */ function buildInitFiles(preset) {
+    return [
+        {
+            path: 'src/lib/cms.ts',
+            content: ()=>cmsConfigTemplate(preset)
+        },
+        {
+            path: `src/cms/collections/${preset.fileName}.ts`,
+            content: preset.collection
+        },
+        {
+            path: 'src/app/api/cms/[[...rest]]/route.ts',
+            content: routeHandlerTemplate
+        },
+        {
+            path: '.env.example',
+            content: envExampleTemplate
+        }
+    ];
+}
+
+/**
+ * Resolve which preset to scaffold. An explicit `--preset` wins (and a typo is
+ * a hard error listing the valid names). Otherwise an interactive picker runs
+ * when a TTY is available; non-interactively it falls back to the default.
+ */ async function resolvePreset(flag) {
+    if (flag) {
+        // Object.hasOwn (not `in`) so prototype keys (constructor, __proto__, …) are
+        // rejected as unknown instead of resolving to a bogus non-preset value.
+        if (!Object.hasOwn(PRESETS, flag)) {
+            throw new Error(`Unknown preset "${flag}". Available: ${Object.keys(PRESETS).join(', ')}.`);
+        }
+        return PRESETS[flag];
+    }
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+        const response = await prompts({
+            type: 'select',
+            name: 'preset',
+            message: 'Which collection preset?',
+            choices: Object.values(PRESETS).map((p)=>({
+                    title: p.name,
+                    description: p.description,
+                    value: p.name
+                })),
+            initial: Object.keys(PRESETS).indexOf(DEFAULT_PRESET)
+        });
+        // Ctrl+C / escape leaves preset undefined → fall through to the default.
+        if (typeof response.preset === 'string' && Object.hasOwn(PRESETS, response.preset)) {
+            return PRESETS[response.preset];
+        }
+    }
+    return PRESETS[DEFAULT_PRESET];
+}
+/**
+ * Write the scaffold for `preset` into `cwd`. NON-DESTRUCTIVE: an existing file
+ * is left untouched and reported as `skipped` (init never clobbers your code).
+ * Returns the per-target outcome so the command can report it and tests can
+ * assert it. Pure of any console/spinner UI — that lives in the command wrapper.
+ */ async function scaffoldInit(opts) {
+    const files = [];
+    for (const file of buildInitFiles(opts.preset)){
+        const target = path.join(opts.cwd, file.path);
+        if (await fileExists(target)) {
+            files.push({
+                path: file.path,
+                status: 'skipped'
+            });
+            continue;
+        }
+        await mkdir(path.dirname(target), {
+            recursive: true
+        });
+        await writeFile(target, file.content(), 'utf8');
+        files.push({
+            path: file.path,
+            status: 'created'
+        });
+    }
+    return {
+        files,
+        pkg: await patchPackageJson(opts.cwd)
+    };
+}
+/** Add the `cms:generate` script to package.json, if present and not already set. */ async function patchPackageJson(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (!await fileExists(pkgPath)) {
+        return {
+            status: 'skipped',
+            reason: 'no package.json'
+        };
+    }
+    const raw = await readFile(pkgPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return {
+            status: 'skipped',
+            reason: 'package.json is not valid JSON'
+        };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            status: 'skipped',
+            reason: 'package.json is not an object'
+        };
+    }
+    const pkg = parsed;
+    if (pkg.scripts?.[GENERATE_SCRIPT.name]) {
+        return {
+            status: 'skipped',
+            reason: `script "${GENERATE_SCRIPT.name}" exists`
+        };
+    }
+    pkg.scripts = {
+        ...pkg.scripts,
+        [GENERATE_SCRIPT.name]: GENERATE_SCRIPT.command
+    };
+    // Preserve the file's existing indentation (tabs / N spaces) to avoid
+    // reformatting the user's whole package.json into a noisy git diff.
+    const indent = raw.match(/\n([ \t]+)\S/)?.[1] ?? '  ';
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
+    return {
+        status: 'patched'
+    };
+}
+function registerInitCommand(cli) {
+    cli.command('init', 'Scaffold a CMS config, a collection preset, and the Next.js route handler').option('--cwd <dir>', 'Project root to scaffold into (default: cwd)').option('--preset <name>', `Collection preset to scaffold (${Object.keys(PRESETS).join(' | ')})`).action(async (options)=>{
+        const cwd = path.resolve(process.cwd(), options?.cwd ?? '.');
+        const preset = await resolvePreset(options?.preset);
+        const spinner = createSpinner(`Scaffolding the "${preset.name}" preset`);
+        spinner.start();
+        let result;
+        try {
+            result = await scaffoldInit({
+                cwd,
+                preset
+            });
+        } catch (error) {
+            spinner.fail('  Scaffolding failed');
+            throw error;
+        }
+        const created = result.files.filter((f)=>f.status === 'created').length;
+        spinner.succeed(`  Scaffolded ${created} file${created === 1 ? '' : 's'}`);
+        console.log();
+        for (const f of result.files){
+            const tag = f.status === 'created' ? kleur.green('created') : kleur.yellow('exists ');
+            printMeta(tag, kleur.dim(f.path));
+        }
+        const pkgTag = result.pkg.status === 'patched' ? kleur.green('script ') : kleur.yellow('skipped');
+        printMeta(pkgTag, kleur.dim(result.pkg.status === 'patched' ? `package.json → ${GENERATE_SCRIPT.name}` : `package.json (${result.pkg.reason})`));
+        console.log();
+        console.log(`  ${kleur.bold('Next steps')}`);
+        printMeta('1.', 'Provide your Drizzle client at src/lib/db.ts (@/lib/db).');
+        printMeta('2.', 'Set DATABASE_URL + the S3_* vars (see .env.example).');
+        printMeta('3.', `Run "${GENERATE_SCRIPT.command}" to emit the Drizzle schema.`);
+        printMeta('4.', 'Generate + run your migrations (drizzle-kit), then start the app.');
+        console.log();
+    });
+}
+
+const cli = cac('createcms');
+registerInitCommand(cli);
+registerGenerateCommand(cli);
+cli.help();
+cli.version('0.0.1');
+cli.parse(process.argv, {
+    run: false
+});
+const result = cli.runMatchedCommand();
+if (result && typeof result === 'object' && 'then' in result) {
+    result.catch((error)=>{
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    });
+}