@prisma-next/cli 0.3.0-dev.6 → 0.3.0-dev.64

package/src/exports/control-api.ts

@@ -0,0 +1,53 @@
+/**
+ * Programmatic Control API for Prisma Next.
+ *
+ * This module exports the control client factory and types for programmatic
+ * access to control-plane operations without using the CLI.
+ *
+ * @see README.md "Programmatic Control API" section for usage examples
+ * @module
+ */
+
+// Re-export core control plane types for consumer convenience
+export type {
+  ControlPlaneStack,
+  SignDatabaseResult,
+  VerifyDatabaseResult,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/core-control-plane/types';
+// Client factory
+export { createControlClient } from '../control-api/client';
+
+// Standalone operations (for tooling that doesn't need full client)
+export { executeContractEmit } from '../control-api/operations/contract-emit';
+
+// CLI-specific types
+export type {
+  ContractEmitOptions,
+  ContractEmitResult,
+  ControlActionName,
+  ControlClient,
+  ControlClientOptions,
+  ControlProgressEvent,
+  DbInitFailure,
+  DbInitFailureCode,
+  DbInitOptions,
+  DbInitResult,
+  DbInitSuccess,
+  DbUpdateFailure,
+  DbUpdateFailureCode,
+  DbUpdateOptions,
+  DbUpdateResult,
+  DbUpdateSuccess,
+  EmitContractConfig,
+  EmitFailure,
+  EmitFailureCode,
+  EmitOptions,
+  EmitResult,
+  EmitSuccess,
+  IntrospectOptions,
+  OnControlProgress,
+  SchemaVerifyOptions,
+  SignOptions,
+  VerifyOptions,
+} from '../control-api/types';

package/src/load-ts-contract.ts

@@ -30,26 +30,31 @@ function validatePurity(value: unknown): void {
     return;
   }
 
-  const seen = new WeakSet();
+  const path = new WeakSet();
+
   function check(value: unknown): void {
     if (value === null || typeof value !== 'object') {
       return;
     }
 
-    if (seen.has(value)) {
+    if (path.has(value)) {
       throw new Error('Contract export contains circular references');
     }
-    seen.add(value);
+    path.add(value);
 
-    for (const key in value) {
-      const descriptor = Object.getOwnPropertyDescriptor(value, key);
-      if (descriptor && (descriptor.get || descriptor.set)) {
-        throw new Error(`Contract export contains getter/setter at key "${key}"`);
-      }
-      if (descriptor && typeof descriptor.value === 'function') {
-        throw new Error(`Contract export contains function at key "${key}"`);
+    try {
+      for (const key in value) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor && (descriptor.get || descriptor.set)) {
+          throw new Error(`Contract export contains getter/setter at key "${key}"`);
+        }
+        if (descriptor && typeof descriptor.value === 'function') {
+          throw new Error(`Contract export contains function at key "${key}"`);
+        }
+        check((value as Record<string, unknown>)[key]);
       }
-      check((value as Record<string, unknown>)[key]);
+    } finally {
+      path.delete(value);
     }
   }
 

package/src/utils/cli-errors.ts

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

package/src/utils/command-helpers.ts

@@ -1,4 +1,7 @@
 import type { Command } from 'commander';
+import { resolve } from 'pathe';
+
+const longDescriptions = new WeakMap<Command, string>();
 
 /**
  * Sets both short and long descriptions for a command.
@@ -12,8 +15,7 @@ export function setCommandDescriptions(
 ): Command {
   command.description(shortDescription);
   if (longDescription) {
-    // Store long description in a custom property for our formatters to access
-    (command as Command & { _longDescription?: string })._longDescription = longDescription;
+    longDescriptions.set(command, longDescription);
   }
   return command;
 }
@@ -22,5 +24,92 @@ export function setCommandDescriptions(
  * Gets the long description from a command if it was set via setCommandDescriptions.
  */
 export function getLongDescription(command: Command): string | undefined {
-  return (command as Command & { _longDescription?: string })._longDescription;
+  return longDescriptions.get(command);
+}
+
+/**
+ * Shared CLI options interface for migration commands (db init, db update).
+ * These are the Commander.js parsed options common to both commands.
+ */
+export interface MigrationCommandOptions {
+  readonly db?: string;
+  readonly config?: string;
+  readonly plan?: boolean;
+  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;
+}
+
+/**
+ * Resolves the absolute path to contract.json from the config.
+ * Centralises the fallback logic shared by every command that reads the contract.
+ */
+export function resolveContractPath(config: { contract?: { output?: string } }): string {
+  return config.contract?.output
+    ? resolve(config.contract.output)
+    : resolve('src/prisma/contract.json');
+}
+
+/**
+ * Masks credentials in a database connection URL.
+ * Handles standard URLs (username + password + query params) and libpq-style key=value strings.
+ */
+export function maskConnectionUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    if (parsed.username) {
+      parsed.username = '****';
+    }
+    if (parsed.password) {
+      parsed.password = '****';
+    }
+    // Also mask password in query parameters (e.g., ?password=secret, ?sslpassword=secret)
+    for (const key of [...parsed.searchParams.keys()]) {
+      if (/password/i.test(key)) {
+        parsed.searchParams.set(key, '****');
+      }
+    }
+    return parsed.toString();
+  } catch {
+    // Fallback for libpq-style key=value connection strings (e.g., "host=localhost password=secret user=admin")
+    return url
+      .replace(/password\s*=\s*\S+/gi, 'password=****')
+      .replace(/user\s*=\s*\S+/gi, 'user=****');
+  }
+}
+
+/**
+ * Strips raw connection URL fragments from an error message to prevent credential leakage.
+ * Call this before surfacing driver errors to the user.
+ */
+export function sanitizeErrorMessage(message: string, connectionUrl?: string): string {
+  if (!connectionUrl) {
+    return message;
+  }
+  try {
+    const parsed = new URL(connectionUrl);
+    // Replace the full URL (with and without trailing slash)
+    let sanitized = message;
+    sanitized = sanitized.replaceAll(connectionUrl, maskConnectionUrl(connectionUrl));
+    // Also replace the password and username individually if they appear
+    if (parsed.password) {
+      sanitized = sanitized.replaceAll(parsed.password, '****');
+    }
+    if (parsed.username) {
+      sanitized = sanitized.replaceAll(parsed.username, '****');
+    }
+    return sanitized;
+  } catch {
+    // For libpq-style strings, mask password and user values in the message
+    return message
+      .replace(/password\s*=\s*\S+/gi, 'password=****')
+      .replace(/user\s*=\s*\S+/gi, 'user=****');
+  }
 }

