@prisma-next/cli 0.5.0-dev.9 → 0.5.1

package/src/commands/migration-apply.ts

@@ -1,35 +1,41 @@
-import { verifyMigrationBundle } from '@prisma-next/migration-tools/attestation';
-import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { findPathWithDecision } from '@prisma-next/migration-tools/dag';
+import { readFile } from 'node:fs/promises';
+import type { Contract } from '@prisma-next/contract/types';
+import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
-import type { MigrationBundle } from '@prisma-next/migration-tools/types';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
+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 { MigrationApplyFailure, MigrationApplyStep } from '../control-api/types';
+import type {
+  AggregatePerSpaceExecutionEntry,
+  MigrationApplyFailure,
+  MigrationApplyPathDecision,
+} from '../control-api/types';
 import {
   CliStructuredError,
   type CliStructuredError as CliStructuredErrorType,
+  errorContractValidationFailed,
   errorDatabaseConnectionRequired,
   errorDriverRequired,
+  errorFileNotFound,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
+  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadAllBundles,
-  type MigrationBundleSet,
+  collectDeclaredInvariants,
+  loadMigrationPackages,
   maskConnectionUrl,
-  readContractEnvelope,
+  resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   targetSupportsMigrations,
-  toPathDecisionResult,
 } from '../utils/command-helpers';
 import { formatMigrationApplyCommandOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
@@ -44,49 +50,50 @@ interface MigrationApplyCommandOptions extends CommonCommandOptions {
   readonly ref?: string;
 }
 
+/**
+ * Per-space breakdown of an apply run. The CLI command surfaces these
+ * for both the JSON shape (`appliedSpaces[]`) and the human-readable
+ * formatter (per-space block — same shape `db init` / `db update`
+ * use, M6 sub-spec § Output shape contract).
+ */
 export interface MigrationApplyResult {
   readonly ok: boolean;
+  /** Number of contract spaces that had non-zero pending operations applied. */
   readonly migrationsApplied: number;
+  /** Total contract spaces visible in the aggregate (pending + already-up-to-date). */
   readonly migrationsTotal: number;
+  /**
+   * Marker hash for the **app member** post-apply. Surfaced for
+   * back-compat with single-space callers; per-space markers live on
+   * `perSpace[].marker.storageHash`.
+   */
   readonly markerHash: string;
   readonly applied: readonly {
+    readonly spaceId: string;
     readonly dirName: string;
+    readonly migrationHash: string;
     readonly from: string;
     readonly to: string;
     readonly operationsExecuted: number;
   }[];
   readonly summary: string;
-  readonly pathDecision?: {
-    readonly fromHash: string;
-    readonly toHash: string;
-    readonly alternativeCount: number;
-    readonly tieBreakReasons: readonly string[];
-    readonly refName?: string;
-    readonly selectedPath: readonly {
-      readonly dirName: string;
-      readonly migrationId: string;
-      readonly from: string;
-      readonly to: string;
-    }[];
-  };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). Always present for the aggregate-walking
+   * apply path.
+   */
+  readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
+  /**
+   * Path-decision data for the app member. Surfaced for back-compat
+   * with single-space callers (cli-journeys invariant tests).
+   * Absent for no-op applies where the app had nothing to do.
+   */
+  readonly pathDecision?: MigrationApplyPathDecision;
   readonly timings: {
     readonly total: number;
   };
 }
 
-function mapMigrationToolsError(error: unknown): CliStructuredErrorType {
-  if (MigrationToolsError.is(error)) {
-    return errorRuntime(error.message, {
-      why: error.why,
-      fix: error.fix,
-      meta: { code: error.code, ...(error.details ?? {}) },
-    });
-  }
-  return errorUnexpected(error instanceof Error ? error.message : String(error), {
-    why: `Unexpected error during migration apply: ${error instanceof Error ? error.message : String(error)}`,
-  });
-}
-
 function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType {
   return errorRuntime(failure.summary, {
     why: failure.why ?? 'Migration runner failed',
@@ -95,16 +102,6 @@ function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType
   });
 }
 
