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

package/src/control-api/operations/contract-emit.ts

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { emit, getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { createControlStack } from '@prisma-next/framework-components/control';
@@ -7,57 +7,156 @@ import { ifDefined } from '@prisma-next/utils/defined';
 import { dirname } from 'pathe';
 import { loadConfig } from '../../config-loader';
 import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
+import { queueEmitByOutput } from '../../utils/emit-queue';
 import { assertFrameworkComponentsCompatible } from '../../utils/framework-components';
+import { publishContractArtifactPair } from '../../utils/publish-contract-artifact-pair';
+import { validateContractDeps } from '../../utils/validate-contract-deps';
 import { enrichContract } from '../contract-enrichment';
-import type { ContractEmitOptions, ContractEmitResult } from '../types';
+import type {
+  ContractEmitOptions,
+  ContractEmitResult,
+  ControlActionName,
+  OnControlProgress,
+} from '../types';
 
-interface ProviderFailureLike {
-  readonly summary: string;
-  readonly diagnostics: readonly unknown[];
-  readonly meta?: unknown;
-}
+const EMIT_ACTION: ControlActionName = 'emit';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function isAbortError(error: unknown): boolean {
-  return isRecord(error) && typeof error['name'] === 'string' && error['name'] === 'AbortError';
+function startSpan(onProgress: OnControlProgress | undefined, spanId: string, label: string): void {
+  onProgress?.({ action: EMIT_ACTION, kind: 'spanStart', spanId, label });
+}
+
+function endSpan(
+  onProgress: OnControlProgress | undefined,
+  spanId: string,
+  outcome: 'ok' | 'error',
+): void {
+  onProgress?.({ action: EMIT_ACTION, kind: 'spanEnd', spanId, outcome });
+}
+
+function failedToResolveContractSource(why: string, fix: string, meta?: Record<string, unknown>) {
+  return errorRuntime('Failed to resolve contract source', {
+    why,
+    fix,
+    ...ifDefined('meta', meta),
+  });
+}
+
+type ValidatedProviderResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: ReturnType<typeof errorRuntime> };
+
+function diagnosticLocationSuffix(diagnostic: Record<string, unknown>): string {
+  const sourceId = typeof diagnostic['sourceId'] === 'string' ? diagnostic['sourceId'] : undefined;
+  const span = isRecord(diagnostic['span']) ? diagnostic['span'] : undefined;
+  const start = span && isRecord(span['start']) ? span['start'] : undefined;
+  const line = start && typeof start['line'] === 'number' ? start['line'] : undefined;
+  const column = start && typeof start['column'] === 'number' ? start['column'] : undefined;
+  if (sourceId && line !== undefined && column !== undefined) {
+    return ` (${sourceId}:${line}:${column})`;
+  }
+  if (sourceId) {
+    return ` (${sourceId})`;
+  }
+  return '';
 }
 
-function isProviderFailureLike(value: unknown): value is ProviderFailureLike {
-  return (
-    isRecord(value) && typeof value['summary'] === 'string' && Array.isArray(value['diagnostics'])
-  );
+function mapDiagnosticsToIssues(
+  diagnostics: readonly unknown[],
+): ReadonlyArray<{ readonly kind: string; readonly message: string }> {
+  const issues: { readonly kind: string; readonly message: string }[] = [];
+  for (const raw of diagnostics) {
+    if (!isRecord(raw)) continue;
+    const code = typeof raw['code'] === 'string' ? raw['code'] : 'diagnostic';
+    const message = typeof raw['message'] === 'string' ? raw['message'] : '';
+    issues.push({ kind: code, message: `${message}${diagnosticLocationSuffix(raw)}` });
+  }
+  return issues;
+}
+
+function validateProviderResult(providerResult: unknown): ValidatedProviderResult {
+  if (!isRecord(providerResult) || typeof providerResult['ok'] !== 'boolean') {
+    return {
+      ok: false,
+      error: failedToResolveContractSource(
+        'Contract source provider returned malformed result shape.',
+        'Ensure contract.source.load resolves to ok(Contract) or notOk({ summary, diagnostics }).',
+      ),
+    };
+  }
+
+  if (providerResult['ok']) {
+    if (!('value' in providerResult)) {
+      return {
+        ok: false,
+        error: failedToResolveContractSource(
+          'Contract source provider returned malformed success result: missing value.',
+          'Ensure contract.source.load success payload is ok(Contract).',
+        ),
+      };
+    }
+    return { ok: true, value: providerResult['value'] };
+  }
+
+  const failure = providerResult['failure'];
+  if (
+    !isRecord(failure) ||
+    typeof failure['summary'] !== 'string' ||
+    !Array.isArray(failure['diagnostics'])
+  ) {
+    return {
+      ok: false,
+      error: failedToResolveContractSource(
+        'Contract source provider returned malformed failure result: expected summary and diagnostics.',
+        'Ensure contract.source.load failure payload is notOk({ summary, diagnostics, meta? }).',
+      ),
+    };
+  }
+  return {
+    ok: false,
+    error: failedToResolveContractSource(
+      String(failure['summary']),
+      'Fix contract source diagnostics and return ok(Contract).',
+      {
+        diagnostics: failure['diagnostics'],
+        issues: mapDiagnosticsToIssues(failure['diagnostics']),
+        ...ifDefined('providerMeta', failure['meta']),
+      },
+    ),
+  };
 }
 
 /**
- * Executes the contract emit operation.
+ * Canonical 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
+ * This is the SINGLE publication path used by both the CLI command
+ * (`prisma-next contract emit`) and the Vite plugin
+ * (`@prisma-next/vite-plugin-contract-emit`). New callers must go through this
+ * function rather than re-implementing load → emit → publish.
  *
- * Supports AbortSignal for cancellation, enabling "last change wins" behavior.
+ * The whole flow (load config → resolve source → emit bytes → atomic publish)
+ * is serialized per output JSON path via `queueEmitByOutput`. Concurrent calls
+ * for the same output line up FIFO; the user-visible outcome is "last
+ * submission wins on disk" without any supersession bookkeeping. Within a
+ * single emit, `publishContractArtifactPair` stages temp files, renames
+ * `contract.d.ts` before `contract.json`, and attempts to restore the previous
+ * pair if either rename fails — so type-only consumers never observe a
+ * mismatched pair.
  *
- * @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')
+ * @throws {CliStructuredError} on config/source/validation problems
+ * @throws {DOMException} `AbortError` if cancelled via `signal`
  */
 export async function executeContractEmit(
   options: ContractEmitOptions,
 ): Promise<ContractEmitResult> {
-  const { configPath, signal = new AbortController().signal } = options;
+  const { configPath, signal = new AbortController().signal, onProgress } = 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: ... }',
@@ -66,14 +165,12 @@ export async function executeContractEmit(
 
   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.',
     });
   }
 
