@prisma-next/cli 0.11.0 → 0.12.0

package/src/commands/migration-status.ts

@@ -1,10 +1,14 @@
+import type { Contract } from '@prisma-next/contract/types';
 import {
   createControlStack,
   type MigrationPlanOperation,
 } from '@prisma-next/framework-components/control';
 import {
   type ContractMarkerRecordLike,
+  type ContractSpaceAggregate,
   graphWalkStrategy,
+  loadContractSpaceAggregate,
+  requireHeadRef,
 } from '@prisma-next/migration-tools/aggregate';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import {
@@ -39,7 +43,6 @@ import {
 import {
   addGlobalOptions,
   collectDeclaredInvariants,
-  loadMigrationPackages,
   maskConnectionUrl,
   readContractEnvelope,
   resolveMigrationPaths,
@@ -50,9 +53,12 @@ import {
   toStructuralEdge,
 } from '../utils/command-helpers';
 import {
-  type BuildAggregateInputs,
-  buildContractSpaceAggregate,
+  appContractStandInFromIdentity,
+  loadContractRawSafely,
+  refuseContractSpaceIntegrity,
+  refusePackageCorruptionOnAggregate,
 } from '../utils/contract-space-aggregate-loader';
+import { toDeclaredExtensionsFromRaw } from '../utils/extension-pack-inputs';
 import {
   type EdgeStatus,
   type EdgeStatusKind,
@@ -184,10 +190,9 @@ export interface MigrationStatusResult {
    * migrations directory) where the existing diagnostics already
    * surface the failure.
    *
-   * The legacy top-level fields (`migrations`, `markerHash`,
-   * `targetHash`, `pathDecision`, …) describe the **app member**
-   * specifically — back-compat with single-space callers. Per-space
-   * detail for extension members lives only on this list.
+   * The top-level fields (`migrations`, `markerHash`, `targetHash`,
+   * `pathDecision`, …) describe the **app member** specifically.
+   * Per-space detail for extension members lives only on this list.
    */
   readonly spaces?: readonly MigrationStatusSpaceEntry[];
   /** Cross-space pending-migration total (sum of `spaces[].pendingCount`). Present when `spaces` is. */
@@ -424,55 +429,50 @@ function resolveDisplayChain(
 /**
  * Build the aggregate enumeration of contract spaces for the status
  * output. Loads the aggregate from disk (lossy on failure — extension
- * spaces are simply omitted, the existing single-space app behaviour
- * keeps working), reads per-space marker rows when online, and uses
+ * spaces are simply omitted, the app member's output keeps working),
+ * reads per-space marker rows when online, and uses
  * {@link graphWalkStrategy} to compute each space's pending count.
  *
- * Sub-spec § `migration status` semantics — the aggregate-walking
- * version reports per-space marker + pending state alongside the
- * cross-space totals.
+ * The aggregate-walking status reports per-space marker + pending
+ * state alongside the cross-space totals.
  */
 export async function loadAggregateStatusSpaces(args: {
-  readonly targetId: string;
-  readonly migrationsDir: string;
-  readonly appContractRaw: unknown;
-  readonly extensionPacks: BuildAggregateInputs<string, string>['extensionPacks'];
-  readonly deserializeContract: BuildAggregateInputs<string, string>['deserializeContract'];
+  readonly aggregate: ContractSpaceAggregate;
+  readonly extensionPacks: ReadonlyArray<unknown>;
   readonly markersBySpace: ReadonlyMap<string, ContractMarkerRecordLike> | null;
 }): Promise<readonly MigrationStatusSpaceEntry[]> {
-  const loadInputs: BuildAggregateInputs<string, string> = {
-    targetId: args.targetId,
-    migrationsDir: args.migrationsDir,
-    appContract: args.deserializeContract(args.appContractRaw),
-    extensionPacks: args.extensionPacks,
-    deserializeContract: args.deserializeContract,
-  };
-
-  const loaded = await buildContractSpaceAggregate(loadInputs);
-  if (!loaded.ok) {
-    // Loader failure (drift, layout violation, etc.) — surfacing it
-    // as a status diagnostic would duplicate `migration plan`'s job.
-    // The single-space app pipeline still runs; extensions are simply
-    // not enumerated.
+  const declaredExtensions = toDeclaredExtensionsFromRaw(args.extensionPacks);
+  if (
+    refuseContractSpaceIntegrity(args.aggregate, {
+      declaredExtensions,
+      checkContracts: true,
+    })
+  ) {
+    // Full integrity refusal (drift, layout violation, etc.) — surfacing
+    // it as a status diagnostic would duplicate `migration plan`'s job.
+    // The app pipeline still runs; extensions are simply not enumerated.
     return [];
   }
-  const aggregate = loaded.value;
+  const aggregate = args.aggregate;
 
   const orderedMembers = [...aggregate.extensions, aggregate.app];
   const rows: MigrationStatusSpaceEntry[] = [];
   for (const member of orderedMembers) {
     const liveMarker = args.markersBySpace?.get(member.spaceId) ?? null;
     const isApp = member.spaceId === aggregate.app.spaceId;
+    // The aggregate passed the integrity gate above, so every member has
+    // a resolved head ref (a missing one would have refused the load).
+    const headRef = requireHeadRef(member);
 
-    if (member.migrations.graph.nodes.size === 0) {
+    if (member.graph().nodes.size === 0) {
       rows.push({
         spaceId: member.spaceId,
         kind: isApp ? 'app' : 'extension',
-        headHash: member.headRef.hash,
+        headHash: headRef.hash,
         ...(args.markersBySpace !== null
           ? {
               markerHash: liveMarker?.storageHash ?? null,
-              status: member.headRef.hash === EMPTY_CONTRACT_HASH ? 'up-to-date' : 'never-planned',
+              status: headRef.hash === EMPTY_CONTRACT_HASH ? 'up-to-date' : 'never-planned',
               pendingCount: 0,
             }
           : {}),
@@ -484,7 +484,7 @@ export async function loadAggregateStatusSpaces(args: {
       rows.push({
         spaceId: member.spaceId,
         kind: isApp ? 'app' : 'extension',
-        headHash: member.headRef.hash,
+        headHash: headRef.hash,
       });
       continue;
     }
@@ -513,7 +513,7 @@ export async function loadAggregateStatusSpaces(args: {
     rows.push({
       spaceId: member.spaceId,
       kind: isApp ? 'app' : 'extension',
-      headHash: member.headRef.hash,
+      headHash: headRef.hash,
       markerHash: liveMarker?.storageHash ?? null,
       pendingCount,
       ...(status ? { status } : {}),
@@ -528,17 +528,6 @@ export async function loadAggregateStatusSpaces(args: {
  * the existing `readContractEnvelope` path will report the same
  * problem via a status diagnostic, no need to double-surface.
  */
-async function loadContractRawSafely(config: {
-  contract?: { output?: string };
-}): Promise<unknown | null> {
-  try {
-    const path = (await import('../utils/command-helpers')).resolveContractPath(config);
-    const raw = await (await import('node:fs/promises')).readFile(path, 'utf-8');
-    return JSON.parse(raw) as unknown;
-  } catch {
-    return null;
-  }
-}
 
 async function validateOnlineMarkerRead(
   config: Awaited<ReturnType<typeof loadConfig>>,
@@ -580,8 +569,10 @@ async function executeMigrationStatusCommand(
   ui: TerminalUI,
 ): Promise<Result<MigrationStatusResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, migrationsDir, refsDir } =
-    resolveMigrationPaths(options.config, config);
+  const { configPath, appMigrationsRelative, migrationsDir, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
 
   const dbConnection = options.db ?? config.db?.connection;
   const hasDriver = !!config.driver;
@@ -599,37 +590,92 @@ async function executeMigrationStatusCommand(
     throw error;
   }
 
-  let fromOverrideHash: string | undefined;
+  const diagnostics: StatusDiagnostic[] = [];
+  let contractHash: string = EMPTY_CONTRACT_HASH;
+  try {
+    const envelope = await readContractEnvelope(config);
+    contractHash = envelope.storageHash;
+  } catch (error) {
+    diagnostics.push({
+      code: 'CONTRACT.UNREADABLE',
+      severity: 'warn',
+      message: `Could not read contract: ${error instanceof Error ? error.message : 'unknown error'}`,
+      hints: ["Run 'prisma-next contract emit' to generate a valid contract"],
+    });
+  }
 
-  if (options.to || options.from) {
+  const contractRawForAggregate = await loadContractRawSafely(config);
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+  const deserializeContract = (json: unknown): Contract => familyInstance.deserializeContract(json);
+  const appContractStandIn = appContractStandInFromIdentity({
+    contractHash,
+    targetId: config.target.id,
+    targetFamily: config.target.familyId,
+  });
+  let appContractForLoad: Contract = appContractStandIn;
+  if (contractRawForAggregate !== null) {
     try {
-      const { graph: earlyGraph } = await loadMigrationPackages(appMigrationsDir);
+      appContractForLoad = deserializeContract(contractRawForAggregate);
+    } catch (error) {
+      diagnostics.push({
+        code: 'CONTRACT.UNREADABLE',
+        severity: 'warn',
+        message: `Could not deserialize contract: ${error instanceof Error ? error.message : 'unknown error'}`,
+        hints: ["Run 'prisma-next contract emit' to generate a valid contract"],
+      });
+    }
+  }
 
-      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];
-        }
-      }
+  let aggregate: ContractSpaceAggregate;
+  try {
+    aggregate = await loadContractSpaceAggregate({
+      migrationsDir,
+      deserializeContract,
+      appContract: appContractForLoad,
+    });
+  } 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 directory: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
 
-      if (options.from) {
-        const fromResult = parseContractRef(options.from, { graph: earlyGraph, refs: allRefs });
-        if (!fromResult.ok) {
-          return notOk(mapRefResolutionError(fromResult.failure));
-        }
-        fromOverrideHash = fromResult.value.hash;
+  if (contractRawForAggregate !== null) {
+    const corruptionFailure = refusePackageCorruptionOnAggregate(aggregate);
+    if (corruptionFailure) {
+      return notOk(corruptionFailure);
+    }
+  }
+
+  const appGraph = aggregate.app.graph();
+
+  let fromOverrideHash: string | undefined;
+
+  if (options.to || options.from) {
+    if (options.to) {
+      const refResult = parseContractRef(options.to, { graph: appGraph, refs: allRefs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
       }
-    } catch (error) {
-      if (MigrationToolsError.is(error)) {
-        return notOk(mapMigrationToolsError(error));
+      activeRefHash = refResult.value.hash;
+      if (refResult.value.provenance.kind === 'ref') {
+        const resolvedRefName = refResult.value.provenance.refName;
+        activeRefName = resolvedRefName;
+        activeRefEntry = allRefs[resolvedRefName];
       }
-      throw error;
+    }
+
+    if (options.from) {
+      const fromResult = parseContractRef(options.from, { graph: appGraph, refs: allRefs });
+      if (!fromResult.ok) {
+        return notOk(mapRefResolutionError(fromResult.failure));
+      }
+      fromOverrideHash = fromResult.value.hash;
     }
   }
 
@@ -670,34 +716,8 @@ async function executeMigrationStatusCommand(
     ui.stderr(header);
   }
 
-  const diagnostics: StatusDiagnostic[] = [];
-  let contractHash: string = EMPTY_CONTRACT_HASH;
-  try {
-    const envelope = await readContractEnvelope(config);
-    contractHash = envelope.storageHash;
-  } catch (error) {
-    diagnostics.push({
-      code: 'CONTRACT.UNREADABLE',
-      severity: 'warn',
-      message: `Could not read contract: ${error instanceof Error ? error.message : 'unknown error'}`,
-      hints: ["Run 'prisma-next contract emit' to generate a valid contract"],
-    });
-  }
-
-  let bundles: readonly OnDiskMigrationPackage[];
-  let graph: MigrationGraph;
-  try {
-    ({ bundles, 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 directory: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
-  }
+  const bundles = aggregate.app.packages;
+  const graph = appGraph;
 
   if (bundles.length === 0) {
     if (dbConnection && hasDriver) {
@@ -772,8 +792,8 @@ async function executeMigrationStatusCommand(
       mode = 'online';
       // Read every space's marker so the aggregate enumeration can
       // surface per-space marker state. `readAllMarkers` mirrors what
-      // `db init` / `db update` already use to drive the multi-space
-      // planner; here it powers the aggregate status output.
+      // `db init` / `db update` already use to drive the planner;
+      // here it powers the aggregate status output.
       //
       // Probe for the method first so we only swallow the
       // unsupported-method case: older family instances may not
@@ -808,32 +828,15 @@ async function executeMigrationStatusCommand(
     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
-  // can't be loaded — a strict failure here would degrade the
-  // load-bearing app-space output for unrelated reasons.
-  const contractRawForAggregate = await loadContractRawSafely(config);
   let aggregateSpaces: readonly MigrationStatusSpaceEntry[] = [];
   if (contractRawForAggregate !== null) {
-    // The aggregate loader needs a typed-Contract producer. Build a
-    // real control stack so `deserializeContract` runs against a fully
-    // composed family instance — descriptors that read stack members
-    // during construction (e.g. codec lookups) get a consistent view.
-    const stack = createControlStack(config);
-    const familyInstance = config.family.create(stack);
     try {
       aggregateSpaces = await loadAggregateStatusSpaces({
-        targetId: config.target.targetId,
-        migrationsDir,
-        appContractRaw: contractRawForAggregate,
+        aggregate,
         extensionPacks: config.extensionPacks ?? [],
-        deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
         markersBySpace: allMarkers,
       });
     } catch {
-      // Loader failure short-circuits silently — the existing
-      // single-space app pipeline below still runs.
       aggregateSpaces = [];
     }
   }
@@ -1252,7 +1255,7 @@ export function formatStatusSummary(result: MigrationStatusResult, colorize: boo
   }
 
   // Per-space section. Suppressed when there's no extension space —
-  // the legacy single-space output already covers the app member.
+  // the top-level output already covers the app member.
   // When extensions exist, render every space (including the app)
   // for consistency, plus a cross-space pending total + apply hint.
   if (result.spaces?.some((s) => s.kind === 'extension')) {

package/src/commands/ref.ts

@@ -1,18 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { 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 {
-  deleteRef,
+  deleteRefPaired,
   readRefs,
   validateRefName,
   validateRefValue,
-  writeRef,
+  writeRefPaired,
 } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
+import { join } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   CliStructuredError,
+  errorFileNotFound,
+  errorRefSetBundleNotFound,
+  errorRefSetEmptySentinel,
+  errorRefSetHashNotInGraph,
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
@@ -20,12 +28,13 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   resolveMigrationPaths,
   setCommandDescriptions,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatCommandHelp } from '../utils/formatters/help';
 import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { readContractIR } from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI } from '../utils/terminal-ui';
 
@@ -72,14 +81,19 @@ export async function executeRefSetCommand(
 
   try {
     const config = await loadConfig(options.config);
-    const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+    const { migrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+    const loaded = await buildReadAggregate(config, { migrationsDir });
+    if (!loaded.ok) {
+      return notOk(loaded.failure);
+    }
+    const graph = loaded.value.aggregate.app.graph();
+    const bundles = loaded.value.aggregate.app.packages;
+    const refs = loaded.value.aggregate.app.refs;
 
     let resolvedHash: string;
     if (validateRefValue(contractInput)) {
       resolvedHash = contractInput;
     } else {
-      const { graph } = await loadMigrationPackages(appMigrationsDir);
-      const refs = await readRefs(refsDir);
       const refResult = parseContractRef(contractInput, { graph, refs });
       if (!refResult.ok) {
         return notOk(mapRefResolutionError(refResult.failure));
@@ -87,8 +101,39 @@ export async function executeRefSetCommand(
       resolvedHash = refResult.value.hash;
     }
 
+    if (resolvedHash === EMPTY_CONTRACT_HASH) {
+      return notOk(errorRefSetEmptySentinel(resolvedHash));
+    }
+    if (!isGraphNode(resolvedHash, graph)) {
+      const graphTip = findLatestMigration(graph)?.to ?? null;
+      return notOk(errorRefSetHashNotInGraph(resolvedHash, [...graph.nodes].sort(), graphTip));
+    }
+
+    const matchingBundle = bundles.find((bundle) => bundle.metadata.to === resolvedHash);
+    if (!matchingBundle) {
+      return notOk(errorRefSetBundleNotFound(resolvedHash));
+    }
+
+    const contractJsonPath = join(matchingBundle.dirPath, 'end-contract.json');
+    let contractJson: Record<string, unknown>;
+    try {
+      const raw = await readFile(contractJsonPath, 'utf-8');
+      contractJson = JSON.parse(raw) as Record<string, unknown>;
+    } catch (readError) {
+      if (readError instanceof Error && (readError as NodeJS.ErrnoException).code === 'ENOENT') {
+        return notOk(
+          errorFileNotFound(contractJsonPath, {
+            why: `Migration bundle for hash ${resolvedHash} is missing its end-contract snapshot at ${contractJsonPath}`,
+            fix: 'Run `pnpm fixtures:check`, or re-emit the migration so its end-contract.json is restored.',
+          }),
+        );
+      }
+      throw readError;
+    }
+
+    const contractIR = await readContractIR(contractJson, contractJsonPath);
     const entry: RefEntry = { hash: resolvedHash, invariants: [] };
-    await writeRef(refsDir, name, entry);
+    await writeRefPaired(refsDir, name, entry, contractIR);
     return ok({ ok: true as const, ref: name, hash: resolvedHash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -103,7 +148,7 @@ export async function executeRefDeleteCommand(
   try {
     const config = await loadConfig(options.config);
     const { refsDir } = resolveMigrationPaths(options.config, config);
-    await deleteRef(refsDir, name);
+    await deleteRefPaired(refsDir, name);
     return ok({ ok: true as const, ref: name, deleted: true as const });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);

package/src/control-api/client.ts

@@ -473,7 +473,6 @@ class ControlClientImpl implements ControlClient {
       migrationsDir: options.migrationsDir,
       extensionPacks: this.options.extensionPacks ?? [],
       targetId: this.options.target.targetId,
-      appMigrationPackages: options.appMigrationPackages,
       ...ifDefined('refHash', options.refHash),
       ...ifDefined('refInvariants', options.refInvariants),
       ...ifDefined('refName', options.refName),

package/src/control-api/contract-enrichment.ts

@@ -1,7 +1,8 @@
 import type { Contract } from '@prisma-next/contract/types';
-import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
-
-type CapabilityMatrix = Record<string, Record<string, boolean>>;
+import {
+  mergeCapabilityMatrices,
+  type TargetBoundComponentDescriptor,
+} from '@prisma-next/framework-components/components';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -26,37 +27,6 @@ function sortDeepTyped<T>(value: T): T {
   return sortDeep(value) as T;
 }
 
-function extractCapabilityMatrix(value: unknown): CapabilityMatrix {
-  if (!isPlainObject(value)) return {};
-
-  const out: CapabilityMatrix = {};
-  for (const [namespace, maybeCaps] of Object.entries(value)) {
-    if (!isPlainObject(maybeCaps)) continue;
-    const caps: Record<string, boolean> = {};
-    for (const [key, flag] of Object.entries(maybeCaps)) {
-      if (typeof flag === 'boolean') {
-        caps[key] = flag;
-      }
-    }
-    if (Object.keys(caps).length > 0) {
-      out[namespace] = caps;
-    }
-  }
-
-  return out;
-}
-
-function mergeCapabilities(left: CapabilityMatrix, right: CapabilityMatrix): CapabilityMatrix {
-  const next: CapabilityMatrix = { ...left };
-  for (const [namespace, capabilities] of Object.entries(right)) {
-    next[namespace] = {
-      ...(left[namespace] ?? {}),
-      ...capabilities,
-    };
-  }
-  return next;
-}
-
 function extractExtensionPackMeta(
   component: TargetBoundComponentDescriptor<string, string>,
 ): Record<string, unknown> {
@@ -93,16 +63,10 @@ export function enrichContract(
   ir: Contract,
   components: ReadonlyArray<TargetBoundComponentDescriptor<string, string>>,
 ): Contract {
-  let mergedCapabilities = ir.capabilities;
-  const extensionPacksMeta: Record<string, unknown> = {};
+  const mergedCapabilities = mergeCapabilityMatrices(ir.capabilities, components);
 
+  const extensionPacksMeta: Record<string, unknown> = {};
   for (const component of components) {
-    if (component.capabilities) {
-      mergedCapabilities = mergeCapabilities(
-        mergedCapabilities,
-        extractCapabilityMatrix(component.capabilities),
-      );
-    }
     if (component.kind === 'extension') {
       extensionPacksMeta[component.id] = extractExtensionPackMeta(component);
     }