better-convex 0.7.2 → 0.8.0

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as getConvexConfig, t as generateMeta } from "./codegen-Cz1idI3-.mjs";
+import { n as getConvexConfig, t as generateMeta } from "./codegen-BS36cYTH.mjs";
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
@@ -232,6 +232,7 @@ const EnableRLS = Symbol.for("better-convex:EnableRLS");
 const TableDeleteConfig = Symbol.for("better-convex:TableDeleteConfig");
 const OrmSchemaOptions = Symbol.for("better-convex:OrmSchemaOptions");
 const OrmSchemaDefinition = Symbol.for("better-convex:OrmSchemaDefinition");
+const OrmSchemaPluginTables = Symbol.for("better-convex:OrmSchemaPluginTables");
 
 //#endregion
 //#region src/orm/mutation-utils.ts
@@ -1784,6 +1785,15 @@ function createDefaultConfig() {
 				pollIntervalMs: 1e3,
 				timeoutMs: 9e5,
 				strict: false
+			},
+			migrations: {
+				enabled: "auto",
+				wait: true,
+				batchSize: 256,
+				pollIntervalMs: 1e3,
+				timeoutMs: 9e5,
+				strict: false,
+				allowDrift: true
 			}
 		},
 		codegen: {
@@ -1799,6 +1809,15 @@ function createDefaultConfig() {
 				pollIntervalMs: 1e3,
 				timeoutMs: 9e5,
 				strict: true
+			},
+			migrations: {
+				enabled: "auto",
+				wait: true,
+				batchSize: 256,
+				pollIntervalMs: 1e3,
+				timeoutMs: 9e5,
+				strict: true,
+				allowDrift: false
 			}
 		}
 	};
@@ -1843,6 +1862,18 @@ function parseAggregateBackfillConfig(value, fieldName, configPath) {
 	if ("strict" in value) parsed.strict = parseBoolean(value.strict, `${fieldName}.strict`, configPath);
 	return parsed;
 }