-  // Validate source exists and is callable
   if (typeof contractConfig.source?.load !== 'function') {
     throw errorContractConfigMissing({
       why: 'Contract config must include a valid source provider object',
@@ -90,98 +187,84 @@ export async function executeContractEmit(
   }
   const { jsonPath: outputJsonPath, dtsPath: outputDtsPath } = outputPaths;
 
-  const stack = createControlStack(config);
+  return queueEmitByOutput(outputJsonPath, async () => {
+    const stack = createControlStack(config);
 
-  const sourceContext = {
-    composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
-    scalarTypeDescriptors: stack.scalarTypeDescriptors,
-    authoringContributions: stack.authoringContributions,
-    codecLookup: stack.codecLookup,
-    controlMutationDefaults: stack.controlMutationDefaults,
-    resolvedInputs: contractConfig.source.inputs ?? [],
-  };
+    const sourceContext = {
+      composedExtensionPacks: stack.extensionPacks.map((p) => p.id),
+      scalarTypeDescriptors: stack.scalarTypeDescriptors,
+      authoringContributions: stack.authoringContributions,
+      codecLookup: stack.codecLookup,
+      controlMutationDefaults: stack.controlMutationDefaults,
+      resolvedInputs: contractConfig.source.inputs ?? [],
+    };
 
-  let providerResult: Awaited<ReturnType<typeof contractConfig.source.load>>;
-  try {
-    providerResult = await unlessAborted(contractConfig.source.load(sourceContext));
-  } catch (error) {
-    if (signal.aborted || isAbortError(error)) {
-      throw error;
+    startSpan(onProgress, 'resolveSource', 'Resolving contract source...');
+    let providerResult: Awaited<ReturnType<typeof contractConfig.source.load>>;
+    try {
+      providerResult = await unlessAborted(contractConfig.source.load(sourceContext));
+    } catch (error) {
+      endSpan(onProgress, 'resolveSource', 'error');
+      if (signal.aborted || (isRecord(error) && error['name'] === 'AbortError')) {
+        throw error;
+      }
+      throw failedToResolveContractSource(
+        error instanceof Error ? error.message : String(error),
+        'Ensure contract.source.load resolves to ok(Contract) or returns structured diagnostics.',
+      );
     }
-    throw errorRuntime('Failed to resolve contract source', {
-      why: error instanceof Error ? error.message : String(error),
-      fix: 'Ensure contract.source.load resolves to ok(Contract) or returns structured diagnostics.',
-    });
-  }
 
-  if (!isRecord(providerResult) || typeof providerResult.ok !== 'boolean') {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed result shape.',
-      fix: 'Ensure contract.source.load resolves to ok(Contract) or notOk({ summary, diagnostics }).',
-    });
-  }
-
-  if (providerResult.ok && !('value' in providerResult)) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed success result: missing value.',
-      fix: 'Ensure contract.source.load success payload is ok(Contract).',
-    });
-  }
+    const validatedContract = validateProviderResult(providerResult);
+    if (!validatedContract.ok) {
+      endSpan(onProgress, 'resolveSource', 'error');
+      throw validatedContract.error;
+    }
+    endSpan(onProgress, 'resolveSource', 'ok');
 
-  if (!providerResult.ok && !isProviderFailureLike(providerResult.failure)) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: 'Contract source provider returned malformed failure result: expected summary and diagnostics.',
-      fix: 'Ensure contract.source.load failure payload is notOk({ summary, diagnostics, meta? }).',
-    });
-  }
+    startSpan(onProgress, 'emit', 'Emitting contract...');
+    let emitResult: Awaited<ReturnType<typeof emit>>;
+    try {
+      const familyInstance = config.family.create(stack);
+      const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+      const frameworkComponents = assertFrameworkComponentsCompatible(
+        config.family.familyId,
+        config.target.targetId,
+        rawComponents,
+      );
+      const enrichedIR = enrichContract(validatedContract.value as Contract, frameworkComponents);
+      familyInstance.validateContract(enrichedIR);
+      emitResult = await unlessAborted(
+        emit(enrichedIR, stack, config.family.emission, { outputJsonPath }),
+      );
+    } catch (error) {
+      endSpan(onProgress, 'emit', 'error');
+      throw error;
+    }
+    endSpan(onProgress, 'emit', 'ok');
 
