@prisma-next/cli 0.3.0-dev.4 → 0.3.0-dev.40

package/src/control-api/client.ts

@@ -0,0 +1,591 @@
+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 {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  ControlPlaneStack,
+  SignDatabaseResult,
+  VerifyDatabaseResult,
+  VerifyDatabaseSchemaResult,
+} from '@prisma-next/core-control-plane/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { notOk, ok } from '@prisma-next/utils/result';
+import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
+import { executeDbInit } from './operations/db-init';
+import type {
+  ControlClient,
+  ControlClientOptions,
+  DbInitOptions,
+  DbInitResult,
+  EmitOptions,
+  EmitResult,
+  IntrospectOptions,
+  SchemaVerifyOptions,
+  SignOptions,
+  VerifyOptions,
+} from './types';
+
+/**
+ * Creates a programmatic control client for Prisma Next operations.
+ *
+ * The client accepts framework component descriptors at creation time,
+ * manages driver lifecycle via connect()/close(), and exposes domain
+ * operations that delegate to the existing family instance methods.
+ *
+ * @see {@link ControlClient} for the client interface
+ * @see README.md "Programmatic Control API" section for usage examples
+ */
+export function createControlClient(options: ControlClientOptions): ControlClient {
+  return new ControlClientImpl(options);
+}
+
+/**
+ * Implementation of ControlClient.
+ * Manages initialization and connection state, delegates operations to family instance.
+ */
+class ControlClientImpl implements ControlClient {
+  private readonly options: ControlClientOptions;
+  private stack: ControlPlaneStack<string, string> | null = null;
+  private driver: ControlDriverInstance<string, string> | null = null;
+  private familyInstance: ControlFamilyInstance<string> | null = null;
+  private frameworkComponents: ReadonlyArray<
+    TargetBoundComponentDescriptor<string, string>
+  > | null = null;
+  private initialized = false;
+  private readonly defaultConnection: unknown;
+
+  constructor(options: ControlClientOptions) {
+    this.options = options;
+    this.defaultConnection = options.connection;
+  }
+
+  init(): void {
+    if (this.initialized) {
+      return; // Idempotent
+    }
+
+    // Create the control plane stack
+    this.stack = createControlPlaneStack({
+      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
+    const rawComponents = [
+      this.options.target,
+      this.options.adapter,
+      ...(this.options.extensionPacks ?? []),
+    ];
+    this.frameworkComponents = assertFrameworkComponentsCompatible(
+      this.options.family.familyId,
+      this.options.target.targetId,
+      rawComponents,
+    );
+
+    this.initialized = true;
+  }
+
+  async connect(connection?: unknown): Promise<void> {
+    // Auto-init if needed
+    this.init();
+
+    if (this.driver) {
+      throw new Error('Already connected. Call close() before reconnecting.');
+    }
+
+    // Resolve connection: argument > default from options
+    const resolvedConnection = connection ?? this.defaultConnection;
+    if (resolvedConnection === undefined) {
+      throw new Error(
+        'No connection provided. Pass a connection to connect() or provide a default connection when creating the client.',
+      );
+    }
+
+    // Check for driver descriptor
+    if (!this.stack?.driver) {
+      throw new Error(
+        'Driver is not configured. Pass a driver descriptor when creating the control client to enable database operations.',
+      );
+    }
+
+    // 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);
+  }
+
+  async close(): Promise<void> {
+    if (this.driver) {
+      await this.driver.close();
+      this.driver = null;
+    }
+  }
+
+  private async ensureConnected(): Promise<{
+    driver: ControlDriverInstance<string, string>;
+    familyInstance: ControlFamilyInstance<string>;
+    frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<string, string>>;
+  }> {
+    // Auto-init if needed
+    this.init();
+
+    // Auto-connect if not connected and default connection is available
+    if (!this.driver && this.defaultConnection !== undefined) {
+      await this.connect(this.defaultConnection);
+    }
+
+    if (!this.driver || !this.familyInstance || !this.frameworkComponents) {
+      throw new Error('Not connected. Call connect(connection) first.');
+    }
+    return {
+      driver: this.driver,
+      familyInstance: this.familyInstance,
+      frameworkComponents: this.frameworkComponents,
+    };
+  }
+
+  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;
+      }
+    }
+
+    const { driver, familyInstance } = await this.ensureConnected();
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // Emit verify span
+    onProgress?.({
+      action: 'verify',
+      kind: 'spanStart',
+      spanId: 'verify',
+      label: 'Verifying contract 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,
+        contractIR,
+        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;
+
+    // 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;
+      }
+    }
+
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // 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,
+        contractIR,
+        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;
+
+    // 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;
+      }
+    }
+
+    const { driver, familyInstance } = await this.ensureConnected();
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // 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,
+        contractIR,
+        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;
+
+    // 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;
+      }
+    }
+
+    const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
+
+    // Check target supports migrations
+    if (!this.options.target.migrations) {
+      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+    }
+
+    // Validate contract using family instance
+    const contractIR = familyInstance.validateContractIR(options.contractIR);
+
+    // Delegate to extracted dbInit operation
+    return executeDbInit({
+      driver,
+      familyInstance,
+      contractIR,
+      mode: options.mode,
+      migrations: this.options.target.migrations,
+      frameworkComponents,
+      ...(onProgress ? { onProgress } : {}),
+    });
+  }
+
+  async introspect(options?: IntrospectOptions): Promise<unknown> {
+    const onProgress = options?.onProgress;
+
+    // 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;
+      }
+    }
+
+    const { driver, familyInstance } = await this.ensureConnected();
+
+    // TODO: Pass schema option to familyInstance.introspect when schema filtering is implemented
+    const _schema = options?.schema;
+    void _schema;
+
+    // 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?.toSchemaView) {
+      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.');
+    }
+
+    // Resolve contract source
+    let contractRaw: unknown;
+    onProgress?.({
+      action: 'emit',
+      kind: 'spanStart',
+      spanId: 'resolveSource',
+      label: 'Resolving contract source...',
+    });
+
+    try {
+      switch (contractConfig.source.kind) {
+        case 'loader':
+          contractRaw = await contractConfig.source.load();
+          break;
+        case 'value':
+          contractRaw = contractConfig.source.value;
+          break;
+      }
+
+      onProgress?.({
+        action: 'emit',
+        kind: 'spanEnd',
+        spanId: 'resolveSource',
+        outcome: 'ok',
+      });
+    } catch (error) {
+      onProgress?.({
+        action: 'emit',
+        kind: 'spanEnd',
+        spanId: 'resolveSource',
+        outcome: 'error',
+      });
+
+      return notOk({
+        code: 'CONTRACT_SOURCE_INVALID',
+        summary: 'Failed to resolve contract source',
+        why: error instanceof Error ? error.message : String(error),
+        meta: undefined,
+      });
+    }
+
+    // Emit contract
+    onProgress?.({
+      action: 'emit',
+      kind: 'spanStart',
+      spanId: 'emit',
+      label: 'Emitting contract...',
+    });
+
+    try {
+      const emitResult = await this.familyInstance.emitContract({ contractIR: contractRaw });
+
+      onProgress?.({
+        action: 'emit',
+        kind: 'spanEnd',
+        spanId: 'emit',
+        outcome: 'ok',
+      });
+
+      return ok({
+        storageHash: emitResult.storageHash,
+        ...ifDefined('executionHash', emitResult.executionHash),
+        profileHash: emitResult.profileHash,
+        contractJson: emitResult.contractJson,
+        contractDts: emitResult.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/operations/contract-emit.ts

@@ -0,0 +1,103 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createControlPlaneStack } from '@prisma-next/core-control-plane/stack';
+import { abortable } from '@prisma-next/utils/abortable';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { dirname, isAbsolute, join, resolve } from 'pathe';
+import { loadConfig } from '../../config-loader';
+import { errorContractConfigMissing } from '../../utils/cli-errors';
+import type { ContractEmitOptions, ContractEmitResult } from '../types';
+
+/**
+ * Executes the contract emit operation.
+ *
+ * This is an offline operation that:
+ * 1. Loads the Prisma Next config from the specified path
+ * 2. Resolves the contract source from config
+ * 3. Creates a control plane stack and family instance
+ * 4. Emits contract artifacts (JSON and DTS)
+ * 5. Writes files to the paths specified in config
+ *
+ * Supports AbortSignal for cancellation, enabling "last change wins" behavior.
+ *
+ * @param options - Options including configPath and optional signal
+ * @returns File paths and hashes of emitted artifacts
+ * @throws If config loading fails, contract is invalid, or file I/O fails
+ * @throws signal.reason if cancelled via AbortSignal (typically DOMException with name 'AbortError')
+ */
+export async function executeContractEmit(
+  options: ContractEmitOptions,
+): Promise<ContractEmitResult> {
+  const { configPath, signal = new AbortController().signal } = options;
+  const unlessAborted = abortable(signal);
+
+  // Load config using the existing config loader
+  const config = await unlessAborted(loadConfig(configPath));
+
+  // Validate contract config is present
+  if (!config.contract) {
+    throw errorContractConfigMissing({
+      why: 'Config.contract is required for emit. Define it in your config: contract: { source: ..., output: ... }',
+    });
+  }
+
+  const contractConfig = config.contract;
+
+  // Validate output path is present and ends with .json
+  if (!contractConfig.output) {
+    throw errorContractConfigMissing({
+      why: 'Contract config must have output path. This should not happen if defineConfig() was used.',
+    });
+  }
+  if (!contractConfig.output.endsWith('.json')) {
+    throw errorContractConfigMissing({
+      why: 'Contract config output path must end with .json (e.g., "src/prisma/contract.json")',
+    });
+  }
+
+  // Validate source is defined and is either a function or a non-null object
+  if (
+    contractConfig.source === null ||
+    (typeof contractConfig.source !== 'function' && typeof contractConfig.source !== 'object')
+  ) {
+    throw errorContractConfigMissing({
+      why: 'Contract config must include a valid source (function or non-null object)',
+    });
+  }
+
+  // Normalize configPath and resolve artifact paths relative to config file directory
+  const normalizedConfigPath = resolve(configPath);
+  const configDir = dirname(normalizedConfigPath);
+  const outputJsonPath = isAbsolute(contractConfig.output)
+    ? contractConfig.output
+    : join(configDir, contractConfig.output);
+  // Colocate .d.ts with .json (contract.json → contract.d.ts)
+  const outputDtsPath = `${outputJsonPath.slice(0, -5)}.d.ts`;
+
+  // Create control plane stack from config
+  const stack = createControlPlaneStack(config);
+  const familyInstance = config.family.create(stack);
+
+  // Resolve contract source from config
+  const contractRaw =
+    typeof contractConfig.source === 'function'
+      ? await unlessAborted(contractConfig.source())
+      : contractConfig.source;
+
+  // Emit contract via family instance
+  const emitResult = await unlessAborted(familyInstance.emitContract({ contractIR: contractRaw }));
+
+  // Create directory if needed and write files (both colocated)
+  await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
+  await unlessAborted(writeFile(outputJsonPath, emitResult.contractJson, 'utf-8'));
+  await unlessAborted(writeFile(outputDtsPath, emitResult.contractDts, 'utf-8'));
+
+  return {
+    storageHash: emitResult.storageHash,
+    ...ifDefined('executionHash', emitResult.executionHash),
+    profileHash: emitResult.profileHash,
+    files: {
+      json: outputJsonPath,
+      dts: outputDtsPath,
+    },
+  };
+}