@noego/proper 0.1.0 → 0.2.1

package/bin/cli.js

@@ -123,11 +123,10 @@ function migration_filter(_0) {
 }
 
 // framework/MigrationRunner.ts
-var import_fs3 = __toESM(require("fs"));
+var import_fs6 = __toESM(require("fs"));
 
 // framework/MigrationDirectoryReader.ts
-var import_fs = __toESM(require("fs"));
-var import_path = __toESM(require("path"));
+var import_fs2 = __toESM(require("fs"));
 
 // framework/errors.ts
 var MigrationError = class _MigrationError extends Error {
@@ -242,6 +241,54 @@ ${originalError.message}`;
     return new _MigrationExecutionError(message);
   }
 };
+var PatchError = class _PatchError extends MigrationError {
+  constructor(message, patchFile, patchKey) {
+    super(`Patch Error: ${message}`);
+    this.patchFile = patchFile;
+    this.patchKey = patchKey;
+    this.name = "PatchError";
+    Object.setPrototypeOf(this, _PatchError.prototype);
+  }
+};
+var PatchValidationError = class _PatchValidationError extends PatchError {
+  constructor(message, patchFile, patchKey) {
+    super(message, patchFile, patchKey);
+    this.name = "PatchValidationError";
+    Object.setPrototypeOf(this, _PatchValidationError.prototype);
+  }
+};
+var PatchIntegrityError = class _PatchIntegrityError extends PatchError {
+  constructor(message, patchFile, patchKey, expectedChecksum, actualChecksum) {
+    super(message, patchFile, patchKey);
+    this.expectedChecksum = expectedChecksum;
+    this.actualChecksum = actualChecksum;
+    this.name = "PatchIntegrityError";
+    Object.setPrototypeOf(this, _PatchIntegrityError.prototype);
+  }
+};
+var PatchConflictError = class _PatchConflictError extends PatchError {
+  constructor(message, patchFile, patchKey, operationIndex, operationVerb, migrationKeys, observedRowCounts) {
+    super(message, patchFile, patchKey);
+    this.operationIndex = operationIndex;
+    this.operationVerb = operationVerb;
+    this.migrationKeys = migrationKeys;
+    this.observedRowCounts = observedRowCounts;
+    this.name = "PatchConflictError";
+    Object.setPrototypeOf(this, _PatchConflictError.prototype);
+  }
+};
+var PatchExecutionError = class _PatchExecutionError extends PatchError {
+  constructor(message, patchFile, patchKey, operationIndex, operationVerb, originalError) {
+    super(originalError ? `${message}
+Original Error:
+${originalError.message}` : message, patchFile, patchKey);
+    this.operationIndex = operationIndex;
+    this.operationVerb = operationVerb;
+    this.originalError = originalError;
+    this.name = "PatchExecutionError";
+    Object.setPrototypeOf(this, _PatchExecutionError.prototype);
+  }
+};
 var CLIError = class _CLIError extends MigrationError {
   constructor(message) {
     super(`CLI Error: ${message}`);
@@ -404,6 +451,40 @@ var SqlMigrationBuilder = class {
   }
 };
 
+// framework/MigrationManifest.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var MIGRATION_FILE_REGEX = /(?:\.(mysql|sqlite|pg))?\.(up|down)\.(sql|js)$/i;
+function isMigrationFile(fileName) {
+  return MIGRATION_FILE_REGEX.test(fileName);
+}
+function canonicalMigrationKey(value) {
+  return value.replace(MIGRATION_FILE_REGEX, "").toLowerCase();
+}
+function resolveMigrationFile(directory, baseName, direction, dialect) {
+  const dialectExt = dialect === "sql" ? "mysql" : dialect;
+  const dialectFile = import_path.default.join(directory, `${baseName}.${dialectExt}.${direction}.sql`);
+  if (import_fs.default.existsSync(dialectFile)) return dialectFile;
+  const genericFile = import_path.default.join(directory, `${baseName}.${direction}.sql`);
+  if (import_fs.default.existsSync(genericFile)) return genericFile;
+  return null;
+}
+function loadMigrationManifest(directory, dialect) {
+  const manifest = /* @__PURE__ */ new Map();
+  if (!import_fs.default.existsSync(directory)) return manifest;
+  const files = import_fs.default.readdirSync(directory, { withFileTypes: true }).filter((f) => f.isFile()).map((f) => f.name).filter(isMigrationFile);
+  const uniqueKeys = /* @__PURE__ */ new Set();
+  files.forEach((file) => uniqueKeys.add(canonicalMigrationKey(file)));
+  uniqueKeys.forEach((key) => {
+    manifest.set(key, {
+      key,
+      upFile: resolveMigrationFile(directory, key, "up", dialect),
+      downFile: resolveMigrationFile(directory, key, "down", dialect)
+    });
+  });
+  return manifest;
+}
+
 // framework/MigrationDirectoryReader.ts
 var MigrationDirectoryReader = class {
   constructor(directory, read_strategy, sqlrunner, dialect = "sql") {
@@ -418,12 +499,7 @@ var MigrationDirectoryReader = class {
    * File extensions: `.mysql.up.sql`, `.sqlite.up.sql`, `.pg.up.sql`.
    */
   resolveFile(baseName, direction) {
-    const dialectExt = this.dialect === "sql" ? "mysql" : this.dialect;
-    const dialectFile = import_path.default.join(this.directory, `${baseName}.${dialectExt}.${direction}.sql`);
-    if (import_fs.default.existsSync(dialectFile)) return dialectFile;
-    const genericFile = import_path.default.join(this.directory, `${baseName}.${direction}.sql`);
-    if (import_fs.default.existsSync(genericFile)) return genericFile;
-    return null;
+    return resolveMigrationFile(this.directory, baseName, direction, this.dialect);
   }
   /**
    * Checks if a file path is dialect-specific (contains .mysql. or .sqlite. in the name)
@@ -432,11 +508,11 @@ var MigrationDirectoryReader = class {
     return /\.(mysql|sqlite|pg)\.(up|down)\.sql$/i.test(filePath);
   }
   loadMigrations(table, connection) {
-    import_fs.default.existsSync(this.directory) || import_fs.default.mkdirSync(this.directory);
-    const dir_content = import_fs.default.readdirSync(this.directory, { withFileTypes: true }).filter((file) => file.isFile()).map((file) => file.name);
+    import_fs2.default.existsSync(this.directory) || import_fs2.default.mkdirSync(this.directory);
+    const dir_content = import_fs2.default.readdirSync(this.directory, { withFileTypes: true }).filter((file) => file.isFile()).map((file) => file.name).filter(isMigrationFile);
     const uniqueKeys = /* @__PURE__ */ new Set();
     dir_content.forEach((file) => {
-      const key = file.replace(/(?:\.(mysql|sqlite|pg))?\.(up|down)\.(sql|js)/i, "").toLowerCase();
+      const key = canonicalMigrationKey(file);
       uniqueKeys.add(key);
     });
     const migration_sorter = {};
@@ -476,14 +552,14 @@ var MigrationDirectoryReader = class {
     return builder;
   }
   sql_up(file) {
-    let content = import_fs.default.readFileSync(file).toString();
+    let content = import_fs2.default.readFileSync(file).toString();
     if (!this.isDialectSpecific(file)) {
       content = this.read_strategy(content);
     }
     return content.trim();
   }
   sql_down(file) {
-    let content = import_fs.default.readFileSync(file).toString();
+    let content = import_fs2.default.readFileSync(file).toString();
     if (!this.isDialectSpecific(file)) {
       content = this.read_strategy(content);
     }
@@ -492,7 +568,23 @@ var MigrationDirectoryReader = class {
 };
 
 // framework/MigrationSetup.ts
-var import_fs2 = __toESM(require("fs"));
+var import_fs3 = __toESM(require("fs"));
+
+// framework/PatchTypes.ts
+var import_path2 = __toESM(require("path"));
+var PATCH_FORMAT_VERSION = 1;
+var DEFAULT_PATCH_TABLE = "proper_patches";
+var PATCH_FILENAME_REGEX = new RegExp("^(?<stamp>[0-9]{13})_(?<name>[a-z0-9][a-z0-9_-]{0,119})\\.yaml$");
+function resolvePatchFolder(config) {
+  if (config.patch_folder) return config.patch_folder;
+  const dir = import_path2.default.dirname(config.migration_folder);
+  return dir === "." && !config.migration_folder.includes(import_path2.default.sep) && !config.migration_folder.includes("/") ? "patches" : import_path2.default.join(dir, "patches");
+}
+function resolvePatchTable(config) {
+  return config.patch_table || DEFAULT_PATCH_TABLE;
+}
+
+// framework/MigrationSetup.ts
 var MigrationSetup = class {
   constructor(sqlrunner, config) {
     this.sqlrunner = sqlrunner;
@@ -500,7 +592,7 @@ var MigrationSetup = class {
   }
   setup() {
     return __async(this, null, function* () {
-      import_fs2.default.existsSync(this.config.migration_folder) || import_fs2.default.mkdirSync(this.config.migration_folder);
+      import_fs3.default.existsSync(this.config.migration_folder) || import_fs3.default.mkdirSync(this.config.migration_folder);
       const tableName = this.config.migration_table;
       const createTableSql = this.config.database === "sqlite" ? `CREATE TABLE IF NOT EXISTS ${tableName} (
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -522,11 +614,39 @@ var MigrationSetup = class {
                 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
             )`;
       yield this.sqlrunner.query(createTableSql);
+      const patchTable = resolvePatchTable(this.config);
+      const createPatchTableSql = this.config.database === "sqlite" ? `CREATE TABLE IF NOT EXISTS ${patchTable} (
+                migration_table TEXT NOT NULL,
+                patch_key TEXT NOT NULL,
+                checksum TEXT NOT NULL,
+                format_version INTEGER NOT NULL,
+                description TEXT NOT NULL,
+                applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (migration_table, patch_key)
+            )` : this.config.database === "pg" ? `CREATE TABLE IF NOT EXISTS ${patchTable} (
+                migration_table TEXT NOT NULL,
+                patch_key TEXT NOT NULL,
+                checksum TEXT NOT NULL,
+                format_version INTEGER NOT NULL,
+                description TEXT NOT NULL,
+                applied_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+                PRIMARY KEY (migration_table, patch_key)
+            )` : `CREATE TABLE IF NOT EXISTS ${patchTable} (
+                migration_table VARCHAR(255) NOT NULL,
+                patch_key VARCHAR(255) NOT NULL,
+                checksum CHAR(64) NOT NULL,
+                format_version INT NOT NULL,
+                description TEXT NOT NULL,
+                applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (migration_table, patch_key)
+            )`;
+      yield this.sqlrunner.query(createPatchTableSql);
     });
   }
   teardown() {
     return __async(this, null, function* () {
       yield this.sqlrunner.execute(`DROP TABLE ${this.config.migration_table}`);
+      yield this.sqlrunner.execute(`DROP TABLE IF EXISTS ${resolvePatchTable(this.config)}`);
     });
   }
 };
@@ -588,6 +708,673 @@ function markerDialectParser(names) {
 var SqliteDialectParser = markerDialectParser(["sqlite"]);
 var PgDialectParser = markerDialectParser(["pg", "postgres", "postgresql"]);
 
+// framework/PatchDirectoryReader.ts
+var import_crypto = __toESM(require("crypto"));
+var import_fs4 = __toESM(require("fs"));
+var import_path3 = __toESM(require("path"));
+
+// framework/PatchValidator.ts
+var import_ajv = __toESM(require("ajv"));
+var import_yaml = require("yaml");
+var MAX_DESCRIPTION_LENGTH = 500;
+var MAX_MIGRATION_KEY_LENGTH = 255;
+var migrationKeySchema = {
+  type: "string",
+  minLength: 1,
+  maxLength: MAX_MIGRATION_KEY_LENGTH
+};
+var patchSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["version", "description", "operations"],
+  properties: {
+    version: { type: "integer" },
+    description: { type: "string" },
+    operations: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        minProperties: 1,
+        maxProperties: 1,
+        properties: {
+          rename_migration: {
+            type: "object",
+            additionalProperties: false,
+            required: ["from", "to"],
+            properties: { from: migrationKeySchema, to: migrationKeySchema }
+          },
+          mark_applied: {
+            type: "object",
+            additionalProperties: false,
+            required: ["key"],
+            properties: { key: migrationKeySchema }
+          },
+          unmark_applied: {
+            type: "object",
+            additionalProperties: false,
+            required: ["key"],
+            properties: { key: migrationKeySchema }
+          }
+        }
+      }
+    }
+  }
+};
+var ajv = new import_ajv.default({ allErrors: true, strict: true });
+var validateSchema = ajv.compile(patchSchema);
+function fail(message, file, patchKey) {
+  throw new PatchValidationError(message, file, patchKey);
+}
+function checkMigrationKey(value, context, file, patchKey) {
+  if (value !== value.trim()) fail(`${context}: migration key has leading/trailing whitespace`, file, patchKey);
+  if (/[/\\]/.test(value)) fail(`${context}: migration key contains a path separator`, file, patchKey);
+  if (/[\x00-\x1f\x7f]/.test(value)) fail(`${context}: migration key contains control characters`, file, patchKey);
+  if (value.length === 0 || value.length > MAX_MIGRATION_KEY_LENGTH) {
+    fail(`${context}: migration key length out of bounds`, file, patchKey);
+  }
+  return canonicalMigrationKey(value);
+}
+function assertStrictYaml(doc, file, patchKey) {
+  if (doc.errors.length > 0) {
+    fail(`YAML parse error: ${doc.errors[0].message}`, file, patchKey);
+  }
+  if (doc.warnings.length > 0) {
+    fail(`YAML warning treated as error: ${doc.warnings[0].message}`, file, patchKey);
+  }
+  const visit = (node) => {
+    var _a, _b;
+    if (node == null || typeof node !== "object") return;
+    if ("source" in node && ((_a = node.constructor) == null ? void 0 : _a.name) === "Alias") {
+      fail("YAML aliases are not permitted in patch files", file, patchKey);
+    }
+    if (node.anchor) {
+      fail("YAML anchors are not permitted in patch files", file, patchKey);
+    }
+    if (node.tag && ![
+      "tag:yaml.org,2002:str",
+      "tag:yaml.org,2002:int",
+      "tag:yaml.org,2002:bool",
+      "tag:yaml.org,2002:null",
+      "tag:yaml.org,2002:map",
+      "tag:yaml.org,2002:seq"
+    ].includes(node.tag)) {
+      fail(`YAML tag '${node.tag}' is not permitted in patch files`, file, patchKey);
+    }
+    if (Array.isArray(node.items)) {
+      for (const item of node.items) {
+        if (item && typeof item === "object" && "key" in item) {
+          const keyValue = (_b = item.key) == null ? void 0 : _b.value;
+          if (keyValue === "<<") fail("YAML merge keys are not permitted in patch files", file, patchKey);
+          visit(item.key);
+          visit(item.value);
+        } else {
+          visit(item);
+        }
+      }
+    }
+  };
+  visit(doc.contents);
+}
+function parsePatchContent(content, fileName, patchKey) {
+  var _a;
+  const doc = (0, import_yaml.parseDocument)(content, {
+    uniqueKeys: true,
+    // duplicate mapping keys become errors
+    merge: false,
+    schema: "core",
+    version: "1.2"
+  });
+  assertStrictYaml(doc, fileName, patchKey);
+  const raw = doc.toJS({ mapAsMap: false });
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    fail("Patch document must be a YAML mapping", fileName, patchKey);
+  }
+  if (!validateSchema(raw)) {
+    const detail = ((_a = validateSchema.errors) != null ? _a : []).map((e) => `${e.instancePath || "/"} ${e.message}`).join("; ");
+    const anyRaw = raw;
+    if (typeof anyRaw.version === "number" && anyRaw.version !== PATCH_FORMAT_VERSION) {
+      fail(`Unknown patch format version: ${anyRaw.version} (supported: ${PATCH_FORMAT_VERSION})`, fileName, patchKey);
+    }
+    fail(`Schema validation failed: ${detail}`, fileName, patchKey);
+  }
+  const parsed = raw;
+  if (parsed.version !== PATCH_FORMAT_VERSION) {
+    fail(`Unknown patch format version: ${parsed.version} (supported: ${PATCH_FORMAT_VERSION})`, fileName, patchKey);
+  }
+  const description = parsed.description.trim();
+  if (description.length === 0) fail("description must be non-empty", fileName, patchKey);
+  if (description.length > MAX_DESCRIPTION_LENGTH) {
+    fail(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters`, fileName, patchKey);
+  }
+  const operations = parsed.operations.map((op, index) => {
+    const verbs = Object.keys(op);
+    const verb = verbs[0];
+    const context = `operation ${index} (${verb})`;
+    switch (verb) {
+      case "rename_migration": {
+        const from = checkMigrationKey(op.rename_migration.from, context, fileName, patchKey);
+        const to = checkMigrationKey(op.rename_migration.to, context, fileName, patchKey);
+        if (from === to) {
+          fail(`${context}: 'from' and 'to' are identical after canonicalization ('${from}')`, fileName, patchKey);
+        }
+        return { verb: "rename_migration", from, to };
+      }
+      case "mark_applied":
+        return { verb: "mark_applied", key: checkMigrationKey(op.mark_applied.key, context, fileName, patchKey) };
+      case "unmark_applied":
+        return { verb: "unmark_applied", key: checkMigrationKey(op.unmark_applied.key, context, fileName, patchKey) };
+      default:
+        fail(`operation ${index}: unknown verb '${verb}'`, fileName, patchKey);
+    }
+  });
+  return { version: parsed.version, description, operations };
+}
+function validatePatchPlan(patches, manifest) {
+  const renames = [];
+  for (const patch of patches) {
+    patch.operations.forEach((op, index) => {
+      if (op.verb === "rename_migration") {
+        renames.push({ from: op.from, to: op.to, file: patch.fileName });
+      } else if (op.verb === "mark_applied") {
+        if (!manifest.has(op.key)) {
+          throw new PatchValidationError(
+            `operation ${index} (mark_applied): key '${op.key}' is not present in the current migration manifest`,
+            patch.fileName,
+            patch.patchKey
+          );
+        }
+      }
+    });
+  }
+  if (renames.length === 0) return;
+  const mentioned = /* @__PURE__ */ new Set();
+  renames.forEach((r) => {
+    mentioned.add(r.from);
+    mentioned.add(r.to);
+  });
+  const finalKey = (start) => {
+    let current = start;
+    for (const r of renames) {
+      if (current === r.from) current = r.to;
+    }
+    return current;
+  };
+  for (const key of mentioned) {
+    const finish = finalKey(key);
+    if (manifest.has(key)) {
+      if (finish !== key) {
+        throw new PatchValidationError(
+          `rename plan moves current migration '${key}' to '${finish}', which would make its file incorrectly pending`
+        );
+      }
+    } else {
+      if (!manifest.has(finish)) {
+        throw new PatchValidationError(
+          `rename plan leaves historical key '${key}' at '${finish}', which is not present in the current migration manifest`
+        );
+      }
+    }
+  }
+}
+
+// framework/PatchDirectoryReader.ts
+var PatchDirectoryReader = class {
+  constructor(directory) {
+    this.directory = directory;
+  }
+  loadPatches() {
+    if (!import_fs4.default.existsSync(this.directory)) return [];
+    const entries = import_fs4.default.readdirSync(this.directory, { withFileTypes: true });
+    const patchFiles = [];
+    for (const entry of entries) {
+      if (!entry.name.endsWith(".yaml")) continue;
+      if (!entry.isFile() || entry.isSymbolicLink()) {
+        if (entry.isSymbolicLink()) {
+          throw new PatchValidationError(`patch file must be a regular file, not a symlink`, entry.name);
+        }
+        continue;
+      }
+      patchFiles.push(entry.name);
+    }
+    patchFiles.sort((a, b) => {
+      const stampA = parseInt(a.slice(0, 13), 10);
+      const stampB = parseInt(b.slice(0, 13), 10);
+      if (!Number.isNaN(stampA) && !Number.isNaN(stampB) && stampA !== stampB) {
+        return stampA - stampB;
+      }
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+    return patchFiles.map((fileName) => {
+      const match = PATCH_FILENAME_REGEX.exec(fileName);
+      if (!match) {
+        throw new PatchValidationError(
+          `invalid patch filename (expected <13-digit-stamp>_<name>.yaml with name matching [a-z0-9][a-z0-9_-]{0,119})`,
+          fileName
+        );
+      }
+      const patchKey = fileName.slice(0, -".yaml".length);
+      const filePath = import_path3.default.join(this.directory, fileName);
+      const bytes = import_fs4.default.readFileSync(filePath);
+      const checksum = import_crypto.default.createHash("sha256").update(bytes).digest("hex");
+      const content = bytes.toString("utf8");
+      const { version, description, operations } = parsePatchContent(content, fileName, patchKey);
+      return { patchKey, fileName, filePath, checksum, version, description, operations };
+    });
+  }
+};
+
+// framework/PatchRunner.ts
+function toError(error) {
+  if (error instanceof Error) return error;
+  return new Error(String(error));
+}
+function extractRows(result) {
+  if (!Array.isArray(result)) return [];
+  if (Array.isArray(result[0])) return result[0];
+  if (result.length === 2 && result[0] && typeof result[0] === "object" && result[1] && typeof result[1] === "object" && !("rows" in result[1])) {
+    return result;
+  }
+  if (result[0] == null) return [];
+  return [result[0]];
+}
+var PatchRunner = class {
+  constructor(sqlrunner, config) {
+    this.sqlrunner = sqlrunner;
+    this.config = config;
+    this.patchTable = resolvePatchTable(config);
+    this.migrationTable = config.migration_table;
+    this.dialect = config.database;
+  }
+  /**
+   * Discovers, validates, and applies every unapplied patch in order.
+   * Each unapplied patch is its own transaction; earlier committed patches
+   * remain committed if a later patch fails.
+   */
+  applyPending() {
+    return __async(this, null, function* () {
+      const reader = new PatchDirectoryReader(resolvePatchFolder(this.config));
+      const patches = reader.loadPatches();
+      const history = yield this.loadHistory();
+      if (patches.length === 0 && history.length === 0) {
+        return [];
+      }
+      const byKey = new Map(patches.map((p) => [p.patchKey, p]));
+      for (const row of history) {
+        const file = byKey.get(row.patch_key);
+        if (!file) {
+          throw new PatchIntegrityError(
+            `applied patch '${row.patch_key}' has no corresponding file in the patch folder; patch files are permanent and must never be renamed or deleted`,
+            void 0,
+            row.patch_key
+          );
+        }
+        if (file.checksum !== row.checksum) {
+          throw new PatchIntegrityError(
+            `applied patch '${row.patch_key}' content changed after application; patch files are immutable once recorded`,
+            file.fileName,
+            row.patch_key,
+            row.checksum,
+            file.checksum
+          );
+        }
+      }
+      const manifest = loadMigrationManifest(this.config.migration_folder, this.dialect);
+      validatePatchPlan(patches, manifest);
+      const appliedKeys = new Set(history.map((r) => r.patch_key));
+      const results = [];
+      for (const patch of patches) {
+        if (appliedKeys.has(patch.patchKey)) {
+          results.push({
+            patchKey: patch.patchKey,
+            fileName: patch.fileName,
+            status: "already_applied",
+            operations: []
+          });
+          continue;
+        }
+        results.push(yield this.applyOne(patch, manifest));
+      }
+      return results;
+    });
+  }
+  loadHistory() {
+    return __async(this, null, function* () {
+      try {
+        const result = yield this.sqlrunner.query(
+          `SELECT patch_key, checksum FROM ${this.patchTable} WHERE migration_table = ?`,
+          [this.migrationTable]
+        );
+        return extractRows(result);
+      } catch (error) {
+        throw new PatchExecutionError(
+          `failed to read patch history from '${this.patchTable}'`,
+          void 0,
+          void 0,
+          void 0,
+          void 0,
+          toError(error)
+        );
+      }
+    });
+  }
+  beginSql() {
+    switch (this.dialect) {
+      case "sqlite":
+        return "BEGIN IMMEDIATE";
+      case "pg":
+        return "BEGIN";
+      default:
+        return "START TRANSACTION";
+    }
+  }
+  begin(patch) {
+    return __async(this, null, function* () {
+      const deadline = Date.now() + 1e4;
+      while (true) {
+        try {
+          yield this.sqlrunner.execute(this.beginSql());
+          return;
+        } catch (error) {
+          const message = toError(error).message;
+          if (/SQLITE_BUSY|database is locked/i.test(message) && Date.now() < deadline) {
+            yield new Promise((resolve) => setTimeout(resolve, 50));
+            continue;
+          }
+          throw new PatchExecutionError(
+            "failed to start patch transaction",
+            patch.fileName,
+            patch.patchKey,
+            void 0,
+            void 0,
+            toError(error)
+          );
+        }
+      }
+    });
+  }
+  rollbackQuietly() {
+    return __async(this, null, function* () {
+      try {
+        yield this.sqlrunner.execute("ROLLBACK");
+      } catch (e) {
+      }
+    });
+  }
+  applyOne(patch, manifest) {
+    return __async(this, null, function* () {
+      yield this.begin(patch);
+      try {
+        yield this.sqlrunner.execute(
+          `INSERT INTO ${this.patchTable} (migration_table, patch_key, checksum, format_version, description)
+                 VALUES (?, ?, ?, ?, ?)`,
+          [this.migrationTable, patch.patchKey, patch.checksum, patch.version, patch.description]
+        );
+      } catch (claimError) {
+        yield this.rollbackQuietly();
+        const committed = yield this.findCommittedRow(patch.patchKey);
+        if (committed) {
+          if (committed.checksum === patch.checksum) {
+            return {
+              patchKey: patch.patchKey,
+              fileName: patch.fileName,
+              status: "already_applied",
+              operations: []
+            };
+          }
+          throw new PatchIntegrityError(
+            `patch '${patch.patchKey}' was applied elsewhere with a different checksum`,
+            patch.fileName,
+            patch.patchKey,
+            committed.checksum,
+            patch.checksum
+          );
+        }
+        throw new PatchExecutionError(
+          "failed to claim patch-history row",
+          patch.fileName,
+          patch.patchKey,
+          void 0,
+          void 0,
+          toError(claimError)
+        );
+      }
+      const operationResults = [];
+      try {
+        for (let index = 0; index < patch.operations.length; index++) {
+          operationResults.push(
+            yield this.applyOperation(patch, patch.operations[index], index, manifest)
+          );
+        }
+        yield this.sqlrunner.execute("COMMIT");
+      } catch (error) {
+        yield this.rollbackQuietly();
+        if (error instanceof PatchConflictError || error instanceof PatchExecutionError || error instanceof PatchIntegrityError) {
+          throw error;
+        }
+        throw new PatchExecutionError(
+          "patch application failed",
+          patch.fileName,
+          patch.patchKey,
+          void 0,
+          void 0,
+          toError(error)
+        );
+      }
+      return {
+        patchKey: patch.patchKey,
+        fileName: patch.fileName,
+        status: "applied",
+        operations: operationResults
+      };
+    });
+  }
+  findCommittedRow(patchKey) {
+    return __async(this, null, function* () {
+      const result = yield this.sqlrunner.query(
+        `SELECT patch_key, checksum FROM ${this.patchTable} WHERE migration_table = ? AND patch_key = ?`,
+        [this.migrationTable, patchKey]
+      );
+      const list = extractRows(result);
+      return list.length > 0 ? list[0] : null;
+    });
+  }
+  countRows(key) {
+    return __async(this, null, function* () {
+      var _a, _b, _c;
+      const result = yield this.sqlrunner.query(
+        `SELECT COUNT(*) AS row_count FROM ${this.migrationTable} WHERE migration_key = ?`,
+        [key]
+      );
+      const rows = extractRows(result);
+      const value = (_c = (_a = rows[0]) == null ? void 0 : _a.row_count) != null ? _c : Object.values((_b = rows[0]) != null ? _b : {})[0];
+      return Number(value != null ? value : 0);
+    });
+  }
+  conflict(patch, index, verb, message, keys, counts) {
+    throw new PatchConflictError(
+      `operation ${index} (${verb}): ${message}`,
+      patch.fileName,
+      patch.patchKey,
+      index,
+      verb,
+      keys,
+      counts
+    );
+  }
+  applyOperation(patch, op, index, manifest) {
+    return __async(this, null, function* () {
+      var _a, _b, _c, _d;
+      try {
+        switch (op.verb) {
+          case "rename_migration": {
+            const fromCount = yield this.countRows(op.from);
+            const toCount = yield this.countRows(op.to);
+            const counts = { [op.from]: fromCount, [op.to]: toCount };
+            if (fromCount > 1 || toCount > 1) {
+              this.conflict(
+                patch,
+                index,
+                op.verb,
+                `ledger corruption: duplicate rows for a migration key`,
+                [op.from, op.to],
+                counts
+              );
+            }
+            if (fromCount === 1 && toCount === 1) {
+              this.conflict(
+                patch,
+                index,
+                op.verb,
+                `both '${op.from}' and '${op.to}' exist in the ledger`,
+                [op.from, op.to],
+                counts
+              );
+            }
+            if (fromCount === 0) {
+              return { verb: op.verb, changed: false };
+            }
+            const target = manifest.get(op.to);
+            if (target) {
+              yield this.sqlrunner.execute(
+                `UPDATE ${this.migrationTable} SET migration_key = ?, up = ?, down = ? WHERE migration_key = ?`,
+                [op.to, (_a = target.upFile) != null ? _a : "", (_b = target.downFile) != null ? _b : "", op.from]
+              );
+            } else {
+              yield this.sqlrunner.execute(
+                `UPDATE ${this.migrationTable} SET migration_key = ? WHERE migration_key = ?`,
+                [op.to, op.from]
+              );
+            }
+            return { verb: op.verb, changed: true };
+          }
+          case "mark_applied": {
+            const count = yield this.countRows(op.key);
+            if (count > 1) {
+              this.conflict(
+                patch,
+                index,
+                op.verb,
+                `ledger corruption: duplicate rows for '${op.key}'`,
+                [op.key],
+                { [op.key]: count }
+              );
+            }
+            if (count === 1) {
+              return { verb: op.verb, changed: false };
+            }
+            const entry = manifest.get(op.key);
+            yield this.sqlrunner.execute(
+              `INSERT INTO ${this.migrationTable} (migration_key, up, down) VALUES (?, ?, ?)`,
+              [op.key, (_c = entry == null ? void 0 : entry.upFile) != null ? _c : "", (_d = entry == null ? void 0 : entry.downFile) != null ? _d : ""]
+            );
+            return { verb: op.verb, changed: true };
+          }
+          case "unmark_applied": {
+            const count = yield this.countRows(op.key);
+            if (count > 1) {
+              this.conflict(
+                patch,
+                index,
+                op.verb,
+                `ledger corruption: duplicate rows for '${op.key}'`,
+                [op.key],
+                { [op.key]: count }
+              );
+            }
+            if (count === 0) {
+              return { verb: op.verb, changed: false };
+            }
+            yield this.sqlrunner.execute(
+              `DELETE FROM ${this.migrationTable} WHERE migration_key = ?`,
+              [op.key]
+            );
+            return { verb: op.verb, changed: true };
+          }
+        }
+      } catch (error) {
+        if (error instanceof PatchConflictError) throw error;
+        throw new PatchExecutionError(
+          `operation failed`,
+          patch.fileName,
+          patch.patchKey,
+          index,
+          op.verb,
+          toError(error)
+        );
+      }
+    });
+  }
+};
+
+// framework/PatchCreator.ts
+var import_fs5 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
+var MAX_NAME_LENGTH = 120;
+var SCAFFOLD = `version: 1
+description: TODO
+operations: []
+`;
+var PatchCreator = class _PatchCreator {
+  constructor(patchFolder) {
+    this.patchFolder = patchFolder;
+  }
+  /**
+   * Normalizes a patch name: trim, whitespace runs -> `_`, lowercase.
+   * Rejects empty results, path separators, `..`, control characters,
+   * characters outside [a-z0-9_-], and names longer than 120 characters.
+   */
+  static normalizeName(name) {
+    const normalized = (name != null ? name : "").trim().replace(/\s+/g, "_").toLowerCase();
+    if (normalized.length === 0) {
+      throw new CLIError("Patch name is required");
+    }
+    if (normalized.includes("/") || normalized.includes("\\")) {
+      throw new CLIError("Patch name must not contain path separators");
+    }
+    if (normalized.includes("..")) {
+      throw new CLIError("Patch name must not contain '..'");
+    }
+    if (/[\x00-\x1f\x7f]/.test(normalized)) {
+      throw new CLIError("Patch name must not contain control characters");
+    }
+    if (!/^[a-z0-9_-]+$/.test(normalized)) {
+      throw new CLIError("Patch name may only contain characters [a-z0-9_-]");
+    }
+    if (normalized.length > MAX_NAME_LENGTH) {
+      throw new CLIError(`Patch name exceeds ${MAX_NAME_LENGTH} characters after normalization`);
+    }
+    return normalized;
+  }
+  /**
+   * Creates `<patch_folder>/<stamp>_<normalized_name>.yaml` with exclusive
+   * file creation. On a millisecond-stamp collision, mints a later stamp
+   * and retries. Returns the created path.
+   */
+  create(name) {
+    const normalized = _PatchCreator.normalizeName(name);
+    if (!import_fs5.default.existsSync(this.patchFolder)) {
+      import_fs5.default.mkdirSync(this.patchFolder, { recursive: true });
+    }
+    let stamp = Date.now();
+    for (let attempt = 0; attempt < 1e3; attempt++) {
+      const filePath = import_path4.default.join(this.patchFolder, `${stamp}_${normalized}.yaml`);
+      try {
+        import_fs5.default.writeFileSync(filePath, SCAFFOLD, { flag: "wx" });
+        return filePath;
+      } catch (error) {
+        if (error && error.code === "EEXIST") {
+          stamp += 1;
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new CLIError("Unable to create patch file: too many filename collisions");
+  }
+};
+
 // framework/SQLRunner.ts
 var BaseSQLRunner = class {
   /**
@@ -902,7 +1689,7 @@ var PgRunner = class _PgRunner extends BaseSQLRunner {
 };
 
 // framework/MigrationRunner.ts
-function toError(error) {
+function toError2(error) {
   if (error instanceof Error) return error;
   return new Error(String(error));
 }
@@ -926,10 +1713,12 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
     return __async(this, null, function* () {
       const configReader = new FileMigrationConfigReader(configFile);
       const config = configReader.loadFile();
+      let factoryOwnsConnection = false;
       if (!conn) {
         conn = yield this.createConnection(config);
+        factoryOwnsConnection = true;
       }
-      return new _MigrationRunnerFactory().create(config, conn);
+      return new _MigrationRunnerFactory().create(config, conn, factoryOwnsConnection);
     });
   }
   static createConnection(config) {
@@ -949,7 +1738,7 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
             conn = yield ((_b = (_a = mysql.default) == null ? void 0 : _a.createConnection) != null ? _b : mysql.createConnection)(settings);
             return conn;
           } catch (error) {
-            throw DatabaseConnectionError.connectionFailed("sql", toError(error).message);
+            throw DatabaseConnectionError.connectionFailed("sql", toError2(error).message);
           }
         case "sqlite":
           if (!config.sqlite) {
@@ -964,7 +1753,7 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
             });
             return conn;
           } catch (error) {
-            throw DatabaseConnectionError.connectionFailed("sqlite", toError(error).message);
+            throw DatabaseConnectionError.connectionFailed("sqlite", toError2(error).message);
           }
         case "pg":
           if (!config.pg && !process.env.DATABASE_URL) {
@@ -980,7 +1769,7 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
             yield conn.connect();
             return conn;
           } catch (error) {
-            throw DatabaseConnectionError.connectionFailed("pg", toError(error).message);
+            throw DatabaseConnectionError.connectionFailed("pg", toError2(error).message);
           }
         default:
           throw ConfigurationError.unknownDatabaseType(config.database);
@@ -994,7 +1783,7 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
       return new _MigrationRunnerFactory().createEmpty(config);
     });
   }
-  create(config, conn) {
+  create(config, conn, factoryOwnsConnection = false) {
     return __async(this, null, function* () {
       let sqlrunner;
       let driverConnection = conn;
@@ -1007,8 +1796,19 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
       const setup = new MigrationSetup(sqlrunner, config);
       const read_strategy = this.getReadStategy(config);
       const migration_files = new MigrationDirectoryReader(config.migration_folder, read_strategy, sqlrunner, config.database);
-      yield setup.setup();
-      return new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, driverConnection);
+      const runner = new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, driverConnection);
+      try {
+        yield runner.setup();
+      } catch (error) {
+        if (factoryOwnsConnection) {
+          try {
+            yield sqlrunner.end();
+          } catch (e) {
+          }
+        }
+        throw error;
+      }
+      return runner;
     });
   }
   createEmpty(config) {
@@ -1018,7 +1818,7 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
       const setup = new MigrationSetup(sqlrunner, config);
       const read_strategy = this.getReadStategy(config);
       const migration_files = new MigrationDirectoryReader(config.migration_folder, read_strategy, sqlrunner, config.database);
-      return new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, conn);
+      return new MySQLMigrationRunner(config, migration_files, setup, sqlrunner, conn, false);
     });
   }
   getReadStategy(config) {
@@ -1035,33 +1835,77 @@ var MigrationRunnerFactory = class _MigrationRunnerFactory {
   }
 };
 var MySQLMigrationRunner = class {
-  constructor(config, directory, setupRunner, sqlrunner, connection) {
+  constructor(config, directory, setupRunner, sqlrunner, connection, preflightEnabled = true) {
     this.config = config;
     this.directory = directory;
     this.setupRunner = setupRunner;
     this.sqlrunner = sqlrunner;
     this.connection = connection;
+    this.preflightEnabled = preflightEnabled;
+    /**
+     * Memoized in-flight preflight promise. Simultaneous or repeated calls
+     * to setup() on one runner execute the preflight (migration table setup
+     * + patch application) exactly once. Cleared after rejection so a caller
+     * may retry after fixing the cause.
+     */
+    this.preflightPromise = null;
+    this.lastPatchResults = [];
   }
   setup() {
+    return __async(this, null, function* () {
+      if (!this.preflightEnabled) {
+        return;
+      }
+      if (!this.preflightPromise) {
+        this.preflightPromise = this.runPreflight();
+        this.preflightPromise.catch(() => {
+          this.preflightPromise = null;
+        });
+      }
+      return this.preflightPromise;
+    });
+  }
+  runPreflight() {
     return __async(this, null, function* () {
       try {
         yield this.setupRunner.setup();
       } catch (error) {
-        throw new MigrationExecutionError("Failed to set up migration database", void 0, void 0, toError(error));
+        throw new MigrationExecutionError("Failed to set up migration database", void 0, void 0, toError2(error));
       }
+      const patchRunner = new PatchRunner(this.sqlrunner, this.config);
+      this.lastPatchResults = yield patchRunner.applyPending();
+    });
+  }
+  /**
+   * Delegates to the same idempotent preflight; returns the results of the
+   * patch pass that ran (or is running) for this runner.
+   */
+  applyPendingPatches() {
+    return __async(this, null, function* () {
+      yield this.setup();
+      return this.lastPatchResults;
     });
   }
+  /**
+   * Scaffolds a new ledger patch file and returns the created path.
+   * Never connects to a database.
+   */
+  createPatch(name) {
+    const creator = new PatchCreator(resolvePatchFolder(this.config));
+    return creator.create(name);
+  }
   terminate() {
     return __async(this, null, function* () {
       try {
         yield this.setupRunner.teardown();
       } catch (error) {
-        throw new MigrationExecutionError("Failed to tear down migration database", void 0, void 0, toError(error));
+        throw new MigrationExecutionError("Failed to tear down migration database", void 0, void 0, toError2(error));
       }
     });
   }
   getMigrationsHistory() {
     return __async(this, null, function* () {
+      yield this.setup();
       try {
         const results = yield this.sqlrunner.query(`
                 select * 
@@ -1069,16 +1913,17 @@ var MySQLMigrationRunner = class {
             `);
         return results[0];
       } catch (error) {
-        throw new MigrationExecutionError("Failed to get migration history", void 0, void 0, toError(error));
+        throw new MigrationExecutionError("Failed to get migration history", void 0, void 0, toError2(error));
       }
     });
   }
   getMigrations() {
     return __async(this, null, function* () {
+      yield this.setup();
       try {
         return this.directory.loadMigrations(this.config.migration_table, this.connection);
       } catch (error) {
-        throw new MigrationExecutionError("Failed to load migrations", void 0, void 0, toError(error));
+        throw new MigrationExecutionError("Failed to load migrations", void 0, void 0, toError2(error));
       }
     });
   }
@@ -1091,7 +1936,7 @@ var MySQLMigrationRunner = class {
         if (error instanceof MigrationExecutionError) {
           throw error;
         }
-        throw new MigrationExecutionError("Failed to get pending migrations", void 0, void 0, toError(error));
+        throw new MigrationExecutionError("Failed to get pending migrations", void 0, void 0, toError2(error));
       }
     });
   }
@@ -1104,12 +1949,13 @@ var MySQLMigrationRunner = class {
         if (error instanceof MigrationExecutionError) {
           throw error;
         }
-        throw new MigrationExecutionError("Failed to get completed migrations", void 0, void 0, toError(error));
+        throw new MigrationExecutionError("Failed to get completed migrations", void 0, void 0, toError2(error));
       }
     });
   }
   migrate(migrationNodes, forward) {
     return __async(this, null, function* () {
+      yield this.setup();
       for (let node of migrationNodes) {
         try {
           if (forward) {
@@ -1122,7 +1968,7 @@ var MySQLMigrationRunner = class {
             `Failed to ${forward ? "apply" : "rollback"} migration`,
             node.name || String(node),
             forward ? node.up_sql() : node.down_sql(),
-            toError(error)
+            toError2(error)
           );
         }
       }
@@ -1130,6 +1976,7 @@ var MySQLMigrationRunner = class {
   }
   reset() {
     return __async(this, null, function* () {
+      yield this.setup();
       try {
         let migrations = yield this.getMigrations();
         const rollback = yield migration_filter(migrations, true);
@@ -1141,7 +1988,7 @@ var MySQLMigrationRunner = class {
         if (error instanceof MigrationExecutionError) {
           throw error;
         }
-        throw new MigrationExecutionError("Failed to reset migrations", void 0, void 0, toError(error));
+        throw new MigrationExecutionError("Failed to reset migrations", void 0, void 0, toError2(error));
       }
     });
   }
@@ -1150,7 +1997,7 @@ var MySQLMigrationRunner = class {
       const creator = new MigrationCreator(this.config);
       creator.create(name);
     } catch (error) {
-      throw new MigrationExecutionError(`Failed to create migration: ${name}`, void 0, void 0, toError(error));
+      throw new MigrationExecutionError(`Failed to create migration: ${name}`, void 0, void 0, toError2(error));
     }
   }
   close() {
@@ -1159,7 +2006,7 @@ var MySQLMigrationRunner = class {
         try {
           yield this.sqlrunner.end();
         } catch (error) {
-          throw new DatabaseConnectionError(`Failed to close database connection: ${toError(error).message}`);
+          throw new DatabaseConnectionError(`Failed to close database connection: ${toError2(error).message}`);
         }
       }
     });
@@ -1173,7 +2020,7 @@ var MySQLMigrationRunner = class {
     return __async(this, null, function* () {
       try {
         console.log(`Checking for ${config_file2}`);
-        const config_exist = import_fs3.default.existsSync(config_file2);
+        const config_exist = import_fs6.default.existsSync(config_file2);
         if (!config_exist) {
           console.log(`Creating ${config_file2}`);
           const default_config = {
@@ -1187,11 +2034,11 @@ var MySQLMigrationRunner = class {
               "password": ""
             }
           };
-          import_fs3.default.writeFileSync(config_file2, JSON.stringify(default_config, null, 2));
+          import_fs6.default.writeFileSync(config_file2, JSON.stringify(default_config, null, 2));
           console.log(`Created ${config_file2}`);
         }
       } catch (error) {
-        throw new ConfigurationError(`Failed to initialize config file: ${toError(error).message}`);
+        throw new ConfigurationError(`Failed to initialize config file: ${toError2(error).message}`);
       }
     });
   }
@@ -1202,7 +2049,7 @@ var FileMigrationConfigReader = class {
   }
   loadFile() {
     try {
-      const fileContent = import_fs3.default.readFileSync(this.configFile);
+      const fileContent = import_fs6.default.readFileSync(this.configFile);
       const config = JSON.parse(fileContent.toString());
       if (!config.migration_folder) {
         throw ConfigurationError.missingRequiredProperty("migration_folder");
@@ -1226,7 +2073,7 @@ var FileMigrationConfigReader = class {
       if (error instanceof ConfigurationError) {
         throw error;
       }
-      const err = toError(error);
+      const err = toError2(error);
       if (err.message.includes("ENOENT")) {
         throw new ConfigurationError(`Config file not found: ${this.configFile}`);
       }
@@ -1243,16 +2090,16 @@ var MigrationCreator = class {
       throw new CLIError("Migration name is required");
     }
     try {
-      if (!import_fs3.default.existsSync(this.config.migration_folder)) {
-        import_fs3.default.mkdirSync(this.config.migration_folder, { recursive: true });
+      if (!import_fs6.default.existsSync(this.config.migration_folder)) {
+        import_fs6.default.mkdirSync(this.config.migration_folder, { recursive: true });
       }
       const now_timestamp = Date.now();
       const filename_up = `${now_timestamp}_${name}.up.sql`;
       const filename_down = `${now_timestamp}_${name}.down.sql`;
-      import_fs3.default.writeFileSync(`${this.config.migration_folder}/${filename_up}`, `
+      import_fs6.default.writeFileSync(`${this.config.migration_folder}/${filename_up}`, `
 -- Write your up migration here
             `.trim());
-      import_fs3.default.writeFileSync(`${this.config.migration_folder}/${filename_down}`, `
+      import_fs6.default.writeFileSync(`${this.config.migration_folder}/${filename_down}`, `
 -- Write your down migration here
             `.trim());
       console.log(`Created migration files:`);
@@ -1262,16 +2109,16 @@ var MigrationCreator = class {
       if (error instanceof CLIError) {
         throw error;
       }
-      throw new MigrationExecutionError(`Failed to create migration files: ${toError(error).message}`);
+      throw new MigrationExecutionError(`Failed to create migration files: ${toError2(error).message}`);
     }
   }
 };
 
 // framework/SeedRunner.ts
-var import_fs4 = __toESM(require("fs"));
-var import_path2 = __toESM(require("path"));
+var import_fs7 = __toESM(require("fs"));
+var import_path5 = __toESM(require("path"));
 var import_url = require("url");
-var import_ajv = __toESM(require("ajv"));
+var import_ajv2 = __toESM(require("ajv"));
 var import_ajv_formats = __toESM(require("ajv-formats"));
 var import_api = require("tsx/esm/api");
 function resolveAlias(name, aliasMap) {
@@ -1280,10 +2127,10 @@ function resolveAlias(name, aliasMap) {
   return (_a = aliasMap[name]) != null ? _a : name;
 }
 function walkForFile(rootDir, fileName) {
-  if (!import_fs4.default.existsSync(rootDir)) return null;
-  const entries = import_fs4.default.readdirSync(rootDir, { withFileTypes: true });
+  if (!import_fs7.default.existsSync(rootDir)) return null;
+  const entries = import_fs7.default.readdirSync(rootDir, { withFileTypes: true });
   for (const entry of entries) {
-    const full = import_path2.default.join(rootDir, entry.name);
+    const full = import_path5.default.join(rootDir, entry.name);
     if (entry.isDirectory()) {
       const found = walkForFile(full, fileName);
       if (found) return found;
@@ -1377,39 +2224,39 @@ function resolveSeed(name, migrationConfig, options) {
 }
 function loadJson(filePath) {
   return __async(this, null, function* () {
-    const content = yield import_fs4.default.promises.readFile(filePath, "utf8");
+    const content = yield import_fs7.default.promises.readFile(filePath, "utf8");
     return JSON.parse(content);
   });
 }
 function createValidator() {
-  const ajv = new import_ajv.default({ allErrors: true, strict: false });
-  (0, import_ajv_formats.default)(ajv);
-  return ajv;
+  const ajv2 = new import_ajv2.default({ allErrors: true, strict: false });
+  (0, import_ajv_formats.default)(ajv2);
+  return ajv2;
 }
 function validateData(schemaPath, data, validate, log) {
   return __async(this, null, function* () {
     if (!validate || !schemaPath) return;
-    const content = yield import_fs4.default.promises.readFile(schemaPath, "utf8");
+    const content = yield import_fs7.default.promises.readFile(schemaPath, "utf8");
     const schema = JSON.parse(content);
-    const ajv = createValidator();
-    const validateFn = ajv.compile(schema);
+    const ajv2 = createValidator();
+    const validateFn = ajv2.compile(schema);
     const ok = validateFn(data);
     if (!ok) {
       log == null ? void 0 : log(`Validation failed for seed data (${schemaPath})`);
-      throw new Error(`Seed data validation failed: ${ajv.errorsText(validateFn.errors || [])}`);
+      throw new Error(`Seed data validation failed: ${ajv2.errorsText(validateFn.errors || [])}`);
     }
   });
 }
 function runSqlSeed(runner, resolved, direction) {
   return __async(this, null, function* () {
     const sqlPath = direction === "up" ? resolved.upPath : resolved.downPath;
-    const sql = yield import_fs4.default.promises.readFile(sqlPath, "utf8");
+    const sql = yield import_fs7.default.promises.readFile(sqlPath, "utf8");
     yield runner.query(sql);
   });
 }
 function loadSeedModule(modulePath) {
   return __async(this, null, function* () {
-    const resolved = import_path2.default.resolve(modulePath);
+    const resolved = import_path5.default.resolve(modulePath);
     if (resolved.endsWith(".ts")) {
       const fileUrl = (0, import_url.pathToFileURL)(resolved).href;
       return (0, import_api.tsImport)(fileUrl, fileUrl);
@@ -1510,7 +2357,7 @@ if (!args.commands || args.commands.length === 0) {
 }
 var commands = args.commands;
 var command = commands[0];
-var load_database = !["init", "create", "help"].includes(command.toLowerCase());
+var load_database = !["init", "create", "help", "patch"].includes(command.toLowerCase());
 var config_file = args.flags.config || "proper.json";
 if (command.toLowerCase() === "help") {
   printUsage();
@@ -1519,9 +2366,17 @@ if (command.toLowerCase() === "help") {
 console.log(`Loading database: ${load_database}`);
 var pending_runner = load_database ? MigrationRunnerFactory.create(config_file) : MigrationRunnerFactory.createEmpty(config_file);
 pending_runner.then((runner) => __async(null, null, function* () {
+  let failed = false;
   try {
     if (load_database) {
-      yield runner.setup();
+      const patch_results = yield runner.applyPendingPatches();
+      for (const patch of patch_results) {
+        if (patch.status === "applied") {
+          const changed = patch.operations.filter((op) => op.changed).length;
+          const noop = patch.operations.length - changed;
+          console.log(`Applied patch ${patch.fileName}: ${changed} changed, ${noop} no-op operation(s)`);
+        }
+      }
     }
     switch (command.toLowerCase()) {
       case "up":
@@ -1541,7 +2396,6 @@ pending_runner.then((runner) => __async(null, null, function* () {
         } else {
           console.log("No pending migrations");
         }
-        yield runner.close();
         break;
       case "down":
         const migrations_rollback = yield runner.getMigrations();
@@ -1562,13 +2416,11 @@ pending_runner.then((runner) => __async(null, null, function* () {
         } else {
           console.log("No migrations to roll back");
         }
-        yield runner.close();
         break;
       case "reset":
         console.log("Resetting all migrations...");
         yield runner.reset();
         console.log("Reset completed successfully");
-        yield runner.close();
         break;
       case "create":
         let filename = args.flags.name || commands[1];
@@ -1577,11 +2429,22 @@ pending_runner.then((runner) => __async(null, null, function* () {
         }
         filename = filename.replace(/\s/g, "_");
         runner.createMigration(filename);
-        runner.close();
         break;
+      case "patch": {
+        const patch_name = args.flags.name || commands[1];
+        if (!patch_name) {
+          throw new CLIError("Patch name is required. Usage: proper patch <name>");
+        }
+        const created_path = runner.createPatch(patch_name);
+        console.log(`Created patch file:`);
+        console.log(`  ${created_path}`);
+        console.log("");
+        console.log("Complete this file before running another database-backed");
+        console.log("Proper command: 'operations: []' is intentionally not runnable.");
+        break;
+      }
       case "init":
         yield runner.init(config_file);
-        runner.close();
         break;
       case "status":
         const { printTable } = require("console-table-printer");
@@ -1595,7 +2458,6 @@ pending_runner.then((runner) => __async(null, null, function* () {
           };
         }));
         printTable(yield Promise.all(table));
-        runner.close();
         break;
       case "query":
         const sql_query = args.flags.query || commands[1];
@@ -1639,7 +2501,6 @@ Returned ${results.length} row(s)`);
         } catch (error) {
           throw new CLIError(`Query execution failed: ${error.message}`);
         }
-        yield runner.close();
         break;
       case "seed": {
         const subCommands = commands.slice(1);
@@ -1672,7 +2533,6 @@ Returned ${results.length} row(s)`);
         const reader = new FileMigrationConfigReader(config_file);
         const migrationConfig = reader.loadFile();
         yield runSeedsWithRunner(runner, migrationConfig, action, seedOptions);
-        yield runner.close();
         break;
       }
       default:
@@ -1683,9 +2543,25 @@ Returned ${results.length} row(s)`);
     if (error.stack && process.env.DEBUG) {
       console.error(error.stack);
     }
+    failed = true;
+  } finally {
+    try {
+      yield runner.close();
+    } catch (closeError) {
+      console.error(`Error closing connection: ${closeError.message}`);
+      failed = true;
+    }
+  }
+  if (failed) {
     process.exit(1);
   }
-}));
+})).catch((error) => {
+  console.error(`Error: ${error.message}`);
+  if (error.stack && process.env.DEBUG) {
+    console.error(error.stack);
+  }
+  process.exit(1);
+});
 function printUsage() {
   console.log(`
 SQL Proper - Database migration tool
@@ -1698,6 +2574,7 @@ Commands:
   down     Roll back completed migrations
   reset    Roll back all migrations and reapply them
   create   Create a new migration
+  patch    Create a new ledger patch file (repairs migration history; no database access)
   init     Initialize a new config file
   status   Show migration status
   query    Execute a SQL query and display results
@@ -1716,6 +2593,7 @@ Examples:
   proper down --increment 3                    Roll back the last 3 applied migrations
   proper down --all                            Roll back all completed migrations
   proper create my_migration                   Create a new migration named "my_migration"
+  proper patch fix_renamed_keys                Scaffold a ledger patch file in the patch folder
   proper init                                  Create a new config file
   proper status                                Show the status of all migrations
   proper query "select * from users"           Execute a SQL query