@prisma-next/cli 0.10.0 → 0.11.0-dev.10

package/src/commands/migration-status.ts

@@ -30,7 +30,7 @@ import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import {
-  type CliStructuredError,
+  CliStructuredError,
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
@@ -65,10 +65,10 @@ import {
 } from '../utils/formatters/graph-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import type { StatusDiagnostic, StatusRef } from '../utils/migration-types';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationStatusOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -540,6 +540,40 @@ async function loadContractRawSafely(config: {
   }
 }
 
+async function validateOnlineMarkerRead(
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  dbConnection: unknown,
+): Promise<Result<void, CliStructuredError>> {
+  const driver = config.driver;
+  if (!driver) {
+    return ok(undefined);
+  }
+
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    driver,
+    extensionPacks: config.extensionPacks ?? [],
+  });
+  try {
+    await client.connect(dbConnection);
+    await client.readMarker();
+    return ok(undefined);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read database marker: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  } finally {
+    await client.close();
+  }
+}
+
 async function executeMigrationStatusCommand(
   options: MigrationStatusOptions,
   flags: GlobalFlags,
@@ -666,6 +700,12 @@ async function executeMigrationStatusCommand(
   }
 
   if (bundles.length === 0) {
+    if (dbConnection && hasDriver) {
+      const markerProbe = await validateOnlineMarkerRead(config, dbConnection);
+      if (!markerProbe.ok) {
+        return markerProbe;
+      }
+    }
     if (contractHash !== EMPTY_CONTRACT_HASH) {
       diagnostics.push({
         code: 'CONTRACT.AHEAD',
@@ -750,7 +790,10 @@ async function executeMigrationStatusCommand(
         // space has no marker", which is a different condition).
         allMarkers = null;
       }
-    } catch {
+    } catch (error) {
+      if (CliStructuredError.is(error)) {
+        return notOk(error);
+      }
       if (!flags.json && !flags.quiet) {
         ui.warn('Could not connect to database — showing offline status');
       }
@@ -1097,8 +1140,8 @@ export function createMigrationStatusCommand(): Command {
       'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
     )
     .action(async (options: MigrationStatusOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       const result = await executeMigrationStatusCommand(options, flags, ui);
 

package/src/commands/ref.ts

@@ -1,18 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { findLatestMigration, isGraphNode } from '@prisma-next/migration-tools/migration-graph';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
-  deleteRef,
+  deleteRefPaired,
   readRefs,
   validateRefName,
   validateRefValue,
-  writeRef,
+  writeRefPaired,
 } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
+import { join } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   CliStructuredError,
+  errorFileNotFound,
+  errorRefSetBundleNotFound,
+  errorRefSetEmptySentinel,
+  errorRefSetHashNotInGraph,
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
@@ -25,9 +33,10 @@ import {
   setCommandDescriptions,
 } from '../utils/command-helpers';
 import { formatCommandHelp } from '../utils/formatters/help';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { readContractIR } from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 
 interface RefSetResult {
   readonly ok: true;
@@ -73,13 +82,13 @@ export async function executeRefSetCommand(
   try {
     const config = await loadConfig(options.config);
     const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+    const { graph, bundles } = await loadMigrationPackages(appMigrationsDir);
+    const refs = await readRefs(refsDir);
 
     let resolvedHash: string;
     if (validateRefValue(contractInput)) {
       resolvedHash = contractInput;
     } else {
-      const { graph } = await loadMigrationPackages(appMigrationsDir);
-      const refs = await readRefs(refsDir);
       const refResult = parseContractRef(contractInput, { graph, refs });
       if (!refResult.ok) {
         return notOk(mapRefResolutionError(refResult.failure));
@@ -87,8 +96,39 @@ export async function executeRefSetCommand(
       resolvedHash = refResult.value.hash;
     }
 
+    if (resolvedHash === EMPTY_CONTRACT_HASH) {
+      return notOk(errorRefSetEmptySentinel(resolvedHash));
+    }
+    if (!isGraphNode(resolvedHash, graph)) {
+      const graphTip = findLatestMigration(graph)?.to ?? null;
+      return notOk(errorRefSetHashNotInGraph(resolvedHash, [...graph.nodes].sort(), graphTip));
+    }
+
+    const matchingBundle = bundles.find((bundle) => bundle.metadata.to === resolvedHash);
+    if (!matchingBundle) {
+      return notOk(errorRefSetBundleNotFound(resolvedHash));
+    }
+
+    const contractJsonPath = join(matchingBundle.dirPath, 'end-contract.json');
+    let contractJson: Record<string, unknown>;
+    try {
+      const raw = await readFile(contractJsonPath, 'utf-8');
+      contractJson = JSON.parse(raw) as Record<string, unknown>;
+    } catch (readError) {
+      if (readError instanceof Error && (readError as NodeJS.ErrnoException).code === 'ENOENT') {
+        return notOk(
+          errorFileNotFound(contractJsonPath, {
+            why: `Migration bundle for hash ${resolvedHash} is missing its end-contract snapshot at ${contractJsonPath}`,
+            fix: 'Run `pnpm fixtures:check`, or re-emit the migration so its end-contract.json is restored.',
+          }),
+        );
+      }
+      throw readError;
+    }
+
+    const contractIR = await readContractIR(contractJson, contractJsonPath);
     const entry: RefEntry = { hash: resolvedHash, invariants: [] };
-    await writeRef(refsDir, name, entry);
+    await writeRefPaired(refsDir, name, entry, contractIR);
     return ok({ ok: true as const, ref: name, hash: resolvedHash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -103,7 +143,7 @@ export async function executeRefDeleteCommand(
   try {
     const config = await loadConfig(options.config);
     const { refsDir } = resolveMigrationPaths(options.config, config);
-    await deleteRef(refsDir, name);
+    await deleteRefPaired(refsDir, name);
     return ok({ ok: true as const, ref: name, deleted: true as const });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -145,8 +185,8 @@ function createRefSetCommand(): Command {
         hash: string,
         options: { config?: string; json?: string | boolean; quiet?: boolean },
       ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const flags = parseGlobalFlagsOrExit(options);
+        const ui = createTerminalUI(flags);
         const result = await executeRefSetCommand(name, hash, options);
         const exitCode = handleResult(result, flags, ui, (value) => {
           if (flags.json) {
@@ -172,8 +212,8 @@ function createRefDeleteCommand(): Command {
         name: string,
         options: { config?: string; json?: string | boolean; quiet?: boolean },
       ) => {
-        const flags = parseGlobalFlags(options);
-        const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+        const flags = parseGlobalFlagsOrExit(options);
+        const ui = createTerminalUI(flags);
         const result = await executeRefDeleteCommand(name, options);
         const exitCode = handleResult(result, flags, ui, (value) => {
           if (flags.json) {
@@ -194,8 +234,8 @@ function createRefListCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: { config?: string; json?: string | boolean; quiet?: boolean }) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeRefListCommand(options);
       const exitCode = handleResult(result, flags, ui, (value) => {
         if (flags.json) {

package/src/control-api/operations/apply-aggregate.ts

@@ -178,6 +178,7 @@ export async function applyAggregate<TFamilyId extends string, TTargetId extends
       meta: {
         ...(runnerResult.failure.meta ?? {}),
         failingSpace: runnerResult.failure.failingSpace,
+        runnerErrorCode: runnerResult.failure.code,
       },
     });
   }

package/src/control-api/operations/contract-emit.ts

@@ -5,7 +5,7 @@ import { createControlStack } from '@prisma-next/framework-components/control';
 import { abortable } from '@prisma-next/utils/abortable';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { JsonObject } from '@prisma-next/utils/json';
-import { dirname } from 'pathe';
+import { dirname, join } from 'pathe';
 import { loadConfig } from '../../config-loader';
 import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
 import { queueEmitByOutput } from '../../utils/emit-queue';
@@ -153,7 +153,7 @@ function validateProviderResult(providerResult: unknown): ValidatedProviderResul
 export async function executeContractEmit(
   options: ContractEmitOptions,
 ): Promise<ContractEmitResult> {
-  const { configPath, signal = new AbortController().signal, onProgress } = options;
+  const { configPath, outputPath, signal = new AbortController().signal, onProgress } = options;
   const unlessAborted = abortable(signal);
 
   const config = await unlessAborted(loadConfig(configPath));
@@ -166,7 +166,10 @@ export async function executeContractEmit(
 
   const contractConfig = config.contract;
 
-  if (!contractConfig.output) {
+  const effectiveOutput =
+    outputPath !== undefined ? join(outputPath, 'contract.json') : contractConfig.output;
+
+  if (!effectiveOutput) {
     throw errorContractConfigMissing({
       why: 'Contract config must have output path. This should not happen if defineConfig() was used.',
     });
@@ -180,7 +183,7 @@ export async function executeContractEmit(
 
   let outputPaths: ReturnType<typeof getEmittedArtifactPaths>;
   try {
-    outputPaths = getEmittedArtifactPaths(contractConfig.output);
+    outputPaths = getEmittedArtifactPaths(effectiveOutput);
   } catch (error) {
     throw errorContractConfigMissing({
       why: error instanceof Error ? error.message : String(error),

package/src/control-api/types.ts

@@ -719,6 +719,13 @@ export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyF
 export interface ContractEmitOptions {
   /** Path to the prisma-next.config.ts file */
   readonly configPath: string;
+  /**
+   * Directory to write contract artifacts into. When set, `contract.json` and
+   * `contract.d.ts` are written inside this directory, taking precedence over
+   * any output path from the loaded config. The value must be an absolute path;
+   * resolution against cwd is the caller's responsibility.
+   */
+  readonly outputPath?: string;
   /** Optional AbortSignal for cancelling the in-flight emit */
   readonly signal?: AbortSignal;
   /** Optional progress callback for observing source-resolution and emit spans */

package/src/utils/cli-errors.ts

@@ -16,9 +16,11 @@ import {
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
+  errorInvalidOutputFormat,
   errorMigrationCliInvalidConfigArg,
   errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
+  errorOutputFormatMutex,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -26,6 +28,7 @@ import {
 import { errorRuntime } from '@prisma-next/errors/execution';
 import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';
+import type { MigrationApplyFailure } from '../control-api/types';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -56,14 +59,188 @@ export {
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
+  errorInvalidOutputFormat,
   errorMigrationCliInvalidConfigArg,
   errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
+  errorOutputFormatMutex,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,
 };
 
+export function errorRefSetHashNotInGraph(
+  resolvedHash: string,
+  reachableHashes: readonly string[],
+  graphTipHash: string | null,
+): CliStructuredError {
+  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 } : {}),
+    },
+  });
+}
+
+export function errorRefSetEmptySentinel(hash: string): CliStructuredError {
+  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,
+    },
+  });
+}
+
+export function errorRefSetBundleNotFound(hash: string): CliStructuredError {
+  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,
+    },
+  });
+}
+
+export function errorPlanForgotTheFlag(
+  resolvedHash: string,
+  reachableRefs: ReadonlyArray<{ readonly name: string; readonly hash: string }>,
+  graphTipHash: string | null,
+): CliStructuredError {
+  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 } : {}),
+    },
+  });
+}
+
+export function errorSnapshotMissing(
+  identifier: string,
+  options?: { readonly viaRef?: boolean },
+): CliStructuredError {
+  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,
+      },
+    },
+  );
+}
+
+export function errorMarkerMismatch(
+  markerHash: string,
+  reachableHashes: readonly string[],
+  graphTip: string | null,
+): CliStructuredError {
+  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 } : {}),
+    },
+  });
+}
+
+export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {
+  const meta = failure.meta ?? {};
+  const fromHash = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
+  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 planFix = (() => {
+    if (fromHash !== null && targetHash !== null) {
+      return `Run \`prisma-next migration plan --from ${fromHash} --to ${targetHash}\` to introduce the missing path.`;
+    }
+    if (targetHash !== null) {
+      return `Run \`prisma-next migration plan --to ${targetHash}\` to introduce the missing path.`;
+    }
+    if (fromHash !== null) {
+      return `Run \`prisma-next migration plan --from ${fromHash}\` to introduce the missing path.`;
+    }
+    return 'Run `prisma-next migration plan` to introduce the missing path.';
+  })();
+  return errorRuntime(failure.summary, {
+    why:
+      failure.why ??
+      `Cannot reach target "${targetHash ?? '<unknown>'}" from current marker "${fromHash ?? '<unknown>'}".${deadEndsSuffix}`,
+    fix: [
+      'Run `prisma-next migration list` to see the on-disk graph.',
+      planFix,
+      'Run `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`,

package/src/utils/command-helpers.ts

@@ -11,6 +11,7 @@ import { APP_SPACE_ID, spaceMigrationDirectory } from '@prisma-next/migration-to
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
 import { relative, resolve } from 'pathe';
+import { errorRuntime } from './cli-errors';
 import { formatCommandHelp } from './formatters/help';
 import type { CommonCommandOptions } from './global-flags';
 import { parseGlobalFlags } from './global-flags';
@@ -94,12 +95,15 @@ export interface MigrationCommandOptions extends CommonCommandOptions {
 
 /**
  * Resolves the absolute path to contract.json from the config.
- * Centralises the fallback logic shared by every command that reads the contract.
  */
 export function resolveContractPath(config: { contract?: { output?: string } }): string {
-  return config.contract?.output
-    ? resolve(config.contract.output)
-    : resolve('src/prisma/contract.json');
+  if (config.contract?.output === undefined) {
+    throw errorRuntime('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);
 }
 
 /**
@@ -365,7 +369,7 @@ export function sanitizeErrorMessage(message: string, connectionUrl?: string): s
 
 /**
  * Registers the global CLI options shared by every command:
- * --json, -q/--quiet, -v/--verbose, --trace, --color, --no-color,
+ * --format, --json, -q/--quiet, -v/--verbose, --trace, --color, --no-color,
  * --interactive, --no-interactive, -y/--yes.
  *
  * Also sets up the styled help formatter.
@@ -378,7 +382,11 @@ export function addGlobalOptions(command: Command): Command {
         return formatCommandHelp({ command: cmd, flags });
       },
     })
-    .option('--json', 'Output as JSON')
+    .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')

package/src/utils/formatters/migrations.ts

@@ -82,6 +82,8 @@ export interface MigrationCommandResult {
    * into a single ambiguous list. See {@link AggregatePerSpaceExecutionEntry}.
    */
   readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
+  readonly plannedAdvanceRef?: { readonly name: string; readonly hash: string } | null;
   readonly summary: string;
   readonly timings: {
     readonly total: number;
@@ -208,6 +210,15 @@ export function formatMigrationPlanOutput(
     lines.push(`${formatDimText(`Destination hash: ${result.plan.destination.storageHash}`)}`);
   }
 
+  if (result.plannedAdvanceRef) {
+    lines.push('');
+    lines.push(
+      formatDimText(
+        `Would advance ref "${result.plannedAdvanceRef.name}" → ${result.plannedAdvanceRef.hash}`,
+      ),
+    );
+  }
+
   // Statement preview (any family that implements OperationPreviewCapable)
   const preview = result.plan?.preview;
   if (preview) {
@@ -260,6 +271,7 @@ export interface MigrationApplyCommandOutputResult {
   readonly timings?: {
     readonly total: number;
   };
+  readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
 }
 
 export function formatMigrationApplyCommandOutput(
@@ -284,6 +296,13 @@ export function formatMigrationApplyCommandOutput(
     }
   }
 
+  if (result.advancedRef) {
+    lines.push('');
+    lines.push(
+      formatDimText(`Advanced ref "${result.advancedRef.name}" → ${result.advancedRef.hash}`),
+    );
+  }
+
   lines.push('');
   lines.push(formatDimText('Next: prisma-next migration status'));
 
@@ -470,6 +489,12 @@ export function formatMigrationApplyOutput(
     if (isVerbose(flags, 1)) {
       lines.push(`${formatDimText(`  Total time: ${result.timings.total}ms`)}`);
     }
+
+    if (result.advancedRef) {
+      lines.push(
+        formatDimText(`Advanced ref "${result.advancedRef.name}" → ${result.advancedRef.hash}`),
+      );
+    }
   }
 
   return lines.join('\n');