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

package/src/commands/db-introspect.ts

@@ -0,0 +1,256 @@
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import {
+  errorDatabaseUrlRequired,
+  errorDriverRequired,
+  errorRuntime,
+  errorUnexpected,
+} from '@prisma-next/core-control-plane/errors';
+import type { CoreSchemaView } from '@prisma-next/core-control-plane/schema-view';
+import type { IntrospectSchemaResult } 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,
+  formatIntrospectJson,
+  formatIntrospectOutput,
+  formatStyledHeader,
+} from '../utils/output';
+import { handleResult } from '../utils/result-handler';
+import { withSpinner } from '../utils/spinner';
+
+interface DbIntrospectOptions {
+  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 createDbIntrospectCommand(): Command {
+  const command = new Command('introspect');
+  setCommandDescriptions(
+    command,
+    'Inspect the database schema',
+    'Reads the live database schema and displays it as a tree structure. This command\n' +
+      'does not check the schema against your contract - it only shows what exists in\n' +
+      'the database. Use `db verify` or `db schema-verify` to compare against your contract.',
+  );
+  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: DbIntrospectOptions) => {
+      const flags = parseGlobalFlags(options);
+
+      const result = await performAction(async () => {
+        const startTime = Date.now();
+
+        // 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';
+
+        // Optionally load contract if contract config exists
+        let contractIR: unknown | undefined;
+        if (config.contract?.output) {
+          const contractPath = resolve(config.contract.output);
+          try {
+            const contractJsonContent = await readFile(contractPath, 'utf-8');
+            contractIR = JSON.parse(contractJsonContent);
+          } catch (error) {
+            // Contract file is optional for introspection - don't fail if it doesn't exist
+            if (error instanceof Error && (error as { code?: string }).code !== 'ENOENT') {
+              throw errorUnexpected(error.message, {
+                why: `Failed to read contract file: ${error.message}`,
+              });
+            }
+          }
+        }
+
+        // Output header (only for human-readable output)
+        if (flags.json !== 'object' && !flags.quiet) {
+          const details: Array<{ label: string; value: string }> = [
+            { label: 'config', value: configPath },
+          ];
+          if (options.db) {
+            // Mask password in URL for security
+            const maskedUrl = options.db.replace(/:([^:@]+)@/, ':****@');
+            details.push({ label: 'database', value: maskedUrl });
+          } else if (config.db?.url) {
+            // Mask password in URL for security
+            const maskedUrl = config.db.url.replace(/:([^:@]+)@/, ':****@');
+            details.push({ label: 'database', value: maskedUrl });
+          }
+          const header = formatStyledHeader({
+            command: 'db introspect',
+            description: 'Inspect the database schema',
+            url: 'https://pris.ly/db-introspect',
+            details,
+            flags,
+          });
+          console.log(header);
+        }
+
+        // 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 IR if we loaded it
+          if (contractIR) {
+            const validatedContract = familyInstance.validateContractIR(contractIR);
+            assertContractRequirementsSatisfied({ contract: validatedContract, stack });
+            contractIR = validatedContract;
+          }
+
+          // Call family instance introspect method
+          let schemaIR: unknown;
+          try {
+            schemaIR = await withSpinner(
+              () =>
+                familyInstance.introspect({
+                  driver,
+                  contractIR,
+                }),
+              {
+                message: 'Introspecting database schema...',
+                flags,
+              },
+            );
+          } catch (error) {
+            // Wrap errors from introspect() in structured error
+            throw errorRuntime(error instanceof Error ? error.message : String(error), {
+              why: `Failed to introspect database: ${error instanceof Error ? error.message : String(error)}`,
+            });
+          }
+
+          // Optionally call toSchemaView if available
+          let schemaView: CoreSchemaView | undefined;
+          if (familyInstance.toSchemaView) {
+            try {
+              schemaView = familyInstance.toSchemaView(schemaIR);
+            } catch (error) {
+              // Schema view projection is optional - log but don't fail
+              if (flags.verbose) {
+                console.error(
+                  `Warning: Failed to project schema to view: ${error instanceof Error ? error.message : String(error)}`,
+                );
+              }
+            }
+          }
+
+          const totalTime = Date.now() - startTime;
+
+          // Add blank line after all async operations if spinners were shown
+          if (!flags.quiet && flags.json !== 'object' && process.stdout.isTTY) {
+            console.log('');
+          }
+
+          // Build result envelope
+          const introspectResult: IntrospectSchemaResult<unknown> = {
+            ok: true,
+            summary: 'Schema introspected successfully',
+            target: {
+              familyId: config.family.familyId,
+              id: config.target.targetId,
+            },
+            schema: schemaIR,
+            ...(configPath || options.db || config.db?.url
+              ? {
+                  meta: {
+                    ...(configPath ? { configPath } : {}),
+                    ...(options.db || config.db?.url
+                      ? {
+                          dbUrl: (options.db ?? config.db?.url ?? '').replace(
+                            /:([^:@]+)@/,
+                            ':****@',
+                          ),
+                        }
+                      : {}),
+                  },
+                }
+              : {}),
+            timings: {
+              total: totalTime,
+            },
+          };
+
+          return { introspectResult, schemaView };
+        } finally {
+          // Ensure driver connection is closed
+          await driver.close();
+        }
+      });
+
+      // Handle result - formats output and returns exit code
+      const exitCode = handleResult(result, flags, (value) => {
+        const { introspectResult, schemaView } = value;
+        // Output based on flags
+        if (flags.json === 'object') {
+          // JSON output to stdout
+          console.log(formatIntrospectJson(introspectResult));
+        } else {
+          // Human-readable output to stdout
+          const output = formatIntrospectOutput(introspectResult, schemaView, flags);
+          if (output) {
+            console.log(output);
+          }
+        }
+      });
+      process.exit(exitCode);
+    });
+
+  return command;
+}

