@prisma-next/cli 0.5.0-dev.2 → 0.5.0-dev.20

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

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { emit, getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { createControlStack } from '@prisma-next/framework-components/control';
@@ -7,57 +7,156 @@ import { ifDefined } from '@prisma-next/utils/defined';
 import { dirname } from 'pathe';
 import { loadConfig } from '../../config-loader';
 import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
+import { queueEmitByOutput } from '../../utils/emit-queue';
 import { assertFrameworkComponentsCompatible } from '../../utils/framework-components';
+import { publishContractArtifactPair } from '../../utils/publish-contract-artifact-pair';
+import { validateContractDeps } from '../../utils/validate-contract-deps';
 import { enrichContract } from '../contract-enrichment';
-import type { ContractEmitOptions, ContractEmitResult } from '../types';
+import type {
+  ContractEmitOptions,
+  ContractEmitResult,
+  ControlActionName,
+  OnControlProgress,
+} from '../types';
 
-interface ProviderFailureLike {
-  readonly summary: string;
-  readonly diagnostics: readonly unknown[];
-  readonly meta?: unknown;
-}
+const EMIT_ACTION: ControlActionName = 'emit';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function isAbortError(error: unknown): boolean {
-  return isRecord(error) && typeof error['name'] === 'string' && error['name'] === 'AbortError';
+function startSpan(onProgress: OnControlProgress | undefined, spanId: string, label: string): void {
+  onProgress?.({ action: EMIT_ACTION, kind: 'spanStart', spanId, label });
+}
+
+function endSpan(
+  onProgress: OnControlProgress | undefined,
+  spanId: string,
+  outcome: 'ok' | 'error',
+): void {
+  onProgress?.({ action: EMIT_ACTION, kind: 'spanEnd', spanId, outcome });
+}
+
+function failedToResolveContractSource(why: string, fix: string, meta?: Record<string, unknown>) {
+  return errorRuntime('Failed to resolve contract source', {
+    why,
+    fix,
+    ...ifDefined('meta', meta),
+  });
+}
+
+type ValidatedProviderResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: ReturnType<typeof errorRuntime> };
+
+function diagnosticLocationSuffix(diagnostic: Record<string, unknown>): string {
+  const sourceId = typeof diagnostic['sourceId'] === 'string' ? diagnostic['sourceId'] : undefined;
+  const span = isRecord(diagnostic['span']) ? diagnostic['span'] : undefined;
+  const start = span && isRecord(span['start']) ? span['start'] : undefined;
+  const line = start && typeof start['line'] === 'number' ? start['line'] : undefined;
+  const column = start && typeof start['column'] === 'number' ? start['column'] : undefined;
+  if (sourceId && line !== undefined && column !== undefined) {
+    return ` (${sourceId}:${line}:${column})`;
+  }
+  if (sourceId) {
+    return ` (${sourceId})`;
+  }
+  return '';
 }
 
-function isProviderFailureLike(value: unknown): value is ProviderFailureLike {
-  return (
-    isRecord(value) && typeof value['summary'] === 'string' && Array.isArray(value['diagnostics'])
-  );
+function mapDiagnosticsToIssues(
+  diagnostics: readonly unknown[],
+): ReadonlyArray<{ readonly kind: string; readonly message: string }> {
+  const issues: { readonly kind: string; readonly message: string }[] = [];
+  for (const raw of diagnostics) {
+    if (!isRecord(raw)) continue;
+    const code = typeof raw['code'] === 'string' ? raw['code'] : 'diagnostic';
+    const message = typeof raw['message'] === 'string' ? raw['message'] : '';
+    issues.push({ kind: code, message: `${message}${diagnosticLocationSuffix(raw)}` });
+  }
+  return issues;
+}
+
+function validateProviderResult(providerResult: unknown): ValidatedProviderResult {
+  if (!isRecord(providerResult) || typeof providerResult['ok'] !== 'boolean') {
+    return {
+      ok: false,
+      error: failedToResolveContractSource(
+        'Contract source provider returned malformed result shape.',
+        'Ensure contract.source.load resolves to ok(Contract) or notOk({ summary, diagnostics }).',
+      ),
+    };
+  }
+
+  if (providerResult['ok']) {
+    if (!('value' in providerResult)) {
+      return {
+        ok: false,
+        error: failedToResolveContractSource(
+          'Contract source provider returned malformed success result: missing value.',
+          'Ensure contract.source.load success payload is ok(Contract).',
+        ),
+      };
+    }
+    return { ok: true, value: providerResult['value'] };
+  }
+
+  const failure = providerResult['failure'];
+  if (
+    !isRecord(failure) ||
+    typeof failure['summary'] !== 'string' ||
+    !Array.isArray(failure['diagnostics'])
+  ) {
+    return {
+      ok: false,
+      error: failedToResolveContractSource(
+        'Contract source provider returned malformed failure result: expected summary and diagnostics.',
+        'Ensure contract.source.load failure payload is notOk({ summary, diagnostics, meta? }).',
+      ),
+    };
+  }
+  return {
+    ok: false,
+    error: failedToResolveContractSource(
+      String(failure['summary']),
+      'Fix contract source diagnostics and return ok(Contract).',
+      {
+        diagnostics: failure['diagnostics'],
+        issues: mapDiagnosticsToIssues(failure['diagnostics']),
+        ...ifDefined('providerMeta', failure['meta']),
+      },
+    ),
+  };
 }
 
 /**
- * Executes the contract emit operation.
+ * Canonical contract emit operation.
  *
- * This is an offline operation that:
- * 1. Loads the Prisma Next config from the specified path
- * 2. Resolves the contract source from config
- * 3. Creates a control plane stack and family instance
- * 4. Emits contract artifacts (JSON and DTS)
- * 5. Writes files to the paths specified in config
+ * This is the SINGLE publication path used by both the CLI command
+ * (`prisma-next contract emit`) and the Vite plugin
+ * (`@prisma-next/vite-plugin-contract-emit`). New callers must go through this
+ * function rather than re-implementing load → emit → publish.
  *
- * Supports AbortSignal for cancellation, enabling "last change wins" behavior.
+ * The whole flow (load config → resolve source → emit bytes → atomic publish)
+ * is serialized per output JSON path via `queueEmitByOutput`. Concurrent calls
+ * for the same output line up FIFO; the user-visible outcome is "last
+ * submission wins on disk" without any supersession bookkeeping. Within a
+ * single emit, `publishContractArtifactPair` stages temp files, renames
+ * `contract.d.ts` before `contract.json`, and attempts to restore the previous
+ * pair if either rename fails — so type-only consumers never observe a
+ * mismatched pair.
  *
- * @param options - Options including configPath and optional signal
- * @returns File paths and hashes of emitted artifacts
- * @throws If config loading fails, contract is invalid, or file I/O fails
- * @throws signal.reason if cancelled via AbortSignal (typically DOMException with name 'AbortError')
+ * @throws {CliStructuredError} on config/source/validation problems
+ * @throws {DOMException} `AbortError` if cancelled via `signal`
  */
 export async function executeContractEmit(
   options: ContractEmitOptions,
 ): Promise<ContractEmitResult> {
-  const { configPath, signal = new AbortController().signal } = options;
+  const { configPath, signal = new AbortController().signal, onProgress } = options;
   const unlessAborted = abortable(signal);
 
-  // Load config using the existing config loader
   const config = await unlessAborted(loadConfig(configPath));
 
-  // Validate contract config is present
   if (!config.contract) {
     throw errorContractConfigMissing({
       why: 'Config.contract is required for emit. Define it in your config: contract: { source: ..., output: ... }',
@@ -66,14 +165,12 @@ export async function executeContractEmit(
 
   const contractConfig = config.contract;
 
-  // Validate output path is present and ends with .json
   if (!contractConfig.output) {
     throw errorContractConfigMissing({
       why: 'Contract config must have output path. This should not happen if defineConfig() was used.',
     });
   }
 
-  // Validate source exists and is callable
   if (typeof contractConfig.source?.load !== 'function') {
     throw errorContractConfigMissing({
       why: 'Contract config must include a valid source provider object',
@@ -90,98 +187,84 @@ export async function executeContractEmit(
   }
   const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } = outputPaths;
 
-  const stack = createControlStack(config);
+  return queueEmitByOutput(outputJsonPath, async () => {
+    const stack = createControlStack(config);
 
-  const sourceContext = {
-    composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
-    scalarTypeDescriptors: stack.scalarTypeDescriptors,
-    authoringContributions: stack.authoringContributions,
-    codecLookup: stack.codecLookup,
-    controlMutationDefaults: stack.controlMutationDefaults,
-    resolvedInputs: contractConfig.source.inputs ?? [],
-  };
+    const sourceContext = {
+      composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+      scalarTypeDescriptors: stack.scalarTypeDescriptors,
+      authoringContributions: stack.authoringContributions,
+      codecLookup: stack.codecLookup,
+      controlMutationDefaults: stack.controlMutationDefaults,
+      resolvedInputs: contractConfig.source.inputs ?? [],
+    };
 
-  let providerResult: Awaited<ReturnType<typeof contractConfig.source.load>>;
-  try {
-    providerResult = await unlessAborted(contractConfig.source.load(sourceContext));
-  } catch (error) {
-    if (signal.aborted || isAbortError(error)) {
-      throw error;
+    startSpan(onProgress, 'resolveSource', 'Resolving contract source...');
+    let providerResult: Awaited<ReturnType<typeof contractConfig.source.load>>;
+    try {
+      providerResult = await unlessAborted(contractConfig.source.load(sourceContext));
+    } catch (error) {
+      endSpan(onProgress, 'resolveSource', 'error');
+      if (signal.aborted || (isRecord(error) && error['name'] === 'AbortError')) {
+        throw error;
+      }
+      throw failedToResolveContractSource(
+        error instanceof Error ? error.message : String(error),
+        'Ensure contract.source.load resolves to ok(Contract) or returns structured diagnostics.',
+      );
     }
-    throw errorRuntime('Failed to resolve contract source', {
-      why: error instanceof Error ? error.message : String(error),
-      fix: 'Ensure contract.source.load resolves to ok(Contract) or returns structured diagnostics.',
-    });
-  }
 
-  if (!isRecord(providerResult) || typeof providerResult.ok !== 'boolean') {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed result shape.',
-      fix: 'Ensure contract.source.load resolves to ok(Contract) or notOk({ summary, diagnostics }).',
-    });
-  }
-
-  if (providerResult.ok && !('value' in providerResult)) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed success result: missing value.',
-      fix: 'Ensure contract.source.load success payload is ok(Contract).',
-    });
-  }
+    const validatedContract = validateProviderResult(providerResult);
+    if (!validatedContract.ok) {
+      endSpan(onProgress, 'resolveSource', 'error');
+      throw validatedContract.error;
+    }
+    endSpan(onProgress, 'resolveSource', 'ok');
 
-  if (!providerResult.ok && !isProviderFailureLike(providerResult.failure)) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed failure result: expected summary and diagnostics.',
-      fix: 'Ensure contract.source.load failure payload is notOk({ summary, diagnostics, meta? }).',
-    });
-  }
+    startSpan(onProgress, 'emit', 'Emitting contract...');
+    let emitResult: Awaited<ReturnType<typeof emit>>;
+    try {
+      const familyInstance = config.family.create(stack);
+      const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+      const frameworkComponents = assertFrameworkComponentsCompatible(
+        config.family.familyId,
+        config.target.targetId,
+        rawComponents,
+      );
+      const enrichedIR = enrichContract(validatedContract.value as Contract, frameworkComponents);
+      familyInstance.validateContract(enrichedIR);
+      emitResult = await unlessAborted(
+        emit(enrichedIR, stack, config.family.emission, { outputJsonPath }),
+      );
+    } catch (error) {
+      endSpan(onProgress, 'emit', 'error');
+      throw error;
+    }
+    endSpan(onProgress, 'emit', 'ok');
 
-  if (!providerResult.ok) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: providerResult.failure.summary,
-      fix: 'Fix contract source diagnostics and return ok(Contract).',
-      meta: {
-        diagnostics: providerResult.failure.diagnostics,
-        ...ifDefined('providerMeta', providerResult.failure.meta),
-      },
+    await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
+    await publishContractArtifactPair({
+      outputJsonPath,
+      outputDtsPath,
+      contractJson: emitResult.contractJson,
+      contractDts: emitResult.contractDts,
+      publicationToken: String(process.hrtime.bigint()),
     });
-  }
 
-  const familyInstance = config.family.create(stack);
-
-  const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
-  const frameworkComponents = assertFrameworkComponentsCompatible(
-    config.family.familyId,
-    config.target.targetId,
-    rawComponents,
-  );
-  const enrichedIR = enrichContract(providerResult.value as Contract, frameworkComponents);
-
-  familyInstance.validateContract(enrichedIR);
-  const emitResult = await unlessAborted(
-    emit(enrichedIR, stack, config.family.emission, {
-      outputJsonPath: outputJsonPath,
-    }),
-  );
-
-  // Create directory if needed and write files (both colocated)
-  await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
-  await unlessAborted(writeFile(outputJsonPath, emitResult.contractJson, 'utf-8'));
-  await unlessAborted(writeFile(outputDtsPath, emitResult.contractDts, 'utf-8'));
-
-  // Validate that contract.d.ts type imports are resolvable
-  const { validateContractDeps } = await import('../../utils/validate-contract-deps');
-  const depsValidation = validateContractDeps(emitResult.contractDts, dirname(outputDtsPath));
-  if (depsValidation.warning) {
-    process.stderr.write(`\n⚠ ${depsValidation.warning}\n`);
-  }
+    const validationWarning = validateContractDeps(
+      emitResult.contractDts,
+      dirname(outputDtsPath),
+    ).warning;
 
-  return {
-    storageHash: emitResult.storageHash,
-    ...ifDefined('executionHash', emitResult.executionHash),
-    profileHash: emitResult.profileHash,
-    files: {
-      json: outputJsonPath,
-      dts: outputDtsPath,
-    },
-  };
+    return {
+      storageHash: emitResult.storageHash,
+      ...ifDefined('executionHash', emitResult.executionHash),
+      profileHash: emitResult.profileHash,
+      files: {
+        json: outputJsonPath,
+        dts: outputDtsPath,
+      },
+      ...ifDefined('validationWarning', validationWarning),
+    };
+  });
 }

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/control-api/types.ts

