@prisma-next/cli 0.8.0 → 0.9.0-dev.1

package/src/commands/migration-plan.ts

@@ -2,6 +2,7 @@ import { readFile } 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,
@@ -18,6 +19,8 @@ import {
 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 { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { join, relative } from 'pathe';
@@ -28,10 +31,10 @@ import {
   errorContractValidationFailed,
   errorFileNotFound,
   errorMigrationPlanningFailed,
-  errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -58,6 +61,55 @@ interface MigrationPlanOptions extends CommonCommandOptions {
   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 } },
+    );
+  }
+}
+
 export interface MigrationPlanResult {
   readonly ok: boolean;
   readonly noOp: boolean;
@@ -74,7 +126,7 @@ export interface MigrationPlanResult {
    * 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.
+   * that `migrate` will replay.
    */
   readonly emittedExtensionDirs: readonly { readonly spaceId: string; readonly dirName: string }[];
   readonly operations: readonly {
@@ -155,19 +207,26 @@ async function executeMigrationPlanCommand(
     );
   }
 
-  let toContractJson: Contract;
+  // Construct the family instance up-front so on-disk reads (the app
+  // contract here + every `readPredecessorEndContract` below) 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);
+  const familyInstance = config.family.create(stack);
+
+  let toContract: Contract;
   try {
-    toContractJson = JSON.parse(contractJsonContent) as Contract;
+    toContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
   } catch (error) {
     return notOk(
       errorContractValidationFailed(
-        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        `Contract at ${contractPathAbsolute} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
         { where: { path: contractPathAbsolute } },
       ),
     );
   }
 
-  const rawStorageHash = toContractJson.storage?.storageHash;
+  const rawStorageHash = toContract.storage?.storageHash;
   if (typeof rawStorageHash !== 'string') {
     return notOk(
       errorContractValidationFailed('Contract is missing storageHash', {
@@ -186,24 +245,26 @@ async function executeMigrationPlanCommand(
     const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
 
     if (options.from) {
-      const resolved = resolveBundleByPrefix(bundles, options.from);
-      if (!resolved.ok) {
-        const f = resolved.failure;
+      const refs = await readRefs(resolveMigrationPaths(options.config, config).refsDir);
+      const refResult = parseContractRef(options.from, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      fromHash = refResult.value.hash;
+      const matchingBundle = bundles.find((p) => p.metadata.to === fromHash);
+      if (!matchingBundle) {
         return notOk(
-          f.reason === 'ambiguous'
-            ? errorRuntime('Multiple matching migrations found', {
-                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 ${appMigrationsRelative}`,
-                fix: 'Check that the --from hash matches a known migration target hash, or omit --from to use the latest migration target.',
-              }),
+          errorUnexpected(
+            `No migration bundle found for --from "${options.from}" (resolved hash: ${fromHash})`,
+            {
+              why: `The ref resolved successfully but no on-disk migration package has an end-contract hash matching ${fromHash}.`,
+              fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
+            },
+          ),
         );
       }
-      fromHash = resolved.value.metadata.to;
-      fromContract = resolved.value.metadata.toContract;
-      fromContractSourceDir = resolved.value.dirPath;
+      fromContractSourceDir = matchingBundle.dirPath;
+      fromContract = await readPredecessorEndContract(fromContractSourceDir, familyInstance);
     } else {
       const latestMigration = findLatestMigration(graph);
       if (latestMigration) {
@@ -212,8 +273,8 @@ async function executeMigrationPlanCommand(
           (p) => p.metadata.migrationHash === latestMigration.migrationHash,
         );
         if (leafPkg) {
-          fromContract = leafPkg.metadata.toContract;
           fromContractSourceDir = leafPkg.dirPath;
+          fromContract = await readPredecessorEndContract(fromContractSourceDir, familyInstance);
         }
       }
     }
@@ -221,6 +282,12 @@ async function executeMigrationPlanCommand(
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
     }
