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

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

@@ -5,12 +5,14 @@ import type {
   ControlFamilyInstance,
   MigrationPlan,
   MigrationPlannerResult,
-  MigrationPlanOperation,
   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 { DbInitResult, DbInitSuccess, OnControlProgress } from '../types';
+import { extractSqlDdl } from './extract-sql-ddl';
+import { createOperationCallbacks, stripOperations } from './migration-helpers';
 
 /**
  * Options for executing dbInit operation.
@@ -114,7 +116,7 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     action: 'dbInit',
     kind: 'spanStart',
     spanId: checkMarkerSpanId,
-    label: 'Checking contract marker',
+    label: 'Checking database signature',
   });
   const existingMarker = await familyInstance.readMarker({ driver });
   if (existingMarker) {
@@ -134,15 +136,23 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
       const result: DbInitSuccess = {
         mode,
         plan: { operations: [] },
-        ...(mode === 'apply'
-          ? {
-              execution: { operationsPlanned: 0, operationsExecuted: 0 },
-              marker: {
+        destination: {
+          storageHash: migrationPlan.destination.storageHash,
+          ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+        },
+        ...ifDefined(
+          'execution',
+          mode === 'apply' ? { operationsPlanned: 0, operationsExecuted: 0 } : undefined,
+        ),
+        ...ifDefined(
+          'marker',
+          mode === 'apply'
+            ? {
                 storageHash: existingMarker.storageHash,
                 profileHash: existingMarker.profileHash,
-              },
-            }
-          : {}),
+              }
+            : undefined,
+        ),
         summary: 'Database already at target contract state',
       };
       return ok(result);
@@ -181,9 +191,18 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
 
   // Plan mode - don't execute
   if (mode === 'plan') {
+    const planSql =
+      familyInstance.familyId === 'sql' ? extractSqlDdl(migrationPlan.operations) : undefined;
     const result: DbInitSuccess = {
       mode: 'plan',
-      plan: { operations: migrationPlan.operations },
+      plan: {
+        operations: stripOperations(migrationPlan.operations),
+        ...ifDefined('sql', planSql),
+      },
+      destination: {
+        storageHash: migrationPlan.destination.storageHash,
+        ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+      },
       summary: `Planned ${migrationPlan.operations.length} operation(s)`,
     };
     return ok(result);
@@ -198,34 +217,14 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     label: 'Applying migration plan',
   });
 
-  const callbacks = onProgress
-    ? {
-        onOperationStart: (op: MigrationPlanOperation) => {
-          onProgress({
-            action: 'dbInit',
-            kind: 'spanStart',
-            spanId: `operation:${op.id}`,
-            parentSpanId: applySpanId,
-            label: op.label,
-          });
-        },
-        onOperationComplete: (op: MigrationPlanOperation) => {
-          onProgress({
-            action: 'dbInit',
-            kind: 'spanEnd',
-            spanId: `operation:${op.id}`,
-            outcome: 'ok',
-          });
-        },
-      }
-    : undefined;
+  const callbacks = createOperationCallbacks(onProgress, 'dbInit', applySpanId);
 
   const runnerResult: MigrationRunnerResult = await runner.execute({
     plan: migrationPlan,
     driver,
     destinationContract: contractIR,
     policy,
-    ...(callbacks ? { callbacks } : {}),
+    ...ifDefined('callbacks', callbacks),
     // db init plans and applies back-to-back from a fresh introspection, so per-operation
     // pre/postchecks and the idempotency probe are usually redundant overhead. We still
     // enforce marker/origin compatibility and a full schema verification after apply.
@@ -264,7 +263,13 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
 
   const result: DbInitSuccess = {
     mode: 'apply',
-    plan: { operations: migrationPlan.operations },
+    plan: {
+      operations: stripOperations(migrationPlan.operations),
+    },
+    destination: {
+      storageHash: migrationPlan.destination.storageHash,
+      ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+    },
     execution: {
       operationsPlanned: execution.operationsPlanned,
       operationsExecuted: execution.operationsExecuted,
@@ -275,7 +280,7 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
           profileHash: migrationPlan.destination.profileHash,
         }
       : { storageHash: migrationPlan.destination.storageHash },
-    summary: `Applied ${execution.operationsExecuted} operation(s), marker written`,
+    summary: `Applied ${execution.operationsExecuted} operation(s), database signed`,
   };
   return ok(result);
 }

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: 'Use --plan to preview destructive operations, then re-run with --accept-data-loss to apply',
+        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-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',
+      });
+    },
+  };
+}

package/src/control-api/types.ts

@@ -60,6 +60,7 @@ export interface ControlClientOptions {
  */
 export type ControlActionName =
   | 'dbInit'
+  | 'dbUpdate'
   | 'verify'
   | 'schemaVerify'
   | 'sign'
@@ -189,6 +190,36 @@ export interface DbInitOptions {
   readonly onProgress?: OnControlProgress;
 }
 
+/**
+ * Options for the dbUpdate operation.
+ */
+export interface DbUpdateOptions {
+  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
+  readonly contractIR: unknown;
+  /**
+   * Mode for the dbUpdate operation.
+   * - 'plan': Returns planned operations without applying
+   * - 'apply': Applies operations and writes marker/ledger
+   */
+  readonly mode: 'plan' | 'apply';
+  /**
+   * Database connection. If provided, dbUpdate will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /**
+   * When true, allows applying plans that contain destructive operations
+   * (e.g., DROP TABLE, DROP COLUMN, ALTER TYPE).
+   * When false (default), the operation returns a failure if the plan
+   * includes destructive operations, prompting the user to use --plan
+   * to preview and then re-run with --accept-data-loss.
+   */
+  readonly acceptDataLoss?: boolean;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
 /**
  * Options for the introspect operation.
  */
@@ -249,6 +280,11 @@ export interface DbInitSuccess {
       readonly label: string;
       readonly operationClass: string;
     }>;
+    readonly sql?: ReadonlyArray<string>;
+  };
+  readonly destination: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
   };
   readonly execution?: {
     readonly operationsPlanned: number;
@@ -291,6 +327,56 @@ export interface DbInitFailure {
  */
 export type DbInitResult = Result<DbInitSuccess, DbInitFailure>;
 
+/**
+ * Successful dbUpdate result.
+ */
+export interface DbUpdateSuccess {
+  readonly mode: 'plan' | 'apply';
+  readonly plan: {
+    readonly operations: ReadonlyArray<{
+      readonly id: string;
+      readonly label: string;
+      readonly operationClass: string;
+    }>;
+    readonly sql?: ReadonlyArray<string>;
+  };
+  readonly destination: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly execution?: {
+    readonly operationsPlanned: number;
+    readonly operationsExecuted: number;
+  };
+  readonly marker?: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly summary: string;
+}
+
+/**
+ * Failure codes for dbUpdate operation.
+ */
+export type DbUpdateFailureCode = 'PLANNING_FAILED' | 'RUNNER_FAILED' | 'DESTRUCTIVE_CHANGES';
+
+/**
+ * Failure details for dbUpdate operation.
+ */
+export interface DbUpdateFailure {
+  readonly code: DbUpdateFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+}
+
+/**
+ * Result type for dbUpdate operation.
+ * Uses Result pattern: success returns DbUpdateSuccess, failure returns DbUpdateFailure.
+ */
+export type DbUpdateResult = Result<DbUpdateSuccess, DbUpdateFailure>;
+
 /**
  * Successful emit result.
  * Contains the hashes and paths of emitted files.
@@ -311,7 +397,10 @@ export interface EmitSuccess {
 /**
  * Failure codes for emit operation.
  */
-export type EmitFailureCode = 'CONTRACT_SOURCE_INVALID' | 'EMIT_FAILED';
+export type EmitFailureCode =
+  | 'CONTRACT_SOURCE_INVALID'
+  | 'CONTRACT_VALIDATION_FAILED'
+  | 'EMIT_FAILED';
 
 /**
  * Failure details for emit operation.
@@ -428,9 +517,9 @@ export interface ControlClient {
   schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult>;
 
   /**
-   * Signs the database with a contract marker.
-   * Writes or updates the contract marker if schema verification passes.
-   * Idempotent (no-op if marker already matches).
+   * Signs the database with a contract signature.
+   * Writes or updates the signature if schema verification passes.
+   * Idempotent (no-op if signature already matches).
    *
    * @returns Structured result
    * @throws If not connected or infrastructure failure
@@ -447,6 +536,17 @@ export interface ControlClient {
    */
   dbInit(options: DbInitOptions): Promise<DbInitResult>;
 
+  /**
+   * Updates a database schema to match the current contract.
+   * Creates the signature table if it does not exist. No preconditions required.
+   * Allows additive, widening, and destructive operation classes.
+   *
+   * @param options.mode - 'plan' to preview, 'apply' to execute
+   * @returns Result pattern: Ok with planned/executed operations, NotOk with failure details
+   * @throws If not connected, target doesn't support migrations, or infrastructure failure
+   */
+  dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult>;
+
   /**
    * Introspects the database schema.
    *

package/src/exports/control-api.ts

@@ -34,6 +34,11 @@ export type {
   DbInitOptions,
   DbInitResult,
   DbInitSuccess,
+  DbUpdateFailure,
+  DbUpdateFailureCode,
+  DbUpdateOptions,
+  DbUpdateResult,
+  DbUpdateSuccess,
   EmitContractConfig,
   EmitFailure,
   EmitFailureCode,

package/src/utils/cli-errors.ts

@@ -11,6 +11,7 @@ export {
   errorContractMissingExtensionPacks,
   errorContractValidationFailed,
   errorDatabaseConnectionRequired,
+  errorDestructiveChanges,
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
@@ -19,6 +20,7 @@ export {
   errorMarkerMissing,
   errorMigrationPlanningFailed,
   errorQueryRunnerFactoryRequired,
+  errorRunnerFailed,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorTargetMismatch,