@prisma-next/cli 0.11.0-dev.6 → 0.11.0-dev.60

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

@@ -12,11 +12,11 @@ import {
   type ContractSpaceAggregate,
   type ContractSpaceMember,
   graphWalkStrategy,
+  requireHeadRef,
 } from '@prisma-next/migration-tools/aggregate';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { errorNoInvariantPath } from '@prisma-next/migration-tools/errors';
 import { findPathWithDecision } from '@prisma-next/migration-tools/migration-graph';
-import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import {
@@ -56,15 +56,6 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
   readonly migrationsDir: string;
   readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly targetId: TTargetId;
-  /**
-   * Already-loaded app-space migration packages. The CLI command
-   * loads these via `loadMigrationPackages(appMigrationsDir)`; the
-   * operation hydrates the app member's graph with them. Required
-   * because the framework-neutral aggregate loader doesn't know how
-   * to read the user's `migrations/` directory layout (it's family-
-   * aware: ops.json shape, manifest keys, etc.).
-   */
-  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
   /**
    * Optional app-space ref override. When provided, the app member's
    * graph-walk targets this hash instead of `member.headRef.hash`.
@@ -125,7 +116,6 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     migrationsDir,
     extensionPacks,
     targetId,
-    appMigrationPackages,
     refHash,
     refInvariants,
     refName,
@@ -138,7 +128,6 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     appContract: contract,
     extensionPacks,
     deserializeContract: (json) => familyInstance.deserializeContract(json),
-    appMigrationPackages,
   };
   const loaded = await buildContractSpaceAggregate(loadInputs);
   if (!loaded.ok) {
@@ -161,12 +150,15 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
   const atHeadResolutions = new Map<string, AggregatePerSpacePlan>();
   for (const member of allMembers) {
     const isAppMember = member.spaceId === aggregate.app.spaceId;
-    const targetHash = isAppMember && refHash !== undefined ? refHash : member.headRef.hash;
+    // The aggregate passed the integrity gate, so every member's head ref
+    // is resolved (the app's is synthesised from the live contract).
+    const headRef = requireHeadRef(member);
+    const targetHash = isAppMember && refHash !== undefined ? refHash : headRef.hash;
     const liveMarker = markerRows.get(member.spaceId) ?? null;
 
     // Empty-graph members fail loudly: replay needs an on-disk path
     // and an empty graph means the user has never planned this space.
-    if (member.migrations.graph.nodes.size === 0) {
+    if (member.graph().nodes.size === 0) {
       // Edge case: target == EMPTY (greenfield, nothing to do) or
       // the live marker already matches the target. Loader integrity
       // allows this for extensions whose head ref is the empty
@@ -197,9 +189,9 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     const targetInvariants =
       isAppMember && refHash !== undefined && refInvariants !== undefined
         ? refInvariants
-        : member.headRef.invariants;
+        : headRef.invariants;
     const targetMember: ContractSpaceMember =
-      targetHash === member.headRef.hash && targetInvariants === member.headRef.invariants
+      targetHash === headRef.hash && targetInvariants === headRef.invariants
         ? member
         : { ...member, headRef: { hash: targetHash, invariants: targetInvariants } };
 
@@ -224,7 +216,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
       // is never a graph node, producing an empty `structuralPath` and
       // a less actionable diagnostic.
       const fromHash = liveMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
-      const structural = findPathWithDecision(targetMember.migrations.graph, fromHash, targetHash, {
+      const structural = findPathWithDecision(targetMember.graph(), fromHash, targetHash, {
         required: new Set<string>(),
       });
       const structuralPath =
@@ -369,7 +361,7 @@ function buildAtHeadResolution(args: {
       providedInvariants: [],
     },
     displayOps: [],
-    destinationContract: member.contract,
+    destinationContract: member.contract(),
     strategy: 'graph-walk',
     migrationEdges: [],
   };
@@ -407,7 +399,7 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
     (r) => r.spaceId === args.aggregate.app.spaceId,
   );
   const appMarkerHash =
-    appResolution?.entry.plan.destination.storageHash ?? args.aggregate.app.headRef.hash;
+    appResolution?.entry.plan.destination.storageHash ?? requireHeadRef(args.aggregate.app).hash;
 
   // Per-migration entries (one per authored edge) preserve the
   // single-space `migrationsApplied` count semantics for back-compat
@@ -458,16 +450,37 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
   };
 }
 
-function buildNeverPlannedFailure(spaceId: string, targetHash: string): MigrationApplyFailure {
+/**
+ * Build the `neverPlanned` failure raised when a contract space has no on-disk
+ * migration graph but migrate was asked to reach a target hash. The `why`
+ * states only the condition; the recovery sequence is composed by
+ * `errorPathUnreachable`'s `fix`.
+ *
+ * @internal Exported for testing only.
+ */
+export function buildNeverPlannedFailure(
+  spaceId: string,
+  targetHash: string,
+): MigrationApplyFailure {
   return {
     code: 'MIGRATION_PATH_NOT_FOUND',
     summary: `No on-disk migrations for contract space "${spaceId}"`,
-    why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}". Run \`prisma-next migration plan\` first to materialise the path.`,
+    why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}".`,
     meta: { spaceId, target: targetHash, kind: 'neverPlanned' },
   };
 }
 