-  if (!providerResult.ok) {
-    throw errorRuntime('Failed to resolve contract source', {
-      why: providerResult.failure.summary,
-      fix: 'Fix contract source diagnostics and return ok(Contract).',
-      meta: {
-        diagnostics: providerResult.failure.diagnostics,
-        ...ifDefined('providerMeta', providerResult.failure.meta),
-      },
+    await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
+    await publishContractArtifactPair({
+      outputJsonPath,
+      outputDtsPath,
+      contractJson: emitResult.contractJson,
+      contractDts: emitResult.contractDts,
+      publicationToken: String(process.hrtime.bigint()),
     });
-  }
 
-  const familyInstance = config.family.create(stack);
-
-  const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
-  const frameworkComponents = assertFrameworkComponentsCompatible(
-    config.family.familyId,
-    config.target.targetId,
-    rawComponents,
-  );
-  const enrichedIR = enrichContract(providerResult.value as Contract, frameworkComponents);
-
-  familyInstance.validateContract(enrichedIR);
-  const emitResult = await unlessAborted(
-    emit(enrichedIR, stack, config.family.emission, {
-      outputJsonPath: outputJsonPath,
-    }),
-  );
-
-  // 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'));
-
-  // Validate that contract.d.ts type imports are resolvable
-  const { validateContractDeps } = await import('../../utils/validate-contract-deps');
-  const depsValidation = validateContractDeps(emitResult.contractDts, dirname(outputDtsPath));
-  if (depsValidation.warning) {
-    process.stderr.write(`\n⚠ ${depsValidation.warning}\n`);
-  }
+    const validationWarning = validateContractDeps(
+      emitResult.contractDts,
+      dirname(outputDtsPath),
+    ).warning;
 
-  return {
-    storageHash: emitResult.storageHash,
-    ...ifDefined('executionHash', emitResult.executionHash),
-    profileHash: emitResult.profileHash,
-    files: {
-      json: outputJsonPath,
-      dts: outputDtsPath,
-    },
-  };
+    return {
+      storageHash: emitResult.storageHash,
+      ...ifDefined('executionHash', emitResult.executionHash),
+      profileHash: emitResult.profileHash,
+      files: {
+        json: outputJsonPath,
+        dts: outputDtsPath,
+      },
+      ...ifDefined('validationWarning', validationWarning),
+    };
+  });
 }

