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

package/src/commands/migration-apply.ts

@@ -1,9 +1,8 @@
-import { verifyMigrationBundle } from '@prisma-next/migration-tools/attestation';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { findPathWithDecision } from '@prisma-next/migration-tools/dag';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { findPathWithDecision } from '@prisma-next/migration-tools/migration-graph';
+import type { MigrationPackage } from '@prisma-next/migration-tools/package';
 import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
-import type { MigrationBundle } from '@prisma-next/migration-tools/types';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 
@@ -18,11 +17,11 @@ import {
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
+  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadAllBundles,
-  type MigrationBundleSet,
+  loadMigrationPackages,
   maskConnectionUrl,
   readContractEnvelope,
   resolveMigrationPaths,
@@ -64,7 +63,7 @@ export interface MigrationApplyResult {
     readonly refName?: string;
     readonly selectedPath: readonly {
       readonly dirName: string;
-      readonly migrationId: string;
+      readonly migrationHash: string;
       readonly from: string;
       readonly to: string;
     }[];
@@ -74,19 +73,6 @@ export interface MigrationApplyResult {
   };
 }
 
-function mapMigrationToolsError(error: unknown): CliStructuredErrorType {
-  if (MigrationToolsError.is(error)) {
-    return errorRuntime(error.message, {
-      why: error.why,
-      fix: error.fix,
-      meta: { code: error.code, ...(error.details ?? {}) },
-    });
-  }
-  return errorUnexpected(error instanceof Error ? error.message : String(error), {
-    why: `Unexpected error during migration apply: ${error instanceof Error ? error.message : String(error)}`,
-  });
-}
-
 function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType {
   return errorRuntime(failure.summary, {
     why: failure.why ?? 'Migration runner failed',
@@ -95,12 +81,12 @@ function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType
   });
 }
 
-function packageToStep(pkg: MigrationBundle): MigrationApplyStep {
+function packageToStep(pkg: MigrationPackage): MigrationApplyStep {
   return {
     dirName: pkg.dirName,
-    from: pkg.manifest.from,
-    to: pkg.manifest.to,
-    toContract: pkg.manifest.toContract,
+    from: pkg.metadata.from,
+    to: pkg.metadata.to,
+    toContract: pkg.metadata.toContract,
     operations: pkg.ops,
   };
 }
@@ -112,7 +98,7 @@ async function executeMigrationApplyCommand(
   startTime: number,
 ): Promise<Result<MigrationApplyResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, migrationsRelative, refsPath } = resolveMigrationPaths(
+  const { configPath, migrationsDir, migrationsRelative, refsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -149,8 +135,8 @@ async function executeMigrationApplyCommand(
   if (options.ref) {
     refName = options.ref;
     try {
-      const refs = await readRefs(refsPath);
-      destinationHash = resolveRef(refs, refName);
+      const refs = await readRefs(refsDir);
+      destinationHash = resolveRef(refs, refName).hash;
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -196,9 +182,9 @@ async function executeMigrationApplyCommand(
   }
 
   // Read migrations and build migration chain model (offline — no DB needed)
-  let migrations: MigrationBundleSet;
+  let migrations: Awaited<ReturnType<typeof loadMigrationPackages>>;
   try {
-    migrations = await loadAllBundles(migrationsDir);
+    migrations = await loadMigrationPackages(migrationsDir);
   } catch (error) {
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
@@ -206,27 +192,6 @@ async function executeMigrationApplyCommand(
     throw error;
   }
 
-  // Defense in depth: re-hash every bundle and confirm the recorded
-  // `migrationId` matches the on-disk `(manifest, ops)`. Catches FS
-  // corruption, partial writes, and post-emit hand edits before we
-  // start touching the database.
-  for (const bundle of migrations.bundles) {
-    const verified = verifyMigrationBundle(bundle);
-    if (!verified.ok) {
-      return notOk(
-        errorRuntime(`Migration package is corrupt: ${bundle.dirName}`, {
-          why: `Stored migrationId "${verified.storedMigrationId}" does not match the recomputed hash "${verified.computedMigrationId}" for ${migrationsRelative}/${bundle.dirName}. The migration.json or ops.json has been edited or partially written since emit.`,
-          fix: `Re-emit the package by running \`node "${migrationsRelative}/${bundle.dirName}/migration.ts"\`, or restore the directory from version control.`,
-          meta: {
-            dirName: bundle.dirName,
-            storedMigrationId: verified.storedMigrationId,
-            computedMigrationId: verified.computedMigrationId,
-          },
-        }),
-      );
-    }
-  }
-
   const client = createControlClient({
     family: config.family,
     target: config.target,

package/src/commands/migration-new.ts

@@ -12,31 +12,36 @@ import { readFileSync } from 'node:fs';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { createControlStack } from '@prisma-next/framework-components/control';
-import { computeMigrationId } from '@prisma-next/migration-tools/attestation';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { findLatestMigration, reconstructGraph } from '@prisma-next/migration-tools/dag';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import {
   copyFilesWithRename,
   formatMigrationDirName,
   readMigrationsDir,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
+import {
+  findLatestMigration,
+  reconstructGraph,
+} from '@prisma-next/migration-tools/migration-graph';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
-import type { MigrationManifest } from '@prisma-next/migration-tools/types';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { join, relative, resolve } from 'pathe';
+import { join, relative } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   CliStructuredError,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
+  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
   getTargetMigrations,
+  resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
@@ -68,11 +73,7 @@ async function executeMigrationNewCommand(
   const config = await loadConfig(options.config);
   const { migrationsDir, migrationsRelative } = resolveMigrationPaths(options.config, config);
 
-  const contractPath = config.contract?.output ?? 'contract.json';
-  const contractPathAbsolute = resolve(
-    options.config ? resolve(options.config, '..') : process.cwd(),
-    contractPath,
-  );
+  const contractPathAbsolute = resolveContractPath(config);
 
   let contractJsonContent: string;
   try {
@@ -126,7 +127,7 @@ async function executeMigrationNewCommand(
       const graph = reconstructGraph(packages);
 
       if (options.from) {
-        const match = packages.find((p) => p.manifest.to.startsWith(options.from!));
+        const match = packages.find((p) => p.metadata.to.startsWith(options.from!));
         if (!match) {
           return notOk(
             errorRuntime('Starting contract not found', {
@@ -135,18 +136,18 @@ async function executeMigrationNewCommand(
             }),
           );
         }
-        fromHash = match.manifest.to;
-        fromContract = match.manifest.toContract;
+        fromHash = match.metadata.to;
+        fromContract = match.metadata.toContract;
         fromContractSourceDir = match.dirPath;
       } else {
         const latestMigration = findLatestMigration(graph);
         if (latestMigration) {
           fromHash = latestMigration.to;
           const leafPkg = packages.find(
-            (p) => p.manifest.migrationId === latestMigration.migrationId,
+            (p) => p.metadata.migrationHash === latestMigration.migrationHash,
           );
           if (leafPkg) {
-            fromContract = leafPkg.manifest.toContract;
+            fromContract = leafPkg.metadata.toContract;
             fromContractSourceDir = leafPkg.dirPath;
           }
         }
@@ -154,13 +155,7 @@ async function executeMigrationNewCommand(
     }
   } catch (error) {
     if (MigrationToolsError.is(error)) {
-      return notOk(
-        errorRuntime(error.message, {
-          why: error.why,
-          fix: error.fix,
-          meta: { code: error.code },
-        }),
-      );
+      return notOk(mapMigrationToolsError(error));
     }
     throw error;
   }
@@ -181,9 +176,9 @@ async function executeMigrationNewCommand(
 
   // `migration new` scaffolds an empty `migration.ts` for the user to
   // fill, so we attest over `ops: []`. Re-running self-emit after the
-  // user adds operations will produce a different `migrationId` (over
+  // user adds operations will produce a different `migrationHash` (over
   // the real ops). This is intentional — there is no on-disk draft.
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: fromHash,
     to: toStorageHash,
     kind: 'regular',
@@ -197,9 +192,9 @@ async function executeMigrationNewCommand(
     labels: [],
     createdAt: timestamp.toISOString(),
   };
-  const manifest: MigrationManifest = {
-    ...baseManifest,
-    migrationId: computeMigrationId(baseManifest, []),
+  const metadata: MigrationMetadata = {
+    ...baseMetadata,
+    migrationHash: computeMigrationHash(baseMetadata, []),
   };
 
   const migrations = getTargetMigrations(config.target);
@@ -218,7 +213,7 @@ async function executeMigrationNewCommand(
       ...(config.extensionPacks ?? []),
     ]);
 
-    await writeMigrationPackage(packageDir, manifest, []);
+    await writeMigrationPackage(packageDir, metadata, []);
     const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
     await copyFilesWithRename(packageDir, [
       { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },

package/src/commands/migration-plan.ts

@@ -5,16 +5,17 @@ import {
   createControlStack,
   type MigrationPlanOperation,
 } from '@prisma-next/framework-components/control';
-import { computeMigrationId } from '@prisma-next/migration-tools/attestation';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { findLatestMigration } from '@prisma-next/migration-tools/dag';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import {
   copyFilesWithRename,
   formatMigrationDirName,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
+import { findLatestMigration } from '@prisma-next/migration-tools/migration-graph';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
-import { type MigrationManifest, MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { join, relative } from 'pathe';
@@ -29,11 +30,12 @@ import {
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
+  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
   getTargetMigrations,
-  loadAllBundles,
+  loadMigrationPackages,
   resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
@@ -76,22 +78,6 @@ export interface MigrationPlanResult {
   };
 }
 
-function mapMigrationToolsError(error: unknown): CliStructuredError {
-  if (CliStructuredError.is(error)) {
-    return error;
-  }
-  if (MigrationToolsError.is(error)) {
-    return errorRuntime(error.message, {
-      why: error.why,
-      fix: error.fix,
-      meta: { code: error.code, ...(error.details ?? {}) },
-    });
-  }
-  return errorUnexpected(error instanceof Error ? error.message : String(error), {
-    why: `Unexpected error during migration plan: ${error instanceof Error ? error.message : String(error)}`,
-  });
-}
-
 async function executeMigrationPlanCommand(
   options: MigrationPlanOptions,
   flags: GlobalFlags,
@@ -177,7 +163,7 @@ async function executeMigrationPlanCommand(
   let fromContractSourceDir: string | null = null;
 
   try {
-    const { bundles, graph } = await loadAllBundles(migrationsDir);
+    const { bundles, graph } = await loadMigrationPackages(migrationsDir);
 
     if (options.from) {
       const resolved = resolveBundleByPrefix(bundles, options.from);
@@ -195,16 +181,18 @@ async function executeMigrationPlanCommand(
               }),
         );
       }
-      fromHash = resolved.value.manifest.to;
-      fromContract = resolved.value.manifest.toContract;
+      fromHash = resolved.value.metadata.to;
+      fromContract = resolved.value.metadata.toContract;
       fromContractSourceDir = resolved.value.dirPath;
     } else {
       const latestMigration = findLatestMigration(graph);
       if (latestMigration) {
         fromHash = latestMigration.to;
-        const leafPkg = bundles.find((p) => p.manifest.migrationId === latestMigration.migrationId);
+        const leafPkg = bundles.find(
+          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
+        );
         if (leafPkg) {
-          fromContract = leafPkg.manifest.toContract;
+          fromContract = leafPkg.metadata.toContract;
           fromContractSourceDir = leafPkg.dirPath;
         }
       }
@@ -213,7 +201,16 @@ async function executeMigrationPlanCommand(
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
     }
-    throw error;
+    // Wrap unexpected (non-MigrationToolsError) failures from the migration
+    // load phase in a structured CLI envelope. Letting them throw would
+    // bypass `handleResult()` and crash the command — see CLI structured-
+    // errors guideline (CliStructuredError + Result pattern).
+    const message = error instanceof Error ? error.message : String(error);
+    return notOk(
+      errorUnexpected(message, {
+        why: `Unexpected error while loading migrations: ${message}`,
+      }),
+    );
   }
 
   // Check for no-op (same hash means no changes)
@@ -251,7 +248,7 @@ async function executeMigrationPlanCommand(
   const dirName = formatMigrationDirName(timestamp, slug);
   const packageDir = join(migrationsDir, dirName);
 
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: fromHash,
     to: toStorageHash,
     kind: 'regular',
@@ -320,18 +317,18 @@ async function executeMigrationPlanCommand(
 
     const migrationTsContent = plannerResult.plan.renderTypeScript();
 
-    // Always-attest: compute migrationId over (manifest, ops). When
-    // placeholders blocked lowering, ops is `[]` and the id hashes over
-    // the empty list — re-emitting after the user fills the placeholder
-    // produces a different id (over the real ops). This is intentional;
+    // Always-attest: compute migrationHash over (metadata, ops). When
+    // placeholders blocked lowering, ops is `[]` and the hash is computed
+    // over the empty list — re-emitting after the user fills the placeholder
+    // produces a different hash (over the real ops). This is intentional;
     // there is no on-disk "draft" state.
     const opsForWrite = hasPlaceholders ? [] : plannedOps;
-    const manifest: MigrationManifest = {
-      ...baseManifest,
-      migrationId: computeMigrationId(baseManifest, opsForWrite),
+    const metadata: MigrationMetadata = {
+      ...baseMetadata,
+      migrationHash: computeMigrationHash(baseMetadata, opsForWrite),
     };
 
-    await writeMigrationPackage(packageDir, manifest, opsForWrite);
+    await writeMigrationPackage(packageDir, metadata, opsForWrite);
     const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
     await copyFilesWithRename(packageDir, [
       { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
@@ -382,7 +379,18 @@ async function executeMigrationPlanCommand(
     };
     return ok(result);
   } catch (error) {
-    return notOk(mapMigrationToolsError(error));
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return notOk(
+      errorUnexpected(message, {
+        why: `Unexpected error during migration plan: ${message}`,
+      }),
+    );
   }
 }
 
@@ -489,7 +497,7 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
 
   lines.push('');
   lines.push(
-    `Next: ${green_(`node ${result.dir ?? '<dir>'}/migration.ts`)} to emit ops.json and attest migrationId before running ${green_('prisma-next migration apply')}.`,
+    `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migration apply')}.`,
   );
 
   if (result.sql && result.sql.length > 0) {
@@ -517,24 +525,27 @@ export type PrefixResolutionFailure =
   | { reason: 'not-found' };
 
 /**
- * Resolve a migration bundle by exact hash or prefix match.
+ * Resolve a migration package by **target contract hash** (`metadata.to`)
+ * using exact match or prefix match.
  *
+ * Note: matches `metadata.to` (the contract hash this migration produces),
+ * not `metadata.migrationHash` (the package's content-addressed identity).
  * Tries exact match first, then prefix match (auto-prepending `sha256:` when
- * the needle omits the scheme). Returns the matched bundle on success, or a
+ * the needle omits the scheme). Returns the matched package on success, or a
  * discriminated failure indicating whether the prefix was ambiguous or simply
  * not found.
  *
  * @internal Exported for testing only.
  */
-export function resolveBundleByPrefix<T extends { manifest: { to: string } }>(
+export function resolveBundleByPrefix<T extends { metadata: { to: string } }>(
   bundles: readonly T[],
   needle: string,
 ): Result<T, PrefixResolutionFailure> {
-  const exact = bundles.find((p) => p.manifest.to === needle);
+  const exact = bundles.find((p) => p.metadata.to === needle);
   if (exact) return ok(exact);
 
   const prefixWithScheme = needle.startsWith('sha256:') ? needle : `sha256:${needle}`;
-  const candidates = bundles.filter((p) => p.manifest.to.startsWith(prefixWithScheme));
+  const candidates = bundles.filter((p) => p.metadata.to.startsWith(prefixWithScheme));
 
   if (candidates.length === 1) return ok(candidates[0]!);
   if (candidates.length > 1) return notOk({ reason: 'ambiguous', count: candidates.length });

package/src/commands/migration-ref.ts

@@ -1,17 +1,27 @@
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import {
+  deleteRef,
+  readRef,
   readRefs,
-  resolveRef,
   validateRefName,
   validateRefValue,
-  writeRefs,
+  writeRef,
 } from '@prisma-next/migration-tools/refs';
-import { MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
-import { CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
-import { addGlobalOptions, setCommandDescriptions } from '../utils/command-helpers';
+import {
+  CliStructuredError,
+  errorRuntime,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+} from '../utils/command-helpers';
 import { formatCommandHelp } from '../utils/formatters/help';
 import { parseGlobalFlags } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
@@ -21,12 +31,14 @@ interface RefSetResult {
   readonly ok: true;
   readonly ref: string;
   readonly hash: string;
+  readonly invariants: readonly string[];
 }
 
 interface RefGetResult {
   readonly ok: true;
   readonly ref: string;
   readonly hash: string;
+  readonly invariants: readonly string[];
 }
 
 interface RefDeleteResult {
@@ -37,21 +49,12 @@ interface RefDeleteResult {
 
 interface RefListResult {
   readonly ok: true;
-  readonly refs: Record<string, string>;
-}
-
-function resolveRefsPath(configPath?: string, config?: { migrations?: { dir?: string } }): string {
-  const base = configPath ? resolve(configPath, '..') : process.cwd();
-  return resolve(base, config?.migrations?.dir ?? 'migrations', 'refs.json');
+  readonly refs: Record<string, RefEntry>;
 }
 
 function mapError(error: unknown): CliStructuredError {
   if (MigrationToolsError.is(error)) {
-    return errorRuntime(error.message, {
-      why: error.why,
-      fix: error.fix,
-      meta: { code: error.code },
-    });
+    return mapMigrationToolsError(error);
   }
   return errorUnexpected(error instanceof Error ? error.message : String(error));
 }
@@ -70,13 +73,6 @@ function cliErrorInvalidRefValue(hash: string): CliStructuredError {
   });
 }
 
-function errorRefNotFound(name: string): CliStructuredError {
-  return errorRuntime(`Ref "${name}" does not exist`, {
-    why: `No ref named "${name}" found in refs.json`,
-    fix: `Run \`prisma-next migration ref list\` to see available refs, or \`prisma-next migration ref set ${name} <hash>\` to create it`,
-  });
-}
-
 async function executeRefSetCommand(
   name: string,
   hash: string,
@@ -91,11 +87,10 @@ async function executeRefSetCommand(
 
   try {
     const config = await loadConfig(options.config);
-    const refsPath = resolveRefsPath(options.config, config);
-    const refs = await readRefs(refsPath);
-    const updated = { ...refs, [name]: hash };
-    await writeRefs(refsPath, updated);
-    return ok({ ok: true as const, ref: name, hash });
+    const { refsDir } = resolveMigrationPaths(options.config, config);
+    const entry: RefEntry = { hash, invariants: [] };
+    await writeRef(refsDir, name, entry);
+    return ok({ ok: true as const, ref: name, hash, invariants: [] });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
     return notOk(mapError(error));
@@ -108,10 +103,9 @@ async function executeRefGetCommand(
 ): Promise<Result<RefGetResult, CliStructuredError>> {
   try {
     const config = await loadConfig(options.config);
-    const refsPath = resolveRefsPath(options.config, config);
-    const refs = await readRefs(refsPath);
-    const hash = resolveRef(refs, name);
-    return ok({ ok: true as const, ref: name, hash });
+    const { refsDir } = resolveMigrationPaths(options.config, config);
+    const entry = await readRef(refsDir, name);
+    return ok({ ok: true as const, ref: name, hash: entry.hash, invariants: entry.invariants });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
     return notOk(mapError(error));
@@ -124,13 +118,8 @@ async function executeRefDeleteCommand(
 ): Promise<Result<RefDeleteResult, CliStructuredError>> {
   try {
     const config = await loadConfig(options.config);
-    const refsPath = resolveRefsPath(options.config, config);
-    const refs = await readRefs(refsPath);
-    if (!Object.hasOwn(refs, name)) {
-      return notOk(errorRefNotFound(name));
-    }
-    const { [name]: _, ...remaining } = refs;
-    await writeRefs(refsPath, remaining);
+    const { refsDir } = resolveMigrationPaths(options.config, config);
+    await deleteRef(refsDir, name);
     return ok({ ok: true as const, ref: name, deleted: true as const });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -143,8 +132,8 @@ async function executeRefListCommand(options: {
 }): Promise<Result<RefListResult, CliStructuredError>> {
   try {
     const config = await loadConfig(options.config);
-    const refsPath = resolveRefsPath(options.config, config);
-    const refs = await readRefs(refsPath);
+    const { refsDir } = resolveMigrationPaths(options.config, config);
+    const refs = await readRefs(refsDir);
     return ok({ ok: true as const, refs });
   } catch (error) {
     if (error instanceof CliStructuredError) return notOk(error);
@@ -157,7 +146,7 @@ function createRefSetCommand(): Command {
   setCommandDescriptions(
     command,
     'Set a ref to a contract hash',
-    'Sets a named ref to point to a contract hash in migrations/refs.json.',
+    'Sets a named ref to point to a contract hash in migrations/refs/.',
   );
   addGlobalOptions(command)
     .argument('<name>', 'Ref name (e.g., staging, production)')
@@ -190,7 +179,7 @@ function createRefGetCommand(): Command {
   setCommandDescriptions(
     command,
     'Get the hash for a ref',
-    'Reads a named ref from migrations/refs.json and prints its contract hash.',
+    'Reads a named ref from migrations/refs/ and prints its contract hash.',
   );
   addGlobalOptions(command)
     .argument('<name>', 'Ref name to look up')
@@ -218,7 +207,7 @@ function createRefGetCommand(): Command {
 
 function createRefDeleteCommand(): Command {
   const command = new Command('delete');
-  setCommandDescriptions(command, 'Delete a ref', 'Removes a named ref from migrations/refs.json.');
+  setCommandDescriptions(command, 'Delete a ref', 'Removes a named ref from migrations/refs/.');
   addGlobalOptions(command)
     .argument('<name>', 'Ref name to delete')
     .option('--config <path>', 'Path to prisma-next.config.ts')
@@ -245,11 +234,7 @@ function createRefDeleteCommand(): Command {
 
 function createRefListCommand(): Command {
   const command = new Command('list');
-  setCommandDescriptions(
-    command,
-    'List all refs',
-    'Lists all named refs from migrations/refs.json.',
-  );
+  setCommandDescriptions(command, 'List all refs', 'Lists all named refs from migrations/refs/.');
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: { config?: string; json?: string | boolean; quiet?: boolean }) => {
@@ -264,8 +249,10 @@ function createRefListCommand(): Command {
           if (entries.length === 0) {
             ui.output('No refs defined');
           } else {
-            for (const [refName, hash] of entries) {
-              ui.output(`${refName} → ${hash}`);
+            for (const [refName, entry] of entries) {
+              const invariantsSuffix =
+                entry.invariants.length > 0 ? ` [invariants: ${entry.invariants.join(', ')}]` : '';
+              ui.output(`${refName} → ${entry.hash}${invariantsSuffix}`);
             }
           }
         }
@@ -282,7 +269,6 @@ export {
   executeRefListCommand,
   cliErrorInvalidRefName,
   cliErrorInvalidRefValue,
-  errorRefNotFound,
 };
 
 export function createMigrationRefCommand(): Command {
@@ -290,7 +276,7 @@ export function createMigrationRefCommand(): Command {
   setCommandDescriptions(
     command,
     'Manage migration refs',
-    'Manage named refs in migrations/refs.json. Refs map logical environment\n' +
+    'Manage named refs in migrations/refs/. Refs map logical environment\n' +
       'names (e.g., staging, production) to contract hashes.',
   );
   addGlobalOptions(command).configureHelp({