@prisma/orm-toolchain 8.0.0-rc.1-dev.32 → 8.0.0-rc.1-dev.34

package/dist/cli.mjs

@@ -1,21 +1,27 @@
 import { i as loadConfig } from "./exports-BZLNbtkY.mjs";
-import { F as requireLiveDatabase, N as errorUnexpected, a as errorConfigValidation$1, b as errorNoMigrations, d as errorFileNotFound, h as errorLegendHumanOnly, j as errorTargetMigrationNotSupported, s as errorContractValidationFailed, v as errorMigrationPackageNotFound } from "./cli-errors-CihMAEVj-C1uUYBop.mjs";
+import { F as requireLiveDatabase, I as runCommandAction, N as errorUnexpected, a as errorConfigValidation$1, b as errorNoMigrations, c as errorDatabaseConnectionRequired, d as errorFileNotFound, h as errorLegendHumanOnly, j as errorTargetMigrationNotSupported, s as errorContractValidationFailed, t as CliStructuredError$1$1, u as errorDriverRequired, v as errorMigrationPackageNotFound } from "./cli-errors-C6_pH59O-CzD4SYcJ.mjs";
 import { r as getEmittedArtifactPaths } from "./exports-BCLg4CiV-05kuwcb0.mjs";
-import { m as previewBlockHeader } from "./terminal-ui-JJKxvT0q-CPDEJqqU.mjs";
+import { h as renderPreviewStatement, m as previewBlockHeader } from "./terminal-ui-Cqz4LVL7-B0mcVdLy.mjs";
 import { c as spaceMigrationDirectory } from "./verify-contract-spaces-DhJTb0zM-_oh6W6lp.mjs";
-import { S as targetSupportsMigrations, f as maskConnectionUrl, n as closeQuietly } from "./command-helpers-Dw3LDEu_-B4AETH4D.mjs";
-import { t as createContractEmitCommand } from "./contract-emit-CIdgw3Kq-BcfYaUfn.mjs";
-import { t as createFormatCommand } from "./format-CYdgHub4-Cs6VcFje.mjs";
-import { a as loadContractSpaceAggregateForCli, r as buildReadAggregate } from "./contract-space-aggregate-loader-1wG1OiDk-D75luh5-.mjs";
-import { t as createControlClient } from "./client-C4Gh4PBz-BMUlBcuE.mjs";
-import { t as mapCaughtMigrationError } from "./caught-errors-B_oGFiYw-BqX49eW0.mjs";
-import { n as migrationSpaceListEntriesFromAggregate, r as runMigrationList } from "./migration-list-AKRIIovW-BN-Zrwk0.mjs";
-import { n as resolveMigrationRef } from "./ref-resolution-Bi4lpxM8-BbfL_yv8.mjs";
-import { S as toneSpans, b as renderMigrationListWithStyle, d as createToneMigrationListStyler, n as TONE_MIGRATION_GRAPH_PALETTE, v as renderMigrationGraphLegend, x as toneDrawing } from "./migration-graph-command-render-CgdHruiZ-B6V4gmUe.mjs";
-import { n as looksLikePath, r as resolveAppTargetPath, t as findPackageByDirPath } from "./migration-path-target-yA4h5Zc6-DlzBblBG.mjs";
-import { t as buildMigrationSpaceGraphEntries } from "./migration-graph-BtP1Va3T-C8PpuaYw.mjs";
-import { n as renderMigrationGraphDot, r as renderMigrationGraphSections, t as buildMigrationGraphTreeSections } from "./migration-graph-sections-CceYWPCP-LqImOaK1.mjs";
-import { a as sortLedgerEntries, i as serializeLedgerEntriesForJson, n as formatLedgerAppliedAt, o as styleHashTransition, t as MIGRATION_LOG_EMPTY_MESSAGE } from "./migration-log-table-JR7fFVbE-DR2mom6h.mjs";
+import { S as targetSupportsMigrations, f as maskConnectionUrl, n as closeQuietly, v as sanitizeErrorMessage } from "./command-helpers-kD9CO1hd-BPhnkBin.mjs";
+import { t as createContractEmitCommand } from "./contract-emit-BlvUNMHM-BEioUVR5.mjs";
+import { t as createFormatCommand } from "./format-D5x0jz7q-xalz6Fkn.mjs";
+import { a as loadContractSpaceAggregateForCli, r as buildReadAggregate, s as refuseContractSpaceIntegrity, u as toDeclaredExtensionsFromRaw } from "./contract-space-aggregate-loader-BpdB-mHG-BiU0IUeb.mjs";
+import { t as createControlClient } from "./client-BqhVohc5-DFRVWFps.mjs";
+import { a as readContractIR, o as resolveRefAdvancementFields, t as advanceRefSafely } from "./ref-advancement-DaZBzm7m-WoqnFAyr.mjs";
+import { t as mapDbInitFailure } from "./db-init-failure-XYOVL4o7-BitY_JYn.mjs";
+import { t as mapCaughtMigrationError } from "./caught-errors-BZ-9WASe-DH4DaDha.mjs";
+import { t as mapContractAtError } from "./contract-at-errors-CLFX1-Gc-MNPXDx1t.mjs";
+import { i as refuseUnknownInvariants, n as refuseMarkerOutsideGraph } from "./invariants-1L2zfc6--BpedlAbF.mjs";
+import { t as executeMigrateShowPlan } from "./migrate-show-bdXjSFgh-CQxl5yNp.mjs";
+import { n as resolveMigrationRef, t as resolveContractRef } from "./ref-resolution-D4fAdXo8-Dfaky0yw.mjs";
+import { n as migrationSpaceListEntriesFromAggregate, r as runMigrationList } from "./migration-list-W0dqabIj-Dc2NH_LY.mjs";
+import { S as toneSpans, b as renderMigrationListWithStyle, d as createToneMigrationListStyler, n as TONE_MIGRATION_GRAPH_PALETTE, v as renderMigrationGraphLegend, x as toneDrawing } from "./migration-graph-command-render-BeuEyf2B-BNH9oUB_.mjs";
+import { n as migrateShowRunListRows, r as renderMigrateShowGraph, t as mapMigrateFailure } from "./migrate-failure-Bdr3AJee-C9yNeQXy.mjs";
+import { n as looksLikePath, r as resolveAppTargetPath, t as findPackageByDirPath } from "./migration-path-target-5r1leSW5-B0EMgvEv.mjs";
+import { t as buildMigrationSpaceGraphEntries } from "./migration-graph-DmdVVJoZ-DDBKjUMz.mjs";
+import { n as renderMigrationGraphDot, r as renderMigrationGraphSections, t as buildMigrationGraphTreeSections } from "./migration-graph-sections-BWcFCOL6-_G0Wb4QR.mjs";
+import { a as sortLedgerEntries, i as serializeLedgerEntriesForJson, n as formatLedgerAppliedAt, o as styleHashTransition, t as MIGRATION_LOG_EMPTY_MESSAGE } from "./migration-log-table-DRiOnvzf-zTQBThqe.mjs";
 import { CliStructuredError } from "@prisma/orm-framework/errors/control";
 import { ifDefined } from "@prisma/orm-framework/utils/defined";
 import { join, normalize, relative, resolve } from "pathe";
