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

package/src/commands/db-update.ts

@@ -0,0 +1,220 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { Command } from 'commander';
+import { ContractValidationError } from '../control-api/errors';
+import type { DbUpdateFailure } from '../control-api/types';
+import {
+  CliStructuredError,
+  errorContractValidationFailed,
+  errorDestructiveChanges,
+  errorJsonFormatNotSupported,
+  errorMigrationPlanningFailed,
+  errorRunnerFailed,
+  errorUnexpected,
+} from '../utils/cli-errors';
+import type { MigrationCommandOptions } from '../utils/command-helpers';
+import { sanitizeErrorMessage, setCommandDescriptions } from '../utils/command-helpers';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import {
+  addMigrationCommandOptions,
+  prepareMigrationContext,
+} from '../utils/migration-command-scaffold';
+import {
+  formatCommandHelp,
+  formatMigrationApplyOutput,
+  formatMigrationJson,
+  formatMigrationPlanOutput,
+  type MigrationCommandResult,
+} from '../utils/output';
+import { handleResult } from '../utils/result-handler';
+
+type DbUpdateOptions = MigrationCommandOptions & {
+  readonly acceptDataLoss?: boolean;
+};
+
+/**
+ * Maps a DbUpdateFailure to a CliStructuredError for consistent error handling.
+ */
+function mapDbUpdateFailure(failure: DbUpdateFailure): CliStructuredError {
+  if (failure.code === 'PLANNING_FAILED') {
+    return errorMigrationPlanningFailed({ conflicts: failure.conflicts ?? [] });
+  }
+
+  if (failure.code === 'RUNNER_FAILED') {
+    return errorRunnerFailed(failure.summary, {
+      why: failure.why ?? 'Migration runner failed',
+      fix: 'Inspect the reported conflict, reconcile schema drift if needed, then re-run `prisma-next db update`',
+      ...ifDefined('meta', failure.meta),
+    });
+  }
+
+  if (failure.code === 'DESTRUCTIVE_CHANGES') {
+    return errorDestructiveChanges(failure.summary, {
+      ...ifDefined('why', failure.why),
+      fix: 'Use `prisma-next db update --plan` to preview, then re-run with `--accept-data-loss` to apply destructive changes',
+      ...ifDefined('meta', failure.meta),
+    });
+  }
+
+  const exhaustive: never = failure.code;
+  throw new Error(`Unhandled DbUpdateFailure code: ${exhaustive}`);
+}
+
+/**
+ * Executes the db update command and returns a structured Result.
+ */
+async function executeDbUpdateCommand(
+  options: DbUpdateOptions,
+  flags: GlobalFlags,
+  startTime: number,
+): Promise<Result<MigrationCommandResult, CliStructuredError>> {
+  // Prepare shared migration context (config, contract, connection, client)
+  const ctxResult = await prepareMigrationContext(options, flags, {
+    commandName: 'db update',
+    description: 'Update your database schema to match your contract',
+    url: 'https://pris.ly/db-update',
+  });
+  if (!ctxResult.ok) {
+    return ctxResult;
+  }
+  const { client, contractJson, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
+
+  try {
+    // Call dbUpdate with connection and progress callback
+    const result = await client.dbUpdate({
+      contractIR: contractJson,
+      mode: options.plan ? 'plan' : 'apply',
+      connection: dbConnection,
+      ...(options.acceptDataLoss ? { acceptDataLoss: true } : {}),
+      onProgress,
+    });
+
+    // Handle failures by mapping to CLI structured error
+    if (!result.ok) {
+      return notOk(mapDbUpdateFailure(result.failure));
+    }
+
+    // Convert success result to CLI output format
+    const dbUpdateResult: MigrationCommandResult = {
+      ok: true,
+      mode: result.value.mode,
+      plan: {
+        targetId: ctxResult.value.config.target.targetId,
+        destination: {
+          storageHash: result.value.destination.storageHash,
+          ...ifDefined('profileHash', result.value.destination.profileHash),
+        },
+        operations: result.value.plan.operations.map((op) => ({
+          id: op.id,
+          label: op.label,
+          operationClass: op.operationClass,
+        })),
+        ...ifDefined('sql', result.value.plan.sql),
+      },
+      ...ifDefined(
+        'execution',
+        result.value.execution
+          ? {
+              operationsPlanned: result.value.execution.operationsPlanned,
+              operationsExecuted: result.value.execution.operationsExecuted,
+            }
+          : undefined,
+      ),
+      ...ifDefined(
+        'marker',
+        result.value.marker
+          ? {
+              storageHash: result.value.marker.storageHash,
+              ...ifDefined('profileHash', result.value.marker.profileHash),
+            }
+          : undefined,
+      ),
+      summary: result.value.summary,
+      timings: { total: Date.now() - startTime },
+    };
+
+    return ok(dbUpdateResult);
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+
+    if (error instanceof ContractValidationError) {
+      return notOk(
+        errorContractValidationFailed(`Contract validation failed: ${error.message}`, {
+          where: { path: contractPathAbsolute },
+        }),
+      );
+    }
+
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const safeMessage = sanitizeErrorMessage(
+      rawMessage,
+      typeof dbConnection === 'string' ? dbConnection : undefined,
+    );
+    return notOk(
+      errorUnexpected(safeMessage, {
+        why: `Unexpected error during db update: ${safeMessage}`,
+      }),
+    );
+  } finally {
+    await client.close();
+  }
+}
+
+export function createDbUpdateCommand(): Command {
+  const command = new Command('update');
+  setCommandDescriptions(
+    command,
+    'Update your database schema to match your contract',
+    'Compares your database schema to the emitted contract and applies the necessary\n' +
+      'changes. Works on any database, whether or not it has been initialized with `db init`.\n' +
+      'Use --plan to preview operations before applying.',
+  );
+  addMigrationCommandOptions(command);
+  command.option(
+    '--accept-data-loss',
+    'Confirm destructive operations (required when plan includes drops or type changes)',
+    false,
+  );
+  command.configureHelp({
+    formatHelp: (cmd) => {
+      const flags = parseGlobalFlags({});
+      return formatCommandHelp({ command: cmd, flags });
+    },
+  });
+  command.action(async (options: DbUpdateOptions) => {
+    const flags = parseGlobalFlags(options);
+    const startTime = Date.now();
+
+    if (flags.json === 'ndjson') {
+      const result = notOk(
+        errorJsonFormatNotSupported({
+          command: 'db update',
+          format: 'ndjson',
+          supportedFormats: ['object'],
+        }),
+      );
+      const exitCode = handleResult(result, flags);
+      process.exit(exitCode);
+    }
+
+    const result = await executeDbUpdateCommand(options, flags, startTime);
+    const exitCode = handleResult(result, flags, (dbUpdateResult) => {
+      if (flags.json === 'object') {
+        console.log(formatMigrationJson(dbUpdateResult));
+      } else {
+        const output =
+          dbUpdateResult.mode === 'plan'
+            ? formatMigrationPlanOutput(dbUpdateResult, flags)
+            : formatMigrationApplyOutput(dbUpdateResult, flags);
+        if (output) {
+          console.log(output);
+        }
+      }
+    });
+    process.exit(exitCode);
+  });
+
+  return command;
+}

package/src/commands/db-verify.ts

@@ -6,6 +6,7 @@ import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
+import { ContractValidationError } from '../control-api/errors';
 import {
   CliStructuredError,
   errorContractValidationFailed,
@@ -19,7 +20,7 @@ import {
   errorTargetMismatch,
   errorUnexpected,
 } from '../utils/cli-errors';
-import { setCommandDescriptions } from '../utils/command-helpers';
+import { maskConnectionUrl, setCommandDescriptions } from '../utils/command-helpers';
 import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
 import {
   formatCommandHelp,
@@ -94,7 +95,7 @@ async function executeDbVerifyCommand(
       { label: 'contract', value: contractPath },
     ];
     if (options.db) {
-      details.push({ label: 'database', value: options.db });
+      details.push({ label: 'database', value: maskConnectionUrl(options.db) });
     }
     const header = formatStyledHeader({
       command: 'db verify',
@@ -189,6 +190,14 @@ async function executeDbVerifyCommand(
       return notOk(error);
     }
 
+    if (error instanceof ContractValidationError) {
+      return notOk(
+        errorContractValidationFailed(`Contract validation failed: ${error.message}`, {
+          where: { path: contractPathAbsolute },
+        }),
+      );
+    }
+
     // Wrap unexpected errors
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {

package/src/control-api/client.ts

@@ -1,4 +1,5 @@
 import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
 import type { CoreSchemaView } from '@prisma-next/core-control-plane/schema-view';
 import { createControlPlaneStack } from '@prisma-next/core-control-plane/stack';
 import type {
@@ -12,15 +13,21 @@ import type {
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
+import { ContractValidationError } from './errors';
 import { executeDbInit } from './operations/db-init';
+import { executeDbUpdate } from './operations/db-update';
 import type {
+  ControlActionName,
   ControlClient,
   ControlClientOptions,
   DbInitOptions,
   DbInitResult,
+  DbUpdateOptions,
+  DbUpdateResult,
   EmitOptions,
   EmitResult,
   IntrospectOptions,
+  OnControlProgress,
   SchemaVerifyOptions,
   SignOptions,
   VerifyOptions,
@@ -152,47 +159,47 @@ class ControlClientImpl implements ControlClient {
     };
   }
 
-  async verify(options: VerifyOptions): Promise<VerifyDatabaseResult> {
-    const { onProgress } = options;
-
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'verify',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'verify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'verify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
+  private async connectWithProgress(
+    connection: unknown | undefined,
+    action: ControlActionName,
+    onProgress?: OnControlProgress,
+  ): Promise<void> {
+    if (connection === undefined) return;
+    onProgress?.({
+      action,
+      kind: 'spanStart',
+      spanId: 'connect',
+      label: 'Connecting to database...',
+    });
+    try {
+      await this.connect(connection);
+      onProgress?.({ action, kind: 'spanEnd', spanId: 'connect', outcome: 'ok' });
+    } catch (error) {
+      onProgress?.({ action, kind: 'spanEnd', spanId: 'connect', outcome: 'error' });
+      throw error;
     }
+  }
 
+  async verify(options: VerifyOptions): Promise<VerifyDatabaseResult> {
+    const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'verify', onProgress);
     const { driver, familyInstance } = await this.ensureConnected();
 
     // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contractIR: ContractIR;
+    try {
+      contractIR = familyInstance.validateContractIR(options.contractIR);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
     // Emit verify span
     onProgress?.({
       action: 'verify',
       kind: 'spanStart',
       spanId: 'verify',
-      label: 'Verifying contract marker...',
+      label: 'Verifying database signature...',
     });
 
     try {
@@ -228,38 +235,17 @@ class ControlClientImpl implements ControlClient {
 
   async schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult> {
     const { onProgress } = options;
-
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'schemaVerify',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'schemaVerify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'schemaVerify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
-    }
-
+    await this.connectWithProgress(options.connection, 'schemaVerify', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contractIR: ContractIR;
+    try {
+      contractIR = familyInstance.validateContractIR(options.contractIR);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
     // Emit schemaVerify span
     onProgress?.({
@@ -300,38 +286,17 @@ class ControlClientImpl implements ControlClient {
 
   async sign(options: SignOptions): Promise<SignDatabaseResult> {
     const { onProgress } = options;
-
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'sign',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'sign',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'sign',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
-    }
-
+    await this.connectWithProgress(options.connection, 'sign', onProgress);
     const { driver, familyInstance } = await this.ensureConnected();
 
     // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contractIR: ContractIR;
+    try {
+      contractIR = familyInstance.validateContractIR(options.contractIR);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
     // Emit sign span
     onProgress?.({
@@ -371,34 +336,7 @@ class ControlClientImpl implements ControlClient {
 
   async dbInit(options: DbInitOptions): Promise<DbInitResult> {
     const { onProgress } = options;
-
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'dbInit',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'dbInit',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'dbInit',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
-    }
-
+    await this.connectWithProgress(options.connection, 'dbInit', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     // Check target supports migrations
@@ -407,7 +345,13 @@ class ControlClientImpl implements ControlClient {
     }
 
     // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contractIR: ContractIR;
+    try {
+      contractIR = familyInstance.validateContractIR(options.contractIR);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
     // Delegate to extracted dbInit operation
     return executeDbInit({
@@ -417,40 +361,42 @@ class ControlClientImpl implements ControlClient {
       mode: options.mode,
       migrations: this.options.target.migrations,
       frameworkComponents,
-      ...(onProgress ? { onProgress } : {}),
+      ...ifDefined('onProgress', onProgress),
     });
   }
 
-  async introspect(options?: IntrospectOptions): Promise<unknown> {
-    const onProgress = options?.onProgress;
+  async dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult> {
+    const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'dbUpdate', onProgress);
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
-    // Connect with progress span if connection provided
-    if (options?.connection !== undefined) {
-      onProgress?.({
-        action: 'introspect',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'introspect',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'introspect',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
+    if (!this.options.target.migrations) {
+      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
+    let contractIR: ContractIR;
+    try {
+      contractIR = familyInstance.validateContractIR(options.contractIR);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
+
+    return executeDbUpdate({
+      driver,
+      familyInstance,
+      contractIR,
+      mode: options.mode,
+      migrations: this.options.target.migrations,
+      frameworkComponents,
+      ...ifDefined('acceptDataLoss', options.acceptDataLoss),
+      ...ifDefined('onProgress', onProgress),
+    });
+  }
+
+  async introspect(options?: IntrospectOptions): Promise<unknown> {
+    const onProgress = options?.onProgress;
+    await this.connectWithProgress(options?.connection, 'introspect', onProgress);
     const { driver, familyInstance } = await this.ensureConnected();
 
     // TODO: Pass schema option to familyInstance.introspect when schema filtering is implemented
@@ -575,6 +521,24 @@ class ControlClientImpl implements ControlClient {
     });
 
     try {
+      try {
+        this.familyInstance.validateContractIR(contractRaw);
+      } catch (error) {
+        onProgress?.({
+          action: 'emit',
+          kind: 'spanEnd',
+          spanId: 'emit',
+          outcome: 'error',
+        });
+        const message = error instanceof Error ? error.message : String(error);
+        return notOk({
+          code: 'CONTRACT_VALIDATION_FAILED',
+          summary: 'Contract validation failed',
+          why: message,
+          meta: undefined,
+        });
+      }
+
       const emitResult = await this.familyInstance.emitContract({ contractIR: contractRaw });
 
       onProgress?.({

package/src/control-api/errors.ts

@@ -0,0 +1,9 @@
+export class ContractValidationError extends Error {
+  override readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = 'ContractValidationError';
+    this.cause = cause;
+  }
+}