@prisma-next/cli 0.11.0-dev.6 → 0.11.0-dev.8

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/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');

package/src/utils/plan-resolution.ts

@@ -0,0 +1,257 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { ControlFamilyInstance } from '@prisma-next/framework-components/control';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
+import {
+  assertHashIsGraphNode,
+  findLatestMigration,
+  isGraphNode,
+} from '@prisma-next/migration-tools/migration-graph';
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+import type { Refs } from '@prisma-next/migration-tools/refs';
+import { readRefSnapshot, readRefs } from '@prisma-next/migration-tools/refs';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import {
+  CliStructuredError,
+  errorContractValidationFailed,
+  errorPlanForgotTheFlag,
+  errorSnapshotMissing,
+  errorUnexpected,
+  mapMigrationToolsError,
+  mapRefResolutionError,
+} from './cli-errors';
+
+const FULL_HASH_PATTERN = /^sha256:([0-9a-f]{64}|empty)$/;
+
+export function looksLikeFullHash(input: string): boolean {
+  return FULL_HASH_PATTERN.test(input);
+}
+
+export type FromResolution =
+  | { kind: 'greenfield'; fromHash: null; fromContract: null }
+  | { kind: 'graph-node'; fromHash: string; fromContract: Contract; sourceDir: string }
+  | {
+      kind: 'snapshot';
+      fromHash: string;
+      fromContract: Contract;
+      contractDts: string;
+      contractJson: unknown;
+    }
+  | {
+      kind: 'auto-baseline';
+      fromHash: string;
+      fromContract: Contract;
+      contractDts: string;
+      contractJson: unknown;
+    };
+
+export interface ResolveFromForPlanInput {
+  readonly optionsFrom?: string | undefined;
+  readonly refsDir: string;
+  readonly bundles: readonly OnDiskMigrationPackage[];
+  readonly graph: MigrationGraph;
+  readonly familyInstance: ControlFamilyInstance<string, unknown>;
+  readonly readBundleEndContract: (migrationDir: string) => Promise<Contract>;
+}
+
+function graphIsEmpty(bundles: readonly OnDiskMigrationPackage[]): boolean {
+  return bundles.length === 0;
+}
+
+function getReachableRefs(
+  refs: Refs,
+  graph: MigrationGraph,
+): ReadonlyArray<{ name: string; hash: string }> {
+  return Object.entries(refs)
+    .flatMap(([name, entry]) =>
+      entry && isGraphNode(entry.hash, graph) ? [{ name, hash: entry.hash }] : [],
+    )
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function assertFromIsGraphNode(
+  fromHash: string,
+  graph: MigrationGraph,
+  refs: Refs,
+  graphTipHash: string | null,
+): void {
+  try {
+    assertHashIsGraphNode(fromHash, graph);
+  } catch (error) {
+    if (MigrationToolsError.is(error) && error.code === 'MIGRATION.HASH_NOT_IN_GRAPH') {
+      throw errorPlanForgotTheFlag(fromHash, getReachableRefs(refs, graph), graphTipHash);
+    }
+    throw error;
+  }
+}
+
+async function deserializeSnapshotContract(
+  familyInstance: ControlFamilyInstance<string, unknown>,
+  contract: unknown,
+): Promise<Result<Contract, CliStructuredError>> {
+  try {
+    return ok(familyInstance.deserializeContract(contract));
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    return notOk(
+      errorContractValidationFailed(
+        `Ref snapshot contract failed to deserialize: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: 'ref-snapshot' } },
+      ),
+    );
+  }
+}
+
+async function resolveGraphNodeFromBundle(
+  fromHash: string,
+  bundles: readonly OnDiskMigrationPackage[],
+  readBundleEndContract: (migrationDir: string) => Promise<Contract>,
+  explicitFromLabel?: string,
+): Promise<Result<Extract<FromResolution, { kind: 'graph-node' }>, CliStructuredError>> {
+  const matchingBundle = bundles.find((pkg) => pkg.metadata.to === fromHash);
+  if (!matchingBundle) {
+    return notOk(
+      errorUnexpected(
+        explicitFromLabel
+          ? `No migration bundle found for --from "${explicitFromLabel}" (resolved hash: ${fromHash})`
+          : `No migration bundle found for graph node ${fromHash}`,
+        {
+          why: `The hash ${fromHash} is a graph node but no on-disk migration package has an end-contract hash matching it.`,
+          fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
+        },
+      ),
+    );
+  }
+  try {
+    const fromContract = await readBundleEndContract(matchingBundle.dirPath);
+    return ok({
+      kind: 'graph-node',
+      fromHash,
+      fromContract,
+      sourceDir: matchingBundle.dirPath,
+    });
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    throw error;
+  }
+}
+
+async function resolveFromRefName(
+  refName: string,
+  fromHash: string,
+  input: ResolveFromForPlanInput,
+  refs: Refs,
+): Promise<Result<FromResolution, CliStructuredError>> {
+  const { refsDir, bundles, graph, familyInstance, readBundleEndContract } = input;
+  const empty = graphIsEmpty(bundles);
+  const graphTip = findLatestMigration(graph)?.to ?? null;
+
+  let snapshot: Awaited<ReturnType<typeof readRefSnapshot>>;
+  try {
+    snapshot = await readRefSnapshot(refsDir, refName);
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
+    throw error;
+  }
+
+  if (snapshot) {
+    const contractResult = await deserializeSnapshotContract(familyInstance, snapshot.contract);
+    if (!contractResult.ok) {
+      return contractResult;
+    }
+    const fromContract = contractResult.value;
+    const { contractDts, contract: contractJson } = snapshot;
+    if (empty) {
+      return ok({ kind: 'auto-baseline', fromHash, fromContract, contractDts, contractJson });
+    }
+    try {
+      assertFromIsGraphNode(fromHash, graph, refs, graphTip);
+    } catch (error) {
+      if (CliStructuredError.is(error)) {
+        return notOk(error);
+      }
+      throw error;
+    }
+    return ok({ kind: 'snapshot', fromHash, fromContract, contractDts, contractJson });
+  }
+
+  if (isGraphNode(fromHash, graph)) {
+    return resolveGraphNodeFromBundle(fromHash, bundles, readBundleEndContract);
+  }
+
+  return notOk(errorSnapshotMissing(refName));
+}
+
+async function resolveFromHashProvenance(
+  fromHash: string,
+  input: ResolveFromForPlanInput,
+  _refs: Refs,
+  explicitFromLabel?: string,
+): Promise<Result<FromResolution, CliStructuredError>> {
+  const { bundles, graph } = input;
+
+  if (isGraphNode(fromHash, graph)) {
+    return resolveGraphNodeFromBundle(
+      fromHash,
+      bundles,
+      input.readBundleEndContract,
+      explicitFromLabel,
+    );
+  }
+
+  throw new Error(
+    `resolveFromHashProvenance: non-graph-node hash ${fromHash} should be refused via looksLikeFullHash before this helper is called`,
+  );
+}
+
+export async function resolveFromForPlan(
+  input: ResolveFromForPlanInput,
+): Promise<Result<FromResolution, CliStructuredError>> {
+  const { optionsFrom, refsDir, graph } = input;
+
+  let refs: Refs;
+  try {
+    refs = await readRefs(refsDir);
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
+    throw error;
+  }
+
+  if (optionsFrom === undefined) {
+    const dbRef = refs['db'];
+    if (!dbRef) {
+      return ok({ kind: 'greenfield', fromHash: null, fromContract: null });
+    }
+    return resolveFromRefName('db', dbRef.hash, input, refs);
+  }
+
+  const refResult = parseContractRef(optionsFrom, { graph, refs });
+  if (!refResult.ok) {
+    if (looksLikeFullHash(optionsFrom)) {
+      const empty = graphIsEmpty(input.bundles);
+      const graphTip = findLatestMigration(graph)?.to ?? null;
+      if (empty) {
+        return notOk(errorSnapshotMissing(optionsFrom, { viaRef: false }));
+      }
+      return notOk(errorPlanForgotTheFlag(optionsFrom, getReachableRefs(refs, graph), graphTip));
+    }
+    return notOk(mapRefResolutionError(refResult.failure));
+  }
+
+  const { hash: fromHash, provenance } = refResult.value;
+
+  if (provenance.kind === 'ref') {
+    return resolveFromRefName(provenance.refName, fromHash, input, refs);
+  }
+
+  return resolveFromHashProvenance(fromHash, input, refs, optionsFrom);
+}

package/src/utils/ref-advancement.ts

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import type { ContractIR } from '@prisma-next/migration-tools/refs';
+import { writeRefPaired } from '@prisma-next/migration-tools/refs';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+export interface RefAdvancementFields {
+  readonly advancedRef: { readonly name: string; readonly hash: string } | null;
+  readonly plannedAdvanceRef: { readonly name: string; readonly hash: string } | null;
+}
+
+export function computeRefAdvancementName(options: {
+  readonly advanceRef?: string;
+  readonly db?: string;
+}): string | null {
+  if (options.advanceRef !== undefined) {
+    return options.advanceRef;
+  }
+  if (options.db === undefined) {
+    return 'db';
+  }
+  return null;
+}
+
+export async function readContractIR(
+  contractJson: Record<string, unknown>,
+  contractJsonPath: string,
+): Promise<ContractIR> {
+  const contractDtsPath = contractJsonPath.replace(/\.json$/i, '.d.ts');
+  const contractDts = await readFile(contractDtsPath, 'utf-8');
+  return { contract: contractJson, contractDts };
+}
+
+export async function executeRefAdvancement(
+  refsDir: string,
+  name: string,
+  hash: string,
+  contractIR: ContractIR,
+): Promise<{ name: string; hash: string }> {
+  await writeRefPaired(refsDir, name, { hash, invariants: [] }, contractIR);
+  return { name, hash };
+}
+
+export async function buildRefAdvancementFields(options: {
+  readonly advanceRef?: string;
+  readonly db?: string;
+  readonly refsDir: string;
+  readonly contractIR: ContractIR;
+  readonly mode: 'plan' | 'apply';
+  readonly hash: string;
+}): Promise<RefAdvancementFields> {
+  const name = computeRefAdvancementName({
+    ...ifDefined('advanceRef', options.advanceRef),
+    ...ifDefined('db', options.db),
+  });
+  if (name === null) {
+    return { advancedRef: null, plannedAdvanceRef: null };
+  }
+  if (options.mode === 'plan') {
+    return { advancedRef: null, plannedAdvanceRef: { name, hash: options.hash } };
+  }
+  const advancedRef = await executeRefAdvancement(
+    options.refsDir,
+    name,
+    options.hash,
+    options.contractIR,
+  );
+  return { advancedRef, plannedAdvanceRef: null };
+}

package/dist/cli-errors-Czmx92Zy.d.mts

@@ -1,3 +0,0 @@
-import { CliStructuredError as CliStructuredError$1 } from "@prisma-next/errors/control";
-import { MigrationToolsError } from "@prisma-next/migration-tools/errors";
-export { CliStructuredError$1 as t };