@prisma-next/cli 0.3.0-dev.55 → 0.3.0-dev.63

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

@@ -0,0 +1,195 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/core-control-plane/constants';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  MigrationPlanOperation,
+  MigrationRunnerResult,
+  TargetMigrationsCapability,
+} from '@prisma-next/core-control-plane/types';
+import { notOk, ok } from '@prisma-next/utils/result';
+import type {
+  MigrationApplyAppliedEntry,
+  MigrationApplyResult,
+  MigrationApplyStep,
+  OnControlProgress,
+} from '../types';
+
+export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetId extends string> {
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId>;
+  readonly originHash: string;
+  readonly destinationHash: string;
+  readonly pendingMigrations: readonly MigrationApplyStep[];
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly targetId: string;
+  readonly onProgress?: OnControlProgress;
+}
+
+export async function executeMigrationApply<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteMigrationApplyOptions<TFamilyId, TTargetId>,
+): Promise<MigrationApplyResult> {
+  const {
+    driver,
+    familyInstance,
+    originHash,
+    destinationHash,
+    pendingMigrations,
+    migrations,
+    frameworkComponents,
+    targetId,
+    onProgress,
+  } = options;
+
+  if (pendingMigrations.length === 0) {
+    if (originHash !== destinationHash) {
+      return notOk({
+        code: 'MIGRATION_PATH_NOT_FOUND' as const,
+        summary: 'No migrations provided for requested origin and destination',
+        why: `Requested ${originHash} -> ${destinationHash} but pendingMigrations is empty`,
+        meta: { originHash, destinationHash },
+      });
+    }
+    return ok({
+      migrationsApplied: 0,
+      markerHash: originHash,
+      applied: [],
+      summary: 'Already up to date',
+    });
+  }
+
+  const firstMigration = pendingMigrations[0]!;
+  const lastMigration = pendingMigrations[pendingMigrations.length - 1]!;
+  if (firstMigration.from !== originHash || lastMigration.to !== destinationHash) {
+    return notOk({
+      code: 'MIGRATION_PATH_NOT_FOUND' as const,
+      summary: 'Migration apply path does not match requested origin and destination',
+      why: `Path resolved as ${firstMigration.from} -> ${lastMigration.to}, but requested ${originHash} -> ${destinationHash}`,
+      meta: {
+        originHash,
+        destinationHash,
+        pathOrigin: firstMigration.from,
+        pathDestination: lastMigration.to,
+      },
+    });
+  }
+
+  for (let i = 1; i < pendingMigrations.length; i++) {
+    const previous = pendingMigrations[i - 1]!;
+    const current = pendingMigrations[i]!;
+    if (previous.to !== current.from) {
+      return notOk({
+        code: 'MIGRATION_PATH_NOT_FOUND' as const,
+        summary: 'Migration apply path contains a discontinuity between adjacent migrations',
+        why: `Migration "${previous.dirName}" ends at ${previous.to}, but next migration "${current.dirName}" starts at ${current.from}`,
+        meta: {
+          originHash,
+          destinationHash,
+          previousDirName: previous.dirName,
+          previousTo: previous.to,
+          currentDirName: current.dirName,
+          currentFrom: current.from,
+          discontinuityIndex: i,
+        },
+      });
+    }
+  }
+
+  const runner = migrations.createRunner(familyInstance);
+  const applied: MigrationApplyAppliedEntry[] = [];
+
+  for (const migration of pendingMigrations) {
+    const migrationSpanId = `migration:${migration.dirName}`;
+    onProgress?.({
+      action: 'migrationApply',
+      kind: 'spanStart',
+      spanId: migrationSpanId,
+      label: `Applying ${migration.dirName}`,
+    });
+
+    const operations = migration.operations as readonly MigrationPlanOperation[];
+
+    // Allow all operation classes. The policy gate belongs at plan time, not
+    // apply time — the planner already decided what to emit. Restricting here
+    // would be a tautology (the allowed set would just mirror what's in ops).
+    const policy = {
+      allowedOperationClasses: ['additive', 'widening', 'destructive'] as const,
+    };
+
+    // EMPTY_CONTRACT_HASH means "no prior state" — the runner expects origin: null
+    // for a fresh database (no marker present).
+    const plan = {
+      targetId,
+      origin: migration.from === EMPTY_CONTRACT_HASH ? null : { storageHash: migration.from },
+      destination: { storageHash: migration.to },
+      operations,
+    };
+
+    const destinationContract = familyInstance.validateContractIR(
+      migration.toContract as ContractIR,
+    );
+
+    const runnerResult: MigrationRunnerResult = await runner.execute({
+      plan,
+      driver,
+      destinationContract,
+      policy,
+      executionChecks: {
+        prechecks: true,
+        postchecks: true,
+        idempotencyChecks: true,
+      },
+      frameworkComponents,
+    });
+
+    if (!runnerResult.ok) {
+      onProgress?.({
+        action: 'migrationApply',
+        kind: 'spanEnd',
+        spanId: migrationSpanId,
+        outcome: 'error',
+      });
+      return notOk({
+        code: 'RUNNER_FAILED' as const,
+        summary: runnerResult.failure.summary,
+        why: runnerResult.failure.why,
+        meta: {
+          migration: migration.dirName,
+          from: migration.from,
+          to: migration.to,
+          ...(runnerResult.failure.meta ?? {}),
+        },
+      });
+    }
+
+    onProgress?.({
+      action: 'migrationApply',
+      kind: 'spanEnd',
+      spanId: migrationSpanId,
+      outcome: 'ok',
+    });
+
+    applied.push({
+      dirName: migration.dirName,
+      from: migration.from,
+      to: migration.to,
+      operationsExecuted: runnerResult.value.operationsExecuted,
+    });
+  }
+
+  const finalHash = pendingMigrations[pendingMigrations.length - 1]!.to;
+  const totalOps = applied.reduce((sum, a) => sum + a.operationsExecuted, 0);
+
+  return ok({
+    migrationsApplied: applied.length,
+    markerHash: finalHash,
+    applied,
+    summary: `Applied ${applied.length} migration(s) (${totalOps} operation(s)), marker at ${finalHash}`,
+  });
+}