+    // `readPredecessorEndContract` raises a `CliStructuredError` directly
+    // for the missing-snapshot case so the operator gets a precise
+    // why/fix; pass it through unchanged rather than re-wrapping.
+    if (CliStructuredError.is(error)) {
+      return notOk(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-
@@ -286,15 +353,16 @@ 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);
+  // declaredButUnmigrated precheck always passes here. The app contract
+  // was already routed through `familyInstance.deserializeContract` at the
+  // read site above (see TML-2536), so it's the hydrated `Contract`
+  // here — no second validation pass needed.
   const aggregateResult = await buildContractSpaceAggregate({
     targetId: config.target.targetId,
     migrationsDir,
-    appContract: toContractJson,
+    appContract: toContract,
     extensionPacks: config.extensionPacks ?? [],
-    validateContract: (json: unknown) => familyInstance.validateContract(json),
+    deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
   });
   if (!aggregateResult.ok) {
     return notOk(aggregateResult.failure);
@@ -316,8 +384,6 @@ async function executeMigrationPlanCommand(
   const baseMetadata: Omit<MigrationMetadata, 'migrationHash' | 'providedInvariants'> = {
     from: fromHash,
     to: toStorageHash,
-    fromContract,
-    toContract: toContractJson,
     hints: {
       used: [],
       applied: [],
@@ -480,7 +546,10 @@ export function createMigrationPlanCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--name <slug>', 'Name slug for the migration directory', 'migration')
-    .option('--from <hash>', 'Explicit starting contract hash (overrides latest migration target)')
+    .option(
+      '--from <contract>',
+      'Starting contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
     .action(async (options: MigrationPlanOptions) => {
       const flags = parseGlobalFlags(options);
       const startTime = Date.now();
@@ -546,7 +615,7 @@ export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: Gl
     }
     lines.push('');
     lines.push(
-      `Next: review the extension migrations above, then run ${green_('prisma-next migration apply')}.`,
+      `Next: review the extension migrations above, then run ${green_('prisma-next migrate')}.`,
     );
   }
 
@@ -617,11 +686,11 @@ export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: Gl
 
   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.
+  // (`prisma-next migrate`) regardless of how many spaces were
+  // materialised — `db update` is a dev-time convenience, not the
+  // canonical replay step.
   lines.push(
-    `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migration apply')}.`,
+    `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migrate')}.`,
   );
 
   if (result.preview && result.preview.statements.length > 0) {

package/src/commands/migration-show.ts

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import {
+  APP_SPACE_ID,
   createControlStack,
   type MigrationPlanOperation,
   type OperationPreview,
@@ -12,6 +13,8 @@ import {
   reconstructGraph,
 } from '@prisma-next/migration-tools/migration-graph';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { parseMigrationRef } from '@prisma-next/migration-tools/ref-resolution';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { spaceMigrationDirectory } from '@prisma-next/migration-tools/spaces';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
@@ -26,6 +29,7 @@ import {
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -33,6 +37,7 @@ import {
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
+  setCommandSeeAlso,
 } from '../utils/command-helpers';
 import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatMigrationShowOutput } from '../utils/formatters/migrations';
@@ -237,7 +242,7 @@ async function executeMigrationShowCommand(
   ui: TerminalUI,
 ): Promise<Result<MigrationShowResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative } =
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
     resolveMigrationPaths(options.config, config);
 
   const contractPathAbsolute = resolveContractPath(config);
@@ -261,7 +266,91 @@ async function executeMigrationShowCommand(
     ui.stderr(header);
   }
 
-  // Load the app contract so the aggregate loader can validate it.
+  // `migration show` is an offline command; the control client is constructed
+  // purely to dispatch the family-specific `toOperationPreview` capability and
+  // is not connected to a database.
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    ...ifDefined('driver', config.driver),
+    extensionPacks: config.extensionPacks ?? [],
+  });
+
+  // Explicit-target path. Read the app-space migrations directory directly
+  // and resolve `target` against the app graph. We deliberately skip
+  // `buildContractSpaceAggregate` here for two reasons:
+  //
+  // 1. Functional: the user asked about ONE specific migration. They don't
+  //    need extension-space enumeration; resolving + rendering the named
+  //    package is enough.
+  // 2. UX: the aggregate's layout-integrity check (PN-MIG-5001) fires when
+  //    an extension is declared but its migrations directory hasn't been
+  //    materialised. Gating an offline read-only inspect command on that
+  //    check forces users to run `migrate` against a database before they
+  //    can see what a migration contains — which contradicts what an
+  //    offline read-only verb should require.
+  //
+  // Same pattern as `migration list`, `migration graph`, `migration check`:
+  // those verbs read `appMigrationsDir` directly without ever consulting
+  // the aggregate.
+  if (target) {
+    try {
+      let appPkg: OnDiskMigrationPackage;
+      if (looksLikePath(target)) {
+        const resolved = resolveAppTargetPath(target, appMigrationsDir, appMigrationsRelative);
+        if (!resolved.ok) return resolved;
+        appPkg = await readMigrationPackage(resolved.value);
+      } else {
+        const allPackages = await readMigrationsDir(appMigrationsDir);
+        if (allPackages.length === 0) {
+          return notOk(
+            errorRuntime('No migrations found', {
+              why: `No migration packages found in ${appMigrationsRelative}`,
+              fix: 'Run `prisma-next migration plan` to create a migration first.',
+            }),
+          );
+        }
+        const graph = reconstructGraph(allPackages);
+        const refs = await readRefs(refsDir);
+        const migResult = parseMigrationRef(target, { graph, refs });
+        if (!migResult.ok) {
+          return notOk(mapRefResolutionError(migResult.failure));
+        }
+        const matchedPkg = allPackages.find(
+          (p) => p.metadata.migrationHash === migResult.value.migrationHash,
+        );
+        if (!matchedPkg) {
+          return notOk(
+            errorRuntime('Migration package not found', {
+              why: `Resolved migration "${migResult.value.dirName}" but the package was not loaded`,
+              fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
+            }),
+          );
+        }
+        appPkg = matchedPkg;
+      }
+      return ok({
+        ok: true,
+        spaces: [pkgToSpaceResult(APP_SPACE_ID, appPkg, client)],
+      });
+    } catch (error) {
+      if (MigrationToolsError.is(error)) {
+        return notOk(mapMigrationToolsError(error));
+      }
+      return notOk(
+        errorUnexpected(error instanceof Error ? error.message : String(error), {
+          why: `Failed to read app-space migration: ${error instanceof Error ? error.message : String(error)}`,
+        }),
+      );
+    }
+  }
+
+  // No-target path. Enumerate the latest migration per space (app +
+  // extensions). The aggregate-loader is needed here because we need to
+  // know which extension spaces are declared; its layout-integrity check
+  // is appropriate at this entry point because the user is asking the
+  // system to report on every loaded space.
   let contractJsonContent: string;
   try {
     contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
@@ -281,93 +370,71 @@ async function executeMigrationShowCommand(
     );
   }
 
+  // Construct the family instance up-front so the on-disk app contract
+  // read crosses the serializer seam (`familyInstance.deserializeContract`)
+  // at the read site. See TML-2536.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
   let appContract: Contract;
   try {
-    appContract = JSON.parse(contractJsonContent) as Contract;
+    appContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
   } catch (error) {
     return notOk(
       errorContractValidationFailed(
-        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        `Contract at ${contractPathAbsolute} failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
         { where: { path: contractPathAbsolute } },
       ),
     );
   }
 
-  // Build the aggregate against current disk state to enumerate all spaces.
-  const stack = createControlStack(config);
-  const familyInstance = config.family.create(stack);
   const aggregateResult = await buildContractSpaceAggregate({
     targetId: config.target.targetId,
     migrationsDir,
     appContract,
     extensionPacks: config.extensionPacks ?? [],
-    validateContract: (json: unknown) => familyInstance.validateContract(json),
+    deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
   });
   if (!aggregateResult.ok) {
     return notOk(aggregateResult.failure);
   }
   const aggregate = aggregateResult.value;
 
-  // `migration show` is an offline command; the control client is constructed
-  // purely to dispatch the family-specific `toOperationPreview` capability and
-  // is not connected to a database.
-  const client = createControlClient({
-    family: config.family,
-    target: config.target,
-    adapter: config.adapter,
-    ...ifDefined('driver', config.driver),
-    extensionPacks: config.extensionPacks ?? [],
-  });
-
   const spaces: MigrationShowSpaceResult[] = [];
 
-  // App space: honour the `target` argument (path or hash prefix) when provided.
+  // App space: latest leaf.
   try {
-    let appPkg: OnDiskMigrationPackage;
-    if (target && looksLikePath(target)) {
-      const resolved = resolveAppTargetPath(target, appMigrationsDir, appMigrationsRelative);
-      if (!resolved.ok) return resolved;
-      appPkg = await readMigrationPackage(resolved.value);
-    } else {
-      const allPackages = await readMigrationsDir(appMigrationsDir);
-      if (allPackages.length === 0) {
-        return notOk(
-          errorRuntime('No migrations found', {
-            why: `No migration packages found in ${appMigrationsRelative}`,
-            fix: 'Run `prisma-next migration plan` to create a migration first.',
-          }),
-        );
-      }
-      if (target) {
-        const resolved = resolveByHashPrefix(allPackages, target);
-        if (!resolved.ok) return resolved;
-        appPkg = resolved.value;
-      } else {
-        const graph = reconstructGraph(allPackages);
-        const latestMigration = findLatestMigration(graph);
-        if (!latestMigration) {
-          return notOk(
-            errorRuntime('Could not resolve latest migration', {
-              why: 'No latest migration found in the migration history',
-              fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
-            }),
-          );
-        }
-        const leafPkg = allPackages.find(
-          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
-        );
-        if (!leafPkg) {
-          return notOk(
-            errorRuntime('Could not resolve latest migration', {
-              why: `Latest migration ${latestMigration.dirName} does not match any package`,
-              fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
-            }),
-          );
-        }
-        appPkg = leafPkg;
-      }
+    const allPackages = await readMigrationsDir(appMigrationsDir);
+    if (allPackages.length === 0) {
+      return notOk(
+        errorRuntime('No migrations found', {
+          why: `No migration packages found in ${appMigrationsRelative}`,
+          fix: 'Run `prisma-next migration plan` to create a migration first.',
+        }),
+      );
+    }
+    const graph = reconstructGraph(allPackages);
+    const latestMigration = findLatestMigration(graph);
+    if (!latestMigration) {
+      return notOk(
+        errorRuntime('Could not resolve latest migration', {
+          why: 'No latest migration found in the migration history',
+          fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
+        }),
+      );
     }
-    spaces.push(pkgToSpaceResult(aggregate.app.spaceId, appPkg, client));
+    const leafPkg = allPackages.find(
+      (p) => p.metadata.migrationHash === latestMigration.migrationHash,
+    );
+    if (!leafPkg) {
+      return notOk(
+        errorRuntime('Could not resolve latest migration', {
+          why: `Latest migration ${latestMigration.dirName} does not match any package`,
+          fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
+        }),
+      );
+    }
+    spaces.push(pkgToSpaceResult(aggregate.app.spaceId, leafPkg, client));
   } catch (error) {
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
@@ -415,8 +482,17 @@ export function createMigrationShowCommand(): Command {
     'prisma-next migration show',
     'prisma-next migration show sha256:a1b2c3',
   ]);
+  setCommandSeeAlso(command, [
+    { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
+    { verb: 'migration log', oneLiner: 'Show executed migration history' },
+    { verb: 'migration list', oneLiner: 'List on-disk migrations' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+  ]);
   addGlobalOptions(command)
-    .argument('[target]', 'App-space migration path or migrationHash prefix (defaults to latest)')
+    .argument(
+      '[target]',
+      'Migration reference: directory name, hash/prefix, or path (defaults to latest)',
+    )
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string | undefined, options: MigrationShowOptions) => {
       const flags = parseGlobalFlags(options);