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

package/src/utils/formatters/migration-list-styler.ts

@@ -0,0 +1,56 @@
+import { bold, cyan, cyanBright, dim, green, greenBright, yellow } from 'colorette';
+import { IDENTITY_MIGRATION_LIST_STYLER, type MigrationListStyler } from './migration-list-render';
+
+/**
+ * The reserved ref name for the live-database marker. Treated as a
+ * structurally distinct token from user-named refs so the styler can
+ * make it visually pop in `(refs)` decorations.
+ */
+const DB_REF_NAME = 'db';
+
+function styleRefName(name: string): string {
+  return name === DB_REF_NAME ? bold(greenBright(name)) : green(name);
+}
+
+/**
+ * Build a {@link MigrationListStyler} that decorates `migration list`
+ * tokens with ANSI SGR codes. When `useColor` is `false` (non-TTY,
+ * `--no-color`, `NO_COLOR=1`, piped output) the function returns the
+ * shared identity styler so callers get plain text with zero ANSI
+ * bytes — pipe-friendly by construction.
+ *
+ * Palette:
+ *
+ * - `dirName`: bold
+ * - `sourceHash`: dim cyan
+ * - `destHash`: bright cyan
+ * - `glyph` (`→` / `⟲` / `∅`): dim
+ * - `invariants` (`{...}`): yellow
+ * - `refs` (`(...)`): green; the live-DB `db` marker inside is green-bold
+ * - `spaceHeading` (`<spaceId>:`): bold
+ * - `summary`: dim
+ * - `emptyState`: dim
+ */
+export function createAnsiMigrationListStyler(opts: {
+  readonly useColor: boolean;
+}): MigrationListStyler {
+  if (!opts.useColor) {
+    return IDENTITY_MIGRATION_LIST_STYLER;
+  }
+  return {
+    dirName: (text) => bold(text),
+    sourceHash: (text) => dim(cyan(text)),
+    destHash: (text) => cyanBright(text),
+    glyph: (text) => dim(text),
+    invariants: (ids) => yellow(`{${ids.join(', ')}}`),
+    refs: (names) => {
+      const open = green('(');
+      const close = green(')');
+      const separator = green(', ');
+      return open + names.map(styleRefName).join(separator) + close;
+    },
+    spaceHeading: (text) => bold(text),
+    summary: (text) => dim(text),
+    emptyState: (text) => dim(text),
+  };
+}

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 };

package/dist/cli-errors-Djtz98Vm.mjs

@@ -1,71 +0,0 @@
-import { CliStructuredError as CliStructuredError$1, errorConfigValidation as errorConfigValidation$1, errorContractConfigMissing as errorContractConfigMissing$1, errorContractValidationFailed, errorDatabaseConnectionRequired, errorDriverRequired, errorFileNotFound, errorInvalidOutputFormat, errorMigrationPlanningFailed, errorOutputFormatMutex, errorTargetMigrationNotSupported, errorUnexpected as errorUnexpected$1 } from "@prisma-next/errors/control";
-import { ERROR_CODE_DESTRUCTIVE_CHANGES, errorDestructiveChanges, errorHashMismatch, errorMarkerMissing, errorRunnerFailed, errorRuntime, errorRuntime as errorRuntime$1, errorTargetMismatch } from "@prisma-next/errors/execution";
-import "@prisma-next/errors/migration";
-//#region src/utils/cli-errors.ts
-/**
-* Maps a `MigrationToolsError` raised by the migration-tools loader/graph
-* surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,
-* `resolveRef`, `reconstructGraph`, ...) into a CLI `errorRuntime` envelope.
-*
-* The full `error.details` payload is forwarded into `meta` so machine
-* consumers (`--json`) see structural fields like `dir`, `storedHash`,
-* `computedHash` (for `MIGRATION.HASH_MISMATCH`) alongside the stable
-* `code`. The user-visible `summary`/`why`/`fix` text is unchanged.
-*
-* Callers are expected to gate on `MigrationToolsError.is(error)` first
-* (mirroring the original inline pattern); non-`MigrationToolsError`
-* values are caller-classified (rethrow, wrap with command-specific
-* `errorUnexpected`, etc.).
-*/
-function mapMigrationToolsError(error) {
-	return errorRuntime(error.message, {
-		why: error.why,
-		fix: error.fix,
-		meta: {
-			code: error.code,
-			...error.details ?? {}
-		}
-	});
-}
-/**
-* Maps a `RefResolutionError` from the contract/migration reference
-* resolver into a CLI structured error envelope.
-*/
-function mapRefResolutionError(error) {
-	switch (error.kind) {
-		case "not-found": return errorRuntime(`Not a known ${error.grammar} reference: "${error.input}"`, {
-			why: `No ${error.grammar} matching "${error.input}" exists in the migration graph or refs index.`,
-			fix: error.grammar === "contract" ? "Provide a valid contract hash, ref name, or migration directory name." : "Provide a valid migration directory name or migration hash.",
-			meta: {
-				input: error.input,
-				grammar: error.grammar
-			}
-		});
-		case "ambiguous": return errorRuntime(`Ambiguous ${error.grammar} reference: "${error.input}"`, {
-			why: `"${error.input}" matches multiple ${error.grammar}s: ${error.candidates.join(", ")}`,
-			fix: "Provide a longer prefix or use the full hash to disambiguate.",
-			meta: {
-				input: error.input,
-				candidates: error.candidates,
-				grammar: error.grammar
-			}
-		});
-		case "wrong-grammar": return errorRuntime(error.message, {
-			why: error.message,
-			fix: error.fix,
-			meta: {
-				input: error.input,
-				expectedGrammar: error.expectedGrammar
-			}
-		});
-		case "invalid-format": return errorRuntime(`Invalid reference format: "${error.input}"`, {
-			why: error.reason,
-			fix: "Provide a valid contract hash, ref name, or migration directory name.",
-			meta: { input: error.input }
-		});
-	}
-}
-//#endregion
-export { errorTargetMigrationNotSupported as _, errorContractValidationFailed as a, mapMigrationToolsError as b, errorDriverRequired as c, errorInvalidOutputFormat as d, errorMarkerMissing as f, errorRuntime$1 as g, errorRunnerFailed as h, errorContractConfigMissing$1 as i, errorFileNotFound as l, errorOutputFormatMutex as m, ERROR_CODE_DESTRUCTIVE_CHANGES as n, errorDatabaseConnectionRequired as o, errorMigrationPlanningFailed as p, errorConfigValidation$1 as r, errorDestructiveChanges as s, CliStructuredError$1 as t, errorHashMismatch as u, errorTargetMismatch as v, mapRefResolutionError as x, errorUnexpected$1 as y };
-
-//# sourceMappingURL=cli-errors-Djtz98Vm.mjs.map

