@prisma-next/cli 0.3.0-dev.12 → 0.3.0-dev.14

package/src/control-api/client.ts

@@ -0,0 +1,229 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import { createControlPlaneStack } from '@prisma-next/core-control-plane/stack';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  ControlPlaneStack,
+  SignDatabaseResult,
+  VerifyDatabaseResult,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/core-control-plane/types';
+import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
+import { executeDbInit } from './operations/db-init';
+import type {
+  ControlClient,
+  ControlClientOptions,
+  DbInitOptions,
+  DbInitResult,
+  IntrospectOptions,
+  SchemaVerifyOptions,
+  SignOptions,
+  VerifyOptions,
+} from './types';
+
+/**
+ * Creates a programmatic control client for Prisma Next operations.
+ *
+ * The client accepts framework component descriptors at creation time,
+ * manages driver lifecycle via connect()/close(), and exposes domain
+ * operations that delegate to the existing family instance methods.
+ *
+ * @see {@link ControlClient} for the client interface
+ * @see README.md "Programmatic Control API" section for usage examples
+ */
+export function createControlClient(options: ControlClientOptions): ControlClient {
+  return new ControlClientImpl(options);
+}
+
+/**
+ * Implementation of ControlClient.
+ * Manages initialization and connection state, delegates operations to family instance.
+ */
+class ControlClientImpl implements ControlClient {
+  private readonly options: ControlClientOptions;
+  private stack: ControlPlaneStack<string, string> | null = null;
+  private driver: ControlDriverInstance<string, string> | null = null;
+  private familyInstance: ControlFamilyInstance<string> | null = null;
+  private frameworkComponents: ReadonlyArray<
+    TargetBoundComponentDescriptor<string, string>
+  > | null = null;
+  private initialized = false;
+  private readonly defaultConnection: unknown;
+
+  constructor(options: ControlClientOptions) {
+    this.options = options;
+    this.defaultConnection = options.connection;
+  }
+
+  init(): void {
+    if (this.initialized) {
+      return; // Idempotent
+    }
+
+    // Create the control plane stack
+    this.stack = createControlPlaneStack({
+      target: this.options.target,
+      adapter: this.options.adapter,
+      driver: this.options.driver,
+      extensionPacks: this.options.extensionPacks,
+    });
+
+    // Create family instance using the stack
+    this.familyInstance = this.options.family.create(this.stack);
+
+    // Validate and type-narrow framework components
+    const rawComponents = [
+      this.options.target,
+      this.options.adapter,
+      ...(this.options.extensionPacks ?? []),
+    ];
+    this.frameworkComponents = assertFrameworkComponentsCompatible(
+      this.options.family.familyId,
+      this.options.target.targetId,
+      rawComponents,
+    );
+
+    this.initialized = true;
+  }
+
+  async connect(connection?: unknown): Promise<void> {
+    // Auto-init if needed
+    this.init();
+
+    if (this.driver) {
+      throw new Error('Already connected. Call close() before reconnecting.');
+    }
+
+    // Resolve connection: argument > default from options
+    const resolvedConnection = connection ?? this.defaultConnection;
+    if (resolvedConnection === undefined) {
+      throw new Error(
+        'No connection provided. Pass a connection to connect() or provide a default connection when creating the client.',
+      );
+    }
+
+    // Check for driver descriptor
+    if (!this.stack?.driver) {
+      throw new Error(
+        'Driver is not configured. Pass a driver descriptor when creating the control client to enable database operations.',
+      );
+    }
+
+    // Create driver instance
+    // Cast through any since connection type is driver-specific at runtime.
+    // The driver descriptor is typed with any for TConnection in ControlClientOptions,
+    // but createControlPlaneStack defaults it to string. We bridge this at runtime.
+    // biome-ignore lint/suspicious/noExplicitAny: required for runtime connection type flexibility
+    this.driver = await this.stack?.driver.create(resolvedConnection as any);
+  }
+
+  async close(): Promise<void> {
+    if (this.driver) {
+      await this.driver.close();
+      this.driver = null;
+    }
+  }
+
+  private async ensureConnected(): Promise<{
+    driver: ControlDriverInstance<string, string>;
+    familyInstance: ControlFamilyInstance<string>;
+    frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<string, string>>;
+  }> {
+    // Auto-init if needed
+    this.init();
+
+    // Auto-connect if not connected and default connection is available
+    if (!this.driver && this.defaultConnection !== undefined) {
+      await this.connect(this.defaultConnection);
+    }
+
+    if (!this.driver || !this.familyInstance || !this.frameworkComponents) {
+      throw new Error('Not connected. Call connect(connection) first.');
+    }
+    return {
+      driver: this.driver,
+      familyInstance: this.familyInstance,
+      frameworkComponents: this.frameworkComponents,
+    };
+  }
+
+  async verify(options: VerifyOptions): Promise<VerifyDatabaseResult> {
+    const { driver, familyInstance } = await this.ensureConnected();
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // Delegate to family instance verify method
+    // Note: We pass empty strings for contractPath/configPath since the programmatic
+    // API doesn't deal with file paths. The family instance accepts these as optional
+    // metadata for error reporting.
+    return familyInstance.verify({
+      driver,
+      contractIR,
+      expectedTargetId: this.options.target.targetId,
+      contractPath: '',
+    });
+  }
+
+  async schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult> {
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // Delegate to family instance schemaVerify method
+    return familyInstance.schemaVerify({
+      driver,
+      contractIR,
+      strict: options.strict ?? false,
+      contractPath: '',
+      frameworkComponents,
+    });
+  }
+
+  async sign(options: SignOptions): Promise<SignDatabaseResult> {
+    const { driver, familyInstance } = await this.ensureConnected();
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // Delegate to family instance sign method
+    return familyInstance.sign({
+      driver,
+      contractIR,
+      contractPath: '',
+    });
+  }
+
+  async dbInit(options: DbInitOptions): Promise<DbInitResult> {
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+
+    // Check target supports migrations
+    if (!this.options.target.migrations) {
+      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+    }
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // Delegate to extracted dbInit operation
+    return executeDbInit({
+      driver,
+      familyInstance,
+      contractIR,
+      mode: options.mode,
+      migrations: this.options.target.migrations,
+      frameworkComponents,
+    });
+  }
+
+  async introspect(options?: IntrospectOptions): Promise<unknown> {
+    const { driver, familyInstance } = await this.ensureConnected();
+
+    // TODO: Pass schema option to familyInstance.introspect when schema filtering is implemented
+    const _schema = options?.schema;
+    void _schema;
+
+    return familyInstance.introspect({ driver });
+  }
+}

