@prisma-next/cli 0.12.0-dev.9 → 0.13.0-dev.1

package/src/commands/migration-graph.ts

@@ -1,5 +1,6 @@
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
@@ -12,69 +13,80 @@ import {
   setCommandSeeAlso,
 } from '../utils/command-helpers';
 import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
-import { migrationGraphToRenderInput } from '../utils/formatters/graph-migration-mapper';
-import { graphRenderer } from '../utils/formatters/graph-render';
-import { buildMigrationGraphLayout } from '../utils/formatters/migration-graph-layout';
-import { buildMigrationGraphRows } from '../utils/formatters/migration-graph-rows';
+import { renderMigrationGraphLegend } from '../utils/formatters/migration-graph-labels';
 import {
-  renderMigrationGraphLegend,
-  renderMigrationGraphTree,
-} from '../utils/formatters/migration-graph-tree-render';
+  computeGlobalMaxDirNameWidth,
+  computeGlobalMaxEdgeTreePrefixWidth,
+  indentMigrationGraphTreeBlock,
+  renderMigrationGraphSpaceTree,
+} from '../utils/formatters/migration-graph-space-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
-import type { StatusRef } from '../utils/migration-types';
+import { shouldShowLegend, validateLegendOptions } from '../utils/legend';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
+import type { MigrationGraphJsonResult, MigrationSpaceGraphEntry } from './json/schemas';
+import {
+  listRefsByContractHash,
+  migrationSpaceListEntriesFromAggregate,
+  runMigrationList,
+} from './migration-list';
 
 interface MigrationGraphOptions extends CommonCommandOptions {
   readonly config?: string;
   readonly dot?: boolean;
-  readonly tree?: boolean;
+  readonly space?: string;
   readonly ascii?: boolean;
   readonly legend?: boolean;
 }
 
