@prisma-next/cli 0.11.0 → 0.12.0

package/src/commands/migration-show.ts

@@ -6,16 +6,10 @@ import {
   type MigrationPlanOperation,
   type OperationPreview,
 } from '@prisma-next/framework-components/control';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
-import { readMigrationPackage, readMigrationsDir } from '@prisma-next/migration-tools/io';
-import {
-  findLatestMigration,
-  reconstructGraph,
-} from '@prisma-next/migration-tools/migration-graph';
+import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
 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 { castAs } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -28,7 +22,6 @@ import {
   errorFileNotFound,
   errorRuntime,
   errorUnexpected,
-  mapMigrationToolsError,
   mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
@@ -39,7 +32,6 @@ import {
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
-import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatMigrationShowOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -51,11 +43,7 @@ interface MigrationShowOptions extends CommonCommandOptions {
   readonly config?: string;
 }
 
-/**
- * Details of one space's latest (or targeted) migration package.
- */
-export interface MigrationShowSpacePresent {
-  readonly kind: 'present';
+export interface MigrationShowPresent {
   readonly spaceId: string;
   readonly dirName: string;
   readonly dirPath: string;
@@ -68,56 +56,19 @@ export interface MigrationShowSpacePresent {
     readonly label: string;
     readonly operationClass: string;
   }[];
-  /**
-   * Family-agnostic textual preview of the migration's operations. Always
-   * defined; statements is empty for a no-op migration or a family that does
-   * not implement the `OperationPreviewCapable` capability.
-   */
   readonly preview: OperationPreview;
   readonly summary: string;
 }
 
-/**
- * Placeholder for a loaded contract space that has no on-disk migration
- * package — the extension descriptor declared the space but no migrations
- * directory has been materialised for it yet. Surfaces the space in the
- * response so JSON consumers see every loaded extension instead of having
- * silently-skipped entries.
- */
-export interface MigrationShowSpaceMissing {
-  readonly kind: 'missing';
-  readonly spaceId: string;
-  readonly summary: string;
-}
-
-export type MigrationShowSpaceResult = MigrationShowSpacePresent | MigrationShowSpaceMissing;
-
 export interface MigrationShowResult {
   readonly ok: true;
-  /**
-   * Per-space results, ordered: app first, then extensions alphabetically
-   * (matching the aggregate's canonical ordering).
-   */
-  readonly spaces: readonly MigrationShowSpaceResult[];
+  readonly migration: MigrationShowPresent;
 }
 
 function looksLikePath(target: string): boolean {
   return target.includes('/') || target.includes('\\');
 }
 
-/**
- * Validate that a path-like `migration show` target resolves inside the app
- * migrations directory. The returned result is always emitted under
- * `aggregate.app.spaceId`, so accepting an extension-space (or otherwise
- * external) path here would silently mislabel the result. Returns the
- * resolved absolute path on success.
- *
- * `pathe.relative` can return an absolute path when the target cannot be
- * expressed relative to the base (e.g. on Windows when `target` is on a
- * different drive than `appMigrationsDir`). That case does not start with
- * `..`, so the absolute-check below is required to reject cross-drive
- * targets rather than mislabeling them as app-space.
- */
 export function resolveAppTargetPath(
   target: string,
   appMigrationsDir: string,
@@ -141,83 +92,14 @@ export function resolveAppTargetPath(
   return ok(targetPath);
 }
 
-export function resolveByHashPrefix(
-  packages: readonly OnDiskMigrationPackage[],
-  prefix: string,
-): Result<OnDiskMigrationPackage, CliStructuredError> {
-  const normalizedPrefix = prefix.startsWith('sha256:') ? prefix : `sha256:${prefix}`;
-  const matches = packages.filter((p) => p.metadata.migrationHash.startsWith(normalizedPrefix));
-
-  if (matches.length === 1) {
-    return ok(matches[0]!);
-  }
-
-  if (matches.length === 0) {
-    return notOk(
-      errorRuntime('No migration found matching prefix', {
-        why: `No migration has a migrationHash starting with "${normalizedPrefix}"`,
-        fix: 'Run `prisma-next migration show` (no argument) to see the latest migration, or check the migrations directory for available packages.',
-      }),
-    );
-  }
-
-  const candidates = matches.map((p) => `  ${p.dirName}  ${p.metadata.migrationHash}`).join('\n');
-  return notOk(
-    errorRuntime('Ambiguous hash prefix', {
-      why: `Multiple migrations match prefix "${normalizedPrefix}":\n${candidates}`,
-      fix: 'Provide a longer prefix to uniquely identify the migration.',
-    }),
-  );
-}
-
-/**
- * Resolve the latest migration from a space directory.
- *
- * Returns `ok(null)` only when the directory is empty or absent (ENOENT is
- * absorbed by `readMigrationsDir`). If `readMigrationsDir` returned packages
- * but `findLatestMigration` cannot pick a leaf, the on-disk history is
- * corrupt — return a runtime error rather than collapsing it to a `missing`
- * placeholder, which would hide the corruption from the caller.
- */
-export async function resolveLatestFromDir(
-  spaceDir: string,
-): Promise<Result<OnDiskMigrationPackage | null, CliStructuredError>> {
-  try {
-    const allPackages = await readMigrationsDir(spaceDir);
-    if (allPackages.length === 0) return ok(null);
-    const graph = reconstructGraph(allPackages);
-    const latestMigration = findLatestMigration(graph);
-    if (!latestMigration) {
-      return notOk(
-        errorRuntime('Could not resolve latest migration', {
-          why: `No latest migration found in ${relative(process.cwd(), spaceDir)}`,
-          fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
-        }),
-      );
-    }
-    const leafPkg = allPackages.find(
-      (p) => p.metadata.migrationHash === latestMigration.migrationHash,
-    );
-    return ok(leafPkg ?? null);
-  } catch (error) {
-    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
-  }
-}
-
-function pkgToSpaceResult(
+function pkgToPresent(
   spaceId: string,
   pkg: OnDiskMigrationPackage,
   client: ReturnType<typeof createControlClient>,
-): MigrationShowSpacePresent {
-  const ops = pkg.ops as readonly MigrationPlanOperation[];
+): MigrationShowPresent {
+  const ops = castAs<readonly MigrationPlanOperation[]>(pkg.ops);
   const preview: OperationPreview = client.toOperationPreview(ops) ?? { statements: [] };
   return {
-    kind: 'present',
     spaceId,
     dirName: pkg.dirName,
     dirPath: relative(process.cwd(), pkg.dirPath),
@@ -235,40 +117,42 @@ function pkgToSpaceResult(
   };
 }
 
+function findPackageByDirPath(
+  packages: readonly OnDiskMigrationPackage[],
+  resolvedDirPath: string,
+): OnDiskMigrationPackage | undefined {
+  const normalized = resolve(resolvedDirPath);
+  return packages.find((p) => resolve(p.dirPath) === normalized);
+}
+
 async function executeMigrationShowCommand(
-  target: string | undefined,
+  target: string,
   options: MigrationShowOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationShowResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative } =
     resolveMigrationPaths(options.config, config);
 
   const contractPathAbsolute = resolveContractPath(config);
   const contractPath = relative(process.cwd(), contractPathAbsolute);
 
   if (!flags.json && !flags.quiet) {
-    const details: Array<{ label: string; value: string }> = [
-      { label: 'config', value: configPath },
-      { label: 'contract', value: contractPath },
-      { label: 'migrations', value: appMigrationsRelative },
-    ];
-    if (target) {
-      details.push({ label: 'target', value: target });
-    }
     const header = formatStyledHeader({
       command: 'migration show',
       description: 'Display migration package contents',
-      details,
+      details: [
+        { label: 'config', value: configPath },
+        { label: 'contract', value: contractPath },
+        { label: 'migrations', value: appMigrationsRelative },
+        { label: 'target', value: target },
+      ],
       flags,
     });
     ui.stderr(header);
   }
 
-  // `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,
@@ -277,85 +161,11 @@ async function executeMigrationShowCommand(
     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');
   } catch (error) {
-    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+    if (error instanceof Error && (error as NodeJS.ErrnoException).code === 'ENOENT') {
       return notOk(
         errorFileNotFound(contractPathAbsolute, {
           why: `Contract file not found at ${contractPathAbsolute}`,
@@ -370,15 +180,14 @@ 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 = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
+    appContract = familyInstance.deserializeContract(
+      castAs<unknown>(JSON.parse(contractJsonContent)),
+    );
   } catch (error) {
     return notOk(
       errorContractValidationFailed(
@@ -388,85 +197,61 @@ async function executeMigrationShowCommand(
     );
   }
 
-  const aggregateResult = await buildContractSpaceAggregate({
-    targetId: config.target.targetId,
+  const aggregate = await loadContractSpaceAggregate({
     migrationsDir,
     appContract,
-    extensionPacks: config.extensionPacks ?? [],
     deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
   });
-  if (!aggregateResult.ok) {
-    return notOk(aggregateResult.failure);
-  }
-  const aggregate = aggregateResult.value;
 
-  const spaces: MigrationShowSpaceResult[] = [];
+  const packages = aggregate.app.packages;
+  const graph = aggregate.app.graph();
+  const refs = aggregate.app.refs;
 
-  // App space: latest leaf.
-  try {
-    const allPackages = await readMigrationsDir(appMigrationsDir);
-    if (allPackages.length === 0) {
+  let appPkg: OnDiskMigrationPackage;
+  if (looksLikePath(target)) {
+    const resolved = resolveAppTargetPath(target, appMigrationsDir, appMigrationsRelative);
+    if (!resolved.ok) return resolved;
+    const matched = findPackageByDirPath(packages, resolved.value);
+    if (!matched) {
       return notOk(
-        errorRuntime('No migrations found', {
-          why: `No migration packages found in ${appMigrationsRelative}`,
-          fix: 'Run `prisma-next migration plan` to create a migration first.',
+        errorRuntime('Migration package not found', {
+          why: `No loaded migration package at ${relative(process.cwd(), resolved.value)}`,
+          fix: 'Pass a directory name, hash prefix, or path to an on-disk app-space migration package.',
         }),
       );
     }
-    const graph = reconstructGraph(allPackages);
-    const latestMigration = findLatestMigration(graph);
-    if (!latestMigration) {
+    appPkg = matched;
+  } else {
+    if (packages.length === 0) {
       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.',
+        errorRuntime('No migrations found', {
+          why: `No migration packages found in ${appMigrationsRelative}`,
+          fix: 'Run `prisma-next migration plan` to create a migration first.',
         }),
       );
     }
-    const leafPkg = allPackages.find(
-      (p) => p.metadata.migrationHash === latestMigration.migrationHash,
+    const migResult = parseMigrationRef(target, { graph, refs });
+    if (!migResult.ok) {
+      return notOk(mapRefResolutionError(migResult.failure));
+    }
+    const matchedPkg = packages.find(
+      (p) => p.metadata.migrationHash === migResult.value.migrationHash,
     );
-    if (!leafPkg) {
+    if (!matchedPkg) {
       return notOk(
-        errorRuntime('Could not resolve latest migration', {
-          why: `Latest migration ${latestMigration.dirName} does not match any package`,
+        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.',
         }),
       );
     }
-    spaces.push(pkgToSpaceResult(aggregate.app.spaceId, leafPkg, 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)}`,
-      }),
-    );
-  }
-
-  // Extension spaces: always emit one entry per loaded extension so the
-  // response enumerates every space the aggregate knows about. Spaces
-  // with no on-disk migration package yet (e.g. an extension was declared
-  // but never `migrate`d) become `kind: 'missing'` placeholders instead
-  // of being silently skipped.
-  for (const ext of aggregate.extensions) {
-    const extSpaceDir = spaceMigrationDirectory(migrationsDir, ext.spaceId);
-    const extPkgResult = await resolveLatestFromDir(extSpaceDir);
-    if (!extPkgResult.ok) return extPkgResult;
-    if (extPkgResult.value !== null) {
-      spaces.push(pkgToSpaceResult(ext.spaceId, extPkgResult.value, client));
-    } else {
-      spaces.push({
-        kind: 'missing',
-        spaceId: ext.spaceId,
-        summary: 'No on-disk migration package for this space',
-      });
-    }
+    appPkg = matchedPkg;
   }
 
-  return ok({ ok: true, spaces });
+  return ok({
+    ok: true,
+    migration: pkgToPresent(APP_SPACE_ID, appPkg, client),
+  });
 }
 
 export function createMigrationShowCommand(): Command {
@@ -474,12 +259,11 @@ export function createMigrationShowCommand(): Command {
   setCommandDescriptions(
     command,
     'Display migration package contents',
-    'Shows the operations, statement preview, and metadata for every loaded contract\n' +
-      'space (app + extensions). Accepts a directory path or hash prefix to target a\n' +
-      'specific app-space migration; defaults to the latest per space.',
+    'Shows the operations, statement preview, and metadata for one app-space migration.\n' +
+      'Accepts a directory path, directory name, or hash prefix.',
   );
   setCommandExamples(command, [
-    'prisma-next migration show',
+    'prisma-next migration show 20260101_100000_add_user',
     'prisma-next migration show sha256:a1b2c3',
   ]);
   setCommandSeeAlso(command, [
@@ -489,12 +273,9 @@ export function createMigrationShowCommand(): Command {
     { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
   ]);
   addGlobalOptions(command)
-    .argument(
-      '[target]',
-      'Migration reference: directory name, hash/prefix, or path (defaults to latest)',
-    )
+    .argument('<target>', 'Migration reference: directory name, hash/prefix, or path')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .action(async (target: string | undefined, options: MigrationShowOptions) => {
+    .action(async (target: string, options: MigrationShowOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
 
       const ui = createTerminalUI(flags);