package/src/control-api/operations/db-init.ts

@@ -8,10 +8,10 @@ import type {
   MigrationRunnerResult,
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
+import { hasOperationPreview } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import type { DbInitResult, DbInitSuccess, OnControlProgress } from '../types';
-import { extractOperationStatements } from './extract-operation-statements';
 import { createOperationCallbacks, stripOperations } from './migration-helpers';
 
 /**
@@ -84,8 +84,9 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     schema: schemaIR,
     policy,
     // `db init` does not produce a `migration.ts`, so the from-hash on the
-    // resulting plan is never surfaced to authoring — pass empty string.
-    fromHash: '',
+    // resulting plan is never surfaced to authoring — pass null (the
+    // baseline encoding for `MigrationPlanner.plan({ fromHash })`).
+    fromHash: null,
     frameworkComponents,
   });
 
@@ -194,12 +195,14 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
 
   // Plan mode - don't execute
   if (mode === 'plan') {
-    const planSql = extractOperationStatements(familyInstance.familyId, migrationPlan.operations);
+    const preview = hasOperationPreview(familyInstance)
+      ? familyInstance.toOperationPreview(migrationPlan.operations)
+      : undefined;
     const result: DbInitSuccess = {
       mode: 'plan',
       plan: {
         operations: stripOperations(migrationPlan.operations),
-        ...ifDefined('sql', planSql),
+        ...ifDefined('preview', preview),
       },
       destination: {
         storageHash: migrationPlan.destination.storageHash,

package/src/control-api/operations/db-update.ts

@@ -7,10 +7,10 @@ import type {
   MigrationRunnerResult,
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
+import { hasOperationPreview } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import type { DbUpdateResult, DbUpdateSuccess, OnControlProgress } from '../types';
-import { extractOperationStatements } from './extract-operation-statements';
 import { createOperationCallbacks, stripOperations } from './migration-helpers';
 
 // F12: db update allows additive, widening, and destructive operations.
@@ -84,8 +84,9 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
     schema: schemaIR,
     policy,
     // `db update` does not produce a `migration.ts`, so the from-hash on the
-    // resulting plan is never surfaced to authoring — pass empty string.
-    fromHash: '',
+    // resulting plan is never surfaced to authoring — pass null (the
+    // baseline encoding for `MigrationPlanner.plan({ fromHash })`).
+    fromHash: null,
     frameworkComponents,
   });
   if (plannerResult.kind === 'failure') {
@@ -113,12 +114,14 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
   const migrationPlan = plannerResult.plan;
 
   if (mode === 'plan') {
-    const planSql = extractOperationStatements(familyInstance.familyId, migrationPlan.operations);
+    const preview = hasOperationPreview(familyInstance)
+      ? familyInstance.toOperationPreview(migrationPlan.operations)
+      : undefined;
     const result: DbUpdateSuccess = {
       mode: 'plan',
       plan: {
         operations: stripOperations(migrationPlan.operations),
-        ...(planSql !== undefined ? { sql: planSql } : {}),
+        ...ifDefined('preview', preview),
       },
       destination: {
         storageHash: migrationPlan.destination.storageHash,

package/src/control-api/operations/migration-apply.ts

@@ -30,6 +30,21 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
   readonly onProgress?: OnControlProgress;
 }
 
+/**
+ * Apply a sequence of migration packages against the configured driver.
+ *
+ * Validates the path's continuity (origin → ... → destination, no gaps),
+ * then drives the family/target's migration runner over each package's
+ * operations in order, surfacing per-migration progress through `onProgress`.
+ *
+ * The `pendingMigrations` parameter is trusted input. Callers are responsible
+ * for upstream verification of the originating migration packages — typically
+ * by loading them via `readMigrationPackage` from
+ * `@prisma-next/migration-tools/io`, which performs hash-integrity checks at
+ * the load boundary. This operation does not re-verify the packages and
+ * assumes the `(metadata, ops)` pairs on disk have not been tampered with
+ * since emit.
+ */
 export async function executeMigrationApply<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteMigrationApplyOptions<TFamilyId, TTargetId>,
 ): Promise<MigrationApplyResult> {
@@ -64,15 +79,19 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
 
   const firstMigration = pendingMigrations[0]!;
   const lastMigration = pendingMigrations[pendingMigrations.length - 1]!;
-  if (firstMigration.from !== originHash || lastMigration.to !== destinationHash) {
+  // Manifest `from` is `string | null` (null = baseline). The live-marker
+  // layer encodes "no prior state" as EMPTY_CONTRACT_HASH; bridge here so the
+  // string comparisons below work uniformly.
+  const firstFromMarker = firstMigration.from ?? EMPTY_CONTRACT_HASH;
+  if (firstFromMarker !== originHash || lastMigration.to !== destinationHash) {
     return notOk({
       code: 'MIGRATION_PATH_NOT_FOUND' as const,
       summary: 'Migration apply path does not match requested origin and destination',
-      why: `Path resolved as ${firstMigration.from} -> ${lastMigration.to}, but requested ${originHash} -> ${destinationHash}`,
+      why: `Path resolved as ${firstFromMarker} -> ${lastMigration.to}, but requested ${originHash} -> ${destinationHash}`,
       meta: {
         originHash,
         destinationHash,
-        pathOrigin: firstMigration.from,
+        pathOrigin: firstFromMarker,
         pathDestination: lastMigration.to,
       },
     });
@@ -81,18 +100,19 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
   for (let i = 1; i < pendingMigrations.length; i++) {
     const previous = pendingMigrations[i - 1]!;
     const current = pendingMigrations[i]!;
-    if (previous.to !== current.from) {
+    const currentFromMarker = current.from ?? EMPTY_CONTRACT_HASH;
+    if (previous.to !== currentFromMarker) {
       return notOk({
         code: 'MIGRATION_PATH_NOT_FOUND' as const,
         summary: 'Migration apply path contains a discontinuity between adjacent migrations',
-        why: `Migration "${previous.dirName}" ends at ${previous.to}, but next migration "${current.dirName}" starts at ${current.from}`,
+        why: `Migration "${previous.dirName}" ends at ${previous.to}, but next migration "${current.dirName}" starts at ${currentFromMarker}`,
         meta: {
           originHash,
           destinationHash,
           previousDirName: previous.dirName,
           previousTo: previous.to,
           currentDirName: current.dirName,
-          currentFrom: current.from,
+          currentFrom: currentFromMarker,
           discontinuityIndex: i,
         },
       });
@@ -120,11 +140,11 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
       allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] as const,
     };
 
-    // EMPTY_CONTRACT_HASH means "no prior state" — the runner expects origin: null
-    // for a fresh database (no marker present).
+    // Manifest `from === null` means "no prior state" — the runner expects
+    // `origin: null` for a fresh database (no marker present).
     const plan = {
       targetId,
-      origin: migration.from === EMPTY_CONTRACT_HASH ? null : { storageHash: migration.from },
+      origin: migration.from === null ? null : { storageHash: migration.from },
       destination: { storageHash: migration.to },
       operations,
     };