@prisma-next/cli 0.5.0-dev.4 → 0.5.0-dev.41

package/src/utils/cli-errors.ts

@@ -1,9 +1,11 @@
 /**
  * Re-export all domain error factories from @prisma-next/errors for convenience.
- * CLI-specific errors (e.g., Commander.js argument validation) can be added here if needed.
+ * CLI-specific errors (e.g., Commander argument validation in the main CLI, or
+ * clipanion parse errors in the migration-file CLI) can be added here if needed.
  */
 export type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';
-export {
+
+import {
   CliStructuredError,
   errorConfigFileNotFound,
   errorConfigValidation,
@@ -15,11 +17,33 @@ export {
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
   errorMigrationCliInvalidConfigArg,
+  errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
   errorUnexpected,
 } from '@prisma-next/errors/control';
+import { errorRuntime } from '@prisma-next/errors/execution';
+import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+
+export {
+  CliStructuredError,
+  errorConfigFileNotFound,
+  errorConfigValidation,
+  errorContractConfigMissing,
+  errorContractMissingExtensionPacks,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFamilyReadMarkerSqlRequired,
+  errorFileNotFound,
+  errorMigrationCliInvalidConfigArg,
+  errorMigrationCliUnknownFlag,
+  errorMigrationPlanningFailed,
+  errorQueryRunnerFactoryRequired,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+};
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
   errorDestructiveChanges,
@@ -38,3 +62,26 @@ export {
   errorUnfilledPlaceholder,
   placeholder,
 } from '@prisma-next/errors/migration';
+
+/**
+ * Maps a `MigrationToolsError` raised by the migration-tools loader/graph
+ * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,
+ * `resolveRef`, `reconstructGraph`, ...) into a CLI `errorRuntime` envelope.
+ *
+ * The full `error.details` payload is forwarded into `meta` so machine
+ * consumers (`--json`) see structural fields like `dir`, `storedHash`,
+ * `computedHash` (for `MIGRATION.HASH_MISMATCH`) alongside the stable
+ * `code`. The user-visible `summary`/`why`/`fix` text is unchanged.
+ *
+ * Callers are expected to gate on `MigrationToolsError.is(error)` first
+ * (mirroring the original inline pattern); non-`MigrationToolsError`
+ * values are caller-classified (rethrow, wrap with command-specific
+ * `errorUnexpected`, etc.).
+ */
+export function mapMigrationToolsError(error: MigrationToolsError): CliStructuredError {
+  return errorRuntime(error.message, {
+    why: error.why,
+    fix: error.fix,
+    meta: { code: error.code, ...(error.details ?? {}) },
+  });
+}

package/src/utils/command-helpers.ts

@@ -1,10 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import type { ControlTargetDescriptor } from '@prisma-next/framework-components/control';
 import { hasMigrations } from '@prisma-next/framework-components/control';
-import type { PathDecision } from '@prisma-next/migration-tools/dag';
-import { reconstructGraph } from '@prisma-next/migration-tools/dag';
+import type { NoInvariantPathStructuralEdge } from '@prisma-next/migration-tools/errors';
+import type { MigrationEdge, MigrationGraph } from '@prisma-next/migration-tools/graph';
 import { readMigrationsDir } from '@prisma-next/migration-tools/io';
-import type { MigrationBundle, MigrationGraph } from '@prisma-next/migration-tools/types';
+import type { PathDecision } from '@prisma-next/migration-tools/migration-graph';
+import { reconstructGraph } from '@prisma-next/migration-tools/migration-graph';
+import type { MigrationPackage } from '@prisma-next/migration-tools/package';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
 import { relative, resolve } from 'pathe';
@@ -109,14 +111,45 @@ export interface PathDecisionResult {
   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 migrationId: string;
+    readonly migrationHash: string;
     readonly from: string;
     readonly to: string;
+    readonly invariants: readonly string[];
   }[];
 }
 
+export function collectDeclaredInvariants(graph: MigrationGraph): ReadonlySet<string> {
+  const declared = new Set<string>();
+  for (const edges of graph.forwardChain.values()) {
+    for (const edge of edges) {
+      for (const inv of edge.invariants) {
+        declared.add(inv);
+      }
+    }
+  }
+  return declared;
+}
+
+/**
+ * Maps a `MigrationEdge` to the structural-edge shape used in the
+ * `MIGRATION.NO_INVARIANT_PATH` error envelope. Shared between
+ * `migration apply` and `migration status` so both commands surface
+ * the same JSON wire shape when an invariant-aware route is unsatisfiable.
+ */
+export function toStructuralEdge(edge: MigrationEdge): NoInvariantPathStructuralEdge {
+  return {
+    dirName: edge.dirName,
+    migrationHash: edge.migrationHash,
+    from: edge.from,
+    to: edge.to,
+    invariants: edge.invariants,
+  };
+}
+
 /**
  * Maps a PathDecision to the slim CLI output representation.
  */
@@ -126,12 +159,15 @@ export function toPathDecisionResult(decision: PathDecision): PathDecisionResult
     toHash: decision.toHash,
     alternativeCount: decision.alternativeCount,
     tieBreakReasons: decision.tieBreakReasons,
+    requiredInvariants: decision.requiredInvariants ?? [],
+    satisfiedInvariants: decision.satisfiedInvariants ?? [],
     ...ifDefined('refName', decision.refName),
     selectedPath: decision.selectedPath.map((entry) => ({
       dirName: entry.dirName,
-      migrationId: entry.migrationId,
+      migrationHash: entry.migrationHash,
       from: entry.from,
       to: entry.to,
+      invariants: entry.invariants,
     })),
   };
 }
