@prisma/orm-toolchain 0.16.0-dev.36

package/dist/migration-plan-q_L84PN1-BWE0LTH6.mjs

@@ -0,0 +1,759 @@
+import { t as MigrationToolsError } from "./errors-IpZm1Skp-BH495dRd.mjs";
+import { a as snapshotsImportPathFrom, o as writeContractSnapshot } from "./contract-snapshot-store-sf5nP4mb-MLpG-ihh.mjs";
+import { t as computeMigrationHash } from "./hash-DH8hl5Rq-BpM2t3Nu.mjs";
+import { t as deriveProvidedInvariants } from "./invariants-lXzy6txi-DAoP4nTE.mjs";
+import { i as materialiseExtensionMigrationPackageIfMissing, r as formatMigrationDirName, u as writeMigrationPackage } from "./io-C8TdyBKt-DloEBi70.mjs";
+import { r as findLatestMigration } from "./migration-graph-CBf9ORe7-B4xAF8GN.mjs";
+import { c as spaceMigrationDirectory, s as readContractSpaceHeadRef } from "./verify-contract-spaces-BZDcJsuA-De8v4Z4T.mjs";
+import { i as emitContractSpaceArtifacts, o as planAllSpaces } from "./spaces-C27bA-xc.mjs";
+import { C as errorPlanForgotTheFlag, K as getTargetMigrations, N as errorUnexpected, Q as mapRefResolutionError, W as formatStyledHeader, Z as mapMigrationToolsError, at as resolveMigrationPaths, ct as setCommandExamples, d as errorContractValidationFailed, h as errorFileNotFound, it as resolveContractPath, j as errorTargetMigrationNotSupported, k as errorSnapshotMissing, o as createTerminalUI, q as handleResult, r as addGlobalOptions, st as setCommandDescriptions, t as CliStructuredError$1, tt as parseGlobalFlagsOrExit, x as errorMigrationPlanningFailed } from "./command-helpers-CAoXqAY9-DWUBcTXM.mjs";
+import { t as assertFrameworkComponentsCompatible } from "./framework-components-CjshQKHA-Dlp6Leo5.mjs";
+import { t as createProjectSpecifierResolver } from "./project-import-root-CpwLCDLY-DkVwAnWj.mjs";
+import { r as getEmittedArtifactPaths } from "./exports-D3-NwrMA-CadaBGQ3.mjs";
+import { r as loadConfig } from "./exports-Dl2aGAk7.mjs";
+import { n as isGraphNode, t as assertHashIsGraphNode } from "./graph-membership-DW6nnbyQ-Bp2KcVwR.mjs";
+import { c as toExtensionInputs, i as loadContractSpaceAggregateForCli, t as buildContractSpaceAggregate } from "./contract-space-aggregate-loader-CFH-336b-BhAyRQEL.mjs";
+import { n as parseContractRef } from "./ref-resolution-BjJBWPjX.mjs";
+import { i as writeMigrationTs } from "./migration-ts-FyF55c4M.mjs";
+import { t as mapContractAtError } from "./contract-at-errors-BX7w-p19-SxA8eaV2.mjs";
+import { notOk, ok } from "@prisma/orm-framework/utils/result";
+import { join, relative } from "pathe";
+import { readFile } from "node:fs/promises";
+import { createControlStack, hasOperationPreview } from "@prisma/orm-framework/components/control";
+import { Command } from "commander";
+//#region ../../../1-framework/3-tooling/cli/dist/migration-plan-q_L84PN1.mjs
+/**
+* Phase-1 of the two-phase `migration plan` pipeline (sub-spec § 4).
+*
+* For every extension that exposes a `contractSpace`:
+*
+* 1. Read the on-disk head ref (returns `null` on first emit).
+* 2. Write the head contract into the migrations-root snapshot store
+*    (write-if-absent, keyed by hash) and unconditionally re-emit
+*    `refs/head.json`, via {@link emitContractSpaceArtifacts}. The
+*    framework owns `refs/head.json`; re-emit is the contract for that
+*    file. The snapshot itself is only written once per distinct hash.
+* 3. Materialise any descriptor-shipped migration packages not yet on
+*    disk via {@link materialiseExtensionMigrationPackageIfMissing}.
+*    Existing packages are left untouched (by-existence skip).
+*
+* The return value lets the caller render a per-space status line and
+* lets the phase-2 aggregate loader run on a now-consistent disk state
+* (every loaded extension is guaranteed to have its head ref pinned
+* to the descriptor's hash and to ship every package the descriptor
+* declares).
+*
+* Output ordering is deterministic and alphabetical by spaceId (via
+* {@link planAllSpaces}, which also detects duplicate spaceIds). This
+* matches the canonical sort order used by every other aggregate
+* surface (`migrate`, `migration status`, the runner).
+*/
+async function runContractSpaceSeedPhase(inputs) {
+	const planned = planAllSpaces(inputs.extensions.filter((pack) => pack.contractSpace !== void 0).map((pack) => ({
+		spaceId: pack.id,
+		priorContract: null,
+		newContract: pack.contractSpace.contractJson,
+		__pack: pack.contractSpace
+	})), (input) => input.__pack.migrations);
+	const descriptorBySpace = /* @__PURE__ */ new Map();
+	for (const pack of inputs.extensions) if (pack.contractSpace !== void 0) descriptorBySpace.set(pack.id, pack.contractSpace);
+	const seeded = [];
+	for (const space of planned) {
+		const descriptor = descriptorBySpace.get(space.spaceId);
+		if (descriptor === void 0) continue;
+		const priorHash = (await readContractSpaceHeadRef(inputs.migrationsDir, space.spaceId))?.hash ?? null;
+		await emitContractSpaceArtifacts(inputs.migrationsDir, space.spaceId, {
+			contract: descriptor.contractJson,
+			contractDts: buildPlaceholderContractDts(space.spaceId),
+			headRef: {
+				hash: descriptor.headRef.hash,
+				invariants: descriptor.headRef.invariants
+			}
+		});
+		const spaceDir = spaceMigrationDirectory(inputs.migrationsDir, space.spaceId);
+		const newMigrationDirs = [];
+		for (const pkg of space.migrationPackages) {
+			const { written } = await materialiseExtensionMigrationPackageIfMissing(spaceDir, pkg);
+			if (written) newMigrationDirs.push(pkg.dirName);
+		}
+		const action = priorHash !== descriptor.headRef.hash || newMigrationDirs.length > 0 ? "updated" : "unchanged";
+		seeded.push({
+			spaceId: space.spaceId,
+			action,
+			priorHash,
+			newHash: descriptor.headRef.hash,
+			newMigrationDirs
+		});
+	}
+	return { seeded };
+}
+/**
+* Placeholder `.d.ts` content for an extension space's on-disk mirror.
+*
+* Rendering a fully-typed `.d.ts` for an extension contract requires
+* the SQL-family renderer with the codec / typemap registry threaded
+* through; until that integration ships, the on-disk `.d.ts` is a
+* stub `export {};` module that documents how consumers should
+* validate the sibling `contract.json`. The stub typechecks on its
+* own and does not need any TypeScript suppressions.
+*/
+function buildPlaceholderContractDts(spaceId) {
+	return [
+		"/**",
+		` * Placeholder \`.d.ts\` for extension space "${spaceId}".`,
+		" *",
+		" * The framework re-emits this file on every `migration plan` run",
+		" * alongside `contract.json` and `refs/head.json`. A typed `.d.ts`",
+		" * rendering pass for extension contracts is tracked separately;",
+		" * until that ships, consumers should import `contract.json`",
+		" * and pass it through the target descriptor’s `contractSerializer`.",
+		" */",
+		"export {};",
+		""
+	].join("\n");
+}
+const FULL_HASH_PATTERN = /^([0-9a-f]{64}|empty)$/;
+function looksLikeFullHash(input) {
+	return FULL_HASH_PATTERN.test(input);
+}
+function graphIsEmpty(space) {
+	return space.packages.length === 0;
+}
+function getReachableRefs(refs, graph) {
+	return Object.entries(refs).flatMap(([name, entry]) => entry && isGraphNode(entry.hash, graph) ? [{
+		name,
+		hash: entry.hash
+	}] : []).sort((a, b) => a.name.localeCompare(b.name));
+}
+function assertFromIsGraphNode(fromHash, graph, refs, graphTipHash) {
+	try {
+		assertHashIsGraphNode(fromHash, graph);
+	} catch (error) {
+		if (MigrationToolsError.is(error) && error.code === "MIGRATION.HASH_NOT_IN_GRAPH") throw errorPlanForgotTheFlag(fromHash, getReachableRefs(refs, graph), graphTipHash);
+		throw error;
+	}
+}
+async function resolveContractRef(parsed, space, options) {
+	const { hash, provenance } = parsed;
+	const refName = provenance.kind === "ref" ? provenance.refName : void 0;
+	try {
+		const at = await space.contractAt(hash, refName !== void 0 ? { refName } : void 0);
+		if (at.provenance === "ref") return ok({
+			kind: "ref",
+			hash: at.hash,
+			contract: at.contract,
+			contractJson: at.contractJson,
+			contractDts: at.contractDts
+		});
+		return ok({
+			kind: "graph-node",
+			hash: at.hash,
+			contract: at.contract,
+			contractJson: at.contractJson,
+			contractDts: at.contractDts
+		});
+	} catch (error) {
+		return mapContractAtError(error, options?.artifactRole !== void 0 ? { artifactRole: options.artifactRole } : void 0);
+	}
+}
+async function resolveFromPolicy(parsed, input, refs, explicitFromLabel) {
+	const resolution = await resolveContractRef(parsed, input.space, {
+		...explicitFromLabel !== void 0 ? { explicitLabel: explicitFromLabel } : {},
+		artifactRole: "from"
+	});
+	if (!resolution.ok) return resolution;
+	if (resolution.value.kind === "graph-node") return ok({
+		kind: "graph-node",
+		fromHash: resolution.value.hash,
+		fromContract: resolution.value.contract
+	});
+	const { hash, contract, contractJson, contractDts } = resolution.value;
+	if (graphIsEmpty(input.space)) return ok({
+		kind: "auto-baseline",
+		fromHash: hash,
+		fromContract: contract,
+		contractDts,
+		contractJson
+	});
+	const graph = input.space.graph();
+	const graphTip = findLatestMigration(graph)?.to ?? null;
+	try {
+		assertFromIsGraphNode(hash, graph, refs, graphTip);
+	} catch (error) {
+		if (CliStructuredError$1.is(error)) return notOk(error);
+		throw error;
+	}
+	return ok({
+		kind: "ref",
+		fromHash: hash,
+		fromContract: contract,
+		contractDts,
+		contractJson
+	});
+}
+async function resolveFromForPlan(input) {
+	const { optionsFrom, space } = input;
+	const graph = space.graph();
+	const refs = space.refs;
+	if (optionsFrom === void 0) {
+		const dbRef = refs["db"];
+		if (!dbRef) return ok({
+			kind: "greenfield",
+			fromHash: null,
+			fromContract: null
+		});
+		return resolveFromPolicy({
+			hash: dbRef.hash,
+			provenance: {
+				kind: "ref",
+				refName: "db"
+			}
+		}, input, refs);
+	}
+	const refResult = parseContractRef(optionsFrom, {
+		graph,
+		refs
+	});
+	if (!refResult.ok) {
+		if (looksLikeFullHash(optionsFrom)) {
+			const empty = graphIsEmpty(space);
+			const graphTip = findLatestMigration(graph)?.to ?? null;
+			if (empty) return notOk(errorSnapshotMissing(optionsFrom, { viaRef: false }));
+			return notOk(errorPlanForgotTheFlag(optionsFrom, getReachableRefs(refs, graph), graphTip));
+		}
+		return notOk(mapRefResolutionError(refResult.failure));
+	}
+	return resolveFromPolicy(refResult.value, input, refs, optionsFrom);
+}
+async function resolveToForPlan(optionsTo, input) {
+	const { space } = input;
+	const graph = space.graph();
+	const refs = space.refs;
+	const refResult = parseContractRef(optionsTo, {
+		graph,
+		refs
+	});
+	if (!refResult.ok) return notOk(mapRefResolutionError(refResult.failure));
+	const resolution = await resolveContractRef(refResult.value, space, {
+		explicitLabel: optionsTo,
+		artifactRole: "to"
+	});
+	if (!resolution.ok) return resolution;
+	const { hash, contract, contractJson, contractDts } = resolution.value;
+	return ok({
+		hash,
+		contract,
+		contractJson,
+		contractDts
+	});
+}
+async function runPlannerLeg(planner, migrations, frameworkComponents, contract, fromContract, spaceId, ownership, snapshotsImportPath, resolveImportSpecifier) {
+	const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
+	const plannerResult = planner.plan({
+		contract,
+		schema: fromSchema,
+		policy: { allowedOperationClasses: [
+			"additive",
+			"widening",
+			"destructive",
+			"data"
+		] },
+		fromContract,
+		frameworkComponents,
+		spaceId,
+		ownership,
+		snapshotsImportPath
+	});
+	if (plannerResult.kind === "failure") return notOk(errorMigrationPlanningFailed({ conflicts: plannerResult.conflicts }));
+	let plannedOps = [];
+	let hasPlaceholders = false;
+	try {
+		plannedOps = await Promise.all(plannerResult.plan.operations);
+		if (plannedOps.length === 0) return notOk(errorMigrationPlanningFailed({ conflicts: [{
+			kind: "unsupportedChange",
+			summary: "Contract changed but planner produced no operations. This indicates unsupported or ignored changes."
+		}] }));
+	} catch (e) {
+		if (CliStructuredError$1.is(e) && e.code === "MIGRATION.UNFILLED_PLACEHOLDER") hasPlaceholders = true;
+		else throw e;
+	}
+	return ok({
+		plannedOps,
+		migrationTsContent: plannerResult.plan.renderTypeScript(resolveImportSpecifier),
+		hasPlaceholders
+	});
+}
+async function writePlannedMigrationPackage(packageDir, fromHash, toHash, createdAt, leg) {
+	const opsForWrite = leg.hasPlaceholders ? [] : leg.plannedOps;
+	const metadataWithInvariants = {
+		from: fromHash,
+		to: toHash,
+		providedInvariants: deriveProvidedInvariants(opsForWrite),
+		createdAt: createdAt.toISOString()
+	};
+	await writeMigrationPackage(packageDir, {
+		...metadataWithInvariants,
+		migrationHash: computeMigrationHash(metadataWithInvariants, opsForWrite)
+	}, opsForWrite);
+	await writeMigrationTs(packageDir, leg.migrationTsContent);
+}
+async function executeMigrationPlanCommand(options, flags, ui, startTime) {
+	const config = await loadConfig(options.config);
+	const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(options.config, config);
+	const contractPathAbsolute = resolveContractPath(config);
+	const contractPath = relative(process.cwd(), contractPathAbsolute);
+	if (!flags.json && !flags.quiet) {
+		const details = [
+			{
+				label: "config",
+				value: configPath
+			},
+			{
+				label: "contract",
+				value: contractPath
+			},
+			{
+				label: "migrations",
+				value: appMigrationsRelative
+			}
+		];
+		if (options.from) details.push({
+			label: "from",
+			value: options.from
+		});
+		if (options.to) details.push({
+			label: "to",
+			value: options.to
+		});
+		if (options.name) details.push({
+			label: "name",
+			value: options.name
+		});
+		const header = formatStyledHeader({
+			command: "migration plan",
+			description: "Plan a migration from contract changes",
+			url: "https://pris.ly/migration-plan",
+			details,
+			flags
+		});
+		ui.stderr(header);
+	}
+	let contractJsonContent;
+	try {
+		contractJsonContent = await readFile(contractPathAbsolute, "utf-8");
+	} catch (error) {
+		if (error instanceof Error && error.code === "ENOENT") return notOk(errorFileNotFound(contractPathAbsolute, {
+			why: `Contract file not found at ${contractPathAbsolute}`,
+			fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`
+		}));
+		return notOk(errorUnexpected(error instanceof Error ? error.message : String(error), { why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}` }));
+	}
+	const stack = createControlStack(config);
+	const familyInstance = config.family.create(stack);
+	const controlAdapter = config.adapter.create(stack);
+	let toContract;
+	try {
+		toContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent));
+	} catch (error) {
+		return notOk(errorContractValidationFailed(`Contract at ${contractPathAbsolute} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`, { where: { path: contractPathAbsolute } }));
+	}
+	const rawStorageHash = toContract.storage?.storageHash;
+	if (typeof rawStorageHash !== "string") return notOk(errorContractValidationFailed("Contract is missing storageHash", { where: { path: contractPathAbsolute } }));
+	let toStorageHash = rawStorageHash;
+	let toArtifacts = null;
+	let fromContract = null;
+	let fromHash = null;
+	let snapshotStartContract = null;
+	let isAutoBaseline = false;
+	const tolerantAggregateResult = await loadContractSpaceAggregateForCli({
+		targetId: config.target.targetId,
+		migrationsDir,
+		appContract: toContract,
+		extensions: config.extensions ?? [],
+		deserializeContract: (json) => familyInstance.deserializeContract(json)
+	});
+	if (!tolerantAggregateResult.ok) return notOk(tolerantAggregateResult.failure);
+	const resolutionSpace = tolerantAggregateResult.value.app;
+	const resolutionResult = await resolveFromForPlan({
+		optionsFrom: options.from,
+		space: resolutionSpace
+	});
+	if (!resolutionResult.ok) return notOk(resolutionResult.failure);
+	switch (resolutionResult.value.kind) {
+		case "greenfield": break;
+		case "graph-node":
+			fromHash = resolutionResult.value.fromHash;
+			fromContract = resolutionResult.value.fromContract;
+			break;
+		case "ref":
+			fromHash = resolutionResult.value.fromHash;
+			fromContract = resolutionResult.value.fromContract;
+			snapshotStartContract = {
+				fromHash: resolutionResult.value.fromHash,
+				contractJson: resolutionResult.value.contractJson,
+				contractDts: resolutionResult.value.contractDts
+			};
+			break;
+		case "auto-baseline":
+			fromHash = resolutionResult.value.fromHash;
+			fromContract = resolutionResult.value.fromContract;
+			snapshotStartContract = {
+				fromHash: resolutionResult.value.fromHash,
+				contractJson: resolutionResult.value.contractJson,
+				contractDts: resolutionResult.value.contractDts
+			};
+			isAutoBaseline = true;
+			break;
+	}
+	if (options.to !== void 0) {
+		const toResolution = await resolveToForPlan(options.to, { space: resolutionSpace });
+		if (!toResolution.ok) return notOk(toResolution.failure);
+		toContract = toResolution.value.contract;
+		toStorageHash = toResolution.value.hash;
+		toArtifacts = {
+			contractJson: toResolution.value.contractJson,
+			contractDts: toResolution.value.contractDts
+		};
+	}
+	const resolveImportSpecifier = createProjectSpecifierResolver(options.config);
+	const seedResult = await runContractSpaceSeedPhase({
+		migrationsDir,
+		extensions: toExtensionInputs(config.extensions ?? [])
+	});
+	if (!flags.json && !flags.quiet) {
+		for (const record of seedResult.seeded) if (record.action === "updated") {
+			const pkgSuffix = record.newMigrationDirs.length > 0 ? `; ${record.newMigrationDirs.length} new migration package(s) materialised` : "";
+			ui.step(`Updated ${record.spaceId} to ${record.newHash}${pkgSuffix}`);
+		}
+	}
+	const emittedExtensionDirs = seedResult.seeded.flatMap((r) => r.newMigrationDirs.map((dirName) => ({
+		spaceId: r.spaceId,
+		dirName
+	})));
+	if (fromHash === toStorageHash && !isAutoBaseline) return ok({
+		ok: true,
+		noOp: true,
+		from: fromHash,
+		to: toStorageHash,
+		operations: [],
+		emittedExtensionDirs,
+		summary: "No changes detected between contracts",
+		timings: { total: Date.now() - startTime }
+	});
+	const migrations = getTargetMigrations(config.target);
+	if (!migrations) return notOk(errorTargetMigrationNotSupported({ why: `Target "${config.target.id}" does not support migrations` }));
+	const aggregateResult = await buildContractSpaceAggregate({
+		targetId: config.target.targetId,
+		migrationsDir,
+		appContract: toContract,
+		extensions: config.extensions ?? [],
+		deserializeContract: (json) => familyInstance.deserializeContract(json)
+	});
+	if (!aggregateResult.ok) return notOk(aggregateResult.failure);
+	const aggregate = aggregateResult.value;
+	const frameworkComponents = assertFrameworkComponentsCompatible(config.family.familyId, config.target.targetId, [
+		config.target,
+		config.adapter,
+		...config.extensions ?? []
+	]);
+	async function writeDestinationSnapshot(destHash) {
+		if (toArtifacts !== null) {
+			await writeContractSnapshot(migrationsDir, destHash, {
+				contractJson: toArtifacts.contractJson,
+				contractDts: toArtifacts.contractDts
+			});
+			return;
+		}
+		const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
+		const [contractJsonRaw, contractDts] = await Promise.all([readFile(destinationArtifacts.jsonPath, "utf-8"), readFile(destinationArtifacts.dtsPath, "utf-8")]);
+		await writeContractSnapshot(migrationsDir, destHash, {
+			contractJson: JSON.parse(contractJsonRaw),
+			contractDts
+		});
+	}
+	try {
+		const planner = migrations.createPlanner(controlAdapter);
+		if (isAutoBaseline && fromHash !== null && fromContract !== null && snapshotStartContract !== null) {
+			const baselineTimestamp = /* @__PURE__ */ new Date();
+			const deltaTimestamp = new Date(baselineTimestamp.getTime() + 6e4);
+			const baselineDirName = formatMigrationDirName(baselineTimestamp, "baseline");
+			const deltaDirName = formatMigrationDirName(deltaTimestamp, options.name ?? "migration");
+			const baselinePackageDir = join(appMigrationsDir, baselineDirName);
+			const deltaPackageDir = join(appMigrationsDir, deltaDirName);
+			const baselineLeg = await runPlannerLeg(planner, migrations, frameworkComponents, fromContract, null, aggregate.app.spaceId, aggregate, snapshotsImportPathFrom(baselinePackageDir, migrationsDir), resolveImportSpecifier);
+			if (!baselineLeg.ok) return notOk(baselineLeg.failure);
+			await writePlannedMigrationPackage(baselinePackageDir, null, fromHash, baselineTimestamp, baselineLeg.value);
+			await writeContractSnapshot(migrationsDir, fromHash, {
+				contractJson: snapshotStartContract.contractJson,
+				contractDts: snapshotStartContract.contractDts
+			});
+			if (fromHash === toStorageHash) {
+				const baselineOps = baselineLeg.value.hasPlaceholders ? [] : baselineLeg.value.plannedOps;
+				if (baselineLeg.value.hasPlaceholders) {
+					const baselineDir = relative(process.cwd(), baselinePackageDir);
+					return ok({
+						ok: true,
+						noOp: false,
+						from: fromHash,
+						to: toStorageHash,
+						dir: baselineDir,
+						baselineDir,
+						operations: [],
+						emittedExtensionDirs,
+						pendingPlaceholders: true,
+						summary: "Planned baseline with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit",
+						timings: { total: Date.now() - startTime }
+					});
+				}
+				const preview = hasOperationPreview(familyInstance) ? familyInstance.toOperationPreview(baselineOps) : void 0;
+				return ok({
+					ok: true,
+					noOp: false,
+					from: fromHash,
+					to: toStorageHash,
+					baselineDir: relative(process.cwd(), baselinePackageDir),
+					operations: baselineOps.map((op) => ({
+						id: op.id,
+						label: op.label,
+						operationClass: op.operationClass
+					})),
+					emittedExtensionDirs,
+					...preview !== void 0 ? { preview } : {},
+					summary: buildAutoBaselinePlanSummary(0, emittedExtensionDirs.length),
+					timings: { total: Date.now() - startTime }
+				});
+			}
+			const deltaLeg = await runPlannerLeg(planner, migrations, frameworkComponents, aggregate.app.contract(), fromContract, aggregate.app.spaceId, aggregate, snapshotsImportPathFrom(deltaPackageDir, migrationsDir), resolveImportSpecifier);
+			if (!deltaLeg.ok) return notOk(deltaLeg.failure);
+			await writePlannedMigrationPackage(deltaPackageDir, fromHash, toStorageHash, deltaTimestamp, deltaLeg.value);
+			await writeDestinationSnapshot(toStorageHash);
+			await writeContractSnapshot(migrationsDir, fromHash, {
+				contractJson: snapshotStartContract.contractJson,
+				contractDts: snapshotStartContract.contractDts
+			});
+			const deltaOps = deltaLeg.value.hasPlaceholders ? [] : deltaLeg.value.plannedOps;
+			if (deltaLeg.value.hasPlaceholders) return ok({
+				ok: true,
+				noOp: false,
+				from: fromHash,
+				to: toStorageHash,
+				dir: relative(process.cwd(), deltaPackageDir),
+				baselineDir: relative(process.cwd(), baselinePackageDir),
+				operations: [],
+				emittedExtensionDirs,
+				pendingPlaceholders: true,
+				summary: "Planned baseline + migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit",
+				timings: { total: Date.now() - startTime }
+			});
+			const preview = hasOperationPreview(familyInstance) ? familyInstance.toOperationPreview(deltaOps) : void 0;
+			return ok({
+				ok: true,
+				noOp: false,
+				from: fromHash,
+				to: toStorageHash,
+				dir: relative(process.cwd(), deltaPackageDir),
+				baselineDir: relative(process.cwd(), baselinePackageDir),
+				operations: deltaOps.map((op) => ({
+					id: op.id,
+					label: op.label,
+					operationClass: op.operationClass
+				})),
+				emittedExtensionDirs,
+				...preview !== void 0 ? { preview } : {},
+				summary: buildAutoBaselinePlanSummary(deltaOps.length, emittedExtensionDirs.length),
+				timings: { total: Date.now() - startTime }
+			});
+		}
+		const timestamp = /* @__PURE__ */ new Date();
+		const packageDir = join(appMigrationsDir, formatMigrationDirName(timestamp, options.name ?? "migration"));
+		const deltaLeg = await runPlannerLeg(planner, migrations, frameworkComponents, aggregate.app.contract(), fromContract, aggregate.app.spaceId, aggregate, snapshotsImportPathFrom(packageDir, migrationsDir), resolveImportSpecifier);
+		if (!deltaLeg.ok) return notOk(deltaLeg.failure);
+		await writePlannedMigrationPackage(packageDir, fromHash, toStorageHash, timestamp, deltaLeg.value);
+		await writeDestinationSnapshot(toStorageHash);
+		if (snapshotStartContract !== null) await writeContractSnapshot(migrationsDir, snapshotStartContract.fromHash, {
+			contractJson: snapshotStartContract.contractJson,
+			contractDts: snapshotStartContract.contractDts
+		});
+		if (deltaLeg.value.hasPlaceholders) return ok({
+			ok: true,
+			noOp: false,
+			from: fromHash,
+			to: toStorageHash,
+			dir: relative(process.cwd(), packageDir),
+			operations: [],
+			emittedExtensionDirs,
+			pendingPlaceholders: true,
+			summary: "Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit",
+			timings: { total: Date.now() - startTime }
+		});
+		const plannedOps = deltaLeg.value.plannedOps;
+		const preview = hasOperationPreview(familyInstance) ? familyInstance.toOperationPreview(plannedOps) : void 0;
+		return ok({
+			ok: true,
+			noOp: false,
+			from: fromHash,
+			to: toStorageHash,
+			dir: relative(process.cwd(), packageDir),
+			operations: plannedOps.map((op) => ({
+				id: op.id,
+				label: op.label,
+				operationClass: op.operationClass
+			})),
+			emittedExtensionDirs,
+			...preview !== void 0 ? { preview } : {},
+			summary: buildPlanSummary(plannedOps.length, emittedExtensionDirs.length),
+			timings: { total: Date.now() - startTime }
+		});
+	} catch (error) {
+		if (CliStructuredError$1.is(error)) return notOk(error);
+		if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+		const message = error instanceof Error ? error.message : String(error);
+		return notOk(errorUnexpected(message, { why: `Unexpected error during migration plan: ${message}` }));
+	}
+}
+function createMigrationPlanCommand() {
+	const command = new Command("plan");
+	setCommandDescriptions(command, "Plan a migration from contract changes", "Compares the emitted contract against the latest on-disk migration state and\nproduces a new migration package with the required operations. No database\nconnection is needed — this is a fully offline operation.");
+	setCommandExamples(command, [
+		"prisma-next migration plan",
+		"prisma-next migration plan --name add-users-table",
+		"prisma-next migration plan --to <migration-dir>^ --name rollback"
+	]);
+	addGlobalOptions(command).option("--config <path>", "Path to prisma-next.config.ts").option("--name <slug>", "Name slug for the migration directory", "migration").option("--from <contract>", "Starting contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)").option("--to <contract>", "Destination contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path); defaults to the emitted contract").action(async (options) => {
+		const flags = parseGlobalFlagsOrExit(options);
+		const startTime = Date.now();
+		const ui = createTerminalUI(flags);
+		const exitCode = handleResult(await executeMigrationPlanCommand(options, flags, ui, startTime), flags, ui, (planResult) => {
+			if (flags.json) ui.output(JSON.stringify(planResult, null, 2));
+			else if (!flags.quiet) ui.log(formatMigrationPlanOutput(planResult, flags));
+		});
+		process.exit(exitCode);
+	});
+	return command;
+}
+/**
+* Compose the success-line summary so the cross-space side effect
+* (extension-space migration packages materialised on disk during
+* this `plan` run) is visible in the top line — not just in the
+* step log above it.
+*
+* Example outputs:
+*   - `Planned 3 operation(s)` (app-space-only project)
+*   - `Planned 3 operation(s); materialised 1 extension-space migration` (one extension)
+*   - `Planned 3 operation(s); materialised 2 extension-space migrations` (two extensions)
+*
+* Locks AC3 at the summary-line level: a reader of the success line
+* can tell that something happened beyond the app space.
+*/
+function buildPlanSummary(plannedOpsCount, emittedExtensionDirsCount) {
+	const base = `Planned ${plannedOpsCount} operation(s)`;
+	if (emittedExtensionDirsCount === 0) return base;
+	return `${base}; materialised ${emittedExtensionDirsCount} ${emittedExtensionDirsCount === 1 ? "extension-space migration" : "extension-space migrations"}`;
+}
+function buildAutoBaselinePlanSummary(deltaOpsCount, emittedExtensionDirsCount) {
+	const base = `Planned baseline + ${deltaOpsCount} operation(s)`;
+	if (emittedExtensionDirsCount === 0) return base;
+	return `${base}; materialised ${emittedExtensionDirsCount} ${emittedExtensionDirsCount === 1 ? "extension-space migration" : "extension-space migrations"}`;
+}
+function formatMigrationPlanOutput(result, flags) {
+	const lines = [];
+	const useColor = flags.color !== false;
+	const green_ = useColor ? (s) => `\x1b[32m${s}\x1b[0m` : (s) => s;
+	const yellow_ = useColor ? (s) => `\x1b[33m${s}\x1b[0m` : (s) => s;
+	const dim_ = useColor ? (s) => `\x1b[2m${s}\x1b[0m` : (s) => s;
+	function appendEmittedExtensions() {
+		if (result.emittedExtensionDirs.length === 0) return;
+		lines.push("");
+		lines.push(dim_("Emitted extension migrations:"));
+		for (const entry of result.emittedExtensionDirs) lines.push(dim_(`  ${entry.spaceId} → migrations/${entry.spaceId}/${entry.dirName}`));
+		lines.push("");
+		lines.push(`Next: review the extension migrations above, then run ${green_("prisma-next migrate")}.`);
+	}
+	if (result.noOp) {
+		lines.push(`${green_("✔")} No changes detected`);
+		lines.push(dim_(`  from: ${result.from}`));
+		lines.push(dim_(`  to:   ${result.to}`));
+		appendEmittedExtensions();
+		return lines.join("\n");
+	}
+	if (result.pendingPlaceholders) {
+		lines.push(`${yellow_("⚠")} ${result.summary}`);
+		lines.push("");
+		lines.push(dim_(`from: ${result.from}`));
+		lines.push(dim_(`to:   ${result.to}`));
+		if (result.dir) lines.push(dim_(`dir:  ${result.dir}`));
+		lines.push("");
+		lines.push("Open migration.ts and replace each `placeholder(...)` call with your actual query.");
+		lines.push(`Then run: ${green_(`node ${result.dir ?? "<dir>"}/migration.ts`)}`);
+		appendEmittedExtensions();
+		return lines.join("\n");
+	}
+	lines.push(`${green_("✔")} ${result.summary}`);
+	lines.push("");
+	if (result.operations.length > 0) {
+		lines.push(dim_("│"));
+		for (let i = 0; i < result.operations.length; i++) {
+			const op = result.operations[i];
+			const treeChar = i === result.operations.length - 1 ? "└" : "├";
+			const destructiveMarker = op.operationClass === "destructive" ? ` ${yellow_("(destructive)")}` : "";
+			lines.push(`${dim_(treeChar)}─ ${op.label}${destructiveMarker}`);
+		}
+		if (result.operations.some((op) => op.operationClass === "destructive")) {
+			lines.push("");
+			lines.push(`${yellow_("⚠")} This migration contains destructive operations that may cause data loss.`);
+		}
+		lines.push("");
+	}
+	lines.push(dim_(`from:   ${result.from}`));
+	lines.push(dim_(`to:     ${result.to}`));
+	if (result.baselineDir) lines.push(dim_(`Baseline → ${result.baselineDir}`));
+	if (result.dir) lines.push(dim_(`App space → ${result.dir}`));
+	for (const entry of result.emittedExtensionDirs) lines.push(dim_(`Extension space ${entry.spaceId} → migrations/${entry.spaceId}/${entry.dirName}`));
+	lines.push("");
+	const reviewTarget = result.baselineDir !== void 0 && result.dir !== void 0 ? `${result.baselineDir} and ${result.dir}` : result.baselineDir ?? result.dir ?? "<dir>";
+	lines.push(`Next: review ${green_(reviewTarget)} if needed, then run ${green_("prisma-next migrate")}.`);
+	if (result.preview && result.preview.statements.length > 0) {
+		const allSql = result.preview.statements.every((s) => s.language === "sql");
+		lines.push("");
+		lines.push(dim_(allSql ? "DDL preview" : "Operation preview"));
+		lines.push("");
+		for (const statement of result.preview.statements) {
+			const trimmed = statement.text.trim();
+			if (!trimmed) continue;
+			const line = statement.language === "sql" && !trimmed.endsWith(";") ? `${trimmed};` : trimmed;
+			lines.push(line);
+		}
+	}
+	if (flags.verbose && result.timings) {
+		lines.push("");
+		lines.push(dim_(`Total time: ${result.timings.total}ms`));
+	}
+	return lines.join("\n");
+}
+/**
+* Resolve a migration package by **target contract hash** (`metadata.to`)
+* using exact match or prefix match.
+*
+* Note: matches `metadata.to` (the contract hash this migration produces),
+* not `metadata.migrationHash` (the package's content-addressed identity).
+* Tries exact match first, then prefix match. Returns the matched package on
+* success, or a discriminated failure indicating whether the prefix was
+* ambiguous or simply not found.
+*
+* @internal Exported for testing only.
+*/
+function resolveBundleByPrefix(bundles, needle) {
+	const exact = bundles.find((p) => p.metadata.to === needle);
+	if (exact) return ok(exact);
+	const candidates = bundles.filter((p) => p.metadata.to.startsWith(needle));
+	if (candidates.length === 1) return ok(candidates[0]);
+	if (candidates.length > 1) return notOk({
+		reason: "ambiguous",
+		count: candidates.length
+	});
+	return notOk({ reason: "not-found" });
+}
+//#endregion
+export { formatMigrationPlanOutput as n, resolveBundleByPrefix as r, createMigrationPlanCommand as t };
+
+//# sourceMappingURL=migration-plan-q_L84PN1-BWE0LTH6.mjs.map