+function parseMigrationConfig(value, fieldName, configPath) {
+	if (!isRecord(value)) throw new Error(`Invalid ${fieldName} in ${configPath}: expected object.`);
+	const parsed = {};
+	if ("enabled" in value) parsed.enabled = parseBackfillEnabled(value.enabled, `${fieldName}.enabled`, configPath);
+	if ("wait" in value) parsed.wait = parseBoolean(value.wait, `${fieldName}.wait`, configPath);
+	if ("batchSize" in value) parsed.batchSize = parsePositiveInteger(value.batchSize, `${fieldName}.batchSize`, configPath);
+	if ("pollIntervalMs" in value) parsed.pollIntervalMs = parsePositiveInteger(value.pollIntervalMs, `${fieldName}.pollIntervalMs`, configPath);
+	if ("timeoutMs" in value) parsed.timeoutMs = parsePositiveInteger(value.timeoutMs, `${fieldName}.timeoutMs`, configPath);
+	if ("strict" in value) parsed.strict = parseBoolean(value.strict, `${fieldName}.strict`, configPath);
+	if ("allowDrift" in value) parsed.allowDrift = parseBoolean(value.allowDrift, `${fieldName}.allowDrift`, configPath);
+	return parsed;
+}
 function parseCommandConfig(value, fieldName, configPath) {
 	if (!isRecord(value)) throw new Error(`Invalid ${fieldName} in ${configPath}: expected object.`);
 	const parsed = {};
@@ -1850,6 +1881,7 @@ function parseCommandConfig(value, fieldName, configPath) {
 	if ("convexArgs" in value) parsed.convexArgs = parseStringArray(value.convexArgs, `${fieldName}.convexArgs`, configPath);
 	if (fieldName === "codegen" && "scope" in value && value.scope !== void 0) parsed.scope = parseScope(value.scope, `${fieldName}.scope`, configPath);
 	if (fieldName === "dev" && "aggregateBackfill" in value && value.aggregateBackfill !== void 0) parsed.aggregateBackfill = parseAggregateBackfillConfig(value.aggregateBackfill, `${fieldName}.aggregateBackfill`, configPath);
+	if (fieldName === "dev" && "migrations" in value && value.migrations !== void 0) parsed.migrations = parseMigrationConfig(value.migrations, `${fieldName}.migrations`, configPath);
 	return parsed;
 }
 function parseDeployConfig(value, configPath) {
@@ -1857,6 +1889,7 @@ function parseDeployConfig(value, configPath) {
 	const parsed = {};
 	if ("convexArgs" in value) parsed.convexArgs = parseStringArray(value.convexArgs, "deploy.convexArgs", configPath);
 	if ("aggregateBackfill" in value && value.aggregateBackfill !== void 0) parsed.aggregateBackfill = parseAggregateBackfillConfig(value.aggregateBackfill, "deploy.aggregateBackfill", configPath);
+	if ("migrations" in value && value.migrations !== void 0) parsed.migrations = parseMigrationConfig(value.migrations, "deploy.migrations", configPath);
 	return parsed;
 }
 function loadBetterConvexConfig(configPathArg) {
@@ -1885,6 +1918,10 @@ function loadBetterConvexConfig(configPathArg) {
 			...config.dev.aggregateBackfill,
 			...parsed.aggregateBackfill
 		};
+		if (parsed.migrations !== void 0) config.dev.migrations = {
+			...config.dev.migrations,
+			...parsed.migrations
+		};
 	}
 	if ("codegen" in rawConfig) {
 		const parsed = parseCommandConfig(rawConfig.codegen, "codegen", resolvedConfigPath);
@@ -1899,6 +1936,10 @@ function loadBetterConvexConfig(configPathArg) {
 			...config.deploy.aggregateBackfill,
 			...parsed.aggregateBackfill
 		};
+		if (parsed.migrations !== void 0) config.deploy.migrations = {
+			...config.deploy.migrations,
+			...parsed.migrations
+		};
 	}
 	return config;
 }
@@ -2009,6 +2050,7 @@ const __dirname = dirname(__filename);
 const realConvex = join(dirname(createRequire(import.meta.url).resolve("convex/package.json")), "bin/main.js");
 const MISSING_BACKFILL_FUNCTION_RE = /could not find function|function .* was not found|unknown function/i;
 const GITIGNORE_CONVEX_ENTRY_RE = /(^|\r?\n)\.convex\/?\s*(\r?\n|$)/m;
+const TS_EXTENSION_RE = /\.ts$/;
 const AGGREGATE_STATE_RELATIVE_PATH = join(".convex", "better-convex", "aggregate-backfill-state.json");
 const AGGREGATE_STATE_VERSION = 1;
 const VALID_SCOPES = new Set([
@@ -2290,6 +2332,85 @@ function extractBackfillCliOptions(args) {
 		overrides
 	};
 }
+function extractMigrationCliOptions(args) {
+	const remainingArgs = [];
+	const overrides = {};
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--migrations") {
+			const { value, nextIndex } = readFlagValue(args, i, "--migrations");
+			if (!VALID_BACKFILL_ENABLED.has(value)) throw new Error("Invalid --migrations value. Expected auto, on, or off.");
+			overrides.enabled = value;
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--migrations=")) {
+			const value = arg.slice(13);
+			if (!VALID_BACKFILL_ENABLED.has(value)) throw new Error("Invalid --migrations value. Expected auto, on, or off.");
+			overrides.enabled = value;
+			continue;
+		}
+		if (arg === "--migrations-wait") {
+			overrides.wait = true;
+			continue;
+		}
+		if (arg === "--no-migrations-wait") {
+			overrides.wait = false;
+			continue;
+		}
+		if (arg === "--migrations-strict") {
+			overrides.strict = true;
+			continue;
+		}
+		if (arg === "--no-migrations-strict") {
+			overrides.strict = false;
+			continue;
+		}
+		if (arg === "--migrations-allow-drift") {
+			overrides.allowDrift = true;
+			continue;
+		}
+		if (arg === "--no-migrations-allow-drift") {
+			overrides.allowDrift = false;
+			continue;
+		}
+		if (arg === "--migrations-batch-size") {
+			const { value, nextIndex } = readFlagValue(args, i, "--migrations-batch-size");
+			overrides.batchSize = parsePositiveIntegerArg("--migrations-batch-size", value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--migrations-batch-size=")) {
+			overrides.batchSize = parsePositiveIntegerArg("--migrations-batch-size", arg.slice(24));
+			continue;
+		}
+		if (arg === "--migrations-timeout-ms") {
+			const { value, nextIndex } = readFlagValue(args, i, "--migrations-timeout-ms");
+			overrides.timeoutMs = parsePositiveIntegerArg("--migrations-timeout-ms", value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--migrations-timeout-ms=")) {
+			overrides.timeoutMs = parsePositiveIntegerArg("--migrations-timeout-ms", arg.slice(24));
+			continue;
+		}
+		if (arg === "--migrations-poll-ms") {
+			const { value, nextIndex } = readFlagValue(args, i, "--migrations-poll-ms");
+			overrides.pollIntervalMs = parsePositiveIntegerArg("--migrations-poll-ms", value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--migrations-poll-ms=")) {
+			overrides.pollIntervalMs = parsePositiveIntegerArg("--migrations-poll-ms", arg.slice(21));
+			continue;
+		}
+		remainingArgs.push(arg);
+	}
+	return {
+		remainingArgs,
+		overrides
+	};
+}
 function extractResetCliOptions(args) {
 	const remainingArgs = [];
 	let confirmed = false;
@@ -2355,6 +2476,27 @@ function resolveBackfillConfig(base, overrides) {
 		strict: overrides.strict ?? resolvedBase.strict
 	};
 }
+function resolveMigrationConfig(base, overrides) {
+	const resolvedBase = base ?? {
+		enabled: "auto",
+		wait: true,
+		batchSize: 256,
+		timeoutMs: 9e5,
+		pollIntervalMs: 1e3,
+		strict: false,
+		allowDrift: true
+	};
+	return {
+		...resolvedBase,
+		enabled: overrides.enabled ?? resolvedBase.enabled,
+		wait: overrides.wait ?? resolvedBase.wait,
+		batchSize: overrides.batchSize ?? resolvedBase.batchSize,
+		timeoutMs: overrides.timeoutMs ?? resolvedBase.timeoutMs,
+		pollIntervalMs: overrides.pollIntervalMs ?? resolvedBase.pollIntervalMs,
+		strict: overrides.strict ?? resolvedBase.strict,
+		allowDrift: overrides.allowDrift ?? resolvedBase.allowDrift
+	};
+}
 function extractRunDeploymentArgs(args) {
 	const deploymentArgs = [];
 	for (let i = 0; i < args.length; i += 1) {
@@ -2505,6 +2647,179 @@ async function runAggregatePruneFlow(params) {
 	else console.info("ℹ️  aggregateBackfill prune no-op");
 	return 0;
 }
+function slugifyMigrationName(name) {
+	return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function createMigrationTimestamp(now = /* @__PURE__ */ new Date()) {
+	return `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, "0")}${String(now.getUTCDate()).padStart(2, "0")}_${String(now.getUTCHours()).padStart(2, "0")}${String(now.getUTCMinutes()).padStart(2, "0")}${String(now.getUTCSeconds()).padStart(2, "0")}`;
+}
+function extractMigrationDownOptions(args) {
+	const remainingArgs = [];
+	let steps;
+	let to;
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--steps") {
+			const { value, nextIndex } = readFlagValue(args, i, "--steps");
+			steps = parsePositiveIntegerArg("--steps", value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--steps=")) {
+			steps = parsePositiveIntegerArg("--steps", arg.slice(8));
+			continue;
+		}
+		if (arg === "--to") {
+			const { value, nextIndex } = readFlagValue(args, i, "--to");
+			to = value;
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--to=")) {
+			const value = arg.slice(5);
+			if (!value) throw new Error("Missing value for --to.");
+			to = value;
+			continue;
+		}
+		remainingArgs.push(arg);
+	}
+	if (steps !== void 0 && to !== void 0) throw new Error("Use either --steps or --to, not both.");
+	return {
+		remainingArgs,
+		steps,
+		to
+	};
+}
+function renderMigrationManifest(ids) {
+	const sorted = [...new Set(ids)].sort((a, b) => a.localeCompare(b));
+	const importLines = sorted.map((id, index) => `import { migration as migration_${index} } from './${id}';`);
+	const entryLines = sorted.map((_, index) => `  migration_${index},`);
+	return `// biome-ignore-all format: generated
+// This file is auto-generated by better-convex migrate create.
+// Do not edit manually.
+
+import { defineMigrationSet } from 'better-convex/orm';
+${importLines.join("\n")}
+
+export const migrations = defineMigrationSet([
+${entryLines.join("\n")}
+]);
+`;
+}
+async function runMigrationCreate(params) {
+	const { migrationName, functionsDir } = params;
+	const normalizedName = slugifyMigrationName(migrationName);
+	if (!normalizedName) throw new Error("Migration name must include at least one letter or digit.");
+	const migrationId = `${createMigrationTimestamp()}_${normalizedName}`;
+	const migrationsDir = join(functionsDir, "migrations");
+	const migrationFile = join(migrationsDir, `${migrationId}.ts`);
+	const manifestFile = join(migrationsDir, "manifest.ts");
+	fs.mkdirSync(migrationsDir, { recursive: true });
+	if (fs.existsSync(migrationFile)) throw new Error(`Migration file already exists for '${migrationId}'. Wait one second and retry.`);
+	const migrationSource = `import { defineMigration } from '../generated/migrations.gen';
+
+export const migration = defineMigration({
+  id: '${migrationId}',
+  description: '${migrationName.replaceAll("'", "\\'")}',
+  up: {
+    table: 'replace_with_table_name',
+    migrateOne: async () => {
+      // TODO: implement migration logic.
+    },
+  },
+  down: {
+    table: 'replace_with_table_name',
+    migrateOne: async () => {
+      // TODO: implement rollback logic.
+    },
+  },
+});
+`;
+	fs.writeFileSync(migrationFile, migrationSource);
+	const existingMigrationIds = fs.readdirSync(migrationsDir).filter((file) => file.endsWith(".ts")).map((file) => file.replace(TS_EXTENSION_RE, "")).filter((id) => id !== "manifest").sort((a, b) => a.localeCompare(b));
+	fs.writeFileSync(manifestFile, renderMigrationManifest(existingMigrationIds));
+	console.info(`ℹ️  created migration ${migrationId}`);
+	console.info(`ℹ️  file: ${migrationFile}`);
+	console.info(`ℹ️  manifest: ${manifestFile}`);
+}
+async function runMigrationFlow(params) {
+	const { execaFn, realConvexPath, migrationConfig, deploymentArgs, signal, context, direction, steps, to } = params;
+	if (signal?.aborted || migrationConfig.enabled === "off") return 0;
+	const kickoff = await runConvexFunction(execaFn, realConvexPath, "generated/server:migrationRun", {
+		direction,
+		batchSize: migrationConfig.batchSize,
+		allowDrift: migrationConfig.allowDrift,
+		...steps !== void 0 ? { steps } : {},
+		...to !== void 0 ? { to } : {}
+	}, deploymentArgs, { echoOutput: false });
+	if (kickoff.exitCode !== 0) {
+		const combinedOutput = `${kickoff.stdout}\n${kickoff.stderr}`;
+		if (migrationConfig.enabled === "auto" && isMissingBackfillFunctionOutput(combinedOutput)) {
+			if (context === "deploy") console.info("ℹ️  migration runtime not found in this deployment; skipping (auto mode).");
+			return 0;
+		}
+		return kickoff.exitCode;
+	}
+	const payload = parseConvexRunJson(kickoff.stdout);
+	const kickoffStatus = typeof payload === "object" && payload !== null && !Array.isArray(payload) && typeof payload.status === "string" ? payload.status : "running";
+	const driftMessages = typeof payload === "object" && payload !== null && !Array.isArray(payload) && Array.isArray(payload.drift) ? payload.drift.map((entry) => entry?.message).filter((entry) => typeof entry === "string") : [];
+	if (kickoffStatus === "drift_blocked") {
+		const message = driftMessages[0] ?? "Migration drift detected and blocked by current policy.";
+		if (migrationConfig.strict) {
+			console.error(`❌ ${message}`);
+			return 1;
+		}
+		console.warn(`⚠️  ${message}`);
+		return 0;
+	}
+	if (kickoffStatus === "noop") {
+		const noopMessage = direction === "down" ? "No applied migrations to roll back." : "No pending migrations to apply.";
+		console.info(`ℹ️  ${noopMessage}`);
+		return 0;
+	}
+	if (kickoffStatus === "dry_run") {
+		console.info("ℹ️  migration dry run completed (no writes committed).");
+		return 0;
+	}
+	const runId = typeof payload === "object" && payload !== null && !Array.isArray(payload) && typeof payload.runId === "string" ? payload.runId : void 0;
+	if (!migrationConfig.wait || signal?.aborted || !runId) return 0;
+	const deadline = Date.now() + migrationConfig.timeoutMs;
+	let lastStatusLine = "";
+	while (!signal?.aborted) {
+		const statusResult = await runConvexFunction(execaFn, realConvexPath, "generated/server:migrationStatus", { runId }, deploymentArgs, { echoOutput: false });
+		if (statusResult.exitCode !== 0) return statusResult.exitCode;
+		const statusPayload = parseConvexRunJson(statusResult.stdout);
+		const runStatus = typeof statusPayload === "object" && statusPayload !== null && !Array.isArray(statusPayload) ? statusPayload.activeRun?.status ?? statusPayload.runs?.[0]?.status ?? "unknown" : "unknown";
+		const currentIndex = typeof statusPayload === "object" && statusPayload !== null && !Array.isArray(statusPayload) && typeof statusPayload.runs?.[0]?.currentIndex === "number" ? statusPayload.runs[0].currentIndex : 0;
+		const total = typeof statusPayload === "object" && statusPayload !== null && !Array.isArray(statusPayload) && Array.isArray(statusPayload.runs?.[0]?.migrationIds) ? statusPayload.runs?.[0]?.migrationIds?.length ?? 0 : 0;
+		const statusLine = `${runStatus}:${currentIndex}/${total}`;
+		if (statusLine !== lastStatusLine && total > 0) {
+			lastStatusLine = statusLine;
+			console.info(`ℹ️  migration ${runStatus} ${currentIndex}/${total}`);
+		}
+		if (runStatus === "completed" || runStatus === "noop") return 0;
+		if (runStatus === "failed" || runStatus === "canceled") {
+			const message = `Migrations ${runStatus} for run ${runId}.`;
+			if (migrationConfig.strict) {
+				console.error(`❌ ${message}`);
+				return 1;
+			}
+			console.warn(`⚠️  ${message}`);
+			return 0;
+		}
+		if (Date.now() > deadline) {
+			const timeoutMessage = `Migrations timed out after ${migrationConfig.timeoutMs}ms.`;
+			if (migrationConfig.strict) {
+				console.error(`❌ ${timeoutMessage}`);
+				return 1;
+			}
+			console.warn(`⚠️  ${timeoutMessage}`);
+			return 0;
+		}
+		await sleep(migrationConfig.pollIntervalMs, signal);
+	}
+	return 0;
+}
 async function runDevSchemaBackfillIfNeeded(params) {
 	const { execaFn, realConvexPath, backfillConfig, functionsDir, deploymentArgs, signal } = params;
 	const fingerprint = await computeAggregateIndexFingerprint(functionsDir);
@@ -2551,13 +2866,15 @@ async function run(argv, deps) {
 	if (command === "dev") {
 		if (cliScope) throw new Error("`--scope` is not supported for `better-convex dev`. Use `better-convex codegen --scope <all|auth|orm>` for scoped generation.");
 		const config = loadBetterConvexConfigFn(configPath);
-		const { remainingArgs: devCommandArgs, overrides: devBackfillOverrides } = extractBackfillCliOptions(convexArgs);
+		const { remainingArgs: devArgsWithoutMigrationFlags, overrides: devMigrationOverrides } = extractMigrationCliOptions(convexArgs);
+		const { remainingArgs: devCommandArgs, overrides: devBackfillOverrides } = extractBackfillCliOptions(devArgsWithoutMigrationFlags);
 		const outputDir = cliOutputDir ?? config.outputDir;
 		const debug = cliDebug || config.dev.debug;
 		const generateApi = config.api;
 		const generateAuth = config.auth;
 		const convexDevArgs = [...config.dev.convexArgs, ...devCommandArgs];
 		const devBackfillConfig = resolveBackfillConfig(config.dev.aggregateBackfill, devBackfillOverrides);
+		const devMigrationConfig = resolveMigrationConfig(config.dev.migrations, devMigrationOverrides);
 		const { functionsDir } = getConvexConfigFn(outputDir);
 		const schemaPath = join(functionsDir, "schema.ts");
 		const deploymentArgs = extractRunDeploymentArgs(convexDevArgs);
@@ -2627,6 +2944,21 @@ async function run(argv, deps) {
 				schemaBackfillInFlight = null;
 			});
 		};
+		if (devMigrationConfig.enabled !== "off") (async () => {
+			try {
+				if (await runMigrationFlow({
+					execaFn,
+					realConvexPath,
+					migrationConfig: devMigrationConfig,
+					deploymentArgs,
+					signal: backfillAbortController.signal,
+					context: "dev",
+					direction: "up"
+				}) !== 0 && !backfillAbortController.signal.aborted) console.warn("⚠️  migration up failed in dev (continuing without blocking).");
+			} catch (error) {
+				if (!backfillAbortController.signal.aborted) console.warn(`⚠️  migration up errored in dev: ${error.message}`);
+			}
+		})();
 		if (devBackfillConfig.enabled !== "off") (async () => {
 			try {
 				if (await runAggregateBackfillFlow({
@@ -2760,7 +3092,8 @@ async function run(argv, deps) {
 	}
 	if (command === "deploy") {
 		const config = loadBetterConvexConfigFn(configPath);
-		const { remainingArgs: deployCommandArgs, overrides: deployBackfillOverrides } = extractBackfillCliOptions(convexArgs);
+		const { remainingArgs: deployArgsWithoutMigrationFlags, overrides: deployMigrationOverrides } = extractMigrationCliOptions(convexArgs);
+		const { remainingArgs: deployCommandArgs, overrides: deployBackfillOverrides } = extractBackfillCliOptions(deployArgsWithoutMigrationFlags);
 		const deployArgs = [...config.deploy.convexArgs, ...deployCommandArgs];
 		const deployResult = await execaFn("node", [
 			realConvexPath,
@@ -2772,15 +3105,91 @@ async function run(argv, deps) {
 			reject: false
 		});
 		if ((deployResult.exitCode ?? 1) !== 0) return deployResult.exitCode ?? 1;
+		const migrationConfig = resolveMigrationConfig(config.deploy.migrations, deployMigrationOverrides);
+		const backfillConfig = resolveBackfillConfig(config.deploy.aggregateBackfill, deployBackfillOverrides);
+		const deploymentArgs = extractRunDeploymentArgs(deployArgs);
+		const migrationExitCode = await runMigrationFlow({
+			execaFn,
+			realConvexPath,
+			migrationConfig,
+			deploymentArgs,
+			context: "deploy",
+			direction: "up"
+		});
+		if (migrationExitCode !== 0) return migrationExitCode;
 		return runAggregateBackfillFlow({
 			execaFn,
 			realConvexPath,
-			backfillConfig: resolveBackfillConfig(config.deploy.aggregateBackfill, deployBackfillOverrides),
+			backfillConfig,
 			mode: "resume",
-			deploymentArgs: extractRunDeploymentArgs(deployArgs),
+			deploymentArgs,
 			context: "deploy"
 		});
 	}
+	if (command === "migrate") {
+		const subcommand = restArgs[0];
+		if (subcommand !== "create" && subcommand !== "up" && subcommand !== "down" && subcommand !== "status" && subcommand !== "cancel") throw new Error("Unknown migrate command. Use: `better-convex migrate create|up|down|status|cancel`.");
+		const config = loadBetterConvexConfigFn(configPath);
+		if (subcommand === "create") {
+			const rawName = restArgs.slice(1).join(" ").trim();
+			if (!rawName) throw new Error("Missing migration name. Usage: `better-convex migrate create <name>`.");
+			const { functionsDir } = getConvexConfigFn(cliOutputDir ?? config.outputDir);
+			await runMigrationCreate({
+				migrationName: rawName,
+				functionsDir
+			});
+			return 0;
+		}
+		const { remainingArgs: migrationCommandArgs, overrides: migrationOverrides } = extractMigrationCliOptions(restArgs.slice(1));
+		const migrationConfig = {
+			...resolveMigrationConfig(config.deploy.migrations, migrationOverrides),
+			enabled: "on"
+		};
+		const commandArgs = [...config.deploy.convexArgs, ...migrationCommandArgs];
+		const deploymentArgs = extractRunDeploymentArgs(commandArgs);
+		if (subcommand === "up") return runMigrationFlow({
+			execaFn,
+			realConvexPath,
+			migrationConfig,
+			deploymentArgs,
+			context: "migration",
+			direction: "up"
+		});
+		if (subcommand === "down") {
+			const { remainingArgs, steps, to } = extractMigrationDownOptions(commandArgs);
+			return runMigrationFlow({
+				execaFn,
+				realConvexPath,
+				migrationConfig,
+				deploymentArgs: extractRunDeploymentArgs(remainingArgs),
+				context: "migration",
+				direction: "down",
+				steps,
+				to
+			});
+		}
+		if (subcommand === "status") return (await runConvexFunction(execaFn, realConvexPath, "generated/server:migrationStatus", {}, deploymentArgs)).exitCode;
+		let runId;
+		const cancelArgs = [];
+		for (let i = 0; i < commandArgs.length; i += 1) {
+			const arg = commandArgs[i];
+			if (arg === "--run-id") {
+				const { value, nextIndex } = readFlagValue(commandArgs, i, "--run-id");
+				runId = value;
+				i = nextIndex;
+				continue;
+			}
+			if (arg.startsWith("--run-id=")) {
+				const value = arg.slice(9);
+				if (!value) throw new Error("Missing value for --run-id.");
+				runId = value;
+				continue;
+			}
+			cancelArgs.push(arg);
+		}
+		const cancelDeploymentArgs = extractRunDeploymentArgs(cancelArgs);
+		return (await runConvexFunction(execaFn, realConvexPath, "generated/server:migrationCancel", runId ? { runId } : {}, cancelDeploymentArgs)).exitCode;
+	}
 	if (command === "aggregate") {
 		const subcommand = restArgs[0];
 		if (subcommand !== "rebuild" && subcommand !== "backfill" && subcommand !== "prune") throw new Error("Unknown aggregate command. Use: `better-convex aggregate backfill`, `better-convex aggregate rebuild`, or `better-convex aggregate prune`.");