@prisma-next/cli 0.5.0-dev.9 → 0.5.1

package/src/commands/migration-plan.ts

@@ -3,23 +3,25 @@ import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import {
   createControlStack,
+  hasOperationPreview,
   type MigrationPlanOperation,
+  type OperationPreview,
 } 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 { deriveProvidedInvariants } from '@prisma-next/migration-tools/invariants';
 import {
   copyFilesWithRename,
   formatMigrationDirName,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
+import { findLatestMigration } from '@prisma-next/migration-tools/migration-graph';
 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';
 import { loadConfig } from '../config-loader';
-import { extractSqlDdl } from '../control-api/operations/extract-sql-ddl';
 import {
   type CliErrorConflict,
   CliStructuredError,
@@ -29,16 +31,20 @@ import {
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
+  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
   getTargetMigrations,
-  loadAllBundles,
+  loadMigrationPackages,
   resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
+import { runContractSpaceSeedPhase } from '../utils/contract-space-seed-phase';
+import { toExtensionInputs } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -55,15 +61,33 @@ interface MigrationPlanOptions extends CommonCommandOptions {
 export interface MigrationPlanResult {
   readonly ok: boolean;
   readonly noOp: boolean;
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
   readonly dir?: string;
+  /**
+   * Extension-space migration packages materialised onto disk during this
+   * `plan` run. Each entry names a `migrations/<spaceId>/<dirName>/`
+   * tree the framework wrote alongside the app-space migration directory.
+   * Empty when the project has no extension packs declaring a contract
+   * space, or when every extension-space package is already on disk.
+   *
+   * Surfacing these in the result (rather than only via `ui.step` log
+   * lines) makes the cross-space side effect explicit to JSON consumers
+   * and the success-summary renderer — the same multi-space side effect
+   * that `migration apply` will replay.
+   */
+  readonly emittedExtensionDirs: readonly { readonly spaceId: string; readonly dirName: string }[];
   readonly operations: readonly {
     readonly id: string;
     readonly label: string;
     readonly operationClass: string;
   }[];
-  readonly sql?: readonly string[];
+  /**
+   * Family-agnostic textual preview of the migration plan operations.
+   * Replaces the previous `sql?: readonly string[]` field; consumers should
+   * read `result.preview?.statements`.
+   */
+  readonly preview?: OperationPreview;
   readonly summary: string;
   /**
    * When true, `migration.ts` was written but contains unfilled
@@ -76,22 +100,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,
@@ -99,10 +107,8 @@ async function executeMigrationPlanCommand(
   startTime: number,
 ): Promise<Result<MigrationPlanResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, migrationsRelative } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative } =
+    resolveMigrationPaths(options.config, config);
 
   const contractPathAbsolute = resolveContractPath(config);
   const contractPath = relative(process.cwd(), contractPathAbsolute);
@@ -111,7 +117,7 @@ async function executeMigrationPlanCommand(
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
       { label: 'contract', value: contractPath },
-      { label: 'migrations', value: migrationsRelative },
+      { label: 'migrations', value: appMigrationsRelative },
     ];
     if (options.from) {
       details.push({ label: 'from', value: options.from });
@@ -173,11 +179,11 @@ async function executeMigrationPlanCommand(
 
   // Read existing migrations and determine "from" contract
   let fromContract: Contract | null = null;
-  let fromHash: string = EMPTY_CONTRACT_HASH;
+  let fromHash: string | null = null;
   let fromContractSourceDir: string | null = null;
 
   try {
-    const { bundles, graph } = await loadAllBundles(migrationsDir);
+    const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
 
     if (options.from) {
       const resolved = resolveBundleByPrefix(bundles, options.from);
@@ -186,25 +192,27 @@ async function executeMigrationPlanCommand(
         return notOk(
           f.reason === 'ambiguous'
             ? errorRuntime('Multiple matching migrations found', {
-                why: `Prefix "${options.from}" matches ${f.count} migrations in ${migrationsRelative}`,
+                why: `Prefix "${options.from}" matches ${f.count} migrations in ${appMigrationsRelative}`,
                 fix: 'Provide a longer prefix to disambiguate, or omit --from to use the latest migration target.',
               })
             : errorRuntime('Starting contract not found', {
-                why: `No migration with to hash matching "${options.from}" exists in ${migrationsRelative}`,
+                why: `No migration with to hash matching "${options.from}" exists in ${appMigrationsRelative}`,
                 fix: 'Check that the --from hash matches a known migration target hash, or omit --from to use the latest migration target.',
               }),
         );
       }
-      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,8 +221,42 @@ 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}`,
+      }),
+    );
+  }
+
+  // Phase 1 — seed: unconditionally re-emit per-space pinned artefacts
+  // (contract.json / contract.d.ts / refs/head.json) and materialise any
+  // descriptor-shipped migration packages not yet on disk. Runs before
+  // the no-op check so that an extension bump alone (with no structural
+  // app-space change) still re-pins extension artefacts on disk.
+  const canonicalExtensionInputs = toExtensionInputs(config.extensionPacks ?? []);
+  const seedResult = await runContractSpaceSeedPhase({
+    migrationsDir,
+    extensionPacks: canonicalExtensionInputs,
+  });
+  if (!flags.json && !flags.quiet) {
+    for (const record of seedResult.seeded) {
+      if (record.action === 'updated') {
+        const pkgSuffix =
+          record.newMigrationDirs.length > 0
+            ? `; ${record.newMigrationDirs.length} new migration package(s) materialised`
+            : '';
+        ui.step(`Updated ${record.spaceId} to ${record.newHash}${pkgSuffix}`);
+      }
+    }
   }
+  const emittedExtensionDirs = seedResult.seeded.flatMap((r) =>
+    r.newMigrationDirs.map((dirName) => ({ spaceId: r.spaceId, dirName })),
+  );
 
   // Check for no-op (same hash means no changes)
   if (fromHash === toStorageHash) {
@@ -224,6 +266,7 @@ async function executeMigrationPlanCommand(
       from: fromHash,
       to: toStorageHash,
       operations: [],
+      emittedExtensionDirs,
       summary: 'No changes detected between contracts',
       timings: { total: Date.now() - startTime },
     };
@@ -239,6 +282,25 @@ async function executeMigrationPlanCommand(
       }),
     );
   }
+
+  // Phase 2 — load: build the aggregate against the now-consistent disk
+  // state that phase 1 just seeded. The seed phase guarantees every
+  // declared extension has its head ref pinned, so the loader's
+  // declaredButUnmigrated precheck always passes here.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+  const aggregateResult = await buildContractSpaceAggregate({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: toContractJson,
+    extensionPacks: config.extensionPacks ?? [],
+    validateContract: (json: unknown) => familyInstance.validateContract(json),
+  });
+  if (!aggregateResult.ok) {
+    return notOk(aggregateResult.failure);
+  }
+  const aggregate = aggregateResult.value;
+
   const frameworkComponents = assertFrameworkComponentsCompatible(
     config.family.familyId,
     config.target.targetId,
@@ -249,12 +311,11 @@ async function executeMigrationPlanCommand(
   const timestamp = new Date();
   const slug = options.name ?? 'migration';
   const dirName = formatMigrationDirName(timestamp, slug);
-  const packageDir = join(migrationsDir, dirName);
+  const packageDir = join(appMigrationsDir, dirName);
 
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  const baseMetadata: Omit<MigrationMetadata, 'migrationHash' | 'providedInvariants'> = {
     from: fromHash,
     to: toStorageHash,
-    kind: 'regular',
     fromContract,
     toContract: toContractJson,
     hints: {
@@ -267,17 +328,15 @@ async function executeMigrationPlanCommand(
   };
 
   try {
-    const stack = createControlStack(config);
-    const familyInstance = config.family.create(stack);
     const planner = migrations.createPlanner(familyInstance);
     const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
     const plannerResult = planner.plan({
-      contract: toContractJson,
+      contract: aggregate.app.contract,
       schema: fromSchema,
       policy: { allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] },
-      fromHash,
       fromContract,
       frameworkComponents,
+      spaceId: aggregate.app.spaceId,
     });
     if (plannerResult.kind === 'failure') {
       return notOk(
@@ -320,18 +379,22 @@ 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 metadataWithInvariants: Omit<MigrationMetadata, 'migrationHash'> = {
+      ...baseMetadata,
+      providedInvariants: deriveProvidedInvariants(opsForWrite),
+    };
+    const metadata: MigrationMetadata = {
+      ...metadataWithInvariants,
+      migrationHash: computeMigrationHash(metadataWithInvariants, 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' },
@@ -356,6 +419,7 @@ async function executeMigrationPlanCommand(
         to: toStorageHash,
         dir: relative(process.cwd(), packageDir),
         operations: [],
+        emittedExtensionDirs,
         pendingPlaceholders: true,
         summary:
           'Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit',
@@ -364,7 +428,9 @@ async function executeMigrationPlanCommand(
       return ok(result);
     }
 
-    const sql = extractSqlDdl(plannedOps);
+    const preview = hasOperationPreview(familyInstance)
+      ? familyInstance.toOperationPreview(plannedOps)
+      : undefined;
     const result: MigrationPlanResult = {
       ok: true,
       noOp: false,
@@ -376,13 +442,25 @@ async function executeMigrationPlanCommand(
         label: op.label,
         operationClass: op.operationClass,
       })),
-      sql,
-      summary: `Planned ${plannedOps.length} operation(s)`,
+      emittedExtensionDirs,
+      ...(preview !== undefined ? { preview } : {}),
+      summary: buildPlanSummary(plannedOps.length, emittedExtensionDirs.length),
       timings: { total: Date.now() - startTime },
     };
     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}`,
+      }),
+    );
   }
 }
 
@@ -424,7 +502,29 @@ export function createMigrationPlanCommand(): Command {
   return command;
 }
 
-function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFlags): string {
+/**
+ * Compose the success-line summary so the cross-space side effect
+ * (extension-space migration packages materialised on disk during
+ * this `plan` run) is visible in the top line — not just in the
+ * step log above it.
+ *
+ * Example outputs:
+ *   - `Planned 3 operation(s)` (app-space-only project)
+ *   - `Planned 3 operation(s); materialised 1 extension-space migration` (one extension)
+ *   - `Planned 3 operation(s); materialised 2 extension-space migrations` (two extensions)
+ *
+ * Locks AC3 at the summary-line level: a reader of the success line
+ * can tell that something happened beyond the app space.
+ */
+function buildPlanSummary(plannedOpsCount: number, emittedExtensionDirsCount: number): string {
+  const base = `Planned ${plannedOpsCount} operation(s)`;
+  if (emittedExtensionDirsCount === 0) return base;
+  const noun =
+    emittedExtensionDirsCount === 1 ? 'extension-space migration' : 'extension-space migrations';
+  return `${base}; materialised ${emittedExtensionDirsCount} ${noun}`;
+}
+
+export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFlags): string {
   const lines: string[] = [];
   const useColor = flags.color !== false;
 
@@ -432,10 +532,29 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
   const yellow_ = useColor ? (s: string) => `\x1b[33m${s}\x1b[0m` : (s: string) => s;
   const dim_ = useColor ? (s: string) => `\x1b[2m${s}\x1b[0m` : (s: string) => s;
 
+  // Renders the extension-space materialisation block + canonical apply-step
+  // hint shared by the no-op, placeholder, and full-plan branches. The app
+  // space short-circuits do not skip it: an extension-only bump emits new
+  // `migrations/<spaceId>/<dirName>/` directories on disk that the user
+  // still has to apply, so the success line must surface them.
+  function appendEmittedExtensions(): void {
+    if (result.emittedExtensionDirs.length === 0) return;
+    lines.push('');
+    lines.push(dim_('Emitted extension migrations:'));
+    for (const entry of result.emittedExtensionDirs) {
+      lines.push(dim_(`  ${entry.spaceId} → migrations/${entry.spaceId}/${entry.dirName}`));
+    }
+    lines.push('');
+    lines.push(
+      `Next: review the extension migrations above, then run ${green_('prisma-next migration apply')}.`,
+    );
+  }
+
   if (result.noOp) {
     lines.push(`${green_('✔')} No changes detected`);
     lines.push(dim_(`  from: ${result.from}`));
     lines.push(dim_(`  to:   ${result.to}`));
+    appendEmittedExtensions();
     return lines.join('\n');
   }
 
@@ -452,6 +571,7 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
       'Open migration.ts and replace each `placeholder(...)` call with your actual query.',
     );
     lines.push(`Then run: ${green_(`node ${result.dir ?? '<dir>'}/migration.ts`)}`);
+    appendEmittedExtensions();
     return lines.join('\n');
   }
 
@@ -464,11 +584,11 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
       const op = result.operations[i]!;
       const isLast = i === result.operations.length - 1;
       const treeChar = isLast ? '└' : '├';
-      const opClassLabel =
-        op.operationClass === 'destructive'
-          ? yellow_(`[${op.operationClass}]`)
-          : dim_(`[${op.operationClass}]`);
-      lines.push(`${dim_(treeChar)}─ ${op.label} ${opClassLabel}`);
+      // operationClass tag is intentionally NOT inlined per spec:
+      // a destructive footer warning still surfaces below this list.
+      const destructiveMarker =
+        op.operationClass === 'destructive' ? ` ${yellow_('(destructive)')}` : '';
+      lines.push(`${dim_(treeChar)}─ ${op.label}${destructiveMarker}`);
     }
 
     const hasDestructive = result.operations.some((op) => op.operationClass === 'destructive');
@@ -484,22 +604,37 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
   lines.push(dim_(`from:   ${result.from}`));
   lines.push(dim_(`to:     ${result.to}`));
   if (result.dir) {
-    lines.push(dim_(`dir:    ${result.dir}`));
+    lines.push(dim_(`App space → ${result.dir}`));
+  }
+  // Per-space block: surface the extension-space directories materialised
+  // alongside the app-space migration. Without this block the cross-space
+  // side effect is invisible in the success summary (e2e finding F1).
+  for (const entry of result.emittedExtensionDirs) {
+    lines.push(
+      dim_(`Extension space ${entry.spaceId} → migrations/${entry.spaceId}/${entry.dirName}`),
+    );
   }
 
   lines.push('');
+  // The "Next:" hint always points at the canonical apply path
+  // (`prisma-next migration apply`) regardless of how many spaces
+  // were materialised — `db update` is a dev-time convenience, not
+  // the canonical replay step.
   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) {
+  if (result.preview && result.preview.statements.length > 0) {
+    // The non-empty length is already guaranteed by the surrounding check, so
+    // a plain `every` here is equivalent to the helper in formatters/migrations.ts.
+    const allSql = result.preview.statements.every((s) => s.language === 'sql');
     lines.push('');
-    lines.push(dim_('DDL preview'));
+    lines.push(dim_(allSql ? 'DDL preview' : 'Operation preview'));
     lines.push('');
-    for (const statement of result.sql) {
-      const trimmed = statement.trim();
+    for (const statement of result.preview.statements) {
+      const trimmed = statement.text.trim();
       if (!trimmed) continue;
-      const line = trimmed.endsWith(';') ? trimmed : `${trimmed};`;
+      const line = statement.language === 'sql' && !trimmed.endsWith(';') ? `${trimmed};` : trimmed;
       lines.push(line);
     }
   }
@@ -517,24 +652,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));
 }