@@ -146,13 +182,13 @@ export function getTargetMigrations(target: ControlTargetDescriptor<string, stri
 
 /**
  * Reads the migrations directory and builds the migration graph from all
- * bundles. Throws on I/O or graph errors — callers handle error mapping.
+ * packages. Throws on I/O or graph errors — callers handle error mapping.
  *
- * Every on-disk bundle is content-addressed (`migrationId` is always a
+ * Every on-disk package is content-addressed (`migrationHash` is always a
  * string); there is no draft state to filter out.
  */
-export async function loadMigrationBundles(migrationsDir: string): Promise<{
-  bundles: readonly MigrationBundle[];
+export async function loadMigrationPackages(migrationsDir: string): Promise<{
+  bundles: readonly MigrationPackage[];
   graph: MigrationGraph;
 }> {
   const bundles = await readMigrationsDir(migrationsDir);
@@ -160,20 +196,6 @@ export async function loadMigrationBundles(migrationsDir: string): Promise<{
   return { bundles, graph };
 }
 
-export interface MigrationBundleSet {
-  readonly bundles: readonly MigrationBundle[];
-  readonly graph: MigrationGraph;
-}
-
-/**
- * Alias of `loadMigrationBundles` retained for naming-clarity in commands
- * that previously needed both attested and draft splits. With the
- * collapse of the draft state, both helpers do the same thing.
- */
-export async function loadAllBundles(migrationsDir: string): Promise<MigrationBundleSet> {
-  return loadMigrationBundles(migrationsDir);
-}
-
 /**
  * The subset of the emitted contract.json that the framework layer can
  * safely type. The emitter adds these fields on top of the family-specific

package/src/utils/emit-queue.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-output FIFO queue for `executeContractEmit`.
+ *
+ * Ensures that at most one emit (load → resolve source → emit bytes → publish)
+ * runs per output JSON path at a time. Concurrent calls for the same path
+ * line up behind the in-flight one and run in submission order; the user-visible
+ * outcome is "last submission wins on disk" without any supersession bookkeeping.
+ *
+ * Long-lived hosts (Vite dev server, watch CLIs) must call `disposeEmitQueue`
+ * when they stop publishing to a path, otherwise the module-global `Map`
+ * accumulates one entry per unique output path for the lifetime of the process.
+ */
+const emitQueues = new Map<string, Promise<unknown>>();
+
+export function queueEmitByOutput<T>(outputJsonPath: string, action: () => Promise<T>): Promise<T> {
+  const previous = emitQueues.get(outputJsonPath) ?? Promise.resolve();
+  // Continue regardless of the previous task's outcome — a failed emit must not
+  // block subsequent ones. The current task's outcome propagates via `next`.
+  const next = previous.then(action, action);
+  emitQueues.set(outputJsonPath, next);
+  return next;
+}
+
+export function disposeEmitQueue(outputJsonPath: string): void {
+  emitQueues.delete(outputJsonPath);
+}

package/src/utils/formatters/graph-migration-mapper.ts

@@ -2,8 +2,8 @@
  * Maps MigrationGraph + status info to the generic graph renderer types.
  */
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { findPath } from '@prisma-next/migration-tools/dag';
-import type { MigrationGraph } from '@prisma-next/migration-tools/types';
+import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
+import { findPath } from '@prisma-next/migration-tools/migration-graph';
 import { ifDefined } from '@prisma-next/utils/defined';
 
 import type { StatusRef } from '../migration-types';
@@ -106,7 +106,11 @@ export function migrationGraphToRenderInput(input: MigrationGraphInput): Migrati
     for (const entry of entries) {
       const status = statusByDirName.get(entry.dirName);
       const icon = status ? STATUS_ICON[status] : '';
-      const label = `${entry.dirName}${icon}`;
+      const invariantsSuffix =
+        entry.invariants.length > 0
+          ? `  provides [${entry.invariants.map((id) => JSON.stringify(id)).join(', ')}]`
+          : '';
+      const label = `${entry.dirName}${icon}${invariantsSuffix}`;
 
       edgeList.push({
         from: toShortId(entry.from),

package/src/utils/formatters/migrations.ts

@@ -1,8 +1,41 @@
+import type { OperationPreview } from '@prisma-next/framework-components/control';
 import { green, yellow } from 'colorette';
 
 import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
 
+/**
+ * Render a single statement of an `OperationPreview` for the human-readable
+ * preview block. SQL statements get a trailing `;` if missing — matches the
+ * legacy `string[]`-based renderer byte-for-byte (per spec OQ-4). Other
+ * languages (`'mongodb-shell'`) render verbatim.
+ */
+function renderPreviewStatement(text: string, language: string): string | undefined {
+  const trimmed = text.trim();
+  if (!trimmed) return undefined;
+  if (language === 'sql') {
+    return trimmed.endsWith(';') ? trimmed : `${trimmed};`;
+  }
+  return trimmed;
+}
+
+/**
+ * Choose the header label for a preview block. SQL-only previews keep the
+ * legacy `DDL preview` label (preserves CLI byte-identity for SQL targets per
+ * spec OQ-4); previews from any other family — or a mix that includes any
+ * non-SQL language — use the family-agnostic `Operation preview` label.
+ *
+ * An empty `statements` array deliberately renders as `Operation preview`
+ * rather than `DDL preview`: `Array.prototype.every` is vacuously true for
+ * empty arrays, but we have no evidence the preview is SQL-only when no
+ * statements are present, so the family-agnostic label is the safer default.
+ */
+export function previewBlockHeader(preview: OperationPreview): string {
+  const allSql =
+    preview.statements.length > 0 && preview.statements.every((s) => s.language === 'sql');
+  return allSql ? 'DDL preview' : 'Operation preview';
+}
+
 // ============================================================================
 // Migration Command Output Formatters (shared by db init and db update)
 // ============================================================================
@@ -24,7 +57,12 @@ export interface MigrationCommandResult {
       readonly label: string;
       readonly operationClass: string;
     }[];
-    readonly sql?: readonly string[];
+    /**
+     * Family-agnostic textual preview of the planned operations. Replaces the
+     * previous `sql?: readonly string[]`. Consumers should read
+     * `plan.preview?.statements`.
+     */
+    readonly preview?: OperationPreview;
   };
   readonly execution?: {
     readonly operationsPlanned: number;
@@ -92,20 +130,20 @@ export function formatMigrationPlanOutput(
     lines.push(`${formatDimText(`Destination hash: ${result.plan.destination.storageHash}`)}`);
   }
 
-  // SQL DDL preview (SQL family only)
-  const planSql = result.plan?.sql;
-  if (planSql) {
+  // Statement preview (any family that implements OperationPreviewCapable)
+  const preview = result.plan?.preview;
+  if (preview) {
     lines.push('');
-    lines.push(`${formatDimText('DDL preview')}`);
-    if (planSql.length === 0) {
-      lines.push(`${formatDimText('No DDL operations.')}`);
+    lines.push(`${formatDimText(previewBlockHeader(preview))}`);
+    if (preview.statements.length === 0) {
+      lines.push(`${formatDimText('No operations.')}`);
     } else {
       lines.push('');
-      for (const statement of planSql) {
-        const trimmed = statement.trim();
-        if (!trimmed) continue;
-        const line = trimmed.endsWith(';') ? trimmed : `${trimmed};`;
-        lines.push(`${line}`);
+      for (const statement of preview.statements) {
+        const rendered = renderPreviewStatement(statement.text, statement.language);
+        if (rendered) {
+          lines.push(rendered);
+        }
       }
     }
   }
@@ -181,17 +219,16 @@ export function formatMigrationApplyCommandOutput(
 interface MigrationShowResult {
   readonly dirName: string;
   readonly dirPath: string;
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
-  readonly migrationId: string;
-  readonly kind: string;
+  readonly migrationHash: string;
   readonly createdAt: string;
   readonly operations: readonly {
     readonly id: string;
     readonly label: string;
     readonly operationClass: string;
   }[];
-  readonly sql: readonly string[];
+  readonly preview: OperationPreview;
   readonly summary: string;
 }
 
@@ -208,10 +245,9 @@ export function formatMigrationShowOutput(result: MigrationShowResult, flags: Gl
   const formatDimText = (text: string) => formatDim(useColor, text);
 
   lines.push(`${formatGreen('✔')} ${result.dirName}`);
-  lines.push(`${formatDimText(`  kind: ${result.kind}`)}`);
-  lines.push(`${formatDimText(`  from: ${result.from}`)}`);
+  lines.push(`${formatDimText(`  from: ${result.from ?? '(baseline)'}`)}`);
   lines.push(`${formatDimText(`  to:   ${result.to}`)}`);
-  lines.push(`${formatDimText(`  migrationId: ${result.migrationId}`)}`);
+  lines.push(`${formatDimText(`  migrationHash: ${result.migrationHash}`)}`);
   lines.push(`${formatDimText(`  created: ${result.createdAt}`)}`);
 
   lines.push('');
@@ -239,15 +275,15 @@ export function formatMigrationShowOutput(result: MigrationShowResult, flags: Gl
     }
   }
 
-  if (result.sql.length > 0) {
+  if (result.preview.statements.length > 0) {
     lines.push('');
-    lines.push(`${formatDimText('DDL preview')}`);
+    lines.push(`${formatDimText(previewBlockHeader(result.preview))}`);
     lines.push('');
-    for (const statement of result.sql) {
-      const trimmed = statement.trim();
-      if (!trimmed) continue;
-      const line = trimmed.endsWith(';') ? trimmed : `${trimmed};`;
-      lines.push(`${line}`);
+    for (const statement of result.preview.statements) {
+      const rendered = renderPreviewStatement(statement.text, statement.language);
+      if (rendered) {
+        lines.push(rendered);
+      }
     }
   }
 

package/src/utils/publish-contract-artifact-pair.ts

@@ -0,0 +1,134 @@
+import { readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'pathe';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function createTempArtifactPath(path: string, publicationToken: string, phase: string): string {
+  return join(dirname(path), `.${basename(path)}.${process.pid}.${publicationToken}.${phase}.tmp`);
+}
+
+type PreviousArtifact = { readonly content: string } | 'remove';
+
+async function readExistingArtifact(path: string): Promise<PreviousArtifact> {
+  try {
+    return { content: await readFile(path, 'utf-8') };
+  } catch (error) {
+    if (isRecord(error) && error['code'] === 'ENOENT') {
+      return 'remove';
+    }
+    throw error;
+  }
+}
+
+async function restoreArtifact(
+  path: string,
+  previous: PreviousArtifact,
+  publicationToken: string,
+): Promise<void> {
+  if (previous === 'remove') {
+    await rm(path, { force: true });
+    return;
+  }
+
+  const restorePath = createTempArtifactPath(path, publicationToken, 'rollback');
+  await writeFile(restorePath, previous.content, 'utf-8');
+  try {
+    await rename(restorePath, path);
+  } finally {
+    await rm(restorePath, { force: true });
+  }
+}
+
+interface PublishEntry {
+  readonly tempPath: string;
+  readonly outputPath: string;
+  readonly previous: PreviousArtifact;
+}
+
+function withRollbackFailureCause(error: unknown, rollbackFailures: readonly unknown[]): Error {
+  const rollbackCause = new AggregateError(
+    rollbackFailures,
+    'Failed to restore published artifacts',
+  );
+
+  if (error instanceof Error) {
+    Object.defineProperty(error, 'cause', {
+      value: rollbackCause,
+      configurable: true,
+      writable: true,
+    });
+    return error;
+  }
+
+  return new Error(String(error), { cause: rollbackCause });
+}
+
+async function publishPairWithRollback(
+  entries: readonly PublishEntry[],
+  publicationToken: string,
+): Promise<void> {
+  const replaced: PublishEntry[] = [];
+  try {
+    for (const entry of entries) {
+      await rename(entry.tempPath, entry.outputPath);
+      replaced.push(entry);
+    }
+  } catch (error) {
+    const rollbackResults = await Promise.allSettled(
+      replaced.map((entry) => restoreArtifact(entry.outputPath, entry.previous, publicationToken)),
+    );
+    const rollbackFailures = rollbackResults.flatMap((result) =>
+      result.status === 'rejected' ? [result.reason] : [],
+    );
+
+    if (rollbackFailures.length > 0) {
+      throw withRollbackFailureCause(error, rollbackFailures);
+    }
+
+    throw error;
+  }
+}
+
+export async function publishContractArtifactPair({
+  outputJsonPath,
+  outputDtsPath,
+  contractJson,
+  contractDts,
+  publicationToken,
+  beforePublish,
+}: {
+  readonly outputJsonPath: string;
+  readonly outputDtsPath: string;
+  readonly contractJson: string;
+  readonly contractDts: string;
+  readonly publicationToken: string;
+  readonly beforePublish?: () => Promise<boolean> | boolean;
+}): Promise<boolean> {
+  const tempJsonPath = createTempArtifactPath(outputJsonPath, publicationToken, 'next');
+  const tempDtsPath = createTempArtifactPath(outputDtsPath, publicationToken, 'next');
+
+  try {
+    await writeFile(tempJsonPath, contractJson, 'utf-8');
+    await writeFile(tempDtsPath, contractDts, 'utf-8');
+
+    if ((await beforePublish?.()) === false) {
+      return false;
+    }
+
+    const previousJson = await readExistingArtifact(outputJsonPath);
+    const previousDts = await readExistingArtifact(outputDtsPath);
+
+    await publishPairWithRollback(
+      [
+        { tempPath: tempDtsPath, outputPath: outputDtsPath, previous: previousDts },
+        { tempPath: tempJsonPath, outputPath: outputJsonPath, previous: previousJson },
+      ],
+      publicationToken,
+    );
+    return true;
+  } finally {
+    await Promise.allSettled([rm(tempJsonPath, { force: true }), rm(tempDtsPath, { force: true })]);
+  }
+}

package/dist/cli-errors-DHq6GQGu.mjs

@@ -1,5 +0,0 @@
-import { CliStructuredError as CliStructuredError$1, errorConfigValidation as errorConfigValidation$1, errorContractConfigMissing as errorContractConfigMissing$1, errorContractValidationFailed, errorDatabaseConnectionRequired, errorDriverRequired, errorFileNotFound, errorMigrationPlanningFailed, errorTargetMigrationNotSupported, errorUnexpected as errorUnexpected$1 } from "@prisma-next/errors/control";
-import { ERROR_CODE_DESTRUCTIVE_CHANGES, errorDestructiveChanges, errorHashMismatch, errorMarkerMissing, errorRunnerFailed, errorRuntime as errorRuntime$1, errorTargetMismatch } from "@prisma-next/errors/execution";
-import "@prisma-next/errors/migration";
-
-export { errorUnexpected$1 as _, errorContractValidationFailed as a, errorDriverRequired as c, errorMarkerMissing as d, errorMigrationPlanningFailed as f, errorTargetMismatch as g, errorTargetMigrationNotSupported as h, errorContractConfigMissing$1 as i, errorFileNotFound as l, errorRuntime$1 as m, ERROR_CODE_DESTRUCTIVE_CHANGES as n, errorDatabaseConnectionRequired as o, errorRunnerFailed as p, errorConfigValidation$1 as r, errorDestructiveChanges as s, CliStructuredError$1 as t, errorHashMismatch as u };