package/src/control-api/operations/db-init.ts

@@ -0,0 +1,167 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  MigrationPlan,
+  MigrationPlannerResult,
+  MigrationRunnerResult,
+  TargetMigrationsCapability,
+} from '@prisma-next/core-control-plane/types';
+import { notOk, ok } from '@prisma-next/utils/result';
+import type { DbInitResult, DbInitSuccess } from '../types';
+
+/**
+ * Options for executing dbInit operation.
+ */
+export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extends string> {
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId>;
+  readonly contractIR: ContractIR;
+  readonly mode: 'plan' | 'apply';
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+}
+
+/**
+ * Executes the dbInit operation.
+ *
+ * This is the core logic extracted from the CLI command, without any file I/O,
+ * process.exit(), or console output. It uses the Result pattern to return
+ * success or failure details.
+ *
+ * @param options - The options for executing dbInit
+ * @returns Result with DbInitSuccess on success, DbInitFailure on failure
+ */
+export async function executeDbInit<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteDbInitOptions<TFamilyId, TTargetId>,
+): Promise<DbInitResult> {
+  const { driver, familyInstance, contractIR, mode, migrations, frameworkComponents } = options;
+
+  // Create planner and runner from target migrations capability
+  const planner = migrations.createPlanner(familyInstance);
+  const runner = migrations.createRunner(familyInstance);
+
+  // Introspect live schema
+  const schemaIR = await familyInstance.introspect({ driver });
+
+  // Policy for init mode (additive only)
+  const policy = { allowedOperationClasses: ['additive'] as const };
+
+  // Plan migration
+  const plannerResult: MigrationPlannerResult = await planner.plan({
+    contract: contractIR,
+    schema: schemaIR,
+    policy,
+    frameworkComponents,
+  });
+
+  if (plannerResult.kind === 'failure') {
+    return notOk({
+      code: 'PLANNING_FAILED' as const,
+      summary: 'Migration planning failed due to conflicts',
+      conflicts: plannerResult.conflicts,
+    });
+  }
+
+  const migrationPlan: MigrationPlan = plannerResult.plan;
+
+  // Check for existing marker - handle idempotency and mismatch errors
+  const existingMarker = await familyInstance.readMarker({ driver });
+  if (existingMarker) {
+    const markerMatchesDestination =
+      existingMarker.coreHash === migrationPlan.destination.coreHash &&
+      (!migrationPlan.destination.profileHash ||
+        existingMarker.profileHash === migrationPlan.destination.profileHash);
+
+    if (markerMatchesDestination) {
+      // Already at destination - return success with no operations
+      const result: DbInitSuccess = {
+        mode,
+        plan: { operations: [] },
+        ...(mode === 'apply'
+          ? {
+              execution: { operationsPlanned: 0, operationsExecuted: 0 },
+              marker: {
+                coreHash: existingMarker.coreHash,
+                profileHash: existingMarker.profileHash,
+              },
+            }
+          : {}),
+        summary: 'Database already at target contract state',
+      };
+      return ok(result);
+    }
+
+    // Marker exists but doesn't match destination - fail
+    return notOk({
+      code: 'MARKER_ORIGIN_MISMATCH' as const,
+      summary: 'Existing contract marker does not match plan destination',
+      marker: {
+        coreHash: existingMarker.coreHash,
+        profileHash: existingMarker.profileHash,
+      },
+      destination: {
+        coreHash: migrationPlan.destination.coreHash,
+        profileHash: migrationPlan.destination.profileHash,
+      },
+    });
+  }
+
+  // Plan mode - don't execute
+  if (mode === 'plan') {
+    const result: DbInitSuccess = {
+      mode: 'plan',
+      plan: { operations: migrationPlan.operations },
+      summary: `Planned ${migrationPlan.operations.length} operation(s)`,
+    };
+    return ok(result);
+  }
+
+  // Apply mode - execute runner
+  const runnerResult: MigrationRunnerResult = await runner.execute({
+    plan: migrationPlan,
+    driver,
+    destinationContract: contractIR,
+    policy,
+    // db init plans and applies back-to-back from a fresh introspection, so per-operation
+    // pre/postchecks and the idempotency probe are usually redundant overhead. We still
+    // enforce marker/origin compatibility and a full schema verification after apply.
+    executionChecks: {
+      prechecks: false,
+      postchecks: false,
+      idempotencyChecks: false,
+    },
+    frameworkComponents,
+  });
+
+  if (!runnerResult.ok) {
+    return notOk({
+      code: 'RUNNER_FAILED' as const,
+      summary: runnerResult.failure.summary,
+    });
+  }
+
+  const execution = runnerResult.value;
+
+  const result: DbInitSuccess = {
+    mode: 'apply',
+    plan: { operations: migrationPlan.operations },
+    execution: {
+      operationsPlanned: execution.operationsPlanned,
+      operationsExecuted: execution.operationsExecuted,
+    },
+    marker: migrationPlan.destination.profileHash
+      ? {
+          coreHash: migrationPlan.destination.coreHash,
+          profileHash: migrationPlan.destination.profileHash,
+        }
+      : { coreHash: migrationPlan.destination.coreHash },
+    summary: `Applied ${execution.operationsExecuted} operation(s), marker written`,
+  };
+  return ok(result);
+}

