@prisma-next/cli 0.4.2 → 0.5.0-dev.10

package/src/commands/migration-plan.ts

@@ -5,16 +5,17 @@ import {
   createControlStack,
   type MigrationPlanOperation,
 } from '@prisma-next/framework-components/control';
-import { computeMigrationId } from '@prisma-next/migration-tools/attestation';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { findLatestMigration } from '@prisma-next/migration-tools/dag';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import {
   copyFilesWithRename,
   formatMigrationDirName,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
-import { type MigrationManifest, MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { join, relative } from 'pathe';
@@ -29,11 +30,12 @@ import {
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
+  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
   getTargetMigrations,
-  loadAllBundles,
+  loadMigrationPackages,
   resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
@@ -76,22 +78,6 @@ export interface MigrationPlanResult {
   };
 }
 
-function mapMigrationToolsError(error: unknown): CliStructuredError {
-  if (CliStructuredError.is(error)) {
-    return error;
-  }
-  if (MigrationToolsError.is(error)) {
-    return errorRuntime(error.message, {
-      why: error.why,
-      fix: error.fix,
-      meta: { code: error.code, ...(error.details ?? {}) },
-    });
-  }
-  return errorUnexpected(error instanceof Error ? error.message : String(error), {
-    why: `Unexpected error during migration plan: ${error instanceof Error ? error.message : String(error)}`,
-  });
-}
-
 async function executeMigrationPlanCommand(
   options: MigrationPlanOptions,
   flags: GlobalFlags,
@@ -177,7 +163,7 @@ async function executeMigrationPlanCommand(
   let fromContractSourceDir: string | null = null;
 
   try {
-    const { bundles, graph } = await loadAllBundles(migrationsDir);
+    const { bundles, graph } = await loadMigrationPackages(migrationsDir);
 
     if (options.from) {
       const resolved = resolveBundleByPrefix(bundles, options.from);
@@ -195,16 +181,18 @@ async function executeMigrationPlanCommand(
               }),
         );
       }
-      fromHash = resolved.value.manifest.to;
-      fromContract = resolved.value.manifest.toContract;
+      fromHash = resolved.value.metadata.to;
+      fromContract = resolved.value.metadata.toContract;
       fromContractSourceDir = resolved.value.dirPath;
     } else {
       const latestMigration = findLatestMigration(graph);
       if (latestMigration) {
         fromHash = latestMigration.to;
-        const leafPkg = bundles.find((p) => p.manifest.migrationId === latestMigration.migrationId);
+        const leafPkg = bundles.find(
+          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
+        );
         if (leafPkg) {
-          fromContract = leafPkg.manifest.toContract;
+          fromContract = leafPkg.metadata.toContract;
           fromContractSourceDir = leafPkg.dirPath;
         }
       }
@@ -213,7 +201,16 @@ async function executeMigrationPlanCommand(
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
     }
-    throw error;
+    // Wrap unexpected (non-MigrationToolsError) failures from the migration
+    // load phase in a structured CLI envelope. Letting them throw would
+    // bypass `handleResult()` and crash the command — see CLI structured-
+    // errors guideline (CliStructuredError + Result pattern).
+    const message = error instanceof Error ? error.message : String(error);
+    return notOk(
+      errorUnexpected(message, {
+        why: `Unexpected error while loading migrations: ${message}`,
+      }),
+    );
   }
 
   // Check for no-op (same hash means no changes)
@@ -251,7 +248,7 @@ async function executeMigrationPlanCommand(
   const dirName = formatMigrationDirName(timestamp, slug);
   const packageDir = join(migrationsDir, dirName);
 
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: fromHash,
     to: toStorageHash,
     kind: 'regular',
@@ -320,18 +317,18 @@ async function executeMigrationPlanCommand(
 
     const migrationTsContent = plannerResult.plan.renderTypeScript();
 
-    // Always-attest: compute migrationId over (manifest, ops). When
-    // placeholders blocked lowering, ops is `[]` and the id hashes over
-    // the empty list — re-emitting after the user fills the placeholder
-    // produces a different id (over the real ops). This is intentional;
+    // Always-attest: compute migrationHash over (metadata, ops). When
+    // placeholders blocked lowering, ops is `[]` and the hash is computed
+    // over the empty list — re-emitting after the user fills the placeholder
+    // produces a different hash (over the real ops). This is intentional;
     // there is no on-disk "draft" state.
     const opsForWrite = hasPlaceholders ? [] : plannedOps;
-    const manifest: MigrationManifest = {
-      ...baseManifest,
-      migrationId: computeMigrationId(baseManifest, opsForWrite),
+    const metadata: MigrationMetadata = {
+      ...baseMetadata,
+      migrationHash: computeMigrationHash(baseMetadata, opsForWrite),
     };
 
-    await writeMigrationPackage(packageDir, manifest, opsForWrite);
+    await writeMigrationPackage(packageDir, metadata, opsForWrite);
     const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
     await copyFilesWithRename(packageDir, [
       { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
@@ -382,7 +379,18 @@ async function executeMigrationPlanCommand(
     };
     return ok(result);
   } catch (error) {
-    return notOk(mapMigrationToolsError(error));
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return notOk(
+      errorUnexpected(message, {
+        why: `Unexpected error during migration plan: ${message}`,
+      }),
+    );
   }
 }
 
@@ -489,7 +497,7 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
 
   lines.push('');
   lines.push(
-    `Next: ${green_(`node ${result.dir ?? '<dir>'}/migration.ts`)} to emit ops.json and attest migrationId before running ${green_('prisma-next migration apply')}.`,
+    `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migration apply')}.`,
   );
 
   if (result.sql && result.sql.length > 0) {
@@ -517,24 +525,27 @@ export type PrefixResolutionFailure =
   | { reason: 'not-found' };
 
 /**
- * Resolve a migration bundle by exact hash or prefix match.
+ * Resolve a migration package by **target contract hash** (`metadata.to`)
+ * using exact match or prefix match.
  *
+ * Note: matches `metadata.to` (the contract hash this migration produces),
+ * not `metadata.migrationHash` (the package's content-addressed identity).
  * Tries exact match first, then prefix match (auto-prepending `sha256:` when
- * the needle omits the scheme). Returns the matched bundle on success, or a
+ * the needle omits the scheme). Returns the matched package on success, or a
  * discriminated failure indicating whether the prefix was ambiguous or simply
  * not found.
  *
  * @internal Exported for testing only.
  */
-export function resolveBundleByPrefix<T extends { manifest: { to: string } }>(
+export function resolveBundleByPrefix<T extends { metadata: { to: string } }>(
   bundles: readonly T[],
   needle: string,
 ): Result<T, PrefixResolutionFailure> {
-  const exact = bundles.find((p) => p.manifest.to === needle);
+  const exact = bundles.find((p) => p.metadata.to === needle);
   if (exact) return ok(exact);
 
   const prefixWithScheme = needle.startsWith('sha256:') ? needle : `sha256:${needle}`;
-  const candidates = bundles.filter((p) => p.manifest.to.startsWith(prefixWithScheme));
+  const candidates = bundles.filter((p) => p.metadata.to.startsWith(prefixWithScheme));
 
   if (candidates.length === 1) return ok(candidates[0]!);
   if (candidates.length > 1) return notOk({ reason: 'ambiguous', count: candidates.length });

package/src/commands/migration-ref.ts

@@ -1,3 +1,4 @@
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
   deleteRef,
@@ -7,11 +8,15 @@ import {
   validateRefValue,
   writeRef,
 } from '@prisma-next/migration-tools/refs';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
-import { CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
+import {
+  CliStructuredError,
+  errorRuntime,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
 import {
   addGlobalOptions,
   resolveMigrationPaths,
@@ -49,11 +54,7 @@ interface RefListResult {
 
 function mapError(error: unknown): CliStructuredError {
   if (MigrationToolsError.is(error)) {
-    return errorRuntime(error.message, {
-      why: error.why,
-      fix: error.fix,
-      meta: { code: error.code },
-    });
+    return mapMigrationToolsError(error);
   }
   return errorUnexpected(error instanceof Error ? error.message : String(error));
 }

package/src/commands/migration-show.ts

@@ -1,14 +1,19 @@
 import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
 import { findLatestMigration, reconstructGraph } from '@prisma-next/migration-tools/dag';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import { readMigrationPackage, readMigrationsDir } from '@prisma-next/migration-tools/io';
-import type { MigrationBundle } from '@prisma-next/migration-tools/types';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
+import type { MigrationPackage } from '@prisma-next/migration-tools/package';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { extractOperationStatements } from '../control-api/operations/extract-operation-statements';
-import { type CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
+import {
+  type CliStructuredError,
+  errorRuntime,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
 import {
   addGlobalOptions,
   setCommandDescriptions,
@@ -31,7 +36,7 @@ export interface MigrationShowResult {
   readonly dirPath: string;
   readonly from: string;
   readonly to: string;
-  readonly migrationId: string;
+  readonly migrationHash: string;
   readonly kind: string;
   readonly createdAt: string;
   readonly operations: readonly {
@@ -48,11 +53,11 @@ function looksLikePath(target: string): boolean {
 }
 
 export function resolveByHashPrefix(
-  packages: readonly MigrationBundle[],
+  packages: readonly MigrationPackage[],
   prefix: string,
-): Result<MigrationBundle, CliStructuredError> {
+): Result<MigrationPackage, CliStructuredError> {
   const normalizedPrefix = prefix.startsWith('sha256:') ? prefix : `sha256:${prefix}`;
-  const matches = packages.filter((p) => p.manifest.migrationId.startsWith(normalizedPrefix));
+  const matches = packages.filter((p) => p.metadata.migrationHash.startsWith(normalizedPrefix));
 
   if (matches.length === 1) {
     return ok(matches[0]!);
@@ -61,13 +66,13 @@ export function resolveByHashPrefix(
   if (matches.length === 0) {
     return notOk(
       errorRuntime('No migration found matching prefix', {
-        why: `No migration has a migrationId starting with "${normalizedPrefix}"`,
+        why: `No migration has a migrationHash starting with "${normalizedPrefix}"`,
         fix: 'Run `prisma-next migration show` (no argument) to see the latest migration, or check the migrations directory for available packages.',
       }),
     );
   }
 
-  const candidates = matches.map((p) => `  ${p.dirName}  ${p.manifest.migrationId}`).join('\n');
+  const candidates = matches.map((p) => `  ${p.dirName}  ${p.metadata.migrationHash}`).join('\n');
   return notOk(
     errorRuntime('Ambiguous hash prefix', {
       why: `Multiple migrations match prefix "${normalizedPrefix}":\n${candidates}`,
@@ -110,7 +115,7 @@ async function executeMigrationShowCommand(
     ui.stderr(header);
   }
 
-  let pkg: MigrationBundle;
+  let pkg: MigrationPackage;
 
   try {
     if (target && looksLikePath(target)) {
@@ -142,7 +147,7 @@ async function executeMigrationShowCommand(
           );
         }
         const leafPkg = allPackages.find(
-          (p) => p.manifest.migrationId === latestMigration.migrationId,
+          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
         );
         if (!leafPkg) {
           return notOk(
@@ -157,13 +162,7 @@ async function executeMigrationShowCommand(
     }
   } catch (error) {
     if (MigrationToolsError.is(error)) {
-      return notOk(
-        errorRuntime(error.message, {
-          why: error.why,
-          fix: error.fix,
-          meta: { code: error.code, ...(error.details ?? {}) },
-        }),
-      );
+      return notOk(mapMigrationToolsError(error));
     }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
@@ -179,11 +178,11 @@ async function executeMigrationShowCommand(
     ok: true,
     dirName: pkg.dirName,
     dirPath: relative(process.cwd(), pkg.dirPath),
-    from: pkg.manifest.from,
-    to: pkg.manifest.to,
-    migrationId: pkg.manifest.migrationId,
-    kind: pkg.manifest.kind,
-    createdAt: pkg.manifest.createdAt,
+    from: pkg.metadata.from,
+    to: pkg.metadata.to,
+    migrationHash: pkg.metadata.migrationHash,
+    kind: pkg.metadata.kind,
+    createdAt: pkg.metadata.createdAt,
     operations: ops.map((op) => ({
       id: op.id,
       label: op.label,
@@ -209,10 +208,7 @@ export function createMigrationShowCommand(): Command {
     'prisma-next migration show sha256:a1b2c3',
   ]);
   addGlobalOptions(command)
-    .argument(
-      '[target]',
-      'Migration directory path or migrationId hash prefix (defaults to latest)',
-    )
+    .argument('[target]', 'Migration directory path or migrationHash prefix (defaults to latest)')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string | undefined, options: MigrationShowOptions) => {
       const flags = parseGlobalFlags(options);

package/src/commands/migration-status.ts

@@ -5,14 +5,11 @@ import {
   findPathWithDecision,
   findReachableLeaves,
 } from '@prisma-next/migration-tools/dag';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import type { MigrationChainEntry, MigrationGraph } from '@prisma-next/migration-tools/graph';
+import type { MigrationPackage } from '@prisma-next/migration-tools/package';
 import type { Refs } from '@prisma-next/migration-tools/refs';
 import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
-import type {
-  MigrationBundle,
-  MigrationChainEntry,
-  MigrationGraph,
-} from '@prisma-next/migration-tools/types';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { cyan, dim, magenta, yellow } from 'colorette';
@@ -20,10 +17,15 @@ import { Command } from 'commander';
 
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
-import { type CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
+import {
+  type CliStructuredError,
+  errorRuntime,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadAllBundles,
+  loadMigrationPackages,
   maskConnectionUrl,
   readContractEnvelope,
   resolveMigrationPaths,
@@ -61,7 +63,7 @@ export interface MigrationStatusEntry {
   readonly dirName: string;
   readonly from: string;
   readonly to: string;
-  readonly migrationId: string;
+  readonly migrationHash: string;
   readonly operationCount: number;
   readonly operationSummary: string;
   readonly hasDestructive: boolean;
@@ -86,7 +88,7 @@ export interface MigrationStatusResult {
     readonly refName?: string;
     readonly selectedPath: readonly {
       readonly dirName: string;
-      readonly migrationId: string;
+      readonly migrationHash: string;
       readonly from: string;
       readonly to: string;
     }[];
@@ -94,7 +96,7 @@ export interface MigrationStatusResult {
   readonly summary: string;
   readonly diagnostics: readonly StatusDiagnostic[];
   readonly graph?: MigrationGraph;
-  readonly bundles?: readonly MigrationBundle[];
+  readonly bundles?: readonly MigrationPackage[];
   readonly edgeStatuses?: readonly EdgeStatus[];
   readonly activeRefHash?: string;
   readonly activeRefName?: string;
@@ -225,7 +227,7 @@ export function deriveEdgeStatuses(
  */
 function buildMigrationEntries(
   chain: readonly MigrationChainEntry[],
-  packages: readonly MigrationBundle[],
+  packages: readonly MigrationPackage[],
   mode: 'online' | 'offline',
   markerHash: string | undefined,
   edgeStatuses?: readonly EdgeStatus[],
@@ -261,7 +263,7 @@ function buildMigrationEntries(
       dirName: migration.dirName,
       from: migration.from,
       to: migration.to,
-      migrationId: migration.migrationId,
+      migrationHash: migration.migrationHash,
       operationCount: ops.length,
       operationSummary: summary,
       hasDestructive,
@@ -360,13 +362,7 @@ async function executeMigrationStatusCommand(
     allRefs = await readRefs(refsDir);
   } catch (error) {
     if (MigrationToolsError.is(error)) {
-      return notOk(
-        errorRuntime(error.message, {
-          why: error.why,
-          fix: error.fix,
-          meta: { code: error.code },
-        }),
-      );
+      return notOk(mapMigrationToolsError(error));
     }
     throw error;
   }
@@ -377,13 +373,7 @@ async function executeMigrationStatusCommand(
       activeRefHash = resolveRef(allRefs, activeRefName).hash;
     } catch (error) {
       if (MigrationToolsError.is(error)) {
-        return notOk(
-          errorRuntime(error.message, {
-            why: error.why,
-            fix: error.fix,
-            meta: { code: error.code },
-          }),
-        );
+        return notOk(mapMigrationToolsError(error));
       }
       throw error;
     }
@@ -429,15 +419,13 @@ async function executeMigrationStatusCommand(
     });
   }
 
-  let bundles: readonly MigrationBundle[];
+  let bundles: readonly MigrationPackage[];
   let graph: MigrationGraph;
   try {
-    ({ bundles, graph } = await loadAllBundles(migrationsDir));
+    ({ bundles, graph } = await loadMigrationPackages(migrationsDir));
   } catch (error) {
     if (MigrationToolsError.is(error)) {
-      return notOk(
-        errorRuntime(error.message, { why: error.why, fix: error.fix, meta: { code: error.code } }),
-      );
+      return notOk(mapMigrationToolsError(error));
     }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {

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

@@ -30,6 +30,21 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
   readonly onProgress?: OnControlProgress;
 }
 
+/**
+ * Apply a sequence of migration packages against the configured driver.
+ *
+ * Validates the path's continuity (origin → ... → destination, no gaps),
+ * then drives the family/target's migration runner over each package's
+ * operations in order, surfacing per-migration progress through `onProgress`.
+ *
+ * The `pendingMigrations` parameter is trusted input. Callers are responsible
+ * for upstream verification of the originating migration packages — typically
+ * by loading them via `readMigrationPackage` from
+ * `@prisma-next/migration-tools/io`, which performs hash-integrity checks at
+ * the load boundary. This operation does not re-verify the packages and
+ * assumes the `(metadata, ops)` pairs on disk have not been tampered with
+ * since emit.
+ */
 export async function executeMigrationApply<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteMigrationApplyOptions<TFamilyId, TTargetId>,
 ): Promise<MigrationApplyResult> {

package/src/migration-cli.ts

@@ -41,13 +41,13 @@ import { fileURLToPath } from 'node:url';
 import { CliStructuredError, errorMigrationCliInvalidConfigArg } from '@prisma-next/errors/control';
 import { errorMigrationTargetMismatch } from '@prisma-next/errors/migration';
 import { createControlStack } from '@prisma-next/framework-components/control';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import {
   buildMigrationArtifacts,
   isDirectEntrypoint,
   type Migration,
   printMigrationHelp,
 } from '@prisma-next/migration-tools/migration';
-import type { MigrationManifest } from '@prisma-next/migration-tools/types';
 import { dirname, join } from 'pathe';
 import { loadConfig } from './config-loader';
 
@@ -202,16 +202,23 @@ export class MigrationCLI {
  * `buildMigrationArtifacts` so the pure builder can preserve fields owned
  * by `migration plan` (contract bookends, hints, labels, `createdAt`)
  * across re-emits.
+ *
+ * Author-time path: this loader is non-verifying by design. Hash mismatch
+ * is the *expected* outcome of a re-author (the developer's source
+ * changes invalidate the prior hash by construction), and verification
+ * here would block legitimate regenerations. Apply-time consumers always
+ * route through the verifying `readMigrationPackage` in
+ * `@prisma-next/migration-tools/io` instead.
  */
-function readExistingManifest(manifestPath: string): Partial<MigrationManifest> | null {
+function readExistingMetadata(metadataPath: string): Partial<MigrationMetadata> | null {
   let raw: string;
   try {
-    raw = readFileSync(manifestPath, 'utf-8');
+    raw = readFileSync(metadataPath, 'utf-8');
   } catch {
     return null;
   }
   try {
-    return JSON.parse(raw) as Partial<MigrationManifest>;
+    return JSON.parse(raw) as Partial<MigrationMetadata>;
   } catch {
     return null;
   }
@@ -236,19 +243,19 @@ function serializeMigrationToDisk(
   migrationDir: string,
   dryRun: boolean,
 ): void {
-  const manifestPath = join(migrationDir, 'migration.json');
-  const existing = readExistingManifest(manifestPath);
-  const { opsJson, manifestJson } = buildMigrationArtifacts(instance, existing);
+  const metadataPath = join(migrationDir, 'migration.json');
+  const existing = readExistingMetadata(metadataPath);
+  const { opsJson, metadataJson } = buildMigrationArtifacts(instance, existing);
 
   if (dryRun) {
-    process.stdout.write(`--- migration.json ---\n${manifestJson}\n`);
+    process.stdout.write(`--- migration.json ---\n${metadataJson}\n`);
     process.stdout.write('--- ops.json ---\n');
     process.stdout.write(`${opsJson}\n`);
     return;
   }
 
   writeFileSync(join(migrationDir, 'ops.json'), opsJson);
-  writeFileSync(manifestPath, manifestJson);
+  writeFileSync(metadataPath, metadataJson);
 
   process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
 }

package/src/utils/cli-errors.ts

@@ -3,7 +3,8 @@
  * CLI-specific errors (e.g., Commander.js argument validation) can be added here if needed.
  */
 export type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';
-export {
+
+import {
   CliStructuredError,
   errorConfigFileNotFound,
   errorConfigValidation,
@@ -20,6 +21,26 @@ export {
   errorTargetMigrationNotSupported,
   errorUnexpected,
 } from '@prisma-next/errors/control';
+import { errorRuntime } from '@prisma-next/errors/execution';
+import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+
+export {
+  CliStructuredError,
+  errorConfigFileNotFound,
+  errorConfigValidation,
+  errorContractConfigMissing,
+  errorContractMissingExtensionPacks,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFamilyReadMarkerSqlRequired,
+  errorFileNotFound,
+  errorMigrationCliInvalidConfigArg,
+  errorMigrationPlanningFailed,
+  errorQueryRunnerFactoryRequired,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+};
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
   errorDestructiveChanges,
@@ -38,3 +59,26 @@ export {
   errorUnfilledPlaceholder,
   placeholder,
 } from '@prisma-next/errors/migration';
+
+/**
+ * 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.).
+ */
+export function mapMigrationToolsError(error: MigrationToolsError): CliStructuredError {
+  return errorRuntime(error.message, {
+    why: error.why,
+    fix: error.fix,
+    meta: { code: error.code, ...(error.details ?? {}) },
+  });
+}