@prisma-next/cli 0.8.0 → 0.9.0-dev.2

package/src/commands/migration-graph.ts

@@ -0,0 +1,184 @@
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
+import { readRefs } from '@prisma-next/migration-tools/refs';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import {
+  type CliStructuredError,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  loadMigrationPackages,
+  readContractEnvelope,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+  setCommandExamples,
+  setCommandSeeAlso,
+} from '../utils/command-helpers';
+import { migrationGraphToRenderInput } from '../utils/formatters/graph-migration-mapper';
+import { graphRenderer } 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 { StatusRef } from '../utils/migration-types';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface MigrationGraphOptions extends CommonCommandOptions {
+  readonly config?: string;
+  readonly dot?: boolean;
+}
+
+export interface MigrationGraphResult {
+  readonly ok: true;
+  readonly graph: MigrationGraph;
+  readonly contractHash: string | null;
+  readonly refs: readonly StatusRef[];
+  readonly summary: string;
+}
+
+async function executeMigrationGraphCommand(
+  options: MigrationGraphOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<Result<MigrationGraphResult, CliStructuredError>> {
+  const config = await loadConfig(options.config);
+  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  if (!flags.json && !flags.quiet) {
+    const header = formatStyledHeader({
+      command: 'migration graph',
+      description: 'Show the migration graph topology',
+      details: [
+        { label: 'config', value: configPath },
+        { label: 'migrations', value: appMigrationsRelative },
+      ],
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  let graph: MigrationGraph;
+  try {
+    ({ graph } = await loadMigrationPackages(appMigrationsDir));
+  } catch (error) {
+    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  let contractHash: string | null = null;
+  try {
+    const envelope = await readContractEnvelope(config);
+    contractHash = envelope.storageHash;
+  } catch {
+    // Contract unreadable — render graph without contract marker
+  }
+
+  let refs: readonly StatusRef[] = [];
+  try {
+    const allRefs = await readRefs(refsDir);
+    refs = Object.entries(allRefs).map(([name, entry]) => ({
+      name,
+      hash: entry.hash,
+      active: false,
+    }));
+  } catch {
+    // Refs unreadable — render graph without ref markers
+  }
+
+  return ok({
+    ok: true,
+    graph,
+    contractHash,
+    refs,
+    summary: `${graph.nodes.size} node(s), ${graph.migrationByHash.size} edge(s)`,
+  });
+}
+
+export function createMigrationGraphCommand(): Command {
+  const command = new Command('graph');
+  setCommandDescriptions(
+    command,
+    'Show the migration graph topology',
+    'Renders the migration graph as an ASCII tree. Offline — does not\n' +
+      'consult the database. Use --json for machine-readable output or\n' +
+      '--dot for Graphviz DOT format.',
+  );
+  setCommandExamples(command, [
+    'prisma-next migration graph',
+    'prisma-next migration graph --json',
+    'prisma-next migration graph --dot',
+  ]);
+  setCommandSeeAlso(command, [
+    { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
+    { verb: 'migration log', oneLiner: 'Show executed migration history' },
+    { verb: 'migration list', oneLiner: 'List on-disk migrations' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
+  ]);
+  addGlobalOptions(command)
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .option('--dot', 'Output in Graphviz DOT format')
+    .action(async (options: MigrationGraphOptions) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const result = await executeMigrationGraphCommand(options, flags, ui);
+      const exitCode = handleResult(result, flags, ui, (graphResult) => {
+        // Explicit format flags win over the auto-JSON default. `flags.json`
+        // is auto-enabled when stdout is non-TTY (per CLI Style Guide §
+        // JSON Semantics); without this ordering, `migration graph --dot |
+        // dot -Tsvg` pipes JSON into the GraphViz binary, which then
+        // errors. `--dot` is the more specific instruction; honour it.
+        if (options.dot) {
+          const lines = ['digraph migrations {'];
+          for (const edge of graphResult.graph.migrationByHash.values()) {
+            const from = edge.from.slice(0, 12);
+            const to = edge.to.slice(0, 12);
+            lines.push(`  "${from}" -> "${to}" [label="${edge.dirName}"];`);
+          }
+          lines.push('}');
+          ui.output(lines.join('\n'));
+        } else if (flags.json) {
+          const nodes = [...graphResult.graph.nodes];
+          const edges = [...graphResult.graph.migrationByHash.values()].map((e) => ({
+            dirName: e.dirName,
+            from: e.from,
+            to: e.to,
+            migrationHash: e.migrationHash,
+          }));
+          ui.output(
+            JSON.stringify({ ok: true, nodes, edges, summary: graphResult.summary }, null, 2),
+          );
+        } else if (!flags.quiet) {
+          const renderInput = migrationGraphToRenderInput({
+            graph: graphResult.graph,
+            mode: 'offline',
+            markerHash: undefined,
+            contractHash: graphResult.contractHash ?? EMPTY_CONTRACT_HASH,
+            refs: graphResult.refs,
+            activeRefHash: undefined,
+            activeRefName: undefined,
+            edgeStatuses: [],
+          });
+          const graphOutput = graphRenderer.render(renderInput.graph, {
+            ...renderInput.options,
+            colorize: flags.color !== false,
+          });
+          ui.log(graphOutput);
+          ui.log(`\n${graphResult.summary}`);
+        }
+      });
+      process.exit(exitCode);
+    });
+  return command;
+}

package/src/commands/migration-list.ts

@@ -0,0 +1,155 @@
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { findPath } from '@prisma-next/migration-tools/migration-graph';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import {
+  type CliStructuredError,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  loadMigrationPackages,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+  setCommandExamples,
+  setCommandSeeAlso,
+} from '../utils/command-helpers';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import type { CommonCommandOptions } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface MigrationListOptions extends CommonCommandOptions {
+  readonly config?: string;
+}
+
+export interface MigrationListEntry {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly operationCount: number;
+  readonly createdAt: string;
+}
+
+export interface MigrationListResult {
+  readonly ok: true;
+  readonly migrations: readonly MigrationListEntry[];
+  readonly summary: string;
+}
+
+async function executeMigrationListCommand(
+  options: MigrationListOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<Result<MigrationListResult, CliStructuredError>> {
+  const config = await loadConfig(options.config);
+  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  if (!flags.json && !flags.quiet) {
+    const header = formatStyledHeader({
+      command: 'migration list',
+      description: 'List on-disk migrations in topological order',
+      details: [
+        { label: 'config', value: configPath },
+        { label: 'migrations', value: appMigrationsRelative },
+      ],
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
+  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
+  try {
+    ({ bundles, graph } = await loadMigrationPackages(appMigrationsDir));
+  } catch (error) {
+    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  if (bundles.length === 0) {
+    return ok({ ok: true, migrations: [], summary: 'No migrations found' });
+  }
+
+  const leaves = [...graph.nodes].filter(
+    (n) => !graph.forwardChain.has(n) || graph.forwardChain.get(n)!.length === 0,
+  );
+  const targetHash =
+    leaves.length === 1 ? leaves[0]! : ([...graph.nodes].values().next().value as string);
+  const chain = findPath(graph, EMPTY_CONTRACT_HASH, targetHash) ?? [];
+
+  const pkgByDirName = new Map(bundles.map((p) => [p.dirName, p]));
+  const entries: MigrationListEntry[] = chain.map((edge) => {
+    const pkg = pkgByDirName.get(edge.dirName);
+    const ops = (pkg?.ops ?? []) as readonly MigrationPlanOperation[];
+    return {
+      dirName: edge.dirName,
+      from: edge.from,
+      to: edge.to,
+      migrationHash: edge.migrationHash,
+      operationCount: ops.length,
+      createdAt: edge.createdAt,
+    };
+  });
+
+  return ok({
+    ok: true,
+    migrations: entries,
+    summary: `${entries.length} migration(s) on disk`,
+  });
+}
+
+export function createMigrationListCommand(): Command {
+  const command = new Command('list');
+  setCommandDescriptions(
+    command,
+    'List on-disk migrations in topological order',
+    'Enumerates all migration packages under migrations/<space>/ in\n' +
+      'topological order. Offline — does not consult the database.',
+  );
+  setCommandExamples(command, ['prisma-next migration list']);
+  setCommandSeeAlso(command, [
+    { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
+    { verb: 'migration log', oneLiner: 'Show executed migration history' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
+  ]);
+  addGlobalOptions(command)
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (options: MigrationListOptions) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const result = await executeMigrationListCommand(options, flags, ui);
+      const exitCode = handleResult(result, flags, ui, (listResult) => {
+        if (flags.json) {
+          ui.output(JSON.stringify(listResult, null, 2));
+        } else if (!flags.quiet) {
+          if (listResult.migrations.length === 0) {
+            ui.log('No migrations found');
+          } else {
+            for (const entry of listResult.migrations) {
+              ui.log(
+                `${entry.dirName}  ${entry.migrationHash.slice(0, 16)}…  ${entry.operationCount} op(s)`,
+              );
+            }
+            ui.log(`\n${listResult.summary}`);
+          }
+        }
+      });
+      process.exit(exitCode);
+    });
+  return command;
+}

package/src/commands/migration-log.ts

@@ -0,0 +1,218 @@
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { findPath } from '@prisma-next/migration-tools/migration-graph';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { cyan, dim } from 'colorette';
+import { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import { createControlClient } from '../control-api/client';
+import {
+  type CliStructuredError,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  loadMigrationPackages,
+  maskConnectionUrl,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+  setCommandExamples,
+  setCommandSeeAlso,
+  targetSupportsMigrations,
+} from '../utils/command-helpers';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import type { CommonCommandOptions } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface MigrationLogOptions extends CommonCommandOptions {
+  readonly db?: string;
+  readonly config?: string;
+}
+
+export interface MigrationLogEntry {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly operationCount: number;
+  readonly createdAt: string;
+}
+
+export interface MigrationLogResult {
+  readonly ok: true;
+  readonly markerHash: string | null;
+  readonly applied: readonly MigrationLogEntry[];
+  readonly summary: string;
+}
+
+async function executeMigrationLogCommand(
+  options: MigrationLogOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<Result<MigrationLogResult, CliStructuredError>> {
+  const config = await loadConfig(options.config);
+  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  const dbConnection = options.db ?? config.db?.connection;
+  if (!dbConnection) {
+    return notOk(
+      errorDatabaseConnectionRequired({
+        why: `Database connection is required for migration log (set db.connection in ${configPath}, or pass --db <url>)`,
+        commandName: 'migration log',
+      }),
+    );
+  }
+  if (!config.driver) {
+    return notOk(errorDriverRequired({ why: 'Config.driver is required for migration log' }));
+  }
+  if (!targetSupportsMigrations(config.target)) {
+    return notOk(errorUnexpected('Target does not support migrations'));
+  }
+
+  if (!flags.json && !flags.quiet) {
+    const header = formatStyledHeader({
+      command: 'migration log',
+      description: 'Show executed migration history',
+      details: [
+        { label: 'config', value: configPath },
+        { label: 'migrations', value: appMigrationsRelative },
+        ...(typeof dbConnection === 'string'
+          ? [{ label: 'database', value: maskConnectionUrl(dbConnection) }]
+          : []),
+      ],
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
+  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
+  try {
+    ({ bundles, graph } = await loadMigrationPackages(appMigrationsDir));
+  } catch (error) {
+    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    driver: config.driver,
+    extensionPacks: config.extensionPacks ?? [],
+  });
+
+  try {
+    await client.connect(dbConnection);
+    const marker = await client.readMarker();
+    const markerHash = marker?.storageHash ?? null;
+
+    if (!markerHash) {
+      return ok({
+        ok: true,
+        markerHash: null,
+        applied: [],
+        summary: 'No migrations applied (database has no marker)',
+      });
+    }
+
+    const appliedPath = findPath(graph, EMPTY_CONTRACT_HASH, markerHash);
+    if (appliedPath === null) {
+      return notOk(
+        errorUnexpected('Database marker is not reachable from migration history', {
+          why: `Marker hash ${markerHash} is not reachable from the root of the on-disk migration graph.`,
+          fix: 'The database may have been migrated outside this project. Use `migration status` to inspect the current state.',
+        }),
+      );
+    }
+    const pkgByDirName = new Map(bundles.map((p) => [p.dirName, p]));
+    const entries: MigrationLogEntry[] = appliedPath.map((edge) => {
+      const pkg = pkgByDirName.get(edge.dirName);
+      const ops = (pkg?.ops ?? []) as readonly MigrationPlanOperation[];
+      return {
+        dirName: edge.dirName,
+        from: edge.from,
+        to: edge.to,
+        migrationHash: edge.migrationHash,
+        operationCount: ops.length,
+        createdAt: edge.createdAt,
+      };
+    });
+
+    return ok({
+      ok: true,
+      markerHash,
+      applied: entries,
+      summary: `${entries.length} migration(s) applied`,
+    });
+  } catch (error) {
+    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read migration log: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  } finally {
+    await client.close();
+  }
+}
+
+export function createMigrationLogCommand(): Command {
+  const command = new Command('log');
+  setCommandDescriptions(
+    command,
+    'Show executed migration history',
+    'Reads the database marker and displays the applied migration chain\n' +
+      'from the initial state to the current marker position.',
+  );
+  setCommandExamples(command, [
+    'prisma-next migration log --db $DATABASE_URL',
+    'prisma-next migration log --json --db $DATABASE_URL',
+  ]);
+  setCommandSeeAlso(command, [
+    { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
+    { verb: 'migration list', oneLiner: 'List on-disk migrations' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
+  ]);
+  addGlobalOptions(command)
+    .option('--db <url>', 'Database connection string')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (options: MigrationLogOptions) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const result = await executeMigrationLogCommand(options, flags, ui);
+      const exitCode = handleResult(result, flags, ui, (logResult) => {
+        if (flags.json) {
+          ui.output(JSON.stringify(logResult, null, 2));
+        } else if (!flags.quiet) {
+          const c = (fn: (s: string) => string, s: string) => (flags.color !== false ? fn(s) : s);
+          if (logResult.applied.length === 0) {
+            ui.log(logResult.summary);
+          } else {
+            for (const entry of logResult.applied) {
+              ui.log(
+                `${c(cyan, '✓')} ${entry.dirName}  ${c(dim, entry.migrationHash.slice(0, 16) + '…')}  ${entry.operationCount} op(s)`,
+              );
+            }
+            ui.log(`\n${logResult.summary}`);
+          }
+        }
+      });
+      process.exit(exitCode);
+    });
+  return command;
+}

package/src/commands/migration-new.ts

@@ -8,7 +8,7 @@
  * verbatim.
  */
 
-import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { APP_SPACE_ID, createControlStack } from '@prisma-next/framework-components/control';
@@ -32,6 +32,7 @@ import { join, relative } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   CliStructuredError,
+  errorFileNotFound,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -72,11 +73,17 @@ async function executeMigrationNewCommand(
   const config = await loadConfig(options.config);
   const { appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(options.config, config);
 
+  // Construct the family instance up-front so the on-disk contract read
+  // below crosses the serializer seam (`familyInstance.deserializeContract`)
+  // at the read site, not somewhere downstream. See TML-2536.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
   const contractPathAbsolute = resolveContractPath(config);
 
   let contractJsonContent: string;
   try {
-    contractJsonContent = readFileSync(contractPathAbsolute, 'utf-8');
+    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
   } catch (error) {
     if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
       return notOk(
@@ -89,24 +96,20 @@ async function executeMigrationNewCommand(
     throw error;
   }
 
-  let toContractJson: Contract;
+  let toContract: Contract;
   try {
-    toContractJson = JSON.parse(contractJsonContent) as Contract;
+    toContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
   } catch (error) {
     return notOk(
       errorRuntime('Contract JSON is invalid', {
-        why: `Failed to parse ${contractPathAbsolute}: ${error instanceof Error ? error.message : String(error)}`,
+        why: `Failed to deserialize ${contractPathAbsolute}: ${error instanceof Error ? error.message : String(error)}`,
         fix: 'Run `prisma-next contract emit` to regenerate the contract',
       }),
     );
   }
 
-  const toStorageHash = (
-    (toContractJson as unknown as Record<string, unknown>)['storage'] as
-      | Record<string, unknown>
-      | undefined
-  )?.['storageHash'] as string | undefined;
-  if (!toStorageHash) {
+  const toStorageHash = toContract.storage?.storageHash;
+  if (typeof toStorageHash !== 'string') {
     return notOk(
       errorRuntime('Contract is missing storageHash', {
         why: `Contract at ${contractPathAbsolute} has no storageHash`,
@@ -115,7 +118,6 @@ async function executeMigrationNewCommand(
     );
   }
 
-  let fromContract: Contract | null = null;
   let fromHash: string | null = null;
   let fromContractSourceDir: string | null = null;
 
@@ -136,7 +138,6 @@ async function executeMigrationNewCommand(
           );
         }
         fromHash = match.metadata.to;
-        fromContract = match.metadata.toContract;
         fromContractSourceDir = match.dirPath;
       } else {
         const latestMigration = findLatestMigration(graph);
@@ -146,7 +147,6 @@ async function executeMigrationNewCommand(
             (p) => p.metadata.migrationHash === latestMigration.migrationHash,
           );
           if (leafPkg) {
-            fromContract = leafPkg.metadata.toContract;
             fromContractSourceDir = leafPkg.dirPath;
           }
         }
@@ -180,8 +180,6 @@ async function executeMigrationNewCommand(
   const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: fromHash,
     to: toStorageHash,
-    fromContract,
-    toContract: toContractJson,
     hints: {
       used: [],
       applied: [],
@@ -222,14 +220,24 @@ async function executeMigrationNewCommand(
       const sourceArtifacts = getEmittedArtifactPaths(
         join(fromContractSourceDir, 'end-contract.json'),
       );
-      await copyFilesWithRename(packageDir, [
-        { sourcePath: sourceArtifacts.jsonPath, destName: 'start-contract.json' },
-        { sourcePath: sourceArtifacts.dtsPath, destName: 'start-contract.d.ts' },
-      ]);
+      try {
+        await copyFilesWithRename(packageDir, [
+          { sourcePath: sourceArtifacts.jsonPath, destName: 'start-contract.json' },
+          { sourcePath: sourceArtifacts.dtsPath, destName: 'start-contract.d.ts' },
+        ]);
+      } catch (error) {
+        if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+          return notOk(
+            errorFileNotFound(sourceArtifacts.jsonPath, {
+              why: `Predecessor migration is missing its destination contract snapshot at ${sourceArtifacts.jsonPath}`,
+              fix: 'Re-emit the predecessor migration (`prisma-next migration plan` from its source) so its sibling `end-contract.json` is restored, then re-run this command.',
+            }),
+          );
+        }
+        throw error;
+      }
     }
 
-    const stack = createControlStack(config);
-    const familyInstance = config.family.create(stack);
     const planner = migrations.createPlanner(familyInstance);
     const emptyPlan = planner.emptyMigration(
       {