@@ -31,7 +37,7 @@ import { defineCommand, defineCommandFamily, defineConfigSection, flag, position
 import { CliStructuredError as CliStructuredError$1, notOk, ok } from "@prisma/cli-engine/protocol";
 import { pathToFileURL } from "node:url";
 import { build } from "esbuild";
-//#region ../../../1-framework/3-tooling/cli/dist/load-config-Dmql8awN.mjs
+//#region ../../../1-framework/3-tooling/cli/dist/load-config-BQgwPvgu.mjs
 const MISSING_CONFIG_ACTION = {
 	kind: "run-command",
 	label: "Create a configuration file",
@@ -255,6 +261,229 @@ function defineOrmCommand(def) {
 	});
 }
 /**
+* The database connection override, declared from here by every command that
+* accepts one so its brief and placeholder cannot drift apart. Resolution
+* order is the flag, then `config.db.connection`, then
+* `CONFIG.DB_CONNECTION_REQUIRED`.
+*/
+const dbFlag = flag.string({
+	brief: "Database connection string",
+	placeholder: "url"
+});
+const OUTCOMES = {
+	ok: "ok",
+	skipped: "skipped",
+	error: "failed"
+};
+/**
+* The control API's spans as engine events. A span's label is remembered when
+* it starts so the finishing event names the step with the same words.
+*/
+function controlProgressReporter(report) {
+	const labels = /* @__PURE__ */ new Map();
+	return (event) => {
+		if (event.kind === "spanStart") {
+			labels.set(event.spanId, event.label);
+			report({
+				kind: "step-started",
+				step: event.label,
+				id: event.spanId,
+				...ifDefined("parentId", event.parentSpanId)
+			});
+			return;
+		}
+		const step = labels.get(event.spanId) ?? event.spanId;
+		labels.delete(event.spanId);
+		report({
+			kind: "step-finished",
+			step,
+			id: event.spanId,
+			outcome: OUTCOMES[event.outcome]
+		});
+	};
+}
+function operationNode(operation) {
+	return operation.operationClass === "destructive" ? {
+		label: operation.label,
+		status: "warn"
+	} : { label: operation.label };
+}
+function spaceLabel(space) {
+	return space.kind === "app" ? "App space" : `Extension space: ${space.spaceId}`;
+}
+/**
+* One root per contract space, in the schedule order the runner used. A
+* space's post-apply marker is the last child of its own space, so the engine
+* draws it under the operations it signs.
+*/
+function spaceNodes(perSpace, mode) {
+	return perSpace.map((space) => ({
+		label: [{
+			text: spaceLabel(space),
+			tone: "identifier"
+		}],
+		children: [...space.operations.length === 0 ? [{ label: [{
+			text: "(no operations)",
+			tone: "muted"
+		}] }] : space.operations.map(operationNode), ...mode === "apply" && space.marker !== void 0 ? [{ label: [{
+			text: "marker ",
+			tone: "muted"
+		}, {
+			text: space.marker.storageHash,
+			tone: "identifier"
+		}] }] : []]
+	}));
+}
+function destructiveWarningBlocks(hasDestructive) {
+	return hasDestructive ? [{
+		kind: "summary",
+		status: "warn",
+		text: "This migration contains destructive operations that may cause data loss."
+	}] : [];
+}
+/**
+* The planned or executed operations. The per-space breakdown is the shape the
+* aggregate flow produces; the flat tree is the fallback for a result that
+* carries no breakdown.
+*/
+function perSpaceBlocks(perSpace, mode) {
+	const hasDestructive = perSpace.some((space) => space.operations.some((operation) => operation.operationClass === "destructive"));
+	return [{
+		kind: "tree",
+		roots: spaceNodes(perSpace, mode)
+	}, ...destructiveWarningBlocks(hasDestructive)];
+}
+function operationBlocks$1(result) {
+	const perSpace = result.perSpace;
+	if (perSpace !== void 0 && perSpace.length > 0) return perSpaceBlocks(perSpace, result.mode);
+	if (result.plan.operations.length === 0) return [];
+	const hasDestructive = result.plan.operations.some((operation) => operation.operationClass === "destructive");
+	return [{
+		kind: "tree",
+		roots: result.plan.operations.map(operationNode)
+	}, ...destructiveWarningBlocks(hasDestructive)];
+}
+/** The statements a database would run, printed verbatim rather than laid out. */
+function previewBlocks$1(preview) {
+	if (preview === void 0) return [];
+	const header = {
+		kind: "summary",
+		status: "info",
+		tone: "muted",
+		text: previewBlockHeader(preview)
+	};
+	const statements = preview.statements.map((statement) => renderPreviewStatement(statement.text, statement.language)).filter((text) => text !== void 0);
+	return statements.length === 0 ? [header, {
+		kind: "summary",
+		status: "info",
+		tone: "muted",
+		text: "No operations."
+	}] : [header, {
+		kind: "drawing",
+		lines: statements
+	}];
+}
+function planSummaryText(result) {
+	const operations = result.plan.operations.length;
+	const spaces = result.perSpace?.length ?? 0;
+	return spaces > 0 ? `Planned ${operations} operation(s) across ${spaces} contract space${spaces === 1 ? "" : "s"}` : `Planned ${operations} operation(s)`;
+}
+function applySummaryText(result) {
+	const executed = result.execution?.operationsExecuted ?? 0;
+	const spaces = result.perSpace?.length ?? 0;
+	const across = spaces > 0 ? ` across ${spaces} contract space${spaces === 1 ? "" : "s"}` : "";
+	if (executed === 0) return `Database already matches contract${across}`;
+	return `Applied ${executed} operation(s)${across}`;
+}
+function planBlocks(result) {
+	const planned = result.plannedAdvanceRef;
+	return [
+		{
+			kind: "summary",
+			status: "ok",
+			text: planSummaryText(result)
+		},
+		...operationBlocks$1(result),
+		{
+			kind: "fields",
+			rows: [{
+				label: "destination",
+				value: [{
+					text: result.plan.destination.storageHash,
+					tone: "identifier"
+				}]
+			}]
+		},
+		...planned === null || planned === void 0 ? [] : [{
+			kind: "summary",
+			status: "info",
+			text: [{ text: `Would advance ref "${planned.name}" → ` }, {
+				text: planned.hash,
+				tone: "identifier"
+			}]
+		}],
+		...previewBlocks$1(result.plan.preview),
+		{
+			kind: "summary",
+			status: "info",
+			tone: "muted",
+			text: "This is a dry run. No changes were applied."
+		}
+	];
+}
+/**
+* The app-space marker, for a result that carried no per-space breakdown. The
+* label names what the marker covers rather than calling it "the" signature.
+*/
+function fallbackMarkerBlocks(result) {
+	const marker = result.marker;
+	if (marker === void 0 || result.perSpace !== void 0 && result.perSpace.length > 0) return [];
+	return [{
+		kind: "fields",
+		rows: [{
+			label: "App-space marker",
+			value: [{
+				text: marker.storageHash,
+				tone: "identifier"
+			}]
+		}, ...marker.profileHash === void 0 ? [] : [{
+			label: "Profile hash",
+			value: [{
+				text: marker.profileHash,
+				tone: "identifier"
+			}]
+		}]]
+	}];
+}
+function applyBlocks(result) {
+	const advanced = result.advancedRef;
+	return [
+		{
+			kind: "summary",
+			status: "ok",
+			text: applySummaryText(result)
+		},
+		...operationBlocks$1(result),
+		...fallbackMarkerBlocks(result),
+		...advanced === null || advanced === void 0 ? [] : [{
+			kind: "summary",
+			status: "ok",
+			text: [{ text: `Advanced ref "${advanced.name}" → ` }, {
+				text: advanced.hash,
+				tone: "identifier"
+			}]
+		}]
+	];
+}
+/** What a `db init` / `db update` result looks like in human mode. */
+function migrationResultBlocks(result) {
+	return result.mode === "plan" ? planBlocks(result) : applyBlocks(result);
+}
+/** Where the user goes next, as typed actions rather than trailing prose. */
+function migrationResultNextActions(result, applyCommand) {
+	return result.mode === "plan" ? [runCommandAction("Apply the planned operations", applyCommand)] : [runCommandAction(result.perSpace !== void 0 && result.perSpace.length === 1 ? "Confirm the space is up to date" : "Confirm every space is up to date", "prisma-next migration status")];
+}
+/**
 * Where migrations live for this project. Resolved against the invocation
 * directory, which is also the config file's directory for every default
 * invocation.
@@ -267,6 +496,13 @@ function appMigrationsDirFor(config, cwd) {
 	return spaceMigrationDirectory(migrationsDirFor(config, cwd), APP_SPACE_ID);
 }
 /**
+* Where refs live. The framework keeps them under the app subspace rather than
+* at the migrations root.
+*/
+function appRefsDirFor(config, cwd) {
+	return resolve(appMigrationsDirFor(config, cwd), "refs");
+}
+/**
 * The emitted contract. The config loader has already resolved
 * `contract.output` against the config file's directory, so this only has an
 * effect for a config handed in raw, as tests do.
@@ -282,6 +518,711 @@ function contractPathFor(config, cwd) {
 function displayPath(path, cwd) {
 	return relative(cwd, path);
 }
+/** Reads the emitted contract as the raw document the control API validates. */
+async function readContractDocument(contractPath) {
+	let content;
+	try {
+		content = await readFile(contractPath, "utf-8");
+	} catch (error) {
+		return notOk(normalizeError(Reflect.get(Object(error), "code") === "ENOENT" ? errorFileNotFound(contractPath, {
+			why: `Contract file not found at ${contractPath}`,
+			fix: "Run `prisma-next contract emit` to generate contract.json, or update `contract.output` in prisma-next.config.ts"
+		}) : errorUnexpected(error instanceof Error ? error.message : String(error), { why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}` })));
+	}
+	try {
+		return ok(castAs(JSON.parse(content)));
+	} catch (error) {
+		return notOk(normalizeError(errorContractValidationFailed(`Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`, { where: { path: contractPath } })));
+	}
+}
+async function prepareMigrationRun(inputs) {
+	const { config, cwd, commandName } = inputs;
+	const contractPath = contractPathFor(config, cwd);
+	if (contractPath === void 0) return notOk(normalizeError(errorConfigValidation$1("contract.output", {
+		why: `${commandName} reads the emitted contract from config.contract.output; the config has no value to read.`,
+		section: "contract"
+	})));
+	const contract = await readContractDocument(contractPath);
+	if (!contract.ok) return notOk(contract.failure);
+	const dbConnection = inputs.db ?? config.db?.connection;
+	if (dbConnection === void 0) return notOk(normalizeError(errorDatabaseConnectionRequired({
+		why: `Database connection is required for ${commandName} (set db.connection in prisma-next.config.ts, or pass --db <url>)`,
+		commandName,
+		missingFlags: ["--db"]
+	})));
+	if (config.driver === void 0) return notOk(normalizeError(errorDriverRequired({ why: `Config.driver is required for ${commandName}` })));
+	if (!targetSupportsMigrations(config.target)) return notOk(normalizeError(errorTargetMigrationNotSupported({ why: `Target "${config.target.id}" does not support migrations` })));
+	return ok({
+		client: inputs.createClient({
+			family: config.family,
+			target: config.target,
+			adapter: config.adapter,
+			driver: config.driver,
+			extensions: config.extensions ?? []
+		}),
+		contractJson: contract.value,
+		contractPath,
+		contractDisplayPath: displayPath(contractPath, cwd),
+		dbConnection,
+		database: typeof dbConnection === "string" ? maskConnectionUrl(dbConnection) : void 0,
+		migrationsDir: migrationsDirFor(config, cwd),
+		refsDir: appRefsDirFor(config, cwd)
+	});
+}
+function initPresentations(inputs) {
+	const { document, database, dryRun } = inputs;
+	return {
+		human: () => [{
+			kind: "fields",
+			rail: true,
+			rows: [
+				{
+					label: "contract",
+					value: inputs.contractPath
+				},
+				...database === void 0 ? [] : [{
+					label: "database",
+					value: database
+				}],
+				...dryRun ? [{
+					label: "mode",
+					value: "dry run"
+				}] : []
+			]
+		}, ...migrationResultBlocks(document)],
+		json: () => document,
+		next: () => migrationResultNextActions(document, "prisma-next db init")
+	};
+}
+function initDocument(inputs) {
+	const { value } = inputs;
+	return {
+		ok: true,
+		mode: value.mode,
+		plan: {
+			targetId: inputs.targetId,
+			destination: {
+				storageHash: value.destination.storageHash,
+				...ifDefined("profileHash", value.destination.profileHash)
+			},
+			operations: value.plan.operations.map((operation) => ({
+				id: operation.id,
+				label: operation.label,
+				operationClass: operation.operationClass
+			})),
+			...ifDefined("preview", value.plan.preview)
+		},
+		...value.execution === void 0 ? {} : { execution: {
+			operationsPlanned: value.execution.operationsPlanned,
+			operationsExecuted: value.execution.operationsExecuted
+		} },
+		...value.marker === void 0 ? {} : { marker: {
+			storageHash: value.marker.storageHash,
+			...ifDefined("profileHash", value.marker.profileHash)
+		} },
+		...ifDefined("perSpace", value.perSpace),
+		advancedRef: inputs.advancedRef,
+		plannedAdvanceRef: inputs.plannedAdvanceRef,
+		summary: value.summary,
+		timings: { total: Date.now() - inputs.startedAt }
+	};
+}
+function createDbInitCommand(createClient) {
+	return defineOrmCommand({
+		help: {
+			summary: "Bootstrap a database to match the current contract and sign it",
+			description: "Creates everything the emitted contract declares and the database does not\nhave yet, using additive operations only. Structures already in place and\ncompatible are left alone, a conflict that would need a destructive change\nstops the run, and the database is signed with the contract it now matches.\nUse --dry-run to see the operations without applying them.",
+			examples: [
+				"db init",
+				"db init --db $DATABASE_URL",
+				"db init --dry-run",
+				"db init --advance-ref production"
+			]
+		},
+		args: { flags: {
+			db: dbFlag,
+			dryRun: flag.boolean({ brief: "Preview the planned operations without applying them" }),
+			advanceRef: flag.string({
+				brief: "Advance the named ref to the post-command contract hash",
+				placeholder: "name"
+			})
+		} },
+		needs: { config: ormConfigSection },
+		handler: async (args, ctx) => {
+			const startedAt = Date.now();
+			const prepared = await prepareMigrationRun({
+				config: ctx.config,
+				cwd: ctx.cwd,
+				db: args.flags.db,
+				commandName: "db init",
+				createClient
+			});
+			if (!prepared.ok) return notOk(prepared.failure);
+			const { client, contractJson, contractPath, dbConnection, migrationsDir, refsDir } = prepared.value;
+			let document;
+			try {
+				await client.connect(dbConnection);
+				const result = await client.dbInit({
+					contract: contractJson,
+					mode: args.flags.dryRun ? "plan" : "apply",
+					migrationsDir,
+					onProgress: controlProgressReporter(ctx.report)
+				});
+				if (!result.ok) return notOk(normalizeError(mapDbInitFailure(result.failure)));
+				const advancementHash = result.value.mode === "apply" ? result.value.marker?.storageHash ?? result.value.destination.storageHash : result.value.destination.storageHash;
+				const advancement = await resolveRefAdvancementFields({
+					...ifDefined("advanceRef", args.flags.advanceRef),
+					...ifDefined("db", args.flags.db),
+					refsDir,
+					migrationsDir,
+					contractJson,
+					contractJsonPath: contractPath,
+					mode: result.value.mode,
+					hash: advancementHash
+				});
+				if (!advancement.ok) return notOk(normalizeError(advancement.failure));
+				document = initDocument({
+					value: result.value,
+					targetId: ctx.config.target.targetId,
+					advancedRef: advancement.value.advancedRef,
+					plannedAdvanceRef: advancement.value.plannedAdvanceRef,
+					startedAt
+				});
+			} catch (error) {
+				if (CliStructuredError$1$1.is(error)) return notOk(normalizeError(error));
+				if (isStructuredError(error) && error.code === "CONTRACT.VALIDATION_FAILED") return notOk(normalizeError(errorContractValidationFailed(`Contract validation failed: ${error.message}`, { where: { path: contractPath } })));
+				const safeMessage = sanitizeErrorMessage(error instanceof Error ? error.message : String(error), typeof dbConnection === "string" ? dbConnection : void 0);
+				return notOk(normalizeError(errorUnexpected(safeMessage, { why: `Unexpected error during db init: ${safeMessage}` })));
+			} finally {
+				await closeQuietly(client);
+			}
+			ctx.report({
+				kind: "message",
+				severity: "verbose",
+				text: `Total time: ${document.timings.total}ms`
+			});
+			return ok(ctx.present({ data: document }, initPresentations({
+				document,
+				contractPath: prepared.value.contractDisplayPath,
+				database: prepared.value.database,
+				dryRun: args.flags.dryRun
+			})));
+		}
+	});
+}
+const dbInitCommand = createDbInitCommand(createControlClient);
+const SUMMARY = "Schema read successfully";
+/**
+* A leading keyword and the name it introduces: `<keyword> <name>`, or
+* `<keyword>: <name>`. The keyword recedes and the name is the identifier.
+*/
+function keywordThenName(label) {
+	const colon = label.match(/^(.+?):\s*(\S.*)$/);
+	if (colon?.[1] !== void 0 && colon[2] !== void 0) return [
+		{
+			text: colon[1],
+			tone: "muted"
+		},
+		{ text: ": " },
+		{
+			text: colon[2],
+			tone: "identifier"
+		}
+	];
+	const spaced = label.match(/^(\S.*\S|\S+)\s+(\S+)$/);
+	if (spaced?.[1] !== void 0 && spaced[2] !== void 0) return [
+		{
+			text: spaced[1],
+			tone: "muted"
+		},
+		{ text: " " },
+		{
+			text: spaced[2],
+			tone: "identifier"
+		}
+	];
+}
+/** `<name>: <detail> (<qualifier>)` — the name leads and the qualifier recedes. */
+function namedDetail(label) {
+	const parts = label.match(/^([^:]+):\s*(.+)$/);
+	if (parts?.[1] === void 0 || parts[2] === void 0) return;
+	const [, name, rest] = parts;
+	const qualified = rest.match(/^([^\s(]+)\s*(\([^)]+\))$/);
+	if (qualified?.[1] !== void 0 && qualified[2] !== void 0) return [
+		{
+			text: name,
+			tone: "identifier"
+		},
+		{ text: `: ${qualified[1]} ` },
+		{
+			text: qualified[2],
+			tone: "muted"
+		}
+	];
+	return [{
+		text: name,
+		tone: "identifier"
+	}, { text: `: ${rest}` }];
+}
+/** `<name> <rest>` — the name leads and the prose behind it recedes. */
+function nameThenProse(label) {
+	const parts = label.match(/^(\S+)\s+(\S.*)$/);
+	if (parts?.[1] === void 0 || parts[2] === void 0) return;
+	return [
+		{
+			text: parts[1],
+			tone: "identifier"
+		},
+		{ text: " " },
+		{
+			text: parts[2],
+			tone: "muted"
+		}
+	];
+}
+/**
+* What a schema node's label means, said in tones.
+*
+* The families phrase these labels themselves, so the shapes recognised here
+* are positional (`<keyword> <name>`, `<name>: <detail>`) rather than a list of
+* words: a family that renames a keyword keeps its colouring, and no family's
+* vocabulary is written down in the framework layer.
+*/
+function labelSpans(node) {
+	switch (node.kind) {
+		case "root": return [{
+			text: node.label,
+			tone: "emphasis"
+		}];
+		case "collection": return [{
+			text: node.label,
+			tone: "muted"
+		}];
+		case "entity":
+		case "index": return keywordThenName(node.label) ?? [{
+			text: node.label,
+			tone: "identifier"
+		}];
+		case "field": return namedDetail(node.label) ?? [{ text: node.label }];
+		case "dependency": return nameThenProse(node.label) ?? [{
+			text: node.label,
+			tone: "identifier"
+		}];
+		default: return [{ text: node.label }];
+	}
+}
+function treeNode(node) {
+	return {
+		label: labelSpans(node),
+		...ifDefined("children", node.children === void 0 || node.children.length === 0 ? void 0 : node.children.map(treeNode))
+	};
+}
+function schemaPresentations(inputs) {
+	const { document, schemaView, database } = inputs;
+	return {
+		human: () => [...database === void 0 ? [] : [{
+			kind: "fields",
+			rail: true,
+			rows: [{
+				label: "database",
+				value: database
+			}]
+		}], schemaView === void 0 ? {
+			kind: "summary",
+			status: "ok",
+			text: document.summary
+		} : {
+			kind: "tree",
+			roots: [treeNode(schemaView.root)]
+		}],
+		json: () => document
+	};
+}
+function createDbSchemaCommand(createClient) {
+	return defineOrmCommand({
+		help: {
+			summary: "Inspect the live database schema",
+			description: "Reads the live database schema and prints it as a tree, or as the result\ndocument with --json. Always read-only: it never writes a file and never\nchanges the database.",
+			examples: [
+				"db schema",
+				"db schema --db $DATABASE_URL",
+				"db schema --json"
+			]
+		},
+		args: { flags: { db: dbFlag } },
+		needs: { config: ormConfigSection },
+		handler: async (args, ctx) => {
+			const startedAt = Date.now();
+			const dbConnection = args.flags.db ?? ctx.config.db?.connection;
+			if (dbConnection === void 0) return notOk(normalizeError(errorDatabaseConnectionRequired({
+				why: "Database connection is required for db schema (set db.connection in prisma-next.config.ts, or pass --db <url>)",
+				commandName: "db schema",
+				missingFlags: ["--db"]
+			})));
+			if (ctx.config.driver === void 0) return notOk(normalizeError(errorDriverRequired({ why: "Config.driver is required for db schema" })));
+			const client = createClient({
+				family: ctx.config.family,
+				target: ctx.config.target,
+				adapter: ctx.config.adapter,
+				driver: ctx.config.driver,
+				extensions: ctx.config.extensions ?? []
+			});
+			let schema;
+			let schemaView;
+			try {
+				schema = await client.introspect({
+					connection: dbConnection,
+					onProgress: controlProgressReporter(ctx.report)
+				});
+				schemaView = client.toSchemaView(schema);
+			} catch (error) {
+				if (CliStructuredError$1$1.is(error)) return notOk(normalizeError(error));
+				const safeMessage = sanitizeErrorMessage(error instanceof Error ? error.message : String(error), typeof dbConnection === "string" ? dbConnection : void 0);
+				return notOk(normalizeError(errorUnexpected(safeMessage, { why: `Unexpected error during db schema: ${safeMessage}` })));
+			} finally {
+				await closeQuietly(client);
+			}
+			const database = typeof dbConnection === "string" ? maskConnectionUrl(dbConnection) : void 0;
+			const document = {
+				ok: true,
+				summary: SUMMARY,
+				target: {
+					familyId: ctx.config.family.familyId,
+					id: ctx.config.target.targetId
+				},
+				schema,
+				meta: { ...ifDefined("dbUrl", database) },
+				timings: { total: Date.now() - startedAt }
+			};
+			return ok(ctx.present({ data: document }, schemaPresentations({
+				document,
+				schemaView,
+				database
+			})));
+		}
+	});
+}
+const dbSchemaCommand = createDbSchemaCommand(createControlClient);
+const STATUS_ACTION = runCommandAction("Check every space against the database", "prisma-next migration status");
+/**
+* The route the migration will take. The graph is a drawing — the engine cannot
+* derive a lane gutter — and the ordered list under it is drawn with the same
+* widths so every arrow lands in one column.
+*/
+function showPresentations$1(inputs) {
+	const { document, graph, runList } = inputs;
+	const count = document.migrations.length;
+	return {
+		human: () => [
+			{
+				kind: "fields",
+				rail: true,
+				rows: [
+					{
+						label: "migrations",
+						value: inputs.migrationsDir
+					},
+					...inputs.database === void 0 ? [] : [{
+						label: "database",
+						value: inputs.database
+					}],
+					...inputs.from === void 0 ? [] : [{
+						label: "from",
+						value: inputs.from
+					}],
+					...inputs.to === void 0 ? [] : [{
+						label: "to",
+						value: inputs.to
+					}]
+				]
+			},
+			...graph.length === 0 ? [] : [{
+				kind: "drawing",
+				lines: toneDrawing(graph)
+			}],
+			...count === 0 ? [{
+				kind: "summary",
+				status: "info",
+				text: document.summary
+			}] : [{
+				kind: "summary",
+				status: "info",
+				text: `The following ${count} migration${count === 1 ? "" : "s"} will run:`
+			}, {
+				kind: "drawing",
+				lines: toneDrawing(runList.join("\n"))
+			}]
+		],
+		json: () => document
+	};
+}
+function applyPresentations(inputs) {
+	const { document } = inputs;
+	const advanced = document.advancedRef;
+	return {
+		human: () => [
+			{
+				kind: "fields",
+				rail: true,
+				rows: [
+					{
+						label: "migrations",
+						value: inputs.migrationsDir
+					},
+					...inputs.database === void 0 ? [] : [{
+						label: "database",
+						value: inputs.database
+					}],
+					...inputs.to === void 0 ? [] : [{
+						label: "to",
+						value: inputs.to
+					}]
+				]
+			},
+			{
+				kind: "summary",
+				status: "ok",
+				text: document.summary
+			},
+			...document.perSpace.length === 0 ? [] : perSpaceBlocks(document.perSpace, "apply"),
+			...advanced === null || advanced === void 0 ? [] : [{
+				kind: "summary",
+				status: "ok",
+				text: [{ text: `Advanced ref "${advanced.name}" → ` }, {
+					text: advanced.hash,
+					tone: "identifier"
+				}]
+			}]
+		],
+		json: () => document,
+		next: () => [STATUS_ACTION]
+	};
+}
+/**
+* `--to` as a contract the app graph knows. A ref target keeps the invariants
+* the ref declares; a bare hash carries none. Omitting `--to` targets the
+* emitted contract, which needs no resolution at all.
+*/
+function resolveRequestedTarget(to, refs, graph) {
+	if (to === void 0) return ok({
+		entry: void 0,
+		refName: void 0
+	});
+	const resolved = resolveContractRef(to, {
+		graph,
+		refs
+	});
+	if (!resolved.ok) return notOk(normalizeError(resolved.failure));
+	if (resolved.value.provenance.kind !== "ref") return ok({
+		entry: {
+			hash: resolved.value.hash,
+			invariants: []
+		},
+		refName: void 0
+	});
+	const refName = resolved.value.provenance.refName;
+	return ok({
+		entry: refs[refName],
+		refName
+	});
+}
+function createMigrateCommand(createClient) {
+	return defineOrmCommand({
+		help: {
+			summary: "Apply planned migrations to advance the database",
+			description: "Walks every contract space (app + extensions) and applies pending on-disk\nmigrations in canonical order (extensions alphabetically, then app). It\nreplays the on-disk migration graph and never invents an edge. Use --to to\ntarget a specific contract (hash, ref name, or migration directory) and\n--show for a read-only preview of the route it would take.",
+			examples: [
+				"migrate",
+				"migrate --db $DATABASE_URL",
+				"migrate --to production",
+				"migrate --show",
+				"migrate --show --from @contract --to production"
+			]
+		},
+		args: { flags: {
+			db: dbFlag,
+			to: flag.string({
+				brief: "Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)",
+				placeholder: "contract"
+			}),
+			advanceRef: flag.string({
+				brief: "Advance the named ref to the post-apply marker after success",
+				placeholder: "name"
+			}),
+			show: flag.boolean({ brief: "Preview the migration route without applying (read-only)" }),
+			from: flag.string({
+				brief: "From-state for the --show preview (@contract, @db, hash, ref name, or dir)",
+				placeholder: "contract"
+			})
+		} },
+		needs: { config: ormConfigSection },
+		handler: async (args, ctx) => {
+			const migrationsRelative = displayPath(migrationsDirFor(ctx.config, ctx.cwd), ctx.cwd);
+			if (args.flags.show) {
+				const planned = await executeMigrateShowPlan({
+					config: ctx.config,
+					cwd: ctx.cwd,
+					createClient,
+					...ifDefined("db", args.flags.db),
+					...ifDefined("to", args.flags.to),
+					...ifDefined("from", args.flags.from)
+				});
+				if (!planned.ok) return notOk(normalizeError(planned.failure));
+				const plan = planned.value;
+				const paint = {
+					colorize: true,
+					glyphMode: "unicode",
+					styler: createToneMigrationListStyler(),
+					palette: TONE_MIGRATION_GRAPH_PALETTE
+				};
+				const rendering = renderMigrateShowGraph(plan, paint);
+				const document = {
+					ok: true,
+					migrations: plan.migrations,
+					summary: plan.summary
+				};
+				const dbConnection = args.flags.db ?? ctx.config.db?.connection;
+				return ok(ctx.present({ data: document }, showPresentations$1({
+					document,
+					graph: rendering.graphOutput,
+					runList: migrateShowRunListRows(plan.migrations, rendering, paint),
+					migrationsDir: migrationsRelative,
+					database: args.flags.from === void 0 && typeof dbConnection === "string" ? maskConnectionUrl(dbConnection) : void 0,
+					from: args.flags.from,
+					to: args.flags.to
+				})));
+			}
+			const startedAt = Date.now();
+			const prepared = await prepareMigrationRun({
+				config: ctx.config,
+				cwd: ctx.cwd,
+				db: args.flags.db,
+				commandName: "migrate",
+				createClient
+			});
+			if (!prepared.ok) return notOk(prepared.failure);
+			const { client, contractJson, contractPath, dbConnection, migrationsDir, refsDir } = prepared.value;
+			const familyInstance = ctx.config.family.create(createControlStack(ctx.config));
+			let appContract;
+			try {
+				appContract = familyInstance.deserializeContract(contractJson);
+			} catch (error) {
+				return notOk(normalizeError(errorContractValidationFailed(`Contract at ${contractPath} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`, { where: { path: contractPath } })));
+			}
+			const loaded = await loadContractSpaceAggregateForCli({
+				targetId: ctx.config.target.targetId,
+				migrationsDir,
+				appContract,
+				extensions: ctx.config.extensions ?? [],
+				deserializeContract: (json) => familyInstance.deserializeContract(json)
+			});
+			if (!loaded.ok) return notOk(normalizeError(loaded.failure));
+			const aggregate = loaded.value;
+			const integrityFailure = refuseContractSpaceIntegrity(aggregate, {
+				declaredExtensions: toDeclaredExtensionsFromRaw(castAs(ctx.config.extensions ?? [])),
+				checkContracts: true
+			});
+			if (integrityFailure) return notOk(normalizeError(integrityFailure));
+			const target = resolveRequestedTarget(args.flags.to, aggregate.app.refs, aggregate.app.graph());
+			if (!target.ok) return notOk(target.failure);
+			let document;
+			try {
+				await client.connect(dbConnection);
+				const appGraph = aggregate.app.graph();
+				const appMarker = (await client.readAllMarkers()).get("app") ?? null;
+				if (appMarker !== null) {
+					const markerRefusal = refuseMarkerOutsideGraph({
+						markerHash: appMarker.storageHash,
+						graph: appGraph
+					});
+					if (markerRefusal) return notOk(normalizeError(markerRefusal));
+				}
+				const refEntry = target.value.entry;
+				if (refEntry !== void 0 && refEntry.invariants.length > 0) {
+					const invariantRefusal = refuseUnknownInvariants({
+						graph: appGraph,
+						markerInvariants: appMarker?.invariants ?? [],
+						refInvariants: refEntry.invariants,
+						...ifDefined("refName", args.flags.to)
+					});
+					if (invariantRefusal) return notOk(normalizeError(invariantRefusal));
+				}
+				let applyContract = appContract;
+				let snapshotContractJson = contractJson;
+				let snapshotContractDts;
+				if (args.flags.to !== void 0 && refEntry !== void 0) {
+					if (aggregate.app.packages.find((p) => p.metadata.to === refEntry.hash) !== void 0) try {
+						const at = await aggregate.app.contractAt(refEntry.hash, target.value.refName === void 0 ? void 0 : { refName: target.value.refName });
+						applyContract = at.contract;
+						snapshotContractJson = blindCast(at.contractJson);
+						snapshotContractDts = at.contractDts;
+					} catch (error) {
+						const mapped = mapContractAtError(error, { artifactRole: "to" });
+						if (!mapped.ok) return notOk(normalizeError(mapped.failure));
+						throw error;
+					}
+				}
+				const applied = await client.migrate({
+					contract: applyContract,
+					migrationsDir,
+					onProgress: controlProgressReporter(ctx.report),
+					...ifDefined("refHash", refEntry?.hash),
+					...refEntry?.invariants === void 0 ? {} : { refInvariants: refEntry.invariants },
+					...refEntry === void 0 ? {} : ifDefined("refName", args.flags.to)
+				});
+				if (!applied.ok) return notOk(normalizeError(mapMigrateFailure(applied.failure)));
+				const { value } = applied;
+				let advancedRef = null;
+				if (args.flags.advanceRef !== void 0) {
+					const contractIR = snapshotContractDts === void 0 ? await readContractIR(snapshotContractJson, contractPath) : {
+						contract: snapshotContractJson,
+						contractDts: snapshotContractDts
+					};
+					const advanced = await advanceRefSafely({
+						refsDir,
+						migrationsDir,
+						name: args.flags.advanceRef,
+						hash: value.markerHash,
+						contractIR
+					});
+					if (!advanced.ok) return notOk(normalizeError(advanced.failure));
+					advancedRef = {
+						name: advanced.value.name,
+						hash: advanced.value.hash
+					};
+				}
+				document = {
+					ok: true,
+					migrationsApplied: value.migrationsApplied,
+					migrationsTotal: value.applied.length,
+					markerHash: value.markerHash,
+					applied: value.applied,
+					summary: value.summary,
+					perSpace: value.perSpace,
+					...ifDefined("pathDecision", value.pathDecision),
+					timings: { total: Date.now() - startedAt },
+					advancedRef
+				};
+			} catch (error) {
+				return notOk(normalizeError(mapCaughtMigrationError(error) ?? errorUnexpected(error instanceof Error ? error.message : String(error), { why: `Unexpected error during migrate: ${error instanceof Error ? error.message : String(error)}` })));
+			} finally {
+				await closeQuietly(client);
+			}
+			ctx.report({
+				kind: "message",
+				severity: "verbose",
+				text: `Total time: ${document.timings.total}ms`
+			});
+			return ok(ctx.present({ data: document }, applyPresentations({
+				document,
+				migrationsDir: migrationsRelative,
+				database: prepared.value.database,
+				to: args.flags.to
+			})));
+		}
+	});
+}
+const migrateCommand = createMigrateCommand(createControlClient);
 /**
 * The tree is a drawing for a reader; the DOT document is a graph description
 * for another program, so it is the one thing here that belongs on stdout.
@@ -478,16 +1419,6 @@ const migrationListCommand = defineOrmCommand({
 		})));
 	}
 });
-/**
-* The database connection override, declared from here by every command that
-* accepts one so its brief and placeholder cannot drift apart. Resolution
-* order is the flag, then `config.db.connection`, then
-* `CONFIG.DB_CONNECTION_REQUIRED`.
-*/
-const dbFlag = flag.string({
-	brief: "Database connection string",
-	placeholder: "url"
-});
 const HEADING_APPLIED_AT = "Applied at";
 const HEADING_SPACE = "Space";
 const HEADING_MIGRATION = "Migration";
@@ -627,7 +1558,7 @@ function operationBlocks(migration) {
 * than laid out, so nothing is re-wrapped between here and the reader.
 */
 function previewBlocks(migration) {
-	const statements = migration.preview.statements.map((statement) => statement.text.trim()).filter((text) => text.length > 0).map((text) => text.endsWith(";") ? text : `${text};`);
+	const statements = migration.preview.statements.map((statement) => renderPreviewStatement(statement.text, statement.language)).filter((text) => text !== void 0);
 	if (statements.length === 0) return [];
 	return [{
 		kind: "summary",
@@ -843,6 +1774,9 @@ const DOCS_BASE_URL = `${DOCS_BASE}/`;
 const ormCommandFamily = defineCommandFamily({
 	configSection: ormConfigSection,
 	commands: {
+		"db init": dbInitCommand,
+		"db schema": dbSchemaCommand,
+		migrate: migrateCommand,
 		"migration graph": migrationGraphCommand,
 		"migration list": migrationListCommand,
 		"migration log": migrationLogCommand,