package/src/utils/framework-components.ts

@@ -3,12 +3,7 @@ import {
   type TargetBoundComponentDescriptor,
 } from '@prisma-next/contract/framework-components';
 import type { ContractIR } from '@prisma-next/contract/ir';
-import type {
-  ControlAdapterDescriptor,
-  ControlExtensionDescriptor,
-  ControlFamilyDescriptor,
-  ControlTargetDescriptor,
-} from '@prisma-next/core-control-plane/types';
+import type { ControlPlaneStack } from '@prisma-next/core-control-plane/types';
 import { errorConfigValidation, errorContractMissingExtensionPacks } from './cli-errors';
 
 /**
@@ -113,17 +108,14 @@ export function assertFrameworkComponentsCompatible<
 }
 
 /**
- * Validates that a contract is compatible with the configured family, target, adapter,
+ * Validates that a contract is compatible with the configured target, adapter,
  * and extension packs. Throws on family/target mismatches or missing extension packs.
  *
  * This check ensures the emitted contract matches the CLI config before running
  * commands that depend on the contract (e.g., db verify, db sign).
  *
  * @param contract - The contract IR to validate (must include targetFamily, target, extensionPacks).
- * @param family - The configured family descriptor.
- * @param target - The configured target descriptor.
- * @param adapter - The configured adapter descriptor.
- * @param extensionPacks - Optional array of extension descriptors provided by the config.
+ * @param stack - The control plane stack (target, adapter, driver, extensionPacks).
  *
  * @throws {CliStructuredError} errorConfigValidation when contract.targetFamily or contract.target
  *   doesn't match the configured family/target.
@@ -136,15 +128,10 @@ export function assertFrameworkComponentsCompatible<
  *
  * const config = await loadConfig();
  * const contractIR = await loadContractJson(config.contract.output);
+ * const stack = createControlPlaneStack({ target: config.target, adapter: config.adapter, ... });
  *
  * // Throws if contract is incompatible with config
- * assertContractRequirementsSatisfied({
- *   contract: contractIR,
- *   family: config.family,
- *   target: config.target,
- *   adapter: config.adapter,
- *   extensionPacks: config.extensionPacks,
- * });
+ * assertContractRequirementsSatisfied({ contract: contractIR, stack });
  * ```
  */
 export function assertContractRequirementsSatisfied<
