@prisma-next/core-control-plane 0.3.0-dev.2 → 0.3.0-dev.21

package/dist/migrations.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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.).
+ */
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { Result } from '@prisma-next/utils/result';
+import type { ControlDriverInstance, ControlFamilyInstance } from './types';
+/**
+ * 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)
+ */
+export type MigrationOperationClass = 'additive' | 'widening' | 'destructive';
+/**
+ * Policy defining which operation classes are allowed during a migration.
+ */
+export 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).
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.
+ */
+export interface MigrationPlannerSuccessResult {
+    readonly kind: 'success';
+    readonly plan: MigrationPlan;
+}
+/**
+ * Failed planner result with the list of conflicts.
+ */
+export interface MigrationPlannerFailureResult {
+    readonly kind: 'failure';
+    readonly conflicts: readonly MigrationPlannerConflict[];
+}
+/**
+ * Union type for planner results.
+ */
+export type MigrationPlannerResult = MigrationPlannerSuccessResult | MigrationPlannerFailureResult;
+/**
+ * Success value for migration runner execution.
+ */
+export interface MigrationRunnerSuccessValue {
+    readonly operationsPlanned: number;
+    readonly operationsExecuted: number;
+}
+/**
+ * Failure details for migration runner execution.
+ */
+export 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;
+    /** Optional metadata for debugging and UX (e.g., schema issues, SQL state). */
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Result type for migration runner execution.
+ */
+export type MigrationRunnerResult = Result<MigrationRunnerSuccessValue, MigrationRunnerFailure>;
+/**
+ * Execution-time checks configuration for migration runners.
+ * All checks default to `true` (enabled) when omitted.
+ */
+export interface MigrationRunnerExecutionChecks {
+    /**
+     * Whether to run prechecks before executing operations.
+     * Defaults to `true` (prechecks are run).
+     */
+    readonly prechecks?: boolean;
+    /**
+     * Whether to run postchecks after executing operations.
+     * Defaults to `true` (postchecks are run).
+     */
+    readonly postchecks?: boolean;
+    /**
+     * Whether to run idempotency probe (check if postcheck is already satisfied before execution).
+     * Defaults to `true` (idempotency probe is run).
+     */
+    readonly idempotencyChecks?: boolean;
+}
+/**
+ * Migration planner interface for planning schema changes.
+ * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+export interface MigrationPlanner<TFamilyId extends string = string, TTargetId extends string = string> {
+    plan(options: {
+        readonly contract: unknown;
+        readonly schema: unknown;
+        readonly policy: MigrationOperationPolicy;
+        /**
+         * Active framework components participating in this composition.
+         * Families/targets can interpret this list to derive family-specific metadata.
+         * All components must have matching familyId and targetId.
+         */
+        readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+    }): MigrationPlannerResult;
+}
+/**
+ * Migration runner interface for executing migration plans.
+ * This is the minimal interface that CLI commands use.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+export interface MigrationRunner<TFamilyId extends string = string, TTargetId extends string = string> {
+    execute(options: {
+        readonly plan: MigrationPlan;
+        readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+        readonly destinationContract: unknown;
+        readonly policy: MigrationOperationPolicy;
+        readonly callbacks?: {
+            onOperationStart?(op: MigrationPlanOperation): void;
+            onOperationComplete?(op: MigrationPlanOperation): void;
+        };
+        /**
+         * Execution-time checks configuration.
+         * All checks default to `true` (enabled) when omitted.
+         */
+        readonly executionChecks?: MigrationRunnerExecutionChecks;
+        /**
+         * Active framework components participating in this composition.
+         * Families/targets can interpret this list to derive family-specific metadata.
+         * All components must have matching familyId and targetId.
+         */
+        readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+    }): Promise<MigrationRunnerResult>;
+}
+/**
+ * Optional capability interface for targets that support migrations.
+ * Targets that implement migrations expose this via their descriptor.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TFamilyInstance - The family instance type (e.g., SqlControlFamilyInstance)
+ */
+export interface TargetMigrationsCapability<TFamilyId extends string = string, TTargetId extends string = string, TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>> {
+    createPlanner(family: TFamilyInstance): MigrationPlanner<TFamilyId, TTargetId>;
+    createRunner(family: TFamilyInstance): MigrationRunner<TFamilyId, TTargetId>;
+}
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"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"}

