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

package/src/config-path-validation.ts

@@ -57,7 +57,6 @@ export function finalizeConfig(config: PrismaNextConfig, configDir: string): Pri
   if (!config.contract) {
     return config;
   }
-
   const contract = normalizeContractConfig(config.contract);
   const source = finalizeContractSource(contract.source, configDir);
   const output = resolve(configDir, contract.output);

package/src/control-api/client.ts

@@ -6,15 +6,21 @@ import type {
   ControlFamilyInstance,
   ControlStack,
   CoreSchemaView,
+  MigrationPlanOperation,
+  OperationPreview,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
 import {
+  APP_SPACE_ID,
   createControlStack,
   hasMigrations,
+  hasOperationPreview,
+  hasPslContractInfer,
   hasSchemaView,
 } from '@prisma-next/framework-components/control';
+import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
@@ -22,7 +28,9 @@ import { enrichContract } from './contract-enrichment';
 import { ContractValidationError } from './errors';
 import { executeDbInit } from './operations/db-init';
 import { executeDbUpdate } from './operations/db-update';
+import { type ExecuteDbVerifyResult, executeDbVerify } from './operations/db-verify';
 import { executeMigrationApply } from './operations/migration-apply';
+
 import type {
   ControlActionName,
   ControlClient,
@@ -31,6 +39,7 @@ import type {
   DbInitResult,
   DbUpdateOptions,
   DbUpdateResult,
+  DbVerifyOptions,
   EmitOptions,
   EmitResult,
   IntrospectOptions,
@@ -362,6 +371,9 @@ class ControlClientImpl implements ControlClient {
       mode: options.mode,
       migrations: this.options.target.migrations,
       frameworkComponents,
+      migrationsDir: options.migrationsDir,
+      targetId: this.options.target.targetId,
+      extensionPacks: this.options.extensionPacks ?? [],
       ...ifDefined('onProgress', onProgress),
     });
   }
@@ -390,14 +402,54 @@ class ControlClientImpl implements ControlClient {
       mode: options.mode,
       migrations: this.options.target.migrations,
       frameworkComponents,
+      migrationsDir: options.migrationsDir,
+      targetId: this.options.target.targetId,
+      extensionPacks: this.options.extensionPacks ?? [],
       ...ifDefined('acceptDataLoss', options.acceptDataLoss),
       ...ifDefined('onProgress', onProgress),
     });
   }
 
