@prisma-next/cli 0.3.0-dev.15 → 0.3.0-dev.162

package/src/control-api/types.ts

@@ -1,14 +1,21 @@
+import type {
+  ContractSourceDiagnostics,
+  ContractSourceProvider,
+} from '@prisma-next/config/config-types';
+import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
   ControlExtensionDescriptor,
   ControlFamilyDescriptor,
   ControlTargetDescriptor,
+  CoreSchemaView,
   MigrationPlannerConflict,
+  MigrationPlanOperation,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
-} from '@prisma-next/core-control-plane/types';
+} from '@prisma-next/framework-components/control';
 import type { Result } from '@prisma-next/utils/result';
 
 // ============================================================================
@@ -30,7 +37,7 @@ 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>;
+  readonly target: ControlTargetDescriptor<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 */
@@ -46,6 +53,58 @@ export interface ControlClientOptions {
   readonly connection?: unknown;
 }
 
+// ============================================================================
+// Progress Events
+// ============================================================================
+
+/**
+ * Action names for control-api operations that can emit progress events.
+ */
+export type ControlActionName =
+  | 'dbInit'
+  | 'dbUpdate'
+  | 'migrationApply'
+  | '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
 // ============================================================================
@@ -54,44 +113,114 @@ export interface ControlClientOptions {
  * Options for the verify operation.
  */
 export interface VerifyOptions {
-  /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
-  readonly contractIR: unknown;
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: 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;
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: 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;
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: 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;
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: 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 dbUpdate operation.
+ */
+export interface DbUpdateOptions {
+  /** Contract or unvalidated JSON - validated at runtime via familyInstance.validateContract() */
+  readonly contract: unknown;
+  /**
+   * Mode for the dbUpdate operation.
+   * - 'plan': Returns planned operations without applying
+   * - 'apply': Applies operations and writes marker/ledger
+   */
+  readonly mode: 'plan' | 'apply';
+  /**
+   * Database connection. If provided, dbUpdate 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;
+  /**
+   * When true, allows applying plans that contain destructive operations
+   * (e.g., DROP TABLE, DROP COLUMN, ALTER TYPE).
+   * When false (default), the operation returns a failure if the plan
+   * includes destructive operations, prompting the user to confirm interactively
+   * or re-run with -y/--yes.
+   */
+  readonly acceptDataLoss?: boolean;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
 }
 
 /**
@@ -102,6 +231,41 @@ 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;
 }
 
 // ============================================================================
@@ -119,13 +283,18 @@ export interface DbInitSuccess {
       readonly label: string;
       readonly operationClass: string;
     }>;
+    readonly sql?: ReadonlyArray<string>;
+  };
+  readonly destination: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
   };
   readonly execution?: {
     readonly operationsPlanned: number;
     readonly operationsExecuted: number;
   };
   readonly marker?: {
-    readonly coreHash: string;
+    readonly storageHash: string;
     readonly profileHash?: string;
   };
   readonly summary: string;
@@ -142,13 +311,15 @@ export type DbInitFailureCode = 'PLANNING_FAILED' | 'MARKER_ORIGIN_MISMATCH' | '
 export interface DbInitFailure {
   readonly code: DbInitFailureCode;
   readonly summary: string;
-  readonly conflicts?: ReadonlyArray<MigrationPlannerConflict>;
+  readonly why: string | undefined;
+  readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly meta: Record<string, unknown> | undefined;
   readonly marker?: {
-    readonly coreHash?: string;
+    readonly storageHash?: string;
     readonly profileHash?: string;
   };
   readonly destination?: {
-    readonly coreHash: string;
+    readonly storageHash: string;
     readonly profileHash?: string | undefined;
   };
 }
@@ -159,6 +330,217 @@ export interface DbInitFailure {
  */
 export type DbInitResult = Result<DbInitSuccess, DbInitFailure>;
 
+/**
+ * Successful dbUpdate result.
+ */
+export interface DbUpdateSuccess {
+  readonly mode: 'plan' | 'apply';
+  readonly plan: {
+    readonly operations: ReadonlyArray<{
+      readonly id: string;
+      readonly label: string;
+      readonly operationClass: string;
+    }>;
+    readonly sql?: ReadonlyArray<string>;
+  };
+  readonly destination: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly execution?: {
+    readonly operationsPlanned: number;
+    readonly operationsExecuted: number;
+  };
+  readonly marker?: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  };
+  readonly summary: string;
+}
+
+/**
+ * Failure codes for dbUpdate operation.
+ */
+export type DbUpdateFailureCode = 'PLANNING_FAILED' | 'RUNNER_FAILED' | 'DESTRUCTIVE_CHANGES';
+
+/**
+ * Failure details for dbUpdate operation.
+ */
+export interface DbUpdateFailure {
+  readonly code: DbUpdateFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+}
+
+/**
+ * Result type for dbUpdate operation.
+ * Uses Result pattern: success returns DbUpdateSuccess, failure returns DbUpdateFailure.
+ */
+export type DbUpdateResult = Result<DbUpdateSuccess, DbUpdateFailure>;
+
+/**
+ * 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'
+  | 'CONTRACT_VALIDATION_FAILED'
+  | '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>;
+
+// ============================================================================
+// Migration Apply Types
+// ============================================================================
+
+/**
+ * A pre-planned migration step ready for execution.
+ * Contains the manifest metadata and the serialized operations from ops.json.
+ */
+export interface MigrationApplyStep {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly toContract: Contract;
+  readonly operations: readonly MigrationPlanOperation[];
+}
+
+/**
+ * Options for the migrationApply operation.
+ */
+export interface MigrationApplyOptions {
+  /**
+   * Hash of the database state this apply path starts from.
+   * This is resolved by the caller (typically the CLI orchestration layer).
+   */
+  readonly originHash: string;
+  /**
+   * Hash of the target contract this apply path must reach.
+   * This is resolved by the caller (typically the CLI orchestration layer).
+   */
+  readonly destinationHash: string;
+  /**
+   * Ordered list of migrations to execute from originHash to destinationHash.
+   * The execution layer does not choose defaults; it only executes this explicit path.
+   */
+  readonly pendingMigrations: readonly MigrationApplyStep[];
+  /**
+   * Database connection. If provided, migrationApply will connect before executing.
+   * If omitted, the client must already be connected.
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Record of a successfully applied migration.
+ */
+export interface MigrationApplyAppliedEntry {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly operationsExecuted: number;
+}
+
+/**
+ * Successful migrationApply result.
+ */
+export interface MigrationApplySuccess {
+  readonly migrationsApplied: number;
+  readonly markerHash: string;
+  readonly applied: readonly MigrationApplyAppliedEntry[];
+  readonly summary: string;
+}
+
+/**
+ * Failure codes for migrationApply operation.
+ */
+export type MigrationApplyFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
+
+/**
+ * Failure details for migrationApply operation.
+ */
+export interface MigrationApplyFailure {
+  readonly code: MigrationApplyFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+}
+
+/**
+ * Result type for migrationApply operation.
+ */
+export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyFailure>;
+
+// ============================================================================
+// 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
 // ============================================================================
@@ -205,7 +587,7 @@ export interface ControlClient {
 
   /**
    * Verifies database marker matches the contract.
-   * Compares coreHash and profileHash.
+   * Compares storageHash and profileHash.
    *
    * @returns Structured result (ok: false for mismatch, not throwing)
    * @throws If not connected or infrastructure failure
@@ -222,9 +604,9 @@ export interface ControlClient {
   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).
+   * Signs the database with a contract signature.
+   * Writes or updates the signature if schema verification passes.
+   * Idempotent (no-op if signature already matches).
    *
    * @returns Structured result
    * @throws If not connected or infrastructure failure
@@ -241,6 +623,38 @@ export interface ControlClient {
    */
   dbInit(options: DbInitOptions): Promise<DbInitResult>;
 
+  /**
+   * Updates a database schema to match the current contract.
+   * Creates the signature table if it does not exist. No preconditions required.
+   * Allows additive, widening, and destructive operation classes.
+   *
+   * @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
+   */
+  dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult>;
+
+  /**
+   * Reads the contract marker from the database.
+   * Returns null if no marker exists (fresh database).
+   *
+   * @throws If not connected or infrastructure failure
+   */
+  readMarker(): Promise<ContractMarkerRecord | null>;
+
+  /**
+   * Applies pre-planned on-disk migrations to the database.
+   * Each migration runs in its own transaction with full execution checks.
+   * Resume-safe: re-running after failure picks up from the last applied migration.
+   *
+   * @param options.originHash - Explicit source hash for the apply path
+   * @param options.destinationHash - Explicit destination hash for the apply path
+   * @param options.pendingMigrations - Ordered migrations to execute
+   * @returns Result pattern: Ok with applied details, NotOk with failure details
+   * @throws If not connected, target doesn't support migrations, or infrastructure failure
+   */
+  migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult>;
+
   /**
    * Introspects the database schema.
    *
@@ -248,4 +662,22 @@ export interface ControlClient {
    * @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/config-types.ts

@@ -1,6 +1,7 @@
-// Re-export core-control-plane config types for convenience
+// Re-export config package types for convenience
 export type {
   ContractConfig,
+  ContractSourceContext,
   PrismaNextConfig,
-} from '@prisma-next/core-control-plane/config-types';
-export { defineConfig } from '@prisma-next/core-control-plane/config-types';
+} from '@prisma-next/config/config-types';
+export { defineConfig } from '@prisma-next/config/config-types';

package/src/exports/control-api.ts

@@ -10,24 +10,46 @@
 
 // Re-export core control plane types for consumer convenience
 export type {
-  ControlPlaneStack,
+  ControlStack,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
-} from '@prisma-next/core-control-plane/types';
+} from '@prisma-next/framework-components/control';
 // Client factory
 export { createControlClient } from '../control-api/client';
 
+// Contract enrichment (merges framework-derived capabilities and extension pack metadata)
+export { enrichContract } from '../control-api/contract-enrichment';
+
+// 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,