package/src/control-api/types.ts

@@ -0,0 +1,251 @@
+import type {
+  ControlAdapterDescriptor,
+  ControlDriverDescriptor,
+  ControlExtensionDescriptor,
+  ControlFamilyDescriptor,
+  ControlTargetDescriptor,
+  MigrationPlannerConflict,
+  SignDatabaseResult,
+  VerifyDatabaseResult,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/core-control-plane/types';
+import type { Result } from '@prisma-next/utils/result';
+
+// ============================================================================
+// Client Options
+// ============================================================================
+
+/**
+ * Options for creating a control client.
+ *
+ * Note: This is NOT the same as CLI config. There's no `contract` field,
+ * no file paths. The client is config-agnostic.
+ *
+ * The descriptor types use permissive `any` because family-specific descriptors
+ * (e.g., SqlFamilyDescriptor) have more specific `create` method signatures that
+ * are not compatible with the base ControlFamilyDescriptor type due to TypeScript
+ * variance rules. The client implementation casts these internally.
+ */
+export interface ControlClientOptions {
+  // biome-ignore lint/suspicious/noExplicitAny: required for contravariance - SqlFamilyDescriptor.create has specific parameter types
+  readonly family: ControlFamilyDescriptor<any, any>;
+  // biome-ignore lint/suspicious/noExplicitAny: required for contravariance - SqlControlTargetDescriptor extends with additional methods
+  readonly target: ControlTargetDescriptor<any, any, any, any>;
+  // biome-ignore lint/suspicious/noExplicitAny: required for contravariance in adapter.create()
+  readonly adapter: ControlAdapterDescriptor<any, any, any>;
+  /** Optional - control client can be created without driver for offline operations */
+  // biome-ignore lint/suspicious/noExplicitAny: required for contravariance in driver.create()
+  readonly driver?: ControlDriverDescriptor<any, any, any, any>;
+  // biome-ignore lint/suspicious/noExplicitAny: required for contravariance in extension.create()
+  readonly extensionPacks?: ReadonlyArray<ControlExtensionDescriptor<any, any, any>>;
+  /**
+   * Optional default connection for auto-connect.
+   * When provided, operations will auto-connect if not already connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+}
+
+// ============================================================================
+// Operation Options
+// ============================================================================
+
+/**
+ * Options for the verify operation.
+ */
+export interface VerifyOptions {
+  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
+  readonly contractIR: unknown;
+}
+
+/**
+ * Options for the schemaVerify operation.
+ */
+export interface SchemaVerifyOptions {
+  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
+  readonly contractIR: unknown;
+  /**
+   * Whether to use strict mode for schema verification.
+   * In strict mode, extra tables/columns are reported as issues.
+   * Default: false (tolerant mode - allows superset)
+   */
+  readonly strict?: boolean;
+}
+
+/**
+ * Options for the sign operation.
+ */
+export interface SignOptions {
+  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
+  readonly contractIR: unknown;
+}
+
+/**
+ * Options for the dbInit operation.
+ */
+export interface DbInitOptions {
+  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
+  readonly contractIR: unknown;
+  /**
+   * Mode for the dbInit operation.
+   * - 'plan': Returns planned operations without applying
+   * - 'apply': Applies operations and writes marker
+   */
+  readonly mode: 'plan' | 'apply';
+}
+
+/**
+ * Options for the introspect operation.
+ */
+export interface IntrospectOptions {
+  /**
+   * Optional schema name to introspect.
+   */
+  readonly schema?: string;
+}
+
+// ============================================================================
+// Result Types
+// ============================================================================
+
+/**
+ * Successful dbInit result.
+ */
+export interface DbInitSuccess {
+  readonly mode: 'plan' | 'apply';
+  readonly plan: {
+    readonly operations: ReadonlyArray<{
+      readonly id: string;
+      readonly label: string;
+      readonly operationClass: string;
+    }>;
+  };
+  readonly execution?: {
+    readonly operationsPlanned: number;
+    readonly operationsExecuted: number;
+  };
+  readonly marker?: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  readonly summary: string;
+}
+
+/**
+ * Failure codes for dbInit operation.
+ */
+export type DbInitFailureCode = 'PLANNING_FAILED' | 'MARKER_ORIGIN_MISMATCH' | 'RUNNER_FAILED';
+
+/**
+ * Failure details for dbInit operation.
+ */
+export interface DbInitFailure {
+  readonly code: DbInitFailureCode;
+  readonly summary: string;
+  readonly conflicts?: ReadonlyArray<MigrationPlannerConflict>;
+  readonly marker?: {
+    readonly coreHash?: string;
+    readonly profileHash?: string;
+  };
+  readonly destination?: {
+    readonly coreHash: string;
+    readonly profileHash?: string | undefined;
+  };
+}
+
+/**
+ * Result type for dbInit operation.
+ * Uses Result pattern: success returns DbInitSuccess, failure returns DbInitFailure.
+ */
+export type DbInitResult = Result<DbInitSuccess, DbInitFailure>;
+
+// ============================================================================
+// Client Interface
+// ============================================================================
+
+/**
+ * Programmatic control client for Prisma Next operations.
+ *
+ * Lifecycle: `connect(connection)` before operations, `close()` when done.
+ * Both `init()` and `connect()` are auto-called by operations if needed,
+ * but `connect()` requires a connection so must be called explicitly first
+ * unless a default connection was provided in options.
+ *
+ * @see README.md "Programmatic Control API" section for usage examples
+ */
+export interface ControlClient {
+  /**
+   * Initializes the client by creating the control plane stack,
+   * family instance, and validating framework components.
+   *
+   * Idempotent (safe to call multiple times).
+   * Called automatically by `connect()` if not already initialized.
+   */
+  init(): void;
+
+  /**
+   * Establishes a database connection.
+   * Auto-calls `init()` if not already initialized.
+   * Must be called before any database operations unless a default connection
+   * was provided in options.
+   *
+   * @param connection - Driver-specific connection input (e.g., URL string for Postgres).
+   *   If omitted, uses the default connection from options (if provided).
+   * @throws If connection fails, already connected, driver is not configured,
+   *   or no connection provided and no default connection in options.
+   */
+  connect(connection?: unknown): Promise<void>;
+
+  /**
+   * Closes the database connection.
+   * Idempotent (safe to call multiple times).
+   * After close(), can call `connect()` again with same or different URL.
+   */
+  close(): Promise<void>;
+
+  /**
+   * Verifies database marker matches the contract.
+   * Compares coreHash and profileHash.
+   *
+   * @returns Structured result (ok: false for mismatch, not throwing)
+   * @throws If not connected or infrastructure failure
+   */
+  verify(options: VerifyOptions): Promise<VerifyDatabaseResult>;
+
+  /**
+   * Verifies database schema satisfies the contract requirements.
+   *
+   * @param options.strict - If true, extra tables/columns are issues. Default: false
+   * @returns Structured result with schema issues
+   * @throws If not connected or infrastructure failure
+   */
+  schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult>;
+
+  /**
+   * Signs the database with a contract marker.
+   * Writes or updates the contract marker if schema verification passes.
+   * Idempotent (no-op if marker already matches).
+   *
+   * @returns Structured result
+   * @throws If not connected or infrastructure failure
+   */
+  sign(options: SignOptions): Promise<SignDatabaseResult>;
+
+  /**
+   * Initializes database schema from contract.
+   * Uses additive-only policy (no destructive changes).
+   *
+   * @param options.mode - 'plan' to preview, 'apply' to execute
+   * @returns Result pattern: Ok with planned/executed operations, NotOk with failure details
+   * @throws If not connected, target doesn't support migrations, or infrastructure failure
+   */
+  dbInit(options: DbInitOptions): Promise<DbInitResult>;
+
+  /**
+   * Introspects the database schema.
+   *
+   * @returns Raw schema IR
+   * @throws If not connected or infrastructure failure
+   */
+  introspect(options?: IntrospectOptions): Promise<unknown>;
+}

package/src/exports/control-api.ts

@@ -0,0 +1,34 @@
+/**
+ * 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';
+
+// CLI-specific types
+export type {
+  ControlClient,
+  ControlClientOptions,
+  DbInitFailure,
+  DbInitFailureCode,
+  DbInitOptions,
+  DbInitResult,
+  DbInitSuccess,
+  IntrospectOptions,
+  SchemaVerifyOptions,
+  SignOptions,
+  VerifyOptions,
+} from '../control-api/types';

package/src/utils/cli-errors.ts

@@ -10,7 +10,7 @@ export {
   errorContractConfigMissing,
   errorContractMissingExtensionPacks,
   errorContractValidationFailed,
-  errorDatabaseUrlRequired,
+  errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,