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

package/src/commands/init/inputs.ts

@@ -1,9 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import * as clack from '@clack/prompts';
-import { readUserConfig, resolveGating, writeUserConfig } from '@prisma-next/cli-telemetry';
 import { extname, join, normalize } from 'pathe';
 import type { GlobalFlags } from '../../utils/global-flags';
-import { isCI } from '../../utils/is-ci';
 import {
   errorInitAuthoringSchemaPathMismatch,
   errorInitInvalidFlagValue,
@@ -71,18 +69,6 @@ export interface ResolvedInitInputs {
    * is added separately via the install step.
    */
   readonly removePreviousFacade: string | null;
-  /**
-   * Telemetry consent answer recorded during this `init` run, or `null`
-   * when no prompt was shown. The prompt fires only on the
-   * canPrompt + !autoAcceptPrompts + no env/CI opt-out +
-   * `enableTelemetry === undefined` intersection; outside that window
-   * the field is `null` and the stored preference (if any) stays
-   * unchanged. The answer has already been persisted to
-   * `$XDG_CONFIG_HOME/prisma-next/config.json` by
-   * the time `runInit` sees this value — it's surfaced here purely so
-   * the post-init summary can mention what the user chose.
-   */
-  readonly enableTelemetry: boolean | null;
   /**
    * Whether to run `npx skills add prisma/prisma-next#v<version>` at the
    * project level after install + emit. True by default; `--no-skill`
@@ -106,12 +92,6 @@ const AUTHORING_VALUES: ReadonlyMap<string, AuthoringId> = new Map([
   ['ts', 'typescript'],
 ]);
 
-export const TELEMETRY_CONSENT_MESSAGE = [
-  'Help us prioritize features by sharing anonymous CLI usage data?',
-  'The telemetry implementation is open source and fully transparent.',
-  '(packages/1-framework/3-tooling/cli-telemetry and apps/telemetry-backend).',
-].join(' ');
-
 /**
  * Resolves every required input for `runInit`. In interactive mode, missing
  * inputs are prompted via clack; in non-interactive mode, missing required
@@ -197,11 +177,6 @@ export async function resolveInitInputs(ctx: {
     autoAcceptPrompts,
   });
 
-  const enableTelemetry = await resolveTelemetryConsent({
-    canPrompt,
-    autoAcceptPrompts,
-  });
-
   // Skill-install gating. `--no-skill` (commander parses
   // `options.skill === false`) is the only escape hatch; otherwise
   // project-level install is unconditional. The skill is always
@@ -219,60 +194,10 @@ export async function resolveInitInputs(ctx: {
     strictProbe: Boolean(options.strictProbe),
     reinit,
     removePreviousFacade,
-    enableTelemetry,
     installProjectSkill,
   };
 }
 
-/**
- * The interactive telemetry consent prompt. Shown as the last
- * question of the `init` sequence iff:
- *   1. `canPrompt === true` (interactive stdin / stdout combo),
- *   2. `autoAcceptPrompts === false` (the user did not pass `--yes`),
- *   3. neither telemetry env opt-out is active,
- *   4. the process is not running in CI,
- *   5. the stored `enableTelemetry` value is `undefined` (the user
- *      has never been asked, or skipped the prompt previously).
- *
- * Outside that intersection the function returns `null` and leaves the
- * stored preference untouched. Inside it, the user's answer is
- * persisted via `writeUserConfig({ enableTelemetry })` before this
- * function returns; on an affirmative answer `writeUserConfig`
- * generates and stores the v4 `installationId` in the same write.
- *
- * The wording names CLI usage data and points to the open-source
- * client/backend paths. Default value is `true` to match precedent
- * and to make the consent answer a single keystroke once it's been
- * disclosed.
- */
-async function resolveTelemetryConsent(opts: {
-  readonly canPrompt: boolean;
-  readonly autoAcceptPrompts: boolean;
-}): Promise<boolean | null> {
-  if (!opts.canPrompt || opts.autoAcceptPrompts || isCI()) {
-    return null;
-  }
-  const config = readUserConfig();
-  const gating = resolveGating({ env: process.env, config });
-  if (!gating.enabled && gating.reason === 'env-override') {
-    return null;
-  }
-  const stored = config.enableTelemetry;
-  if (stored !== undefined) {
-    return null;
-  }
-  const result = await clack.confirm({
-    message: TELEMETRY_CONSENT_MESSAGE,
-    initialValue: true,
-    output: process.stderr,
-  });
-  if (clack.isCancel(result)) {
-    throw errorInitUserAborted();
-  }
-  writeUserConfig({ enableTelemetry: Boolean(result) });
-  return Boolean(result);
-}
-
 async function resolveWriteEnv(opts: {
   readonly flag: boolean | undefined;
   readonly canPrompt: boolean;

package/src/commands/migration-graph.ts

@@ -1,5 +1,5 @@
-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,40 +12,75 @@ 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 { renderMigrationGraphTree } from '../utils/formatters/migration-graph-tree-render';
+import {
+  computeGlobalMaxDirNameWidth,
+  computeGlobalMaxEdgeTreePrefixWidth,
+  indentMigrationGraphTreeBlock,
+  renderMigrationGraphSpaceTree,
+} from '../utils/formatters/migration-graph-space-render';
+import { renderMigrationGraphLegend } from '../utils/formatters/migration-graph-tree-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 {
+  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;
+}
+
+export interface MigrationGraphTreeSection {
+  readonly spaceId: string;
+  readonly tree: string;
+  readonly showHeading: boolean;
 }
 
 export interface MigrationGraphResult {
   readonly ok: true;
+  /** App-space graph for `--json` / `--dot` (unchanged machine output). */
   readonly graph: MigrationGraph;
-  readonly contractHash: string | null;
-  readonly refs: readonly StatusRef[];
+  readonly treeSections: readonly MigrationGraphTreeSection[];
   readonly summary: string;
 }
 
+function computeGraphSummary(graph: MigrationGraph): string {
+  return `${graph.nodes.size} node(s), ${graph.migrationByHash.size} edge(s)`;
+}
+
+export function formatMigrationGraphHumanOutput(result: MigrationGraphResult): string {
+  const sections: string[] = [];
+  for (const section of result.treeSections) {
+    if (section.showHeading) {
+      sections.push(`${section.spaceId}:`);
+    }
+    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,
   );
@@ -56,11 +91,21 @@ 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 (shouldShowLegend(options, flags)) {
+      ui.stderr(
+        renderMigrationGraphLegend({
+          colorize: flags.color !== false,
+          glyphMode: ui.resolveGlyphMode(options.ascii === true),
+        }),
+      );
+      ui.stderr('');
+    }
   }
 
   const loaded = await buildReadAggregate(config, { migrationsDir });
@@ -68,20 +113,72 @@ 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.spaceId)!.graph(),
+          liveContractHash,
+        }))
+    : [];
+  const globalMaxEdgeTreePrefixWidth =
+    globalLayoutInputs.length > 0
+      ? computeGlobalMaxEdgeTreePrefixWidth(globalLayoutInputs)
+      : undefined;
+  const globalMaxDirNameWidth =
+    globalLayoutInputs.length > 0 ? computeGlobalMaxDirNameWidth(globalLayoutInputs) : undefined;
+
+  const treeSections: MigrationGraphTreeSection[] = [];
+  for (const spaceEntry of scopedSpaces) {
+    const member = aggregate.space(spaceEntry.spaceId);
+    if (member === undefined) {
+      continue;
+    }
+    const graph = member.graph();
+    const tree =
+      spaceEntry.migrations.length === 0
+        ? ''
+        : renderMigrationGraphSpaceTree({
+            graph,
+            migrations: spaceEntry.migrations,
+            liveContractHash,
+            glyphMode,
+            colorize,
+            refsByHash: listRefsByContractHash(member),
+            ...(globalMaxEdgeTreePrefixWidth !== undefined ? { globalMaxEdgeTreePrefixWidth } : {}),
+            ...(globalMaxDirNameWidth !== undefined ? { globalMaxDirNameWidth } : {}),
+          });
+    const displayTree =
+      showSpaceHeadings && tree.length > 0 ? indentMigrationGraphTreeBlock(tree, '  ') : tree;
+    treeSections.push({
+      spaceId: spaceEntry.spaceId,
+      tree: displayTree,
+      showHeading: showSpaceHeadings,
+    });
+  }
 
   return ok({
     ok: true,
-    graph,
-    contractHash,
-    refs,
-    summary: `${graph.nodes.size} node(s), ${graph.migrationByHash.size} edge(s)`,
+    graph: appGraph,
+    treeSections,
+    summary: computeGraphSummary(appGraph),
   });
 }
 
@@ -91,17 +188,17 @@ export function createMigrationGraphCommand(): Command {
     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' +
+      'the database. --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' },
@@ -111,19 +208,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('--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()) {
@@ -142,55 +239,19 @@ export function createMigrationGraphCommand(): Command {
             migrationHash: e.migrationHash,
           }));
           ui.output(
-            JSON.stringify({ ok: true, nodes, edges, summary: graphResult.summary }, null, 2),
+            JSON.stringify(
+              {
+                ok: true,
+                nodes,
+                edges,
+                summary: `${graphResult.graph.nodes.size} node(s), ${graphResult.graph.migrationByHash.size} edge(s)`,
+              },
+              null,
+              2,
+            ),
           );
         } else if (!flags.quiet) {
-          if (options.tree) {
-            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-tree-render';
+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';
 
@@ -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));
@@ -131,11 +131,20 @@ 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;
 }
 
 export function renderMigrationListHumanOutput(
@@ -143,8 +152,11 @@ 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,
+  });
 }
 
 /**
@@ -212,7 +224,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 +234,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 +243,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 +259,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 +302,25 @@ 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(),
             }),
           );
         }