@prisma-next/cli 0.5.0-dev.9 → 0.5.1

package/src/control-api/types.ts

@@ -12,11 +12,15 @@ 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 { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import type { Result } from '@prisma-next/utils/result';
+import type { ExecuteDbVerifyResult } from './operations/db-verify';
 
 // ============================================================================
 // Client Options
@@ -63,6 +67,7 @@ export interface ControlClientOptions {
 export type ControlActionName =
   | 'dbInit'
   | 'dbUpdate'
+  | 'dbVerify'
   | 'migrationApply'
   | 'verify'
   | 'schemaVerify'
@@ -189,6 +194,13 @@ export interface DbInitOptions {
    * The type is driver-specific (e.g., string URL for Postgres).
    */
   readonly connection?: unknown;
+  /**
+   * On-disk migrations directory. Always required — every `db init`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
@@ -219,10 +231,35 @@ export interface DbUpdateOptions {
    * or re-run with -y/--yes.
    */
   readonly acceptDataLoss?: boolean;
+  /**
+   * On-disk migrations directory. Always required — every `db update`
+   * routes through the per-space flow, which reads on-disk
+   * `refs/head.json` and extension destination contracts from this
+   * root.
+   */
+  readonly migrationsDir: string;
   /** Optional progress callback for observing operation progress */
   readonly onProgress?: OnControlProgress;
 }
 
+/**
+ * Options for the dbVerify operation.
+ *
+ * Drives the loader → aggregate-verifier pipeline. `strict` maps to
+ * `verifyAggregate({ mode: 'strict' | 'lenient' })`; `skipSchema`
+ * mirrors the `--marker-only` CLI flag and short-circuits the schema
+ * portion of the verifier.
+ */
+export interface DbVerifyOptions {
+  readonly contract: unknown;
+  readonly migrationsDir: string;
+  readonly strict: boolean;
+  readonly skipSchema: boolean;
+  readonly skipMarker: boolean;
+  readonly connection?: unknown;
+  readonly onProgress?: OnControlProgress;
+}
+
 /**
  * Options for the introspect operation.
  */
@@ -272,6 +309,42 @@ export interface EmitOptions {
 // Result Types
 // ============================================================================
 
+/**
+ * Per-space breakdown of an aggregate plan / apply.
+ *
+ * Surfaces the canonical schedule shape — extensions alphabetically,
+ * then app — together with the operations attributed to each space and,
+ * when the run was applied, the resulting per-space marker hash.
+ *
+ * Every space involved in a run is observable in the success summary,
+ * including its post-apply marker — the per-space marker is visible
+ * to the user instead of being collapsed into a single ambiguous
+ * top-level hash.
+ */
+export interface AggregatePerSpaceExecutionEntry {
+  readonly spaceId: string;
+  /** `'app'` for the application's contract space; `'extension'` for any extension space. */
+  readonly kind: 'app' | 'extension';
+  /**
+   * Operations attributed to this space (display ops). In `mode: 'plan'`
+   * this is the planned set; in `mode: 'apply'` it is the same set
+   * (every op was executed in order, the runner does not skip).
+   */
+  readonly operations: ReadonlyArray<{
+    readonly id: string;
+    readonly label: string;
+    readonly operationClass: string;
+  }>;
+  /**
+   * Post-apply marker hash for this space. Present only when the run
+   * was applied (i.e. `mode: 'apply'` and the runner returned ok).
+   * Equals the per-space plan's `destination.storageHash`.
+   */
+  readonly marker?: {
+    readonly storageHash: string;
+  };
+}
+
 /**
  * Successful dbInit result.
  */
@@ -283,7 +356,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;
@@ -297,6 +377,14 @@ export interface DbInitSuccess {
     readonly storageHash: string;
     readonly profileHash?: string;
   };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). Present whenever the aggregate flow
+   * produced one — both `mode: 'plan'` and `mode: 'apply'`.
+   *
+   * See {@link AggregatePerSpaceExecutionEntry}.
+   */
+  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
   readonly summary: string;
 }
 
@@ -341,7 +429,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;
@@ -355,6 +450,11 @@ export interface DbUpdateSuccess {
     readonly storageHash: string;
     readonly profileHash?: string;
   };
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   */
+  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
   readonly summary: string;
 }
 
