@prisma-next/cli 0.3.0-dev.1 → 0.3.0-dev.10

package/src/commands/db-sign.ts

@@ -0,0 +1,273 @@
+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 { createControlPlaneStack } from '@prisma-next/core-control-plane/types';
+import { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import { performAction } from '../utils/action';
+import { setCommandDescriptions } from '../utils/command-helpers';
+import {
+  assertContractRequirementsSatisfied,
+  assertFrameworkComponentsCompatible,
+} from '../utils/framework-components';
+import { parseGlobalFlags } from '../utils/global-flags';
+import {
+  formatCommandHelp,
+  formatSchemaVerifyJson,
+  formatSchemaVerifyOutput,
+  formatSignJson,
+  formatSignOutput,
+  formatStyledHeader,
+} from '../utils/output';
+import { handleResult } from '../utils/result-handler';
+import { withSpinner } from '../utils/spinner';
+
+interface DbSignOptions {
+  readonly db?: string;
+  readonly config?: string;
+  readonly json?: string | boolean;
+  readonly quiet?: boolean;
+  readonly q?: boolean;
+  readonly verbose?: boolean;
+  readonly v?: boolean;
+  readonly vv?: boolean;
+  readonly trace?: boolean;
+  readonly timestamps?: boolean;
+  readonly color?: boolean;
+  readonly 'no-color'?: boolean;
+}
+
+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' +
+      'with a specific contract version.',
+  );
+  command
+    .configureHelp({
+      formatHelp: (cmd) => {
+        const flags = parseGlobalFlags({});
+        return formatCommandHelp({ command: cmd, flags });
+      },
+    })
+    .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('-q, --quiet', 'Quiet mode: errors only')
+    .option('-v, --verbose', 'Verbose output: debug info, timings')
+    .option('-vv, --trace', 'Trace output: deep internals, stack traces')
+    .option('--timestamps', 'Add timestamps to output')
+    .option('--color', 'Force color output')
+    .option('--no-color', 'Disable color output')
+    .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({
+            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 stack = createControlPlaneStack({
+          target: config.target,
+          adapter: config.adapter,
+          driver: driverDescriptor,
+          extensionPacks: config.extensionPacks,
+        });
+        const familyInstance = config.family.create(stack);
+
+        // Validate contract using instance validator (fail-fast before DB connection)
+        const contractIR = familyInstance.validateContractIR(contractJson);
+        assertContractRequirementsSatisfied({ contract: contractIR, stack });
+
+        const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+        const frameworkComponents = assertFrameworkComponentsCompatible(
+          config.family.familyId,
+          config.target.targetId,
+          rawComponents,
+        );
+
+        // 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)}`,
+            });
+          }
+
+          // Add blank line after all async operations if spinners were shown
+          if (!flags.quiet && flags.json !== 'object' && process.stdout.isTTY) {
+            console.log('');
+          }
+
+          return { schemaVerifyResult: undefined, signResult };
+        } finally {
+          // Ensure driver connection is closed
+          await driver.close();
+        }
+      });
+
+      // Handle result - formats output and returns exit code
+      const exitCode = handleResult(result, flags, (value) => {
+        const { schemaVerifyResult, signResult } = value;
+
+        // 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);
+            }
+          }
+        }
+      });
+
+      // 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);
+      } else {
+        // Success or infra error - use exit code from handleResult
+        process.exit(exitCode);
+      }
+    });
+
+  return command;
+}

package/src/commands/db-verify.ts