package/dist/schema-view.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Core schema view types for family-agnostic schema visualization.
+ *
+ * These types provide a minimal, generic, tree-shaped representation of schemas
+ * across families, designed for CLI visualization and lightweight tooling.
+ *
+ * Families can optionally project their family-specific Schema IR into this
+ * core view via the `toSchemaView` method on `FamilyInstance`.
+ *
+ * ## Example: SQL Family Mapping
+ *
+ * For the SQL family, `SqlSchemaIR` can be mapped to `CoreSchemaView` as follows:
+ *
+ * ```ts
+ * // SqlSchemaIR structure:
+ * // {
+ * //   tables: { user: { columns: {...}, primaryKey: {...}, ... }, ... },
+ * //   extensions: ['pgvector'],
+ * //   annotations: {...}
+ * // }
+ *
+ * // CoreSchemaView mapping:
+ * // {
+ * //   root: {
+ * //     kind: 'root',
+ * //     id: 'sql-schema',
+ * //     label: 'sql schema (tables: 2)',
+ * //     children: [
+ * //       {
+ * //         kind: 'entity',
+ * //         id: 'table-user',
+ * //         label: 'table user',
+ * //         meta: { primaryKey: ['id'], ... },
+ * //         children: [
+ * //           {
+ * //             kind: 'field',
+ * //             id: 'column-id',
+ * //             label: 'id: int4 (pg/int4@1, not null)',
+ * //             meta: { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false, ... }
+ * //           },
+ * //           {
+ * //             kind: 'index',
+ * //             id: 'index-user-email',
+ * //             label: 'index user_email_unique',
+ * //             meta: { columns: ['email'], unique: true, ... }
+ * //           }
+ * //         ]
+ * //       },
+ * //       {
+ * //         kind: 'extension',
+ * //         id: 'extension-pgvector',
+ * //         label: 'extension pgvector',
+ * //         meta: { ... }
+ * //       }
+ * //     ]
+ * //   }
+ * // }
+ * ```
+ *
+ * This mapping demonstrates that the core view types are expressive enough
+ * to represent SQL schemas without being SQL-specific.
+ */
+/**
+ * Node kinds for schema tree nodes.
+ * Designed to be generic enough for SQL, document, KV, and future families.
+ */
+export type SchemaNodeKind = 'root' | 'namespace' | 'collection' | 'entity' | 'field' | 'index' | 'extension';
+/**
+ * A node in the schema tree.
+ * Tree-shaped structure good for Command Tree-style CLI output.
+ */
+export interface SchemaTreeNode {
+    readonly kind: SchemaNodeKind;
+    readonly id: string;
+    readonly label: string;
+    readonly meta?: Record<string, unknown>;
+    readonly children?: readonly SchemaTreeNode[];
+}
+/**
+ * Core schema view providing a family-agnostic tree representation of a schema.
+ * Used by CLI and cross-family tooling for visualization.
+ */
+export interface CoreSchemaView {
+    readonly root: SchemaTreeNode;
+}
+//# sourceMappingURL=schema-view.d.ts.map

package/dist/schema-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-view.d.ts","sourceRoot":"","sources":["../src/schema-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,OAAO,GACP,WAAW,CAAC;AAEhB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B"}

package/dist/stack.d.ts

@@ -0,0 +1,25 @@
+import type { ControlAdapterDescriptor, ControlDriverDescriptor, ControlExtensionDescriptor, ControlPlaneStack, ControlTargetDescriptor } from './types';
+/**
+ * Creates a ControlPlaneStack from component descriptors.
+ *
+ * Provides sensible defaults:
+ * - `driver` defaults to `undefined` (optional for commands that don't need DB connection)
+ * - `extensionPacks` defaults to `[]` (empty array)
+ *
+ * @example
+ * ```ts
+ * const stack = createControlPlaneStack({
+ *   target: postgresTarget,
+ *   adapter: postgresAdapter,
+ *   driver: postgresDriver, // optional
+ *   extensionPacks: [pgvector], // optional
+ * });
+ * ```
+ */
+export declare function createControlPlaneStack<TFamilyId extends string, TTargetId extends string>(input: {
+    readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
+    readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;
+    readonly driver?: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;
+    readonly extensionPacks?: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[] | undefined;
+}): ControlPlaneStack<TFamilyId, TTargetId>;
+//# sourceMappingURL=stack.d.ts.map

package/dist/stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../src/stack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,SAAS,MAAM,EAAE,SAAS,SAAS,MAAM,EAAE,KAAK,EAAE;IACjG,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC;IAC5E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,0BAA0B,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC;CACnG,GAAG,iBAAiB,CAAC,SAAS,EAAE,SAAS,CAAC,CAO1C"}