@prisma-next/cli 0.11.0 → 0.12.0

package/src/commands/migration-list.ts

@@ -1,55 +1,220 @@
-import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
-import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
-import { findPath } from '@prisma-next/migration-tools/migration-graph';
+import type {
+  ContractSpaceAggregate,
+  ContractSpaceMember,
+} from '@prisma-next/migration-tools/aggregate';
+import { HEAD_REF_NAME, refsByContractHash } from '@prisma-next/migration-tools/refs';
+import {
+  APP_SPACE_ID,
+  isValidSpaceId,
+  listContractSpaceDirectories,
+  RESERVED_SPACE_SUBDIR_NAMES,
+} from '@prisma-next/migration-tools/spaces';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import {
   type CliStructuredError,
-  errorUnexpected,
-  mapMigrationToolsError,
+  errorInvalidSpaceId,
+  errorSpaceNotFound,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
   setCommandSeeAlso,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
+import {
+  buildMigrationListTopologyBySpace,
+  renderMigrationListWithStyle,
+} from '../utils/formatters/migration-list-render';
+import { createAnsiMigrationListStyler } from '../utils/formatters/migration-list-styler';
+import type {
+  MigrationListEntry,
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from '../utils/formatters/migration-list-types';
 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 { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
+function compareSpaceIds(a: string, b: string): number {
+  if (a === APP_SPACE_ID) return b === APP_SPACE_ID ? 0 : -1;
+  if (b === APP_SPACE_ID) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function compareDirNamesDescending(a: MigrationListEntry, b: MigrationListEntry): number {
+  if (a.dirName < b.dirName) return 1;
+  if (a.dirName > b.dirName) return -1;
+  return 0;
+}
+
+/**
+ * Ref names decorating a space's destination contract hashes. The
+ * tolerant `member.refs` deliberately omits the structural `head.json`;
+ * for extension spaces the old enumerator surfaced it as a `head`
+ * decoration on the tip migration, so fold `member.headRef` back in to
+ * keep that output. The app space synthesises its head, so it carries
+ * no on-disk `head` ref to restore.
+ */
+function listRefsByContractHash(
+  member: ContractSpaceMember,
+): ReadonlyMap<string, readonly string[]> {
+  const byHash = new Map(refsByContractHash(member.refs));
+  if (member.spaceId !== APP_SPACE_ID && member.headRef !== null) {
+    const hash = member.headRef.hash;
+    const bucket = byHash.get(hash) ?? [];
+    if (!bucket.includes(HEAD_REF_NAME)) {
+      byHash.set(hash, [...bucket, HEAD_REF_NAME].sort());
+    }
+  }
+  return byHash;
+}
+
+async function orderedOnDiskSpaceIds(projectMigrationsDir: string): Promise<readonly string[]> {
+  const candidateDirs = await listContractSpaceDirectories(projectMigrationsDir);
+  return candidateDirs
+    .filter((name) => !RESERVED_SPACE_SUBDIR_NAMES.has(name))
+    .filter(isValidSpaceId)
+    .sort(compareSpaceIds);
+}
+
+/**
+ * Project the loaded {@link ContractSpaceAggregate} into the render-ready
+ * {@link MigrationSpaceListEntry} rows `migration list` displays.
+ *
+ * Space membership matches the on-disk contract-space directories (not the
+ * aggregate's always-present synthesized app member when `migrations/app/`
+ * is absent); package and ref data come from `aggregate.space(id)`.
+ */
+export async function migrationSpaceListEntriesFromAggregate(
+  aggregate: ContractSpaceAggregate,
+  projectMigrationsDir: string,
+): Promise<readonly MigrationSpaceListEntry[]> {
+  const spaceIds = await orderedOnDiskSpaceIds(projectMigrationsDir);
+  const spaces: MigrationSpaceListEntry[] = [];
+
+  for (const spaceId of spaceIds) {
+    const member = aggregate.space(spaceId);
+    if (member === undefined) {
+      continue;
+    }
+    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,
+        operationCount: pkg.ops.length,
+        createdAt: pkg.metadata.createdAt,
+        refs: refsByHash.get(pkg.metadata.to) ?? [],
+        providedInvariants: pkg.metadata.providedInvariants,
+      }))
+      .sort(compareDirNamesDescending);
+
+    spaces.push({ spaceId, migrations });
+  }
+
+  return spaces;
+}
+
 interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
+  readonly space?: string;
+  readonly ascii?: boolean;
+}
+
+export interface MigrationListHumanRenderOptions {
+  readonly glyphMode: GlyphMode;
+  readonly useColor: boolean;
+}
+
+export function renderMigrationListHumanOutput(
+  result: MigrationListResult,
+  options: MigrationListHumanRenderOptions,
+): string {
+  const styler = createAnsiMigrationListStyler({ useColor: options.useColor });
+  const topologyBySpaceId = buildMigrationListTopologyBySpace(result);
+  return renderMigrationListWithStyle(result, styler, options.glyphMode, topologyBySpaceId);
 }
 
