@prisma-next/core-control-plane 0.1.0-dev.16 → 0.1.0-dev.17

package/dist/exports/config-types.d.ts

@@ -2,6 +2,7 @@ import { ControlFamilyDescriptor, ControlTargetDescriptor, ControlAdapterDescrip
 import '@prisma-next/contract/ir';
 import '@prisma-next/contract/pack-manifest-types';
 import '@prisma-next/contract/types';
+import '@prisma-next/utils/result';
 import './schema-view.js';
 
 /**

package/dist/exports/config-validation.d.ts

@@ -3,6 +3,7 @@ import './types.js';
 import '@prisma-next/contract/ir';
 import '@prisma-next/contract/pack-manifest-types';
 import '@prisma-next/contract/types';
+import '@prisma-next/utils/result';
 import './schema-view.js';
 
 /**

package/dist/exports/types.d.ts

@@ -1,8 +1,149 @@
 import { ContractIR } from '@prisma-next/contract/ir';
 import { ExtensionPackManifest } from '@prisma-next/contract/pack-manifest-types';
 import { TargetFamilyHook } from '@prisma-next/contract/types';
+import { Result } from '@prisma-next/utils/result';
 import { CoreSchemaView } from './schema-view.js';
 
+/**
+ * Core migration types for the framework control plane.
+ *
+ * These are family-agnostic, display-oriented types that provide a stable
+ * vocabulary for CLI commands to work with migration planners and runners
+ * without importing family-specific types.
+ *
+ * Family-specific types (e.g., SqlMigrationPlan) extend these base types
+ * with additional fields for execution (precheck SQL, execute SQL, etc.).
+ */
+
+/**
+ * Migration operation classes define the safety level of an operation.
+ * - 'additive': Adds new structures without modifying existing ones (safe)
+ * - 'widening': Relaxes constraints or expands types (generally safe)
+ * - 'destructive': Removes or alters existing structures (potentially unsafe)
+ */
+type MigrationOperationClass = 'additive' | 'widening' | 'destructive';
+/**
+ * Policy defining which operation classes are allowed during a migration.
+ */
+interface MigrationOperationPolicy {
+    readonly allowedOperationClasses: readonly MigrationOperationClass[];
+}
+/**
+ * A single migration operation for display purposes.
+ * Contains only the fields needed for CLI output (tree view, JSON envelope).
+ */
+interface MigrationPlanOperation {
+    /** Unique identifier for this operation (e.g., "table.users.create"). */
+    readonly id: string;
+    /** Human-readable label for display in UI/CLI (e.g., "Create table users"). */
+    readonly label: string;
+    /** The class of operation (additive, widening, destructive). */
+    readonly operationClass: MigrationOperationClass;
+}
+/**
+ * A migration plan for display purposes.
+ * Contains only the fields needed for CLI output (summary, JSON envelope).
+ */
+interface MigrationPlan {
+    /** The target ID this plan is for (e.g., 'postgres'). */
+    readonly targetId: string;
+    /** Destination contract identity that the plan intends to reach. */
+    readonly destination: {
+        readonly coreHash: string;
+        readonly profileHash?: string;
+    };
+    /** Ordered list of operations to execute. */
+    readonly operations: readonly MigrationPlanOperation[];
+}
+/**
+ * A conflict detected during migration planning.
+ */
+interface MigrationPlannerConflict {
+    /** Kind of conflict (e.g., 'typeMismatch', 'nullabilityConflict'). */
+    readonly kind: string;
+    /** Human-readable summary of the conflict. */
+    readonly summary: string;
+    /** Optional explanation of why this conflict occurred. */
+    readonly why?: string;
+}
+/**
+ * Successful planner result with the migration plan.
+ */
+interface MigrationPlannerSuccessResult {
+    readonly kind: 'success';
+    readonly plan: MigrationPlan;
+}
+/**
+ * Failed planner result with the list of conflicts.
+ */
+interface MigrationPlannerFailureResult {
+    readonly kind: 'failure';
+    readonly conflicts: readonly MigrationPlannerConflict[];
+}
+/**
+ * Union type for planner results.
+ */
+type MigrationPlannerResult = MigrationPlannerSuccessResult | MigrationPlannerFailureResult;
+/**
+ * Success value for migration runner execution.
+ */
+interface MigrationRunnerSuccessValue {
+    readonly operationsPlanned: number;
+    readonly operationsExecuted: number;
+}
+/**
+ * Failure details for migration runner execution.
+ */
+interface MigrationRunnerFailure {
+    /** Error code for the failure. */
+    readonly code: string;
+    /** Human-readable summary of the failure. */
+    readonly summary: string;
+    /** Optional explanation of why the failure occurred. */
+    readonly why?: string;
+}
+/**
+ * Result type for migration runner execution.
+ */
+type MigrationRunnerResult = Result<MigrationRunnerSuccessValue, MigrationRunnerFailure>;
+/**
+ * Migration planner interface for planning schema changes.
+ * This is the minimal interface that CLI commands use.
+ */
+interface MigrationPlanner {
+    plan(options: {
+        readonly contract: unknown;
+        readonly schema: unknown;
+        readonly policy: MigrationOperationPolicy;
+    }): MigrationPlannerResult;
+}
+/**
+ * Migration runner interface for executing migration plans.
+ * This is the minimal interface that CLI commands use.
+ */
+interface MigrationRunner {
+    execute(options: {
+        readonly plan: MigrationPlan;
+        readonly driver: ControlDriverInstance;
+        readonly destinationContract: unknown;
+        readonly policy: MigrationOperationPolicy;
+        readonly callbacks?: {
+            onOperationStart?(op: MigrationPlanOperation): void;
+            onOperationComplete?(op: MigrationPlanOperation): void;
+        };
+    }): Promise<MigrationRunnerResult>;
+}
+/**
+ * Optional capability interface for targets that support migrations.
+ * Targets that implement migrations expose this via their descriptor.
+ *
+ * @template TFamilyInstance - The family instance type (e.g., SqlControlFamilyInstance)
+ */
+interface TargetMigrationsCapability<TFamilyInstance extends ControlFamilyInstance<string> = ControlFamilyInstance<string>> {
+    createPlanner(family: TFamilyInstance): MigrationPlanner;
+    createRunner(family: TFamilyInstance): MigrationRunner;
+}
+
 /**
  * Base interface for control-plane family instances.
  * Families extend this with domain-specific methods.
@@ -117,13 +258,19 @@ interface ControlFamilyDescriptor<TFamilyId extends string, TFamilyInstance exte
  * @template TFamilyId - The family ID (e.g., 'sql', 'document')
  * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
  * @template TTargetInstance - The target instance type
+ * @template TFamilyInstance - The family instance type for migrations (optional)
  */
-interface ControlTargetDescriptor<TFamilyId extends string, TTargetId extends string, TTargetInstance extends ControlTargetInstance<TFamilyId, TTargetId> = ControlTargetInstance<TFamilyId, TTargetId>> {
+interface ControlTargetDescriptor<TFamilyId extends string, TTargetId extends string, TTargetInstance extends ControlTargetInstance<TFamilyId, TTargetId> = ControlTargetInstance<TFamilyId, TTargetId>, TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>> {
     readonly kind: 'target';
     readonly id: string;
     readonly familyId: TFamilyId;
     readonly targetId: TTargetId;
     readonly manifest: ExtensionPackManifest;
+    /**
+     * Optional migrations capability.
+     * Targets that support migrations expose this property.
+     */
+    readonly migrations?: TargetMigrationsCapability<TFamilyInstance>;
     create(): TTargetInstance;
 }
 /**
@@ -403,4 +550,4 @@ interface SignDatabaseResult {
     };
 }
 
-export type { ControlAdapterDescriptor, ControlAdapterInstance, ControlDriverDescriptor, ControlDriverInstance, ControlExtensionDescriptor, ControlExtensionInstance, ControlFamilyDescriptor, ControlFamilyInstance, ControlTargetDescriptor, ControlTargetInstance, EmitContractResult, FamilyInstance, IntrospectSchemaResult, OperationContext, SchemaIssue, SchemaVerificationNode, SignDatabaseResult, VerifyDatabaseResult, VerifyDatabaseSchemaResult };
+export type { ControlAdapterDescriptor, ControlAdapterInstance, ControlDriverDescriptor, ControlDriverInstance, ControlExtensionDescriptor, ControlExtensionInstance, ControlFamilyDescriptor, ControlFamilyInstance, ControlTargetDescriptor, ControlTargetInstance, EmitContractResult, FamilyInstance, IntrospectSchemaResult, MigrationOperationClass, MigrationOperationPolicy, MigrationPlan, MigrationPlanOperation, MigrationPlanner, MigrationPlannerConflict, MigrationPlannerFailureResult, MigrationPlannerResult, MigrationPlannerSuccessResult, MigrationRunner, MigrationRunnerFailure, MigrationRunnerResult, MigrationRunnerSuccessValue, OperationContext, SchemaIssue, SchemaVerificationNode, SignDatabaseResult, TargetMigrationsCapability, VerifyDatabaseResult, VerifyDatabaseSchemaResult };

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@prisma-next/core-control-plane",
-  "version": "0.1.0-dev.16",
+  "version": "0.1.0-dev.17",
   "type": "module",
   "sideEffects": false,
   "description": "Control plane domain actions, config types, validation, and error factories for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.26",
     "prettier": "^3.3.3",
-    "@prisma-next/contract": "0.1.0-dev.16",
-    "@prisma-next/operations": "0.1.0-dev.16",
-    "@prisma-next/utils": "0.1.0-dev.16"
+    "@prisma-next/contract": "0.1.0-dev.17",
+    "@prisma-next/operations": "0.1.0-dev.17",
+    "@prisma-next/utils": "0.1.0-dev.17"
   },
   "devDependencies": {
     "tsup": "^8.3.0",