prisma-next 0.11.0 → 0.12.0-dev.10

package/dist/{command-helpers-BSb0tRC8.mjs → command-helpers-Bbw1GbwL.mjs}

@@ -1,18 +1,253 @@
-import { t as __exportAll } from "./rolldown-runtime-twds-ZHy.mjs";
-import { d as errorInvalidOutputFormat, m as errorOutputFormatMutex, t as CliStructuredError } from "./cli-errors-Djtz98Vm.mjs";
-import { a as isCI, i as formatErrorOutput, o as createColorFormatter, r as formatErrorJson, s as formatDim, t as createTerminalUI } from "./terminal-ui-BiB_8KNo.mjs";
+import { CliStructuredError as CliStructuredError$1, errorConfigValidation as errorConfigValidation$1, errorContractConfigMissing as errorContractConfigMissing$1, errorContractValidationFailed, errorDatabaseConnectionRequired, errorDriverRequired, errorFileNotFound, errorInvalidOutputFormat, errorMigrationPlanningFailed, errorOutputFormatMutex, errorTargetMigrationNotSupported, errorUnexpected as errorUnexpected$1 } from "@prisma-next/errors/control";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { notOk } from "@prisma-next/utils/result";
 import { relative, resolve } from "pathe";
 import { readFile } from "node:fs/promises";
 import { hasMigrations } from "@prisma-next/framework-components/control";
-import { readMigrationsDir } from "@prisma-next/migration-tools/io";
-import { reconstructGraph } from "@prisma-next/migration-tools/migration-graph";
+import { ERROR_CODE_DESTRUCTIVE_CHANGES, errorDestructiveChanges, errorHashMismatch, errorMarkerMissing, errorRunnerFailed, errorRuntime, errorRuntime as errorRuntime$1, errorTargetMismatch } from "@prisma-next/errors/execution";
+import "@prisma-next/errors/migration";
 import { APP_SPACE_ID as APP_SPACE_ID$1, spaceMigrationDirectory } from "@prisma-next/migration-tools/spaces";
-import { blue, bold, cyan, dim, green, magenta } from "colorette";
+import { blue, bold, cyan, dim, green, magenta, red, yellow } from "colorette";
 import wrapAnsi from "wrap-ansi";
 import stringWidth from "string-width";
 import stripAnsi from "strip-ansi";
