@prisma-next/cli 0.11.0-dev.3 → 0.11.0-dev.30

package/src/commands/ref.ts

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

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

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

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

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

package/src/control-api/types.ts

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

package/src/utils/cli-errors.ts

@@ -28,6 +28,7 @@ import {
 import { errorRuntime } from '@prisma-next/errors/execution';
 import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';
+import type { MigrationApplyFailure } from '../control-api/types';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -68,6 +69,229 @@ 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,
+    },
+  });
+}
+
+/**
+ * `--space <id>` was given a value that doesn't satisfy the contract-space
+ * naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before
+ * any fs work — the input is syntactically rejected the same way an on-disk
+ * directory with that name would be skipped by the enumerator.
+ */
+export function errorInvalidSpaceId(spaceId: string): CliStructuredError {
+  return errorRuntime(`Invalid contract space id: ${spaceId}`, {
+    why: 'Contract space ids must match [a-z][a-z0-9_-]{0,63} (lowercase, starts with a letter, max 64 characters — the rule applied to every on-disk space directory).',
+    fix: 'Pass a space id that matches the directory naming rule, or omit --space to list every space.',
+    meta: {
+      code: 'MIGRATION.INVALID_SPACE_ID',
+      spaceId,
+    },
+  });
+}
+
+/**
+ * `migration list --space <id>` was given a contract-space id that has no
+ * directory under `migrations/`. Distinct from "the space exists but is
+ * empty" — that path renders the empty-state line and exits 0 per the
+ * slice spec § Empty-state. This error fires only when `<projectMigrationsDir>/<spaceId>`
+ * does not exist on disk.
+ *
+ * `availableSpaces` lists the contract-space directory names actually
+ * present, sorted lex-asc, so the diagnostic can suggest a near match
+ * without making the user reach for `ls`.
+ */
+export function errorSpaceNotFound(
+  spaceId: string,
+  availableSpaces: readonly string[],
+): CliStructuredError {
+  const availableList =
+    availableSpaces.length > 0
+      ? availableSpaces.join(', ')
+      : '(none — no contract spaces on disk yet)';
+  const fix =
+    availableSpaces.length > 0
+      ? `Pick one of: ${availableList}. Run \`prisma-next migration list\` (no --space) to see every space's migrations.`
+      : 'Author a migration with `prisma-next migration new` to create the first contract-space directory.';
+  return errorRuntime(`Unknown contract space: ${spaceId}`, {
+    why: `No directory named "${spaceId}" exists under the migrations root.`,
+    fix,
+    meta: {
+      code: 'MIGRATION.SPACE_NOT_FOUND',
+      spaceId,
+      availableSpaces: [...availableSpaces],
+    },
+  });
+}
+
+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/migration-list-render.ts