+  async dbVerify(options: DbVerifyOptions): Promise<ExecuteDbVerifyResult> {
+    const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'dbVerify', onProgress);
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
+
+    return executeDbVerify({
+      driver,
+      familyInstance,
+      contract,
+      migrationsDir: options.migrationsDir,
+      targetId: this.options.target.targetId,
+      extensionPacks: this.options.extensionPacks ?? [],
+      frameworkComponents,
+      mode: options.strict ? 'strict' : 'lenient',
+      skipSchema: options.skipSchema,
+      skipMarker: options.skipMarker,
+      ...ifDefined('onProgress', onProgress),
+    });
+  }
+
   async readMarker(): Promise<ContractMarkerRecord | null> {
     const { driver, familyInstance } = await this.ensureConnected();
-    return familyInstance.readMarker({ driver });
+    // The CLI client's readMarker reads the app's marker. Per-extension
+    // readers go through the orchestrator's per-space planner / runner
+    // boundary, which threads the extension's space id through the
+    // family interface explicitly.
+    return familyInstance.readMarker({ driver, space: APP_SPACE_ID });
+  }
+
+  async readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>> {
+    const { driver, familyInstance } = await this.ensureConnected();
+    return familyInstance.readAllMarkers({ driver });
   }
 
   async migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult> {
@@ -409,16 +461,28 @@ class ControlClientImpl implements ControlClient {
       throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
+
     return executeMigrationApply({
       driver,
       familyInstance,
-      originHash: options.originHash,
-      destinationHash: options.destinationHash,
-      pendingMigrations: options.pendingMigrations,
+      contract,
       migrations: this.options.target.migrations,
       frameworkComponents,
+      migrationsDir: options.migrationsDir,
+      extensionPacks: this.options.extensionPacks ?? [],
       targetId: this.options.target.targetId,
-      ...(onProgress ? { onProgress } : {}),
+      appMigrationPackages: options.appMigrationPackages,
+      ...ifDefined('refHash', options.refHash),
+      ...ifDefined('refInvariants', options.refInvariants),
+      ...ifDefined('refName', options.refName),
+      ...ifDefined('onProgress', onProgress),
     });
   }
 
@@ -469,6 +533,22 @@ class ControlClientImpl implements ControlClient {
     return undefined;
   }
 
+  inferPslContract(schemaIR: unknown): PslDocumentAst | undefined {
+    this.init();
+    if (this.familyInstance && hasPslContractInfer(this.familyInstance)) {
+      return this.familyInstance.inferPslContract(schemaIR);
+    }
+    return undefined;
+  }
+
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview | undefined {
+    this.init();
+    if (this.familyInstance && hasOperationPreview(this.familyInstance)) {
+      return this.familyInstance.toOperationPreview(operations);
+    }
+    return undefined;
+  }
+
   async emit(options: EmitOptions): Promise<EmitResult> {
     const { onProgress, contractConfig } = options;
 

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

@@ -73,7 +73,11 @@ function extractExtensionPackMeta(
   }
   if (types) {
     if (types.codecTypes) {
-      const { controlPlaneHooks: _, codecInstances: _ci, ...cleanedCodecTypes } = types.codecTypes;
+      const {
+        controlPlaneHooks: _,
+        codecDescriptors: _cd,
+        ...cleanedCodecTypes
+      } = types.codecTypes;
       base['types'] = { ...types, codecTypes: cleanedCodecTypes };
     } else {
       base['types'] = types;
@@ -83,9 +87,7 @@ function extractExtensionPackMeta(
 }
 
 /**
- * Enriches a raw contract with framework-derived metadata:
- * capabilities from all component descriptors and extension pack metadata
- * from extension descriptors. Produces deterministically sorted output.
+ * Enriches a raw contract with framework-derived metadata: capabilities from all component descriptors and extension pack metadata from extension descriptors. Produces deterministically sorted output.
  */
 export function enrichContract(
   ir: Contract,

package/src/control-api/operations/apply-aggregate.ts

@@ -0,0 +1,290 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  MigrationOperationPolicy,
+  MultiSpaceCapableRunner,
+  MultiSpaceRunnerPerSpaceOptions,
+  TargetMigrationsCapability,
+} from '@prisma-next/framework-components/control';
+import { hasMultiSpaceRunner } from '@prisma-next/framework-components/control';
+import type {
+  AggregatePerSpacePlan,
+  ContractSpaceAggregate,
+} from '@prisma-next/migration-tools/aggregate';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { errorRunnerFailed } from '../../utils/cli-errors';
+import type { AggregatePerSpaceExecutionEntry, OnControlProgress } from '../types';
+
+/**
+ * Span id emitted via `onProgress` for the apply phase. Stable
+ * identifier consumed by the structured-output renderer and by tests.
+ */
+const APPLY_SPAN_ID = 'apply' as const;
+
+/**
+ * Action that originated this apply call. Threaded into `OnControlProgress`
+ * events so the parent CLI command can attribute the span correctly,
+ * and used to compose action-specific summary phrasing.
+ */
+export type AggregateApplyAction = 'dbInit' | 'dbUpdate' | 'migrationApply';
+
+/**
+ * Failure variant emitted by {@link applyAggregate} when the multi-space
+ * runner itself rejects the apply. Mirrors the failure shape callers
+ * already wrap into their own action-specific failure envelopes
+ * (`DbInitFailure`, `DbUpdateFailure`, `MigrationApplyFailure`) so each
+ * caller keeps owning its own discriminated failure code.
+ */
+export interface AggregateApplyRunnerFailure {
+  readonly summary: string;
+  readonly why?: string;
+  readonly meta: Record<string, unknown>;
+}
+
+export interface ApplyAggregateInputs<TFamilyId extends string, TTargetId extends string> {
+  readonly aggregate: ContractSpaceAggregate;
+  /**
+   * Per-space plans, keyed by `spaceId`. Produced by either the full
+   * {@link planAggregate} pipeline (`db init` / `db update` — synth
+   * for the app, graph-walk for extensions) or by direct
+   * {@link graphWalkStrategy} calls (`migration apply` — graph-walk
+   * for every member). Either way, the runner consumes the same shape.
+   */
+  readonly perSpacePlans: ReadonlyMap<string, AggregatePerSpacePlan>;
+  /**
+   * Canonical schedule order — extensions alphabetically by `spaceId`,
+   * then app. Mirrors {@link import('@prisma-next/migration-tools/concatenate-space-apply-inputs').concatenateSpaceApplyInputs}'s
+   * convention so `MultiSpaceRunnerFailure.failingSpace` attribution
+   * stays byte-for-byte stable across callers.
+   */
+  readonly applyOrder: readonly string[];
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId, unknown>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly policy: MigrationOperationPolicy;
+  readonly action: AggregateApplyAction;
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Resolved per-space plan in canonical schedule order. Surfaced from
+ * {@link applyAggregate} to callers so each one can build its own
+ * action-specific success envelope (e.g. `DbInitSuccess` vs
+ * `MigrationApplySuccess`) without re-deriving the ordering.
+ */
+export interface OrderedResolution {
+  readonly spaceId: string;
+  readonly entry: AggregatePerSpacePlan;
+}
+
+export interface ApplyAggregateValue {
+  readonly orderedResolutions: readonly OrderedResolution[];
+  readonly totalOpsPlanned: number;
+  readonly totalOpsExecuted: number;
+  /**
+   * Per-space breakdown ready to thread into action-specific success
+   * envelopes. Each entry carries the post-apply marker (live storage hash
+   * plus invariants) so callers can render it directly without re-reading.
+   */
+  readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
+}
+
+export type ApplyAggregateResult = Result<ApplyAggregateValue, AggregateApplyRunnerFailure>;
+
+/**
+ * Runner-driving tail shared by every aggregate apply caller — `db init`,
+ * `db update`, and `migration apply`. Consumes already-resolved per-space
+ * plans (the planner-vs-replay distinction is owned by the caller) and
+ * dispatches them to the multi-space runner in canonical order.
+ *
+ * Marker advancement is part of the runner's per-space transaction
+ * (the SQL family runner writes the marker as the last step of each
+ * space's transaction), so this primitive does not advance markers
+ * separately — by the time `executeAcrossSpaces` returns ok, every
+ * space's marker has been advanced to its plan's destination.
+ *
+ * Span emission (`spanStart 'apply'` / `spanEnd 'apply'`) is owned here
+ * so callers don't have to duplicate it; the `action` field on each
+ * progress event is taken from the caller's `action` argument.
+ */
+export async function applyAggregate<TFamilyId extends string, TTargetId extends string>(
+  inputs: ApplyAggregateInputs<TFamilyId, TTargetId>,
+): Promise<ApplyAggregateResult> {
+  const {
+    aggregate,
+    perSpacePlans,
+    applyOrder,
+    driver,
+    familyInstance,
+    migrations,
+    frameworkComponents,
+    policy,
+    action,
+    onProgress,
+  } = inputs;
+
+  const orderedResolutions = collectOrdered(applyOrder, perSpacePlans);
+
+  const runner = migrations.createRunner(familyInstance);
+  if (!hasMultiSpaceRunner(runner)) {
+    throw errorRunnerFailed(
+      `Runner for target "${aggregate.targetId}" does not implement \`executeAcrossSpaces\``,
+      {
+        why: `${labelForAction(action)} requires multi-space-capable runners (today: every SQL family runner).`,
+      },
+    );
+  }
+
+  onProgress?.({
+    action,
+    kind: 'spanStart',
+    spanId: APPLY_SPAN_ID,
+    label: progressLabelForAction(action),
+  });
+
+  const perSpaceOptions: MultiSpaceRunnerPerSpaceOptions<TFamilyId, TTargetId>[] =
+    orderedResolutions.map((r) => ({
+      space: r.spaceId,
+      plan: r.entry.plan,
+      driver,
+      destinationContract: r.entry.destinationContract,
+      policy,
+      frameworkComponents,
+      // Per-space post-apply schema verification is non-strict: each
+      // space's `destinationContract` describes only its own slice; a
+      // strict verifier would treat every other space's tables as
+      // `extras`. Tolerant mode still catches missing tables / columns.
+      // SQL family runners read `strictVerification` via structural
+      // typing.
+      strictVerification: false,
+    })) as MultiSpaceRunnerPerSpaceOptions<TFamilyId, TTargetId>[];
+
+  const runnerResult = await (
+    runner as MultiSpaceCapableRunner<TFamilyId, TTargetId>
+  ).executeAcrossSpaces({ driver, perSpaceOptions });
+
+  if (!runnerResult.ok) {
+    onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'error' });
+    return notOk({
+      summary: runnerResult.failure.summary,
+      ...ifDefined('why', runnerResult.failure.why),
+      meta: {
+        ...(runnerResult.failure.meta ?? {}),
+        failingSpace: runnerResult.failure.failingSpace,
+      },
+    });
+  }
+  onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'ok' });
+
+  const totalOpsPlanned = runnerResult.value.perSpaceResults.reduce(
+    (sum, r) => sum + r.value.operationsPlanned,
+    0,
+  );
+  const totalOpsExecuted = runnerResult.value.perSpaceResults.reduce(
+    (sum, r) => sum + r.value.operationsExecuted,
+    0,
+  );
+
+  const perSpace = buildPerSpaceBreakdown(orderedResolutions, aggregate.app.spaceId, {
+    includeMarkers: true,
+  });
+
+  return ok({
+    orderedResolutions,
+    totalOpsPlanned,
+    totalOpsExecuted,
+    perSpace,
+  });
+}
+
+/**
+ * Project the planner's per-space resolutions into the
+ * `AggregatePerSpaceExecutionEntry[]` shape the CLI surfaces.
+ *
+ * `includeMarkers` is `true` for apply-mode (each space's marker is
+ * the `destination.storageHash` of its plan, which the runner
+ * advances as the last step of each space's transaction) and `false`
+ * for plan-mode (no marker has been written yet).
+ *
+ * Exported alongside {@link applyAggregate} so plan-mode callers can
+ * assemble the same per-space block without going through the runner.
+ */
+export function buildPerSpaceBreakdown(
+  orderedResolutions: readonly OrderedResolution[],
+  appSpaceId: string,
+  options: { readonly includeMarkers: boolean },
+): readonly AggregatePerSpaceExecutionEntry[] {
+  return orderedResolutions.map((r) => {
+    const operations = r.entry.displayOps.map((op) => ({
+      id: op.id,
+      label: op.label,
+      operationClass: op.operationClass,
+    }));
+    const base: AggregatePerSpaceExecutionEntry = {
+      spaceId: r.spaceId,
+      kind: r.spaceId === appSpaceId ? 'app' : 'extension',
+      operations,
+    };
+    if (!options.includeMarkers) return base;
+    return {
+      ...base,
+      marker: { storageHash: r.entry.plan.destination.storageHash },
+    };
+  });
+}
+
+/**
+ * Materialise the `applyOrder` ordering into resolved per-space
+ * entries. Throws if the planner output is missing a member listed
+ * in `applyOrder` — a wiring bug that should never reach runtime.
+ *
+ * Exported so callers building their own success envelopes after a
+ * plan-mode dispatch can replay the same ordering.
+ */
+export function collectOrdered(
+  applyOrder: readonly string[],
+  perSpace: ReadonlyMap<string, AggregatePerSpacePlan>,
+): readonly OrderedResolution[] {
+  return applyOrder.map((spaceId) => {
+    const entry = perSpace.get(spaceId);
+    if (!entry) {
+      throw new Error(`Aggregate planner output missing per-space plan for "${spaceId}"`);
+    }
+    return { spaceId, entry };
+  });
+}
+
+/**
+ * Action-appropriate label for the `spanStart` event the apply
+ * primitive emits. `applyAggregate` is shared by `db init`, `db update`,
+ * and `migration apply`; the span label tracks the user-visible action
+ * so structured-progress output reads naturally for each surface.
+ */
+export function progressLabelForAction(action: AggregateApplyAction): string {
+  switch (action) {
+    case 'dbInit':
+      return 'Initialising database across spaces';
+    case 'dbUpdate':
+      return 'Updating database across spaces';
+    case 'migrationApply':
+      return 'Applying migration plan across spaces';
+  }
+}
+
+function labelForAction(action: AggregateApplyAction): string {
+  switch (action) {
+    case 'dbInit':
+      return 'db init';
+    case 'dbUpdate':
+      return 'db update';
+    case 'migrationApply':
+      return 'migration apply';
+  }
+}