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

package/src/commands/migrate.ts

@@ -5,17 +5,15 @@ import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migrati
 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 { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { join } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import type {
-  AggregatePerSpaceExecutionEntry,
   MigrationApplyFailure,
   MigrationApplyPathDecision,
+  PerSpaceExecutionEntry,
 } from '../control-api/types';
 import {
   CliStructuredError,
@@ -35,7 +33,6 @@ import {
 import {
   addGlobalOptions,
   collectDeclaredInvariants,
-  loadMigrationPackages,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
@@ -43,6 +40,12 @@ import {
   setCommandExamples,
   targetSupportsMigrations,
 } from '../utils/command-helpers';
+import { mapContractAtError } from '../utils/contract-at-errors';
+import {
+  loadContractSpaceAggregateForCli,
+  refuseContractSpaceIntegrity,
+} from '../utils/contract-space-aggregate-loader';
+import { toDeclaredExtensionsFromRaw } from '../utils/extension-pack-inputs';
 import { formatMigrationApplyCommandOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -72,7 +75,7 @@ export interface MigrateResult {
     readonly operationsExecuted: number;
   }[];
   readonly summary: string;
-  readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
+  readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly pathDecision?: MigrationApplyPathDecision;
   readonly timings: {
     readonly total: number;
@@ -98,8 +101,10 @@ async function executeMigrateCommand(
   startTime: number,
 ): Promise<Result<MigrateResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
-    resolveMigrationPaths(options.config, config);
+  const { configPath, migrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
 
   const dbConnection = options.db ?? config.db?.connection;
   if (!dbConnection) {
@@ -127,31 +132,8 @@ async function executeMigrateCommand(
     );
   }
 
-  let refEntry: RefEntry | undefined;
   const toArg = options.to;
 
-  if (toArg) {
-    try {
-      const refs = await readRefs(refsDir);
-      const { graph } = await loadMigrationPackages(appMigrationsDir);
-      const refResult = parseContractRef(toArg, { graph, refs });
-      if (!refResult.ok) {
-        return notOk(mapRefResolutionError(refResult.failure));
-      }
-      if (refResult.value.provenance.kind === 'ref') {
-        const resolved = refs[refResult.value.provenance.refName];
-        if (resolved) refEntry = resolved;
-      } else {
-        refEntry = { hash: refResult.value.hash, invariants: [] };
-      }
-    } catch (error) {
-      if (MigrationToolsError.is(error)) {
-        return notOk(mapMigrationToolsError(error));
-      }
-      throw error;
-    }
-  }
-
   // Construct the family instance up-front so the on-disk contract read
   // crosses the serializer seam (`familyInstance.deserializeContract`) at
   // the read site. The downstream `client.migrationApply({ contract })`
@@ -193,6 +175,44 @@ async function executeMigrateCommand(
     );
   }
 
+  const loadedAggregate = await loadContractSpaceAggregateForCli({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: contractRaw,
+    extensionPacks: config.extensionPacks ?? [],
+    deserializeContract: (json) => familyInstance.deserializeContract(json),
+  });
+  if (!loadedAggregate.ok) {
+    return notOk(loadedAggregate.failure);
+  }
+  const aggregate = loadedAggregate.value;
+  const integrityFailure = refuseContractSpaceIntegrity(aggregate, {
+    declaredExtensions: toDeclaredExtensionsFromRaw(
+      (config.extensionPacks ?? []) as ReadonlyArray<unknown>,
+    ),
+    checkContracts: true,
+  });
+  if (integrityFailure) {
+    return notOk(integrityFailure);
+  }
+
+  let refEntry: RefEntry | undefined;
+  let refName: string | undefined;
+  if (toArg) {
+    const refs = aggregate.app.refs;
+    const refResult = parseContractRef(toArg, { graph: aggregate.app.graph(), refs });
+    if (!refResult.ok) {
+      return notOk(mapRefResolutionError(refResult.failure));
+    }
+    if (refResult.value.provenance.kind === 'ref') {
+      refName = refResult.value.provenance.refName;
+      const resolved = refs[refName];
+      if (resolved) refEntry = resolved;
+    } else {
+      refEntry = { hash: refResult.value.hash, invariants: [] };
+    }
+  }
+
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
@@ -217,15 +237,7 @@ async function executeMigrateCommand(
     ui.stderr(header);
   }
 
-  let appPackages: Awaited<ReturnType<typeof loadMigrationPackages>>;
-  try {
-    appPackages = await loadMigrationPackages(appMigrationsDir);
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      return notOk(mapMigrationToolsError(error));
-    }
-    throw error;
-  }
+  const appGraph = aggregate.app.graph();
 
   const client = createControlClient({
     family: config.family,
@@ -240,20 +252,19 @@ async function executeMigrateCommand(
 
     const allMarkers = await client.readAllMarkers();
     const appMarker = allMarkers.get('app') ?? null;
-    const { graph } = appPackages;
 
-    if (appMarker !== null && !isGraphNode(appMarker.storageHash, graph)) {
+    if (appMarker !== null && !isGraphNode(appMarker.storageHash, appGraph)) {
       return notOk(
         errorMarkerMismatch(
           appMarker.storageHash,
-          [...graph.nodes].sort(),
-          findLatestMigration(graph)?.to ?? null,
+          [...appGraph.nodes].sort(),
+          findLatestMigration(appGraph)?.to ?? null,
         ),
       );
     }
 
     if (refEntry && refEntry.invariants.length > 0) {
-      const declared = collectDeclaredInvariants(appPackages.graph);
+      const declared = collectDeclaredInvariants(appGraph);
       const known = new Set<string>(declared);
       for (const id of appMarker?.invariants ?? []) known.add(id);
       const unknown = refEntry.invariants.filter((id) => !known.has(id));
@@ -274,10 +285,36 @@ async function executeMigrateCommand(
       ui.step('Loading contract spaces…');
     }
 
+    // When `--to` resolves to an on-disk graph node with a matching bundle,
+    // verify and apply against THAT bundle's destination contract via
+    // `contractAt` — not the emitted `contract.json`. With `--to` omitted,
+    // or a target with no matching bundle, the emitted contract stays the
+    // apply contract (the only migrate-specific default). The same
+    // `contractAt` artifacts feed the optional ref-advancement snapshot.
+    let applyContract: Contract = contractRaw;
+    let snapshotContractJson: Record<string, unknown> = JSON.parse(contractContent);
+    let snapshotContractDts: string | undefined;
+    if (toArg && refEntry) {
+      const targetHash = refEntry.hash;
+      const matchingBundle = aggregate.app.packages.find((p) => p.metadata.to === targetHash);
+      if (matchingBundle) {
+        try {
+          const at = await aggregate.app.contractAt(
+            targetHash,
+            refName !== undefined ? { refName } : undefined,
+          );
+          applyContract = at.contract;
+          snapshotContractJson = at.contractJson as Record<string, unknown>;
+          snapshotContractDts = at.contractDts;
+        } catch (error) {
+          return mapContractAtError(error, { artifactRole: 'to' });
+        }
+      }
+    }
+
     const applyResult = await client.migrationApply({
-      contract: contractRaw,
+      contract: applyContract,
       migrationsDir,
-      appMigrationPackages: appPackages.bundles,
       ...ifDefined('refHash', refEntry?.hash),
       ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
       ...(refEntry !== undefined ? ifDefined('refName', toArg) : {}),
@@ -291,37 +328,11 @@ async function executeMigrateCommand(
 
     let advancedRef: { name: string; hash: string } | null = null;
     if (options.advanceRef !== undefined) {
-      let contractJsonPathForSnapshot = contractPathAbsolute;
-      let contractJsonForSnapshot: Record<string, unknown> = JSON.parse(contractContent) as Record<
-        string,
-        unknown
-      >;
-      if (toArg && refEntry) {
-        const matchingBundle = appPackages.bundles.find((p) => p.metadata.to === refEntry.hash);
-        if (matchingBundle) {
-          const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
-          contractJsonPathForSnapshot = endContractPath;
-          try {
-            const raw = await readFile(endContractPath, 'utf-8');
-            contractJsonForSnapshot = JSON.parse(raw) as Record<string, unknown>;
-          } catch (error) {
-            if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
-              return notOk(
-                errorFileNotFound(endContractPath, {
-                  why: `Bundle end-contract not found at ${endContractPath}`,
-                  fix: 'Re-emit the migration bundle or pick a different --to target.',
-                }),
-              );
-            }
-            throw error;
-          }
-        }
-      }
       try {
-        const contractIR = await readContractIR(
-          contractJsonForSnapshot,
-          contractJsonPathForSnapshot,
-        );
+        const contractIR =
+          snapshotContractDts !== undefined
+            ? { contract: snapshotContractJson, contractDts: snapshotContractDts }
+            : await readContractIR(snapshotContractJson, contractPathAbsolute);
         advancedRef = await executeRefAdvancement(
           refsDir,
           options.advanceRef,

package/src/commands/migration-check.ts

@@ -1,6 +1,11 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { readFile } from 'node:fs/promises';
+import { createControlStack } from '@prisma-next/framework-components/control';
+import type { IntegrityViolation } from '@prisma-next/migration-tools/aggregate';
+import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
 import { verifyMigrationHash } from '@prisma-next/migration-tools/hash';
+import { readMigrationsDir } from '@prisma-next/migration-tools/io';
+import { reconstructGraph } from '@prisma-next/migration-tools/migration-graph';
 import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import { parseMigrationRef } from '@prisma-next/migration-tools/ref-resolution';
 import { readRefs } from '@prisma-next/migration-tools/refs';
@@ -9,15 +14,20 @@ import { join, relative } from 'pathe';
 import { loadConfig } from '../config-loader';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
+  resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
+import { toDeclaredExtensionsFromRaw } from '../utils/extension-pack-inputs';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import {
+  type CheckFailure,
+  integrityViolationToCheckFailure,
+} from '../utils/integrity-violation-to-check-failure';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 import { INTEGRITY_FAILED, OK, PRECONDITION } from './migration-check/exit-codes';
 
@@ -25,12 +35,7 @@ interface MigrationCheckOptions extends CommonCommandOptions {
   readonly config?: string;
 }
 
-export interface CheckFailure {
-  readonly pnCode: string;
-  readonly where: string;
-  readonly why: string;
-  readonly fix: string;
-}
+export type { CheckFailure } from '../utils/integrity-violation-to-check-failure';
 
 export interface MigrationCheckResult {
   readonly ok: boolean;
@@ -38,11 +43,6 @@ export interface MigrationCheckResult {
   readonly summary: string;
 }
 
-/**
- * Canonical user-facing locator for a check failure: the cwd-relative path
- * to the migration package directory. Surfacing the same shape across every
- * PN code means `--json` consumers can branch uniformly on `where`.
- */
 function migrationPathRelative(dirPath: string): string {
   return relative(process.cwd(), dirPath);
 }
@@ -63,21 +63,6 @@ function checkFileExists(dirPath: string, dirName: string, fileName: string): Ch
   return null;
 }
 
-/**
- * Within-migration snapshot-consistency check (PN-MIG-CHECK-005).
- *
- * Compares the migration's stored `metadata.to` against the `storageHash`
- * recorded in its on-disk `end-contract.json` snapshot. The two values are
- * independent on-disk records of the same fact (the migration's destination
- * contract); drift between them indicates the package is internally
- * corrupt. Cross-migration consistency (one migration's end-contract.json
- * agreeing with the next migration's start-contract.json) is a separate
- * check that requires shadow execution and is deferred to
- * `migration preflight`.
- *
- * Shared between the graph-wide and per-migration code paths so both report
- * the same failure for the same on-disk state.
- */
 function checkSnapshotConsistency(pkg: OnDiskMigrationPackage): CheckFailure | null {
   const endContractPath = join(pkg.dirPath, 'end-contract.json');
   if (!existsSync(endContractPath)) return null;
@@ -104,6 +89,27 @@ function checkSnapshotConsistency(pkg: OnDiskMigrationPackage): CheckFailure | n
   return null;
 }
 
+async function loadAggregateIntegrityViolations(
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  migrationsDir: string,
+): Promise<readonly IntegrityViolation[]> {
+  try {
+    const contractJsonContent = await readFile(resolveContractPath(config), 'utf-8');
+    const familyInstance = config.family.create(createControlStack(config));
+    const declaredExtensions = toDeclaredExtensionsFromRaw(config.extensionPacks ?? []);
+
+    const parsedAppContract: unknown = JSON.parse(contractJsonContent);
+    const aggregate = await loadContractSpaceAggregate({
+      migrationsDir,
+      deserializeContract: (json: unknown) => familyInstance.deserializeContract(json),
+      appContract: familyInstance.deserializeContract(parsedAppContract),
+    });
+    return aggregate.checkIntegrity({ declaredExtensions, checkContracts: true });
+  } catch {
+    return [];
+  }
+}
+
 async function executeMigrationCheckCommand(
   target: string | undefined,
   options: MigrationCheckOptions,
@@ -111,10 +117,8 @@ async function executeMigrationCheckCommand(
   ui: TerminalUI,
 ): Promise<{ result: MigrationCheckResult; exitCode: number }> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
+    resolveMigrationPaths(options.config, config);
 
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
@@ -135,37 +139,9 @@ async function executeMigrationCheckCommand(
 
   const failures: CheckFailure[] = [];
 
-  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
-  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
-  try {
-    const loaded = await loadMigrationPackages(appMigrationsDir);
-    bundles = loaded.bundles;
-    graph = loaded.graph;
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      const pnCode =
-        error.code === 'MIGRATION.HASH_MISMATCH' ? 'PN-MIG-CHECK-001' : 'PN-MIG-CHECK-002';
-      // Normalise to a cwd-relative path. `error.details.dir` is absolute
-      // (the migration-tools layer doesn't know the caller's cwd); the
-      // `filePath` fallback is also absolute. Surfacing the relative form
-      // matches the rest of the command's `where` shape and keeps `--json`
-      // consumers from having to special-case the bootstrap-failure path.
-      const rawWhere =
-        (error.details?.['dir'] as string) ?? (error.details?.['filePath'] as string) ?? null;
-      const where = rawWhere ? relative(process.cwd(), rawWhere) : 'unknown';
-      failures.push({
-        pnCode,
-        where,
-        why: error.why,
-        fix: error.fix,
-      });
-      return {
-        result: { ok: false, failures, summary: `${failures.length} integrity failure(s)` },
-        exitCode: INTEGRITY_FAILED,
-      };
-    }
-    throw error;
-  }
+  const loaded = await readMigrationsDir(appMigrationsDir);
+  const bundles: readonly OnDiskMigrationPackage[] = loaded.packages;
+  const graph = reconstructGraph(bundles);
 
   if (existsSync(appMigrationsDir)) {
     const loadedDirNames = new Set(bundles.map((p) => p.dirName));
@@ -236,29 +212,9 @@ async function executeMigrationCheckCommand(
       });
     }
 
-    // PN-MIG-CHECK-005 must fire per-migration as well as graph-wide; both
-    // call sites delegate to the shared helper so the same on-disk drift
-    // produces the same failure regardless of how the user invoked check.
     const snapshotFailure = checkSnapshotConsistency(matchedPkg);
     if (snapshotFailure) failures.push(snapshotFailure);
   } else {
-    for (const pkg of bundles) {
-      for (const f of ['migration.json', 'ops.json']) {
-        const fail = checkFileExists(pkg.dirPath, pkg.dirName, f);
-        if (fail) failures.push(fail);
-      }
-
-      const verification = verifyMigrationHash(pkg);
-      if (!verification.ok) {
-        failures.push({
-          pnCode: 'PN-MIG-CHECK-001',
-          where: migrationFileRelative(pkg.dirPath, 'migration.json'),
-          why: `Stored hash ${verification.storedHash} does not match recomputed hash ${verification.computedHash}`,
-          fix: 'Re-emit the migration package or restore from version control.',
-        });
-      }
-    }
-
     for (const pkg of bundles) {
       const snapshotFailure = checkSnapshotConsistency(pkg);
       if (snapshotFailure) failures.push(snapshotFailure);
@@ -295,6 +251,10 @@ async function executeMigrationCheckCommand(
     } catch {
       // Refs unreadable — skip ref checks
     }
+
+    for (const violation of await loadAggregateIntegrityViolations(config, migrationsDir)) {
+      failures.push(integrityViolationToCheckFailure(violation, migrationsDir));
+    }
   }
 
   if (failures.length === 0) {

package/src/commands/migration-graph.ts

@@ -1,26 +1,22 @@
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { MigrationGraph } from '@prisma-next/migration-tools/graph';
-import { readRefs } from '@prisma-next/migration-tools/refs';
-import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
-import {
-  type CliStructuredError,
-  errorUnexpected,
-  mapMigrationToolsError,
-} from '../utils/cli-errors';
+import type { CliStructuredError } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
-  readContractEnvelope,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   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 { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
@@ -31,6 +27,8 @@ import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 interface MigrationGraphOptions extends CommonCommandOptions {
   readonly config?: string;
   readonly dot?: boolean;
+  readonly tree?: boolean;
+  readonly ascii?: boolean;
 }
 
 export interface MigrationGraphResult {
@@ -41,13 +39,13 @@ export interface MigrationGraphResult {
   readonly summary: string;
 }
 
-async function executeMigrationGraphCommand(
+export async function executeMigrationGraphCommand(
   options: MigrationGraphOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationGraphResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+  const { configPath, appMigrationsRelative, migrationsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -65,37 +63,18 @@ async function executeMigrationGraphCommand(
     ui.stderr(header);
   }
 
-  let graph: MigrationGraph;
-  try {
-    ({ graph } = await loadMigrationPackages(appMigrationsDir));
-  } catch (error) {
-    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read migrations: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
+  const loaded = await buildReadAggregate(config, { migrationsDir });
+  if (!loaded.ok) {
+    return loaded;
   }
 
-  let contractHash: string | null = null;
-  try {
-    const envelope = await readContractEnvelope(config);
-    contractHash = envelope.storageHash;
-  } catch {
-    // Contract unreadable — render graph without contract marker
-  }
-
-  let refs: readonly StatusRef[] = [];
-  try {
-    const allRefs = await readRefs(refsDir);
-    refs = Object.entries(allRefs).map(([name, entry]) => ({
-      name,
-      hash: entry.hash,
-      active: false,
-    }));
-  } catch {
-    // Refs unreadable — render graph without ref markers
-  }
+  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,
+  }));
 
   return ok({
     ok: true,
@@ -111,14 +90,18 @@ export function createMigrationGraphCommand(): Command {
   setCommandDescriptions(
     command,
     'Show the migration graph topology',
-    'Renders the migration graph as an ASCII tree. Offline — does not\n' +
-      'consult the database. Use --json for machine-readable output or\n' +
-      '--dot for Graphviz DOT format.',
+    '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' +
+      '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',
   ]);
   setCommandSeeAlso(command, [
     { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
@@ -129,6 +112,8 @@ export function createMigrationGraphCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--dot', 'Output in Graphviz DOT format')
+    .option('--tree', 'Experimental condensed annotated tree renderer')
+    .option('--ascii', 'Use ASCII glyphs for --tree (pipe-friendly)')
     .action(async (options: MigrationGraphOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
@@ -160,22 +145,52 @@ export function createMigrationGraphCommand(): Command {
             JSON.stringify({ ok: true, nodes, edges, summary: graphResult.summary }, null, 2),
           );
         } else if (!flags.quiet) {
-          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}`);
+          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}`);
+          }
         }
       });
       process.exit(exitCode);