package/dist/cli-errors-Djtz98Vm.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-errors-Djtz98Vm.mjs","names":[],"sources":["../src/utils/cli-errors.ts"],"sourcesContent":["/**\n * Re-export all domain error factories from @prisma-next/errors for convenience.\n * CLI-specific errors (e.g., Commander argument validation in the main CLI, or\n * clipanion parse errors in the migration-file CLI) can be added here if needed.\n */\nexport type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';\n\nimport {\n  CliStructuredError,\n  errorConfigFileNotFound,\n  errorConfigValidation,\n  errorContractConfigMissing,\n  errorContractMissingExtensionPacks,\n  errorContractValidationFailed,\n  errorDatabaseConnectionRequired,\n  errorDriverRequired,\n  errorFamilyReadMarkerSqlRequired,\n  errorFileNotFound,\n  errorInvalidOutputFormat,\n  errorMigrationCliInvalidConfigArg,\n  errorMigrationCliUnknownFlag,\n  errorMigrationPlanningFailed,\n  errorOutputFormatMutex,\n  errorQueryRunnerFactoryRequired,\n  errorTargetMigrationNotSupported,\n  errorUnexpected,\n} from '@prisma-next/errors/control';\nimport { errorRuntime } from '@prisma-next/errors/execution';\nimport type { MigrationToolsError } from '@prisma-next/migration-tools/errors';\nimport type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';\n\nexport {\n  ERROR_CODE_DESTRUCTIVE_CHANGES,\n  errorDestructiveChanges,\n  errorHashMismatch,\n  errorMarkerMissing,\n  errorMarkerRequired,\n  errorRunnerFailed,\n  errorRuntime,\n  errorSchemaVerificationFailed,\n  errorTargetMismatch,\n} from '@prisma-next/errors/execution';\nexport {\n  errorMigrationFileMissing,\n  errorMigrationInvalidDefaultExport,\n  errorMigrationPlanNotArray,\n  errorUnfilledPlaceholder,\n  placeholder,\n} from '@prisma-next/errors/migration';\nexport {\n  CliStructuredError,\n  errorConfigFileNotFound,\n  errorConfigValidation,\n  errorContractConfigMissing,\n  errorContractMissingExtensionPacks,\n  errorContractValidationFailed,\n  errorDatabaseConnectionRequired,\n  errorDriverRequired,\n  errorFamilyReadMarkerSqlRequired,\n  errorFileNotFound,\n  errorInvalidOutputFormat,\n  errorMigrationCliInvalidConfigArg,\n  errorMigrationCliUnknownFlag,\n  errorMigrationPlanningFailed,\n  errorOutputFormatMutex,\n  errorQueryRunnerFactoryRequired,\n  errorTargetMigrationNotSupported,\n  errorUnexpected,\n};\n\n/**\n * Maps a `MigrationToolsError` raised by the migration-tools loader/graph\n * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,\n * `resolveRef`, `reconstructGraph`, ...) into a CLI `errorRuntime` envelope.\n *\n * The full `error.details` payload is forwarded into `meta` so machine\n * consumers (`--json`) see structural fields like `dir`, `storedHash`,\n * `computedHash` (for `MIGRATION.HASH_MISMATCH`) alongside the stable\n * `code`. The user-visible `summary`/`why`/`fix` text is unchanged.\n *\n * Callers are expected to gate on `MigrationToolsError.is(error)` first\n * (mirroring the original inline pattern); non-`MigrationToolsError`\n * values are caller-classified (rethrow, wrap with command-specific\n * `errorUnexpected`, etc.).\n */\nexport function mapMigrationToolsError(error: MigrationToolsError): CliStructuredError {\n  return errorRuntime(error.message, {\n    why: error.why,\n    fix: error.fix,\n    meta: { code: error.code, ...(error.details ?? {}) },\n  });\n}\n\n/**\n * Maps a `RefResolutionError` from the contract/migration reference\n * resolver into a CLI structured error envelope.\n */\nexport function mapRefResolutionError(error: RefResolutionError): CliStructuredError {\n  switch (error.kind) {\n    case 'not-found':\n      return errorRuntime(`Not a known ${error.grammar} reference: \"${error.input}\"`, {\n        why: `No ${error.grammar} matching \"${error.input}\" exists in the migration graph or refs index.`,\n        fix:\n          error.grammar === 'contract'\n            ? 'Provide a valid contract hash, ref name, or migration directory name.'\n            : 'Provide a valid migration directory name or migration hash.',\n        meta: { input: error.input, grammar: error.grammar },\n      });\n    case 'ambiguous':\n      return errorRuntime(`Ambiguous ${error.grammar} reference: \"${error.input}\"`, {\n        why: `\"${error.input}\" matches multiple ${error.grammar}s: ${error.candidates.join(', ')}`,\n        fix: 'Provide a longer prefix or use the full hash to disambiguate.',\n        meta: { input: error.input, candidates: error.candidates, grammar: error.grammar },\n      });\n    case 'wrong-grammar':\n      return errorRuntime(error.message, {\n        why: error.message,\n        fix: error.fix,\n        meta: { input: error.input, expectedGrammar: error.expectedGrammar },\n      });\n    case 'invalid-format':\n      return errorRuntime(`Invalid reference format: \"${error.input}\"`, {\n        why: error.reason,\n        fix: 'Provide a valid contract hash, ref name, or migration directory name.',\n        meta: { input: error.input },\n      });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAqFA,SAAgB,uBAAuB,OAAgD;CACrF,OAAO,aAAa,MAAM,SAAS;EACjC,KAAK,MAAM;EACX,KAAK,MAAM;EACX,MAAM;GAAE,MAAM,MAAM;GAAM,GAAI,MAAM,WAAW,EAAE;GAAG;EACrD,CAAC;;;;;;AAOJ,SAAgB,sBAAsB,OAA+C;CACnF,QAAQ,MAAM,MAAd;EACE,KAAK,aACH,OAAO,aAAa,eAAe,MAAM,QAAQ,eAAe,MAAM,MAAM,IAAI;GAC9E,KAAK,MAAM,MAAM,QAAQ,aAAa,MAAM,MAAM;GAClD,KACE,MAAM,YAAY,aACd,0EACA;GACN,MAAM;IAAE,OAAO,MAAM;IAAO,SAAS,MAAM;IAAS;GACrD,CAAC;EACJ,KAAK,aACH,OAAO,aAAa,aAAa,MAAM,QAAQ,eAAe,MAAM,MAAM,IAAI;GAC5E,KAAK,IAAI,MAAM,MAAM,qBAAqB,MAAM,QAAQ,KAAK,MAAM,WAAW,KAAK,KAAK;GACxF,KAAK;GACL,MAAM;IAAE,OAAO,MAAM;IAAO,YAAY,MAAM;IAAY,SAAS,MAAM;IAAS;GACnF,CAAC;EACJ,KAAK,iBACH,OAAO,aAAa,MAAM,SAAS;GACjC,KAAK,MAAM;GACX,KAAK,MAAM;GACX,MAAM;IAAE,OAAO,MAAM;IAAO,iBAAiB,MAAM;IAAiB;GACrE,CAAC;EACJ,KAAK,kBACH,OAAO,aAAa,8BAA8B,MAAM,MAAM,IAAI;GAChE,KAAK,MAAM;GACX,KAAK;GACL,MAAM,EAAE,OAAO,MAAM,OAAO;GAC7B,CAAC"}