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

package/src/control-api/client.ts

@@ -1,21 +1,42 @@
-import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
-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,
@@ -41,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;
@@ -60,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
@@ -109,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> {
@@ -126,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
@@ -147,83 +163,449 @@ class ControlClientImpl implements ControlClient {
     };
   }
 
+  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);
+    }
 
-    // Delegate to family instance verify method
-    // Note: We pass empty strings for contractPath/configPath since the programmatic
-    // API doesn't deal with file paths. The family instance accepts these as optional
-    // metadata for error reporting.
-    return familyInstance.verify({
-      driver,
-      contractIR,
-      expectedTargetId: this.options.target.targetId,
-      contractPath: '',
+    // Emit verify span
+    onProgress?.({
+      action: 'verify',
+      kind: 'spanStart',
+      spanId: 'verify',
+      label: 'Verifying database marker...',
     });
+
+    try {
+      // Delegate to family instance verify method
+      // Note: We pass empty strings for contractPath/configPath since the programmatic
+      // API doesn't deal with file paths. The family instance accepts these as optional
+      // metadata for error reporting.
+      const result = await familyInstance.verify({
+        driver,
+        contract,
+        expectedTargetId: this.options.target.targetId,
+        contractPath: '',
+      });
+
+      onProgress?.({
+        action: 'verify',
+        kind: 'spanEnd',
+        spanId: 'verify',
+        outcome: result.ok ? 'ok' : 'error',
+      });
+
+      return result;
+    } catch (error) {
+      onProgress?.({
+        action: 'verify',
+        kind: 'spanEnd',
+        spanId: 'verify',
+        outcome: 'error',
+      });
+      throw error;
+    }
   }
 
   async schemaVerify(options: SchemaVerifyOptions): Promise<VerifyDatabaseSchemaResult> {
+    const { onProgress } = options;
+    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);
+    }
 
-    // Delegate to family instance schemaVerify method
-    return familyInstance.schemaVerify({
-      driver,
-      contractIR,
-      strict: options.strict ?? false,
-      contractPath: '',
-      frameworkComponents,
+    // Emit schemaVerify span
+    onProgress?.({
+      action: 'schemaVerify',
+      kind: 'spanStart',
+      spanId: 'schemaVerify',
+      label: 'Verifying database schema...',
     });
+
+    try {
+      // Delegate to family instance schemaVerify method
+      const result = await familyInstance.schemaVerify({
+        driver,
+        contract,
+        strict: options.strict ?? false,
+        contractPath: '',
+        frameworkComponents,
+      });
+
+      onProgress?.({
+        action: 'schemaVerify',
+        kind: 'spanEnd',
+        spanId: 'schemaVerify',
+        outcome: result.ok ? 'ok' : 'error',
+      });
+
+      return result;
+    } catch (error) {
+      onProgress?.({
+        action: 'schemaVerify',
+        kind: 'spanEnd',
+        spanId: 'schemaVerify',
+        outcome: 'error',
+      });
+      throw error;
+    }
   }
 
   async sign(options: SignOptions): Promise<SignDatabaseResult> {
+    const { onProgress } = options;
+    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);
+    }
 