-/**
- * `--legend` describes the `--tree` visual language, so passing it auto-enables
- * the tree path (it has nothing to say about the legacy dagre default).
- */
-export function migrationGraphUsesTree(options: {
-  readonly tree?: boolean;
-  readonly legend?: boolean;
-}): boolean {
-  return options.tree === true || options.legend === true;
-}
-
-/**
- * The legend is decoration printed alongside the command header on stderr, so
- * it is suppressed for the machine-readable / silent paths (`--json`, `--dot`,
- * `--quiet`) exactly as the header is.
- */
-export function migrationGraphShowsLegend(
-  options: { readonly legend?: boolean; readonly dot?: boolean },
-  flags: GlobalFlags,
-): boolean {
-  return (
-    options.legend === true && options.dot !== true && flags.json !== true && flags.quiet !== true
-  );
+export interface MigrationGraphTreeSection {
+  readonly space: string;
+  readonly tree: string;
+  readonly showHeading: boolean;
 }
 
 export interface MigrationGraphResult {
   readonly ok: true;
+  /** App-space graph for the `--dot` Graphviz output. */
   readonly graph: MigrationGraph;
-  readonly contractHash: string | null;
-  readonly refs: readonly StatusRef[];
+  /** Nested per-space contracts + migrations for `--json`. */
+  readonly spaces: readonly MigrationSpaceGraphEntry[];
+  readonly treeSections: readonly MigrationGraphTreeSection[];
   readonly summary: string;
 }
 
+function computeGraphSummary(spaces: readonly MigrationSpaceGraphEntry[]): string {
+  const contractCount = spaces.reduce((count, space) => count + space.contracts.length, 0);
+  const migrationCount = spaces.reduce((count, space) => count + space.migrations.length, 0);
+  return `${spaces.length} space(s), ${contractCount} contract(s), ${migrationCount} migration(s)`;
+}
+
+export function formatMigrationGraphHumanOutput(result: MigrationGraphResult): string {
+  const sections: string[] = [];
+  for (const section of result.treeSections) {
+    if (section.showHeading) {
+      sections.push(`${section.space}:`);
+    }
+    if (section.tree.length > 0) {
+      sections.push(section.tree);
+    } else {
+      sections.push('(no migrations)');
+    }
+    sections.push('');
+  }
+  sections.push(result.summary);
+  return sections.join('\n').trimEnd();
+}
+
 export async function executeMigrationGraphCommand(
   options: MigrationGraphOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationGraphResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsRelative, migrationsDir } = resolveMigrationPaths(
+  const { configPath, migrationsRelative, migrationsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -85,19 +97,19 @@ export async function executeMigrationGraphCommand(
       description: 'Show the migration graph topology',
       details: [
         { label: 'config', value: configPath },
-        { label: 'migrations', value: appMigrationsRelative },
+        { label: 'migrations', value: migrationsRelative },
+        ...(options.space !== undefined ? [{ label: 'space', value: options.space }] : []),
       ],
       flags,
     });
     ui.stderr(header);
-    if (migrationGraphShowsLegend(options, flags)) {
+    if (shouldShowLegend(options, flags)) {
       ui.stderr(
         renderMigrationGraphLegend({
           colorize: flags.color !== false,
           glyphMode: ui.resolveGlyphMode(options.ascii === true),
         }),
       );
-      // Blank line separating the stderr key from the graph that follows on stdout.
       ui.stderr('');
     }
   }
@@ -107,20 +119,90 @@ export async function executeMigrationGraphCommand(
     return loaded;
   }
 
-  const { aggregate, contractHash } = loaded.value;
-  const graph = aggregate.app.graph();
-  const refs: readonly StatusRef[] = Object.entries(aggregate.app.refs).map(([name, entry]) => ({
-    name,
-    hash: entry.hash,
-    active: false,
-  }));
+  const { aggregate, contractHash: liveContractHash } = loaded.value;
+  const appGraph = aggregate.app.graph();
+
+  const listSpaces = await migrationSpaceListEntriesFromAggregate(aggregate, migrationsDir);
+  const listResult = runMigrationList({
+    spaces: listSpaces,
+    ...ifDefined('spaceFilter', options.space),
+  });
+  if (!listResult.ok) {
+    return listResult;
+  }
+
+  const scopedSpaces = listResult.value.spaces;
+  const showSpaceHeadings = scopedSpaces.length > 1;
+  const glyphMode = ui.resolveGlyphMode(options.ascii === true);
+  const colorize = flags.color !== false;
+
+  const globalLayoutInputs = showSpaceHeadings
+    ? scopedSpaces
+        .filter((spaceEntry) => spaceEntry.migrations.length > 0)
+        .map((spaceEntry) => ({
+          graph: aggregate.space(spaceEntry.space)!.graph(),
+          liveContractHash,
+        }))
+    : [];
+  const globalMaxEdgeTreePrefixWidth =
+    globalLayoutInputs.length > 0
+      ? computeGlobalMaxEdgeTreePrefixWidth(globalLayoutInputs)
+      : undefined;
+  const globalMaxDirNameWidth =
+    globalLayoutInputs.length > 0 ? computeGlobalMaxDirNameWidth(globalLayoutInputs) : undefined;
+
+  const treeSections: MigrationGraphTreeSection[] = [];
+  const spaces: MigrationSpaceGraphEntry[] = [];
+  for (const spaceEntry of scopedSpaces) {
+    const member = aggregate.space(spaceEntry.space);
+    if (member === undefined) {
+      continue;
+    }
+    const graph = member.graph();
+    const isAppSpace = spaceEntry.space === aggregate.app.spaceId;
+    const refsByHash = listRefsByContractHash(member);
+    const tree =
+      spaceEntry.migrations.length === 0
+        ? ''
+        : renderMigrationGraphSpaceTree({
+            graph,
+            migrations: spaceEntry.migrations,
+            liveContractHash,
+            glyphMode,
+            colorize,
+            isAppSpace,
+            refsByHash,
+            ...(globalMaxEdgeTreePrefixWidth !== undefined ? { globalMaxEdgeTreePrefixWidth } : {}),
+            ...(globalMaxDirNameWidth !== undefined ? { globalMaxDirNameWidth } : {}),
+          });
+    const displayTree =
+      showSpaceHeadings && tree.length > 0 ? indentMigrationGraphTreeBlock(tree, '  ') : tree;
+    treeSections.push({
+      space: spaceEntry.space,
+      tree: displayTree,
+      showHeading: showSpaceHeadings,
+    });
+    spaces.push({
+      space: spaceEntry.space,
+      contracts: [...graph.nodes].map((hash) => ({
+        hash,
+        refs: [...(refsByHash.get(hash) ?? [])],
+      })),
+      migrations: [...graph.migrationByHash.values()].map((edge) => ({
+        name: edge.dirName,
+        hash: edge.migrationHash,
+        fromContract: edge.from === EMPTY_CONTRACT_HASH ? null : edge.from,
+        toContract: edge.to,
+      })),
+    });
+  }
 
   return ok({
     ok: true,
-    graph,
-    contractHash,
-    refs,
-    summary: `${graph.nodes.size} node(s), ${graph.migrationByHash.size} edge(s)`,
+    graph: appGraph,
+    spaces,
+    treeSections,
+    summary: computeGraphSummary(spaces),
   });
 }
 
@@ -129,19 +211,19 @@ export function createMigrationGraphCommand(): Command {
   setCommandDescriptions(
     command,
     'Show the migration graph topology',
-    'Renders the migration graph topology. Offline — does not consult\n' +
-      'the database. Use --tree for the condensed annotated tree\n' +
-      '(--ascii swaps box-drawing for pipe-friendly ASCII glyphs),\n' +
-      '--json for machine-readable output, or --dot for Graphviz DOT\n' +
+    'Renders the migration graph topology.\n' +
+      'Offline — does not consult the database.\n' +
+      '--ascii swaps box-drawing for pipe-friendly ASCII glyphs.\n' +
+      'Use --json for machine-readable output, or --dot for Graphviz DOT\n' +
       'format.',
   );
   setCommandExamples(command, [
     'prisma-next migration graph',
     'prisma-next migration graph --json',
     'prisma-next migration graph --dot',
-    'prisma-next migration graph --tree',
-    'prisma-next migration graph --tree --ascii',
+    'prisma-next migration graph --ascii',
     'prisma-next migration graph --legend',
+    'prisma-next migration graph --space app',
   ]);
   setCommandSeeAlso(command, [
     { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
@@ -151,20 +233,19 @@ export function createMigrationGraphCommand(): Command {
   ]);
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
+    .option('--space <id>', 'Narrow output to a single contract space')
     .option('--dot', 'Output in Graphviz DOT format')
-    .option('--tree', 'Experimental condensed annotated tree renderer')
-    .option('--ascii', 'Use ASCII glyphs for --tree (pipe-friendly)')
-    .option('--legend', 'Print a key for the --tree glyphs and lane colors (implies --tree)')
+    .option('--ascii', 'Use ASCII glyphs (pipe-friendly)')
+    .option('--legend', 'Print a key for the tree glyphs and lane colors')
     .action(async (options: MigrationGraphOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
+      const legendValidation = validateLegendOptions(options, flags);
+      if (!legendValidation.ok) {
+        process.exit(handleResult(legendValidation, flags, ui));
+      }
       const result = await executeMigrationGraphCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (graphResult) => {
-        // Explicit format flags win over the auto-JSON default. `flags.json`
-        // is auto-enabled when stdout is non-TTY (per CLI Style Guide §
-        // JSON Semantics); without this ordering, `migration graph --dot |
-        // dot -Tsvg` pipes JSON into the GraphViz binary, which then
-        // errors. `--dot` is the more specific instruction; honour it.
         if (options.dot) {
           const lines = ['digraph migrations {'];
           for (const edge of graphResult.graph.migrationByHash.values()) {
@@ -175,63 +256,14 @@ export function createMigrationGraphCommand(): Command {
           lines.push('}');
           ui.output(lines.join('\n'));
         } else if (flags.json) {
-          const nodes = [...graphResult.graph.nodes];
-          const edges = [...graphResult.graph.migrationByHash.values()].map((e) => ({
-            dirName: e.dirName,
-            from: e.from,
-            to: e.to,
-            migrationHash: e.migrationHash,
-          }));
-          ui.output(
-            JSON.stringify({ ok: true, nodes, edges, summary: graphResult.summary }, null, 2),
-          );
+          const jsonResult: MigrationGraphJsonResult = {
+            ok: true,
+            spaces: [...graphResult.spaces],
+            summary: graphResult.summary,
+          };
+          ui.output(JSON.stringify(jsonResult, null, 2));
         } else if (!flags.quiet) {
-          if (migrationGraphUsesTree(options)) {
-            const refsByHash = new Map<string, string[]>();
-            for (const ref of graphResult.refs) {
-              const existing = refsByHash.get(ref.hash);
-              refsByHash.set(ref.hash, existing ? [...existing, ref.name] : [ref.name]);
-            }
-            const rowModel = buildMigrationGraphRows(graphResult.graph, {
-              ...(graphResult.contractHash !== null
-                ? { contractHash: graphResult.contractHash }
-                : {}),
-            });
-            const layout = buildMigrationGraphLayout(rowModel);
-            const activeRef = graphResult.refs.find((ref) => ref.active);
-            const treeOutput = renderMigrationGraphTree(layout, {
-              refsByHash,
-              ...(graphResult.contractHash !== null
-                ? { contractHash: graphResult.contractHash }
-                : {}),
-              ...(activeRef !== undefined ? { activeRefName: activeRef.name } : {}),
-              colorize: flags.color !== false,
-              glyphMode: ui.resolveGlyphMode(options.ascii === true),
-            });
-            // Emit the rendered tree to stdout (same stream as flat `migration list`),
-            // not through clack's `log.message` rail: the graph is the command's
-            // result (and its own box-drawing is the only vertical structure it
-            // should carry), not a status line that needs the prompt gutter.
-            ui.output(treeOutput);
-            ui.output(`\n${graphResult.summary}`);
-          } else {
-            const renderInput = migrationGraphToRenderInput({
-              graph: graphResult.graph,
-              mode: 'offline',
-              markerHash: undefined,
-              contractHash: graphResult.contractHash ?? EMPTY_CONTRACT_HASH,
-              refs: graphResult.refs,
-              activeRefHash: undefined,
-              activeRefName: undefined,
-              edgeStatuses: [],
-            });
-            const graphOutput = graphRenderer.render(renderInput.graph, {
-              ...renderInput.options,
-              colorize: flags.color !== false,
-            });
-            ui.log(graphOutput);
-            ui.log(`\n${graphResult.summary}`);
-          }
+          ui.output(formatMigrationGraphHumanOutput(graphResult));
         }
       });
       process.exit(exitCode);

package/src/commands/migration-list.ts

@@ -2,6 +2,7 @@ import type {
   ContractSpaceAggregate,
   ContractSpaceMember,
 } from '@prisma-next/migration-tools/aggregate';
+import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
 import { HEAD_REF_NAME, refsByContractHash } from '@prisma-next/migration-tools/refs';
 import {
   APP_SPACE_ID,
@@ -26,10 +27,8 @@ import {
   setCommandSeeAlso,
 } from '../utils/command-helpers';
 import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
-import {
-  buildMigrationListTopologyBySpace,
-  renderMigrationListWithStyle,
-} from '../utils/formatters/migration-list-render';
+import { renderMigrationGraphLegend } from '../utils/formatters/migration-graph-labels';
+import { renderMigrationListWithStyle } from '../utils/formatters/migration-list-render';
 import { createAnsiMigrationListStyler } from '../utils/formatters/migration-list-styler';
 import type {
   MigrationListEntry,
@@ -40,6 +39,7 @@ import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import type { GlyphMode } from '../utils/glyph-mode';
+import { shouldShowLegend, validateLegendOptions } from '../utils/legend';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
@@ -52,8 +52,8 @@ function compareSpaceIds(a: string, b: string): number {
 }
 
 function compareDirNamesDescending(a: MigrationListEntry, b: MigrationListEntry): number {
-  if (a.dirName < b.dirName) return 1;
-  if (a.dirName > b.dirName) return -1;
+  if (a.name < b.name) return 1;
+  if (a.name > b.name) return -1;
   return 0;
 }
 
@@ -65,7 +65,7 @@ function compareDirNamesDescending(a: MigrationListEntry, b: MigrationListEntry)
  * keep that output. The app space synthesises its head, so it carries
  * no on-disk `head` ref to restore.
  */
-function listRefsByContractHash(
+export function listRefsByContractHash(
   member: ContractSpaceMember,
 ): ReadonlyMap<string, readonly string[]> {
   const byHash = new Map(refsByContractHash(member.refs));
@@ -110,18 +110,18 @@ export async function migrationSpaceListEntriesFromAggregate(
     const refsByHash = listRefsByContractHash(member);
     const migrations: MigrationListEntry[] = member.packages
       .map((pkg) => ({
-        dirName: pkg.dirName,
-        from: pkg.metadata.from,
-        to: pkg.metadata.to,
-        migrationHash: pkg.metadata.migrationHash,
+        name: pkg.dirName,
+        hash: pkg.metadata.migrationHash,
+        fromContract: pkg.metadata.from,
+        toContract: pkg.metadata.to,
         operationCount: pkg.ops.length,
         createdAt: pkg.metadata.createdAt,
-        refs: refsByHash.get(pkg.metadata.to) ?? [],
-        providedInvariants: pkg.metadata.providedInvariants,
+        refs: [...(refsByHash.get(pkg.metadata.to) ?? [])],
+        providedInvariants: [...pkg.metadata.providedInvariants],
       }))
       .sort(compareDirNamesDescending);
 
-    spaces.push({ spaceId, migrations });
+    spaces.push({ space: spaceId, migrations });
   }
 
   return spaces;
@@ -131,11 +131,21 @@ interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
   readonly space?: string;
   readonly ascii?: boolean;
+  readonly legend?: boolean;
+}
+
+export interface MigrationListExecuteResult {
+  readonly list: MigrationListResult;
+  readonly liveContractHash: string;
+  readonly aggregate: ContractSpaceAggregate;
 }
 
 export interface MigrationListHumanRenderOptions {
   readonly glyphMode: GlyphMode;
   readonly useColor: boolean;
+  readonly liveContractHash: string;
+  readonly graphForSpace: (spaceId: string) => MigrationGraph | undefined;
+  readonly appSpaceId?: string;
 }
 
 export function renderMigrationListHumanOutput(
@@ -143,8 +153,12 @@ export function renderMigrationListHumanOutput(
   options: MigrationListHumanRenderOptions,
 ): string {
   const styler = createAnsiMigrationListStyler({ useColor: options.useColor });
-  const topologyBySpaceId = buildMigrationListTopologyBySpace(result);
-  return renderMigrationListWithStyle(result, styler, options.glyphMode, topologyBySpaceId);
+  return renderMigrationListWithStyle(result, styler, options.glyphMode, {
+    colorize: options.useColor,
+    liveContractHash: options.liveContractHash,
+    graphForSpace: options.graphForSpace,
+    ...(options.appSpaceId !== undefined ? { appSpaceId: options.appSpaceId } : {}),
+  });
 }
 
 /**
@@ -186,19 +200,19 @@ export function runMigrationList(
     return notOk(errorInvalidSpaceId(spaceFilter));
   }
 
-  if (spaceFilter !== undefined && !spaces.some((s) => s.spaceId === spaceFilter)) {
-    return notOk(errorSpaceNotFound(spaceFilter, spaces.map((s) => s.spaceId).sort()));
+  if (spaceFilter !== undefined && !spaces.some((s) => s.space === spaceFilter)) {
+    return notOk(errorSpaceNotFound(spaceFilter, spaces.map((s) => s.space).sort()));
   }
 
   const scopedSpaces =
-    spaceFilter !== undefined ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
+    spaceFilter !== undefined ? spaces.filter((s) => s.space === spaceFilter) : spaces;
 
   const resultSpaces: readonly MigrationSpaceListEntry[] =
-    scopedSpaces.length === 0 ? [{ spaceId: APP_SPACE_ID, migrations: [] }] : scopedSpaces;
+    scopedSpaces.length === 0 ? [{ space: APP_SPACE_ID, migrations: [] }] : scopedSpaces;
 
   return ok({
     ok: true,
-    spaces: resultSpaces,
+    spaces: [...resultSpaces],
     summary: computeSummary(resultSpaces),
   });
 }
@@ -212,7 +226,7 @@ export async function executeMigrationListCommand(
   options: MigrationListOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
-): Promise<Result<MigrationListResult, CliStructuredError>> {
+): Promise<Result<MigrationListExecuteResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
   const { configPath, migrationsDir, migrationsRelative } = resolveMigrationPaths(
     options.config,
@@ -222,7 +236,7 @@ export async function executeMigrationListCommand(
   if (!flags.json && !flags.quiet) {
     const header = formatStyledHeader({
       command: 'migration list',
-      description: 'List on-disk migrations, latest first, per contract space',
+      description: 'List on-disk migrations per contract space',
       details: [
         { label: 'config', value: configPath },
         { label: 'migrations', value: migrationsRelative },
@@ -231,6 +245,15 @@ export async function executeMigrationListCommand(
       flags,
     });
     ui.stderr(header);
+    if (shouldShowLegend(options, flags)) {
+      ui.stderr(
+        renderMigrationGraphLegend({
+          colorize: flags.color !== false,
+          glyphMode: ui.resolveGlyphMode(options.ascii === true),
+        }),
+      );
+      ui.stderr('');
+    }
   }
 
   const loaded = await buildReadAggregate(config, { migrationsDir });
@@ -238,35 +261,37 @@ export async function executeMigrationListCommand(
     return notOk(loaded.failure);
   }
 
-  const spaces = await migrationSpaceListEntriesFromAggregate(
-    loaded.value.aggregate,
-    migrationsDir,
-  );
+  const { aggregate, contractHash: liveContractHash } = loaded.value;
 
-  return runMigrationList({
+  const spaces = await migrationSpaceListEntriesFromAggregate(aggregate, migrationsDir);
+
+  const listResult = runMigrationList({
     spaces,
     ...ifDefined('spaceFilter', options.space),
   });
+  if (!listResult.ok) {
+    return listResult;
+  }
+  return ok({ list: listResult.value, liveContractHash, aggregate });
 }
 
 export function createMigrationListCommand(): Command {
   const command = new Command('list');
   setCommandDescriptions(
     command,
-    'List on-disk migrations, latest first, per contract space',
+    'List on-disk migrations per contract space',
     'Enumerates every on-disk migration under migrations/<space>/ for every\n' +
-      'contract space found on disk, latest first. Offline — does not consult\n' +
-      'the database. Each row leads with a kind glyph (* forward, ↩ rollback,\n' +
-      '⟲ self), then dirName, then source → destination contract hashes\n' +
-      '(7-char git-style). Self-edges show a single hash. Invariants render as\n' +
-      '{...}; refs on the destination as (production, db). Pass --space <id>\n' +
-      'to narrow to one contract space. --ascii forces ASCII kind glyphs\n' +
-      '(orthogonal to --no-color).',
+      'contract space found on disk. Offline — does not consult the database.\n' +
+      'Human output draws the shared migration graph tree with operation counts,\n' +
+      'invariants on each migration row, and refs on destination contract nodes.\n' +
+      'Pass --space <id> to narrow to one contract space. --ascii forces ASCII\n' +
+      'tree glyphs (orthogonal to --no-color).',
   );
   setCommandExamples(command, [
     'prisma-next migration list',
     'prisma-next migration list --space app',
     'prisma-next migration list --ascii',
+    'prisma-next migration list --legend',
     'prisma-next migration list --json',
   ]);
   setCommandSeeAlso(command, [
@@ -279,18 +304,26 @@ export function createMigrationListCommand(): Command {
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--space <id>', 'Narrow output to a single contract space')
     .option('--ascii', 'Use ASCII kind glyphs (pipe-friendly)')
+    .option('--legend', 'Print a key for the tree glyphs and lane colors')
     .action(async (options: MigrationListOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
+      const legendValidation = validateLegendOptions(options, flags);
+      if (!legendValidation.ok) {
+        process.exit(handleResult(legendValidation, flags, ui));
+      }
       const result = await executeMigrationListCommand(options, flags, ui);
-      const exitCode = handleResult(result, flags, ui, (listResult) => {
+      const exitCode = handleResult(result, flags, ui, ({ list, liveContractHash, aggregate }) => {
         if (flags.json) {
-          ui.output(JSON.stringify(listResult, null, 2));
+          ui.output(JSON.stringify(list, null, 2));
         } else if (!flags.quiet) {
           ui.output(
-            renderMigrationListHumanOutput(listResult, {
+            renderMigrationListHumanOutput(list, {
               glyphMode: ui.resolveGlyphMode(options.ascii === true),
               useColor: ui.useColor,
+              liveContractHash,
+              graphForSpace: (spaceId) => aggregate.space(spaceId)?.graph(),
+              appSpaceId: aggregate.app.spaceId,
             }),
           );
         }