-function packageToStep(pkg: MigrationBundle): MigrationApplyStep {
-  return {
-    dirName: pkg.dirName,
-    from: pkg.manifest.from,
-    to: pkg.manifest.to,
-    toContract: pkg.manifest.toContract,
-    operations: pkg.ops,
-  };
-}
-
 async function executeMigrationApplyCommand(
   options: MigrationApplyCommandOptions,
   flags: GlobalFlags,
@@ -112,10 +109,8 @@ async function executeMigrationApplyCommand(
   startTime: number,
 ): Promise<Result<MigrationApplyResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, migrationsRelative, refsDir } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
+    resolveMigrationPaths(options.config, config);
 
   const dbConnection = options.db ?? config.db?.connection;
   if (!dbConnection) {
@@ -143,38 +138,49 @@ async function executeMigrationApplyCommand(
     );
   }
 
-  let destinationHash: string;
-  let refName: string | undefined;
+  let refEntry: RefEntry | undefined;
+  const refName = options.ref;
 
-  if (options.ref) {
-    refName = options.ref;
+  if (refName) {
     try {
       const refs = await readRefs(refsDir);
-      destinationHash = resolveRef(refs, refName).hash;
+      refEntry = resolveRef(refs, refName);
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
       }
       throw error;
     }
-  } else {
-    try {
-      const envelope = await readContractEnvelope(config);
-      destinationHash = envelope.storageHash;
-    } catch (error) {
+  }
+
+  // Resolve and parse the contract envelope. The aggregate-walking
+  // operation needs the validated app contract to load the aggregate.
+  const contractPathAbsolute = resolveContractPath(config);
+  let contractRaw: Contract;
+  try {
+    const contractContent = await readFile(contractPathAbsolute, 'utf-8');
+    contractRaw = JSON.parse(contractContent) as Contract;
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
       return notOk(
-        errorRuntime('Current contract is unavailable', {
-          why: `Failed to read contract: ${error instanceof Error ? error.message : String(error)}`,
+        errorFileNotFound(contractPathAbsolute, {
+          why: `Contract file not found at ${contractPathAbsolute}`,
           fix: 'Run `prisma-next contract emit` to generate a valid contract.json, then retry apply.',
         }),
       );
     }
+    return notOk(
+      errorContractValidationFailed(
+        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
   }
 
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
-      { label: 'migrations', value: migrationsRelative },
+      { label: 'migrations', value: appMigrationsRelative },
     ];
     if (typeof dbConnection === 'string') {
       details.push({
@@ -195,10 +201,11 @@ async function executeMigrationApplyCommand(
     ui.stderr(header);
   }
 
-  // Read migrations and build migration chain model (offline — no DB needed)
-  let migrations: MigrationBundleSet;
+  // Load app-space migration packages — the aggregate operation
+  // needs them to hydrate the app member's graph for graph-walk.
+  let appPackages: Awaited<ReturnType<typeof loadMigrationPackages>>;
   try {
-    migrations = await loadAllBundles(migrationsDir);
+    appPackages = await loadMigrationPackages(appMigrationsDir);
   } catch (error) {
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
@@ -206,27 +213,6 @@ async function executeMigrationApplyCommand(
     throw error;
   }
 
-  // Defense in depth: re-hash every bundle and confirm the recorded
-  // `migrationId` matches the on-disk `(manifest, ops)`. Catches FS
-  // corruption, partial writes, and post-emit hand edits before we
-  // start touching the database.
-  for (const bundle of migrations.bundles) {
-    const verified = verifyMigrationBundle(bundle);
-    if (!verified.ok) {
-      return notOk(
-        errorRuntime(`Migration package is corrupt: ${bundle.dirName}`, {
-          why: `Stored migrationId "${verified.storedMigrationId}" does not match the recomputed hash "${verified.computedMigrationId}" for ${migrationsRelative}/${bundle.dirName}. The migration.json or ops.json has been edited or partially written since emit.`,
-          fix: `Re-emit the package by running \`node "${migrationsRelative}/${bundle.dirName}/migration.ts"\`, or restore the directory from version control.`,
-          meta: {
-            dirName: bundle.dirName,
-            storedMigrationId: verified.storedMigrationId,
-            computedMigrationId: verified.computedMigrationId,
-          },
-        }),
-      );
-    }
-  }
-
   const client = createControlClient({
     family: config.family,
     target: config.target,
@@ -237,134 +223,45 @@ async function executeMigrationApplyCommand(
 
   try {
     await client.connect(dbConnection);
-    const marker = await client.readMarker();
 
-    // --- No migrations on disk ---
-    if (migrations.bundles.length === 0) {
-      if (marker?.storageHash) {
-        return notOk(
-          errorRuntime('Database has state but no migrations exist', {
-            why: `The database marker hash "${marker.storageHash}" exists but no migrations were found in ${migrationsRelative}`,
-            fix: 'Ensure the migrations directory is correct. If the database was managed with `db init` or `db update`, run `prisma-next db sign` to update the marker.',
-            meta: { markerHash: marker.storageHash, migrationsDir: migrationsRelative },
-          }),
-        );
-      }
-      // Non-empty contract + no migrations = user needs to plan first.
-      if (destinationHash !== EMPTY_CONTRACT_HASH) {
+    // Pre-check unknown invariants against `(declared by app graph) ∪
+    // (already on the app marker)`. The marker side of the union
+    // catches the case where the ref carries an invariant whose
+    // declaring migration was retired (history rewritten) but whose
+    // id is recorded on the marker — surfacing UNKNOWN_INVARIANT
+    // there would be misleading because the database has already
+    // satisfied the requirement.
+    if (refEntry && refEntry.invariants.length > 0) {
+      const allMarkers = await client.readAllMarkers();
+      const appMarker = allMarkers.get('app') ?? null;
+      const declared = collectDeclaredInvariants(appPackages.graph);
+      const known = new Set<string>(declared);
+      for (const id of appMarker?.invariants ?? []) known.add(id);
+      const unknown = refEntry.invariants.filter((id) => !known.has(id));
+      if (unknown.length > 0) {
         return notOk(
-          errorRuntime('Current contract has no planned migrations', {
-            why: `No migrations were found in ${migrationsRelative}, but current contract hash is "${destinationHash}"`,
-            fix: 'Run `prisma-next migration plan` to create a migration for the current contract.',
-            meta: { destinationHash, migrationsDir: migrationsRelative },
-          }),
+          mapMigrationToolsError(
+            errorUnknownInvariant({
+              ...ifDefined('refName', refName),
+              unknown,
+              declared: [...declared].sort(),
+            }),
+          ),
         );
       }
-      // Empty contract + no migrations = nothing to do.
-      return ok({
-        ok: true,
-        migrationsApplied: 0,
-        migrationsTotal: 0,
-        markerHash: EMPTY_CONTRACT_HASH,
-        applied: [],
-        summary: 'No migrations found',
-        timings: { total: Date.now() - startTime },
-      });
-    }
-
-    // --- Validate marker state ---
-
-    // The empty sentinel should never appear in a real marker row — if it does,
-    // the marker was corrupted and replaying all migrations would be dangerous.
-    if (marker?.storageHash === EMPTY_CONTRACT_HASH) {
-      return notOk(
-        errorRuntime('Database marker contains the empty sentinel hash', {
-          why: `The marker row exists but contains the empty sentinel value "${EMPTY_CONTRACT_HASH}". This should never happen — the marker should contain the hash of the last applied contract.`,
-          fix: 'The marker is corrupted. Run `prisma-next db sign` to overwrite it with the correct contract hash, or drop and recreate the database.',
-          meta: { markerHash: EMPTY_CONTRACT_HASH },
-        }),
-      );
-    }
-
-    const markerHash = marker?.storageHash;
-
-    if (markerHash !== undefined && !migrations.graph.nodes.has(markerHash)) {
-      return notOk(
-        errorRuntime('Database marker does not match any known migration', {
-          why: `The database marker hash "${markerHash}" is not found in the migration history at ${migrationsRelative}`,
-          fix: 'Ensure the migrations directory matches this database. If the database was managed with `db init` or `db update`, run `prisma-next db sign` to update the marker.',
-          meta: { markerHash, knownNodes: [...migrations.graph.nodes] },
-        }),
-      );
-    }
-
-    if (!migrations.graph.nodes.has(destinationHash)) {
-      return notOk(
-        errorRuntime('Current contract has no planned migration path', {
-          why: `Current contract hash "${destinationHash}" is not present in the migration history at ${migrationsRelative}`,
-          fix: 'Run `prisma-next migration plan` to create a migration for the current contract, then re-run apply.',
-          meta: { destinationHash, knownNodes: [...migrations.graph.nodes] },
-        }),
-      );
-    }
-
-    // --- Resolve path and apply ---
-
-    // "No marker" means the database is fresh — start from the empty contract hash.
-    const originHash = markerHash ?? EMPTY_CONTRACT_HASH;
-
-    const decision = findPathWithDecision(migrations.graph, originHash, destinationHash, refName);
-    if (!decision) {
-      return notOk(
-        errorRuntime('No migration path from current state to target', {
-          why: `Cannot find a path from "${originHash}" to target "${destinationHash}"`,
-          fix: 'Check the migration history for gaps or inconsistencies.',
-          meta: { markerHash: originHash, destinationHash },
-        }),
-      );
-    }
-
-    const pendingPath = decision.selectedPath;
-    const pathDecision = toPathDecisionResult(decision);
-
-    if (pendingPath.length === 0) {
-      return ok({
-        ok: true,
-        migrationsApplied: 0,
-        migrationsTotal: 0,
-        markerHash: originHash,
-        applied: [],
-        summary: 'Already up to date',
-        pathDecision,
-        timings: { total: Date.now() - startTime },
-      });
-    }
-
-    const bundleByDir = new Map(migrations.bundles.map((b) => [b.dirName, b]));
-    const pendingMigrations: MigrationApplyStep[] = [];
-    for (const migration of pendingPath) {
-      const pkg = bundleByDir.get(migration.dirName);
-      if (!pkg) {
-        return notOk(
-          errorRuntime(`Migration package not found: ${migration.dirName}`, {
-            why: `The migration directory for path segment ${migration.from} → ${migration.to} was not found`,
-            fix: 'Ensure all migration directories are present and intact.',
-          }),
-        );
-      }
-      pendingMigrations.push(packageToStep(pkg));
     }
 
     if (!flags.quiet && !flags.json) {
-      for (const migration of pendingMigrations) {
-        ui.step(`Pending ${migration.dirName}`);
-      }
+      ui.step('Loading contract spaces…');
     }
 
     const applyResult = await client.migrationApply({
-      originHash,
-      destinationHash,
-      pendingMigrations,
+      contract: contractRaw,
+      migrationsDir,
+      appMigrationPackages: appPackages.bundles,
+      ...ifDefined('refHash', refEntry?.hash),
+      ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
+      ...(refEntry !== undefined ? ifDefined('refName', refName) : {}),
     });
 
     if (!applyResult.ok) {
@@ -376,17 +273,21 @@ async function executeMigrationApplyCommand(
     return ok({
       ok: true,
       migrationsApplied: value.migrationsApplied,
-      migrationsTotal: pendingPath.length,
+      migrationsTotal: value.perSpace.length,
       markerHash: value.markerHash,
       applied: value.applied,
       summary: value.summary,
-      pathDecision,
+      perSpace: value.perSpace,
+      ...ifDefined('pathDecision', value.pathDecision),
       timings: { total: Date.now() - startTime },
     });
   } catch (error) {
     if (CliStructuredError.is(error)) {
       return notOk(error);
     }
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
         why: `Unexpected error during migration apply: ${error instanceof Error ? error.message : String(error)}`,
@@ -402,16 +303,17 @@ export function createMigrationApplyCommand(): Command {
   setCommandDescriptions(
     command,
     'Apply planned migrations to the database',
-    'Applies previously planned migrations (created by `migration plan`) to a live database.\n' +
-      'Compares the database marker against the migration history to determine which\n' +
-      'migrations are pending, then executes them sequentially. Each migration runs\n' +
-      'in its own transaction. Does not plan new migrations — run `migration plan` first.',
+    'Walks every contract space (app + extensions) and applies pending\n' +
+      'on-disk migrations in canonical order (extensions alphabetically,\n' +
+      'then app). Graph-walks the on-disk migration graph for every space —\n' +
+      "no introspection, no synth. Each space's marker advances inside its\n" +
+      "transaction; per-space failure rolls back every space's writes.",
   );
   setCommandExamples(command, ['prisma-next migration apply --db $DATABASE_URL']);
   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('--ref <name>', 'App-space target ref name from migrations/app/refs/')
     .action(async (options: MigrationApplyCommandOptions) => {
       const flags = parseGlobalFlags(options);
       const startTime = Date.now();