@momentumcms/migrations 0.3.0 → 0.4.0

package/src/cli/run.js

@@ -0,0 +1,1097 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// libs/migrations/src/cli/run.ts
+import { resolve } from "node:path";
+
+// libs/core/src/lib/collections/define-collection.ts
+function defineCollection(config) {
+  const collection = {
+    timestamps: true,
+    // Enable timestamps by default
+    ...config
+  };
+  if (!collection.slug) {
+    throw new Error("Collection must have a slug");
+  }
+  if (!collection.fields || collection.fields.length === 0) {
+    throw new Error(`Collection "${collection.slug}" must have at least one field`);
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(collection.slug)) {
+    throw new Error(
+      `Collection slug "${collection.slug}" must be kebab-case (lowercase letters, numbers, and hyphens, starting with a letter)`
+    );
+  }
+  return collection;
+}
+
+// libs/core/src/lib/fields/field-builders.ts
+function text(name, options = {}) {
+  return {
+    name,
+    type: "text",
+    ...options
+  };
+}
+function number(name, options = {}) {
+  return {
+    name,
+    type: "number",
+    ...options
+  };
+}
+function json(name, options = {}) {
+  return {
+    name,
+    type: "json",
+    ...options
+  };
+}
+
+// libs/core/src/lib/collections/media.collection.ts
+var MediaCollection = defineCollection({
+  slug: "media",
+  labels: {
+    singular: "Media",
+    plural: "Media"
+  },
+  upload: {
+    mimeTypes: ["image/*", "application/pdf", "video/*", "audio/*"]
+  },
+  admin: {
+    useAsTitle: "filename",
+    defaultColumns: ["filename", "mimeType", "filesize", "createdAt"]
+  },
+  fields: [
+    text("filename", {
+      required: true,
+      label: "Filename",
+      description: "Original filename of the uploaded file"
+    }),
+    text("mimeType", {
+      required: true,
+      label: "MIME Type",
+      description: "File MIME type (e.g., image/jpeg, application/pdf)"
+    }),
+    number("filesize", {
+      label: "File Size",
+      description: "File size in bytes"
+    }),
+    text("path", {
+      label: "Storage Path",
+      description: "Path/key where the file is stored",
+      admin: {
+        hidden: true
+      }
+    }),
+    text("url", {
+      label: "URL",
+      description: "Public URL to access the file"
+    }),
+    text("alt", {
+      label: "Alt Text",
+      description: "Alternative text for accessibility"
+    }),
+    number("width", {
+      label: "Width",
+      description: "Image width in pixels (for images only)"
+    }),
+    number("height", {
+      label: "Height",
+      description: "Image height in pixels (for images only)"
+    }),
+    json("focalPoint", {
+      label: "Focal Point",
+      description: "Focal point coordinates for image cropping",
+      admin: {
+        hidden: true
+      }
+    })
+  ],
+  access: {
+    // Media is readable by anyone by default
+    read: () => true,
+    // Only authenticated users can create/update/delete
+    create: ({ req }) => !!req?.user,
+    update: ({ req }) => !!req?.user,
+    delete: ({ req }) => !!req?.user
+  }
+});
+
+// libs/core/src/lib/migrations.ts
+function resolveMigrationMode(mode) {
+  if (mode === "push" || mode === "migrate")
+    return mode;
+  const env = process.env["NODE_ENV"];
+  if (env === "production")
+    return "migrate";
+  return "push";
+}
+function resolveMigrationConfig(config) {
+  if (!config)
+    return void 0;
+  const mode = resolveMigrationMode(config.mode);
+  return {
+    ...config,
+    directory: config.directory ?? "./migrations",
+    mode,
+    cloneTest: config.cloneTest ?? mode === "migrate",
+    dangerDetection: config.dangerDetection ?? true,
+    autoApply: config.autoApply ?? mode === "push"
+  };
+}
+
+// libs/migrations/src/lib/loader/migration-loader.ts
+import { readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+var MIGRATION_FILE_PATTERN = /^\d{14}_.+\.ts$/;
+function isMigrationFile(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const obj = value;
+  return "meta" in obj && typeof obj["meta"] === "object" && obj["meta"] !== null && "up" in obj && typeof obj["up"] === "function" && "down" in obj && typeof obj["down"] === "function";
+}
+function validateMigrationModule(mod, filePath) {
+  const file = mod["default"] ?? mod;
+  if (!isMigrationFile(file)) {
+    if (typeof file !== "object" || file === null) {
+      throw new Error(`Migration file ${filePath} does not export a valid module`);
+    }
+    if (!("meta" in file) || typeof file["meta"] !== "object") {
+      throw new Error(`Migration file ${filePath} is missing a valid 'meta' export`);
+    }
+    if (!("up" in file) || typeof file["up"] !== "function") {
+      throw new Error(`Migration file ${filePath} is missing an 'up' function export`);
+    }
+    if (!("down" in file) || typeof file["down"] !== "function") {
+      throw new Error(`Migration file ${filePath} is missing a 'down' function export`);
+    }
+    throw new Error(`Migration file ${filePath} does not conform to MigrationFile interface`);
+  }
+  return file;
+}
+async function loadMigrationsFromDisk(directory) {
+  if (!existsSync(directory))
+    return [];
+  const files = readdirSync(directory).filter((f) => MIGRATION_FILE_PATTERN.test(f)).sort();
+  if (files.length === 0)
+    return [];
+  const migrations = [];
+  for (const filename of files) {
+    const filePath = join(directory, filename);
+    const fileUrl = pathToFileURL(filePath).href;
+    const mod = await import(fileUrl);
+    const file = validateMigrationModule(mod, filePath);
+    const name = filename.replace(/\.ts$/, "");
+    migrations.push({ name, file });
+  }
+  return migrations;
+}
+
+// libs/migrations/src/lib/migration.types.ts
+var MIGRATION_TRACKING_TABLE = "_momentum_migrations";
+
+// libs/migrations/src/lib/tracking/migration-tracker.ts
+async function ensureTrackingTable(db, dialect) {
+  if (dialect === "postgresql") {
+    await db.execute(`
+			CREATE TABLE IF NOT EXISTS "${MIGRATION_TRACKING_TABLE}" (
+				"id" VARCHAR(36) PRIMARY KEY,
+				"name" VARCHAR(255) NOT NULL UNIQUE,
+				"batch" INTEGER NOT NULL,
+				"checksum" VARCHAR(64) NOT NULL,
+				"appliedAt" TIMESTAMPTZ NOT NULL,
+				"executionMs" INTEGER NOT NULL
+			)
+		`);
+  } else {
+    await db.execute(`
+			CREATE TABLE IF NOT EXISTS "${MIGRATION_TRACKING_TABLE}" (
+				"id" TEXT PRIMARY KEY,
+				"name" TEXT NOT NULL UNIQUE,
+				"batch" INTEGER NOT NULL,
+				"checksum" TEXT NOT NULL,
+				"appliedAt" TEXT NOT NULL,
+				"executionMs" INTEGER NOT NULL
+			)
+		`);
+  }
+}
+async function getAppliedMigrations(db) {
+  const rows = await db.query(
+    `SELECT * FROM "${MIGRATION_TRACKING_TABLE}" ORDER BY "batch" ASC, "name" ASC`
+  );
+  return rows.map(toTrackingRecord);
+}
+async function getNextBatchNumber(db) {
+  const rows = await db.query(
+    `SELECT MAX("batch") as max_batch FROM "${MIGRATION_TRACKING_TABLE}"`
+  );
+  const maxBatch = rows[0]?.max_batch;
+  return (typeof maxBatch === "number" ? maxBatch : 0) + 1;
+}
+async function recordMigration(db, record, dialect) {
+  const id = generateUUID();
+  const full = { id, ...record };
+  if (dialect === "postgresql") {
+    await db.execute(
+      `INSERT INTO "${MIGRATION_TRACKING_TABLE}" ("id", "name", "batch", "checksum", "appliedAt", "executionMs")
+			 VALUES ($1, $2, $3, $4, $5, $6)`,
+      [full.id, full.name, full.batch, full.checksum, full.appliedAt, full.executionMs]
+    );
+  } else {
+    await db.execute(
+      `INSERT INTO "${MIGRATION_TRACKING_TABLE}" ("id", "name", "batch", "checksum", "appliedAt", "executionMs")
+			 VALUES (?, ?, ?, ?, ?, ?)`,
+      [full.id, full.name, full.batch, full.checksum, full.appliedAt, full.executionMs]
+    );
+  }
+  return full;
+}
+function toTrackingRecord(row2) {
+  return {
+    id: String(row2["id"]),
+    name: String(row2["name"]),
+    batch: Number(row2["batch"]),
+    checksum: String(row2["checksum"]),
+    appliedAt: String(row2["appliedAt"]),
+    executionMs: Number(row2["executionMs"])
+  };
+}
+function generateUUID() {
+  const crypto = __require("node:crypto");
+  return crypto.randomUUID();
+}
+
+// libs/migrations/src/lib/danger/danger-detector.ts
+function detectDangers(operations, dialect) {
+  const warnings = [];
+  for (let i = 0; i < operations.length; i++) {
+    const op = operations[i];
+    warnings.push(...checkOperation(op, i, operations, dialect));
+  }
+  const severityOrder = { error: 0, warning: 1, info: 2 };
+  warnings.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+  return {
+    warnings,
+    hasErrors: warnings.some((w) => w.severity === "error"),
+    hasWarnings: warnings.some((w) => w.severity === "warning")
+  };
+}
+function checkOperation(op, index, _allOps, dialect) {
+  const warnings = [];
+  switch (op.type) {
+    case "dropTable":
+      warnings.push({
+        severity: "error",
+        operation: op,
+        operationIndex: index,
+        message: `Dropping table "${op.table}" will permanently delete all data.`,
+        suggestion: 'Consider renaming the table with a deprecation prefix (e.g., "_deprecated_") and scheduling deletion after verifying no data is needed.'
+      });
+      break;
+    case "dropColumn":
+      warnings.push({
+        severity: "warning",
+        operation: op,
+        operationIndex: index,
+        message: `Dropping column "${op.table}"."${op.column}" will permanently delete all values in this column.`,
+        suggestion: "Before dropping, verify the column data is either migrated elsewhere or truly unneeded. Consider a backup or data export first."
+      });
+      break;
+    case "alterColumnType":
+      warnings.push(...checkTypeChange(op, index, dialect));
+      break;
+    case "alterColumnNullable":
+      if (!op.nullable) {
+        warnings.push({
+          severity: "warning",
+          operation: op,
+          operationIndex: index,
+          message: `Setting "${op.table}"."${op.column}" to NOT NULL may fail if existing rows contain NULL values.`,
+          suggestion: "First backfill NULL values with a default (e.g., UPDATE table SET column = 'default' WHERE column IS NULL), then add the NOT NULL constraint."
+        });
+      }
+      break;
+    case "addColumn":
+      if (!op.nullable && !op.defaultValue) {
+        warnings.push({
+          severity: "error",
+          operation: op,
+          operationIndex: index,
+          message: `Adding NOT NULL column "${op.table}"."${op.column}" without a default value will fail if the table has existing rows.`,
+          suggestion: "Either add a DEFAULT value, make the column nullable first and backfill, or add the column as nullable, backfill, then alter to NOT NULL."
+        });
+      }
+      break;
+    case "renameColumn":
+      warnings.push({
+        severity: "warning",
+        operation: op,
+        operationIndex: index,
+        message: `Renaming "${op.table}"."${op.from}" to "${op.to}" may break application code that references the old name.`,
+        suggestion: "Deploy application code changes to use the new column name before or alongside the migration. Consider a phased approach: add new column, migrate data, update code, then drop old column."
+      });
+      break;
+    case "renameTable":
+      warnings.push({
+        severity: "warning",
+        operation: op,
+        operationIndex: index,
+        message: `Renaming table "${op.from}" to "${op.to}" may break application code and queries.`,
+        suggestion: "Update application code to use the new table name before or alongside the migration."
+      });
+      break;
+    case "addForeignKey":
+      if (dialect === "postgresql") {
+        warnings.push({
+          severity: "info",
+          operation: op,
+          operationIndex: index,
+          message: `Adding foreign key "${op.constraintName}" acquires an ACCESS EXCLUSIVE lock on the referenced table.`,
+          suggestion: "On large tables, consider adding the FK constraint with NOT VALID first, then validating separately: ALTER TABLE ... ADD CONSTRAINT ... NOT VALID; ALTER TABLE ... VALIDATE CONSTRAINT ..."
+        });
+      }
+      break;
+    case "createIndex":
+      if (dialect === "postgresql" && !isCreateIndexConcurrent(op)) {
+        warnings.push({
+          severity: "info",
+          operation: op,
+          operationIndex: index,
+          message: `Creating index "${op.indexName}" will lock "${op.table}" for writes during index creation.`,
+          suggestion: "For large tables, consider CREATE INDEX CONCURRENTLY to avoid blocking writes (requires running outside a transaction)."
+        });
+      }
+      break;
+  }
+  return warnings;
+}
+function checkTypeChange(op, index, dialect) {
+  const warnings = [];
+  if (dialect === "sqlite") {
+    warnings.push({
+      severity: "error",
+      operation: op,
+      operationIndex: index,
+      message: `SQLite does not support ALTER COLUMN TYPE. Changing "${op.table}"."${op.column}" from ${op.fromType} to ${op.toType} requires a table rebuild.`,
+      suggestion: "Create a new table with the desired schema, copy data, drop old table, and rename new table. Use a raw SQL migration for this."
+    });
+    return warnings;
+  }
+  if (isLossyTypeChange(op.fromType, op.toType)) {
+    warnings.push({
+      severity: "warning",
+      operation: op,
+      operationIndex: index,
+      message: `Changing "${op.table}"."${op.column}" from ${op.fromType} to ${op.toType} may cause data loss or cast errors.`,
+      suggestion: "Test the type conversion on a clone database first. Consider adding a USING clause with explicit cast logic."
+    });
+  }
+  if (isTableRewriteType(op.fromType, op.toType)) {
+    warnings.push({
+      severity: "info",
+      operation: op,
+      operationIndex: index,
+      message: `Changing "${op.table}"."${op.column}" from ${op.fromType} to ${op.toType} may require a table rewrite on large tables.`,
+      suggestion: "On large tables, this can take significant time and lock the table. Consider running during low-traffic periods or using a phased approach."
+    });
+  }
+  return warnings;
+}
+function isLossyTypeChange(from, to) {
+  const fromUpper = from.toUpperCase();
+  const toUpper = to.toUpperCase();
+  if (isTextType(fromUpper) && isNumericType(toUpper))
+    return true;
+  if (fromUpper === "NUMERIC" && (toUpper === "INTEGER" || toUpper === "SMALLINT"))
+    return true;
+  if (fromUpper === "BIGINT" && (toUpper === "INTEGER" || toUpper === "SMALLINT"))
+    return true;
+  if (fromUpper === "DOUBLE PRECISION" && toUpper === "REAL")
+    return true;
+  if ((fromUpper === "JSONB" || fromUpper === "JSON") && !fromUpper.includes("JSON"))
+    return true;
+  if (fromUpper.includes("TIMESTAMP") && toUpper === "DATE")
+    return true;
+  const fromLength = extractLength(fromUpper);
+  const toLength = extractLength(toUpper);
+  if (fromLength && toLength && toLength < fromLength)
+    return true;
+  return false;
+}
+function isTableRewriteType(from, to) {
+  const fromUpper = from.toUpperCase();
+  const toUpper = to.toUpperCase();
+  if (fromUpper.startsWith("VARCHAR") && toUpper === "TEXT")
+    return false;
+  if (fromUpper === "TEXT" && toUpper.startsWith("VARCHAR"))
+    return true;
+  if (isNumericType(fromUpper) !== isNumericType(toUpper))
+    return true;
+  return false;
+}
+function isTextType(type) {
+  return type === "TEXT" || type.startsWith("VARCHAR") || type.startsWith("CHAR");
+}
+function isNumericType(type) {
+  return ["INTEGER", "BIGINT", "SMALLINT", "NUMERIC", "REAL", "DOUBLE PRECISION", "FLOAT"].includes(
+    type
+  );
+}
+function extractLength(type) {
+  const match = type.match(/\((\d+)\)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+function isCreateIndexConcurrent(_op) {
+  return false;
+}
+
+// libs/migrations/src/lib/runner/migrate-runner.ts
+import { createHash } from "node:crypto";
+async function runMigrations(options) {
+  const { migrations, dialect, tracker, buildContext, skipDangerDetection, log } = options;
+  const noop = {
+    info: () => {
+    },
+    warn: () => {
+    }
+  };
+  const logger = log ?? noop;
+  await ensureTrackingTable(tracker, dialect);
+  const applied = await getAppliedMigrations(tracker);
+  const appliedNames = new Set(applied.map((m) => m.name));
+  const pending = migrations.filter((m) => !appliedNames.has(m.name));
+  if (pending.length === 0) {
+    logger.info("No pending migrations.");
+    return {
+      batch: 0,
+      results: [],
+      successCount: 0,
+      failCount: 0,
+      dangers: null
+    };
+  }
+  let dangers = null;
+  if (!skipDangerDetection) {
+    const allOps = pending.flatMap((m) => {
+      const ops = m.file.meta.operations;
+      if (!ops)
+        return [];
+      return ops.filter((op) => typeof op.type === "string").map(toMigrationOperation);
+    });
+    if (allOps.length > 0) {
+      dangers = detectDangers(allOps, dialect);
+      if (dangers.hasErrors) {
+        logger.warn("Dangerous operations detected. Migration blocked.");
+        return {
+          batch: 0,
+          results: [],
+          successCount: 0,
+          failCount: 0,
+          dangers
+        };
+      }
+    }
+  }
+  const batch = await getNextBatchNumber(tracker);
+  logger.info(`Running ${pending.length} migration(s) in batch ${batch}...`);
+  const results = [];
+  const ctx = buildContext();
+  for (const migration of pending) {
+    const start = Date.now();
+    try {
+      await migration.file.up(ctx);
+      const executionMs = Date.now() - start;
+      const checksum = computeMigrationChecksum(migration);
+      await recordMigration(
+        tracker,
+        {
+          name: migration.name,
+          batch,
+          checksum,
+          appliedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          executionMs
+        },
+        dialect
+      );
+      results.push({ name: migration.name, success: true, executionMs });
+      logger.info(`  OK: ${migration.name} (${executionMs}ms)`);
+    } catch (err) {
+      const executionMs = Date.now() - start;
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const errorCode = extractErrorCode(err);
+      results.push({ name: migration.name, success: false, executionMs, error: errMsg, errorCode });
+      logger.warn(`  FAILED: ${migration.name} \u2014 ${errMsg}`);
+      break;
+    }
+  }
+  const successCount = results.filter((r) => r.success).length;
+  const failCount = results.filter((r) => !r.success).length;
+  logger.info(`Batch ${batch}: ${successCount} applied, ${failCount} failed.`);
+  return { batch, results, successCount, failCount, dangers };
+}
+function extractErrorCode(err) {
+  if (err !== null && typeof err === "object" && "code" in err && typeof err.code === "string") {
+    return err.code;
+  }
+  return void 0;
+}
+function toMigrationOperation(op) {
+  return op;
+}
+function computeMigrationChecksum(migration) {
+  const content = JSON.stringify(migration.file.meta) + migration.file.up.toString() + migration.file.down.toString();
+  return createHash("sha256").update(content).digest("hex");
+}
+
+// libs/migrations/src/lib/runner/clone-test-apply.ts
+async function cloneTestApply(options) {
+  const {
+    migrations,
+    dialect,
+    tracker,
+    buildContext,
+    db,
+    buildCloneTracker,
+    buildCloneContext,
+    testOnly,
+    skipDangerDetection,
+    log
+  } = options;
+  const noop = { info: () => {
+  }, warn: () => {
+  } };
+  const logger = log ?? noop;
+  const timestamp = Date.now();
+  const cloneName = `_mig_clone_${timestamp}`;
+  let cloneCleanedUp = false;
+  const result = {
+    phase: "clone",
+    cloneResult: null,
+    applyResult: null,
+    dangers: null,
+    cloneCleanedUp: false,
+    cloneName,
+    suggestions: []
+  };
+  try {
+    logger.info(`Cloning database to "${cloneName}"...`);
+    await db.cloneDatabase(cloneName);
+    logger.info("Clone created successfully.");
+    result.phase = "test";
+    logger.info("Running migrations on clone...");
+    const cloneTracker = buildCloneTracker(cloneName);
+    const cloneContext = buildCloneContext(cloneName);
+    const cloneResult = await runMigrations({
+      migrations,
+      dialect,
+      tracker: cloneTracker,
+      buildContext: () => cloneContext,
+      skipDangerDetection,
+      log: {
+        info: (msg) => logger.info(`[clone] ${msg}`),
+        warn: (msg) => logger.warn(`[clone] ${msg}`)
+      }
+    });
+    result.cloneResult = cloneResult;
+    result.dangers = cloneResult.dangers;
+    if (cloneResult.failCount > 0) {
+      const suggestions = generateFixSuggestions(cloneResult);
+      result.suggestions = suggestions;
+      result.error = `Migration failed on clone: ${cloneResult.results.find((r) => !r.success)?.error}`;
+      logger.warn("Migration failed on clone. Suggestions:");
+      for (const suggestion of suggestions) {
+        logger.warn(`  - ${suggestion}`);
+      }
+      await cleanupClone(db, cloneName, logger);
+      result.cloneCleanedUp = true;
+      cloneCleanedUp = true;
+      return result;
+    }
+    logger.info(`Clone test passed: ${cloneResult.successCount} migration(s) applied.`);
+    await cleanupClone(db, cloneName, logger);
+    result.cloneCleanedUp = true;
+    cloneCleanedUp = true;
+    if (testOnly) {
+      result.phase = "skipped";
+      logger.info("Test-only mode: skipping real database apply.");
+      return result;
+    }
+    result.phase = "apply";
+    logger.info("Applying migrations to real database...");
+    const applyResult = await runMigrations({
+      migrations,
+      dialect,
+      tracker,
+      buildContext,
+      skipDangerDetection: true,
+      // Already validated on clone
+      log: logger
+    });
+    result.applyResult = applyResult;
+    if (applyResult.failCount > 0) {
+      result.error = `Migration failed on real database: ${applyResult.results.find((r) => !r.success)?.error}`;
+      return result;
+    }
+    result.phase = "complete";
+    logger.info(
+      `Pipeline complete: ${applyResult.successCount} migration(s) applied to real database.`
+    );
+    return result;
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    result.error = errMsg;
+    logger.warn(`Pipeline error: ${errMsg}`);
+    if (!cloneCleanedUp) {
+      await cleanupClone(db, cloneName, logger);
+      result.cloneCleanedUp = true;
+    }
+    return result;
+  }
+}
+async function cleanupClone(db, cloneName, logger) {
+  try {
+    await db.dropClone(cloneName);
+    logger.info(`Clone "${cloneName}" cleaned up.`);
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    logger.warn(`Failed to clean up clone "${cloneName}": ${errMsg}`);
+  }
+}
+var SQLSTATE_SUGGESTIONS = {
+  // Class 23 — Integrity Constraint Violation
+  "23502": "NOT NULL constraint violation. Backfill NULL values before adding the constraint: Use ctx.data.backfill(table, column, defaultValue) in a prior migration step.",
+  "23505": "Unique constraint violation. Use ctx.data.dedup() to remove duplicates before adding the unique constraint.",
+  "23503": "Foreign key constraint violation. Ensure referenced data exists before adding the constraint. Consider using ctx.data.backfill() to populate references, or add the FK with NOT VALID first.",
+  // Class 42 — Syntax Error or Access Rule Violation
+  "42P07": "The table already exists. Check if a previous migration already created it, or use IF NOT EXISTS in your DDL.",
+  "42701": "The column already exists. Check if a previous migration already created it, or use IF NOT EXISTS in your DDL.",
+  "42P01": "Referenced table does not exist. Check migration ordering \u2014 the table must be created before it can be referenced.",
+  "42703": "Referenced column does not exist. Check migration ordering \u2014 the column must be created before it can be referenced.",
+  // Class 22 — Data Exception
+  "22P02": "Type conversion error. The data contains values that cannot be converted to the target type. Use ctx.data.transform() to clean up values before altering the column type.",
+  "42804": "Type conversion error. Add an explicit USING clause for the type change, or use ctx.data.transform() to convert values before altering the column type."
+};
+function generateFixSuggestions(result) {
+  const suggestions = [];
+  const failedMigration = result.results.find((r) => !r.success);
+  if (!failedMigration)
+    return suggestions;
+  if (failedMigration.errorCode) {
+    const codeSuggestion = SQLSTATE_SUGGESTIONS[failedMigration.errorCode];
+    if (codeSuggestion) {
+      suggestions.push(codeSuggestion);
+      return suggestions;
+    }
+  }
+  const error = failedMigration.error ?? "";
+  if (error.includes("NOT NULL") && error.includes("contains null")) {
+    suggestions.push(
+      "Backfill NULL values before adding NOT NULL constraint: Use ctx.data.backfill(table, column, defaultValue) in a prior migration step."
+    );
+  }
+  if (error.includes("already exists")) {
+    suggestions.push(
+      "The column or table already exists. Check if a previous migration already created it, or use IF NOT EXISTS in your DDL."
+    );
+  }
+  if (error.includes("violates foreign key")) {
+    suggestions.push(
+      "Foreign key constraint violation. Ensure referenced data exists before adding the constraint. Consider using ctx.data.backfill() to populate references, or add the FK with NOT VALID first."
+    );
+  }
+  if (error.includes("does not exist")) {
+    suggestions.push(
+      "Referenced table or column does not exist. Check migration ordering \u2014 the table/column must be created before it can be referenced."
+    );
+  }
+  if (error.includes("unique constraint") || error.includes("duplicate key")) {
+    suggestions.push(
+      "Unique constraint violation. Use ctx.data.dedup() to remove duplicates before adding the unique constraint."
+    );
+  }
+  if (error.includes("type") && (error.includes("cast") || error.includes("convert"))) {
+    suggestions.push(
+      "Type conversion error. Add an explicit USING clause for the type change, or use ctx.data.transform() to convert values before altering the column type."
+    );
+  }
+  if (suggestions.length === 0) {
+    suggestions.push(
+      `Migration "${failedMigration.name}" failed with: ${error}. Review the migration SQL and test on a development database.`
+    );
+  }
+  return suggestions;
+}
+
+// libs/migrations/src/cli/shared.ts
+import { pathToFileURL as pathToFileURL2 } from "node:url";
+
+// libs/migrations/src/lib/helpers/data-helpers.ts
+function createDataHelpers(db, dialect) {
+  const ph = (index) => dialect === "postgresql" ? `$${index}` : "?";
+  return {
+    async backfill(table, column, value, options) {
+      const where = options?.where ? ` AND (${options.where})` : "";
+      const batchSize = options?.batchSize ?? 1e3;
+      let totalAffected = 0;
+      if (dialect === "postgresql") {
+        let affected;
+        do {
+          affected = await db.execute(
+            `UPDATE "${table}" SET "${column}" = ${ph(1)}
+						 WHERE ctid IN (
+							SELECT ctid FROM "${table}"
+							WHERE "${column}" IS NULL${where}
+							LIMIT ${batchSize}
+						 )`,
+            [value]
+          );
+          totalAffected += affected;
+        } while (affected >= batchSize);
+      } else {
+        let affected;
+        do {
+          affected = await db.execute(
+            `UPDATE "${table}" SET "${column}" = ${ph(1)}
+						 WHERE rowid IN (
+							SELECT rowid FROM "${table}"
+							WHERE "${column}" IS NULL${where}
+							LIMIT ${batchSize}
+						 )`,
+            [value]
+          );
+          totalAffected += affected;
+        } while (affected >= batchSize);
+      }
+      return totalAffected;
+    },
+    async transform(table, column, sqlExpression, options) {
+      const where = options?.where ? ` WHERE ${options.where}` : "";
+      const batchSize = options?.batchSize ?? 0;
+      if (batchSize <= 0) {
+        return db.execute(
+          `UPDATE "${table}" SET "${column}" = ${sqlExpression}${where}`
+        );
+      }
+      let totalAffected = 0;
+      let affected;
+      do {
+        if (dialect === "postgresql") {
+          affected = await db.execute(
+            `UPDATE "${table}" SET "${column}" = ${sqlExpression}
+						 WHERE ctid IN (
+							SELECT ctid FROM "${table}"${where}
+							LIMIT ${batchSize}
+						 )`
+          );
+        } else {
+          affected = await db.execute(
+            `UPDATE "${table}" SET "${column}" = ${sqlExpression}
+						 WHERE rowid IN (
+							SELECT rowid FROM "${table}"${where}
+							LIMIT ${batchSize}
+						 )`
+          );
+        }
+        totalAffected += affected;
+      } while (affected >= batchSize);
+      return totalAffected;
+    },
+    async renameColumn(table, from, to, columnType) {
+      await db.execute(
+        `ALTER TABLE "${table}" ADD COLUMN "${to}" ${columnType}`
+      );
+      await db.execute(
+        `UPDATE "${table}" SET "${to}" = "${from}"`
+      );
+      await db.execute(
+        `ALTER TABLE "${table}" DROP COLUMN "${from}"`
+      );
+    },
+    async splitColumn(table, _sourceColumn, targets) {
+      for (const target of targets) {
+        await db.execute(
+          `ALTER TABLE "${table}" ADD COLUMN "${target.name}" ${target.type}`
+        );
+        await db.execute(
+          `UPDATE "${table}" SET "${target.name}" = ${target.expression}`
+        );
+      }
+    },
+    async mergeColumns(table, _sourceColumns, targetColumn, targetType, mergeExpression) {
+      await db.execute(
+        `ALTER TABLE "${table}" ADD COLUMN "${targetColumn}" ${targetType}`
+      );
+      await db.execute(
+        `UPDATE "${table}" SET "${targetColumn}" = ${mergeExpression}`
+      );
+    },
+    async copyData(sourceTable, targetTable, columnMapping, options) {
+      const targetCols = [];
+      const sourceCols = [];
+      for (const [target, source] of Object.entries(columnMapping)) {
+        targetCols.push(`"${target}"`);
+        if (typeof source === "string") {
+          sourceCols.push(`"${source}"`);
+        } else {
+          sourceCols.push(source.expression);
+        }
+      }
+      const where = options?.where ? ` WHERE ${options.where}` : "";
+      const affected = await db.execute(
+        `INSERT INTO "${targetTable}" (${targetCols.join(", ")})
+				 SELECT ${sourceCols.join(", ")} FROM "${sourceTable}"${where}`
+      );
+      return affected;
+    },
+    async columnToJson(table, sourceColumn, jsonColumn, jsonKey) {
+      if (dialect === "postgresql") {
+        await db.execute(
+          `UPDATE "${table}" SET "${jsonColumn}" = COALESCE("${jsonColumn}", '{}'::jsonb) || jsonb_build_object('${jsonKey}', "${sourceColumn}")`
+        );
+      } else {
+        await db.execute(
+          `UPDATE "${table}" SET "${jsonColumn}" = json_set(COALESCE("${jsonColumn}", '{}'), '$.${jsonKey}', "${sourceColumn}")`
+        );
+      }
+    },
+    async jsonToColumn(table, jsonColumn, jsonKey, targetColumn, targetType) {
+      await db.execute(
+        `ALTER TABLE "${table}" ADD COLUMN "${targetColumn}" ${targetType}`
+      );
+      if (dialect === "postgresql") {
+        await db.execute(
+          `UPDATE "${table}" SET "${targetColumn}" = "${jsonColumn}"->>'${jsonKey}'`
+        );
+      } else {
+        await db.execute(
+          `UPDATE "${table}" SET "${targetColumn}" = json_extract("${jsonColumn}", '$.${jsonKey}')`
+        );
+      }
+    },
+    async dedup(table, columns, keepStrategy = "latest") {
+      const colList = columns.map((c) => `"${c}"`).join(", ");
+      let orderBy;
+      switch (keepStrategy) {
+        case "earliest":
+          orderBy = '"createdAt" ASC';
+          break;
+        case "first":
+          orderBy = dialect === "postgresql" ? "ctid ASC" : "rowid ASC";
+          break;
+        default:
+          orderBy = '"createdAt" DESC';
+          break;
+      }
+      if (dialect === "postgresql") {
+        return db.execute(
+          `DELETE FROM "${table}" WHERE ctid NOT IN (
+						SELECT DISTINCT ON (${colList}) ctid
+						FROM "${table}"
+						ORDER BY ${colList}, ${orderBy}
+					)`
+        );
+      }
+      return db.execute(
+        `DELETE FROM "${table}" WHERE rowid NOT IN (
+					SELECT MIN(rowid) FROM "${table}"
+					GROUP BY ${colList}
+				)`
+      );
+    }
+  };
+}
+
+// libs/migrations/src/cli/shared.ts
+function isResolvedConfig(value) {
+  return typeof value === "object" && value !== null && "collections" in value && "db" in value;
+}
+async function loadMomentumConfig(configPath) {
+  const configUrl = pathToFileURL2(configPath).href;
+  const mod = await import(configUrl);
+  const raw = mod["default"] ?? mod;
+  if (!isResolvedConfig(raw)) {
+    throw new Error(`Config at ${configPath} is not a valid ResolvedMomentumConfig`);
+  }
+  if (!raw.db?.adapter) {
+    throw new Error(`Config at ${configPath} is missing db.adapter`);
+  }
+  if (!raw.collections || raw.collections.length === 0) {
+    throw new Error(`Config at ${configPath} has no collections`);
+  }
+  return raw;
+}
+function resolveDialect(adapter) {
+  if (!adapter.dialect) {
+    throw new Error(
+      "DatabaseAdapter.dialect is not set. Ensure your adapter factory (postgresAdapter/sqliteAdapter) sets the dialect property."
+    );
+  }
+  return adapter.dialect;
+}
+function buildTrackerFromAdapter(adapter) {
+  if (!adapter.queryRaw || !adapter.executeRaw) {
+    throw new Error("DatabaseAdapter must implement queryRaw and executeRaw for migration tracking");
+  }
+  const queryRaw = adapter.queryRaw.bind(adapter);
+  const executeRaw = adapter.executeRaw.bind(adapter);
+  return {
+    async query(sql, params) {
+      return queryRaw(sql, params);
+    },
+    async execute(sql, params) {
+      return executeRaw(sql, params);
+    }
+  };
+}
+function buildContextFromAdapter(adapter, dialect) {
+  if (!adapter.queryRaw || !adapter.executeRaw) {
+    throw new Error("DatabaseAdapter must implement queryRaw and executeRaw for migration context");
+  }
+  const queryRaw = adapter.queryRaw.bind(adapter);
+  const executeRaw = adapter.executeRaw.bind(adapter);
+  const dataDb = {
+    async execute(sql, params) {
+      return executeRaw(sql, params);
+    },
+    async query(sql, params) {
+      return queryRaw(sql, params);
+    }
+  };
+  const helpers = createDataHelpers(dataDb, dialect);
+  return {
+    async sql(query, params) {
+      await executeRaw(query, params);
+    },
+    async query(sql, params) {
+      return queryRaw(sql, params);
+    },
+    data: helpers,
+    dialect,
+    log: {
+      info: (msg) => {
+        console.warn(`[migration] ${msg}`);
+      },
+      warn: (msg) => {
+        console.warn(`[migration:warn] ${msg}`);
+      }
+    }
+  };
+}
+function buildCloneDbFromAdapter(adapter) {
+  if (!adapter.cloneDatabase || !adapter.dropClone) {
+    throw new Error("DatabaseAdapter must implement cloneDatabase and dropClone for clone-test-apply");
+  }
+  return {
+    cloneDatabase: adapter.cloneDatabase.bind(adapter),
+    dropClone: adapter.dropClone.bind(adapter)
+  };
+}
+function parseMigrationArgs(args) {
+  const configPath = args.find((a) => !a.startsWith("--"));
+  if (!configPath) {
+    throw new Error("Usage: npx tsx <command>.ts <configPath> [options]");
+  }
+  let name;
+  const nameIdx = args.indexOf("--name");
+  if (nameIdx !== -1 && args[nameIdx + 1]) {
+    name = args[nameIdx + 1];
+  }
+  return {
+    configPath,
+    name,
+    dryRun: args.includes("--dry-run"),
+    testOnly: args.includes("--test-only"),
+    skipCloneTest: args.includes("--skip-clone-test")
+  };
+}
+
+// libs/migrations/src/cli/run.ts
+async function main() {
+  const args = parseMigrationArgs(process.argv.slice(2));
+  const config = await loadMomentumConfig(resolve(args.configPath));
+  const adapter = config.db.adapter;
+  const dialect = resolveDialect(adapter);
+  const migrationConfig = resolveMigrationConfig(config.migrations ?? {});
+  if (!migrationConfig) {
+    console.warn("No migration config found.");
+    process.exit(1);
+  }
+  const directory = resolve(migrationConfig.directory);
+  const migrations = await loadMigrationsFromDisk(directory);
+  if (migrations.length === 0) {
+    console.warn("No migration files found in", directory);
+    return;
+  }
+  const tracker = buildTrackerFromAdapter(adapter);
+  const buildContext = () => buildContextFromAdapter(adapter, dialect);
+  const log = {
+    info: (msg) => console.warn(`[migration] ${msg}`),
+    warn: (msg) => console.warn(`[migration:warn] ${msg}`)
+  };
+  const useCloneTest = !args.skipCloneTest && migrationConfig.cloneTest && dialect === "postgresql";
+  if (useCloneTest) {
+    const db = buildCloneDbFromAdapter(adapter);
+    const result = await cloneTestApply({
+      migrations,
+      dialect,
+      tracker,
+      buildContext,
+      db,
+      buildCloneTracker: (_cloneName) => tracker,
+      buildCloneContext: (_cloneName) => buildContext(),
+      testOnly: args.testOnly,
+      log
+    });
+    const cloneSuccess = result.cloneResult ? result.cloneResult.failCount === 0 : false;
+    console.warn(`
+Clone test: ${cloneSuccess ? "PASSED" : "FAILED"}`);
+    if (!cloneSuccess && result.error) {
+      console.error(`Clone error: ${result.error}`);
+      if (result.suggestions.length > 0) {
+        console.warn(`Suggestion: ${result.suggestions[0]}`);
+      }
+    }
+    if (result.applyResult) {
+      console.warn(
+        `Applied: ${result.applyResult.successCount} migration(s) in batch ${result.applyResult.batch}`
+      );
+      if (result.applyResult.failCount > 0) {
+        console.error(`Failed: ${result.applyResult.failCount} migration(s)`);
+      }
+    }
+    if (!cloneSuccess) {
+      process.exit(1);
+    }
+  } else {
+    const result = await runMigrations({
+      migrations,
+      dialect,
+      tracker,
+      buildContext,
+      log
+    });
+    console.warn(`
+Applied: ${result.successCount} migration(s) in batch ${result.batch}`);
+    if (result.failCount > 0) {
+      console.error(`Failed: ${result.failCount} migration(s)`);
+      for (const r of result.results) {
+        if (!r.success) {
+          console.error(`  ${r.name}: ${r.error}`);
+        }
+      }
+      process.exit(1);
+    }
+  }
+}
+main().catch((err) => {
+  console.error("Migration run failed:", err);
+  process.exit(1);
+});