-    // Delegate to family instance sign method
-    return familyInstance.sign({
-      driver,
-      contractIR,
-      contractPath: '',
+    // Emit sign span
+    onProgress?.({
+      action: 'sign',
+      kind: 'spanStart',
+      spanId: 'sign',
+      label: 'Signing database...',
     });
+
+    try {
+      // Delegate to family instance sign method
+      const result = await familyInstance.sign({
+        driver,
+        contract,
+        contractPath: options.contractPath ?? '',
+        ...ifDefined('configPath', options.configPath),
+      });
+
+      onProgress?.({
+        action: 'sign',
+        kind: 'spanEnd',
+        spanId: 'sign',
+        outcome: 'ok',
+      });
+
+      return result;
+    } catch (error) {
+      onProgress?.({
+        action: 'sign',
+        kind: 'spanEnd',
+        spanId: 'sign',
+        outcome: 'error',
+      });
+      throw error;
+    }
   }
 
   async dbInit(options: DbInitOptions): Promise<DbInitResult> {
+    const { onProgress } = options;
+    await this.connectWithProgress(options.connection, 'dbInit', 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({
       driver,
       familyInstance,
-      contractIR,
+      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();
+
+    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 executeDbUpdate({
+      driver,
+      familyInstance,
+      contract,
       mode: options.mode,
       migrations: this.options.target.migrations,
       frameworkComponents,
+      ...ifDefined('acceptDataLoss', options.acceptDataLoss),
+      ...ifDefined('onProgress', onProgress),
+    });
+  }
+
+  async readMarker(): Promise<ContractMarkerRecord | null> {
+    const { driver, familyInstance } = await this.ensureConnected();
+    return familyInstance.readMarker({ driver });
+  }
+
+  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
     const _schema = options?.schema;
     void _schema;
 
-    return familyInstance.introspect({ driver });
+    // Emit introspect span
+    onProgress?.({
+      action: 'introspect',
+      kind: 'spanStart',
+      spanId: 'introspect',
+      label: 'Introspecting database schema...',
+    });
+
+    try {
+      const result = await familyInstance.introspect({ driver });
+
+      onProgress?.({
+        action: 'introspect',
+        kind: 'spanEnd',
+        spanId: 'introspect',
+        outcome: 'ok',
+      });
+
+      return result;
+    } catch (error) {
+      onProgress?.({
+        action: 'introspect',
+        kind: 'spanEnd',
+        spanId: 'introspect',
+        outcome: 'error',
+      });
+      throw error;
+    }
+  }
+
+  toSchemaView(schemaIR: unknown): CoreSchemaView | undefined {
+    this.init();
+    if (this.familyInstance && hasSchemaView(this.familyInstance)) {
+      return this.familyInstance.toSchemaView(schemaIR);
+    }
+    return undefined;
+  }
+
+  async emit(options: EmitOptions): Promise<EmitResult> {
+    const { onProgress, contractConfig } = options;
+
+    // Ensure initialized (creates stack and family instance)
+    // emit() does NOT require a database connection
+    this.init();
+
+    if (!this.familyInstance) {
+      throw new Error('Family instance was not initialized. This is a bug.');
+    }
+
+    let contractRaw: unknown;
+    onProgress?.({
+      action: 'emit',
+      kind: 'spanStart',
+      spanId: 'resolveSource',
+      label: 'Resolving contract source...',
+    });
+
+    try {
+      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',
+        kind: 'spanEnd',
+        spanId: 'resolveSource',
+        outcome: 'ok',
+      });
+    } catch (error) {
+      onProgress?.({
+        action: 'emit',
+        kind: 'spanEnd',
+        spanId: 'resolveSource',
+        outcome: 'error',
+      });
+
+      const message = error instanceof Error ? error.message : String(error);
+      return notOk({
+        code: 'CONTRACT_SOURCE_INVALID',
+        summary: 'Failed to resolve contract source',
+        why: message,
+        diagnostics: {
+          summary: 'Contract source provider threw an exception',
+          diagnostics: [
+            {
+              code: 'PROVIDER_THROW',
+              message,
+            },
+          ],
+        },
+        meta: undefined,
+      });
+    }
+
+    // Emit contract
+    onProgress?.({
+      action: 'emit',
+      kind: 'spanStart',
+      spanId: 'emit',
+      label: 'Emitting contract...',
+    });
+
+    try {
+      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',
+        kind: 'spanEnd',
+        spanId: 'emit',
+        outcome: 'ok',
+      });
+
+      return ok({
+        storageHash: result.storageHash,
+        ...ifDefined('executionHash', result.executionHash),
+        profileHash: result.profileHash,
+        contractJson: result.contractJson,
+        contractDts: result.contractDts,
+      });
+    } catch (error) {
+      onProgress?.({
+        action: 'emit',
+        kind: 'spanEnd',
+        spanId: 'emit',
+        outcome: 'error',
+      });
+
+      return notOk({
+        code: 'EMIT_FAILED',
+        summary: 'Failed to emit contract',
+        why: error instanceof Error ? error.message : String(error),
+        meta: undefined,
+      });
+    }
   }
 }

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