@momentumcms/migrations 0.3.0

package/src/lib/runner/push-runner.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Push Mode Runner
+ *
+ * Applies schema changes directly to the database without generating
+ * migration files. Used in development for rapid iteration.
+ *
+ * Flow:
+ * 1. Build desired schema from collections
+ * 2. Introspect actual schema from database
+ * 3. Diff them
+ * 4. Run danger detection
+ * 5. Generate and execute SQL statements
+ */
+import type { CollectionConfig } from '@momentumcms/core';
+import type { DatabaseDialect } from '../schema/column-type-map';
+import type { DatabaseSchemaSnapshot } from '../schema/schema-snapshot';
+import type { SchemaDiffResult } from '../schema/schema-diff';
+import type { DangerDetectionResult } from '../danger/danger-detector';
+/**
+ * Query interface needed by the push runner.
+ */
+export interface PushRunnerDb {
+    executeRaw(sql: string): Promise<number>;
+}
+/**
+ * Options for the push runner.
+ */
+export interface PushRunnerOptions {
+    /** Collections to sync */
+    collections: CollectionConfig[];
+    /** Database dialect */
+    dialect: DatabaseDialect;
+    /** Database query interface */
+    db: PushRunnerDb;
+    /** Function to introspect the current DB schema */
+    introspect: () => Promise<DatabaseSchemaSnapshot>;
+    /** If true, only report what would change without executing */
+    dryRun?: boolean;
+    /** If true, skip danger detection */
+    skipDangerDetection?: boolean;
+    /** Logger */
+    log?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+/**
+ * Result of a push operation.
+ */
+export interface PushResult {
+    /** Whether any changes were applied */
+    applied: boolean;
+    /** The diff result */
+    diff: SchemaDiffResult;
+    /** Danger detection result (null if skipped) */
+    dangers: DangerDetectionResult | null;
+    /** SQL statements that were executed (or would be in dry-run) */
+    sqlStatements: string[];
+    /** Number of successful statements */
+    successCount: number;
+    /** Errors encountered during execution */
+    errors: Array<{
+        sql: string;
+        error: string;
+    }>;
+}
+/**
+ * Run push mode: directly apply schema changes to the database.
+ */
+export declare function runPush(options: PushRunnerOptions): Promise<PushResult>;

package/src/lib/schema/collections-to-schema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Collections-to-Schema Mapper
+ *
+ * Converts Momentum CMS collection configs into a DatabaseSchemaSnapshot.
+ * This represents the "desired" state that the diff engine compares
+ * against the "actual" state from introspection.
+ */
+import type { CollectionConfig } from '@momentumcms/core';
+import type { TableSnapshot, DatabaseSchemaSnapshot } from './schema-snapshot';
+import type { DatabaseDialect } from './column-type-map';
+/**
+ * Convert a single collection config to a TableSnapshot.
+ */
+export declare function collectionToTableSnapshot(collection: CollectionConfig, dialect: DatabaseDialect): TableSnapshot;
+/**
+ * Convert an array of collection configs to a full DatabaseSchemaSnapshot.
+ * This is the "desired" schema that the diff engine compares against.
+ */
+export declare function collectionsToSchema(collections: CollectionConfig[], dialect: DatabaseDialect): DatabaseSchemaSnapshot;

package/src/lib/schema/column-type-map.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Column Type Mapping
+ *
+ * Maps Momentum CMS field types to database column types.
+ * Shared between the migration system and database adapters.
+ */
+import type { Field } from '@momentumcms/core';
+/**
+ * Supported database dialects for column type mapping.
+ */
+export type DatabaseDialect = 'postgresql' | 'sqlite';
+/**
+ * Map a Momentum field type to a PostgreSQL column type.
+ */
+export declare function fieldToPostgresType(field: Field): string;
+/**
+ * Map a Momentum field type to a SQLite column type.
+ */
+export declare function fieldToSqliteType(field: Field): string;
+/**
+ * Map a Momentum field type to a database column type for the given dialect.
+ */
+export declare function fieldToColumnType(field: Field, dialect: DatabaseDialect): string;
+/**
+ * Normalize a raw database type string for reliable comparison.
+ * Handles variations like "character varying(255)" vs "VARCHAR(255)".
+ */
+export declare function normalizeColumnType(rawType: string, dialect: DatabaseDialect): string;
+/**
+ * Check if two column types are compatible (same effective storage).
+ * Used to avoid flagging non-breaking type "changes" as diffs.
+ */
+export declare function areTypesCompatible(typeA: string, typeB: string, dialect: DatabaseDialect): boolean;

package/src/lib/schema/introspect-postgres.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PostgreSQL Schema Introspection
+ *
+ * Reads the current database schema from PostgreSQL system catalogs.
+ * Returns a DatabaseSchemaSnapshot for diffing against collection config.
+ */
+import { type DatabaseSchemaSnapshot } from './schema-snapshot';
+/**
+ * Query function signature — abstracts away the specific database driver.
+ */
+export type QueryFunction = <T extends Record<string, unknown>>(sql: string, params?: unknown[]) => Promise<T[]>;
+/**
+ * Introspect the PostgreSQL database schema.
+ * Queries information_schema and pg_catalog to build a complete snapshot.
+ *
+ * @param queryFn - Function to execute SQL queries (from adapter.queryRaw)
+ * @param schema - PostgreSQL schema name to introspect (default: 'public')
+ */
+export declare function introspectPostgres(queryFn: QueryFunction, schema?: string): Promise<DatabaseSchemaSnapshot>;

package/src/lib/schema/introspect-sqlite.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SQLite Schema Introspection
+ *
+ * Reads the current database schema from SQLite system tables.
+ * Returns a DatabaseSchemaSnapshot for diffing against collection config.
+ */
+import { type DatabaseSchemaSnapshot } from './schema-snapshot';
+/**
+ * Query function for SQLite — all return values must use consistent interface.
+ * SQLite drivers return results synchronously but we use async for adapter compat.
+ */
+export type SqliteQueryFunction = <T extends Record<string, unknown>>(sql: string, params?: unknown[]) => Promise<T[]>;
+/**
+ * Introspect the SQLite database schema.
+ *
+ * @param queryFn - Function to execute SQL queries
+ */
+export declare function introspectSqlite(queryFn: SqliteQueryFunction): Promise<DatabaseSchemaSnapshot>;

package/src/lib/schema/schema-diff.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Schema Diff Engine
+ *
+ * Compares two DatabaseSchemaSnapshots (desired vs actual) and produces
+ * an ordered list of MigrationOperations to reconcile the differences.
+ *
+ * Features:
+ * - Table create/drop detection
+ * - Column add/drop/alter detection
+ * - Type change detection with normalization
+ * - Nullable and default value change detection
+ * - Foreign key add/drop detection
+ * - Index create/drop detection
+ * - Heuristic rename detection (column disappears + new one with compatible type)
+ */
+import type { DatabaseSchemaSnapshot } from './schema-snapshot';
+import type { MigrationOperation } from '../operations/operation.types';
+import type { DatabaseDialect } from './column-type-map';
+/**
+ * Options for the diff engine.
+ */
+export interface SchemaDiffOptions {
+    /**
+     * Enable heuristic rename detection.
+     * When a column disappears and a new one appears with the same type,
+     * suggest a rename instead of drop+add.
+     * @default true
+     */
+    detectRenames?: boolean;
+    /**
+     * Similarity threshold for rename detection (0-1).
+     * Currently unused but reserved for fuzzy name matching.
+     * @default 0.6
+     */
+    renameSimilarityThreshold?: number;
+}
+/**
+ * Result of a schema diff operation.
+ */
+export interface SchemaDiffResult {
+    /** Whether the schemas are identical */
+    hasChanges: boolean;
+    /** Ordered list of operations to apply */
+    operations: MigrationOperation[];
+    /** Summary of changes for human-readable output */
+    summary: string[];
+}
+/**
+ * Diff two schema snapshots and produce migration operations.
+ *
+ * @param desired - The schema we want (from collection configs)
+ * @param actual - The schema we have (from database introspection)
+ * @param dialect - The database dialect for type normalization
+ * @param options - Diff options
+ */
+export declare function diffSchemas(desired: DatabaseSchemaSnapshot, actual: DatabaseSchemaSnapshot, dialect: DatabaseDialect, options?: SchemaDiffOptions): SchemaDiffResult;

package/src/lib/schema/schema-snapshot.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Snapshot of a single database column.
+ */
+export interface ColumnSnapshot {
+    /** Column name */
+    name: string;
+    /** Raw database type (e.g., VARCHAR(36), TEXT, JSONB) */
+    type: string;
+    /** Whether the column accepts NULL */
+    nullable: boolean;
+    /** Default value expression, or null */
+    defaultValue: string | null;
+    /** Whether this column is the primary key */
+    isPrimaryKey: boolean;
+}
+/**
+ * Snapshot of a foreign key constraint.
+ */
+export interface ForeignKeySnapshot {
+    /** Constraint name */
+    constraintName: string;
+    /** Column in the source table */
+    column: string;
+    /** Referenced table */
+    referencedTable: string;
+    /** Referenced column */
+    referencedColumn: string;
+    /** ON DELETE action (CASCADE, SET NULL, RESTRICT, NO ACTION) */
+    onDelete: string;
+}
+/**
+ * Snapshot of a database index.
+ */
+export interface IndexSnapshot {
+    /** Index name */
+    name: string;
+    /** Columns included in the index */
+    columns: string[];
+    /** Whether the index enforces uniqueness */
+    unique: boolean;
+}
+/**
+ * Snapshot of a single database table.
+ */
+export interface TableSnapshot {
+    /** Table name */
+    name: string;
+    /** All columns in the table */
+    columns: ColumnSnapshot[];
+    /** Foreign key constraints */
+    foreignKeys: ForeignKeySnapshot[];
+    /** Indexes (excluding the primary key index) */
+    indexes: IndexSnapshot[];
+}
+/**
+ * Complete snapshot of a database schema.
+ */
+export interface DatabaseSchemaSnapshot {
+    /** Database dialect */
+    dialect: 'postgresql' | 'sqlite';
+    /** All tables in the schema */
+    tables: TableSnapshot[];
+    /** When this snapshot was captured (ISO string) */
+    capturedAt: string;
+    /** SHA-256 checksum of the canonical JSON (for drift detection) */
+    checksum: string;
+}
+/**
+ * Internal tables that should be excluded from schema snapshots.
+ */
+export declare const INTERNAL_TABLES: Set<string>;
+/**
+ * Compute a deterministic SHA-256 checksum for a schema snapshot.
+ * The checksum is computed over the sorted, canonical JSON of tables only
+ * (excluding capturedAt and checksum fields).
+ */
+export declare function computeSchemaChecksum(tables: TableSnapshot[]): string;
+/**
+ * Create a DatabaseSchemaSnapshot from a list of tables.
+ */
+export declare function createSchemaSnapshot(dialect: 'postgresql' | 'sqlite', tables: TableSnapshot[]): DatabaseSchemaSnapshot;
+/**
+ * Serialize a snapshot to JSON string (for .snapshot.json files).
+ */
+export declare function serializeSnapshot(snapshot: DatabaseSchemaSnapshot): string;
+/**
+ * Deserialize a snapshot from a JSON string.
+ */
+export declare function deserializeSnapshot(json: string): DatabaseSchemaSnapshot;

package/src/lib/tracking/migration-tracker.d.ts

@@ -0,0 +1,42 @@
+import type { MigrationTrackingRecord } from '../migration.types';
+import type { DatabaseDialect } from '../schema/column-type-map';
+/**
+ * Database query function type.
+ * Abstracts the adapter's queryRaw / executeRaw methods.
+ */
+export interface TrackerQueryFn {
+    query<T extends Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    execute(sql: string, params?: unknown[]): Promise<number>;
+}
+/**
+ * Ensure the migration tracking table exists.
+ */
+export declare function ensureTrackingTable(db: TrackerQueryFn, dialect: DatabaseDialect): Promise<void>;
+/**
+ * Get all applied migrations, ordered by batch and name.
+ */
+export declare function getAppliedMigrations(db: TrackerQueryFn): Promise<MigrationTrackingRecord[]>;
+/**
+ * Get the next batch number.
+ */
+export declare function getNextBatchNumber(db: TrackerQueryFn): Promise<number>;
+/**
+ * Record a migration as applied.
+ */
+export declare function recordMigration(db: TrackerQueryFn, record: Omit<MigrationTrackingRecord, 'id'>, dialect: DatabaseDialect): Promise<MigrationTrackingRecord>;
+/**
+ * Remove a migration record (for rollbacks).
+ */
+export declare function removeMigrationRecord(db: TrackerQueryFn, name: string, dialect: DatabaseDialect): Promise<boolean>;
+/**
+ * Get migrations from a specific batch (for rollback).
+ */
+export declare function getMigrationsByBatch(db: TrackerQueryFn, batch: number, dialect: DatabaseDialect): Promise<MigrationTrackingRecord[]>;
+/**
+ * Get the latest batch number.
+ */
+export declare function getLatestBatchNumber(db: TrackerQueryFn): Promise<number>;
+/**
+ * Check if a specific migration has been applied.
+ */
+export declare function isMigrationApplied(db: TrackerQueryFn, name: string, dialect: DatabaseDialect): Promise<boolean>;