-function buildPathNotFoundFailure(
+/**
+ * Build the `pathUnreachable` failure raised when an emitted contract has no
+ * on-disk migration edge from the current marker to the target. The `why`
+ * states only the condition (no edge between the two named states, and migrate
+ * replays edges rather than inventing them); the recovery sequence — plan the
+ * edge, then re-apply — is composed by `errorPathUnreachable`'s `fix`, so the
+ * two read as one non-redundant plan-then-apply story.
+ *
+ * @internal Exported for testing only.
+ */
+export function buildPathNotFoundFailure(
   spaceId: string,
   marker: ContractMarkerRecordLike | null,
   targetHash: string,
@@ -485,7 +498,7 @@ function buildPathNotFoundFailure(
   return {
     code: 'MIGRATION_PATH_NOT_FOUND',
     summary,
-    why: `Cannot reach target "${targetHash}" from current marker "${fromHash}" in space "${spaceId}". The on-disk migration graph for this space does not connect the two states. Run \`prisma-next migration plan\` to materialise the path.`,
+    why: `No migration edge connects the current state "${fromHash}" to the target "${targetHash}" in contract space "${spaceId}". The on-disk migration graph does not join the two, and migrate replays existing edges — it never invents one.`,
     meta: { spaceId, fromHash, targetHash, kind: 'pathUnreachable' },
   };
 }

package/src/control-api/types.ts

@@ -18,7 +18,6 @@ import type {
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
 import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
-import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import type { Result } from '@prisma-next/utils/result';
 import type { ExecuteDbVerifyResult } from './operations/db-verify';
 
@@ -548,12 +547,6 @@ export interface MigrationApplyOptions {
   readonly contract: unknown;
   /** Migrations root directory (`migrations/` under the project). */
   readonly migrationsDir: string;
-  /**
-   * Already-loaded app-space migration packages. The CLI loads these
-   * via `loadMigrationPackages(appMigrationsDir)` before invoking
-   * `migrationApply`.
-   */
-  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
   /**
    * Optional app-space ref override. When provided, the app member's
    * graph-walk targets this hash instead of `contract.storage.storageHash`.
@@ -584,9 +577,9 @@ export interface MigrationApplyOptions {
 
 /**
  * A single on-disk migration package surfaced to the operation. The
- * SQL family already produces this shape via `loadMigrationPackages`;
- * the operation hands it through to the framework-neutral aggregate
- * loader's `appMigrationPackages` slot.
+ * SQL family surfaces this shape from the tolerant contract-space
+ * aggregate's app packages; the operation hands it through to the
+ * framework-neutral aggregate loader's `appMigrationPackages` slot.
  *
  * (Originally named `MigrationApplyStep` for the legacy single-space
  * apply path; the name is kept for compatibility with existing CLI

package/src/migration-cli.ts

@@ -461,8 +461,8 @@ function writeStructuredError(stream: MigrationCliWritable, err: CliStructuredEr
  * `null` when the file is missing and throwing `MIGRATION.INVALID_JSON`
  * when the file is present but cannot be parsed as JSON. The CLI feeds
  * this into `buildMigrationArtifacts` so the pure builder can preserve
- * fields owned by `migration plan` (contract bookends, hints, labels,
- * `createdAt`) across re-emits.
+ * fields owned by `migration plan` (contract bookends, `createdAt`) across
+ * re-emits.
  *
  * Author-time path: this loader still does not verify the manifest hash
  * or schema — that is the apply-time loader's job. Hash mismatch is the
@@ -472,8 +472,8 @@ function writeStructuredError(stream: MigrationCliWritable, err: CliStructuredEr
  * however, is now surfaced rather than swallowed: a malformed
  * `migration.json` indicates either a hand-edit gone wrong or partial
  * write, and silently rebuilding from `describe()` would discard the
- * user's on-disk content (preserved bookends, hints, labels,
- * `createdAt`) without any indication something was wrong on disk.
+ * user's on-disk content (preserved bookends, `createdAt`) without any
+ * indication something was wrong on disk.
  * Apply-time consumers always route through the verifying
  * `readMigrationPackage` in `@prisma-next/migration-tools/io` instead.
  */

package/src/utils/cli-errors.ts

@@ -28,6 +28,7 @@ import {
 import { errorRuntime } from '@prisma-next/errors/execution';
 import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';
+import type { MigrationApplyFailure } from '../control-api/types';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -68,6 +69,239 @@ export {
   errorUnexpected,
 };
 
+export function errorRefSetHashNotInGraph(
+  resolvedHash: string,
+  reachableHashes: readonly string[],
+  graphTipHash: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';
+  const fix =
+    reachableHashes.length > 0
+      ? graphTipHash !== null
+        ? `Set the ref to a graph-node hash such as ${graphTipHash}, or run \`prisma-next migration plan\` to extend the graph.`
+        : 'Set the ref to a hash that appears in the migration graph.'
+      : 'Run `prisma-next migration plan` first.';
+  return errorRuntime(`Resolved contract hash is not in the migration graph: ${resolvedHash}`, {
+    why:
+      reachableHashes.length > 0
+        ? `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`
+        : 'The migration graph is empty — no hashes reachable.',
+    fix,
+    meta: {
+      code: 'MIGRATION.HASH_NOT_IN_GRAPH',
+      resolvedHash,
+      reachableHashes: [...reachableHashes],
+      ...(graphTipHash !== null ? { graphTipHash } : {}),
+    },
+  });
+}
+
+export function errorRefSetEmptySentinel(hash: string): CliStructuredError {
+  return errorRuntime(`Cannot set ref to the empty-database sentinel: ${hash}`, {
+    why: 'The empty-database sentinel is a planner internal; it is not a valid ref target.',
+    fix: 'Set the ref to a contract hash from the migration graph, or use another ref name.',
+    meta: {
+      code: 'MIGRATION.REF_SET_EMPTY_SENTINEL',
+      hash,
+    },
+  });
+}
+
+/**
+ * `--space <id>` was given a value that doesn't satisfy the contract-space
+ * naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before
+ * any fs work — the input is syntactically rejected the same way an on-disk
+ * directory with that name would be skipped by the enumerator.
+ */
+export function errorInvalidSpaceId(spaceId: string): CliStructuredError {
+  return errorRuntime(`Invalid contract space id: ${spaceId}`, {
+    why: 'Contract space ids must match [a-z][a-z0-9_-]{0,63} (lowercase, starts with a letter, max 64 characters — the rule applied to every on-disk space directory).',
+    fix: 'Pass a space id that matches the directory naming rule, or omit --space to list every space.',
+    meta: {
+      code: 'MIGRATION.INVALID_SPACE_ID',
+      spaceId,
+    },
+  });
+}
+
+/**
+ * `migration list --space <id>` was given a contract-space id that has no
+ * directory under `migrations/`. Distinct from "the space exists but is
+ * empty" — that path renders the empty-state line and exits 0 per the
+ * slice spec § Empty-state. This error fires only when `<projectMigrationsDir>/<spaceId>`
+ * does not exist on disk.
+ *
+ * `availableSpaces` lists the contract-space directory names actually
+ * present, sorted lex-asc, so the diagnostic can suggest a near match
+ * without making the user reach for `ls`.
+ */
+export function errorSpaceNotFound(
+  spaceId: string,
+  availableSpaces: readonly string[],
+): CliStructuredError {
+  const availableList =
+    availableSpaces.length > 0
+      ? availableSpaces.join(', ')
+      : '(none — no contract spaces on disk yet)';
+  const fix =
+    availableSpaces.length > 0
+      ? `Pick one of: ${availableList}. Run \`prisma-next migration list\` (no --space) to see every space's migrations.`
+      : 'Author a migration with `prisma-next migration new` to create the first contract-space directory.';
+  return errorRuntime(`Unknown contract space: ${spaceId}`, {
+    why: `No directory named "${spaceId}" exists under the migrations root.`,
+    fix,
+    meta: {
+      code: 'MIGRATION.SPACE_NOT_FOUND',
+      spaceId,
+      availableSpaces: [...availableSpaces],
+    },
+  });
+}
+
+export function errorRefSetBundleNotFound(hash: string): CliStructuredError {
+  return errorRuntime(`No migration bundle matches graph-node hash ${hash}`, {
+    why: `The hash is a graph node but no on-disk bundle has metadata.to = ${hash}.`,
+    fix: 'Run `pnpm fixtures:check`, or re-emit the migration that produces this hash so its bundle is restored.',
+    meta: {
+      code: 'MIGRATION.REF_SET_BUNDLE_NOT_FOUND',
+      hash,
+    },
+  });
+}
+
+export function errorPlanForgotTheFlag(
+  resolvedHash: string,
+  reachableRefs: ReadonlyArray<{ readonly name: string; readonly hash: string }>,
+  graphTipHash: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableRefs.length > 0
+      ? reachableRefs.map((r) => `${r.name} (${r.hash})`).join(', ')
+      : '(none)';
+  const refFix =
+    reachableRefs.length > 0
+      ? `Run migration plan with ${reachableRefs.map((r) => `--from ${r.name}`).join(' or ')}.`
+      : graphTipHash !== null
+        ? `Run migration plan --from ${graphTipHash}.`
+        : 'Commit pending migrations first, then run migration plan.';
+  return errorRuntime(`Resolved from-hash is not in the migration graph: ${resolvedHash}`, {
+    why: `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`,
+    fix: refFix,
+    meta: {
+      code: 'MIGRATION.HASH_NOT_IN_GRAPH',
+      resolvedHash,
+      reachableRefs: reachableRefs.map((r) => r.name),
+      ...(graphTipHash !== null ? { graphTipHash } : {}),
+    },
+  });
+}
+
+export function errorSnapshotMissing(
+  identifier: string,
+  options?: { readonly viaRef?: boolean },
+): CliStructuredError {
+  const viaRef = options?.viaRef !== false;
+  const fix = viaRef
+    ? `Run "prisma-next db update --advance-ref ${identifier}" to repopulate the snapshot, or "prisma-next ref delete ${identifier}" to clear the orphan pointer.`
+    : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;
+  return errorRuntime(
+    viaRef
+      ? `Ref "${identifier}" has no paired contract snapshot`
+      : `No contract source for from-hash "${identifier}"`,
+    {
+      why: viaRef
+        ? `Ref "${identifier}" exists but its paired snapshot files are missing.`
+        : `Hash "${identifier}" is not a graph node and no paired ref snapshot supplies a contract.`,
+      fix,
+      meta: {
+        code: 'MIGRATION.SNAPSHOT_MISSING',
+        identifier,
+        viaRef,
+      },
+    },
+  );
+}
+
+export function errorMarkerMismatch(
+  markerHash: string,
+  reachableHashes: readonly string[],
+  graphTip: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';
+  const planFromFix =
+    graphTip !== null
+      ? `Run \`prisma-next migration plan --from ${graphTip}\` if the live marker is canonical and the on-disk graph needs catching up.`
+      : 'Run `prisma-next migration plan` if the live marker is canonical and the on-disk graph needs catching up.';
+  return errorRuntime('Database marker is not reachable in the on-disk migration graph', {
+    why: `DB marker is ${markerHash}, but the on-disk migration graph reaches: ${reachableList}.`,
+    fix: [
+      planFromFix,
+      `Run \`prisma-next ref set db ${markerHash}\` if the on-disk graph is canonical and the local \`db\` ref drifted.`,
+      'Investigate whether the database was migrated by an out-of-band process.',
+    ].join('\n'),
+    meta: {
+      code: 'MIGRATION.MARKER_MISMATCH',
+      markerHash,
+      reachableHashes: [...reachableHashes],
+      ...(graphTip !== null ? { graphTip } : {}),
+    },
+  });
+}
+
+export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {
+  const meta = failure.meta ?? {};
+  const fromHashMeta = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
+  // `buildPathNotFoundFailure` uses this sentinel in meta when the live marker is null.
+  const planFromHash = fromHashMeta === '<empty>' ? null : fromHashMeta;
+  const targetHash =
+    typeof meta['targetHash'] === 'string'
+      ? meta['targetHash']
+      : typeof meta['target'] === 'string'
+        ? meta['target']
+        : null;
+  const deadEnds = meta['deadEnds'];
+  const deadEndsSuffix =
+    Array.isArray(deadEnds) && deadEnds.length > 0
+      ? ` Dead-ends: ${deadEnds.map(String).join(', ')}.`
+      : '';
+  // Plan-then-apply recovery. The planner destination is the missing edge's
+  // target; `migration plan --to` (built for arbitrary targets) makes this a
+  // real command, so the diagnostic that sends you here is now honest.
+  const planCommand = (() => {
+    if (planFromHash !== null && targetHash !== null) {
+      return `prisma-next migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;
+    }
+    if (targetHash !== null) {
+      return `prisma-next migration plan --to ${targetHash} --name <slug>`;
+    }
+    if (planFromHash !== null) {
+      return `prisma-next migration plan --from ${planFromHash} --name <slug>`;
+    }
+    return 'prisma-next migration plan';
+  })();
+  const applyCommand =
+    targetHash !== null ? `prisma-next migrate --to ${targetHash}` : 'prisma-next migrate';
+  return errorRuntime(failure.summary, {
+    why:
+      failure.why ??
+      `Cannot reach target "${targetHash ?? '<unknown>'}" from current marker "${fromHashMeta ?? '<unknown>'}".${deadEndsSuffix}`,
+    fix: [
+      'Plan the missing edge, then apply it:',
+      `  1. ${planCommand}`,
+      `  2. ${applyCommand}`,
+      'A rollback (reverse) plan is expected to contain destructive (DROP) operations — review them before applying.',
+      'Narrower cases (rename inference, re-adding a NOT NULL column without a safe default, or a type change that needs data) may additionally need a hint in the planned migration.',
+      'Inspect the on-disk graph with `prisma-next migration list`, or `prisma-next migration show <bundle>` for any bundle in the path you expected.',
+    ].join('\n'),
+    meta: {
+      ...meta,
+      code: 'MIGRATION.PATH_UNREACHABLE',
+    },
+  });
+}
+
 /**
  * Maps a `MigrationToolsError` raised by the migration-tools loader/graph
  * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,

package/src/utils/command-helpers.ts

@@ -3,10 +3,7 @@ import type { ControlTargetDescriptor } from '@prisma-next/framework-components/
 import { hasMigrations } from '@prisma-next/framework-components/control';
 import type { NoInvariantPathStructuralEdge } from '@prisma-next/migration-tools/errors';
 import type { MigrationEdge, MigrationGraph } from '@prisma-next/migration-tools/graph';
-import { readMigrationsDir } from '@prisma-next/migration-tools/io';
 import type { PathDecision } from '@prisma-next/migration-tools/migration-graph';
-import { reconstructGraph } from '@prisma-next/migration-tools/migration-graph';
-import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import { APP_SPACE_ID, spaceMigrationDirectory } from '@prisma-next/migration-tools/spaces';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
@@ -154,7 +151,7 @@ export function resolveMigrationPaths(
 
 /**
  * Slim representation of a PathDecision for CLI JSON output.
- * Strips internal fields (createdAt, labels) from path entries.
+ * Strips internal fields (createdAt) from path entries.
  */
 export interface PathDecisionResult {
   readonly fromHash: string;
@@ -231,22 +228,6 @@ export function getTargetMigrations(target: ControlTargetDescriptor<string, stri
   return hasMigrations(target) ? target.migrations : undefined;
 }
 
-/**
- * Reads the migrations directory and builds the migration graph from all
- * packages. Throws on I/O or graph errors — callers handle error mapping.
- *
- * Every on-disk package is content-addressed (`migrationHash` is always a
- * string); there is no draft state to filter out.
- */
-export async function loadMigrationPackages(migrationsDir: string): Promise<{
-  bundles: readonly OnDiskMigrationPackage[];
-  graph: MigrationGraph;
-}> {
-  const bundles = await readMigrationsDir(migrationsDir);
-  const graph = reconstructGraph(bundles);
-  return { bundles, graph };
-}
-
 /**
  * The subset of the emitted contract.json that the framework layer can
  * safely type. The emitter adds these fields on top of the family-specific

package/src/utils/contract-at-errors.ts

@@ -0,0 +1,96 @@
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { notOk, type Result } from '@prisma-next/utils/result';
+import { join } from 'pathe';
+import {
+  CliStructuredError,
+  errorContractValidationFailed,
+  errorFileNotFound,
+  errorSnapshotMissing,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from './cli-errors';
+
+export function mapContractAtError(
+  error: unknown,
+  options?: { readonly artifactRole?: 'from' | 'to' },
+): Result<never, CliStructuredError> {
+  if (MigrationToolsError.is(error)) {
+    switch (error.code) {
+      case 'MIGRATION.SNAPSHOT_MISSING': {
+        const refName =
+          typeof error.details?.['refName'] === 'string'
+            ? error.details['refName']
+            : typeof error.details?.['identifier'] === 'string'
+              ? error.details['identifier']
+              : 'unknown';
+        return notOk(errorSnapshotMissing(refName));
+      }
+      case 'MIGRATION.CONTRACT_DESERIALIZATION_FAILED': {
+        const filePath =
+          typeof error.details?.['filePath'] === 'string'
+            ? error.details['filePath']
+            : 'ref-snapshot';
+        const message =
+          typeof error.details?.['message'] === 'string' ? error.details['message'] : error.message;
+        const isRefSnapshot = filePath.endsWith('.contract.json');
+        return notOk(
+          errorContractValidationFailed(
+            isRefSnapshot
+              ? `Ref snapshot contract failed to deserialize: ${message}`
+              : `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
+            { where: { path: isRefSnapshot ? 'ref-snapshot' : filePath } },
+          ),
+        );
+      }
+      case 'MIGRATION.INVALID_JSON': {
+        const filePath =
+          typeof error.details?.['filePath'] === 'string' ? error.details['filePath'] : 'unknown';
+        const message =
+          typeof error.details?.['parseError'] === 'string'
+            ? error.details['parseError']
+            : error.message;
+        const role = options?.artifactRole ?? 'from';
+        return notOk(
+          errorContractValidationFailed(
+            role === 'to'
+              ? `Target contract at ${filePath} failed to deserialize: ${message}`
+              : `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
+            { where: { path: filePath } },
+          ),
+        );
+      }
+      case 'MIGRATION.BUNDLE_NOT_FOUND_FOR_GRAPH_NODE':
+        return notOk(
+          errorUnexpected(error.message, {
+            why: error.why,
+            fix: error.fix,
+          }),
+        );
+      case 'MIGRATION.FILE_MISSING': {
+        const file =
+          typeof error.details?.['file'] === 'string' ? error.details['file'] : 'end-contract.json';
+        const dir = typeof error.details?.['dir'] === 'string' ? error.details['dir'] : '';
+        const jsonPath = dir ? join(dir, 'end-contract.json') : file;
+        const role = options?.artifactRole ?? 'from';
+        return notOk(
+          errorFileNotFound(jsonPath, {
+            why:
+              role === 'to'
+                ? `Target migration is missing its destination contract snapshot at ${jsonPath}`
+                : `Predecessor migration is missing its destination contract snapshot at ${jsonPath}`,
+            fix:
+              role === 'to'
+                ? 'Re-emit the target migration so its sibling `end-contract.json` / `end-contract.d.ts` are restored, then re-run this command.'
+                : '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.',
+          }),
+        );
+      }
+      default:
+        return notOk(mapMigrationToolsError(error));
+    }
+  }
+  if (CliStructuredError.is(error)) {
+    return notOk(error);
+  }
+  throw error;
+}