@prisma-next/cli 0.3.0-dev.12 → 0.3.0-dev.123

package/src/control-api/operations/db-update.ts

@@ -0,0 +1,221 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  MigrationPlannerResult,
+  MigrationRunnerResult,
+  TargetMigrationsCapability,
+} from '@prisma-next/core-control-plane/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { notOk, ok } from '@prisma-next/utils/result';
+import type { DbUpdateResult, DbUpdateSuccess, OnControlProgress } from '../types';
+import { extractSqlDdl } from './extract-sql-ddl';
+import { createOperationCallbacks, stripOperations } from './migration-helpers';
+
+// F12: db update allows additive, widening, and destructive operations.
+const DB_UPDATE_POLICY = {
+  allowedOperationClasses: ['additive', 'widening', 'destructive'] as const,
+} as const;
+
+/**
+ * Options for the executeDbUpdate operation.
+ * Config-agnostic: receives pre-resolved driver, family, contract, and migrations capability.
+ */
+export interface ExecuteDbUpdateOptions<TFamilyId extends string, TTargetId extends string> {
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId>;
+  readonly contractIR: ContractIR;
+  readonly mode: 'plan' | 'apply';
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly acceptDataLoss?: boolean;
+  /** Optional progress callback for observing operation progress. */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Executes the db update operation: introspect → plan → (optionally) apply → marker.
+ *
+ * db update is a pure reconciliation command: it introspects the live schema, plans the diff
+ * to the destination contract, and applies operations. The marker is bookkeeping only — written
+ * after apply so that `verify` and `db init` can reference it, but never read or validated
+ * by db update itself. The runner creates the marker table if it does not exist.
+ */
+export async function executeDbUpdate<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteDbUpdateOptions<TFamilyId, TTargetId>,
+): Promise<DbUpdateResult> {
+  const { driver, familyInstance, contractIR, mode, migrations, frameworkComponents, onProgress } =
+    options;
+
+  const planner = migrations.createPlanner(familyInstance);
+  const runner = migrations.createRunner(familyInstance);
+
+  const introspectSpanId = 'introspect';
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanStart',
+    spanId: introspectSpanId,
+    label: 'Introspecting database schema',
+  });
+  const schemaIR = await familyInstance.introspect({ driver });
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanEnd',
+    spanId: introspectSpanId,
+    outcome: 'ok',
+  });
+
+  const policy = DB_UPDATE_POLICY;
+
+  const planSpanId = 'plan';
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanStart',
+    spanId: planSpanId,
+    label: 'Planning migration',
+  });
+  const plannerResult: MigrationPlannerResult = await planner.plan({
+    contract: contractIR,
+    schema: schemaIR,
+    policy,
+    frameworkComponents,
+  });
+  if (plannerResult.kind === 'failure') {
+    onProgress?.({
+      action: 'dbUpdate',
+      kind: 'spanEnd',
+      spanId: planSpanId,
+      outcome: 'error',
+    });
+    return notOk({
+      code: 'PLANNING_FAILED',
+      summary: 'Migration planning failed due to conflicts',
+      conflicts: plannerResult.conflicts,
+      why: undefined,
+      meta: undefined,
+    });
+  }
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanEnd',
+    spanId: planSpanId,
+    outcome: 'ok',
+  });
+
+  const migrationPlan = plannerResult.plan;
+
+  if (mode === 'plan') {
+    const planSql =
+      familyInstance.familyId === 'sql' ? extractSqlDdl(migrationPlan.operations) : undefined;
+    const result: DbUpdateSuccess = {
+      mode: 'plan',
+      plan: {
+        operations: stripOperations(migrationPlan.operations),
+        ...(planSql !== undefined ? { sql: planSql } : {}),
+      },
+      destination: {
+        storageHash: migrationPlan.destination.storageHash,
+        ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+      },
+      summary: `Planned ${migrationPlan.operations.length} operation(s)`,
+    };
+    return ok(result);
+  }
+
+  // When applying, require explicit acceptance for destructive operations
+  if (!options.acceptDataLoss) {
+    const destructiveOps = migrationPlan.operations
+      .filter((op) => op.operationClass === 'destructive')
+      .map((op) => ({ id: op.id, label: op.label }));
+    if (destructiveOps.length > 0) {
+      return notOk({
+        code: 'DESTRUCTIVE_CHANGES',
+        summary: `Planned ${destructiveOps.length} destructive operation(s) that require confirmation`,
+        why: 'Destructive operations require confirmation — re-run with -y to accept',
+        conflicts: undefined,
+        meta: { destructiveOperations: destructiveOps },
+      });
+    }
+  }
+
+  const applySpanId = 'apply';
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanStart',
+    spanId: applySpanId,
+    label: 'Applying migration plan',
+  });
+
+  const callbacks = createOperationCallbacks(onProgress, 'dbUpdate', applySpanId);
+
+  const runnerResult: MigrationRunnerResult = await runner.execute({
+    plan: migrationPlan,
+    driver,
+    destinationContract: contractIR,
+    policy,
+    ...(callbacks ? { callbacks } : {}),
+    // db update plans and applies from a single introspection pass, so per-operation pre/postchecks
+    // and idempotency probes are intentionally disabled to avoid redundant roundtrips.
+    executionChecks: {
+      prechecks: false,
+      postchecks: false,
+      idempotencyChecks: false,
+    },
+    frameworkComponents,
+  });
+
+  if (!runnerResult.ok) {
+    onProgress?.({
+      action: 'dbUpdate',
+      kind: 'spanEnd',
+      spanId: applySpanId,
+      outcome: 'error',
+    });
+    return notOk({
+      code: 'RUNNER_FAILED',
+      summary: runnerResult.failure.summary,
+      why: runnerResult.failure.why,
+      meta: runnerResult.failure.meta,
+      conflicts: undefined,
+    });
+  }
+
+  const execution = runnerResult.value;
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanEnd',
+    spanId: applySpanId,
+    outcome: 'ok',
+  });
+
+  const result: DbUpdateSuccess = {
+    mode: 'apply',
+    plan: {
+      operations: stripOperations(migrationPlan.operations),
+    },
+    destination: {
+      storageHash: migrationPlan.destination.storageHash,
+      ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+    },
+    execution: {
+      operationsPlanned: execution.operationsPlanned,
+      operationsExecuted: execution.operationsExecuted,
+    },
+    marker: migrationPlan.destination.profileHash
+      ? {
+          storageHash: migrationPlan.destination.storageHash,
+          profileHash: migrationPlan.destination.profileHash,
+        }
+      : { storageHash: migrationPlan.destination.storageHash },
+    summary:
+      execution.operationsExecuted === 0
+        ? 'Database already matches contract, signature updated'
+        : `Applied ${execution.operationsExecuted} operation(s), signature updated`,
+  };
+  return ok(result);
+}