@@ -512,18 +512,31 @@ export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyF
 
 /**
  * Options for the standalone executeContractEmit function.
- * Used by tooling (e.g., Vite plugin) that needs to emit contracts
- * without the full ControlClient infrastructure.
+ *
+ * `executeContractEmit` is the canonical publication path for both the
+ * `prisma-next contract emit` CLI command and the `@prisma-next/vite-plugin-contract-emit`
+ * Vite plugin. Do not duplicate the load → emit → publish dance elsewhere; if a
+ * caller needs additional behavior, extend this options shape and update the
+ * single implementation rather than building a parallel publication path.
+ *
+ * Concurrent calls for the same output JSON path are serialized per-output via
+ * a FIFO queue; concurrent calls for distinct outputs run in parallel.
  */
 export interface ContractEmitOptions {
   /** Path to the prisma-next.config.ts file */
   readonly configPath: string;
-  /** Optional AbortSignal for cancellation support */
+  /** Optional AbortSignal for cancelling the in-flight emit */
   readonly signal?: AbortSignal;
+  /** Optional progress callback for observing source-resolution and emit spans */
+  readonly onProgress?: OnControlProgress;
 }
 
 /**
  * Result from the standalone executeContractEmit function.
+ *
+ * Always describes the bytes that were just published to disk. Failures throw
+ * (config / source-resolution / emit / publish) — callers do not need to
+ * branch on a result discriminator.
  */
 export interface ContractEmitResult {
   /** Hash of the storage contract (schema-level) */
@@ -539,6 +552,12 @@ export interface ContractEmitResult {
     /** Path to the emitted contract.d.ts file */
     readonly dts: string;
   };
+  /**
+   * Warning surfaced by `validateContractDeps` after a successful publication.
+   * Callers (CLI, Vite plugin) decide how to render this; the operation does
+   * not write to stderr itself. Undefined when no warning was raised.
+   */
+  readonly validationWarning?: string;
 }
 
 // ============================================================================

package/src/exports/control-api.ts

@@ -23,7 +23,6 @@ export { enrichContract } from '../control-api/contract-enrichment';
 
 // Standalone operations (for tooling that doesn't need full client)
 export { executeContractEmit } from '../control-api/operations/contract-emit';
-
 // CLI-specific types
 export type {
   ContractEmitOptions,
@@ -54,3 +53,5 @@ export type {
   SignOptions,
   VerifyOptions,
 } from '../control-api/types';
+// Lifecycle helpers for hosts that publish to many output paths
+export { disposeEmitQueue } from '../utils/emit-queue';

package/src/exports/init-output.ts

@@ -0,0 +1,10 @@
+/**
+ * Public re-export of the `init --json` success-document schema (FR1.5).
+ *
+ * Imported as `@prisma-next/cli/init-output`. The shared error envelope is
+ * exported separately from `@prisma-next/errors`; consumers should branch
+ * on the `ok` discriminator (success documents carry `ok: true`, error
+ * envelopes carry `ok: false`) per the
+ * [Style Guide § JSON Semantics](../../../../../../../docs/CLI%20Style%20Guide.md#json-semantics).
+ */
+export { type InitOutput, InitOutputSchema } from '../commands/init/output';

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 ?? {}) },
+  });
+}