@prisma-next/cli 0.3.0-pr.99.5 → 0.3.0

package/src/control-api/client.ts

@@ -1,25 +1,42 @@
-import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
-import type { CoreSchemaView } from '@prisma-next/core-control-plane/schema-view';
-import { createControlPlaneStack } from '@prisma-next/core-control-plane/stack';
+import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import { emit as emitContractArtifacts } from '@prisma-next/emitter';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
   ControlDriverInstance,
   ControlFamilyInstance,
-  ControlPlaneStack,
+  ControlStack,
+  CoreSchemaView,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
-} from '@prisma-next/core-control-plane/types';
+} from '@prisma-next/framework-components/control';
+import {
+  createControlStack,
+  hasMigrations,
+  hasSchemaView,
+} from '@prisma-next/framework-components/control';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
+import { enrichContract } from './contract-enrichment';
+import { ContractValidationError } from './errors';
 import { executeDbInit } from './operations/db-init';
+import { executeDbUpdate } from './operations/db-update';
+import { executeMigrationApply } from './operations/migration-apply';
 import type {
+  ControlActionName,
   ControlClient,
   ControlClientOptions,
   DbInitOptions,
   DbInitResult,
+  DbUpdateOptions,
+  DbUpdateResult,
   EmitOptions,
   EmitResult,
   IntrospectOptions,
+  MigrationApplyOptions,
+  MigrationApplyResult,
+  OnControlProgress,
   SchemaVerifyOptions,
   SignOptions,
   VerifyOptions,
@@ -45,9 +62,9 @@ export function createControlClient(options: ControlClientOptions): ControlClien
  */
 class ControlClientImpl implements ControlClient {
   private readonly options: ControlClientOptions;
-  private stack: ControlPlaneStack<string, string> | null = null;
+  private stack: ControlStack | null = null;
   private driver: ControlDriverInstance<string, string> | null = null;
-  private familyInstance: ControlFamilyInstance<string> | null = null;
+  private familyInstance: ControlFamilyInstance<string, unknown> | null = null;
   private frameworkComponents: ReadonlyArray<
     TargetBoundComponentDescriptor<string, string>
   > | null = null;
@@ -64,15 +81,14 @@ class ControlClientImpl implements ControlClient {
       return; // Idempotent
     }
 
-    // Create the control plane stack
-    this.stack = createControlPlaneStack({
+    this.stack = createControlStack({
+      family: this.options.family,
       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
@@ -113,12 +129,8 @@ class ControlClientImpl implements ControlClient {
       );
     }
 
-    // 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);
+    this.driver = await this.stack.driver.create(resolvedConnection as any);
   }
 
   async close(): Promise<void> {
@@ -130,7 +142,7 @@ class ControlClientImpl implements ControlClient {
 
   private async ensureConnected(): Promise<{
     driver: ControlDriverInstance<string, string>;
-    familyInstance: ControlFamilyInstance<string>;
+    familyInstance: ControlFamilyInstance<string, unknown>;
     frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<string, string>>;
   }> {
     // Auto-init if needed
@@ -151,47 +163,47 @@ class ControlClientImpl implements ControlClient {
     };
   }
 
-  async verify(options: VerifyOptions): Promise<VerifyDatabaseResult> {
-    const { onProgress } = options;
-
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'verify',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'verify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'verify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
+  private async connectWithProgress(
+    connection: unknown | undefined,
+    action: ControlActionName,
+    onProgress?: OnControlProgress,
+  ): Promise<void> {
+    if (connection === undefined) return;
+    onProgress?.({
+      action,
+      kind: 'spanStart',
+      spanId: 'connect',
+      label: 'Connecting to database...',
+    });
+    try {
+      await this.connect(connection);
+      onProgress?.({ action, kind: 'spanEnd', spanId: 'connect', outcome: 'ok' });
+    } catch (error) {
+      onProgress?.({ action, kind: 'spanEnd', spanId: 'connect', outcome: 'error' });
+      throw error;
     }
+  }
 
+  async verify(options: VerifyOptions): Promise<VerifyDatabaseResult> {
+    const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'verify', onProgress);
     const { driver, familyInstance } = await this.ensureConnected();
 
     // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
     // Emit verify span
     onProgress?.({
       action: 'verify',
       kind: 'spanStart',
       spanId: 'verify',
-      label: 'Verifying contract marker...',
+      label: 'Verifying database marker...',
     });
 
     try {
@@ -201,7 +213,7 @@ class ControlClientImpl implements ControlClient {
       // metadata for error reporting.
       const result = await familyInstance.verify({
         driver,
-        contractIR,
+        contract,
         expectedTargetId: this.options.target.targetId,
         contractPath: '',
       });
@@ -227,38 +239,17 @@ class ControlClientImpl implements ControlClient {
 
   async schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult> {
     const { onProgress } = options;
-
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'schemaVerify',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'schemaVerify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'schemaVerify',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
-    }
-
+    await this.connectWithProgress(options.connection, 'schemaVerify', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
     // Emit schemaVerify span
     onProgress?.({
@@ -272,7 +263,7 @@ class ControlClientImpl implements ControlClient {
       // Delegate to family instance schemaVerify method
       const result = await familyInstance.schemaVerify({
         driver,
-        contractIR,
+        contract,
         strict: options.strict ?? false,
         contractPath: '',
         frameworkComponents,
@@ -299,38 +290,17 @@ class ControlClientImpl implements ControlClient {
 
   async sign(options: SignOptions): Promise<SignDatabaseResult> {
     const { onProgress } = options;
-
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'sign',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'sign',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'sign',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
-    }
-
+    await this.connectWithProgress(options.connection, 'sign', onProgress);
     const { driver, familyInstance } = await this.ensureConnected();
 
     // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
     // Emit sign span
     onProgress?.({
@@ -344,9 +314,9 @@ class ControlClientImpl implements ControlClient {
       // Delegate to family instance sign method
       const result = await familyInstance.sign({
         driver,
-        contractIR,
+        contract,
         contractPath: options.contractPath ?? '',
-        ...(options.configPath ? { configPath: options.configPath } : {}),
+        ...ifDefined('configPath', options.configPath),
       });
 
       onProgress?.({
@@ -370,86 +340,91 @@ class ControlClientImpl implements ControlClient {
 
   async dbInit(options: DbInitOptions): Promise<DbInitResult> {
     const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'dbInit', onProgress);
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
-    // Connect with progress span if connection provided
-    if (options.connection !== undefined) {
-      onProgress?.({
-        action: 'dbInit',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'dbInit',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'dbInit',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
+    if (!hasMigrations(this.options.target)) {
+      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
+
+    return executeDbInit({
+      driver,
+      familyInstance,
+      contract,
+      mode: options.mode,
+      migrations: this.options.target.migrations,
+      frameworkComponents,
+      ...ifDefined('onProgress', onProgress),
+    });
+  }
+
+  async dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult> {
+    const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'dbUpdate', onProgress);
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
-    // Check target supports migrations
-    if (!this.options.target.migrations) {
+    if (!hasMigrations(this.options.target)) {
       throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
-    // Validate contract using family instance
-    const contractIR = familyInstance.validateContractIR(options.contractIR);
+    let contract: Contract;
+    try {
+      contract = familyInstance.validateContract(options.contract);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ContractValidationError(message, error);
+    }
 
-    // Delegate to extracted dbInit operation
-    return executeDbInit({
+    return executeDbUpdate({
       driver,
       familyInstance,
-      contractIR,
+      contract,
       mode: options.mode,
       migrations: this.options.target.migrations,
       frameworkComponents,
-      ...(onProgress ? { onProgress } : {}),
+      ...ifDefined('acceptDataLoss', options.acceptDataLoss),
+      ...ifDefined('onProgress', onProgress),
     });
   }
 
-  async introspect(options?: IntrospectOptions): Promise<unknown> {
-    const onProgress = options?.onProgress;
+  async readMarker(): Promise<ContractMarkerRecord | null> {
+    const { driver, familyInstance } = await this.ensureConnected();
+    return familyInstance.readMarker({ driver });
+  }
 
-    // Connect with progress span if connection provided
-    if (options?.connection !== undefined) {
-      onProgress?.({
-        action: 'introspect',
-        kind: 'spanStart',
-        spanId: 'connect',
-        label: 'Connecting to database...',
-      });
-      try {
-        await this.connect(options.connection);
-        onProgress?.({
-          action: 'introspect',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'ok',
-        });
-      } catch (error) {
-        onProgress?.({
-          action: 'introspect',
-          kind: 'spanEnd',
-          spanId: 'connect',
-          outcome: 'error',
-        });
-        throw error;
-      }
+  async migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult> {
+    const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'migrationApply', onProgress);
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+
+    if (!hasMigrations(this.options.target)) {
+      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
     }
 
+    return executeMigrationApply({
+      driver,
+      familyInstance,
+      originHash: options.originHash,
+      destinationHash: options.destinationHash,
+      pendingMigrations: options.pendingMigrations,
+      migrations: this.options.target.migrations,
+      frameworkComponents,
+      targetId: this.options.target.targetId,
+      ...(onProgress ? { onProgress } : {}),
+    });
+  }
+
+  async introspect(options?: IntrospectOptions): Promise<unknown> {
+    const onProgress = options?.onProgress;
+    await this.connectWithProgress(options?.connection, 'introspect', onProgress);
     const { driver, familyInstance } = await this.ensureConnected();
 
     // TODO: Pass schema option to familyInstance.introspect when schema filtering is implemented
@@ -488,7 +463,7 @@ class ControlClientImpl implements ControlClient {
 
   toSchemaView(schemaIR: unknown): CoreSchemaView | undefined {
     this.init();
-    if (this.familyInstance?.toSchemaView) {
+    if (this.familyInstance && hasSchemaView(this.familyInstance)) {
       return this.familyInstance.toSchemaView(schemaIR);
     }
     return undefined;
@@ -505,7 +480,6 @@ class ControlClientImpl implements ControlClient {
       throw new Error('Family instance was not initialized. This is a bug.');
     }
 
-    // Resolve contract source
     let contractRaw: unknown;
     onProgress?.({
       action: 'emit',
@@ -515,14 +489,27 @@ class ControlClientImpl implements ControlClient {
     });
 
     try {
-      switch (contractConfig.source.kind) {
-        case 'loader':
-          contractRaw = await contractConfig.source.load();
-          break;
-        case 'value':
-          contractRaw = contractConfig.source.value;
-          break;
+      const sourceContext = {
+        composedExtensionPacks: (this.options.extensionPacks ?? []).map((p) => p.id),
+      };
+      const providerResult = await contractConfig.sourceProvider(sourceContext);
+      if (!providerResult.ok) {
+        onProgress?.({
+          action: 'emit',
+          kind: 'spanEnd',
+          spanId: 'resolveSource',
+          outcome: 'error',
+        });
+
+        return notOk({
+          code: 'CONTRACT_SOURCE_INVALID',
+          summary: providerResult.failure.summary,
+          why: providerResult.failure.summary,
+          meta: providerResult.failure.meta,
+          diagnostics: providerResult.failure,
+        });
       }
+      contractRaw = providerResult.value;
 
       onProgress?.({
         action: 'emit',
@@ -538,10 +525,20 @@ class ControlClientImpl implements ControlClient {
         outcome: 'error',
       });
 
+      const message = error instanceof Error ? error.message : String(error);
       return notOk({
         code: 'CONTRACT_SOURCE_INVALID',
         summary: 'Failed to resolve contract source',
-        why: error instanceof Error ? error.message : String(error),
+        why: message,
+        diagnostics: {
+          summary: 'Contract source provider threw an exception',
+          diagnostics: [
+            {
+              code: 'PROVIDER_THROW',
+              message,
+            },
+          ],
+        },
         meta: undefined,
       });
     }
@@ -555,7 +552,31 @@ class ControlClientImpl implements ControlClient {
     });
 
     try {
-      const emitResult = await this.familyInstance.emitContract({ contractIR: contractRaw });
+      const enrichedIR = enrichContract(contractRaw as Contract, this.frameworkComponents ?? []);
+
+      try {
+        this.familyInstance.validateContract(enrichedIR);
+      } catch (error) {
+        onProgress?.({
+          action: 'emit',
+          kind: 'spanEnd',
+          spanId: 'emit',
+          outcome: 'error',
+        });
+        const message = error instanceof Error ? error.message : String(error);
+        return notOk({
+          code: 'CONTRACT_VALIDATION_FAILED',
+          summary: 'Contract validation failed',
+          why: message,
+          meta: undefined,
+        });
+      }
+
+      const result = await emitContractArtifacts(
+        enrichedIR,
+        this.stack!,
+        this.options.family.emission,
+      );
 
       onProgress?.({
         action: 'emit',
@@ -565,10 +586,11 @@ class ControlClientImpl implements ControlClient {
       });
 
       return ok({
-        coreHash: emitResult.coreHash,
-        profileHash: emitResult.profileHash,
-        contractJson: emitResult.contractJson,
-        contractDts: emitResult.contractDts,
+        storageHash: result.storageHash,
+        ...ifDefined('executionHash', result.executionHash),
+        profileHash: result.profileHash,
+        contractJson: result.contractJson,
+        contractDts: result.contractDts,
       });
     } catch (error) {
       onProgress?.({

package/src/control-api/contract-enrichment.ts

@@ -0,0 +1,119 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+
+type CapabilityMatrix = Record<string, Record<string, boolean>>;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function sortDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortDeep);
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  const next: Record<string, unknown> = {};
+  for (const [key, child] of entries) {
+    next[key] = sortDeep(child);
+  }
+  return next;
+}
+
+function sortDeepTyped<T>(value: T): T {
+  return sortDeep(value) as T;
+}
+
+function extractCapabilityMatrix(value: unknown): CapabilityMatrix {
+  if (!isPlainObject(value)) return {};
+
+  const out: CapabilityMatrix = {};
+  for (const [namespace, maybeCaps] of Object.entries(value)) {
+    if (!isPlainObject(maybeCaps)) continue;
+    const caps: Record<string, boolean> = {};
+    for (const [key, flag] of Object.entries(maybeCaps)) {
+      if (typeof flag === 'boolean') {
+        caps[key] = flag;
+      }
+    }
+    if (Object.keys(caps).length > 0) {
+      out[namespace] = caps;
+    }
+  }
+
+  return out;
+}
+
+function mergeCapabilities(left: CapabilityMatrix, right: CapabilityMatrix): CapabilityMatrix {
+  const next: CapabilityMatrix = { ...left };
+  for (const [namespace, capabilities] of Object.entries(right)) {
+    next[namespace] = {
+      ...(left[namespace] ?? {}),
+      ...capabilities,
+    };
+  }
+  return next;
+}
+
+function extractExtensionPackMeta(
+  component: TargetBoundComponentDescriptor<string, string>,
+): Record<string, unknown> {
+  const { kind, id, version, capabilities, types } = component;
+  const base: Record<string, unknown> = {
+    kind,
+    id,
+    familyId: component.familyId,
+    targetId: component.targetId,
+    version,
+  };
+  if (capabilities) {
+    base['capabilities'] = capabilities;
+  }
+  if (types) {
+    if (types.codecTypes) {
+      const { controlPlaneHooks: _, codecInstances: _ci, ...cleanedCodecTypes } = types.codecTypes;
+      base['types'] = { ...types, codecTypes: cleanedCodecTypes };
+    } else {
+      base['types'] = types;
+    }
+  }
+  return base;
+}
+
+/**
+ * Enriches a raw contract with framework-derived metadata:
+ * capabilities from all component descriptors and extension pack metadata
+ * from extension descriptors. Produces deterministically sorted output.
+ */
+export function enrichContract(
+  ir: Contract,
+  components: ReadonlyArray<TargetBoundComponentDescriptor<string, string>>,
+): Contract {
+  let mergedCapabilities = ir.capabilities;
+  const extensionPacksMeta: Record<string, unknown> = {};
+
+  for (const component of components) {
+    if (component.capabilities) {
+      mergedCapabilities = mergeCapabilities(
+        mergedCapabilities,
+        extractCapabilityMatrix(component.capabilities),
+      );
+    }
+    if (component.kind === 'extension') {
+      extensionPacksMeta[component.id] = extractExtensionPackMeta(component);
+    }
+  }
+
+  const extensionPacks =
+    Object.keys(extensionPacksMeta).length > 0
+      ? { ...ir.extensionPacks, ...extensionPacksMeta }
+      : ir.extensionPacks;
+
+  return {
+    ...ir,
+    capabilities: sortDeepTyped(mergedCapabilities),
+    extensionPacks: sortDeepTyped(extensionPacks),
+  };
+}