@@ -152,26 +139,20 @@ export function assertContractRequirementsSatisfied<
   TTargetId extends string,
 >({
   contract,
-  family,
-  target,
-  adapter,
-  extensionPacks,
+  stack,
 }: {
   readonly contract: Pick<ContractIR, 'targetFamily' | 'target' | 'extensionPacks'>;
-  readonly family: ControlFamilyDescriptor<TFamilyId>;
-  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
-  readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;
-  readonly extensionPacks?: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[] | undefined;
+  readonly stack: ControlPlaneStack<TFamilyId, TTargetId>;
 }): void {
-  const providedComponentIds = new Set<string>([target.id, adapter.id]);
-  for (const extension of extensionPacks ?? []) {
+  const providedComponentIds = new Set<string>([stack.target.id, stack.adapter.id]);
+  for (const extension of stack.extensionPacks) {
     providedComponentIds.add(extension.id);
   }
 
   const result = checkContractComponentRequirements({
     contract,
-    expectedTargetFamily: family.familyId,
-    expectedTargetId: target.targetId,
+    expectedTargetFamily: stack.target.familyId,
+    expectedTargetId: stack.target.targetId,
     providedComponentIds,
   });
 

package/src/utils/migration-command-scaffold.ts

@@ -0,0 +1,190 @@
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import type { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import { createControlClient } from '../control-api/client';
+import type { ControlClient } from '../control-api/types';
+import {
+  type CliStructuredError,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFileNotFound,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+} from './cli-errors';
+import { maskConnectionUrl, resolveContractPath } from './command-helpers';
+import type { GlobalFlags } from './global-flags';
+import { formatStyledHeader } from './output';
+import { createProgressAdapter } from './progress-adapter';
+
+/**
+ * Resolved context for a migration command.
+ * Contains everything needed to invoke a control-api operation.
+ */
+export interface MigrationContext {
+  readonly client: ControlClient;
+  readonly contractJson: Record<string, unknown>;
+  readonly dbConnection: unknown;
+  readonly onProgress: ReturnType<typeof createProgressAdapter>;
+  readonly configPath: string;
+  readonly contractPath: string;
+  readonly contractPathAbsolute: string;
+  readonly config: Awaited<ReturnType<typeof loadConfig>>;
+}
+
+/**
+ * Command-specific configuration for the shared scaffold.
+ */
+export interface MigrationCommandDescriptor {
+  readonly commandName: string;
+  readonly description: string;
+  readonly url: string;
+}
+
+/**
+ * Prepares the shared context for migration commands (db init, db update).
+ *
+ * Handles: config loading, contract file reading, JSON parsing, connection resolution,
+ * driver/migration-support validation, client creation, and header output.
+ *
+ * Returns a Result with either the resolved context or a structured error.
+ */
+export async function prepareMigrationContext(
+  options: { readonly db?: string; readonly config?: string; readonly plan?: boolean },
+  flags: GlobalFlags,
+  descriptor: MigrationCommandDescriptor,
+): Promise<Result<MigrationContext, CliStructuredError>> {
+  // 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) });
+    }
+    if (options.plan) {
+      details.push({ label: 'mode', value: 'plan (dry run)' });
+    }
+    const header = formatStyledHeader({
+      command: descriptor.commandName,
+      description: descriptor.description,
+      url: descriptor.url,
+      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)}`,
+      }),
+    );
+  }
+
+  // Parse contract JSON
+  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 ${descriptor.commandName} (set db.connection in ${configPath}, or pass --db <url>)`,
+      }),
+    );
+  }
+
+  // Check for driver
+  if (!config.driver) {
+    return notOk(
+      errorDriverRequired({ why: `Config.driver is required for ${descriptor.commandName}` }),
+    );
+  }
+
+  // Check target supports migrations via optional descriptor capability
+  const targetWithMigrations = config.target as typeof config.target & {
+    readonly migrations?: unknown;
+  };
+  if (!targetWithMigrations.migrations) {
+    return notOk(
+      errorTargetMigrationNotSupported({
+        why: `Target "${config.target.id}" does not support migrations`,
+      }),
+    );
+  }
+
+  // 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 });
+
+  return ok({
+    client,
+    contractJson,
+    dbConnection,
+    onProgress,
+    configPath,
+    contractPath,
+    contractPathAbsolute,
+    config,
+  });
+}
+
+/**
+ * Registers the shared CLI options for migration commands (db init, db update).
+ */
+export function addMigrationCommandOptions(command: Command): Command {
+  return command
+    .option('--db <url>', 'Database connection string')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .option('--plan', 'Preview planned operations without applying', 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')
+    .option('--timestamps', 'Add timestamps to output')
+    .option('--color', 'Force color output')
+    .option('--no-color', 'Disable color output');
+}