@prisma-next/cli 0.5.0-dev.3 → 0.5.0-dev.30

package/src/control-api/types.ts

@@ -12,10 +12,12 @@ import type {
   CoreSchemaView,
   MigrationPlannerConflict,
   MigrationPlanOperation,
+  OperationPreview,
   SignDatabaseResult,
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
 import type { Result } from '@prisma-next/utils/result';
 
 // ============================================================================
@@ -283,7 +285,14 @@ export interface DbInitSuccess {
       readonly label: string;
       readonly operationClass: string;
     }>;
-    readonly sql?: ReadonlyArray<string>;
+    /**
+     * Family-agnostic textual preview of the planned operations, e.g.
+     * `language: 'sql'` for SQL families and `language: 'mongodb-shell'`
+     * for the Mongo family. Replaces the previous `sql?: readonly string[]`
+     * field; consumers that previously read `plan.sql` should read
+     * `plan.preview?.statements.map((s) => s.text)`.
+     */
+    readonly preview?: OperationPreview;
   };
   readonly destination: {
     readonly storageHash: string;
@@ -341,7 +350,14 @@ export interface DbUpdateSuccess {
       readonly label: string;
       readonly operationClass: string;
     }>;
-    readonly sql?: ReadonlyArray<string>;
+    /**
+     * Family-agnostic textual preview of the planned operations, e.g.
+     * `language: 'sql'` for SQL families and `language: 'mongodb-shell'`
+     * for the Mongo family. Replaces the previous `sql?: readonly string[]`
+     * field; consumers that previously read `plan.sql` should read
+     * `plan.preview?.statements.map((s) => s.text)`.
+     */
+    readonly preview?: OperationPreview;
   };
   readonly destination: {
     readonly storageHash: string;
@@ -432,7 +448,7 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
  */
 export interface MigrationApplyStep {
   readonly dirName: string;
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
   readonly toContract: Contract;
   readonly operations: readonly MigrationPlanOperation[];
@@ -471,7 +487,7 @@ export interface MigrationApplyOptions {
  */
 export interface MigrationApplyAppliedEntry {
   readonly dirName: string;
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
   readonly operationsExecuted: number;
 }
@@ -512,18 +528,31 @@ export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyF
 
 /**
  * Options for the standalone executeContractEmit function.
- * Used by tooling (e.g., Vite plugin) that needs to emit contracts
- * without the full ControlClient infrastructure.
+ *
+ * `executeContractEmit` is the canonical publication path for both the
+ * `prisma-next contract emit` CLI command and the `@prisma-next/vite-plugin-contract-emit`
+ * Vite plugin. Do not duplicate the load → emit → publish dance elsewhere; if a
+ * caller needs additional behavior, extend this options shape and update the
+ * single implementation rather than building a parallel publication path.
+ *
+ * Concurrent calls for the same output JSON path are serialized per-output via
+ * a FIFO queue; concurrent calls for distinct outputs run in parallel.
  */
 export interface ContractEmitOptions {
   /** Path to the prisma-next.config.ts file */
   readonly configPath: string;
-  /** Optional AbortSignal for cancellation support */
+  /** Optional AbortSignal for cancelling the in-flight emit */
   readonly signal?: AbortSignal;
+  /** Optional progress callback for observing source-resolution and emit spans */
+  readonly onProgress?: OnControlProgress;
 }
 
 /**
  * Result from the standalone executeContractEmit function.
+ *
+ * Always describes the bytes that were just published to disk. Failures throw
+ * (config / source-resolution / emit / publish) — callers do not need to
+ * branch on a result discriminator.
  */
 export interface ContractEmitResult {
   /** Hash of the storage contract (schema-level) */
@@ -539,6 +568,12 @@ export interface ContractEmitResult {
     /** Path to the emitted contract.d.ts file */
     readonly dts: string;
   };
+  /**
+   * Warning surfaced by `validateContractDeps` after a successful publication.
+   * Callers (CLI, Vite plugin) decide how to render this; the operation does
+   * not write to stderr itself. Undefined when no warning was raised.
+   */
+  readonly validationWarning?: string;
 }
 
 // ============================================================================
@@ -672,6 +707,25 @@ export interface ControlClient {
    */
   toSchemaView(schemaIR: unknown): CoreSchemaView | undefined;
 
+  /**
+   * Infers a PSL contract AST from an introspected schema IR.
+   * Delegates to the family instance's inferPslContract method.
+   *
+   * @param schemaIR - The schema IR from introspect()
+   * @returns PslDocumentAst if the family supports the capability, undefined otherwise
+   */
+  inferPslContract(schemaIR: unknown): PslDocumentAst | undefined;
+
+  /**
+   * Renders a textual preview of a migration plan's operations for the CLI's
+   * "DDL preview" output. Delegates to the family instance's
+   * `toOperationPreview` method.
+   *
+   * @param operations - The migration plan operations to render
+   * @returns OperationPreview if the family supports the capability, undefined otherwise
+   */
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview | undefined;
+
   /**
    * Emits the contract to JSON and TypeScript declarations.
    * This is an offline operation that does NOT require a database connection.

package/src/exports/control-api.ts

@@ -23,7 +23,6 @@ export { enrichContract } from '../control-api/contract-enrichment';
 
 // Standalone operations (for tooling that doesn't need full client)
 export { executeContractEmit } from '../control-api/operations/contract-emit';
-
 // CLI-specific types
 export type {
   ContractEmitOptions,
@@ -54,3 +53,5 @@ export type {
   SignOptions,
   VerifyOptions,
 } from '../control-api/types';
+// Lifecycle helpers for hosts that publish to many output paths
+export { disposeEmitQueue } from '../utils/emit-queue';

package/src/exports/init-output.ts

@@ -0,0 +1,10 @@
+/**
+ * Public re-export of the `init --json` success-document schema (FR1.5).
+ *
+ * Imported as `@prisma-next/cli/init-output`. The shared error envelope is
+ * exported separately from `@prisma-next/errors`; consumers should branch
+ * on the `ok` discriminator (success documents carry `ok: true`, error
+ * envelopes carry `ok: false`) per the
+ * [Style Guide § JSON Semantics](../../../../../../../docs/CLI%20Style%20Guide.md#json-semantics).
+ */
+export { type InitOutput, InitOutputSchema } from '../commands/init/output';