@prisma-next/cli 0.11.0-dev.2 → 0.11.0-dev.20

package/src/commands/ref.ts

@@ -1,18 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { findLatestMigration, isGraphNode } from '@prisma-next/migration-tools/migration-graph';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
-  deleteRef,
+  deleteRefPaired,
   readRefs,
   validateRefName,
   validateRefValue,
-  writeRef,
+  writeRefPaired,
 } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
+import { join } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   CliStructuredError,
+  errorFileNotFound,
+  errorRefSetBundleNotFound,
+  errorRefSetEmptySentinel,
+  errorRefSetHashNotInGraph,
   errorRuntime,
   errorUnexpected,
   mapMigrationToolsError,
@@ -26,6 +34,7 @@ import {
 } from '../utils/command-helpers';
 import { formatCommandHelp } from '../utils/formatters/help';
 import { parseGlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { readContractIR } from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI } from '../utils/terminal-ui';
 
@@ -73,13 +82,13 @@ export async function executeRefSetCommand(
   try {
     const config = await loadConfig(options.config);
     const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+    const { graph, bundles } = await loadMigrationPackages(appMigrationsDir);
+    const refs = await readRefs(refsDir);
 
     let resolvedHash: string;
     if (validateRefValue(contractInput)) {
       resolvedHash = contractInput;
     } else {
-      const { graph } = await loadMigrationPackages(appMigrationsDir);
-      const refs = await readRefs(refsDir);
       const refResult = parseContractRef(contractInput, { graph, refs });
       if (!refResult.ok) {
         return notOk(mapRefResolutionError(refResult.failure));
@@ -87,8 +96,39 @@ export async function executeRefSetCommand(
       resolvedHash = refResult.value.hash;
     }
 
+    if (resolvedHash === EMPTY_CONTRACT_HASH) {
+      return notOk(errorRefSetEmptySentinel(resolvedHash));
+    }
+    if (!isGraphNode(resolvedHash, graph)) {
+      const graphTip = findLatestMigration(graph)?.to ?? null;
+      return notOk(errorRefSetHashNotInGraph(resolvedHash, [...graph.nodes].sort(), graphTip));
+    }
+
+    const matchingBundle = bundles.find((bundle) => bundle.metadata.to === resolvedHash);
+    if (!matchingBundle) {
+      return notOk(errorRefSetBundleNotFound(resolvedHash));
+    }
+
+    const contractJsonPath = join(matchingBundle.dirPath, 'end-contract.json');
+    let contractJson: Record<string, unknown>;
+    try {
+      const raw = await readFile(contractJsonPath, 'utf-8');
+      contractJson = JSON.parse(raw) as Record<string, unknown>;
+    } catch (readError) {
+      if (readError instanceof Error && (readError as NodeJS.ErrnoException).code === 'ENOENT') {
+        return notOk(
+          errorFileNotFound(contractJsonPath, {
+            why: `Migration bundle for hash ${resolvedHash} is missing its end-contract snapshot at ${contractJsonPath}`,
+            fix: 'Run `pnpm fixtures:check`, or re-emit the migration so its end-contract.json is restored.',
+          }),
+        );
+      }
+      throw readError;
+    }
+
+    const contractIR = await readContractIR(contractJson, contractJsonPath);
     const entry: RefEntry = { hash: resolvedHash, invariants: [] };
-    await writeRef(refsDir, name, entry);
+    await writeRefPaired(refsDir, name, entry, contractIR);
     return ok({ ok: true as const, ref: name, hash: resolvedHash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -103,7 +143,7 @@ export async function executeRefDeleteCommand(
   try {
     const config = await loadConfig(options.config);
     const { refsDir } = resolveMigrationPaths(options.config, config);
-    await deleteRef(refsDir, name);
+    await deleteRefPaired(refsDir, name);
     return ok({ ok: true as const, ref: name, deleted: true as const });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);

package/src/control-api/contract-enrichment.ts

@@ -1,7 +1,8 @@
 import type { Contract } from '@prisma-next/contract/types';
-import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
-
-type CapabilityMatrix = Record<string, Record<string, boolean>>;
+import {
+  mergeCapabilityMatrices,
+  type TargetBoundComponentDescriptor,
+} from '@prisma-next/framework-components/components';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -26,37 +27,6 @@ function sortDeepTyped<T>(value: T): T {
   return sortDeep(value) as T;
 }
 
-function extractCapabilityMatrix(value: unknown): CapabilityMatrix {
-  if (!isPlainObject(value)) return {};
-
-  const out: CapabilityMatrix = {};
-  for (const [namespace, maybeCaps] of Object.entries(value)) {
-    if (!isPlainObject(maybeCaps)) continue;
-    const caps: Record<string, boolean> = {};
-    for (const [key, flag] of Object.entries(maybeCaps)) {
-      if (typeof flag === 'boolean') {
-        caps[key] = flag;
-      }
-    }
-    if (Object.keys(caps).length > 0) {
-      out[namespace] = caps;
-    }
-  }
-
-  return out;
-}
-
-function mergeCapabilities(left: CapabilityMatrix, right: CapabilityMatrix): CapabilityMatrix {
-  const next: CapabilityMatrix = { ...left };
-  for (const [namespace, capabilities] of Object.entries(right)) {
-    next[namespace] = {
-      ...(left[namespace] ?? {}),
-      ...capabilities,
-    };
-  }
-  return next;
-}
-
 function extractExtensionPackMeta(
   component: TargetBoundComponentDescriptor<string, string>,
 ): Record<string, unknown> {
@@ -93,16 +63,10 @@ export function enrichContract(
   ir: Contract,
   components: ReadonlyArray<TargetBoundComponentDescriptor<string, string>>,
 ): Contract {
-  let mergedCapabilities = ir.capabilities;
-  const extensionPacksMeta: Record<string, unknown> = {};
+  const mergedCapabilities = mergeCapabilityMatrices(ir.capabilities, components);
 
+  const extensionPacksMeta: Record<string, unknown> = {};
   for (const component of components) {
-    if (component.capabilities) {
-      mergedCapabilities = mergeCapabilities(
-        mergedCapabilities,
-        extractCapabilityMatrix(component.capabilities),
-      );
-    }
     if (component.kind === 'extension') {
       extensionPacksMeta[component.id] = extractExtensionPackMeta(component);
     }

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

@@ -5,7 +5,7 @@ import { createControlStack } from '@prisma-next/framework-components/control';
 import { abortable } from '@prisma-next/utils/abortable';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { JsonObject } from '@prisma-next/utils/json';
-import { dirname } from 'pathe';
+import { dirname, join } from 'pathe';
 import { loadConfig } from '../../config-loader';
 import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
 import { queueEmitByOutput } from '../../utils/emit-queue';
@@ -153,7 +153,7 @@ function validateProviderResult(providerResult: unknown): ValidatedProviderResul
 export async function executeContractEmit(
   options: ContractEmitOptions,
 ): Promise<ContractEmitResult> {
-  const { configPath, signal = new AbortController().signal, onProgress } = options;
+  const { configPath, outputPath, signal = new AbortController().signal, onProgress } = options;
   const unlessAborted = abortable(signal);
 
   const config = await unlessAborted(loadConfig(configPath));
@@ -166,7 +166,10 @@ export async function executeContractEmit(
 
   const contractConfig = config.contract;
 
-  if (!contractConfig.output) {
+  const effectiveOutput =
+    outputPath !== undefined ? join(outputPath, 'contract.json') : contractConfig.output;
+
+  if (!effectiveOutput) {
     throw errorContractConfigMissing({
       why: 'Contract config must have output path. This should not happen if defineConfig() was used.',
     });
@@ -180,7 +183,7 @@ export async function executeContractEmit(
 
   let outputPaths: ReturnType<typeof getEmittedArtifactPaths>;
   try {
-    outputPaths = getEmittedArtifactPaths(contractConfig.output);
+    outputPaths = getEmittedArtifactPaths(effectiveOutput);
   } catch (error) {
     throw errorContractConfigMissing({
       why: error instanceof Error ? error.message : String(error),

package/src/control-api/types.ts

@@ -719,6 +719,13 @@ export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyF
 export interface ContractEmitOptions {
   /** Path to the prisma-next.config.ts file */
   readonly configPath: string;
+  /**
+   * Directory to write contract artifacts into. When set, `contract.json` and
+   * `contract.d.ts` are written inside this directory, taking precedence over
+   * any output path from the loaded config. The value must be an absolute path;
+   * resolution against cwd is the caller's responsibility.
+   */
+  readonly outputPath?: string;
   /** Optional AbortSignal for cancelling the in-flight emit */
   readonly signal?: AbortSignal;
   /** Optional progress callback for observing source-resolution and emit spans */

package/src/utils/cli-errors.ts

@@ -28,6 +28,7 @@ import {
 import { errorRuntime } from '@prisma-next/errors/execution';
 import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';
+import type { MigrationApplyFailure } from '../control-api/types';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -68,6 +69,178 @@ export {
   errorUnexpected,
 };
 
+export function errorRefSetHashNotInGraph(
+  resolvedHash: string,
+  reachableHashes: readonly string[],
+  graphTipHash: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';
+  const fix =
+    reachableHashes.length > 0
+      ? graphTipHash !== null
+        ? `Set the ref to a graph-node hash such as ${graphTipHash}, or run \`prisma-next migration plan\` to extend the graph.`
+        : 'Set the ref to a hash that appears in the migration graph.'
+      : 'Run `prisma-next migration plan` first.';
+  return errorRuntime(`Resolved contract hash is not in the migration graph: ${resolvedHash}`, {
+    why:
+      reachableHashes.length > 0
+        ? `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`
+        : 'The migration graph is empty — no hashes reachable.',
+    fix,
+    meta: {
+      code: 'MIGRATION.HASH_NOT_IN_GRAPH',
+      resolvedHash,
+      reachableHashes: [...reachableHashes],
+      ...(graphTipHash !== null ? { graphTipHash } : {}),
+    },
+  });
+}
+
+export function errorRefSetEmptySentinel(hash: string): CliStructuredError {
+  return errorRuntime(`Cannot set ref to the empty-database sentinel: ${hash}`, {
+    why: 'The empty-database sentinel is a planner internal; it is not a valid ref target.',
+    fix: 'Set the ref to a contract hash from the migration graph, or use another ref name.',
+    meta: {
+      code: 'MIGRATION.REF_SET_EMPTY_SENTINEL',
+      hash,
+    },
+  });
+}
+
+export function errorRefSetBundleNotFound(hash: string): CliStructuredError {
+  return errorRuntime(`No migration bundle matches graph-node hash ${hash}`, {
+    why: `The hash is a graph node but no on-disk bundle has metadata.to = ${hash}.`,
+    fix: 'Run `pnpm fixtures:check`, or re-emit the migration that produces this hash so its bundle is restored.',
+    meta: {
+      code: 'MIGRATION.REF_SET_BUNDLE_NOT_FOUND',
+      hash,
+    },
+  });
+}
+
+export function errorPlanForgotTheFlag(
+  resolvedHash: string,
+  reachableRefs: ReadonlyArray<{ readonly name: string; readonly hash: string }>,
+  graphTipHash: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableRefs.length > 0
+      ? reachableRefs.map((r) => `${r.name} (${r.hash})`).join(', ')
+      : '(none)';
+  const refFix =
+    reachableRefs.length > 0
+      ? `Run migration plan with ${reachableRefs.map((r) => `--from ${r.name}`).join(' or ')}.`
+      : graphTipHash !== null
+        ? `Run migration plan --from ${graphTipHash}.`
+        : 'Commit pending migrations first, then run migration plan.';
+  return errorRuntime(`Resolved from-hash is not in the migration graph: ${resolvedHash}`, {
+    why: `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`,
+    fix: refFix,
+    meta: {
+      code: 'MIGRATION.HASH_NOT_IN_GRAPH',
+      resolvedHash,
+      reachableRefs: reachableRefs.map((r) => r.name),
+      ...(graphTipHash !== null ? { graphTipHash } : {}),
+    },
+  });
+}
+
+export function errorSnapshotMissing(
+  identifier: string,
+  options?: { readonly viaRef?: boolean },
+): CliStructuredError {
+  const viaRef = options?.viaRef !== false;
+  const fix = viaRef
+    ? `Run "prisma-next db update --advance-ref ${identifier}" to repopulate the snapshot, or "prisma-next ref delete ${identifier}" to clear the orphan pointer.`
+    : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;
+  return errorRuntime(
+    viaRef
+      ? `Ref "${identifier}" has no paired contract snapshot`
+      : `No contract source for from-hash "${identifier}"`,
+    {
+      why: viaRef
+        ? `Ref "${identifier}" exists but its paired snapshot files are missing.`
+        : `Hash "${identifier}" is not a graph node and no paired ref snapshot supplies a contract.`,
+      fix,
+      meta: {
+        code: 'MIGRATION.SNAPSHOT_MISSING',
+        identifier,
+        viaRef,
+      },
+    },
+  );
+}
+
+export function errorMarkerMismatch(
+  markerHash: string,
+  reachableHashes: readonly string[],
+  graphTip: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';
+  const planFromFix =
+    graphTip !== null
+      ? `Run \`prisma-next migration plan --from ${graphTip}\` if the live marker is canonical and the on-disk graph needs catching up.`
+      : 'Run `prisma-next migration plan` if the live marker is canonical and the on-disk graph needs catching up.';
+  return errorRuntime('Database marker is not reachable in the on-disk migration graph', {
+    why: `DB marker is ${markerHash}, but the on-disk migration graph reaches: ${reachableList}.`,
+    fix: [
+      planFromFix,
+      `Run \`prisma-next ref set db ${markerHash}\` if the on-disk graph is canonical and the local \`db\` ref drifted.`,
+      'Investigate whether the database was migrated by an out-of-band process.',
+    ].join('\n'),
+    meta: {
+      code: 'MIGRATION.MARKER_MISMATCH',
+      markerHash,
+      reachableHashes: [...reachableHashes],
+      ...(graphTip !== null ? { graphTip } : {}),
+    },
+  });
+}
+
+export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {
+  const meta = failure.meta ?? {};
+  const fromHash = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
+  const targetHash =
+    typeof meta['targetHash'] === 'string'
+      ? meta['targetHash']
+      : typeof meta['target'] === 'string'
+        ? meta['target']
+        : null;
+  const deadEnds = meta['deadEnds'];
+  const deadEndsSuffix =
+    Array.isArray(deadEnds) && deadEnds.length > 0
+      ? ` Dead-ends: ${deadEnds.map(String).join(', ')}.`
+      : '';
+  const planFix = (() => {
+    if (fromHash !== null && targetHash !== null) {
+      return `Run \`prisma-next migration plan --from ${fromHash} --to ${targetHash}\` to introduce the missing path.`;
+    }
+    if (targetHash !== null) {
+      return `Run \`prisma-next migration plan --to ${targetHash}\` to introduce the missing path.`;
+    }
+    if (fromHash !== null) {
+      return `Run \`prisma-next migration plan --from ${fromHash}\` to introduce the missing path.`;
+    }
+    return 'Run `prisma-next migration plan` to introduce the missing path.';
+  })();
+  return errorRuntime(failure.summary, {
+    why:
+      failure.why ??
+      `Cannot reach target "${targetHash ?? '<unknown>'}" from current marker "${fromHash ?? '<unknown>'}".${deadEndsSuffix}`,
+    fix: [
+      'Run `prisma-next migration list` to see the on-disk graph.',
+      planFix,
+      'Run `prisma-next migration show <bundle>` for any bundle in the path you expected.',
+    ].join('\n'),
+    meta: {
+      ...meta,
+      code: 'MIGRATION.PATH_UNREACHABLE',
+    },
+  });
+}
+
 /**
  * Maps a `MigrationToolsError` raised by the migration-tools loader/graph
  * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,

package/src/utils/formatters/migrations.ts

@@ -82,6 +82,8 @@ export interface MigrationCommandResult {
    * into a single ambiguous list. See {@link AggregatePerSpaceExecutionEntry}.
    */
   readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
+  readonly plannedAdvanceRef?: { readonly name: string; readonly hash: string } | null;
   readonly summary: string;
   readonly timings: {
     readonly total: number;
@@ -208,6 +210,15 @@ export function formatMigrationPlanOutput(
     lines.push(`${formatDimText(`Destination hash: ${result.plan.destination.storageHash}`)}`);
   }
 
+  if (result.plannedAdvanceRef) {
+    lines.push('');
+    lines.push(
+      formatDimText(
+        `Would advance ref "${result.plannedAdvanceRef.name}" → ${result.plannedAdvanceRef.hash}`,
+      ),
+    );
+  }
+
   // Statement preview (any family that implements OperationPreviewCapable)
   const preview = result.plan?.preview;
   if (preview) {
@@ -260,6 +271,7 @@ export interface MigrationApplyCommandOutputResult {
   readonly timings?: {
     readonly total: number;
   };
+  readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
 }
 
 export function formatMigrationApplyCommandOutput(
@@ -284,6 +296,13 @@ export function formatMigrationApplyCommandOutput(
     }
   }
 
+  if (result.advancedRef) {
+    lines.push('');
+    lines.push(
+      formatDimText(`Advanced ref "${result.advancedRef.name}" → ${result.advancedRef.hash}`),
+    );
+  }
+
   lines.push('');
   lines.push(formatDimText('Next: prisma-next migration status'));
 
@@ -470,6 +489,12 @@ export function formatMigrationApplyOutput(
     if (isVerbose(flags, 1)) {
       lines.push(`${formatDimText(`  Total time: ${result.timings.total}ms`)}`);
     }
+
+    if (result.advancedRef) {
+      lines.push(
+        formatDimText(`Advanced ref "${result.advancedRef.name}" → ${result.advancedRef.hash}`),
+      );
+    }
   }
 
   return lines.join('\n');