@@ -0,0 +1,171 @@
+import type {
+  MigrationListEntry,
+  MigrationListResult,
+} from '@prisma-next/migration-tools/migration-list-types';
+
+export type {
+  MigrationListEntry,
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from '@prisma-next/migration-tools/migration-list-types';
+
+const HASH_WIDTH = 7;
+const EMPTY_SOURCE = '∅';
+const SELF_EDGE_GLYPH = '⟲';
+const FORWARD_EDGE_GLYPH = '→';
+const DECORATION_PREFIX = '  ';
+
+/**
+ * Semantic styler for `migration list` output tokens. Token-typed so
+ * the renderer composes presentation-neutral fragments and the styler
+ * decides how each token kind is decorated (ANSI codes, plain text,
+ * etc.). The renderer pads with raw spaces *outside* styled tokens so
+ * visible column widths stay stable regardless of what the styler
+ * emits — adding ANSI escape sequences never disturbs alignment.
+ *
+ * `invariants` and `refs` receive the underlying string arrays rather
+ * than a pre-joined string so per-element styling (e.g. distinguishing
+ * the live-DB `db` marker from user-named refs) is possible without
+ * having to re-parse a joined block.
+ */
+export interface MigrationListStyler {
+  dirName(text: string): string;
+  sourceHash(text: string): string;
+  destHash(text: string): string;
+  glyph(text: string): string;
+  invariants(ids: readonly string[]): string;
+  refs(names: readonly string[]): string;
+  spaceHeading(text: string): string;
+  summary(text: string): string;
+  emptyState(text: string): string;
+}
+
+export const IDENTITY_MIGRATION_LIST_STYLER: MigrationListStyler = {
+  dirName: (text) => text,
+  sourceHash: (text) => text,
+  destHash: (text) => text,
+  glyph: (text) => text,
+  invariants: (ids) => `{${ids.join(', ')}}`,
+  refs: (names) => `(${names.join(', ')})`,
+  spaceHeading: (text) => text,
+  summary: (text) => text,
+  emptyState: (text) => text,
+};
+
+function abbreviateContractHash(hash: string): string {
+  const stripped = hash.startsWith('sha256:') ? hash.slice(7) : hash;
+  return stripped.slice(0, HASH_WIDTH);
+}
+
+function formatSourceColumn(from: string | null, style: MigrationListStyler): string {
+  if (from === null) {
+    return style.glyph(EMPTY_SOURCE) + ' '.repeat(HASH_WIDTH - EMPTY_SOURCE.length);
+  }
+  return style.sourceHash(abbreviateContractHash(from));
+}
+
+function formatDestColumn(from: string | null, to: string, style: MigrationListStyler): string {
+  if (from !== null && from === to) {
+    return ' '.repeat(HASH_WIDTH);
+  }
+  return style.destHash(abbreviateContractHash(to));
+}
+
+function formatArrowGlyph(from: string | null, to: string, style: MigrationListStyler): string {
+  return style.glyph(from !== null && from === to ? SELF_EDGE_GLYPH : FORWARD_EDGE_GLYPH);
+}
+
+function formatDecorations(
+  providedInvariants: readonly string[],
+  refs: readonly string[],
+  style: MigrationListStyler,
+): string {
+  const blocks: string[] = [];
+  if (providedInvariants.length > 0) {
+    blocks.push(style.invariants(providedInvariants));
+  }
+  if (refs.length > 0) {
+    blocks.push(style.refs(refs));
+  }
+  if (blocks.length === 0) return '';
+  return `${DECORATION_PREFIX}${blocks.join(' ')}`;
+}
+
+function formatMigrationRow(
+  migration: MigrationListEntry,
+  dirNameWidth: number,
+  style: MigrationListStyler,
+): string {
+  const dirNamePadding = ' '.repeat(Math.max(0, dirNameWidth - migration.dirName.length));
+  const dirName = `${style.dirName(migration.dirName)}${dirNamePadding}`;
+  const source = formatSourceColumn(migration.from, style);
+  const arrow = formatArrowGlyph(migration.from, migration.to, style);
+  const dest = formatDestColumn(migration.from, migration.to, style);
+  const decorations = formatDecorations(migration.providedInvariants, migration.refs, style);
+  return `${dirName}${source} ${arrow} ${dest}${decorations}`;
+}
+
+function formatEmptyStateLine(spaceId: string, style: MigrationListStyler): string {
+  return style.emptyState(`There are no migrations in migrations/${spaceId}/ yet`);
+}
+
+function renderSpaceBlock(
+  spaceId: string,
+  migrations: readonly MigrationListEntry[],
+  multiSpace: boolean,
+  style: MigrationListStyler,
+): readonly string[] {
+  if (migrations.length === 0) {
+    const emptyLine = formatEmptyStateLine(spaceId, style);
+    if (!multiSpace) {
+      return [emptyLine];
+    }
+    return [style.spaceHeading(`${spaceId}:`), `  ${emptyLine}`];
+  }
+
+  const dirNameWidth = Math.max(...migrations.map((entry) => entry.dirName.length)) + 2;
+  const rows = migrations.map((entry) => formatMigrationRow(entry, dirNameWidth, style));
+  if (!multiSpace) {
+    return rows;
+  }
+  return [style.spaceHeading(`${spaceId}:`), ...rows.map((row) => `  ${row}`)];
+}
+
+/**
+ * Compose the styled `migration list` output. The renderer is
+ * presentation-neutral — every token passes through `style` before
+ * landing in the output, so the same composition serves the pure-text
+ * path ({@link renderMigrationList} via
+ * {@link IDENTITY_MIGRATION_LIST_STYLER}) and the ANSI-styled CLI path
+ * (via the ANSI styler the CLI shell wires up).
+ */
+export function renderMigrationListWithStyle(
+  result: MigrationListResult,
+  style: MigrationListStyler,
+): string {
+  const multiSpace = result.spaces.length > 1;
+  const lines: string[] = [];
+
+  for (let index = 0; index < result.spaces.length; index++) {
+    const space = result.spaces[index]!;
+    if (index > 0) {
+      lines.push('');
+    }
+    lines.push(...renderSpaceBlock(space.spaceId, space.migrations, multiSpace, style));
+  }
+
+  const totalMigrations = result.spaces.reduce(
+    (count, space) => count + space.migrations.length,
+    0,
+  );
+  if (totalMigrations > 0) {
+    lines.push('');
+    lines.push(style.summary(result.summary));
+  }
+
+  return lines.join('\n');
+}
+
+export function renderMigrationList(result: MigrationListResult): string {
+  return renderMigrationListWithStyle(result, IDENTITY_MIGRATION_LIST_STYLER);
+}

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),
+  };
+}