@@ -0,0 +1,229 @@
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import {
+  errorDatabaseUrlRequired,
+  errorDriverRequired,
+  errorFileNotFound,
+  errorHashMismatch,
+  errorMarkerMissing,
+  errorRuntime,
+  errorTargetMismatch,
+  errorUnexpected,
+} from '@prisma-next/core-control-plane/errors';
+import type { VerifyDatabaseResult } from '@prisma-next/core-control-plane/types';
+import { createControlPlaneStack } from '@prisma-next/core-control-plane/types';
+import { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import { performAction } from '../utils/action';
+import { setCommandDescriptions } from '../utils/command-helpers';
+import { assertContractRequirementsSatisfied } from '../utils/framework-components';
+import { parseGlobalFlags } from '../utils/global-flags';
+import {
+  formatCommandHelp,
+  formatStyledHeader,
+  formatVerifyJson,
+  formatVerifyOutput,
+} from '../utils/output';
+import { handleResult } from '../utils/result-handler';
+import { withSpinner } from '../utils/spinner';
+
+interface DbVerifyOptions {
+  readonly db?: string;
+  readonly config?: string;
+  readonly json?: string | boolean;
+  readonly quiet?: boolean;
+  readonly q?: boolean;
+  readonly verbose?: boolean;
+  readonly v?: boolean;
+  readonly vv?: boolean;
+  readonly trace?: boolean;
+  readonly timestamps?: boolean;
+  readonly color?: boolean;
+  readonly 'no-color'?: boolean;
+}
+
+export function createDbVerifyCommand(): Command {
+  const command = new Command('verify');
+  setCommandDescriptions(
+    command,
+    'Check whether the database has been signed with your contract',
+    'Verifies that your database schema matches the emitted contract. Checks table structures,\n' +
+      'column types, constraints, and codec coverage. Reports any mismatches or missing codecs.',
+  );
+  command
+    .configureHelp({
+      formatHelp: (cmd) => {
+        const flags = parseGlobalFlags({});
+        return formatCommandHelp({ command: cmd, flags });
+      },
+    })
+    .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('-q, --quiet', 'Quiet mode: errors only')
+    .option('-v, --verbose', 'Verbose output: debug info, timings')
+    .option('-vv, --trace', 'Trace output: deep internals, stack traces')
+    .option('--timestamps', 'Add timestamps to output')
+    .option('--color', 'Force color output')
+    .option('--no-color', 'Disable color output')
+    .action(async (options: DbVerifyOptions) => {
+      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({
+            command: 'db verify',
+            description: 'Check whether the database has been signed with your contract',
+            url: 'https://pris.ly/db-verify',
+            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 driver
+        const driver = await withSpinner(() => driverDescriptor.create(dbUrl), {
+          message: 'Connecting to database...',
+          flags,
+        });
+
+        try {
+          // Create family instance
+          const stack = createControlPlaneStack({
+            target: config.target,
+            adapter: config.adapter,
+            driver: driverDescriptor,
+            extensionPacks: config.extensionPacks,
+          });
+          const familyInstance = config.family.create(stack);
+
+          // Validate contract using instance validator
+          const contractIR = familyInstance.validateContractIR(contractJson) as ContractIR;
+          assertContractRequirementsSatisfied({ contract: contractIR, stack });
+
+          // Call family instance verify method
+          let verifyResult: VerifyDatabaseResult;
+          try {
+            verifyResult = await withSpinner(
+              () =>
+                familyInstance.verify({
+                  driver,
+                  contractIR,
+                  expectedTargetId: config.target.targetId,
+                  contractPath: contractPathAbsolute,
+                  configPath,
+                }),
+              {
+                message: 'Verifying database schema...',
+                flags,
+              },
+            );
+          } catch (error) {
+            // Wrap errors from verify() in structured error
+            throw errorUnexpected(error instanceof Error ? error.message : String(error), {
+              why: `Failed to verify database: ${error instanceof Error ? error.message : String(error)}`,
+            });
+          }
+
+          // If verification failed, throw structured error
+          if (!verifyResult.ok && verifyResult.code) {
+            if (verifyResult.code === 'PN-RTM-3001') {
+              throw errorMarkerMissing();
+            }
+            if (verifyResult.code === 'PN-RTM-3002') {
+              throw errorHashMismatch({
+                expected: verifyResult.contract.coreHash,
+                ...(verifyResult.marker?.coreHash ? { actual: verifyResult.marker.coreHash } : {}),
+              });
+            }
+            if (verifyResult.code === 'PN-RTM-3003') {
+              throw errorTargetMismatch(
+                verifyResult.target.expected,
+                verifyResult.target.actual ?? 'unknown',
+              );
+            }
+            throw errorRuntime(verifyResult.summary);
+          }
+
+          // Add blank line after all async operations if spinners were shown
+          if (!flags.quiet && flags.json !== 'object' && process.stdout.isTTY) {
+            console.log('');
+          }
+
+          return verifyResult;
+        } finally {
+          // Ensure driver connection is closed
+          await driver.close();
+        }
+      });
+
+      // Handle result - formats output and returns exit code
+      const exitCode = handleResult(result, flags, (verifyResult) => {
+        // Output based on flags
+        if (flags.json === 'object') {
+          // JSON output to stdout
+          console.log(formatVerifyJson(verifyResult));
+        } else {
+          // Human-readable output to stdout
+          const output = formatVerifyOutput(verifyResult, flags);
+          if (output) {
+            console.log(output);
+          }
+        }
+      });
+      process.exit(exitCode);
+    });
+
+  return command;
+}

package/src/config-loader.ts

@@ -0,0 +1,76 @@
+import { dirname, resolve } from 'node:path';
+import type { PrismaNextConfig } from '@prisma-next/core-control-plane/config-types';
+import { validateConfig } from '@prisma-next/core-control-plane/config-validation';
+import { errorConfigFileNotFound, errorUnexpected } from '@prisma-next/core-control-plane/errors';
+import { loadConfig as loadConfigC12 } from 'c12';
+
+/**
+ * Loads the Prisma Next config from a TypeScript file.
+ * Supports both default export and named export.
+ * Uses c12 to automatically handle TypeScript compilation and config file discovery.
+ *
+ * @param configPath - Optional path to config file. Defaults to `./prisma-next.config.ts` in current directory.
+ * @returns The loaded config object.
+ * @throws Error if config file doesn't exist or is invalid.
+ */
+export async function loadConfig(configPath?: string): Promise<PrismaNextConfig> {
+  try {
+    const cwd = process.cwd();
+    // Resolve config path to absolute path and set cwd to config directory when path is provided
+    const resolvedConfigPath = configPath ? resolve(cwd, configPath) : undefined;
+    const configCwd = resolvedConfigPath ? dirname(resolvedConfigPath) : cwd;
+
+    const result = await loadConfigC12<PrismaNextConfig>({
+      name: 'prisma-next',
+      ...(resolvedConfigPath ? { configFile: resolvedConfigPath } : {}),
+      cwd: configCwd,
+    });
+
+    // When a specific config file was requested, verify it was actually loaded
+    // (c12 falls back to searching by name if the specified file doesn't exist)
+    if (resolvedConfigPath && result.configFile !== resolvedConfigPath) {
+      throw errorConfigFileNotFound(resolvedConfigPath);
+    }
+
+    // Check if config is missing or empty (c12 may return empty object when file doesn't exist)
+    if (!result.config || Object.keys(result.config).length === 0) {
+      // Use c12's configFile if available, otherwise use explicit configPath, otherwise omit path
+      const displayPath = result.configFile || resolvedConfigPath || configPath;
+      throw errorConfigFileNotFound(displayPath);
+    }
+
+    // Validate config structure
+    validateConfig(result.config);
+
+    return result.config;
+  } catch (error) {
+    // Re-throw structured errors as-is
+    if (
+      error instanceof Error &&
+      'code' in error &&
+      typeof (error as { code: string }).code === 'string'
+    ) {
+      throw error;
+    }
+
+    if (error instanceof Error) {
+      // Check for file not found errors
+      if (
+        error.message.includes('not found') ||
+        error.message.includes('Cannot find') ||
+        error.message.includes('ENOENT')
+      ) {
+        // Use resolved path if available, otherwise use original configPath
+        const displayPath = configPath ? resolve(process.cwd(), configPath) : undefined;
+        throw errorConfigFileNotFound(displayPath, {
+          why: error.message,
+        });
+      }
+      // For other errors, wrap in unexpected error
+      throw errorUnexpected(error.message, {
+        why: `Failed to load config: ${error.message}`,
+      });
+    }
+    throw errorUnexpected(String(error));
+  }
+}

package/src/exports/config-types.ts

@@ -0,0 +1,6 @@
+// Re-export core-control-plane config 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';

package/src/exports/index.ts

@@ -0,0 +1,4 @@
+// CLI-specific exports
+export { createContractEmitCommand } from '../commands/contract-emit';
+export type { LoadTsContractOptions } from '../load-ts-contract';
+export { loadContractFromTs } from '../load-ts-contract';