@prisma-next/cli 0.11.0-dev.55 → 0.11.0-dev.57

package/src/commands/migration-plan.ts

@@ -2,7 +2,6 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import {
-  type ControlFamilyInstance,
   createControlStack,
   hasOperationPreview,
   type MigrationPlanOperation,
@@ -36,20 +35,22 @@ import {
 import {
   addGlobalOptions,
   getTargetMigrations,
-  loadMigrationPackages,
   resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
-import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
+import {
+  buildContractSpaceAggregate,
+  loadContractSpaceAggregateForCli,
+} 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';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
-import { resolveFromForPlan } from '../utils/plan-resolution';
+import { resolveFromForPlan, resolveToForPlan } from '../utils/plan-resolution';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
@@ -57,55 +58,7 @@ interface MigrationPlanOptions extends CommonCommandOptions {
   readonly config?: string;
   readonly name?: string;
   readonly from?: string;
-}
-
-/**
- * Load a predecessor migration's destination contract from its sibling
- * `end-contract.json` on disk and route it through the family's
- * `ContractSerializer` (via `deserializeContract`) so the in-memory shape
- * is the hydrated `Contract` every other caller sees. Bypassing this
- * seam was the root cause of TML-2536: a raw `JSON.parse(...) as Contract`
- * here let polymorphic `storage.types` entries reach the planner without
- * the `kind` discriminator the planner dispatches on.
- *
- * Throws `CliStructuredError` with:
- *   - `errorFileNotFound` when the sibling file is missing — the user
- *     has likely deleted or never authored the snapshot, and the
- *     message names the file and points them at re-emitting from the
- *     source.
- *   - `errorContractValidationFailed` when the JSON parses but the
- *     family deserializer rejects it (legacy untagged shape, structural
- *     mismatch, etc.) — the message names the predecessor's path so
- *     the operator can locate the bad snapshot.
- */
-async function readPredecessorEndContract(
-  migrationDir: string,
-  familyInstance: ControlFamilyInstance<string, unknown>,
-): Promise<Contract> {
-  const path = join(migrationDir, 'end-contract.json');
-  let raw: string;
-  try {
-    raw = await readFile(path, 'utf-8');
-  } catch (error) {
-    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-      throw errorFileNotFound(path, {
-        why: `Predecessor migration is missing its destination contract snapshot at ${path}`,
-        fix: 'Re-emit the predecessor migration (`prisma-next migration plan` from its source) so its sibling `end-contract.json` is restored, then re-run this command.',
-      });
-    }
-    throw error;
-  }
-  try {
-    return familyInstance.deserializeContract(JSON.parse(raw) as unknown);
-  } catch (error) {
-    if (CliStructuredError.is(error)) {
-      throw error;
-    }
-    throw errorContractValidationFailed(
-      `Predecessor contract at ${path} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
-      { where: { path } },
-    );
-  }
+  readonly to?: string;
 }
 
 async function writeSnapshotContractArtifacts(
@@ -282,6 +235,9 @@ async function executeMigrationPlanCommand(
     if (options.from) {
       details.push({ label: 'from', value: options.from });
     }
+    if (options.to) {
+      details.push({ label: 'to', value: options.to });
+    }
     if (options.name) {
       details.push({ label: 'name', value: options.name });
     }
@@ -315,8 +271,7 @@ async function executeMigrationPlanCommand(
     );
   }
 
-  // Construct the family instance up-front so on-disk reads (the app
-  // contract here + every `readPredecessorEndContract` below) cross the
+  // Construct the family instance up-front so on-disk contract reads cross the
   // serializer seam at the read site, not after the planner has already
   // started dispatching on raw shapes. See TML-2536.
   const stack = createControlStack(config);
@@ -342,9 +297,12 @@ async function executeMigrationPlanCommand(
       }),
     );
   }
-  const toStorageHash = rawStorageHash;
+  let toStorageHash: string = rawStorageHash;
 
-  const { refsDir } = resolveMigrationPaths(options.config, config);
+  // When `--to <ref>` resolves a non-default destination, these carry its raw
+  // artifacts so the planned package's `end-contract.*` is written from the
+  // resolved target rather than copied from the emitted `contract.json`.
+  let toArtifacts: { contractJson: unknown; contractDts: string } | null = null;
 
   let fromContract: Contract | null = null;
   let fromHash: string | null = null;
@@ -352,62 +310,71 @@ async function executeMigrationPlanCommand(
   let snapshotStartContract: { contractJson: unknown; contractDts: string } | null = null;
   let isAutoBaseline = false;
 
-  try {
-    const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
-
-    const resolutionResult = await resolveFromForPlan({
-      optionsFrom: options.from,
-      refsDir,
-      bundles,
-      graph,
-      familyInstance,
-      readBundleEndContract: (migrationDir) =>
-        readPredecessorEndContract(migrationDir, familyInstance),
-    });
+  const tolerantAggregateResult = await loadContractSpaceAggregateForCli({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: toContract,
+    extensionPacks: config.extensionPacks ?? [],
+    deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
+  });
+  if (!tolerantAggregateResult.ok) {
+    return notOk(tolerantAggregateResult.failure);
+  }
+  const resolutionMember = tolerantAggregateResult.value.app;
 
-    if (!resolutionResult.ok) {
-      return notOk(resolutionResult.failure);
-    }
+  const resolutionResult = await resolveFromForPlan({
+    optionsFrom: options.from,
+    member: resolutionMember,
+  });
 
-    switch (resolutionResult.value.kind) {
-      case 'greenfield':
-        break;
-      case 'graph-node':
-        fromHash = resolutionResult.value.fromHash;
-        fromContract = resolutionResult.value.fromContract;
-        fromContractSourceDir = resolutionResult.value.sourceDir;
-        break;
-      case 'snapshot':
-        fromHash = resolutionResult.value.fromHash;
-        fromContract = resolutionResult.value.fromContract;
-        snapshotStartContract = {
-          contractJson: resolutionResult.value.contractJson,
-          contractDts: resolutionResult.value.contractDts,
-        };
-        break;
-      case 'auto-baseline':
-        fromHash = resolutionResult.value.fromHash;
-        fromContract = resolutionResult.value.fromContract;
-        snapshotStartContract = {
-          contractJson: resolutionResult.value.contractJson,
-          contractDts: resolutionResult.value.contractDts,
-        };
-        isAutoBaseline = true;
-        break;
-    }
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      return notOk(mapMigrationToolsError(error));
-    }
-    if (CliStructuredError.is(error)) {
-      return notOk(error);
+  if (!resolutionResult.ok) {
+    return notOk(resolutionResult.failure);
+  }
+
+  switch (resolutionResult.value.kind) {
+    case 'greenfield':
+      break;
+    case 'graph-node':
+      fromHash = resolutionResult.value.fromHash;
+      fromContract = resolutionResult.value.fromContract;
+      fromContractSourceDir = resolutionResult.value.sourceDir;
+      break;
+    case 'snapshot':
+      fromHash = resolutionResult.value.fromHash;
+      fromContract = resolutionResult.value.fromContract;
+      snapshotStartContract = {
+        contractJson: resolutionResult.value.contractJson,
+        contractDts: resolutionResult.value.contractDts,
+      };
+      break;
+    case 'auto-baseline':
+      fromHash = resolutionResult.value.fromHash;
+      fromContract = resolutionResult.value.fromContract;
+      snapshotStartContract = {
+        contractJson: resolutionResult.value.contractJson,
+        contractDts: resolutionResult.value.contractDts,
+      };
+      isAutoBaseline = true;
+      break;
+  }
+
+  // `--to <ref>` swaps the planner destination to an arbitrary resolved
+  // contract (e.g. an ancestor / rollback target). The from-side resolution
+  // above is untouched; only the destination + its emitted `end-contract.*`
+  // change.
+  if (options.to !== undefined) {
+    const toResolution = await resolveToForPlan(options.to, {
+      member: resolutionMember,
+    });
+    if (!toResolution.ok) {
+      return notOk(toResolution.failure);
     }
-    const message = error instanceof Error ? error.message : String(error);
-    return notOk(
-      errorUnexpected(message, {
-        why: `Unexpected error while loading migrations: ${message}`,
-      }),
-    );
+    toContract = toResolution.value.contract;
+    toStorageHash = toResolution.value.hash;
+    toArtifacts = {
+      contractJson: toResolution.value.contractJson,
+      contractDts: toResolution.value.contractDts,
+    };
   }
 
   // Phase 1 — seed: unconditionally re-emit per-space pinned artefacts
@@ -487,6 +454,26 @@ async function executeMigrationPlanCommand(
     [config.target, config.adapter, ...(config.extensionPacks ?? [])],
   );
 
+  // Write the planned package's destination `end-contract.*`. With `--to`, the
+  // resolved target's raw artifacts are written; otherwise the emitted
+  // `contract.json` / `contract.d.ts` are copied verbatim (today's behaviour).
+  async function writeDestinationEndContract(packageDir: string): Promise<void> {
+    if (toArtifacts !== null) {
+      await writeSnapshotContractArtifacts(
+        packageDir,
+        toArtifacts.contractJson,
+        toArtifacts.contractDts,
+        'end-contract',
+      );
+      return;
+    }
+    const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
+    await copyFilesWithRename(packageDir, [
+      { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
+      { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
+    ]);
+  }
+
   try {
     const planner = migrations.createPlanner(familyInstance);
 
@@ -591,11 +578,7 @@ async function executeMigrationPlanCommand(
         deltaTimestamp,
         deltaLeg.value,
       );
-      const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
-      await copyFilesWithRename(deltaPackageDir, [
-        { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
-        { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
-      ]);
+      await writeDestinationEndContract(deltaPackageDir);
       await writeSnapshotStartContract(
         deltaPackageDir,
         snapshotStartContract.contractJson,
@@ -668,11 +651,7 @@ async function executeMigrationPlanCommand(
       timestamp,
       deltaLeg.value,
     );
-    const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
-    await copyFilesWithRename(packageDir, [
-      { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
-      { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
-    ]);
+    await writeDestinationEndContract(packageDir);
     if (fromContractSourceDir !== null) {
       const sourceArtifacts = getEmittedArtifactPaths(
         join(fromContractSourceDir, 'end-contract.json'),
@@ -755,6 +734,7 @@ export function createMigrationPlanCommand(): Command {
   setCommandExamples(command, [
     'prisma-next migration plan',
     'prisma-next migration plan --name add-users-table',
+    'prisma-next migration plan --to <migration-dir>^ --name rollback',
   ]);
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
@@ -763,6 +743,10 @@ export function createMigrationPlanCommand(): Command {
       '--from <contract>',
       'Starting contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
+    .option(
+      '--to <contract>',
+      'Destination contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path); defaults to the emitted contract',
+    )
     .action(async (options: MigrationPlanOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();

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

@@ -450,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,
@@ -477,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/utils/cli-errors.ts

@@ -252,7 +252,9 @@ export function errorMarkerMismatch(
 
 export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {
   const meta = failure.meta ?? {};
-  const fromHash = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
+  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']
@@ -264,26 +266,34 @@ export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructu
     Array.isArray(deadEnds) && deadEnds.length > 0
       ? ` Dead-ends: ${deadEnds.map(String).join(', ')}.`
       : '';
-  const planFix = (() => {
-    if (fromHash !== null && targetHash !== null) {
-      return `Run \`prisma-next migration plan --from ${fromHash} --to ${targetHash}\` to introduce the missing path.`;
+  // 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 `Run \`prisma-next migration plan --to ${targetHash}\` to introduce the missing path.`;
+      return `prisma-next migration plan --to ${targetHash} --name <slug>`;
     }
-    if (fromHash !== null) {
-      return `Run \`prisma-next migration plan --from ${fromHash}\` to introduce the missing path.`;
+    if (planFromHash !== null) {
+      return `prisma-next migration plan --from ${planFromHash} --name <slug>`;
     }
-    return 'Run `prisma-next migration plan` to introduce the missing path.';
+    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 "${fromHash ?? '<unknown>'}".${deadEndsSuffix}`,
+      `Cannot reach target "${targetHash ?? '<unknown>'}" from current marker "${fromHashMeta ?? '<unknown>'}".${deadEndsSuffix}`,
     fix: [
-      'Run `prisma-next migration list` to see the on-disk graph.',
-      planFix,
-      'Run `prisma-next migration show <bundle>` for any bundle in the path you expected.',
+      '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,

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;
+}