@@ -427,36 +527,46 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
 // ============================================================================
 
 /**
- * A pre-planned migration step ready for execution.
- * Contains the manifest metadata and the serialized operations from ops.json.
- */
-export interface MigrationApplyStep {
-  readonly dirName: string;
-  readonly from: string;
-  readonly to: string;
-  readonly toContract: Contract;
-  readonly operations: readonly MigrationPlanOperation[];
-}
-
-/**
- * Options for the migrationApply operation.
+ * Options for the aggregate-walking `migrationApply` operation.
+ *
+ * The control-api operation is responsible for: loading the
+ * contract-space aggregate, reading per-space marker rows from the
+ * live database, plotting per-space paths via `graphWalkStrategy`
+ * (replay-only — no synth, no introspection), and dispatching
+ * through the shared `applyAggregate` primitive. The CLI command
+ * just resolves the descriptor surface (config, refs, contract
+ * envelope, app-space migration packages) and hands the inputs in.
  */
 export interface MigrationApplyOptions {
+  /** Already-validated app contract (the canonical "where we are heading" hash). */
+  readonly contract: unknown;
+  /** Migrations root directory (`migrations/` under the project). */
+  readonly migrationsDir: string;
   /**
-   * Hash of the database state this apply path starts from.
-   * This is resolved by the caller (typically the CLI orchestration layer).
+   * Already-loaded app-space migration packages. The CLI loads these
+   * via `loadMigrationPackages(appMigrationsDir)` before invoking
+   * `migrationApply`.
    */
-  readonly originHash: string;
+  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
   /**
-   * Hash of the target contract this apply path must reach.
-   * This is resolved by the caller (typically the CLI orchestration layer).
+   * Optional app-space ref override. When provided, the app member's
+   * graph-walk targets this hash instead of `contract.storage.storageHash`.
+   * Extension members always walk to their own `headRef.hash`.
    */
-  readonly destinationHash: string;
+  readonly refHash?: string;
   /**
-   * Ordered list of migrations to execute from originHash to destinationHash.
-   * The execution layer does not choose defaults; it only executes this explicit path.
+   * Required invariants on the user-supplied app-space ref. Threaded
+   * into the graph-walk's `required` calculation so the planner picks
+   * an invariant-bearing path. Ignored when `refHash` is absent.
    */
-  readonly pendingMigrations: readonly MigrationApplyStep[];
+  readonly refInvariants?: readonly string[];
+  /**
+   * Resolved name of the user-supplied app-space ref (the literal the
+   * user passed to `--ref`). Decorates `pathDecision.refName` and any
+   * `MIGRATION.NO_INVARIANT_PATH` envelope raised during graph-walk.
+   * Ignored when `refHash` is absent.
+   */
+  readonly refName?: string;
   /**
    * Database connection. If provided, migrationApply will connect before executing.
    * If omitted, the client must already be connected.
@@ -467,23 +577,102 @@ export interface MigrationApplyOptions {
 }
 
 /**
- * Record of a successfully applied migration.
+ * A single on-disk migration package surfaced to the operation. The
+ * SQL family already produces this shape via `loadMigrationPackages`;
+ * the operation hands it through to the framework-neutral aggregate
+ * loader's `appMigrationPackages` slot.
+ *
+ * (Originally named `MigrationApplyStep` for the legacy single-space
+ * apply path; the name is kept for compatibility with existing CLI
+ * callers and tests.)
+ */
+export interface MigrationApplyStep {
+  readonly dirName: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly toContract: Contract;
+  readonly operations: readonly MigrationPlanOperation[];
+  /**
+   * Sorted, deduplicated invariant ids from `migration.json.providedInvariants`.
+   * Verified at load time by `readMigrationPackage` (manifest copy must equal
+   * the value derived from `ops.json`).
+   */
+  readonly providedInvariants: readonly string[];
+}
+
+/**
+ * Record of a successfully applied per-space migration. One entry per
+ * contract space that had pending migrations — empty `applied` means
+ * every space was already at its head.
+ */
+/**
+ * One entry per authored migration package applied. Preserves the
+ * single-space `migrationsApplied` count semantics (each entry is
+ * one migration directory) so `applied.length === migrationsApplied`.
+ *
+ * Per-space aggregate detail (markers, ops grouped by space) lives
+ * on `perSpace[]`; this list is the per-edge view.
  */
 export interface MigrationApplyAppliedEntry {
+  readonly spaceId: string;
   readonly dirName: string;
+  readonly migrationHash: string;
   readonly from: string;
   readonly to: string;
   readonly operationsExecuted: number;
 }
 
 /**
- * Successful migrationApply result.
+ * Successful migrationApply result. Carries both the legacy
+ * single-space fields (`markerHash` is the **app member's** post-apply
+ * marker, surfaced for back-compat with single-space callers) and the
+ * per-space breakdown (`perSpace` — markers / operations in canonical
+ * schedule order).
  */
+/**
+ * Path-decision summary for the **app member** post-apply. Surfaced
+ * for back-compat with single-space callers (and the cli-journeys
+ * suite, which inspects `requiredInvariants`/`satisfiedInvariants`/
+ * `selectedPath` to validate invariant routing).
+ *
+ * Per-space path decisions for extension members are not surfaced —
+ * extensions own their own ref/invariant control.
+ */
+export interface MigrationApplyPathDecision {
+  readonly fromHash: string;
+  readonly toHash: string;
+  readonly alternativeCount: number;
+  readonly tieBreakReasons: readonly string[];
+  readonly refName?: string;
+  readonly requiredInvariants: readonly string[];
+  readonly satisfiedInvariants: readonly string[];
+  readonly selectedPath: readonly {
+    readonly dirName: string;
+    readonly migrationHash: string;
+    readonly from: string;
+    readonly to: string;
+    readonly invariants: readonly string[];
+  }[];
+}
+
 export interface MigrationApplySuccess {
   readonly migrationsApplied: number;
   readonly markerHash: string;
   readonly applied: readonly MigrationApplyAppliedEntry[];
   readonly summary: string;
+  /**
+   * Per-space breakdown in canonical schedule order (extensions
+   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   * Always present for the aggregate-walking operation.
+   */
+  readonly perSpace: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  /**
+   * Path-decision data for the app member. Present whenever the
+   * graph-walk strategy ran for the app (i.e. always for the
+   * aggregate-walking apply path). Absent only for the no-op
+   * "Already up to date" early return when the app has no plan.
+   */
+  readonly pathDecision?: MigrationApplyPathDecision;
 }
 
 /**
@@ -512,18 +701,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 +741,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;
 }
 
 // ============================================================================
@@ -634,6 +842,21 @@ export interface ControlClient {
    */
   dbUpdate(options: DbUpdateOptions): Promise<DbUpdateResult>;
 
+  /**
+   * Verifies the database against every contract space (app + extensions).
+   *
+   * Loader → aggregate-verifier pipeline:
+   * - The loader catches layout / drift / disjointness violations.
+   * - The aggregate verifier surfaces marker-vs-on-disk drift and orphan
+   *   markers, and (unless `skipSchema` is true) per-space schema
+   *   verification with pre-projection (closes F23).
+   *
+   * @returns Result pattern: per-space schema results on success;
+   *          structured CLI error on marker / loader failure.
+   * @throws If not connected or infrastructure failure
+   */
+  dbVerify(options: DbVerifyOptions): Promise<ExecuteDbVerifyResult>;
+
   /**
    * Reads the contract marker from the database.
    * Returns null if no marker exists (fresh database).
@@ -642,6 +865,13 @@ export interface ControlClient {
    */
   readMarker(): Promise<ContractMarkerRecord | null>;
 
+  /**
+   * Reads every marker row (one per contract space). Used by the
+   * per-space verifier to detect orphan marker rows and marker-vs-on-disk
+   * drift after a database connection has been established.
+   */
+  readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
+
   /**
    * Applies pre-planned on-disk migrations to the database.
    * Each migration runs in its own transaction with full execution checks.
@@ -672,6 +902,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

@@ -20,10 +20,20 @@ export { createControlClient } from '../control-api/client';
 
 // Contract enrichment (merges framework-derived capabilities and extension pack metadata)
 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';
-
+// Standalone operations (for tooling that doesn't need full client).
+// These drive the aggregate-pipeline `db init` / `db update` / `db verify`
+// flow against a loaded contract-space aggregate.
+export { type ExecuteDbInitOptions, executeDbInit } from '../control-api/operations/db-init';
+export {
+  type ExecuteDbUpdateOptions,
+  executeDbUpdate,
+} from '../control-api/operations/db-update';
+export {
+  type ExecuteDbVerifyOptions,
+  type ExecuteDbVerifyResult,
+  executeDbVerify,
+} from '../control-api/operations/db-verify';
 // CLI-specific types
 export type {
   ContractEmitOptions,
@@ -54,3 +64,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/load-ts-contract.ts

@@ -4,7 +4,7 @@ import { pathToFileURL } from 'node:url';
 import type { Contract } from '@prisma-next/contract/types';
 import type { Plugin } from 'esbuild';
 import { build } from 'esbuild';
-import { join } from 'pathe';
+import { join, resolve as resolvePath } from 'pathe';
 
 export interface LoadTsContractOptions {
   readonly allowlist?: ReadonlyArray<string>;
@@ -78,7 +78,21 @@ function validatePurity(value: unknown): void {
   }
 }
 
-function createImportAllowlistPlugin(allowlist: ReadonlyArray<string>, entryPath: string): Plugin {
+function createImportAllowlistPlugin(
+  allowlist: ReadonlyArray<string>,
+  entryPath: string,
+  collected: Set<string>,
+): Plugin {
+  // Match against several path forms that esbuild may use as the importer:
+  // the absolute resolved entry, the value the caller passed (which may be
+  // relative), and the conventional `<stdin>` placeholder. This is more
+  // forgiving than `===` against a single form, which broke when esbuild
+  // resolved the entry to an absolute path while the caller passed a
+  // relative one (or vice versa).
+  const entryAbs = resolvePath(entryPath);
+  function isFromEntry(importer: string): boolean {
+    return importer === entryAbs || importer === entryPath || importer === '<stdin>';
+  }
   return {
     name: 'import-allowlist',
     setup(build) {
@@ -89,8 +103,8 @@ function createImportAllowlistPlugin(allowlist: ReadonlyArray<string>, entryPath
         if (args.path.startsWith('.') || args.path.startsWith('/')) {
           return undefined;
         }
-        const isFromEntryPoint = args.importer === entryPath || args.importer === '<stdin>';
-        if (isFromEntryPoint && !isAllowedImport(args.path, allowlist)) {
+        if (isFromEntry(args.importer) && !isAllowedImport(args.path, allowlist)) {
+          collected.add(args.path);
           return {
             path: args.path,
             external: true,
@@ -132,6 +146,13 @@ export async function loadContractFromTs(
     `prisma-next-contract-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`,
   );
 
+  // Disallowed imports are collected by the allowlist resolver plugin itself,
+  // which has the `importer` context to distinguish entry-direct imports from
+  // transitive imports made inside allowlisted (`@prisma-next/*`) dependencies.
+  // The metafile is intentionally not re-walked: it would surface internal
+  // `node:*` imports inside framework code as false positives.
+  const disallowedFromEntry = new Set<string>();
+
   try {
     const result = await build({
       entryPoints: [entryPath],
@@ -142,7 +163,7 @@ export async function loadContractFromTs(
       outfile: tempFile,
       write: false,
       metafile: true,
-      plugins: [createImportAllowlistPlugin(allowlist, entryPath)],
+      plugins: [createImportAllowlistPlugin(allowlist, entryPath, disallowedFromEntry)],
       logLevel: 'error',
     });
 
@@ -155,28 +176,9 @@ export async function loadContractFromTs(
       throw new Error('No output files generated from bundling');
     }
 
-    const disallowedImports: string[] = [];
-    if (result.metafile) {
-      const inputs = result.metafile.inputs;
-      for (const [, inputData] of Object.entries(inputs)) {
-        const imports =
-          (inputData as { imports?: Array<{ path: string; external?: boolean }> }).imports || [];
-        for (const imp of imports) {
-          if (
-            imp.external &&
-            !imp.path.startsWith('.') &&
-            !imp.path.startsWith('/') &&
-            !isAllowedImport(imp.path, allowlist)
-          ) {
-            disallowedImports.push(imp.path);
-          }
-        }
-      }
-    }
-
-    if (disallowedImports.length > 0) {
+    if (disallowedFromEntry.size > 0) {
       throw new Error(
-        `Disallowed imports detected. Only imports matching the allowlist are permitted:\n  Allowlist: ${allowlist.join(', ')}\n  Disallowed imports: ${disallowedImports.join(', ')}\n\nOnly @prisma-next/* packages are allowed in contract files.`,
+        `Disallowed imports detected. Only imports matching the allowlist are permitted:\n  Allowlist: ${allowlist.join(', ')}\n  Disallowed imports: ${[...disallowedFromEntry].join(', ')}`,
       );
     }