@prisma-next/cli 0.8.0-dev.7 → 0.8.0-dev.8

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');
@@ -293,7 +382,6 @@ async function executeMigrationShowCommand(
     );
   }
 
-  // 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({
@@ -308,66 +396,41 @@ async function executeMigrationShowCommand(
   }
   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 +478,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);

package/src/commands/migration-status.ts

@@ -19,8 +19,9 @@ import {
   findReachableLeaves,
 } from '@prisma-next/migration-tools/migration-graph';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry, Refs } from '@prisma-next/migration-tools/refs';
-import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { cyan, dim, magenta, yellow } from 'colorette';
@@ -33,6 +34,7 @@ import {
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -43,6 +45,7 @@ import {
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
+  setCommandSeeAlso,
   toPathDecisionResult,
   toStructuralEdge,
 } from '../utils/command-helpers';
@@ -70,10 +73,8 @@ import { TerminalUI } from '../utils/terminal-ui';
 interface MigrationStatusOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
-  readonly ref?: string;
-  readonly graph?: boolean;
-  readonly limit?: string;
-  readonly all?: boolean;
+  readonly to?: string;
+  readonly from?: string;
 }
 
 export interface MigrationStatusEntry {
@@ -94,7 +95,7 @@ export interface MigrationStatusEntry {
  *
  * - `headHash`: the on-disk head ref's hash (where the space is going).
  * - `markerHash`: the live marker hash for the space, or null if no
- *    marker has been written yet (greenfield, or pre-`migration apply`).
+ *    marker has been written yet (greenfield, or pre-`migrate`).
  * - `pendingCount`: number of migration edges between marker and head.
  *    Computed via {@link graphWalkStrategy}; 0 means the space is
  *    already at head.
@@ -420,23 +421,6 @@ function resolveDisplayChain(
   return toTarget;
 }
 
-const DEFAULT_LIMIT = 10;
-
-function determineLimit(opts: MigrationStatusOptions) {
-  if (opts.all) {
-    // No limit
-    return;
-  }
-  if (!opts.limit) {
-    return DEFAULT_LIMIT;
-  }
-  const parsed = Number.parseInt(opts.limit, 10);
-  if (Number.isNaN(parsed)) {
-    return DEFAULT_LIMIT;
-  }
-  return parsed;
-}
-
 /**
  * Build the aggregate enumeration of contract spaces for the status
  * output. Loads the aggregate from disk (lossy on failure — extension
@@ -581,11 +565,32 @@ async function executeMigrationStatusCommand(
     throw error;
   }
 
-  if (options.ref) {
-    activeRefName = options.ref;
+  let fromOverrideHash: string | undefined;
+
+  if (options.to || options.from) {
     try {
-      activeRefEntry = resolveRef(allRefs, activeRefName);
-      activeRefHash = activeRefEntry.hash;
+      const { graph: earlyGraph } = await loadMigrationPackages(appMigrationsDir);
+
+      if (options.to) {
+        const refResult = parseContractRef(options.to, { graph: earlyGraph, refs: allRefs });
+        if (!refResult.ok) {
+          return notOk(mapRefResolutionError(refResult.failure));
+        }
+        activeRefHash = refResult.value.hash;
+        if (refResult.value.provenance.kind === 'ref') {
+          const resolvedRefName = refResult.value.provenance.refName;
+          activeRefName = resolvedRefName;
+          activeRefEntry = allRefs[resolvedRefName];
+        }
+      }
+
+      if (options.from) {
+        const fromResult = parseContractRef(options.from, { graph: earlyGraph, refs: allRefs });
+        if (!fromResult.ok) {
+          return notOk(mapRefResolutionError(fromResult.failure));
+        }
+        fromOverrideHash = fromResult.value.hash;
+      }
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -613,6 +618,9 @@ async function executeMigrationStatusCommand(
     if (activeRefName) {
       details.push({ label: 'ref', value: activeRefName });
     }
+    if (options.from) {
+      details.push({ label: 'from', value: options.from });
+    }
     if (activeRefEntry && activeRefEntry.invariants.length > 0) {
       details.push({
         label: 'required',
@@ -696,8 +704,8 @@ async function executeMigrationStatusCommand(
         severity: 'warn',
         message: 'There are multiple valid migration paths — you must select a target',
         hints: [
-          "Use '--ref <name>' to select a target",
-          "Or 'prisma-next migration ref set <name> <hash>' to create one",
+          "Use '--to <contract>' to select a target",
+          "Or 'prisma-next ref set <name> <hash>' to create one",
         ],
       });
     }
@@ -751,6 +759,12 @@ async function executeMigrationStatusCommand(
     }
   }
 
+  if (fromOverrideHash !== undefined) {
+    markerHash = fromOverrideHash;
+    mode = 'offline';
+    allMarkers = null;
+  }
+
   // Build the aggregate enumeration of contract spaces. Lossy on
   // failure (extensions are simply omitted) so the existing
   // single-space app pipeline below still runs even if extensions
@@ -863,7 +877,7 @@ async function executeMigrationStatusCommand(
       code: 'MIGRATION.NO_MARKER',
       severity: 'warn',
       message: 'Database has not been initialized — no migration marker found',
-      hints: ["Run 'prisma-next migration apply' to apply pending migrations"],
+      hints: ["Run 'prisma-next migrate' to apply pending migrations"],
     });
   }
 
@@ -923,7 +937,7 @@ async function executeMigrationStatusCommand(
   let missingInvariants: readonly string[] | undefined;
   let effectiveRequired = new Set<string>();
   if (mode === 'online') {
-    // Mirrors `migration-apply.ts`: compute `effectiveRequired = required −
+    // Mirrors `migrate.ts`: compute `effectiveRequired = required −
     // marker.invariants` directly, then derive the display fields from it.
     // `appliedInvariants` is the intersection (`required ∩ marker`), which
     // is what JSON consumers see for the active ref; the unfiltered set
@@ -945,17 +959,17 @@ async function executeMigrationStatusCommand(
   if (mode === 'online') {
     if (markerHash !== undefined && !graph.nodes.has(markerHash) && markerHash === contractHash) {
       summary = `${bundles.length} migration(s) on disk`;
-    } else if (activeRefHash && markerHash !== undefined) {
-      const distance = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName!);
+    } else if (activeRefHash && activeRefName && markerHash !== undefined) {
+      const distance = summarizeRefDistance(graph, markerHash, activeRefHash, activeRefName);
       summary = hasInvariantWork ? `${distance} — missing invariant(s): ${missingList}` : distance;
     } else if (pendingCount === 0 && !hasInvariantWork) {
       summary = `Database is up to date (${appliedCount} migration${appliedCount !== 1 ? 's' : ''} applied)`;
     } else if (pendingCount === 0 && hasInvariantWork) {
-      summary = `Missing invariant(s): ${missingList} — run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply`;
+      summary = `Missing invariant(s): ${missingList} — run 'prisma-next migrate --to ${activeRefName ?? '<ref>'}' to apply`;
     } else if (markerHash === undefined) {
       summary = `${pendingCount} pending migration(s) — database has no marker`;
     } else {
-      summary = `${pendingCount} pending migration(s) — run 'prisma-next migration apply' to apply`;
+      summary = `${pendingCount} pending migration(s) — run 'prisma-next migrate' to apply`;
     }
   } else {
     summary = `${entries.length} migration(s) on disk`;
@@ -997,8 +1011,7 @@ async function executeMigrationStatusCommand(
       diagnostics.push({
         code: 'MIGRATION.MARKER_NOT_IN_HISTORY',
         severity: 'warn',
-        message:
-          'Database matches the current contract but was updated directly (not via migration apply)',
+        message: 'Database matches the current contract but was updated directly (not via migrate)',
         hints: ["Run 'prisma-next migration plan' to plan a migration to your current contract"],
       });
     } else if (pendingCount > 0) {
@@ -1006,7 +1019,7 @@ async function executeMigrationStatusCommand(
         code: 'MIGRATION.DATABASE_BEHIND',
         severity: 'info',
         message: `${pendingCount} migration(s) pending`,
-        hints: ["Run 'prisma-next migration apply' to apply pending migrations"],
+        hints: ["Run 'prisma-next migrate' to apply pending migrations"],
       });
     } else if (hasInvariantWork) {
       diagnostics.push({
@@ -1014,7 +1027,7 @@ async function executeMigrationStatusCommand(
         severity: 'info',
         message: `Missing required invariant(s): ${missingList}`,
         hints: [
-          `Run 'prisma-next migration apply --ref ${activeRefName ?? '<ref>'}' to apply a path that covers the required invariants`,
+          `Run 'prisma-next migrate --to ${activeRefName ?? '<ref>'}' to apply a path that covers the required invariants`,
         ],
       });
     } else if (!routingUnreachable) {
@@ -1056,37 +1069,41 @@ export function createMigrationStatusCommand(): Command {
   const command = new Command('status');
   setCommandDescriptions(
     command,
-    'Show migration history and applied status',
-    'Displays the migration history in order. When a database connection\n' +
-      'is available, shows which migrations are applied and which are pending.\n' +
-      'Without a database connection, shows the history from disk only.',
+    'Show migration path and pending status',
+    'Shows which migrations are pending between the database marker and\n' +
+      'the target contract. Requires a database connection for live status.\n' +
+      'Use `migration graph` for topology, `migration log` for history,\n' +
+      'and `migration list` for on-disk enumeration.',
   );
   setCommandExamples(command, [
-    'prisma-next migration status',
     'prisma-next migration status --db $DATABASE_URL',
+    'prisma-next migration status --to production --db $DATABASE_URL',
+  ]);
+  setCommandSeeAlso(command, [
+    { 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' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
   ]);
   addGlobalOptions(command)
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .option('--ref <name>', 'Target ref name from migrations/refs/')
-    .option('--graph', 'Show the full migration graph with all branches')
-    .option('--limit <n>', 'Maximum number of migrations to display (default: 10)')
-    .option('--all', 'Show full history (disables truncation)')
+    .option(
+      '--to <contract>',
+      'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
+    .option(
+      '--from <contract>',
+      'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
+    )
     .action(async (options: MigrationStatusOptions) => {
       const flags = parseGlobalFlags(options);
-
       const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
 
       const result = await executeMigrationStatusCommand(options, flags, ui);
 
       const exitCode = handleResult(result, flags, ui, (statusResult) => {
         if (flags.json) {
-          // Strip non-JSON-shape fields before emitting. These belong to
-          // the in-memory result so the human renderer can avoid
-          // recomputing them, but they would either bloat the wire format
-          // (graph, bundles, edgeStatuses) or expose internals
-          // (activeRefHash, activeRefName, diverged) that consumers should
-          // read off `pathDecision` / `refs` instead.
           const {
             graph: _graph,
             bundles: _bundles,
@@ -1101,7 +1118,6 @@ export function createMigrationStatusCommand(): Command {
           const colorize = flags.color !== false;
 
           if (statusResult.graph) {
-            const limit = determineLimit(options);
             const renderInput = migrationGraphToRenderInput({
               graph: statusResult.graph,
               mode: statusResult.mode,
@@ -1113,16 +1129,13 @@ export function createMigrationStatusCommand(): Command {
               edgeStatuses: statusResult.edgeStatuses,
             });
 
-            const graphToRender =
-              options.graph || statusResult.diverged
-                ? renderInput.graph
-                : extractRelevantSubgraph(renderInput.graph, renderInput.relevantPaths);
-            const dagreOptions =
-              !options.graph && isLinearGraph(graphToRender) ? { ranksep: 1 } : undefined;
+            const graphToRender = statusResult.diverged
+              ? renderInput.graph
+              : extractRelevantSubgraph(renderInput.graph, renderInput.relevantPaths);
+            const dagreOptions = isLinearGraph(graphToRender) ? { ranksep: 1 } : undefined;
             const renderOptions = {
               ...renderInput.options,
               colorize,
-              ...ifDefined('limit', limit),
               ...ifDefined('dagreOptions', dagreOptions),
             };
             const graphOutput = graphRenderer.render(graphToRender, renderOptions);
@@ -1209,7 +1222,7 @@ export function formatStatusSummary(result: MigrationStatusResult, colorize: boo
     if (total > 0) {
       lines.push('');
       lines.push(
-        `${c(yellow, '⧗')} ${total} pending migration(s) across ${result.spaces.length} space(s) — run 'prisma-next migration apply' to apply`,
+        `${c(yellow, '⧗')} ${total} pending migration(s) across ${result.spaces.length} space(s) — run 'prisma-next migrate' to apply`,
       );
     }
   }