@prisma-next/cli 0.5.0-dev.11 → 0.5.0-dev.12

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/types.ts

@@ -512,18 +512,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 +552,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;
 }
 
 // ============================================================================

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/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/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/contract-emit-B9wkchud.mjs

@@ -1,6 +0,0 @@
-import "./config-loader-C25b63rJ.mjs";
-import "./cli-errors-By1iVE3z.mjs";
-import "./framework-components-C6el-5x_.mjs";
-import { t as executeContractEmit } from "./contract-emit-PeB96eHy.mjs";
-
-export { executeContractEmit };