@prisma-next/cli 0.3.0-dev.17 → 0.3.0-dev.19

package/src/control-api/client.ts

@@ -1,4 +1,5 @@
 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,
@@ -8,6 +9,7 @@ import type {
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/core-control-plane/types';
+import { notOk, ok } from '@prisma-next/utils/result';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import { executeDbInit } from './operations/db-init';
 import type {
@@ -15,6 +17,8 @@ import type {
   ControlClientOptions,
   DbInitOptions,
   DbInitResult,
+  EmitOptions,
+  EmitResult,
   IntrospectOptions,
   SchemaVerifyOptions,
   SignOptions,
@@ -148,51 +152,220 @@ 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;
+      }
+    }
+
     const { driver, familyInstance } = await this.ensureConnected();
 
     // Validate contract using family instance
     const contractIR = familyInstance.validateContractIR(options.contractIR);
 
-    // 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 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);
 
-    // 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,
+        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);
 
-    // 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,
+        contractIR,
+        contractPath: options.contractPath ?? '',
+        ...(options.configPath ? { 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> {
@@ -248,12 +421,169 @@ class ControlClientImpl implements ControlClient {
   }
 
   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;
 
-    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?.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({
+        coreHash: emitResult.coreHash,
+        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/types.ts

@@ -1,3 +1,4 @@
+import type { CoreSchemaView } from '@prisma-next/core-control-plane/schema-view';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
@@ -53,7 +54,13 @@ export interface ControlClientOptions {
 /**
  * Action names for control-api operations that can emit progress events.
  */
-export type ControlActionName = 'dbInit' | 'verify' | 'schemaVerify' | 'sign' | 'introspect';
+export type ControlActionName =
+  | 'dbInit'
+  | 'verify'
+  | 'schemaVerify'
+  | 'sign'
+  | 'introspect'
+  | 'emit';
 
 /**
  * Progress event emitted during control-api operation execution.
@@ -100,6 +107,12 @@ export type OnControlProgress = (event: ControlProgressEvent) => void;
 export interface VerifyOptions {
   /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
   readonly contractIR: unknown;
+  /**
+   * Database connection. If provided, verify will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -116,6 +129,12 @@ export interface SchemaVerifyOptions {
    * Default: false (tolerant mode - allows superset)
    */
   readonly strict?: boolean;
+  /**
+   * Database connection. If provided, schemaVerify will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -126,6 +145,20 @@ export interface SchemaVerifyOptions {
 export interface SignOptions {
   /** Contract IR or unvalidated JSON - validated at runtime via familyInstance.validateContractIR() */
   readonly contractIR: unknown;
+  /**
+   * Path to the contract file (for metadata in the result).
+   */
+  readonly contractPath?: string;
+  /**
+   * Path to the config file (for metadata in the result).
+   */
+  readonly configPath?: string;
+  /**
+   * Database connection. If provided, sign will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -160,6 +193,67 @@ export interface IntrospectOptions {
    * Optional schema name to introspect.
    */
   readonly schema?: string;
+  /**
+   * Database connection. If provided, introspect will connect before executing.
+   * If omitted, the client must already be connected.
+   * The type is driver-specific (e.g., string URL for Postgres).
+   */
+  readonly connection?: unknown;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Contract source as a raw value (any JSON-serializable value).
+ */
+export interface ContractSourceValue {
+  readonly kind: 'value';
+  readonly value: unknown;
+}
+
+/**
+ * Contract source as a lazy loader function.
+ */
+export interface ContractSourceLoader {
+  readonly kind: 'loader';
+  readonly load: () => unknown | Promise<unknown>;
+}
+
+/**
+ * Discriminated union for contract source.
+ * Use `kind` to determine how to resolve the contract.
+ */
+export type EmitContractSource = ContractSourceValue | ContractSourceLoader;
+
+/**
+ * Contract configuration for emit operation.
+ */
+export interface EmitContractConfig {
+  /**
+   * Contract source - either a raw value or a loader function.
+   * Switch on `source.kind` to determine how to resolve.
+   */
+  readonly source: EmitContractSource;
+  /**
+   * Output path for contract.json.
+   * Should be an absolute or relative path.
+   */
+  readonly output: string;
+  /**
+   * Output path for contract.d.ts.
+   * Should be an absolute or relative path.
+   */
+  readonly types: string;
+}
+
+/**
+ * Options for the emit operation.
+ */
+export interface EmitOptions {
+  /**
+   * Contract configuration containing source, output, and types paths.
+   */
+  readonly contractConfig: EmitContractConfig;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -221,6 +315,42 @@ export interface DbInitFailure {
  */
 export type DbInitResult = Result<DbInitSuccess, DbInitFailure>;
 
+/**
+ * Successful emit result.
+ * Contains the hashes and paths of emitted files.
+ */
+export interface EmitSuccess {
+  /** Core hash of the emitted contract */
+  readonly coreHash: string;
+  /** Profile hash of the emitted contract (target-specific) */
+  readonly profileHash: string;
+  /** The emitted contract as JSON string */
+  readonly contractJson: string;
+  /** The emitted contract TypeScript declarations */
+  readonly contractDts: string;
+}
+
+/**
+ * Failure codes for emit operation.
+ */
+export type EmitFailureCode = 'CONTRACT_SOURCE_INVALID' | 'EMIT_FAILED';
+
+/**
+ * Failure details for emit operation.
+ */
+export interface EmitFailure {
+  readonly code: EmitFailureCode;
+  readonly summary: string;
+  readonly why: string | undefined;
+  readonly meta: Record<string, unknown> | undefined;
+}
+
+/**
+ * Result type for emit operation.
+ * Uses Result pattern: success returns EmitSuccess, failure returns EmitFailure.
+ */
+export type EmitResult = Result<EmitSuccess, EmitFailure>;
+
 // ============================================================================
 // Client Interface
 // ============================================================================
@@ -310,4 +440,22 @@ export interface ControlClient {
    * @throws If not connected or infrastructure failure
    */
   introspect(options?: IntrospectOptions): Promise<unknown>;
+
+  /**
+   * Converts a schema IR to a schema view for CLI tree rendering.
+   * Delegates to the family instance's toSchemaView method.
+   *
+   * @param schemaIR - The schema IR from introspect()
+   * @returns CoreSchemaView if the family supports it, undefined otherwise
+   */
+  toSchemaView(schemaIR: unknown): CoreSchemaView | undefined;
+
+  /**
+   * Emits the contract to JSON and TypeScript declarations.
+   * This is an offline operation that does NOT require a database connection.
+   * Uses `init()` to create the stack but does NOT call `connect()`.
+   *
+   * @returns Result pattern: Ok with emit details, NotOk with failure details
+   */
+  emit(options: EmitOptions): Promise<EmitResult>;
 }

package/src/exports/control-api.ts

@@ -20,6 +20,8 @@ export { createControlClient } from '../control-api/client';
 
 // CLI-specific types
 export type {
+  ContractSourceLoader,
+  ContractSourceValue,
   ControlActionName,
   ControlClient,
   ControlClientOptions,
@@ -29,6 +31,13 @@ export type {
   DbInitOptions,
   DbInitResult,
   DbInitSuccess,
+  EmitContractConfig,
+  EmitContractSource,
+  EmitFailure,
+  EmitFailureCode,
+  EmitOptions,
+  EmitResult,
+  EmitSuccess,
   IntrospectOptions,
   OnControlProgress,
   SchemaVerifyOptions,

package/dist/chunk-5MPKZYVI.js

@@ -1,47 +0,0 @@
-import {
-  CliStructuredError
-} from "./chunk-VI2YETW7.js";
-
-// src/utils/action.ts
-import { notOk, ok } from "@prisma-next/utils/result";
-async function performAction(fn) {
-  try {
-    const value = await fn();
-    return ok(value);
-  } catch (error) {
-    if (error instanceof CliStructuredError) {
-      return notOk(error);
-    }
-    throw error;
-  }
-}
-
-// src/utils/spinner.ts
-import ora from "ora";
-async function withSpinner(operation, options) {
-  const { message, flags } = options;
-  const shouldShowSpinner = !flags.quiet && flags.json !== "object" && process.stdout.isTTY;
-  if (!shouldShowSpinner) {
-    return operation();
-  }
-  const startTime = Date.now();
-  const spinner = ora({
-    text: message,
-    color: flags.color !== false ? "cyan" : false
-  }).start();
-  try {
-    const result = await operation();
-    const elapsed = Date.now() - startTime;
-    spinner.succeed(`${message} (${elapsed}ms)`);
-    return result;
-  } catch (error) {
-    spinner.fail(`${message} failed: ${error instanceof Error ? error.message : String(error)}`);
-    throw error;
-  }
-}
-
-export {
-  performAction,
-  withSpinner
-};
-//# sourceMappingURL=chunk-5MPKZYVI.js.map