-export interface MigrationListEntry {
-  readonly dirName: string;
-  readonly from: string;
-  readonly to: string;
-  readonly migrationHash: string;
-  readonly operationCount: number;
-  readonly createdAt: string;
+/**
+ * Inputs for {@link runMigrationList} — the policy core of `migration list`
+ * that tests exercise directly.
+ *
+ * The core does not call `loadConfig`, parse CLI flags, render a styled
+ * header, or write to any stream. Enumeration is supplied by the caller
+ * (the CLI shell builds it from {@link migrationSpaceListEntriesFromAggregate}).
+ */
+export interface RunMigrationListInputs {
+  readonly spaces: readonly MigrationSpaceListEntry[];
+  readonly spaceFilter?: string;
 }
 
-export interface MigrationListResult {
-  readonly ok: true;
-  readonly migrations: readonly MigrationListEntry[];
-  readonly summary: string;
+function computeSummary(spaces: readonly MigrationSpaceListEntry[]): string {
+  const totalMigrations = spaces.reduce((count, space) => count + space.migrations.length, 0);
+  if (spaces.length <= 1) {
+    return `${totalMigrations} migration(s) on disk`;
+  }
+  return `${totalMigrations} migration(s) across ${spaces.length} contract space(s)`;
+}
+
+/**
+ * Policy core of `migration list`: validates `--space`, narrows the
+ * pre-enumerated spaces, and assembles a {@link MigrationListResult}.
+ *
+ * - `migrations/` missing or contains no valid space directories →
+ *   caller passes `spaces: []`; this synthesizes `[{ spaceId: APP_SPACE_ID, migrations: [] }]`.
+ * - `--space <id>` on an existing-but-empty space → `{ spaceId, migrations: [] }` in the input.
+ * - `--space <id>` on a non-existent (or reserved) space → `SPACE_NOT_FOUND`.
+ */
+export function runMigrationList(
+  inputs: RunMigrationListInputs,
+): Result<MigrationListResult, CliStructuredError> {
+  const { spaces, spaceFilter } = inputs;
+
+  if (spaceFilter !== undefined && !isValidSpaceId(spaceFilter)) {
+    return notOk(errorInvalidSpaceId(spaceFilter));
+  }
+
+  if (spaceFilter !== undefined && !spaces.some((s) => s.spaceId === spaceFilter)) {
+    return notOk(errorSpaceNotFound(spaceFilter, spaces.map((s) => s.spaceId).sort()));
+  }
+
+  const scopedSpaces =
+    spaceFilter !== undefined ? spaces.filter((s) => s.spaceId === spaceFilter) : spaces;
+
+  const resultSpaces: readonly MigrationSpaceListEntry[] =
+    scopedSpaces.length === 0 ? [{ spaceId: APP_SPACE_ID, migrations: [] }] : scopedSpaces;
+
+  return ok({
+    ok: true,
+    spaces: resultSpaces,
+    summary: computeSummary(resultSpaces),
+  });
 }
 
-async function executeMigrationListCommand(
+/**
+ * CLI shell: loads config, resolves paths, prints the styled header on
+ * stderr (interactive mode only), and delegates to {@link runMigrationList}.
+ * Kept intentionally thin so the unit-testable surface lives in the core.
+ */
+export async function executeMigrationListCommand(
   options: MigrationListOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationListResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+  const { configPath, migrationsDir, migrationsRelative } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -57,58 +222,30 @@ async function executeMigrationListCommand(
   if (!flags.json && !flags.quiet) {
     const header = formatStyledHeader({
       command: 'migration list',
-      description: 'List on-disk migrations in topological order',
+      description: 'List on-disk migrations, latest first, per contract space',
       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);
   }
 
-  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
-  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
-  try {
-    ({ bundles, 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)}`,
-      }),
-    );
-  }
-
-  if (bundles.length === 0) {
-    return ok({ ok: true, migrations: [], summary: 'No migrations found' });
+  const loaded = await buildReadAggregate(config, { migrationsDir });
+  if (!loaded.ok) {
+    return notOk(loaded.failure);
   }
 
-  const leaves = [...graph.nodes].filter(
-    (n) => !graph.forwardChain.has(n) || graph.forwardChain.get(n)!.length === 0,
+  const spaces = await migrationSpaceListEntriesFromAggregate(
+    loaded.value.aggregate,
+    migrationsDir,
   );
-  const targetHash =
-    leaves.length === 1 ? leaves[0]! : ([...graph.nodes].values().next().value as string);
-  const chain = findPath(graph, EMPTY_CONTRACT_HASH, targetHash) ?? [];
-
-  const pkgByDirName = new Map(bundles.map((p) => [p.dirName, p]));
-  const entries: MigrationListEntry[] = chain.map((edge) => {
-    const pkg = pkgByDirName.get(edge.dirName);
-    const ops = (pkg?.ops ?? []) as readonly MigrationPlanOperation[];
-    return {
-      dirName: edge.dirName,
-      from: edge.from,
-      to: edge.to,
-      migrationHash: edge.migrationHash,
-      operationCount: ops.length,
-      createdAt: edge.createdAt,
-    };
-  });
 
-  return ok({
-    ok: true,
-    migrations: entries,
-    summary: `${entries.length} migration(s) on disk`,
+  return runMigrationList({
+    spaces,
+    ...ifDefined('spaceFilter', options.space),
   });
 }
 
@@ -116,11 +253,22 @@ export function createMigrationListCommand(): Command {
   const command = new Command('list');
   setCommandDescriptions(
     command,
-    'List on-disk migrations in topological order',
-    'Enumerates all migration packages under migrations/<space>/ in\n' +
-      'topological order. Offline — does not consult the database.',
+    'List on-disk migrations, latest first, 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).',
   );
-  setCommandExamples(command, ['prisma-next migration list']);
+  setCommandExamples(command, [
+    'prisma-next migration list',
+    'prisma-next migration list --space app',
+    'prisma-next migration list --ascii',
+    'prisma-next migration list --json',
+  ]);
   setCommandSeeAlso(command, [
     { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
     { verb: 'migration log', oneLiner: 'Show executed migration history' },
@@ -129,6 +277,8 @@ export function createMigrationListCommand(): Command {
   ]);
   addGlobalOptions(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)')
     .action(async (options: MigrationListOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
@@ -137,16 +287,12 @@ export function createMigrationListCommand(): Command {
         if (flags.json) {
           ui.output(JSON.stringify(listResult, null, 2));
         } else if (!flags.quiet) {
-          if (listResult.migrations.length === 0) {
-            ui.log('No migrations found');
-          } else {
-            for (const entry of listResult.migrations) {
-              ui.log(
-                `${entry.dirName}  ${entry.migrationHash.slice(0, 16)}…  ${entry.operationCount} op(s)`,
-              );
-            }
-            ui.log(`\n${listResult.summary}`);
-          }
+          ui.output(
+            renderMigrationListHumanOutput(listResult, {
+              glyphMode: ui.resolveGlyphMode(options.ascii === true),
+              useColor: ui.useColor,
+            }),
+          );
         }
       });
       process.exit(exitCode);

package/src/commands/migration-log.ts

@@ -16,7 +16,6 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   maskConnectionUrl,
   resolveMigrationPaths,
   setCommandDescriptions,
@@ -24,6 +23,7 @@ import {
   setCommandSeeAlso,
   targetSupportsMigrations,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
@@ -51,13 +51,13 @@ export interface MigrationLogResult {
   readonly summary: string;
 }
 
-async function executeMigrationLogCommand(
+export async function executeMigrationLogCommand(
   options: MigrationLogOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<MigrationLogResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+  const { configPath, appMigrationsRelative, migrationsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -94,18 +94,12 @@ async function executeMigrationLogCommand(
     ui.stderr(header);
   }
 
-  let bundles: Awaited<ReturnType<typeof loadMigrationPackages>>['bundles'];
-  let graph: Awaited<ReturnType<typeof loadMigrationPackages>>['graph'];
-  try {
-    ({ bundles, 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;
   }
+  const graph = loaded.value.aggregate.app.graph();
+  const bundles = loaded.value.aggregate.app.packages;
 
   const client = createControlClient({
     family: config.family,

package/src/commands/migration-new.ts

@@ -12,19 +12,15 @@ import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { APP_SPACE_ID, createControlStack } from '@prisma-next/framework-components/control';
-import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { loadContractSpaceAggregate } from '@prisma-next/migration-tools/aggregate';
 import { computeMigrationHash } from '@prisma-next/migration-tools/hash';
 import {
   copyFilesWithRename,
   formatMigrationDirName,
-  readMigrationsDir,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
-import {
-  findLatestMigration,
-  reconstructGraph,
-} from '@prisma-next/migration-tools/migration-graph';
+import { findLatestMigration } from '@prisma-next/migration-tools/migration-graph';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -36,7 +32,6 @@ import {
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
-  mapMigrationToolsError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -46,6 +41,7 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { refusePackageCorruptionOnAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
@@ -71,7 +67,10 @@ async function executeMigrationNewCommand(
   options: MigrationNewOptions,
 ): Promise<Result<MigrationNewResult, CliStructuredError>> {
   const config = await loadConfig(options.config);
-  const { appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(options.config, config);
+  const { migrationsDir, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
 
   // Construct the family instance up-front so the on-disk contract read
   // below crosses the serializer seam (`familyInstance.deserializeContract`)
@@ -98,7 +97,8 @@ async function executeMigrationNewCommand(
 
   let toContract: Contract;
   try {
-    toContract = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
+    const parsedContract: unknown = JSON.parse(contractJsonContent);
+    toContract = familyInstance.deserializeContract(parsedContract);
   } catch (error) {
     return notOk(
       errorRuntime('Contract JSON is invalid', {
@@ -118,45 +118,47 @@ async function executeMigrationNewCommand(
     );
   }
 
-  let fromHash: string | null = null;
-  let fromContractSourceDir: string | null = null;
+  const aggregate = await loadContractSpaceAggregate({
+    migrationsDir,
+    deserializeContract: (json) => familyInstance.deserializeContract(json),
+    appContract: toContract,
+  });
+  const packageCorruptionFailure = refusePackageCorruptionOnAggregate(aggregate);
+  if (packageCorruptionFailure) {
+    return notOk(packageCorruptionFailure);
+  }
 
-  try {
-    const packages = await readMigrationsDir(appMigrationsDir);
+  const packages = aggregate.app.packages;
+  const graph = aggregate.app.graph();
 
-    if (packages.length > 0) {
-      const graph = reconstructGraph(packages);
+  let fromHash: string | null = null;
+  let fromContractSourceDir: string | null = null;
 
-      if (options.from) {
-        const match = packages.find((p) => p.metadata.to.startsWith(options.from!));
-        if (!match) {
-          return notOk(
-            errorRuntime('Starting contract not found', {
-              why: `No migration with to hash matching "${options.from}" exists in ${appMigrationsRelative}`,
-              fix: 'Check that the --from hash matches a known migration target hash.',
-            }),
-          );
-        }
-        fromHash = match.metadata.to;
-        fromContractSourceDir = match.dirPath;
-      } else {
-        const latestMigration = findLatestMigration(graph);
-        if (latestMigration) {
-          fromHash = latestMigration.to;
-          const leafPkg = packages.find(
-            (p) => p.metadata.migrationHash === latestMigration.migrationHash,
-          );
-          if (leafPkg) {
-            fromContractSourceDir = leafPkg.dirPath;
-          }
+  if (packages.length > 0) {
+    if (options.from) {
+      const match = packages.find((p) => p.metadata.to.startsWith(options.from!));
+      if (!match) {
+        return notOk(
+          errorRuntime('Starting contract not found', {
+            why: `No migration with to hash matching "${options.from}" exists in ${appMigrationsRelative}`,
+            fix: 'Check that the --from hash matches a known migration target hash.',
+          }),
+        );
+      }
+      fromHash = match.metadata.to;
+      fromContractSourceDir = match.dirPath;
+    } else {
+      const latestMigration = findLatestMigration(graph);
+      if (latestMigration) {
+        fromHash = latestMigration.to;
+        const leafPkg = packages.find(
+          (p) => p.metadata.migrationHash === latestMigration.migrationHash,
+        );
+        if (leafPkg) {
+          fromContractSourceDir = leafPkg.dirPath;
         }
       }
     }
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      return notOk(mapMigrationToolsError(error));
-    }
-    throw error;
   }
 
   if (fromHash === toStorageHash && !options.from) {
@@ -180,12 +182,6 @@ async function executeMigrationNewCommand(
   const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: fromHash,
     to: toStorageHash,
-    hints: {
-      used: [],
-      applied: [],
-      plannerVersion: '1.0.0',
-    },
-    labels: [],
     providedInvariants: [],
     createdAt: timestamp.toISOString(),
   };