@prisma-next/cli 0.3.0-dev.5 → 0.3.0-dev.52

package/src/control-api/types.ts

@@ -0,0 +1,475 @@
+import type {
+  ContractSourceDiagnostics,
+  ContractSourceProvider,
+} from '@prisma-next/core-control-plane/config-types';
+import type { CoreSchemaView } from '@prisma-next/core-control-plane/schema-view';
+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;
+}
+
+// ============================================================================
+// Progress Events
+// ============================================================================
+
+/**
+ * Action names for control-api operations that can emit progress events.
+ */
+export type ControlActionName =
+  | 'dbInit'
+  | 'verify'
+  | 'schemaVerify'
+  | 'sign'
+  | 'introspect'
+  | 'emit';
+
+/**
+ * Progress event emitted during control-api operation execution.
+ *
+ * Events model operation progress using a span-based model:
+ * - `spanStart`: Begin a timed segment (supports nesting via parentSpanId)
+ * - `spanEnd`: Complete a timed segment
+ *
+ * All operation-specific progress (e.g., per-migration-operation) is modeled
+ * as nested spans rather than special event types.
+ *
+ * Events are delivered via an optional `onProgress` callback to avoid polluting
+ * return types. If the callback is absent, operations emit no events (zero overhead).
+ */
+export type ControlProgressEvent =
+  | {
+      readonly action: ControlActionName;
+      readonly kind: 'spanStart';
+      readonly spanId: string;
+      readonly parentSpanId?: string;
+      readonly label: string;
+    }
+  | {
+      readonly action: ControlActionName;
+      readonly kind: 'spanEnd';
+      readonly spanId: string;
+      readonly outcome: 'ok' | 'skipped' | 'error';
+    };
+
+/**
+ * Callback function for receiving progress events during control-api operations.
+ *
+ * @param event - The progress event emitted by the operation
+ */
+export type OnControlProgress = (event: ControlProgressEvent) => void;
+
+// ============================================================================
+// Operation Options
+// ============================================================================
+
+/**
+ * Options for the verify operation.
+ */
+export interface VerifyOptions {
+  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
+  readonly contractIR: unknown;
+  /**
+   * Database connection. If provided, verify will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * 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;
+  /**
+   * Database connection. If provided, schemaVerify will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Options for the sign operation.
+ */
+export interface SignOptions {
+  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
+  readonly contractIR: unknown;
+  /**
+   * Path to the contract file (for metadata in the result).
+   */
+  readonly contractPath?: string;
+  /**
+   * Path to the config file (for metadata in the result).
+   */
+  readonly configPath?: string;
+  /**
+   * Database connection. If provided, sign will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * 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';
+  /**
+   * Database connection. If provided, dbInit will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Options for the introspect operation.
+ */
+export interface IntrospectOptions {
+  /**
+   * Optional schema name to introspect.
+   */
+  readonly schema?: string;
+  /**
+   * Database connection. If provided, introspect will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Contract configuration for emit operation.
+ */
+export interface EmitContractConfig {
+  /**
+   * Contract source provider.
+   */
+  readonly sourceProvider: ContractSourceProvider;
+  /**
+   * Output path for contract.json.
+   * The .d.ts types file will be colocated (e.g., contract.json → contract.d.ts).
+   */
+  readonly output: string;
+}
+
+/**
+ * Options for the emit operation.
+ */
+export interface EmitOptions {
+  /**
+   * Contract configuration containing source, output, and types paths.
+   */
+  readonly contractConfig: EmitContractConfig;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+// ============================================================================
+// 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 storageHash: 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 why: string | undefined;
+  readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+  readonly marker?: {
+    readonly storageHash?: string;
+    readonly profileHash?: string;
+  };
+  readonly destination?: {
+    readonly storageHash: 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>;
+
+/**
+ * Successful emit result.
+ * Contains the hashes and paths of emitted files.
+ */
+export interface EmitSuccess {
+  /** Storage hash of the emitted contract */
+  readonly storageHash: string;
+  /** Execution hash of the emitted contract (if execution section exists) */
+  readonly executionHash?: string;
+  /** Profile hash of the emitted contract (target-specific) */
+  readonly profileHash: string;
+  /** The emitted contract as JSON string */
+  readonly contractJson: string;
+  /** The emitted contract TypeScript declarations */
+  readonly contractDts: string;
+}
+
+/**
+ * Failure codes for emit operation.
+ */
+export type EmitFailureCode = 'CONTRACT_SOURCE_INVALID' | 'EMIT_FAILED';
+
+/**
+ * Failure details for emit operation.
+ */
+export interface EmitFailure {
+  readonly code: EmitFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+  readonly diagnostics?: ContractSourceDiagnostics;
+}
+
+/**
+ * Result type for emit operation.
+ * Uses Result pattern: success returns EmitSuccess, failure returns EmitFailure.
+ */
+export type EmitResult = Result<EmitSuccess, EmitFailure>;
+
+// ============================================================================
+// Standalone Contract Emit Types
+// ============================================================================
+
+/**
+ * Options for the standalone executeContractEmit function.
+ * Used by tooling (e.g., Vite plugin) that needs to emit contracts
+ * without the full ControlClient infrastructure.
+ */
+export interface ContractEmitOptions {
+  /** Path to the prisma-next.config.ts file */
+  readonly configPath: string;
+  /** Optional AbortSignal for cancellation support */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Result from the standalone executeContractEmit function.
+ */
+export interface ContractEmitResult {
+  /** Hash of the storage contract (schema-level) */
+  readonly storageHash: string;
+  /** Hash of the execution contract (if execution section exists) */
+  readonly executionHash?: string;
+  /** Hash of the profile (target+extensions) */
+  readonly profileHash: string;
+  /** Paths to the emitted files */
+  readonly files: {
+    /** Path to the emitted contract.json file */
+    readonly json: string;
+    /** Path to the emitted contract.d.ts file */
+    readonly dts: string;
+  };
+}
+
+// ============================================================================
+// 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 storageHash 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>;
+
+  /**
+   * Converts a schema IR to a schema view for CLI tree rendering.
+   * Delegates to the family instance's toSchemaView method.
+   *
+   * @param schemaIR - The schema IR from introspect()
+   * @returns CoreSchemaView if the family supports it, undefined otherwise
+   */
+  toSchemaView(schemaIR: unknown): CoreSchemaView | undefined;
+
+  /**
+   * Emits the contract to JSON and TypeScript declarations.
+   * This is an offline operation that does NOT require a database connection.
+   * Uses `init()` to create the stack but does NOT call `connect()`.
+   *
+   * @returns Result pattern: Ok with emit details, NotOk with failure details
+   */
+  emit(options: EmitOptions): Promise<EmitResult>;
+}

package/src/exports/control-api.ts

@@ -0,0 +1,48 @@
+/**
+ * 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,
+  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,7 @@ export {
   errorContractConfigMissing,
   errorContractMissingExtensionPacks,
   errorContractValidationFailed,
-  errorDatabaseUrlRequired,
+  errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,

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,
   });