sealed-migrations 0.1.0

package/dist/index.js

@@ -0,0 +1,663 @@
+import { promises } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import process from "node:process";
+
+//#region src/sql.ts
+/**
+* A tiny SQL splitter aware of string/identifier quoting and comments, so a
+* migration file can hold multiple statements. It is deliberately conservative:
+* it never tries to understand SQL, only where one statement ends.
+*/
+function stripLeadingComments(statement) {
+	let sql = statement.trimStart();
+	while (sql.length > 0) {
+		if (sql.startsWith("--")) {
+			const nextLine = sql.indexOf("\n");
+			if (nextLine === -1) return "";
+			sql = sql.slice(nextLine + 1).trimStart();
+			continue;
+		}
+		if (sql.startsWith("#")) {
+			const nextLine = sql.indexOf("\n");
+			if (nextLine === -1) return "";
+			sql = sql.slice(nextLine + 1).trimStart();
+			continue;
+		}
+		if (sql.startsWith("/*")) {
+			if (sql.startsWith("/*!")) return sql;
+			const commentEnd = sql.indexOf("*/");
+			if (commentEnd === -1) return "";
+			sql = sql.slice(commentEnd + 2).trimStart();
+			continue;
+		}
+		return sql;
+	}
+	return "";
+}
+function splitSqlStatements(sqlFileContent) {
+	const statements = [];
+	let current = "";
+	let inSingle = false;
+	let inDouble = false;
+	let inBacktick = false;
+	let inLineComment = false;
+	let inBlockComment = false;
+	for (let i = 0; i < sqlFileContent.length; i += 1) {
+		const char = sqlFileContent[i];
+		const next = sqlFileContent[i + 1];
+		if (inLineComment) {
+			current += char;
+			if (char === "\n") inLineComment = false;
+			continue;
+		}
+		if (inBlockComment) {
+			current += char;
+			if (char === "*" && next === "/") {
+				current += "/";
+				i += 1;
+				inBlockComment = false;
+			}
+			continue;
+		}
+		if (!inSingle && !inDouble && !inBacktick) {
+			if (char === "-" && next === "-" && /\s/.test(sqlFileContent[i + 2] ?? "")) {
+				inLineComment = true;
+				current += char;
+				current += next;
+				i += 1;
+				continue;
+			}
+			if (char === "#") {
+				inLineComment = true;
+				current += char;
+				continue;
+			}
+			if (char === "/" && next === "*") {
+				inBlockComment = true;
+				current += char;
+				current += next;
+				i += 1;
+				continue;
+			}
+			if (char === ";") {
+				const trimmed = current.trim();
+				if (trimmed) statements.push(trimmed);
+				current = "";
+				continue;
+			}
+		}
+		if (!inDouble && !inBacktick && char === "'") {
+			if (inSingle && next === "'") {
+				current += "''";
+				i += 1;
+				continue;
+			}
+			inSingle = !inSingle;
+			current += char;
+			continue;
+		}
+		if (!inSingle && !inBacktick && char === "\"") {
+			if (inDouble && next === "\"") {
+				current += "\"\"";
+				i += 1;
+				continue;
+			}
+			inDouble = !inDouble;
+			current += char;
+			continue;
+		}
+		if (!inSingle && !inDouble && char === "`") {
+			inBacktick = !inBacktick;
+			current += char;
+			continue;
+		}
+		current += char;
+	}
+	const last = current.trim();
+	if (last) statements.push(last);
+	return statements;
+}
+/**
+* Picks the transaction mode for a migration file. An explicit
+* `-- migrate: tx | no-tx | auto` directive wins; otherwise DDL forces the
+* non-transactional path (MySQL/MariaDB cannot roll back DDL).
+*/
+function resolveTxMode(sql, statements) {
+	const directive = sql.match(/--\s*migrate:\s*(tx|no-tx|auto)/i)?.[1]?.toLowerCase();
+	if (directive === "tx") return "transactional";
+	if (directive === "no-tx") return "non_transactional";
+	const ddlRegex = /^(?:ALTER|CREATE|DROP|TRUNCATE|RENAME|LOCK|UNLOCK)\b/i;
+	return statements.some((statement) => ddlRegex.test(stripLeadingComments(statement))) ? "non_transactional" : "transactional";
+}
+
+//#endregion
+//#region src/migrations.ts
+const MIGRATION_DIR_PATTERN = /^(\d+)_([a-z0-9_]+)$/;
+const DEV_MIGRATION_DIR_PATTERN = /^dev_([a-z0-9_]+)$/;
+/** SHA-256 of `up.sql + "\n--down-sql--\n" + down.sql`, content only. */
+function hashMigration(upSql, downSql) {
+	return createHash("sha256").update(upSql).update("\n--down-sql--\n").update(downSql).digest("hex");
+}
+function isDevVersion(version) {
+	return DEV_MIGRATION_DIR_PATTERN.test(String(version));
+}
+function parseMigrationDirName(dirName) {
+	const devMatch = DEV_MIGRATION_DIR_PATTERN.exec(dirName);
+	if (devMatch) return {
+		isDev: true,
+		sortNumber: Number.POSITIVE_INFINITY,
+		version: dirName,
+		description: (devMatch[1] ?? "").replaceAll("_", " ")
+	};
+	const match = MIGRATION_DIR_PATTERN.exec(dirName);
+	if (!match) throw new Error(`Invalid migration directory name "${dirName}". Expected format: NNN_description (example: 002_add_column_x) or dev_description (example: dev_add_column_x)`);
+	return {
+		isDev: false,
+		sortNumber: Number.parseInt(match[1] ?? "0", 10),
+		version: dirName,
+		description: (match[2] ?? "").replaceAll("_", " ")
+	};
+}
+/**
+* Normalises a `seal`/`rehash` argument into a `dev_<slug>` version. Accepts
+* both `foo` and `dev_foo`, and refuses sealed (numbered) versions, which are
+* immutable.
+*/
+function normalizeDevVersion(input) {
+	const raw = (input ?? "").trim();
+	if (!raw) throw new Error("Missing dev migration slug. Usage: seal|rehash <slug> (slug or dev_<slug>)");
+	if (MIGRATION_DIR_PATTERN.test(raw)) throw new Error(`${raw} is a sealed (numbered) migration. Sealed migrations are immutable; this command only operates on dev migrations.`);
+	const version = raw.startsWith("dev_") ? raw : `dev_${raw}`;
+	if (!DEV_MIGRATION_DIR_PATTERN.test(version)) throw new Error(`Invalid dev migration slug "${raw}". Expected [a-z0-9_]+ (example: album_sharing)`);
+	return version;
+}
+async function fileExists(filePath) {
+	try {
+		await promises.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Reads every migration folder, sorted numbered-ascending then dev
+* alphabetical. Duplicate numeric prefixes stay deterministic via the folder
+* name tie-break.
+*/
+async function readMigrations(migrationsDir) {
+	const dirs = (await promises.readdir(migrationsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((a, b) => {
+		const left = parseMigrationDirName(a);
+		const right = parseMigrationDirName(b);
+		if (left.sortNumber !== right.sortNumber) return left.sortNumber - right.sortNumber;
+		return left.version.localeCompare(right.version);
+	});
+	const migrations = [];
+	for (const dirName of dirs) {
+		const parsed = parseMigrationDirName(dirName);
+		const migrationPath = path.join(migrationsDir, dirName);
+		const upPath = path.join(migrationPath, "up.sql");
+		const downPath = path.join(migrationPath, "down.sql");
+		const [upExists, downExists] = await Promise.all([fileExists(upPath), fileExists(downPath)]);
+		if (!upExists || !downExists) throw new Error(`Migration ${dirName} must contain up.sql and down.sql`);
+		const [upSql, downSql] = await Promise.all([promises.readFile(upPath, "utf8"), promises.readFile(downPath, "utf8")]);
+		migrations.push({
+			...parsed,
+			upSql,
+			downSql,
+			checksum: hashMigration(upSql, downSql)
+		});
+	}
+	return migrations;
+}
+
+//#endregion
+//#region src/state.ts
+async function ensureSchemaMigrationsTable(conn) {
+	await conn.query(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version VARCHAR(128) NOT NULL,
+      description VARCHAR(255) NOT NULL,
+      checksum CHAR(64) NOT NULL,
+      applied_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+      execution_ms INT UNSIGNED NOT NULL,
+      tx_mode ENUM('transactional', 'non_transactional', 'baseline_mark') NOT NULL,
+      app_version VARCHAR(128) NULL,
+      executed_by VARCHAR(128) NULL,
+      PRIMARY KEY (version)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+}
+async function getAppliedMigrations(conn) {
+	const [rows] = await conn.query(`SELECT version, checksum, applied_at FROM schema_migrations ORDER BY applied_at ASC, version ASC`);
+	const byVersion = /* @__PURE__ */ new Map();
+	for (const row of rows) byVersion.set(row.version, {
+		checksum: row.checksum,
+		appliedAt: row.applied_at
+	});
+	return byVersion;
+}
+async function getSchemaHasUserTables(conn, dbName) {
+	const [rows] = await conn.execute(`
+      SELECT COUNT(*) AS cnt
+      FROM information_schema.tables
+      WHERE table_schema = ?
+        AND table_type = 'BASE TABLE'
+        AND table_name <> 'schema_migrations'
+    `, [dbName]);
+	return Number(rows[0]?.cnt ?? 0) > 0;
+}
+async function acquireLock(conn, lockName, timeoutSec) {
+	const [rows] = await conn.execute("SELECT GET_LOCK(?, ?) AS lock_acquired", [lockName, timeoutSec]);
+	if (Number(rows[0]?.lock_acquired) !== 1) throw new Error(`Failed to acquire migration lock "${lockName}" within ${timeoutSec}s`);
+}
+async function releaseLock(conn, lockName) {
+	try {
+		await conn.execute("SELECT RELEASE_LOCK(?)", [lockName]);
+	} catch {}
+}
+async function insertAppliedMigration(conn, migration, txMode, executionMs, config) {
+	await conn.execute(`
+      INSERT INTO schema_migrations
+        (version, description, checksum, execution_ms, tx_mode, app_version, executed_by)
+      VALUES
+        (?, ?, ?, ?, ?, ?, ?)
+      ON DUPLICATE KEY UPDATE version = version
+    `, [
+		migration.version,
+		migration.description,
+		migration.checksum,
+		executionMs,
+		txMode,
+		config.appVersion ?? null,
+		config.executedBy ?? null
+	]);
+}
+async function deleteAppliedMigration(conn, version) {
+	await conn.execute("DELETE FROM schema_migrations WHERE version = ?", [version]);
+}
+function makeMigrationMap(migrations) {
+	return new Map(migrations.map((migration) => [migration.version, migration]));
+}
+/**
+* Checks applied state against the repo:
+* - a dev migration applied elsewhere but missing here is only a warning
+*   (the normal state of a shared dev DB with parallel branches),
+* - a numbered migration missing here is a hard error (sealed history is strict),
+* - a checksum mismatch is a hard error, except a dev mismatch in `warn` mode
+*   (the `down` path, so the SQL-first edit loop can start).
+*/
+function validateAppliedState(migrations, appliedByVersion, options = {}, logger = console) {
+	const devChecksumMismatch = options.devChecksumMismatch ?? "error";
+	const migrationsByVersion = makeMigrationMap(migrations);
+	for (const [version] of appliedByVersion) {
+		if (migrationsByVersion.has(version)) continue;
+		if (isDevVersion(version)) {
+			logger.warn(`WARNING: applied dev migration ${version} is missing in this worktree (parallel branch), skipping`);
+			continue;
+		}
+		throw new Error(`Applied migration ${version} is missing in repository`);
+	}
+	for (const migration of migrations) {
+		const applied = appliedByVersion.get(migration.version);
+		if (!applied) continue;
+		if (applied.checksum !== migration.checksum) {
+			if (migration.isDev) {
+				if (devChecksumMismatch === "warn") {
+					logger.warn(`WARNING: checksum mismatch for dev migration ${migration.version} (files changed since apply), continuing with the current SQL`);
+					continue;
+				}
+				const slug = migration.version.slice(4);
+				throw new Error(`Checksum mismatch for dev migration ${migration.version}. Re-apply it (down + up), or run "seal|rehash ${slug}" if you already applied the schema change manually.`);
+			}
+			throw new Error(`Checksum mismatch for migration ${migration.version}. Applied migration files were modified.`);
+		}
+	}
+}
+
+//#endregion
+//#region src/apply.ts
+/** Identity wrapper used when the consumer does not supply a retry strategy. */
+function passthroughRetry(fn) {
+	return fn();
+}
+async function executeStatements(conn, statements, context) {
+	for (let i = 0; i < statements.length; i += 1) {
+		const executableSql = stripLeadingComments(statements[i] ?? "").trim();
+		if (!executableSql) continue;
+		try {
+			await conn.query(executableSql);
+		} catch (error) {
+			const err = error;
+			const message = err?.sqlMessage ?? err?.message ?? "Unknown SQL error";
+			throw new Error(`${context} failed at statement #${i + 1}: ${message}`, { cause: error });
+		}
+	}
+}
+async function applyUpMigration(conn, migration, config, logger) {
+	const statements = splitSqlStatements(migration.upSql);
+	if (statements.length === 0) throw new Error(`Migration ${migration.version} has empty up.sql`);
+	const withRetry = config.withRetry ?? passthroughRetry;
+	const txMode = resolveTxMode(migration.upSql, statements);
+	const start = Date.now();
+	if (txMode === "transactional") await withRetry(async () => {
+		await conn.beginTransaction();
+		try {
+			await executeStatements(conn, statements, `UP migration ${migration.version}`);
+			await insertAppliedMigration(conn, migration, txMode, Date.now() - start, config);
+			await conn.commit();
+		} catch (error) {
+			await conn.rollback();
+			throw error;
+		}
+	}, `UP migration ${migration.version}`);
+	else {
+		await executeStatements(conn, statements, `UP migration ${migration.version}`);
+		await withRetry(() => insertAppliedMigration(conn, migration, txMode, Date.now() - start, config), `record migration ${migration.version}`);
+	}
+	logger.log(`Applied ${migration.version}`);
+}
+async function markBaselineAsApplied(conn, migration, config, logger) {
+	await insertAppliedMigration(conn, migration, "baseline_mark", 0, config);
+	logger.log(`Baseline ${migration.version} marked as applied (existing schema detected)`);
+}
+async function applyDownMigration(conn, migration, logger) {
+	const statements = splitSqlStatements(migration.downSql);
+	if (statements.length === 0) throw new Error(`Migration ${migration.version} has empty down.sql`);
+	if (resolveTxMode(migration.downSql, statements) === "transactional") {
+		await conn.beginTransaction();
+		try {
+			await executeStatements(conn, statements, `DOWN migration ${migration.version}`);
+			await deleteAppliedMigration(conn, migration.version);
+			await conn.commit();
+		} catch (error) {
+			await conn.rollback();
+			throw error;
+		}
+	} else {
+		await executeStatements(conn, statements, `DOWN migration ${migration.version}`);
+		await deleteAppliedMigration(conn, migration.version);
+	}
+	logger.log(`Rolled back ${migration.version}`);
+}
+
+//#endregion
+//#region src/commands.ts
+const DEFAULT_BASELINE_VERSION = "001_baseline";
+function assertDevMigrationsAllowed(migrations, allowDev) {
+	if (allowDev) return;
+	const devVersions = migrations.filter((migration) => migration.isDev).map((migration) => migration.version);
+	if (devVersions.length === 0) return;
+	throw new Error(`Refusing to run "up" with unsealed dev migrations present: ${devVersions.join(", ")}. Only sealed (numbered) migrations may reach production. Seal them first. For local development pass allowDev / --allow-dev.`);
+}
+/** Next free number = max(numbered repo folders ∪ numbered applied versions) + 1. */
+function computeNextSealNumber(migrations, appliedVersions) {
+	let max = 0;
+	for (const migration of migrations) if (!migration.isDev && migration.sortNumber > max) max = migration.sortNumber;
+	for (const version of appliedVersions) {
+		const match = MIGRATION_DIR_PATTERN.exec(version);
+		if (match) {
+			const value = Number.parseInt(match[1] ?? "0", 10);
+			if (value > max) max = value;
+		}
+	}
+	return String(max + 1).padStart(3, "0");
+}
+async function commandCurrent(conn, migrations, logger) {
+	const applied = await getAppliedMigrations(conn);
+	validateAppliedState(migrations, applied, {}, logger);
+	const latestApplied = [...migrations].reverse().find((migration) => applied.has(migration.version));
+	logger.log(latestApplied?.version ?? "none");
+}
+async function commandStatus(conn, migrations, logger) {
+	const applied = await getAppliedMigrations(conn);
+	validateAppliedState(migrations, applied, {}, logger);
+	for (const migration of migrations) {
+		const status = applied.has(migration.version) ? "APPLIED" : "PENDING";
+		logger.log(`${status.padEnd(8, " ")} ${migration.version}  ${migration.description}`);
+	}
+	const repoVersions = new Set(migrations.map((migration) => migration.version));
+	for (const [version] of applied) if (!repoVersions.has(version) && isDevVersion(version)) logger.log(`FOREIGN  ${version}  (applied on this DB, missing in this worktree)`);
+}
+async function commandUp(conn, migrations, config, options, logger) {
+	if (migrations.length === 0) {
+		logger.log("No migrations found");
+		return;
+	}
+	const baselineVersion = config.baselineVersion ?? DEFAULT_BASELINE_VERSION;
+	if (baselineVersion && migrations[0]?.version !== baselineVersion) throw new Error(`Baseline migration must be the first migration (${baselineVersion})`);
+	const targetVersion = (options.to ?? "").trim();
+	const targetIndex = targetVersion ? migrations.findIndex((migration) => migration.version === targetVersion) : migrations.length - 1;
+	if (targetVersion && targetIndex < 0) throw new Error(`Target version not found: ${targetVersion}`);
+	const applied = await getAppliedMigrations(conn);
+	validateAppliedState(migrations, applied, {}, logger);
+	for (let index = 0; index <= targetIndex; index += 1) {
+		const migration = migrations[index];
+		if (!migration || applied.has(migration.version)) continue;
+		if (migration.version === baselineVersion) {
+			if (applied.size > 0) throw new Error("Baseline migration is pending but newer migrations are already applied. State is inconsistent.");
+			if (config.databaseName) {
+				if (await getSchemaHasUserTables(conn, config.databaseName)) {
+					await markBaselineAsApplied(conn, migration, config, logger);
+					applied.set(migration.version, { checksum: migration.checksum });
+					continue;
+				}
+			}
+		}
+		await applyUpMigration(conn, migration, config, logger);
+		applied.set(migration.version, { checksum: migration.checksum });
+	}
+	const latestApplied = [...migrations].reverse().find((migration) => applied.has(migration.version));
+	logger.log(`Current DB version: ${latestApplied?.version ?? "none"}`);
+}
+async function commandDown(conn, migrations, options, logger) {
+	const targetVersion = (options.to ?? "").trim();
+	if (!targetVersion) throw new Error("Rollback requires a target version (to / --to=<version>)");
+	const applied = await getAppliedMigrations(conn);
+	validateAppliedState(migrations, applied, { devChecksumMismatch: "warn" }, logger);
+	if (targetVersion !== "none" && !applied.has(targetVersion)) throw new Error(`Target version ${targetVersion} is not currently applied`);
+	const targetIndex = targetVersion === "none" ? -1 : migrations.findIndex((migration) => migration.version === targetVersion);
+	if (targetVersion !== "none" && targetIndex < 0) throw new Error(`Target version not found in repository: ${targetVersion}`);
+	const rollbackList = migrations.filter((migration, index) => index > targetIndex && applied.has(migration.version)).reverse();
+	if (rollbackList.length === 0) {
+		logger.log(`Nothing to rollback. Current DB already at ${targetVersion}`);
+		return;
+	}
+	for (const migration of rollbackList) await applyDownMigration(conn, migration, logger);
+	logger.log(`Rollback complete. Target DB version: ${targetVersion}`);
+}
+async function commandSeal(conn, migrations, migrationsDir, slug, logger) {
+	const devVersion = normalizeDevVersion(slug);
+	const migration = migrations.find((candidate) => candidate.version === devVersion);
+	if (!migration) throw new Error(`Dev migration not found: ${path.join(migrationsDir, devVersion)}`);
+	const applied = await getAppliedMigrations(conn);
+	const appliedRow = applied.get(devVersion);
+	const bareSlug = devVersion.slice(4);
+	if (appliedRow && appliedRow.checksum !== migration.checksum) throw new Error(`Checksum mismatch for ${devVersion}: the files differ from what was applied. Re-apply it (down + up) or rehash ${bareSlug} first.`);
+	const sealedVersion = `${computeNextSealNumber(migrations, [...applied.keys()])}_${bareSlug}`;
+	const devDir = path.join(migrationsDir, devVersion);
+	const sealedDir = path.join(migrationsDir, sealedVersion);
+	if (await fileExists(sealedDir)) throw new Error(`Cannot seal ${devVersion}: target directory already exists: ${sealedDir}`);
+	if (!appliedRow) {
+		await promises.rename(devDir, sealedDir);
+		logger.log(`Sealed ${devVersion} as ${sealedVersion} (not applied on this DB, folder renamed only)`);
+		logger.log("Commit the renamed folder before merging.");
+		return;
+	}
+	await conn.execute("UPDATE schema_migrations SET version = ?, description = ? WHERE version = ?", [
+		sealedVersion,
+		migration.description,
+		devVersion
+	]);
+	try {
+		await promises.rename(devDir, sealedDir);
+	} catch (renameError) {
+		const rename = renameError;
+		try {
+			await conn.execute("UPDATE schema_migrations SET version = ?, description = ? WHERE version = ?", [
+				devVersion,
+				migration.description,
+				sealedVersion
+			]);
+		} catch (revertError) {
+			const revert = revertError;
+			throw new Error(`Failed to rename ${devDir} to ${sealedDir} (${rename?.message}) AND failed to revert schema_migrations (${revert?.message}). Fix manually: UPDATE schema_migrations SET version = '${devVersion}' WHERE version = '${sealedVersion}'`, { cause: revertError });
+		}
+		throw new Error(`Failed to rename ${devDir} to ${sealedDir}: ${rename?.message}. schema_migrations was reverted to ${devVersion}.`, { cause: renameError });
+	}
+	logger.log(`Sealed ${devVersion} as ${sealedVersion} (schema_migrations updated)`);
+	logger.log("Commit the renamed folder before merging.");
+}
+async function commandRehash(conn, migrations, slug, logger) {
+	const devVersion = normalizeDevVersion(slug);
+	const migration = migrations.find((candidate) => candidate.version === devVersion);
+	if (!migration) throw new Error(`Dev migration not found in repository: ${devVersion}`);
+	const [rows] = await conn.execute("SELECT version, checksum FROM schema_migrations WHERE version = ?", [devVersion]);
+	if (!rows || rows.length === 0) throw new Error(`Dev migration ${devVersion} is not applied on this database. Nothing to rehash, run "up" instead.`);
+	if (rows[0]?.checksum === migration.checksum) {
+		logger.log(`Checksum for ${devVersion} is already up to date`);
+		return;
+	}
+	await conn.execute("UPDATE schema_migrations SET checksum = ? WHERE version = ?", [migration.checksum, devVersion]);
+	logger.log(`Updated checksum for ${devVersion} to match the current up.sql + down.sql content`);
+}
+
+//#endregion
+//#region src/runner.ts
+const DEFAULT_LOCK_NAME = "sealed-migrations:lock";
+const DEFAULT_LOCK_TIMEOUT_SEC = 120;
+/** Minimal `--flag`, `--key=value`, `--key value` and positional parser. */
+function parseArgs(argv) {
+	const args = {};
+	const positionals = [];
+	for (let i = 0; i < argv.length; i += 1) {
+		const token = argv[i] ?? "";
+		if (!token.startsWith("--")) {
+			positionals.push(token);
+			continue;
+		}
+		const eqIndex = token.indexOf("=");
+		if (eqIndex >= 0) {
+			args[token.slice(2, eqIndex)] = token.slice(eqIndex + 1);
+			continue;
+		}
+		const key = token.slice(2);
+		const next = argv[i + 1];
+		if (next && !next.startsWith("--")) {
+			args[key] = next;
+			i += 1;
+		} else args[key] = true;
+	}
+	return {
+		args,
+		positionals
+	};
+}
+function usage() {
+	return [
+		"Usage:",
+		"  up [--allow-dev] [--to=<version>]",
+		"  down --to=<version>",
+		"  seal <slug>",
+		"  rehash <slug>",
+		"  current",
+		"  status",
+		"",
+		"Dev migrations (dev_<slug>/) apply after all numbered migrations,",
+		"alphabetically. \"up\" refuses them without --allow-dev.",
+		"\"seal <slug>\" assigns the next free number right before merge.",
+		"\"rehash <slug>\" aligns the stored checksum after a manual schema change."
+	].join("\n");
+}
+function strOpt(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function createRunner(config) {
+	const logger = config.logger ?? console;
+	const lockName = config.lockName ?? DEFAULT_LOCK_NAME;
+	const lockTimeoutSec = config.lockTimeoutSec ?? DEFAULT_LOCK_TIMEOUT_SEC;
+	const migrationsDir = path.resolve(process.cwd(), config.migrationsDir);
+	async function withConnection(useLock, fn) {
+		const conn = await config.connect();
+		let lockAcquired = false;
+		try {
+			if (config.assertServer) await config.assertServer(conn);
+			await ensureSchemaMigrationsTable(conn);
+			if (useLock) {
+				await acquireLock(conn, lockName, lockTimeoutSec);
+				lockAcquired = true;
+			}
+			return await fn(conn);
+		} finally {
+			if (lockAcquired) await releaseLock(conn, lockName);
+			if (conn.end) await conn.end();
+		}
+	}
+	const runner = {
+		async up(options = {}) {
+			const migrations = await readMigrations(migrationsDir);
+			assertDevMigrationsAllowed(migrations, Boolean(options.allowDev));
+			await withConnection(true, (conn) => commandUp(conn, migrations, config, options, logger));
+		},
+		async down(options) {
+			const migrations = await readMigrations(migrationsDir);
+			await withConnection(true, (conn) => commandDown(conn, migrations, options, logger));
+		},
+		async seal(slug) {
+			const migrations = await readMigrations(migrationsDir);
+			await withConnection(true, (conn) => commandSeal(conn, migrations, migrationsDir, slug, logger));
+		},
+		async rehash(slug) {
+			const migrations = await readMigrations(migrationsDir);
+			await withConnection(true, (conn) => commandRehash(conn, migrations, slug, logger));
+		},
+		async current() {
+			const migrations = await readMigrations(migrationsDir);
+			await withConnection(false, (conn) => commandCurrent(conn, migrations, logger));
+		},
+		async status() {
+			const migrations = await readMigrations(migrationsDir);
+			await withConnection(false, (conn) => commandStatus(conn, migrations, logger));
+		},
+		async runCli(argv) {
+			const { args, positionals } = parseArgs(argv);
+			const command = positionals[0] ?? "";
+			if (args.help || args.h || command === "help" || command === "-h") {
+				logger.log(usage());
+				return;
+			}
+			if (!command) {
+				logger.log(usage());
+				throw new Error("No command given");
+			}
+			switch (command) {
+				case "up":
+					await runner.up({
+						to: strOpt(args.to),
+						allowDev: Boolean(args["allow-dev"])
+					});
+					return;
+				case "down":
+					await runner.down({ to: strOpt(args.to) });
+					return;
+				case "seal":
+					await runner.seal(strOpt(args.slug) ?? positionals[1] ?? "");
+					return;
+				case "rehash":
+					await runner.rehash(strOpt(args.slug) ?? positionals[1] ?? "");
+					return;
+				case "current":
+					await runner.current();
+					return;
+				case "status":
+					await runner.status();
+					return;
+				default: throw new Error(`Unknown command: ${command}`);
+			}
+		}
+	};
+	return runner;
+}
+
+//#endregion
+export { DEV_MIGRATION_DIR_PATTERN, MIGRATION_DIR_PATTERN, assertDevMigrationsAllowed, commandCurrent, commandDown, commandRehash, commandSeal, commandStatus, commandUp, computeNextSealNumber, createRunner, hashMigration, isDevVersion, normalizeDevVersion, parseArgs, parseMigrationDirName, readMigrations, resolveTxMode, splitSqlStatements, validateAppliedState };