package/src/commands/db-schema-verify.ts

@@ -0,0 +1,232 @@
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import {
+  errorDatabaseUrlRequired,
+  errorDriverRequired,
+  errorFileNotFound,
+  errorRuntime,
+  errorUnexpected,
+} from '@prisma-next/core-control-plane/errors';
+import type { 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,
+  formatStyledHeader,
+} from '../utils/output';
+import { handleResult } from '../utils/result-handler';
+import { withSpinner } from '../utils/spinner';
+
+interface DbSchemaVerifyOptions {
+  readonly db?: string;
+  readonly config?: string;
+  readonly json?: string | boolean;
+  readonly strict?: 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 createDbSchemaVerifyCommand(): Command {
+  const command = new Command('schema-verify');
+  setCommandDescriptions(
+    command,
+    'Check whether the database schema satisfies your contract',
+    'Verifies that your database schema satisfies the emitted contract. Compares table structures,\n' +
+      'column types, constraints, and extensions. Reports any mismatches via a contract-shaped\n' +
+      'verification tree. This is a read-only operation that does not modify the database.',
+  );
+  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('--strict', 'Strict mode: extra schema elements cause failures', 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: DbSchemaVerifyOptions) => {
+      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 schema-verify',
+            description: 'Check whether the database schema satisfies your contract',
+            url: 'https://pris.ly/db-schema-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>;
+
+        // Check for driver (needed for family instance creation)
+        if (!config.driver) {
+          throw errorDriverRequired();
+        }
+
+        // Store driver descriptor after null check
+        const driverDescriptor = config.driver;
+
+        // Create family instance (needed for contract validation)
+        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;
+
+        // Validate contract requirements fail-fast before connecting to database
+        assertContractRequirementsSatisfied({ contract: contractIR, stack });
+
+        // Resolve database URL
+        const dbUrl = options.db ?? config.db?.url;
+        if (!dbUrl) {
+          throw errorDatabaseUrlRequired();
+        }
+
+        // Create driver
+        const driver = await withSpinner(() => driverDescriptor.create(dbUrl), {
+          message: 'Connecting to database...',
+          flags,
+        });
+
+        try {
+          const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+          const frameworkComponents = assertFrameworkComponentsCompatible(
+            config.family.familyId,
+            config.target.targetId,
+            rawComponents,
+          );
+
+          // Call family instance schemaVerify method
+          let schemaVerifyResult: VerifyDatabaseSchemaResult;
+          try {
+            schemaVerifyResult = await withSpinner(
+              () =>
+                familyInstance.schemaVerify({
+                  driver,
+                  contractIR,
+                  strict: options.strict ?? false,
+                  contractPath: contractPathAbsolute,
+                  configPath,
+                  frameworkComponents,
+                }),
+              {
+                message: 'Verifying database schema...',
+                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)}`,
+            });
+          }
+
+          // Add blank line after all async operations if spinners were shown
+          if (!flags.quiet && flags.json !== 'object' && process.stdout.isTTY) {
+            console.log('');
+          }
+
+          // Return result (don't throw for logical mismatches - handle exit code separately)
+          return schemaVerifyResult;
+        } finally {
+          // Ensure driver connection is closed
+          await driver.close();
+        }
+      });
+
+      // Handle result - formats output and returns exit code
+      const exitCode = handleResult(result, flags, (schemaVerifyResult) => {
+        // Output based on flags
+        if (flags.json === 'object') {
+          // JSON output to stdout
+          console.log(formatSchemaVerifyJson(schemaVerifyResult));
+        } else {
+          // Human-readable output to stdout
+          const output = formatSchemaVerifyOutput(schemaVerifyResult, flags);
+          if (output) {
+            console.log(output);
+          }
+        }
+      });
+
+      // For logical schema mismatches, check if verification passed
+      // Infra errors already handled by handleResult (returns non-zero exit code)
+      if (result.ok && !result.value.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;
+}