package/src/control-api/types.ts

@@ -1,7 +1,8 @@
 import type {
   ContractSourceDiagnostics,
   ContractSourceProvider,
-} from '@prisma-next/core-control-plane/config-types';
+} from '@prisma-next/config/config-types';
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
 import type { CoreSchemaView } from '@prisma-next/core-control-plane/schema-view';
 import type {
   ControlAdapterDescriptor,
@@ -61,6 +62,7 @@ export interface ControlClientOptions {
 export type ControlActionName =
   | 'dbInit'
   | 'dbUpdate'
+  | 'migrationApply'
   | 'verify'
   | 'schemaVerify'
   | 'sign'
@@ -419,6 +421,95 @@ export interface EmitFailure {
  */
 export type EmitResult = Result<EmitSuccess, EmitFailure>;
 
+// ============================================================================
+// Migration Apply Types
+// ============================================================================
+
+/**
+ * A pre-planned migration step ready for execution.
+ * Contains the manifest metadata and the serialized operations from ops.json.
+ */
+export interface MigrationApplyStep {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly toContract: unknown;
+  readonly operations: ReadonlyArray<{
+    readonly id: string;
+    readonly label: string;
+    readonly operationClass: string;
+    readonly [key: string]: unknown;
+  }>;
+}
+
+/**
+ * Options for the migrationApply operation.
+ */
+export interface MigrationApplyOptions {
+  /**
+   * Hash of the database state this apply path starts from.
+   * This is resolved by the caller (typically the CLI orchestration layer).
+   */
+  readonly originHash: string;
+  /**
+   * Hash of the target contract this apply path must reach.
+   * This is resolved by the caller (typically the CLI orchestration layer).
+   */
+  readonly destinationHash: string;
+  /**
+   * Ordered list of migrations to execute from originHash to destinationHash.
+   * The execution layer does not choose defaults; it only executes this explicit path.
+   */
+  readonly pendingMigrations: readonly MigrationApplyStep[];
+  /**
+   * Database connection. If provided, migrationApply will connect before executing.
+   * If omitted, the client must already be connected.
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Record of a successfully applied migration.
+ */
+export interface MigrationApplyAppliedEntry {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly operationsExecuted: number;
+}
+
+/**
+ * Successful migrationApply result.
+ */
+export interface MigrationApplySuccess {
+  readonly migrationsApplied: number;
+  readonly markerHash: string;
+  readonly applied: readonly MigrationApplyAppliedEntry[];
+  readonly summary: string;
+}
+
+/**
+ * Failure codes for migrationApply operation.
+ */
+export type MigrationApplyFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
+
+/**
+ * Failure details for migrationApply operation.
+ */
+export interface MigrationApplyFailure {
+  readonly code: MigrationApplyFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+}
+
+/**
+ * Result type for migrationApply operation.
+ */
+export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyFailure>;
+
 // ============================================================================
 // Standalone Contract Emit Types
 // ============================================================================
@@ -547,6 +638,27 @@ export interface ControlClient {
    */
   dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult>;
 
+  /**
+   * Reads the contract marker from the database.
+   * Returns null if no marker exists (fresh database).
+   *
+   * @throws If not connected or infrastructure failure
+   */
+  readMarker(): Promise<ContractMarkerRecord | null>;
+
+  /**
+   * Applies pre-planned on-disk migrations to the database.
+   * Each migration runs in its own transaction with full execution checks.
+   * Resume-safe: re-running after failure picks up from the last applied migration.
+   *
+   * @param options.originHash - Explicit source hash for the apply path
+   * @param options.destinationHash - Explicit destination hash for the apply path
+   * @param options.pendingMigrations - Ordered migrations to execute
+   * @returns Result pattern: Ok with applied details, NotOk with failure details
+   * @throws If not connected, target doesn't support migrations, or infrastructure failure
+   */
+  migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult>;
+
   /**
    * Introspects the database schema.
    *

package/src/exports/config-types.ts

@@ -1,6 +1,6 @@
-// Re-export core-control-plane config types for convenience
+// Re-export config package types for convenience
 export type {
   ContractConfig,
   PrismaNextConfig,
-} from '@prisma-next/core-control-plane/config-types';
-export { defineConfig } from '@prisma-next/core-control-plane/config-types';
+} from '@prisma-next/config/config-types';
+export { defineConfig } from '@prisma-next/config/config-types';

package/src/utils/command-helpers.ts

@@ -1,4 +1,5 @@
 import type { Command } from 'commander';
+import { resolve } from 'pathe';
 
 const longDescriptions = new WeakMap<Command, string>();
 
@@ -46,6 +47,16 @@ export interface MigrationCommandOptions {
   readonly 'no-color'?: boolean;
 }
 
+/**
+ * Resolves the absolute path to contract.json from the config.
+ * Centralises the fallback logic shared by every command that reads the contract.
+ */
+export function resolveContractPath(config: { contract?: { output?: string } }): string {
+  return config.contract?.output
+    ? resolve(config.contract.output)
+    : resolve('src/prisma/contract.json');
+}
+
 /**
  * Masks credentials in a database connection URL.
  * Handles standard URLs (username + password + query params) and libpq-style key=value strings.

package/src/utils/migration-command-scaffold.ts

@@ -14,7 +14,7 @@ import {
   errorTargetMigrationNotSupported,
   errorUnexpected,
 } from './cli-errors';
-import { maskConnectionUrl } from './command-helpers';
+import { maskConnectionUrl, resolveContractPath } from './command-helpers';
 import type { GlobalFlags } from './global-flags';
 import { formatStyledHeader } from './output';
 import { createProgressAdapter } from './progress-adapter';
@@ -61,9 +61,7 @@ export async function prepareMigrationContext(
   const configPath = options.config
     ? relative(process.cwd(), resolve(options.config))
     : 'prisma-next.config.ts';
-  const contractPathAbsolute = config.contract?.output
-    ? resolve(config.contract.output)
-    : resolve('src/prisma/contract.json');
+  const contractPathAbsolute = resolveContractPath(config);
   const contractPath = relative(process.cwd(), contractPathAbsolute);
 
   // Output header
@@ -138,8 +136,11 @@ export async function prepareMigrationContext(
     );
   }
 
-  // Check target supports migrations
-  if (!config.target.migrations) {
+  // Check target supports migrations via optional descriptor capability
+  const targetWithMigrations = config.target as typeof config.target & {
+    readonly migrations?: unknown;
+  };
+  if (!targetWithMigrations.migrations) {
     return notOk(
       errorTargetMigrationNotSupported({
         why: `Target "${config.target.id}" does not support migrations`,