@prisma-next/migration-tools 0.4.0-dev.9 → 0.4.2

package/src/migration-base.ts

@@ -1,15 +1,15 @@
-import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { Contract } from '@prisma-next/contract/types';
 import type {
+  ControlStack,
   MigrationPlan,
   MigrationPlanOperation,
 } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { type } from 'arktype';
-import { dirname, join } from 'pathe';
 import { computeMigrationId } from './attestation';
-import type { MigrationManifest, MigrationOps } from './types';
+import type { MigrationHints, MigrationManifest, MigrationOps } from './types';
 
 export interface MigrationMeta {
   readonly from: string;
@@ -26,7 +26,7 @@ const MigrationMetaSchema = type({
 });
 
 /**
- * Base class for class-flow migrations.
+ * Base class for migrations.
  *
  * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the
  * runner can consume it directly via `targetId`, `operations`, `origin`, and
@@ -34,11 +34,29 @@ const MigrationMetaSchema = type({
  * every migration must implement — `migration.json` is required for a
  * migration to be valid.
  */
-export abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation>
-  implements MigrationPlan
+export abstract class Migration<
+  TOperation extends MigrationPlanOperation = MigrationPlanOperation,
+  TFamilyId extends string = string,
+  TTargetId extends string = string,
+> implements MigrationPlan
 {
   abstract readonly targetId: string;
 
+  /**
+   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).
+   *
+   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their
+   * adapter once per instance. Optional at the abstract level so unit tests can
+   * construct `Migration` instances purely for `operations` / `describe`
+   * assertions without needing a real stack; concrete subclasses that need the
+   * stack at runtime should narrow the parameter to required.
+   */
+  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;
+
+  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {
+    this.stack = stack;
+  }
+
   /**
    * Ordered list of operations this migration performs.
    *
@@ -66,54 +84,30 @@ export abstract class Migration<TOperation extends MigrationPlanOperation = Migr
   get destination(): { readonly storageHash: string } {
     return { storageHash: this.describe().to };
   }
+}
 
-  /**
-   * Entrypoint guard for migration files. When called at module scope,
-   * detects whether the file is being run directly (e.g. `node migration.ts`)
-   * and if so, serializes the migration plan to `ops.json` and
-   * `migration.json` in the same directory. When the file is imported by
-   * another module, this is a no-op.
-   *
-   * Usage (at module scope, after the class definition):
-   *
-   *     class MyMigration extends Migration { ... }
-   *     export default MyMigration;
-   *     Migration.run(import.meta.url, MyMigration);
-   */
-  static run(importMetaUrl: string, MigrationClass: new () => Migration): void {
-    if (!importMetaUrl) return;
-
-    const metaFilename = fileURLToPath(importMetaUrl);
-    const argv1 = process.argv[1];
-    if (!argv1) return;
-
-    let isEntrypoint: boolean;
-    try {
-      isEntrypoint = realpathSync(metaFilename) === realpathSync(argv1);
-    } catch {
-      return;
-    }
-    if (!isEntrypoint) return;
-
-    const args = process.argv.slice(2);
-
-    if (args.includes('--help')) {
-      printHelp();
-      return;
-    }
-
-    const dryRun = args.includes('--dry-run');
-    const migrationDir = dirname(metaFilename);
-
-    try {
-      serializeMigration(MigrationClass, migrationDir, dryRun);
-    } catch (err) {
-      process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-      process.exitCode = 1;
-    }
+/**
+ * Returns true when `import.meta.url` resolves to the same file that was
+ * invoked as the node entrypoint (`process.argv[1]`). Used by
+ * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when
+ * the migration module is being imported (e.g. by another script) rather
+ * than executed directly.
+ */
+export function isDirectEntrypoint(importMetaUrl: string): boolean {
+  const metaFilename = fileURLToPath(importMetaUrl);
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  try {
+    return realpathSync(metaFilename) === realpathSync(argv1);
+  } catch {
+    return false;
   }
 }
 
+export function printMigrationHelp(): void {
+  printHelp();
+}
+
 function printHelp(): void {
   process.stdout.write(
     [
@@ -128,10 +122,25 @@ function printHelp(): void {
 }
 
 /**
- * Build the attested manifest written by `Migration.run()`.
+ * In-memory artifacts produced from a `Migration` instance: the
+ * serialized `ops.json` body, the `migration.json` manifest object, and
+ * its serialized form. Returned by `buildMigrationArtifacts` so callers
+ * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can
+ * decide how to persist them — write to disk, print in dry-run, ship
+ * over the wire — without coupling artifact construction to file I/O.
+ */
+export interface MigrationArtifacts {
+  readonly opsJson: string;
+  readonly manifest: MigrationManifest;
+  readonly manifestJson: string;
+}
+
+/**
+ * Build the attested manifest from `describe()`-derived metadata, the
+ * operations list, and the previously-scaffolded manifest (if any).
  *
- * When a `migration.json` already exists in the directory (the common case:
- * the package was scaffolded by `migration plan`), preserve the contract
+ * When a `migration.json` already exists for this package (the common
+ * case: it was scaffolded by `migration plan`), preserve the contract
  * bookends, hints, labels, and `createdAt` set there — those fields are
  * owned by the CLI scaffolder, not the authored class. Only the
  * `describe()`-derived fields (`from`, `to`, `kind`) and the operations
@@ -140,19 +149,15 @@ function printHelp(): void {
  * schema-conformant manifest so the resulting package can still be read,
  * verified, and applied.
  *
- * In both cases the `migrationId` is recomputed against the current
- * manifest + ops so the on-disk artifacts are always fully attested — no
- * draft (`migrationId: null`) ever leaves this function.
+ * The `migrationId` is recomputed against the current manifest + ops so
+ * the on-disk artifacts are always fully attested.
  */
 function buildAttestedManifest(
-  migrationDir: string,
   meta: MigrationMeta,
   ops: MigrationOps,
+  existing: Partial<MigrationManifest> | null,
 ): MigrationManifest {
-  const existing = readExistingManifest(join(migrationDir, 'migration.json'));
-
-  const baseManifest: MigrationManifest = {
-    migrationId: null,
+  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
     from: meta.from,
     to: meta.to,
     kind: meta.kind ?? 'regular',
@@ -165,12 +170,7 @@ function buildAttestedManifest(
     // (everything else is stripped by `computeMigrationId`), and a real
     // contract bookend would only be available after `migration plan`.
     toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),
-    hints: existing?.hints ?? {
-      used: [],
-      applied: [],
-      plannerVersion: '2.0.0',
-      planningStrategy: 'class-based',
-    },
+    hints: normalizeHints(existing?.hints),
     ...ifDefined('authorship', existing?.authorship),
   };
 
@@ -178,52 +178,50 @@ function buildAttestedManifest(
   return { ...baseManifest, migrationId };
 }
 
-function readExistingManifest(manifestPath: string): Partial<MigrationManifest> | null {
-  let raw: string;
-  try {
-    raw = readFileSync(manifestPath, 'utf-8');
-  } catch {
-    return null;
-  }
-  try {
-    return JSON.parse(raw) as Partial<MigrationManifest>;
-  } catch {
-    return null;
-  }
+/**
+ * Project `existing.hints` down to the known `MigrationHints` shape, dropping
+ * any legacy keys that may linger in manifests scaffolded by older CLI
+ * versions (e.g. `planningStrategy`). Picking fields explicitly instead of
+ * spreading keeps refreshed `migration.json` files schema-clean regardless
+ * of what was on disk before.
+ */
+function normalizeHints(existing: MigrationHints | undefined): MigrationHints {
+  return {
+    used: existing?.used ?? [],
+    applied: existing?.applied ?? [],
+    plannerVersion: existing?.plannerVersion ?? '2.0.0',
+  };
 }
 
-function serializeMigration(
-  MigrationClass: new () => Migration,
-  migrationDir: string,
-  dryRun: boolean,
-): void {
-  const instance = new MigrationClass();
-
+/**
+ * Pure conversion from a `Migration` instance (plus the previously
+ * scaffolded manifest, when one exists on disk) to the in-memory
+ * artifacts that downstream tooling persists. Owns metadata validation,
+ * manifest synthesis/preservation, hint normalization, and the
+ * content-addressed `migrationId` computation, but performs no file I/O
+ * — callers handle reads (to source `existing`) and writes (to persist
+ * `opsJson` / `manifestJson`).
+ */
+export function buildMigrationArtifacts(
+  instance: Migration,
+  existing: Partial<MigrationManifest> | null,
+): MigrationArtifacts {
   const ops = instance.operations;
-
   if (!Array.isArray(ops)) {
     throw new Error('operations must be an array');
   }
 
-  const serializedOps = JSON.stringify(ops, null, 2);
-
   const rawMeta: unknown = instance.describe();
   const parsed = MigrationMetaSchema(rawMeta);
   if (parsed instanceof type.errors) {
     throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
   }
 
-  const manifest = buildAttestedManifest(migrationDir, parsed, ops);
-
-  if (dryRun) {
-    process.stdout.write(`--- migration.json ---\n${JSON.stringify(manifest, null, 2)}\n`);
-    process.stdout.write('--- ops.json ---\n');
-    process.stdout.write(`${serializedOps}\n`);
-    return;
-  }
+  const manifest = buildAttestedManifest(parsed, ops, existing);
 
-  writeFileSync(join(migrationDir, 'ops.json'), serializedOps);
-  writeFileSync(join(migrationDir, 'migration.json'), JSON.stringify(manifest, null, 2));
-
-  process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
+  return {
+    opsJson: JSON.stringify(ops, null, 2),
+    manifest,
+    manifestJson: JSON.stringify(manifest, null, 2),
+  };
 }

package/src/migration-ts.ts

@@ -1,17 +1,15 @@
 /**
  * Utilities for reading/writing `migration.ts` files.
  *
- * Rendering migration.ts source is now the target's responsibility — the CLI
- * obtains source strings either from a class-flow planner's
- * `plan.renderTypeScript()` or from a descriptor-flow target's
- * `migrations.renderDescriptorTypeScript(descriptors, context)`. The helper
- * here is limited to file I/O: writing the returned source with the right
- * executable bit, probing for existence, and evaluating legacy descriptor-
- * flow files.
+ * Rendering migration.ts source is the target's responsibility — the CLI
+ * obtains source strings from a planner's `plan.renderTypeScript()`. The
+ * helper here is limited to file I/O: writing the returned source with the
+ * right executable bit and probing for existence.
  */
 
 import { stat, writeFile } from 'node:fs/promises';
-import { join, resolve } from 'pathe';
+import { join } from 'pathe';
+import { format } from 'prettier';
 
 const MIGRATION_TS_FILE = 'migration.ts';
 
@@ -19,17 +17,36 @@ const MIGRATION_TS_FILE = 'migration.ts';
  * Writes a pre-rendered `migration.ts` source string to the given package
  * directory. If the source begins with a shebang, the file is written with
  * executable permissions (0o755) so it can be run directly via
- * `./migration.ts` by the authoring class's `Migration.run(...)` guard.
+ * `./migration.ts` — the rendered scaffold ends with
+ * `MigrationCLI.run(import.meta.url, M)` from
+ * `@prisma-next/cli/migration-cli` (re-exported by the postgres facade),
+ * which guards on the entrypoint and serializes when the file is the main
+ * module.
+ *
+ * The source is run through prettier before writing so migration renderers
+ * can produce structurally-correct but loosely-indented source and rely on
+ * a single canonical format on disk. Matches what `@prisma-next/emitter`
+ * already does for generated `contract.d.ts`.
  */
 export async function writeMigrationTs(packageDir: string, content: string): Promise<void> {
-  const isExecutable = content.startsWith('#!');
+  const formatted = await formatMigrationTsSource(content);
+  const isExecutable = formatted.startsWith('#!');
   await writeFile(
     join(packageDir, MIGRATION_TS_FILE),
-    content,
+    formatted,
     isExecutable ? { mode: 0o755 } : undefined,
   );
 }
 
+async function formatMigrationTsSource(source: string): Promise<string> {
+  return format(source, {
+    parser: 'typescript',
+    singleQuote: true,
+    semi: true,
+    printWidth: 100,
+  });
+}
+
 /**
  * Checks whether a migration.ts file exists in the package directory.
  */
@@ -41,42 +58,3 @@ export async function hasMigrationTs(packageDir: string): Promise<boolean> {
     return false;
   }
 }
-
-/**
- * Evaluates a descriptor-flow migration.ts file by loading it via native
- * Node import. Returns the result of calling the default export (expected
- * to be a function returning an array of operation descriptors).
- *
- * Class-flow migration.ts files use a different shape — their default
- * export is a class that extends `Migration` — and are evaluated by the
- * target's `emit` capability, not this helper.
- *
- * Requires Node ≥24 for native TypeScript support.
- */
-export async function evaluateMigrationTs(packageDir: string): Promise<readonly unknown[]> {
-  const filePath = resolve(join(packageDir, MIGRATION_TS_FILE));
-
-  try {
-    await stat(filePath);
-  } catch {
-    throw new Error(`migration.ts not found at "${filePath}"`);
-  }
-
-  const mod = (await import(filePath)) as { default?: unknown };
-
-  if (typeof mod.default !== 'function') {
-    throw new Error(
-      `migration.ts must export a default function returning an operation list. Got: ${typeof mod.default}`,
-    );
-  }
-
-  const result: unknown = mod.default();
-
-  if (!Array.isArray(result)) {
-    throw new Error(
-      `migration.ts default export must return an array of operations. Got: ${typeof result}`,
-    );
-  }
-
-  return result;
-}

package/src/queue.ts

@@ -0,0 +1,37 @@
+/**
+ * FIFO queue with amortised O(1) push and shift.
+ *
+ * Uses a head-index cursor over a backing array rather than
+ * `Array.prototype.shift()`, which is O(n) on V8. Intended for BFS-shaped
+ * traversals where the queue is drained in a single pass — it does not
+ * reclaim memory for already-shifted items, so it is not suitable for
+ * long-lived queues with many push/shift cycles.
+ */
+export class Queue<T> {
+  private readonly items: T[];
+  private head = 0;
+
+  constructor(initial: Iterable<T> = []) {
+    this.items = [...initial];
+  }
+
+  push(item: T): void {
+    this.items.push(item);
+  }
+
+  /**
+   * Remove and return the next item. Caller must check `isEmpty` first —
+   * shifting an empty queue throws.
+   */
+  shift(): T {
+    if (this.head >= this.items.length) {
+      throw new Error('Queue.shift called on empty queue');
+    }
+    // biome-ignore lint/style/noNonNullAssertion: bounds-checked on the line above
+    return this.items[this.head++]!;
+  }
+
+  get isEmpty(): boolean {
+    return this.head >= this.items.length;
+  }
+}

package/src/refs.ts

@@ -1,14 +1,19 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, rmdir, unlink, writeFile } from 'node:fs/promises';
 import { type } from 'arktype';
-import { dirname, join } from 'pathe';
+import { dirname, join, relative } from 'pathe';
 import {
+  errorInvalidRefFile,
   errorInvalidRefName,
-  errorInvalidRefs,
   errorInvalidRefValue,
   MigrationToolsError,
 } from './errors';
 
-export type Refs = Readonly<Record<string, string>>;
+export interface RefEntry {
+  readonly hash: string;
+  readonly invariants: readonly string[];
+}
+
+export type Refs = Readonly<Record<string, RefEntry>>;
 
 const REF_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\/[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
 const REF_VALUE_PATTERN = /^sha256:(empty|[0-9a-f]{64})$/;
@@ -25,22 +30,40 @@ export function validateRefValue(value: string): boolean {
   return REF_VALUE_PATTERN.test(value);
 }
 
-const RefsSchema = type('Record<string, string>').narrow((refs, ctx) => {
-  for (const [key, value] of Object.entries(refs)) {
-    if (!validateRefName(key)) return ctx.mustBe(`valid ref names (invalid: "${key}")`);
-    if (!validateRefValue(value))
-      return ctx.mustBe(`valid contract hashes (invalid value for "${key}": "${value}")`);
-  }
+const RefEntrySchema = type({
+  hash: 'string',
+  invariants: 'string[]',
+}).narrow((entry, ctx) => {
+  if (!validateRefValue(entry.hash))
+    return ctx.mustBe(`a valid contract hash (got "${entry.hash}")`);
   return true;
 });
 
-export async function readRefs(refsPath: string): Promise<Refs> {
+function refFilePath(refsDir: string, name: string): string {
+  return join(refsDir, `${name}.json`);
+}
+
+function refNameFromPath(refsDir: string, filePath: string): string {
+  const rel = relative(refsDir, filePath);
+  return rel.replace(/\.json$/, '');
+}
+
+export async function readRef(refsDir: string, name: string): Promise<RefEntry> {
+  if (!validateRefName(name)) {
+    throw errorInvalidRefName(name);
+  }
+
+  const filePath = refFilePath(refsDir, name);
   let raw: string;
   try {
-    raw = await readFile(refsPath, 'utf-8');
+    raw = await readFile(filePath, 'utf-8');
   } catch (error) {
     if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-      return {};
+      throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref "${name}"`, {
+        why: `No ref file found at "${filePath}".`,
+        fix: `Create the ref with: prisma-next migration ref set ${name} <hash>`,
+        details: { refName: name, filePath },
+      });
     }
     throw error;
   }
@@ -49,54 +72,142 @@ export async function readRefs(refsPath: string): Promise<Refs> {
   try {
     parsed = JSON.parse(raw);
   } catch {
-    throw errorInvalidRefs(refsPath, 'Failed to parse as JSON');
+    throw errorInvalidRefFile(filePath, 'Failed to parse as JSON');
   }
 
-  const result = RefsSchema(parsed);
+  const result = RefEntrySchema(parsed);
   if (result instanceof type.errors) {
-    throw errorInvalidRefs(refsPath, result.summary);
+    throw errorInvalidRefFile(filePath, result.summary);
   }
 
   return result;
 }
 
-export async function writeRefs(refsPath: string, refs: Refs): Promise<void> {
-  for (const [key, value] of Object.entries(refs)) {
-    if (!validateRefName(key)) {
-      throw errorInvalidRefName(key);
+export async function readRefs(refsDir: string): Promise<Refs> {
+  let entries: string[];
+  try {
+    entries = await readdir(refsDir, { recursive: true, encoding: 'utf-8' });
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+      return {};
+    }
+    throw error;
+  }
+
+  const jsonFiles = entries.filter((entry) => entry.endsWith('.json'));
+  const refs: Record<string, RefEntry> = {};
+
+  for (const jsonFile of jsonFiles) {
+    const filePath = join(refsDir, jsonFile);
+    const name = refNameFromPath(refsDir, filePath);
+
+    let raw: string;
+    try {
+      raw = await readFile(filePath, 'utf-8');
+    } catch (error) {
+      // Tolerate the TOCTOU race between `readdir` and `readFile` (ENOENT) and
+      // benign EISDIR if a directory happens to end in `.json`. Anything else
+      // (EACCES, EIO, EMFILE, …) is a real failure and propagates so the CLI
+      // surfaces it rather than silently dropping the ref.
+      const code = error instanceof Error ? (error as { code?: string }).code : undefined;
+      if (code === 'ENOENT' || code === 'EISDIR') {
+        continue;
+      }
+      throw error;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw errorInvalidRefFile(filePath, 'Failed to parse as JSON');
     }
-    if (!validateRefValue(value)) {
-      throw errorInvalidRefValue(value);
+
+    const result = RefEntrySchema(parsed);
+    if (result instanceof type.errors) {
+      throw errorInvalidRefFile(filePath, result.summary);
     }
+
+    refs[name] = result;
   }
 
-  const sorted = Object.fromEntries(Object.entries(refs).sort(([a], [b]) => a.localeCompare(b)));
+  return refs;
+}
+
+export async function writeRef(refsDir: string, name: string, entry: RefEntry): Promise<void> {
+  if (!validateRefName(name)) {
+    throw errorInvalidRefName(name);
+  }
+  if (!validateRefValue(entry.hash)) {
+    throw errorInvalidRefValue(entry.hash);
+  }
 
-  const dir = dirname(refsPath);
+  const filePath = refFilePath(refsDir, name);
+  const dir = dirname(filePath);
   await mkdir(dir, { recursive: true });
 
-  const tmpPath = join(dir, `.refs.json.${Date.now()}.tmp`);
-  await writeFile(tmpPath, `${JSON.stringify(sorted, null, 2)}\n`);
-  await rename(tmpPath, refsPath);
+  const tmpPath = join(dir, `.${name.split('/').pop()}.json.${Date.now()}.tmp`);
+  await writeFile(
+    tmpPath,
+    `${JSON.stringify({ hash: entry.hash, invariants: [...entry.invariants] }, null, 2)}\n`,
+  );
+  await rename(tmpPath, filePath);
 }
 
-export function resolveRef(refs: Refs, name: string): string {
+export async function deleteRef(refsDir: string, name: string): Promise<void> {
   if (!validateRefName(name)) {
     throw errorInvalidRefName(name);
   }
 
-  const hash = refs[name];
-  if (hash === undefined) {
+  const filePath = refFilePath(refsDir, name);
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+      throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref "${name}"`, {
+        why: `No ref file found at "${filePath}".`,
+        fix: 'Run `prisma-next migration ref list` to see available refs.',
+        details: { refName: name, filePath },
+      });
+    }
+    throw error;
+  }
+
+  // Clean empty parent directories up to refsDir. Stop walking on the expected
+  // "directory has siblings" signal (ENOTEMPTY on Linux, EEXIST on some BSDs)
+  // and on ENOENT (concurrent removal). Anything else (EACCES, EIO, …) is a
+  // real failure and propagates.
+  let dir = dirname(filePath);
+  while (dir !== refsDir && dir.startsWith(refsDir)) {
+    try {
+      await rmdir(dir);
+      dir = dirname(dir);
+    } catch (error) {
+      const code = error instanceof Error ? (error as { code?: string }).code : undefined;
+      if (code === 'ENOTEMPTY' || code === 'EEXIST' || code === 'ENOENT') {
+        break;
+      }
+      throw error;
+    }
+  }
+}
+
+export function resolveRef(refs: Refs, name: string): RefEntry {
+  if (!validateRefName(name)) {
+    throw errorInvalidRefName(name);
+  }
+
+  // Object.hasOwn gate: plain-object `refs` would otherwise let
+  // `refs['constructor']` return Object.prototype.constructor and bypass the
+  // UNKNOWN_REF throw. validateRefName accepts `"constructor"` as a name shape.
+  if (!Object.hasOwn(refs, name)) {
     throw new MigrationToolsError('MIGRATION.UNKNOWN_REF', `Unknown ref "${name}"`, {
-      why: `No ref named "${name}" exists in refs.json.`,
-      fix: `Available refs: ${Object.keys(refs).join(', ') || '(none)'}. Create a ref with: set the "${name}" key in migrations/refs.json.`,
+      why: `No ref named "${name}" exists.`,
+      fix: `Available refs: ${Object.keys(refs).join(', ') || '(none)'}. Create a ref with: prisma-next migration ref set ${name} <hash>`,
       details: { refName: name, availableRefs: Object.keys(refs) },
     });
   }
 
-  if (!validateRefValue(hash)) {
-    throw errorInvalidRefValue(hash);
-  }
-
-  return hash;
+  // biome-ignore lint/style/noNonNullAssertion: Object.hasOwn gate above guarantees this is defined
+  return refs[name]!;
 }