package/src/control-api/operations/extract-sql-ddl.ts

@@ -0,0 +1,47 @@
+import type { MigrationPlanOperation } from '@prisma-next/core-control-plane/types';
+
+/**
+ * Shape of an SQL execute step on SqlMigrationPlanOperation.
+ * Used for runtime type narrowing without importing the concrete SQL type.
+ */
+interface SqlExecuteStep {
+  readonly sql: string;
+}
+
+function isDdlStatement(sqlStatement: string): boolean {
+  const trimmed = sqlStatement.trim().toLowerCase();
+  return (
+    trimmed.startsWith('create ') || trimmed.startsWith('alter ') || trimmed.startsWith('drop ')
+  );
+}
+
+function hasExecuteSteps(
+  operation: MigrationPlanOperation,
+): operation is MigrationPlanOperation & { readonly execute: readonly SqlExecuteStep[] } {
+  const candidate = operation as unknown as Record<string, unknown>;
+  if (!('execute' in candidate) || !Array.isArray(candidate['execute'])) {
+    return false;
+  }
+  return candidate['execute'].every(
+    (step: unknown) => typeof step === 'object' && step !== null && 'sql' in step,
+  );
+}
+
+/**
+ * Extracts a best-effort SQL DDL preview for CLI plan output.
+ * This helper is presentation-only and is never used to decide migration correctness.
+ */
+export function extractSqlDdl(operations: readonly MigrationPlanOperation[]): string[] {
+  const statements: string[] = [];
+  for (const operation of operations) {
+    if (!hasExecuteSteps(operation)) {
+      continue;
+    }
+    for (const step of operation.execute) {
+      if (typeof step.sql === 'string' && isDdlStatement(step.sql)) {
+        statements.push(step.sql.trim());
+      }
+    }
+  }
+  return statements;
+}

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

@@ -0,0 +1,194 @@
+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,
+  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;
+
+    // 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/operations/migration-helpers.ts

@@ -0,0 +1,49 @@
+import type { MigrationPlanOperation } from '@prisma-next/core-control-plane/types';
+import type { ControlActionName, OnControlProgress } from '../types';
+
+/**
+ * Strips operation objects to their public shape (id, label, operationClass).
+ * Used at the API boundary to avoid leaking internal fields (precheck, execute, postcheck, etc.).
+ */
+export function stripOperations(
+  operations: readonly MigrationPlanOperation[],
+): ReadonlyArray<{ readonly id: string; readonly label: string; readonly operationClass: string }> {
+  return operations.map((op) => ({
+    id: op.id,
+    label: op.label,
+    operationClass: op.operationClass,
+  }));
+}
+
+/**
+ * Creates per-operation progress callbacks for the runner.
+ * Returns undefined when no onProgress callback is provided.
+ */
+export function createOperationCallbacks(
+  onProgress: OnControlProgress | undefined,
+  action: ControlActionName,
+  parentSpanId: string,
+) {
+  if (!onProgress) {
+    return undefined;
+  }
+  return {
+    onOperationStart: (op: MigrationPlanOperation) => {
+      onProgress({
+        action,
+        kind: 'spanStart',
+        spanId: `operation:${op.id}`,
+        parentSpanId,
+        label: op.label,
+      });
+    },
+    onOperationComplete: (op: MigrationPlanOperation) => {
+      onProgress({
+        action,
+        kind: 'spanEnd',
+        spanId: `operation:${op.id}`,
+        outcome: 'ok',
+      });
+    },
+  };
+}