@prisma-next/cli 0.3.0-dev.7 → 0.3.0-dev.70

package/src/commands/db-sign.ts

@@ -1,25 +1,29 @@
 import { readFile } from 'node:fs/promises';
 import { relative, resolve } from 'node:path';
-import {
-  errorDatabaseUrlRequired,
-  errorDriverRequired,
-  errorFileNotFound,
-  errorRuntime,
-  errorUnexpected,
-} from '@prisma-next/core-control-plane/errors';
 import type {
   SignDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/core-control-plane/types';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
-import { performAction } from '../utils/action';
-import { setCommandDescriptions } from '../utils/command-helpers';
+import { createControlClient } from '../control-api/client';
+import { ContractValidationError } from '../control-api/errors';
+import {
+  CliStructuredError,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFileNotFound,
+  errorJsonFormatNotSupported,
+  errorUnexpected,
+} from '../utils/cli-errors';
 import {
-  assertContractRequirementsSatisfied,
-  assertFrameworkComponentsCompatible,
-} from '../utils/framework-components';
-import { parseGlobalFlags } from '../utils/global-flags';
+  maskConnectionUrl,
+  resolveContractPath,
+  setCommandDescriptions,
+} from '../utils/command-helpers';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
 import {
   formatCommandHelp,
   formatSchemaVerifyJson,
@@ -28,8 +32,8 @@ import {
   formatSignOutput,
   formatStyledHeader,
 } from '../utils/output';
+import { createProgressAdapter } from '../utils/progress-adapter';
 import { handleResult } from '../utils/result-handler';
-import { withSpinner } from '../utils/spinner';
 
 interface DbSignOptions {
   readonly db?: string;
@@ -46,14 +50,172 @@ interface DbSignOptions {
   readonly 'no-color'?: boolean;
 }
 
+/**
+ * Failure type for db sign command.
+ * Either an infrastructure error (CliStructuredError) or a logical failure (schema verification failed).
+ */
+type DbSignFailure = CliStructuredError | VerifyDatabaseSchemaResult;
+
+/**
+ * Executes the db sign command and returns a structured Result.
+ * Success: SignDatabaseResult (sign happened)
+ * Failure: CliStructuredError (infra error) or VerifyDatabaseSchemaResult (schema mismatch)
+ */
+async function executeDbSignCommand(
+  options: DbSignOptions,
+  flags: GlobalFlags,
+): Promise<Result<SignDatabaseResult, DbSignFailure>> {
+  // Load config
+  const config = await loadConfig(options.config);
+  const configPath = options.config
+    ? relative(process.cwd(), resolve(options.config))
+    : 'prisma-next.config.ts';
+  const contractPathAbsolute = resolveContractPath(config);
+  const contractPath = relative(process.cwd(), contractPathAbsolute);
+
+  // Output header
+  if (flags.json !== 'object' && !flags.quiet) {
+    const details: Array<{ label: string; value: string }> = [
+      { label: 'config', value: configPath },
+      { label: 'contract', value: contractPath },
+    ];
+    if (options.db) {
+      details.push({ label: 'database', value: maskConnectionUrl(options.db) });
+    }
+    const header = formatStyledHeader({
+      command: 'db sign',
+      description: 'Sign the database with your contract so you can safely run queries',
+      url: 'https://pris.ly/db-sign',
+      details,
+      flags,
+    });
+    console.log(header);
+  }
+
+  // Load contract file
+  let contractJsonContent: string;
+  try {
+    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+      return notOk(
+        errorFileNotFound(contractPathAbsolute, {
+          why: `Contract file not found at ${contractPathAbsolute}`,
+          fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`,
+        }),
+      );
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  let contractJson: Record<string, unknown>;
+  try {
+    contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
+  } catch (error) {
+    return notOk(
+      errorContractValidationFailed(
+        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
+  }
+
+  // Resolve database connection (--db flag or config.db.connection)
+  const dbConnection = options.db ?? config.db?.connection;
+  if (!dbConnection) {
+    return notOk(
+      errorDatabaseConnectionRequired({
+        why: `Database connection is required for db sign (set db.connection in ${configPath}, or pass --db <url>)`,
+      }),
+    );
+  }
+
+  // Check for driver
+  if (!config.driver) {
+    return notOk(errorDriverRequired({ why: 'Config.driver is required for db sign' }));
+  }
+
+  // Create control client
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    driver: config.driver,
+    extensionPacks: config.extensionPacks ?? [],
+  });
+
+  // Create progress adapter
+  const onProgress = createProgressAdapter({ flags });
+
+  try {
+    // Step 1: Schema verification - connect here
+    const schemaVerifyResult = await client.schemaVerify({
+      contractIR: contractJson,
+      strict: false,
+      connection: dbConnection,
+      onProgress,
+    });
+
+    // If schema verification failed, return as failure
+    if (!schemaVerifyResult.ok) {
+      // Add blank line after all async operations if spinners were shown
+      if (!flags.quiet && flags.json !== 'object' && process.stdout.isTTY) {
+        console.log('');
+      }
+      return notOk(schemaVerifyResult);
+    }
+
+    // Step 2: Sign (already connected from schemaVerify)
+    const signResult = await client.sign({
+      contractIR: contractJson,
+      contractPath,
+      configPath,
+      onProgress,
+    });
+
+    // Add blank line after all async operations if spinners were shown
+    if (!flags.quiet && flags.json !== 'object' && process.stdout.isTTY) {
+      console.log('');
+    }
+
+    return ok(signResult);
+  } catch (error) {
+    // Driver already throws CliStructuredError for connection failures
+    if (error instanceof CliStructuredError) {
+      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), {
+        why: `Unexpected error during db sign: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  } finally {
+    await client.close();
+  }
+}
+
 export function createDbSignCommand(): Command {
   const command = new Command('sign');
   setCommandDescriptions(
     command,
     'Sign the database with your contract so you can safely run queries',
     'Verifies that your database schema satisfies the emitted contract, and if so, writes or\n' +
-      'updates the contract marker in the database. This command is idempotent and safe to run\n' +
-      'in CI/deployment pipelines. The marker records that this database instance is aligned\n' +
+      'updates the database signature. This command is idempotent and safe to run\n' +
+      'in CI/deployment pipelines. The signature records that this database instance is aligned\n' +
       'with a specific contract version.',
   );
   command
@@ -65,7 +227,7 @@ export function createDbSignCommand(): Command {
     })
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .option('--json [format]', 'Output as JSON (object or ndjson)', false)
+    .option('--json [format]', 'Output as JSON (object)', false)
     .option('-q, --quiet', 'Quiet mode: errors only')
     .option('-v, --verbose', 'Verbose output: debug info, timings')
     .option('-vv, --trace', 'Trace output: deep internals, stack traces')
@@ -75,202 +237,53 @@ export function createDbSignCommand(): Command {
     .action(async (options: DbSignOptions) => {
       const flags = parseGlobalFlags(options);
 
-      const result = await performAction(async () => {
-        // Load config (file I/O)
-        const config = await loadConfig(options.config);
-        // Normalize config path for display (match contract path format - no ./ prefix)
-        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');
-        // Convert to relative path for display
-        const contractPath = relative(process.cwd(), contractPathAbsolute);
-
-        // Output header (only for human-readable output)
-        if (flags.json !== 'object' && !flags.quiet) {
-          const details: Array<{ label: string; value: string }> = [
-            { label: 'config', value: configPath },
-            { label: 'contract', value: contractPath },
-          ];
-          if (options.db) {
-            details.push({ label: 'database', value: options.db });
-          }
-          const header = formatStyledHeader({
+      // Validate JSON format option
+      if (flags.json === 'ndjson') {
+        const result = notOk(
+          errorJsonFormatNotSupported({
             command: 'db sign',
-            description: 'Sign the database with your contract so you can safely run queries',
-            url: 'https://pris.ly/db-sign',
-            details,
-            flags,
-          });
-          console.log(header);
-        }
-
-        // Load contract file (file I/O)
-        let contractJsonContent: string;
-        try {
-          contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
-        } catch (error) {
-          if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-            throw errorFileNotFound(contractPathAbsolute, {
-              why: `Contract file not found at ${contractPathAbsolute}`,
-            });
-          }
-          throw errorUnexpected(error instanceof Error ? error.message : String(error), {
-            why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
-          });
-        }
-        const contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
-
-        // Resolve database URL
-        const dbUrl = options.db ?? config.db?.url;
-        if (!dbUrl) {
-          throw errorDatabaseUrlRequired();
-        }
-
-        // Check for driver
-        if (!config.driver) {
-          throw errorDriverRequired();
-        }
-
-        // Store driver descriptor after null check
-        const driverDescriptor = config.driver;
-
-        // Create family instance (needed for contract validation - no DB connection required)
-        const familyInstance = config.family.create({
-          target: config.target,
-          adapter: config.adapter,
-          driver: driverDescriptor,
-          extensionPacks: config.extensionPacks ?? [],
-        });
-
-        // Validate contract using instance validator (fail-fast before DB connection)
-        const contractIR = familyInstance.validateContractIR(contractJson);
-        assertContractRequirementsSatisfied({
-          contract: contractIR,
-          family: config.family,
-          target: config.target,
-          adapter: config.adapter,
-          extensionPacks: config.extensionPacks,
-        });
-
-        const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
-        const frameworkComponents = assertFrameworkComponentsCompatible(
-          config.family.familyId,
-          config.target.targetId,
-          rawComponents,
+            format: 'ndjson',
+            supportedFormats: ['object'],
+          }),
         );
+        const exitCode = handleResult(result, flags);
+        process.exit(exitCode);
+      }
 
-        // Create driver (expensive operation - done after validation)
-        const driver = await driverDescriptor.create(dbUrl);
-
-        try {
-          // Schema verification precondition with spinner
-          let schemaVerifyResult: VerifyDatabaseSchemaResult;
-          try {
-            schemaVerifyResult = await withSpinner(
-              () =>
-                familyInstance.schemaVerify({
-                  driver,
-                  contractIR,
-                  strict: false,
-                  contractPath: contractPathAbsolute,
-                  configPath,
-                  frameworkComponents,
-                }),
-              {
-                message: 'Verifying database satisfies contract',
-                flags,
-              },
-            );
-          } catch (error) {
-            // Wrap errors from schemaVerify() in structured error
-            throw errorRuntime(error instanceof Error ? error.message : String(error), {
-              why: `Failed to verify database schema: ${error instanceof Error ? error.message : String(error)}`,
-            });
-          }
-
-          // If schema verification failed, return both results for handling outside performAction
-          if (!schemaVerifyResult.ok) {
-            return { schemaVerifyResult, signResult: undefined };
-          }
-
-          // Schema verification passed - proceed with signing
-          let signResult: SignDatabaseResult;
-          try {
-            signResult = await withSpinner(
-              () =>
-                familyInstance.sign({
-                  driver,
-                  contractIR,
-                  contractPath: contractPathAbsolute,
-                  configPath,
-                }),
-              {
-                message: 'Signing database...',
-                flags,
-              },
-            );
-          } catch (error) {
-            // Wrap errors from sign() in structured error
-            throw errorRuntime(error instanceof Error ? error.message : String(error), {
-              why: `Failed to sign database: ${error instanceof Error ? error.message : String(error)}`,
-            });
-          }
+      const result = await executeDbSignCommand(options, flags);
 
-          // Add blank line after all async operations if spinners were shown
-          if (!flags.quiet && flags.json !== 'object' && process.stdout.isTTY) {
-            console.log('');
+      if (result.ok) {
+        // Success - format sign output
+        if (flags.json === 'object') {
+          console.log(formatSignJson(result.value));
+        } else {
+          const output = formatSignOutput(result.value, flags);
+          if (output) {
+            console.log(output);
           }
-
-          return { schemaVerifyResult: undefined, signResult };
-        } finally {
-          // Ensure driver connection is closed
-          await driver.close();
         }
-      });
+        process.exit(0);
+      }
 
-      // Handle result - formats output and returns exit code
-      const exitCode = handleResult(result, flags, (value) => {
-        const { schemaVerifyResult, signResult } = value;
+      // Failure - determine type and handle appropriately
+      const failure = result.failure;
 
-        // If schema verification failed, format and print schema verification output
-        if (schemaVerifyResult && !schemaVerifyResult.ok) {
-          if (flags.json === 'object') {
-            console.log(formatSchemaVerifyJson(schemaVerifyResult));
-          } else {
-            const output = formatSchemaVerifyOutput(schemaVerifyResult, flags);
-            if (output) {
-              console.log(output);
-            }
-          }
-          // Don't proceed to sign output formatting
-          return;
-        }
-
-        // Schema verification passed - format sign output
-        if (signResult) {
-          if (flags.json === 'object') {
-            console.log(formatSignJson(signResult));
-          } else {
-            const output = formatSignOutput(signResult, flags);
-            if (output) {
-              console.log(output);
-            }
-          }
-        }
-      });
+      if (failure instanceof CliStructuredError) {
+        // Infrastructure error - use standard handler
+        const exitCode = handleResult(result as Result<never, CliStructuredError>, flags);
+        process.exit(exitCode);
+      }
 
-      // For logical schema mismatches, check if schema verification passed
-      // Infra errors already handled by handleResult (returns non-zero exit code)
-      if (result.ok && result.value.schemaVerifyResult && !result.value.schemaVerifyResult.ok) {
-        // Schema verification failed - exit with code 1
-        process.exit(1);
+      // Schema verification failed - format and print schema verification output
+      if (flags.json === 'object') {
+        console.log(formatSchemaVerifyJson(failure));
       } else {
-        // Success or infra error - use exit code from handleResult
-        process.exit(exitCode);
+        const output = formatSchemaVerifyOutput(failure, flags);
+        if (output) {
+          console.log(output);
+        }
       }
+      process.exit(1);
     });
 
   return command;

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;
+}