refactor(cli): promote migration plan/show to aggregate, retire drift surface (TML-2457)

packages/1-framework/3-tooling/cli/src/commands/migration-plan.ts

@@ -2,7 +2,6 @@ import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import {
-  APP_SPACE_ID,
   createControlStack,
   hasOperationPreview,
   type MigrationPlanOperation,
@@ -43,16 +42,9 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
-import { runContractSpaceExtensionMigrationsPass } from '../utils/contract-space-extension-migrations-pass';
-import {
-  formatContractSpaceDriftWarning,
-  runContractSpaceMigratePass,
-} from '../utils/contract-space-migrate-pass';
-import {
-  toExtensionInputs,
-  toExtensionMigrationsInputs,
-  toMigratePassInputs,
-} from '../utils/extension-pack-inputs';
+import { buildContractSpaceAggregate } from '../utils/contract-space-aggregate-loader';
+import { runContractSpaceSeedPhase } from '../utils/contract-space-seed-phase';
+import { toExtensionInputs } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -241,41 +233,30 @@ async function executeMigrationPlanCommand(
     );
   }
 
-  // Per-space migrate pass: drift detection + on-disk artefact emission for
-  // every loaded extension that exposes a `contractSpace`. Runs *before*
-  // the app-space no-op check so that an extension bump alone (with no
-  // structural app-space change) still re-pins extension artefacts on
-  // disk. Drift warnings are non-fatal — the on-disk artefacts are refreshed
-  // and the user is notified that the bump is being captured.
-  // Single descriptor-import boundary: every consumer of `extensionPacks`
-  // goes through `toExtensionInputs` + a per-consumer adapter. AC11.
+  // Phase 1 — seed: unconditionally re-emit per-space pinned artefacts
+  // (contract.json / contract.d.ts / refs/head.json) and materialise any
+  // descriptor-shipped migration packages not yet on disk. Runs before
+  // the no-op check so that an extension bump alone (with no structural
+  // app-space change) still re-pins extension artefacts on disk.
   const canonicalExtensionInputs = toExtensionInputs(config.extensionPacks ?? []);
-  const migratePass = await runContractSpaceMigratePass({
+  const seedResult = await runContractSpaceSeedPhase({
     migrationsDir,
-    extensionPacks: toMigratePassInputs(canonicalExtensionInputs),
+    extensionPacks: canonicalExtensionInputs,
   });
   if (!flags.json && !flags.quiet) {
-    for (const drift of migratePass.drifts) {
-      if (drift.kind === 'drift') {
-        ui.stderr(formatContractSpaceDriftWarning(drift));
+    for (const record of seedResult.seeded) {
+      if (record.action === 'updated') {
+        const pkgSuffix =
+          record.newMigrationDirs.length > 0
+            ? `; ${record.newMigrationDirs.length} new migration package(s) materialised`
+            : '';
+        ui.step(`Updated ${record.spaceId} to ${record.newHash}${pkgSuffix}`);
       }
     }
   }
-
-  // Materialise descriptor-shipped migration packages onto disk under
-  // `migrations/<spaceId>/<dirName>/` for any package not yet present.
-  // Idempotent (existing dirs are left untouched).
-  // Uses `planAllSpaces` for deterministic ordering + duplicate-spaceId
-  // detection.
-  const extensionMigrationsResult = await runContractSpaceExtensionMigrationsPass({
-    migrationsDir,
-    extensionPacks: toExtensionMigrationsInputs(canonicalExtensionInputs),
-  });
-  if (!flags.json && !flags.quiet) {
-    for (const entry of extensionMigrationsResult.emitted) {
-      ui.step(`Emitted ${entry.spaceId}/${entry.dirName}`);
-    }
-  }
+  const emittedExtensionDirs = seedResult.seeded.flatMap((r) =>
+    r.newMigrationDirs.map((dirName) => ({ spaceId: r.spaceId, dirName })),
+  );
 
   // Check for no-op (same hash means no changes)
   if (fromHash === toStorageHash) {
@@ -285,7 +266,7 @@ async function executeMigrationPlanCommand(
       from: fromHash,
       to: toStorageHash,
       operations: [],
-      emittedExtensionDirs: extensionMigrationsResult.emitted,
+      emittedExtensionDirs,
       summary: 'No changes detected between contracts',
       timings: { total: Date.now() - startTime },
     };
@@ -301,6 +282,25 @@ 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);
+  const aggregateResult = await buildContractSpaceAggregate({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: toContractJson,
+    extensionPacks: config.extensionPacks ?? [],
+    validateContract: (json: unknown) => familyInstance.validateContract(json),
+  });
+  if (!aggregateResult.ok) {
+    return notOk(aggregateResult.failure);
+  }
+  const aggregate = aggregateResult.value;
+
   const frameworkComponents = assertFrameworkComponentsCompatible(
     config.family.familyId,
     config.target.targetId,
@@ -328,17 +328,15 @@ async function executeMigrationPlanCommand(
   };
 
   try {
-    const stack = createControlStack(config);
-    const familyInstance = config.family.create(stack);
     const planner = migrations.createPlanner(familyInstance);
     const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
     const plannerResult = planner.plan({
-      contract: toContractJson,
+      contract: aggregate.app.contract,
       schema: fromSchema,
       policy: { allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] },
       fromContract,
       frameworkComponents,
-      spaceId: APP_SPACE_ID,
+      spaceId: aggregate.app.spaceId,
     });
     if (plannerResult.kind === 'failure') {
       return notOk(
@@ -421,7 +419,7 @@ async function executeMigrationPlanCommand(
         to: toStorageHash,
         dir: relative(process.cwd(), packageDir),
         operations: [],
-        emittedExtensionDirs: extensionMigrationsResult.emitted,
+        emittedExtensionDirs,
         pendingPlaceholders: true,
         summary:
           'Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit',
@@ -444,9 +442,9 @@ async function executeMigrationPlanCommand(
         label: op.label,
         operationClass: op.operationClass,
       })),
-      emittedExtensionDirs: extensionMigrationsResult.emitted,
+      emittedExtensionDirs,
       ...(preview !== undefined ? { preview } : {}),
-      summary: buildPlanSummary(plannedOps.length, extensionMigrationsResult.emitted.length),
+      summary: buildPlanSummary(plannedOps.length, emittedExtensionDirs.length),
       timings: { total: Date.now() - startTime },
     };
     return ok(result);