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

package/src/commands/migrate.ts

@@ -2,13 +2,12 @@ import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { createControlStack } from '@prisma-next/framework-components/control';
 import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { findLatestMigration, isGraphNode } from '@prisma-next/migration-tools/migration-graph';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } 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 { Command } from 'commander';
-
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import type {
@@ -23,6 +22,8 @@ import {
   errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorFileNotFound,
+  errorMarkerMismatch,
+  errorPathUnreachable,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -32,7 +33,6 @@ import {
 import {
   addGlobalOptions,
   collectDeclaredInvariants,
-  loadMigrationPackages,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
@@ -40,10 +40,17 @@ import {
   setCommandExamples,
   targetSupportsMigrations,
 } from '../utils/command-helpers';
+import { mapContractAtError } from '../utils/contract-at-errors';
+import {
+  loadContractSpaceAggregateForCli,
+  refuseContractSpaceIntegrity,
+} from '../utils/contract-space-aggregate-loader';
+import { toDeclaredExtensionsFromRaw } from '../utils/extension-pack-inputs';
 import { formatMigrationApplyCommandOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { executeRefAdvancement, readContractIR } from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
@@ -51,6 +58,7 @@ interface MigrateCommandOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
   readonly to?: string;
+  readonly advanceRef?: string;
 }
 
 export interface MigrateResult {
@@ -72,9 +80,13 @@ export interface MigrateResult {
   readonly timings: {
     readonly total: number;
   };
+  readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
 }
 
 function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType {
+  if (failure.code === 'MIGRATION_PATH_NOT_FOUND') {
+    return errorPathUnreachable(failure);
+  }
   return errorRuntime(failure.summary, {
     why: failure.why ?? 'Migration runner failed',
     fix: 'Fix the issue and re-run `prisma-next migrate --to <contract>` — previously applied migrations are preserved.',
@@ -89,8 +101,10 @@ async function executeMigrateCommand(
   startTime: number,
 ): Promise<Result<MigrateResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
-    resolveMigrationPaths(options.config, config);
+  const { configPath, migrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
 
   const dbConnection = options.db ?? config.db?.connection;
   if (!dbConnection) {
@@ -118,31 +132,8 @@ async function executeMigrateCommand(
     );
   }
 
-  let refEntry: RefEntry | undefined;
   const toArg = options.to;
 
-  if (toArg) {
-    try {
-      const refs = await readRefs(refsDir);
-      const { graph } = await loadMigrationPackages(appMigrationsDir);
-      const refResult = parseContractRef(toArg, { graph, refs });
-      if (!refResult.ok) {
-        return notOk(mapRefResolutionError(refResult.failure));
-      }
-      if (refResult.value.provenance.kind === 'ref') {
-        const resolved = refs[refResult.value.provenance.refName];
-        if (resolved) refEntry = resolved;
-      } else {
-        refEntry = { hash: refResult.value.hash, invariants: [] };
-      }
-    } catch (error) {
-      if (MigrationToolsError.is(error)) {
-        return notOk(mapMigrationToolsError(error));
-      }
-      throw error;
-    }
-  }
-
   // Construct the family instance up-front so the on-disk contract read
   // crosses the serializer seam (`familyInstance.deserializeContract`) at
   // the read site. The downstream `client.migrationApply({ contract })`
@@ -184,6 +175,44 @@ async function executeMigrateCommand(
     );
   }
 
+  const loadedAggregate = await loadContractSpaceAggregateForCli({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: contractRaw,
+    extensionPacks: config.extensionPacks ?? [],
+    deserializeContract: (json) => familyInstance.deserializeContract(json),
+  });
+  if (!loadedAggregate.ok) {
+    return notOk(loadedAggregate.failure);
+  }
+  const aggregate = loadedAggregate.value;
+  const integrityFailure = refuseContractSpaceIntegrity(aggregate, {
+    declaredExtensions: toDeclaredExtensionsFromRaw(
+      (config.extensionPacks ?? []) as ReadonlyArray<unknown>,
+    ),
+    checkContracts: true,
+  });
+  if (integrityFailure) {
+    return notOk(integrityFailure);
+  }
+
+  let refEntry: RefEntry | undefined;
+  let refName: string | undefined;
+  if (toArg) {
+    const refs = aggregate.app.refs;
+    const refResult = parseContractRef(toArg, { graph: aggregate.app.graph(), refs });
+    if (!refResult.ok) {
+      return notOk(mapRefResolutionError(refResult.failure));
+    }
+    if (refResult.value.provenance.kind === 'ref') {
+      refName = refResult.value.provenance.refName;
+      const resolved = refs[refName];
+      if (resolved) refEntry = resolved;
+    } else {
+      refEntry = { hash: refResult.value.hash, invariants: [] };
+    }
+  }
+
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
@@ -208,15 +237,7 @@ async function executeMigrateCommand(
     ui.stderr(header);
   }
 
-  let appPackages: Awaited<ReturnType<typeof loadMigrationPackages>>;
-  try {
-    appPackages = await loadMigrationPackages(appMigrationsDir);
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      return notOk(mapMigrationToolsError(error));
-    }
-    throw error;
-  }
+  const appGraph = aggregate.app.graph();
 
   const client = createControlClient({
     family: config.family,
@@ -229,10 +250,21 @@ async function executeMigrateCommand(
   try {
     await client.connect(dbConnection);
 
+    const allMarkers = await client.readAllMarkers();
+    const appMarker = allMarkers.get('app') ?? null;
+
+    if (appMarker !== null && !isGraphNode(appMarker.storageHash, appGraph)) {
+      return notOk(
+        errorMarkerMismatch(
+          appMarker.storageHash,
+          [...appGraph.nodes].sort(),
+          findLatestMigration(appGraph)?.to ?? null,
+        ),
+      );
+    }
+
     if (refEntry && refEntry.invariants.length > 0) {
-      const allMarkers = await client.readAllMarkers();
-      const appMarker = allMarkers.get('app') ?? null;
-      const declared = collectDeclaredInvariants(appPackages.graph);
+      const declared = collectDeclaredInvariants(appGraph);
       const known = new Set<string>(declared);
       for (const id of appMarker?.invariants ?? []) known.add(id);
       const unknown = refEntry.invariants.filter((id) => !known.has(id));
@@ -253,10 +285,36 @@ async function executeMigrateCommand(
       ui.step('Loading contract spaces…');
     }
 
+    // When `--to` resolves to an on-disk graph node with a matching bundle,
+    // verify and apply against THAT bundle's destination contract via
+    // `contractAt` — not the emitted `contract.json`. With `--to` omitted,
+    // or a target with no matching bundle, the emitted contract stays the
+    // apply contract (the only migrate-specific default). The same
+    // `contractAt` artifacts feed the optional ref-advancement snapshot.
+    let applyContract: Contract = contractRaw;
+    let snapshotContractJson: Record<string, unknown> = JSON.parse(contractContent);
+    let snapshotContractDts: string | undefined;
+    if (toArg && refEntry) {
+      const targetHash = refEntry.hash;
+      const matchingBundle = aggregate.app.packages.find((p) => p.metadata.to === targetHash);
+      if (matchingBundle) {
+        try {
+          const at = await aggregate.app.contractAt(
+            targetHash,
+            refName !== undefined ? { refName } : undefined,
+          );
+          applyContract = at.contract;
+          snapshotContractJson = at.contractJson as Record<string, unknown>;
+          snapshotContractDts = at.contractDts;
+        } catch (error) {
+          return mapContractAtError(error, { artifactRole: 'to' });
+        }
+      }
+    }
+
     const applyResult = await client.migrationApply({
-      contract: contractRaw,
+      contract: applyContract,
       migrationsDir,
-      appMigrationPackages: appPackages.bundles,
       ...ifDefined('refHash', refEntry?.hash),
       ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
       ...(refEntry !== undefined ? ifDefined('refName', toArg) : {}),
@@ -268,6 +326,27 @@ async function executeMigrateCommand(
 
     const { value } = applyResult;
 
+    let advancedRef: { name: string; hash: string } | null = null;
+    if (options.advanceRef !== undefined) {
+      try {
+        const contractIR =
+          snapshotContractDts !== undefined
+            ? { contract: snapshotContractJson, contractDts: snapshotContractDts }
+            : await readContractIR(snapshotContractJson, contractPathAbsolute);
+        advancedRef = await executeRefAdvancement(
+          refsDir,
+          options.advanceRef,
+          value.markerHash,
+          contractIR,
+        );
+      } catch (error) {
+        if (MigrationToolsError.is(error)) {
+          return notOk(mapMigrationToolsError(error));
+        }
+        throw error;
+      }
+    }
+
     return ok({
       ok: true,
       migrationsApplied: value.migrationsApplied,
@@ -278,6 +357,7 @@ async function executeMigrateCommand(
       perSpace: value.perSpace,
       ...ifDefined('pathDecision', value.pathDecision),
       timings: { total: Date.now() - startTime },
+      advancedRef,
     });
   } catch (error) {
     if (CliStructuredError.is(error)) {
@@ -318,6 +398,7 @@ export function createMigrateCommand(): Command {
       '--to <contract>',
       'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
+    .option('--advance-ref <name>', 'Advance the named ref to the post-apply marker after success')
     .action(async (options: MigrateCommandOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();

package/src/commands/migration-check.ts

@@ -1,6 +1,11 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { readFile } from 'node:fs/promises';
+import { createControlStack } from '@prisma-next/framework-components/control';
+import type { IntegrityViolation } from '@prisma-next/migration-tools/aggregate';
+import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
 import { verifyMigrationHash } from '@prisma-next/migration-tools/hash';
+import { readMigrationsDir } from '@prisma-next/migration-tools/io';
+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';
@@ -9,15 +14,20 @@ import { join, relative } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
+  resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
+import { toDeclaredExtensionsFromRaw } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import {
+  type CheckFailure,
+  integrityViolationToCheckFailure,
+} from '../utils/integrity-violation-to-check-failure';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 import { INTEGRITY_FAILED, OK, PRECONDITION } from './migration-check/exit-codes';
 
@@ -25,12 +35,7 @@ interface MigrationCheckOptions extends CommonCommandOptions {
   readonly config?: string;
 }
 
-export interface CheckFailure {
-  readonly pnCode: string;
-  readonly where: string;
-  readonly why: string;
-  readonly fix: string;
-}
+export type { CheckFailure } from '../utils/integrity-violation-to-check-failure';
 
 export interface MigrationCheckResult {
   readonly ok: boolean;
@@ -38,11 +43,6 @@ export interface MigrationCheckResult {
   readonly summary: string;
 }
 
-/**
- * Canonical user-facing locator for a check failure: the cwd-relative path
- * to the migration package directory. Surfacing the same shape across every
- * PN code means `--json` consumers can branch uniformly on `where`.
- */
 function migrationPathRelative(dirPath: string): string {
   return relative(process.cwd(), dirPath);
 }
@@ -63,21 +63,6 @@ function checkFileExists(dirPath: string, dirName: string, fileName: string): Ch
   return null;
 }
 
-/**
- * Within-migration snapshot-consistency check (PN-MIG-CHECK-005).
- *
- * Compares the migration's stored `metadata.to` against the `storageHash`
- * recorded in its on-disk `end-contract.json` snapshot. The two values are
- * independent on-disk records of the same fact (the migration's destination
- * contract); drift between them indicates the package is internally
- * corrupt. Cross-migration consistency (one migration's end-contract.json
- * agreeing with the next migration's start-contract.json) is a separate
- * check that requires shadow execution and is deferred to
- * `migration preflight`.
- *
- * Shared between the graph-wide and per-migration code paths so both report
- * the same failure for the same on-disk state.
- */
 function checkSnapshotConsistency(pkg: OnDiskMigrationPackage): CheckFailure | null {
   const endContractPath = join(pkg.dirPath, 'end-contract.json');
   if (!existsSync(endContractPath)) return null;
@@ -104,6 +89,27 @@ function checkSnapshotConsistency(pkg: OnDiskMigrationPackage): CheckFailure | n
   return null;
 }
 
+async function loadAggregateIntegrityViolations(
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  migrationsDir: string,
+): Promise<readonly IntegrityViolation[]> {
+  try {
+    const contractJsonContent = await readFile(resolveContractPath(config), 'utf-8');
+    const familyInstance = config.family.create(createControlStack(config));
+    const declaredExtensions = toDeclaredExtensionsFromRaw(config.extensionPacks ?? []);
+
+    const parsedAppContract: unknown = JSON.parse(contractJsonContent);
+    const aggregate = await loadContractSpaceAggregate({
+      migrationsDir,
+      deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
+      appContract: familyInstance.deserializeContract(parsedAppContract),
+    });
+    return aggregate.checkIntegrity({ declaredExtensions, checkContracts: true });
+  } catch {
+    return [];
+  }
+}
+
 async function executeMigrationCheckCommand(
   target: string | undefined,
   options: MigrationCheckOptions,
@@ -111,10 +117,8 @@ async function executeMigrationCheckCommand(
   ui: TerminalUI,
 ): Promise<{ result: MigrationCheckResult; exitCode: number }> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
+    resolveMigrationPaths(options.config, config);
 
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
@@ -135,37 +139,9 @@ async function executeMigrationCheckCommand(
 
   const failures: CheckFailure[] = [];
 
-  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
-  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
-  try {
-    const loaded = await loadMigrationPackages(appMigrationsDir);
-    bundles = loaded.bundles;
-    graph = loaded.graph;
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      const pnCode =
-        error.code === 'MIGRATION.HASH_MISMATCH' ? 'PN-MIG-CHECK-001' : 'PN-MIG-CHECK-002';
-      // Normalise to a cwd-relative path. `error.details.dir` is absolute
-      // (the migration-tools layer doesn't know the caller's cwd); the
-      // `filePath` fallback is also absolute. Surfacing the relative form
-      // matches the rest of the command's `where` shape and keeps `--json`
-      // consumers from having to special-case the bootstrap-failure path.
-      const rawWhere =
-        (error.details?.['dir'] as string) ?? (error.details?.['filePath'] as string) ?? null;
-      const where = rawWhere ? relative(process.cwd(), rawWhere) : 'unknown';
-      failures.push({
-        pnCode,
-        where,
-        why: error.why,
-        fix: error.fix,
-      });
-      return {
-        result: { ok: false, failures, summary: `${failures.length} integrity failure(s)` },
-        exitCode: INTEGRITY_FAILED,
-      };
-    }
-    throw error;
-  }
+  const loaded = await readMigrationsDir(appMigrationsDir);
+  const bundles: readonly OnDiskMigrationPackage[] = loaded.packages;
+  const graph = reconstructGraph(bundles);
 
   if (existsSync(appMigrationsDir)) {
     const loadedDirNames = new Set(bundles.map((p) => p.dirName));
@@ -236,29 +212,9 @@ async function executeMigrationCheckCommand(
       });
     }
 
-    // PN-MIG-CHECK-005 must fire per-migration as well as graph-wide; both
-    // call sites delegate to the shared helper so the same on-disk drift
-    // produces the same failure regardless of how the user invoked check.
     const snapshotFailure = checkSnapshotConsistency(matchedPkg);
     if (snapshotFailure) failures.push(snapshotFailure);
   } else {
-    for (const pkg of bundles) {
-      for (const f of ['migration.json', 'ops.json']) {
-        const fail = checkFileExists(pkg.dirPath, pkg.dirName, f);
-        if (fail) failures.push(fail);
-      }
-
-      const verification = verifyMigrationHash(pkg);
-      if (!verification.ok) {
-        failures.push({
-          pnCode: 'PN-MIG-CHECK-001',
-          where: migrationFileRelative(pkg.dirPath, 'migration.json'),
-          why: `Stored hash ${verification.storedHash} does not match recomputed hash ${verification.computedHash}`,
-          fix: 'Re-emit the migration package or restore from version control.',
-        });
-      }
-    }
-
     for (const pkg of bundles) {
       const snapshotFailure = checkSnapshotConsistency(pkg);
       if (snapshotFailure) failures.push(snapshotFailure);
@@ -295,6 +251,10 @@ async function executeMigrationCheckCommand(
     } catch {
       // Refs unreadable — skip ref checks
     }
+
+    for (const violation of await loadAggregateIntegrityViolations(config, migrationsDir)) {
+      failures.push(integrityViolationToCheckFailure(violation, migrationsDir));
+    }
   }
 
   if (failures.length === 0) {

package/src/commands/migration-graph.ts

@@ -1,24 +1,17 @@
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
-import { readRefs } from '@prisma-next/migration-tools/refs';
-import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
-import {
-  type CliStructuredError,
-  errorUnexpected,
-  mapMigrationToolsError,
-} from '../utils/cli-errors';
+import type { CliStructuredError } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
-  readContractEnvelope,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { migrationGraphToRenderInput } from '../utils/formatters/graph-migration-mapper';
 import { graphRenderer } from '../utils/formatters/graph-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
@@ -41,13 +34,13 @@ export interface MigrationGraphResult {
   readonly summary: string;
 }
 
-async function executeMigrationGraphCommand(
+export async function executeMigrationGraphCommand(
   options: MigrationGraphOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationGraphResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+  const { configPath, appMigrationsRelative, migrationsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -65,37 +58,18 @@ async function executeMigrationGraphCommand(
     ui.stderr(header);
   }
 
-  let graph: MigrationGraph;
-  try {
-    ({ graph } = await loadMigrationPackages(appMigrationsDir));
-  } 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)}`,
-      }),
-    );
-  }
-
-  let contractHash: string | null = null;
-  try {
-    const envelope = await readContractEnvelope(config);
-    contractHash = envelope.storageHash;
-  } catch {
-    // Contract unreadable — render graph without contract marker
+  const loaded = await buildReadAggregate(config, { migrationsDir });
+  if (!loaded.ok) {
+    return loaded;
   }
 
-  let refs: readonly StatusRef[] = [];
-  try {
-    const allRefs = await readRefs(refsDir);
-    refs = Object.entries(allRefs).map(([name, entry]) => ({
-      name,
-      hash: entry.hash,
-      active: false,
-    }));
-  } catch {
-    // Refs unreadable — render graph without ref markers
-  }
+  const { aggregate, contractHash } = loaded.value;
+  const graph = aggregate.app.graph();
+  const refs: readonly StatusRef[] = Object.entries(aggregate.app.refs).map(([name, entry]) => ({
+    name,
+    hash: entry.hash,
+    active: false,
+  }));
 
   return ok({
     ok: true,