+import { isCI } from "ci-info";
+import * as clack from "@clack/prompts";
+//#region src/utils/cli-errors.ts
+function errorRefSetHashNotInGraph(resolvedHash, reachableHashes, graphTipHash) {
+	const reachableList = reachableHashes.length > 0 ? reachableHashes.join(", ") : "(none — migration graph is empty)";
+	const fix = reachableHashes.length > 0 ? graphTipHash !== null ? `Set the ref to a graph-node hash such as ${graphTipHash}, or run \`prisma-next migration plan\` to extend the graph.` : "Set the ref to a hash that appears in the migration graph." : "Run `prisma-next migration plan` first.";
+	return errorRuntime(`Resolved contract hash is not in the migration graph: ${resolvedHash}`, {
+		why: reachableHashes.length > 0 ? `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.` : "The migration graph is empty — no hashes reachable.",
+		fix,
+		meta: {
+			code: "MIGRATION.HASH_NOT_IN_GRAPH",
+			resolvedHash,
+			reachableHashes: [...reachableHashes],
+			...graphTipHash !== null ? { graphTipHash } : {}
+		}
+	});
+}
+function errorRefSetEmptySentinel(hash) {
+	return errorRuntime(`Cannot set ref to the empty-database sentinel: ${hash}`, {
+		why: "The empty-database sentinel is a planner internal; it is not a valid ref target.",
+		fix: "Set the ref to a contract hash from the migration graph, or use another ref name.",
+		meta: {
+			code: "MIGRATION.REF_SET_EMPTY_SENTINEL",
+			hash
+		}
+	});
+}
+/**
+* `--space <id>` was given a value that doesn't satisfy the contract-space
+* naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before
+* any fs work — the input is syntactically rejected the same way an on-disk
+* directory with that name would be skipped by the enumerator.
+*/
+function errorInvalidSpaceId(spaceId) {
+	return errorRuntime(`Invalid contract space id: ${spaceId}`, {
+		why: "Contract space ids must match [a-z][a-z0-9_-]{0,63} (lowercase, starts with a letter, max 64 characters — the rule applied to every on-disk space directory).",
+		fix: "Pass a space id that matches the directory naming rule, or omit --space to list every space.",
+		meta: {
+			code: "MIGRATION.INVALID_SPACE_ID",
+			spaceId
+		}
+	});
+}
+/**
+* `migration list --space <id>` was given a contract-space id that has no
+* directory under `migrations/`. Distinct from "the space exists but is
+* empty" — that path renders the empty-state line and exits 0 per the
+* slice spec § Empty-state. This error fires only when `<projectMigrationsDir>/<spaceId>`
+* does not exist on disk.
+*
+* `availableSpaces` lists the contract-space directory names actually
+* present, sorted lex-asc, so the diagnostic can suggest a near match
+* without making the user reach for `ls`.
+*/
+function errorSpaceNotFound(spaceId, availableSpaces) {
+	const availableList = availableSpaces.length > 0 ? availableSpaces.join(", ") : "(none — no contract spaces on disk yet)";
+	const fix = availableSpaces.length > 0 ? `Pick one of: ${availableList}. Run \`prisma-next migration list\` (no --space) to see every space's migrations.` : "Author a migration with `prisma-next migration new` to create the first contract-space directory.";
+	return errorRuntime(`Unknown contract space: ${spaceId}`, {
+		why: `No directory named "${spaceId}" exists under the migrations root.`,
+		fix,
+		meta: {
+			code: "MIGRATION.SPACE_NOT_FOUND",
+			spaceId,
+			availableSpaces: [...availableSpaces]
+		}
+	});
+}
+function errorRefSetBundleNotFound(hash) {
+	return errorRuntime(`No migration bundle matches graph-node hash ${hash}`, {
+		why: `The hash is a graph node but no on-disk bundle has metadata.to = ${hash}.`,
+		fix: "Run `pnpm fixtures:check`, or re-emit the migration that produces this hash so its bundle is restored.",
+		meta: {
+			code: "MIGRATION.REF_SET_BUNDLE_NOT_FOUND",
+			hash
+		}
+	});
+}
+function errorPlanForgotTheFlag(resolvedHash, reachableRefs, graphTipHash) {
+	const reachableList = reachableRefs.length > 0 ? reachableRefs.map((r) => `${r.name} (${r.hash})`).join(", ") : "(none)";
+	const refFix = reachableRefs.length > 0 ? `Run migration plan with ${reachableRefs.map((r) => `--from ${r.name}`).join(" or ")}.` : graphTipHash !== null ? `Run migration plan --from ${graphTipHash}.` : "Commit pending migrations first, then run migration plan.";
+	return errorRuntime(`Resolved from-hash is not in the migration graph: ${resolvedHash}`, {
+		why: `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`,
+		fix: refFix,
+		meta: {
+			code: "MIGRATION.HASH_NOT_IN_GRAPH",
+			resolvedHash,
+			reachableRefs: reachableRefs.map((r) => r.name),
+			...graphTipHash !== null ? { graphTipHash } : {}
+		}
+	});
+}
+function errorSnapshotMissing(identifier, options) {
+	const viaRef = options?.viaRef !== false;
+	const fix = viaRef ? `Run "prisma-next db update --advance-ref ${identifier}" to repopulate the snapshot, or "prisma-next ref delete ${identifier}" to clear the orphan pointer.` : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;
+	return errorRuntime(viaRef ? `Ref "${identifier}" has no paired contract snapshot` : `No contract source for from-hash "${identifier}"`, {
+		why: viaRef ? `Ref "${identifier}" exists but its paired snapshot files are missing.` : `Hash "${identifier}" is not a graph node and no paired ref snapshot supplies a contract.`,
+		fix,
+		meta: {
+			code: "MIGRATION.SNAPSHOT_MISSING",
+			identifier,
+			viaRef
+		}
+	});
+}
+function errorMarkerMismatch(markerHash, reachableHashes, graphTip) {
+	const reachableList = reachableHashes.length > 0 ? reachableHashes.join(", ") : "(none — migration graph is empty)";
+	const planFromFix = graphTip !== null ? `Run \`prisma-next migration plan --from ${graphTip}\` if the live marker is canonical and the on-disk graph needs catching up.` : "Run `prisma-next migration plan` if the live marker is canonical and the on-disk graph needs catching up.";
+	return errorRuntime("Database marker is not reachable in the on-disk migration graph", {
+		why: `DB marker is ${markerHash}, but the on-disk migration graph reaches: ${reachableList}.`,
+		fix: [
+			planFromFix,
+			`Run \`prisma-next ref set db ${markerHash}\` if the on-disk graph is canonical and the local \`db\` ref drifted.`,
+			"Investigate whether the database was migrated by an out-of-band process."
+		].join("\n"),
+		meta: {
+			code: "MIGRATION.MARKER_MISMATCH",
+			markerHash,
+			reachableHashes: [...reachableHashes],
+			...graphTip !== null ? { graphTip } : {}
+		}
+	});
+}
+function errorPathUnreachable(failure) {
+	const meta = failure.meta ?? {};
+	const fromHashMeta = typeof meta["fromHash"] === "string" ? meta["fromHash"] : null;
+	const planFromHash = fromHashMeta === "<empty>" ? null : fromHashMeta;
+	const targetHash = typeof meta["targetHash"] === "string" ? meta["targetHash"] : typeof meta["target"] === "string" ? meta["target"] : null;
+	const deadEnds = meta["deadEnds"];
+	const deadEndsSuffix = Array.isArray(deadEnds) && deadEnds.length > 0 ? ` Dead-ends: ${deadEnds.map(String).join(", ")}.` : "";
+	const planCommand = (() => {
+		if (planFromHash !== null && targetHash !== null) return `prisma-next migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;
+		if (targetHash !== null) return `prisma-next migration plan --to ${targetHash} --name <slug>`;
+		if (planFromHash !== null) return `prisma-next migration plan --from ${planFromHash} --name <slug>`;
+		return "prisma-next migration plan";
+	})();
+	const applyCommand = targetHash !== null ? `prisma-next migrate --to ${targetHash}` : "prisma-next migrate";
+	return errorRuntime(failure.summary, {
+		why: failure.why ?? `Cannot reach target "${targetHash ?? "<unknown>"}" from current marker "${fromHashMeta ?? "<unknown>"}".${deadEndsSuffix}`,
+		fix: [
+			"Plan the missing edge, then apply it:",
+			`  1. ${planCommand}`,
+			`  2. ${applyCommand}`,
+			"A rollback (reverse) plan is expected to contain destructive (DROP) operations — review them before applying.",
+			"Narrower cases (rename inference, re-adding a NOT NULL column without a safe default, or a type change that needs data) may additionally need a hint in the planned migration.",
+			"Inspect the on-disk graph with `prisma-next migration list`, or `prisma-next migration show <bundle>` for any bundle in the path you expected."
+		].join("\n"),
+		meta: {
+			...meta,
+			code: "MIGRATION.PATH_UNREACHABLE"
+		}
+	});
+}
+/**
+* Maps a `MigrationToolsError` raised by the migration-tools loader/graph
+* surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,
+* `resolveRef`, `reconstructGraph`, ...) into a CLI `errorRuntime` envelope.
+*
+* The full `error.details` payload is forwarded into `meta` so machine
+* consumers (`--json`) see structural fields like `dir`, `storedHash`,
+* `computedHash` (for `MIGRATION.HASH_MISMATCH`) alongside the stable
+* `code`. The user-visible `summary`/`why`/`fix` text is unchanged.
+*
+* Callers are expected to gate on `MigrationToolsError.is(error)` first
+* (mirroring the original inline pattern); non-`MigrationToolsError`
+* values are caller-classified (rethrow, wrap with command-specific
+* `errorUnexpected`, etc.).
+*/
+function mapMigrationToolsError(error) {
+	return errorRuntime(error.message, {
+		why: error.why,
+		fix: error.fix,
+		meta: {
+			code: error.code,
+			...error.details ?? {}
+		}
+	});
+}
+/**
+* Maps a `RefResolutionError` from the contract/migration reference
+* resolver into a CLI structured error envelope.
+*/
+function mapRefResolutionError(error) {
+	switch (error.kind) {
+		case "not-found": return errorRuntime(`Not a known ${error.grammar} reference: "${error.input}"`, {
+			why: `No ${error.grammar} matching "${error.input}" exists in the migration graph or refs index.`,
+			fix: error.grammar === "contract" ? "Provide a valid contract hash, ref name, or migration directory name." : "Provide a valid migration directory name or migration hash.",
+			meta: {
+				input: error.input,
+				grammar: error.grammar
+			}
+		});
+		case "ambiguous": return errorRuntime(`Ambiguous ${error.grammar} reference: "${error.input}"`, {
+			why: `"${error.input}" matches multiple ${error.grammar}s: ${error.candidates.join(", ")}`,
+			fix: "Provide a longer prefix or use the full hash to disambiguate.",
+			meta: {
+				input: error.input,
+				candidates: error.candidates,
+				grammar: error.grammar
+			}
+		});
+		case "wrong-grammar": return errorRuntime(error.message, {
+			why: error.message,
+			fix: error.fix,
+			meta: {
+				input: error.input,
+				expectedGrammar: error.expectedGrammar
+			}
+		});
+		case "invalid-format": return errorRuntime(`Invalid reference format: "${error.input}"`, {
+			why: error.reason,
+			fix: "Provide a valid contract hash, ref name, or migration directory name.",
+			meta: { input: error.input }
+		});
+	}
+}
+//#endregion
+//#region src/utils/formatters/helpers.ts
+/**
+* Checks if verbose output is enabled at the specified level.
+*/
+function isVerbose(flags, level) {
+	return (flags.verbose ?? 0) >= level;
+}
+/**
+* Creates a color-aware formatter function.
+* Returns a function that applies the color only if colors are enabled.
+*/
+function createColorFormatter(useColor, colorFn) {
+	return useColor ? colorFn : (text) => text;
+}
+/**
+* Formats text with dim styling if colors are enabled.
+*/
+function formatDim(useColor, text) {
+	return useColor ? dim(text) : text;
+}
+//#endregion
 //#region src/utils/formatters/styled.ts
 /**
 * Fixed width for left column in help output.
@@ -417,6 +652,75 @@ function formatRootHelp(options) {
 	return `${lines.join("\n")}\n`;
 }
 //#endregion
+//#region src/utils/is-ci.ts
+/**
+* Returns true when the process is running in any CI environment recognised
+* by the `ci-info` package. The single source of truth for CI detection
+* across this CLI — colour-output suppression and telemetry-skip both call
+* this helper, so neither path drifts from the other when a new CI provider
+* is added upstream.
+*
+* `ci-info` checks the standard `CI=true` marker plus dozens of
+* provider-specific environment variables (Buildkite, Jenkins, Drone,
+* Bitbucket Pipelines, Azure Pipelines, AWS CodeBuild, …) that the raw
+* `process.env.CI` read misses.
+*
+*/
+function isCI$1() {
+	return isCI;
+}
+//#endregion
+//#region src/utils/formatters/errors.ts
+/**
+* Formats error output for human-readable display.
+*/
+function formatErrorOutput(error, flags) {
+	const lines = [];
+	const useColor = flags.color !== false;
+	const formatRed = createColorFormatter(useColor, red);
+	const formatDimText = (text) => formatDim(useColor, text);
+	lines.push(`${formatRed("✖")} ${error.summary} (${error.code})`);
+	if (error.why) lines.push(`${formatDimText(`  Why: ${error.why}`)}`);
+	if (error.fix) lines.push(`${formatDimText(`  Fix: ${error.fix}`)}`);
+	if (error.where?.path) {
+		const whereLine = error.where.line ? `${error.where.path}:${error.where.line}` : error.where.path;
+		lines.push(`${formatDimText(`  Where: ${whereLine}`)}`);
+	}
+	if (error.meta?.["conflicts"]) {
+		const conflicts = error.meta["conflicts"];
+		if (conflicts.length > 0) {
+			const maxToShow = isVerbose(flags, 1) ? conflicts.length : Math.min(3, conflicts.length);
+			const header = isVerbose(flags, 1) ? "  Conflicts:" : `  Conflicts (showing ${maxToShow} of ${conflicts.length}):`;
+			lines.push(`${formatDimText(header)}`);
+			for (const conflict of conflicts.slice(0, maxToShow)) lines.push(`${formatDimText(`    - [${conflict.kind}] ${conflict.summary}`)}`);
+			if (!isVerbose(flags, 1) && conflicts.length > maxToShow) lines.push(`${formatDimText("  Re-run with -v/--verbose to see all conflicts")}`);
+		}
+	}
+	if (error.meta?.["issues"]) {
+		const issues = error.meta["issues"];
+		if (issues.length > 0) {
+			const maxToShow = isVerbose(flags, 1) ? issues.length : Math.min(3, issues.length);
+			const header = isVerbose(flags, 1) ? "  Issues:" : `  Issues (showing ${maxToShow} of ${issues.length}):`;
+			lines.push(`${formatDimText(header)}`);
+			for (const issue of issues.slice(0, maxToShow)) {
+				const kind = issue.kind ?? "issue";
+				const message = issue.message ?? "";
+				lines.push(`${formatDimText(`    - [${kind}] ${message}`)}`);
+			}
+			if (!isVerbose(flags, 1) && issues.length > maxToShow) lines.push(`${formatDimText("  Re-run with -v/--verbose to see all issues")}`);
+		}
+	}
+	if (error.docsUrl && isVerbose(flags, 1)) lines.push(formatDimText(error.docsUrl));
+	if (isVerbose(flags, 2) && error.meta) lines.push(`${formatDimText(`  Meta: ${JSON.stringify(error.meta, null, 2)}`)}`);
+	return lines.join("\n");
+}
+/**
+* Formats error output as JSON.
+*/
+function formatErrorJson(error) {
+	return JSON.stringify(error, null, 2);
+}
+//#endregion
 //#region src/utils/result-handler.ts
 /**
 * Processes a CLI command result, handling both success and error cases.
@@ -438,6 +742,333 @@ function handleResult(result, flags, ui, onSuccess) {
 	return result.failure.domain === "CLI" ? 2 : 1;
 }
 //#endregion
+//#region src/utils/glyph-mode.ts
+function localeString(env) {
+	return env["LC_ALL"] ?? env["LC_CTYPE"] ?? env["LANG"] ?? "";
+}
+function isUtf8Locale(env) {
+	const locale = localeString(env);
+	if (locale.length === 0) return false;
+	return /UTF-8|utf8/i.test(locale);
+}
+function detectGlyphMode(input) {
+	if (!input.isTTY) return "ascii";
+	if (!isUtf8Locale(input.env)) return "ascii";
+	return "unicode";
+}
+//#endregion
+//#region src/utils/shutdown.ts
+function createShutdownHandler(options) {
+	const exit = options?.exit ?? ((code) => process.exit(code));
+	const gracePeriodMs = options?.gracePeriodMs ?? 3e3;
+	const controller = new AbortController();
+	let shuttingDown = false;
+	let graceTimer;
+	const onSignal = () => {
+		if (shuttingDown) {
+			exit(130);
+			return;
+		}
+		shuttingDown = true;
+		controller.abort();
+		graceTimer = setTimeout(() => exit(130), gracePeriodMs);
+		graceTimer.unref();
+	};
+	return {
+		signal: controller.signal,
+		isShuttingDown: () => shuttingDown,
+		onSignal,
+		clearGraceTimer: () => {
+			if (graceTimer !== void 0) {
+				clearTimeout(graceTimer);
+				graceTimer = void 0;
+			}
+		}
+	};
+}
+const globalHandler = createShutdownHandler();
+/**
+* The global AbortSignal. Pass this to any async operation that should
+* be cancellable on Ctrl+C (e.g., DB queries, long-running emit).
+*/
+const shutdownSignal = globalHandler.signal;
+/**
+* Installs SIGINT and SIGTERM handlers. Call once at CLI startup.
+*
+* - First signal: aborts the controller, starts a 3s grace timer.
+* - Second signal: force-exits immediately.
+*/
+let installed = false;
+function installShutdownHandlers() {
+	if (installed) return;
+	installed = true;
+	process.on("SIGINT", globalHandler.onSignal);
+	process.on("SIGTERM", globalHandler.onSignal);
+}
+//#endregion
+//#region src/utils/terminal-ui.ts
+/**
+* Composable CLI output abstraction.
+*
+* Follows the Unix convention of separating data from decoration:
+* - **stdout** — data output only (`ui.output()`). This is what scripts and pipes capture.
+* - **stderr** — all decoration (spinners, logs, notes, intro/outro). Visible in terminal, invisible in pipes.
+*
+* Rules:
+* 1. All methods except `output()` and `error()` write to stderr only in interactive mode.
+* 2. `output(data)` always writes to stdout — if a command calls it, there is data to emit.
+* 3. `error()` always writes to stderr — errors matter even when piped.
+* 4. Decoration is suppressed when piped unless `--format pretty` was explicit (`forcePretty`).
+* 5. Never write data to stderr — decoration methods are for human context only.
+* 6. Never write decoration to stdout — it breaks pipes, `$(...)` captures, and `> file` redirects.
+*/
+var TerminalUI = class TerminalUI {
+	/**
+	* True when stdout is a TTY (interactive terminal).
+	* False when piped (e.g., `prisma-next db verify | jq`).
+	*/
+	isInteractive;
+	/**
+	* Whether color output is enabled.
+	*/
+	useColor;
+	/**
+	* When true, decoration methods write even on non-TTY stdout
+	* (explicit `--format pretty`).
+	*/
+	forcePretty;
+	/**
+	* Whether stdout is a TTY — used for migration-list graph glyph detection.
+	*/
+	stdoutIsTTY;
+	/**
+	* Process environment snapshot for locale-aware glyph detection.
+	*/
+	env;
+	static stderrOpts = { output: process.stderr };
+	constructor(options) {
+		this.isInteractive = options?.interactive ?? !!process.stdout.isTTY;
+		this.forcePretty = options?.forcePretty ?? false;
+		this.useColor = options?.color ?? (this.isInteractive || this.forcePretty);
+		this.stdoutIsTTY = options?.stdoutIsTTY ?? !!process.stdout.isTTY;
+		this.env = options?.env ?? process.env;
+	}
+	get isTTY() {
+		return this.stdoutIsTTY;
+	}
+	/**
+	* Resolve glyph mode for migration list/tree output. `--ascii` forces ASCII;
+	* otherwise delegates to the pure {@link detectGlyphMode} helper.
+	*/
+	resolveGlyphMode(forceAscii) {
+		if (forceAscii) return "ascii";
+		return detectGlyphMode(this.glyphModeInput());
+	}
+	glyphModeInput() {
+		return {
+			isTTY: this.stdoutIsTTY,
+			env: this.env
+		};
+	}
+	get shouldDecorate() {
+		return this.isInteractive || this.forcePretty;
+	}
+	/**
+	* Log a message line to stderr. No-op when piped unless forcePretty.
+	*/
+	log(message) {
+		if (!this.shouldDecorate) return;
+		clack.log.message(message, TerminalUI.stderrOpts);
+	}
+	/**
+	* Log a success message to stderr. No-op when piped unless forcePretty.
+	*/
+	success(message) {
+		if (!this.shouldDecorate) return;
+		clack.log.success(message, TerminalUI.stderrOpts);
+	}
+	/**
+	* Log a warning message to stderr. No-op when piped unless forcePretty.
+	*/
+	warn(message) {
+		if (!this.shouldDecorate) return;
+		clack.log.warn(message, TerminalUI.stderrOpts);
+	}
+	/**
+	* Log an error message to stderr. Always writes (errors matter even in pipes).
+	*/
+	error(message) {
+		clack.log.error(message, TerminalUI.stderrOpts);
+	}
+	/**
+	* Log an info message to stderr. No-op when piped unless forcePretty.
+	*/
+	info(message) {
+		if (!this.shouldDecorate) return;
+		clack.log.info(message, TerminalUI.stderrOpts);
+	}
+	/**
+	* Log a step message to stderr. No-op when piped unless forcePretty.
+	*/
+	step(message) {
+		if (!this.shouldDecorate) return;
+		clack.log.step(message, TerminalUI.stderrOpts);
+	}
+	/**
+	* Display a note box on stderr. No-op when piped unless forcePretty.
+	*/
+	note(message, title) {
+		if (!this.shouldDecorate) return;
+		clack.note(message, title, TerminalUI.stderrOpts);
+	}
+	/**
+	* Display intro banner on stderr. No-op when piped unless forcePretty.
+	*/
+	intro(title) {
+		if (!this.shouldDecorate) return;
+		clack.intro(title, TerminalUI.stderrOpts);
+	}
+	/**
+	* Display outro banner on stderr. No-op when piped unless forcePretty.
+	*/
+	outro(message) {
+		if (!this.shouldDecorate) return;
+		clack.outro(message, TerminalUI.stderrOpts);
+	}
+	/**
+	* Create a Clack spinner on stderr with a 100ms delay threshold.
+	* The spinner only appears if the operation takes longer than the threshold,
+	* avoiding flicker for fast operations. Returns a no-op spinner when not decorating.
+	*/
+	spinner(delayMs = 100) {
+		const noop = {
+			start: () => {},
+			stop: () => {},
+			cancel: () => {},
+			error: () => {},
+			message: () => {},
+			clear: () => {},
+			get isCancelled() {
+				return false;
+			}
+		};
+		if (!this.shouldDecorate) return noop;
+		let inner;
+		let timer;
+		let pendingMsg;
+		let settled = false;
+		const ensureCleared = () => {
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				timer = void 0;
+			}
+		};
+		const onAbort = () => {
+			if (!settled) {
+				settled = true;
+				ensureCleared();
+				if (inner) inner.cancel("Interrupted");
+			}
+		};
+		if (!shutdownSignal.aborted) shutdownSignal.addEventListener("abort", onAbort, { once: true });
+		return {
+			start(msg) {
+				pendingMsg = msg;
+				timer = setTimeout(() => {
+					if (!settled) {
+						inner = clack.spinner(TerminalUI.stderrOpts);
+						inner.start(pendingMsg);
+					}
+				}, delayMs);
+			},
+			stop(msg) {
+				settled = true;
+				ensureCleared();
+				if (inner) inner.stop(msg);
+			},
+			cancel(msg) {
+				settled = true;
+				ensureCleared();
+				if (inner) inner.cancel(msg);
+			},
+			error(msg) {
+				settled = true;
+				ensureCleared();
+				if (inner) inner.error(msg);
+			},
+			message(msg) {
+				pendingMsg = msg;
+				if (inner) inner.message(msg);
+			},
+			clear() {
+				settled = true;
+				ensureCleared();
+				if (inner) inner.clear();
+			},
+			get isCancelled() {
+				return inner?.isCancelled ?? false;
+			}
+		};
+	}
+	/**
+	* Prompt for yes/no confirmation on stderr. Returns true if confirmed.
+	* In non-interactive mode or when cancelled (Ctrl-C), returns false.
+	*/
+	async confirm(message) {
+		if (!this.isInteractive) return false;
+		const result = await clack.confirm({
+			message,
+			...TerminalUI.stderrOpts
+		});
+		if (clack.isCancel(result)) return false;
+		return result;
+	}
+	/**
+	* Write a raw line to stderr. No-op when piped unless forcePretty.
+	* Use for decoration that doesn't fit Clack's log format (e.g. styled headers).
+	*/
+	stderr(message) {
+		if (!this.shouldDecorate) return;
+		process.stderr.write(`${message}\n`);
+	}
+	/**
+	* Write machine-readable data to stdout.
+	* Always writes — if a command calls output(), there is data to emit.
+	*
+	* This is what scripts and pipes capture: `prisma-next db verify --json | jq .ok`
+	*/
+	output(data) {
+		process.stdout.write(`${data}\n`);
+	}
+	green(text) {
+		return this.useColor ? green(text) : text;
+	}
+	red(text) {
+		return this.useColor ? red(text) : text;
+	}
+	cyan(text) {
+		return this.useColor ? cyan(text) : text;
+	}
+	dim(text) {
+		return this.useColor ? dim(text) : text;
+	}
+	bold(text) {
+		return this.useColor ? bold(text) : text;
+	}
+	yellow(text) {
+		return this.useColor ? yellow(text) : text;
+	}
+};
+function createTerminalUI(flags, runtime) {
+	return new TerminalUI({
+		color: flags.color,
+		interactive: flags.interactive,
+		forcePretty: flags.format === "pretty" && flags.explicitFormat,
+		stdoutIsTTY: runtime?.isTTY,
+		env: runtime?.env
+	});
+}
+//#endregion
 //#region src/utils/global-flags.ts
 function isJsonFlagSet(json) {
 	return json === true;
@@ -499,7 +1130,7 @@ function parseGlobalFlagsOrExit(options) {
 	try {
 		return parseGlobalFlags(options);
 	} catch (error) {
-		if (CliStructuredError.is(error)) emitGlobalFlagParseError(error, options);
+		if (CliStructuredError$1.is(error)) emitGlobalFlagParseError(error, options);
 		throw error;
 	}
 }
@@ -525,7 +1156,7 @@ function parseGlobalFlags(options) {
 	if (process.env["NO_COLOR"] || flags.json) flags.color = false;
 	else if (options["no-color"]) flags.color = false;
 	else if (options.color !== void 0) flags.color = options.color;
-	else flags.color = process.stdout.isTTY && !isCI();
+	else flags.color = process.stdout.isTTY && !isCI$1();
 	if (options["no-interactive"]) flags.interactive = false;
 	else if (options.interactive !== void 0) flags.interactive = options.interactive;
 	else flags.interactive = !!process.stdout.isTTY;
@@ -534,26 +1165,6 @@ function parseGlobalFlags(options) {
 }
 //#endregion
 //#region src/utils/command-helpers.ts
-var command_helpers_exports = /* @__PURE__ */ __exportAll({
-	addGlobalOptions: () => addGlobalOptions,
-	collectDeclaredInvariants: () => collectDeclaredInvariants,
-	getCommandExamples: () => getCommandExamples,
-	getCommandSeeAlso: () => getCommandSeeAlso,
-	getLongDescription: () => getLongDescription,
-	getTargetMigrations: () => getTargetMigrations,
-	loadMigrationPackages: () => loadMigrationPackages,
-	maskConnectionUrl: () => maskConnectionUrl,
-	readContractEnvelope: () => readContractEnvelope,
-	resolveContractPath: () => resolveContractPath,
-	resolveMigrationPaths: () => resolveMigrationPaths,
-	sanitizeErrorMessage: () => sanitizeErrorMessage,
-	setCommandDescriptions: () => setCommandDescriptions,
-	setCommandExamples: () => setCommandExamples,
-	setCommandSeeAlso: () => setCommandSeeAlso,
-	targetSupportsMigrations: () => targetSupportsMigrations,
-	toPathDecisionResult: () => toPathDecisionResult,
-	toStructuralEdge: () => toStructuralEdge
-});
 const longDescriptions = /* @__PURE__ */ new WeakMap();
 const commandExamples = /* @__PURE__ */ new WeakMap();
 const commandSeeAlso = /* @__PURE__ */ new WeakMap();
@@ -602,10 +1213,13 @@ function getCommandSeeAlso(command) {
 }
 /**
 * Resolves the absolute path to contract.json from the config.
-* Centralises the fallback logic shared by every command that reads the contract.
 */
 function resolveContractPath(config) {
-	return config.contract?.output ? resolve(config.contract.output) : resolve("src/prisma/contract.json");
+	if (config.contract?.output === void 0) throw errorRuntime$1("config.contract.output is required to resolve the contract path", {
+		why: "CLI commands read the emitted contract from config.contract.output; the config has no value to read.",
+		fix: "Ensure your prisma-next.config.ts goes through `defineConfig()`, which normalises a default output when the provider supplies an input path, or set `contract.output` explicitly."
+	});
+	return resolve(config.contract.output);
 }
 /**
 * Resolves the migrations directory and config path from CLI options.
@@ -683,20 +1297,6 @@ function getTargetMigrations(target) {
 	return hasMigrations(target) ? target.migrations : void 0;
 }
 /**
-* Reads the migrations directory and builds the migration graph from all
-* packages. Throws on I/O or graph errors — callers handle error mapping.
-*
-* Every on-disk package is content-addressed (`migrationHash` is always a
-* string); there is no draft state to filter out.
-*/
-async function loadMigrationPackages(migrationsDir) {
-	const bundles = await readMigrationsDir(migrationsDir);
-	return {
-		bundles,
-		graph: reconstructGraph(bundles)
-	};
-}
-/**
 * Reads and parses contract.json, validating the framework-level envelope
 * fields (storageHash, schemaVersion, target, targetFamily).
 *
@@ -770,6 +1370,6 @@ function addGlobalOptions(command) {
 	} }).option("--format <pretty|json>", "Output format (default: pretty, or json when stdout is not a TTY)").option("--json", "Output as JSON (alias for --format json)").option("-q, --quiet", "Quiet mode: errors only").option("-v, --verbose", "Verbose output: debug info, timings").option("--trace", "Trace output: deep internals, stack traces").option("--color", "Force color output").option("--no-color", "Disable color output").option("--interactive", "Force interactive mode").option("--no-interactive", "Disable interactive prompts").option("-y, --yes", "Auto-accept prompts");
 }
 //#endregion
-export { formatSuccessMessage as C, formatStyledHeader as S, parseGlobalFlags as _, loadMigrationPackages as a, formatCommandHelp as b, resolveContractPath as c, setCommandDescriptions as d, setCommandExamples as f, toStructuralEdge as g, toPathDecisionResult as h, getTargetMigrations as i, resolveMigrationPaths as l, targetSupportsMigrations as m, collectDeclaredInvariants as n, maskConnectionUrl as o, setCommandSeeAlso as p, command_helpers_exports as r, readContractEnvelope as s, addGlobalOptions as t, sanitizeErrorMessage as u, parseGlobalFlagsOrExit as v, formatRootHelp as x, handleResult as y };
+export { errorTargetMigrationNotSupported as $, CliStructuredError$1 as A, errorInvalidSpaceId as B, formatCommandHelp as C, createColorFormatter as D, formatSuccessMessage as E, errorDatabaseConnectionRequired as F, errorPlanForgotTheFlag as G, errorMarkerMissing as H, errorDestructiveChanges as I, errorRefSetHashNotInGraph as J, errorRefSetBundleNotFound as K, errorDriverRequired as L, errorConfigValidation$1 as M, errorContractConfigMissing$1 as N, formatDim as O, errorContractValidationFailed as P, errorSpaceNotFound as Q, errorFileNotFound as R, isCI$1 as S, formatStyledHeader as T, errorMigrationPlanningFailed as U, errorMarkerMismatch as V, errorPathUnreachable as W, errorRuntime$1 as X, errorRunnerFailed as Y, errorSnapshotMissing as Z, createTerminalUI as _, readContractEnvelope as a, formatErrorJson as b, sanitizeErrorMessage as c, setCommandSeeAlso as d, errorTargetMismatch as et, targetSupportsMigrations as f, parseGlobalFlagsOrExit as g, parseGlobalFlags as h, maskConnectionUrl as i, ERROR_CODE_DESTRUCTIVE_CHANGES as j, isVerbose as k, setCommandDescriptions as l, toStructuralEdge as m, collectDeclaredInvariants as n, mapMigrationToolsError as nt, resolveContractPath as o, toPathDecisionResult as p, errorRefSetEmptySentinel as q, getTargetMigrations as r, mapRefResolutionError as rt, resolveMigrationPaths as s, addGlobalOptions as t, errorUnexpected$1 as tt, setCommandExamples as u, installShutdownHandlers as v, formatRootHelp as w, formatErrorOutput as x, handleResult as y, errorHashMismatch as z };
 
-//# sourceMappingURL=command-helpers-BSb0tRC8.mjs.map
+//# sourceMappingURL=command-helpers-Bbw1GbwL.mjs.map