@prisma-next/cli 0.8.0-dev.7 → 0.8.0-dev.8

package/src/commands/migration-list.ts

@@ -0,0 +1,155 @@
+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 { notOk, 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 {
+  addGlobalOptions,
+  loadMigrationPackages,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+  setCommandExamples,
+  setCommandSeeAlso,
+} from '../utils/command-helpers';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import type { CommonCommandOptions } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface MigrationListOptions extends CommonCommandOptions {
+  readonly config?: string;
+}
+
+export interface MigrationListEntry {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly operationCount: number;
+  readonly createdAt: string;
+}
+
+export interface MigrationListResult {
+  readonly ok: true;
+  readonly migrations: readonly MigrationListEntry[];
+  readonly summary: string;
+}
+
+async function executeMigrationListCommand(
+  options: MigrationListOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<Result<MigrationListResult, CliStructuredError>> {
+  const config = await loadConfig(options.config);
+  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  if (!flags.json && !flags.quiet) {
+    const header = formatStyledHeader({
+      command: 'migration list',
+      description: 'List on-disk migrations in topological order',
+      details: [
+        { label: 'config', value: configPath },
+        { label: 'migrations', value: appMigrationsRelative },
+      ],
+      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 leaves = [...graph.nodes].filter(
+    (n) => !graph.forwardChain.has(n) || graph.forwardChain.get(n)!.length === 0,
+  );
+  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`,
+  });
+}
+
+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.',
+  );
+  setCommandExamples(command, ['prisma-next migration list']);
+  setCommandSeeAlso(command, [
+    { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
+    { verb: 'migration log', oneLiner: 'Show executed migration history' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
+  ]);
+  addGlobalOptions(command)
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (options: MigrationListOptions) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const result = await executeMigrationListCommand(options, flags, ui);
+      const exitCode = handleResult(result, flags, ui, (listResult) => {
+        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}`);
+          }
+        }
+      });
+      process.exit(exitCode);
+    });
+  return command;
+}

package/src/commands/migration-log.ts

@@ -0,0 +1,218 @@
+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 { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { cyan, dim } from 'colorette';
+import { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import { createControlClient } from '../control-api/client';
+import {
+  type CliStructuredError,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  loadMigrationPackages,
+  maskConnectionUrl,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+  setCommandExamples,
+  setCommandSeeAlso,
+  targetSupportsMigrations,
+} from '../utils/command-helpers';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import type { CommonCommandOptions } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface MigrationLogOptions extends CommonCommandOptions {
+  readonly db?: string;
+  readonly config?: string;
+}
+
+export interface MigrationLogEntry {
+  readonly dirName: string;
+  readonly from: string;
+  readonly to: string;
+  readonly migrationHash: string;
+  readonly operationCount: number;
+  readonly createdAt: string;
+}
+
+export interface MigrationLogResult {
+  readonly ok: true;
+  readonly markerHash: string | null;
+  readonly applied: readonly MigrationLogEntry[];
+  readonly summary: string;
+}
+
+async function executeMigrationLogCommand(
+  options: MigrationLogOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<Result<MigrationLogResult, CliStructuredError>> {
+  const config = await loadConfig(options.config);
+  const { configPath, appMigrationsDir, appMigrationsRelative } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  const dbConnection = options.db ?? config.db?.connection;
+  if (!dbConnection) {
+    return notOk(
+      errorDatabaseConnectionRequired({
+        why: `Database connection is required for migration log (set db.connection in ${configPath}, or pass --db <url>)`,
+        commandName: 'migration log',
+      }),
+    );
+  }
+  if (!config.driver) {
+    return notOk(errorDriverRequired({ why: 'Config.driver is required for migration log' }));
+  }
+  if (!targetSupportsMigrations(config.target)) {
+    return notOk(errorUnexpected('Target does not support migrations'));
+  }
+
+  if (!flags.json && !flags.quiet) {
+    const header = formatStyledHeader({
+      command: 'migration log',
+      description: 'Show executed migration history',
+      details: [
+        { label: 'config', value: configPath },
+        { label: 'migrations', value: appMigrationsRelative },
+        ...(typeof dbConnection === 'string'
+          ? [{ label: 'database', value: maskConnectionUrl(dbConnection) }]
+          : []),
+      ],
+      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)}`,
+      }),
+    );
+  }
+
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    driver: config.driver,
+    extensionPacks: config.extensionPacks ?? [],
+  });
+
+  try {
+    await client.connect(dbConnection);
+    const marker = await client.readMarker();
+    const markerHash = marker?.storageHash ?? null;
+
+    if (!markerHash) {
+      return ok({
+        ok: true,
+        markerHash: null,
+        applied: [],
+        summary: 'No migrations applied (database has no marker)',
+      });
+    }
+
+    const appliedPath = findPath(graph, EMPTY_CONTRACT_HASH, markerHash);
+    if (appliedPath === null) {
+      return notOk(
+        errorUnexpected('Database marker is not reachable from migration history', {
+          why: `Marker hash ${markerHash} is not reachable from the root of the on-disk migration graph.`,
+          fix: 'The database may have been migrated outside this project. Use `migration status` to inspect the current state.',
+        }),
+      );
+    }
+    const pkgByDirName = new Map(bundles.map((p) => [p.dirName, p]));
+    const entries: MigrationLogEntry[] = appliedPath.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,
+      markerHash,
+      applied: entries,
+      summary: `${entries.length} migration(s) applied`,
+    });
+  } catch (error) {
+    if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read migration log: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  } finally {
+    await client.close();
+  }
+}
+
+export function createMigrationLogCommand(): Command {
+  const command = new Command('log');
+  setCommandDescriptions(
+    command,
+    'Show executed migration history',
+    'Reads the database marker and displays the applied migration chain\n' +
+      'from the initial state to the current marker position.',
+  );
+  setCommandExamples(command, [
+    'prisma-next migration log --db $DATABASE_URL',
+    'prisma-next migration log --json --db $DATABASE_URL',
+  ]);
+  setCommandSeeAlso(command, [
+    { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
+    { verb: 'migration list', oneLiner: 'List on-disk migrations' },
+    { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
+    { verb: 'migration show', oneLiner: 'Display migration package contents' },
+  ]);
+  addGlobalOptions(command)
+    .option('--db <url>', 'Database connection string')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (options: MigrationLogOptions) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const result = await executeMigrationLogCommand(options, flags, ui);
+      const exitCode = handleResult(result, flags, ui, (logResult) => {
+        if (flags.json) {
+          ui.output(JSON.stringify(logResult, null, 2));
+        } else if (!flags.quiet) {
+          const c = (fn: (s: string) => string, s: string) => (flags.color !== false ? fn(s) : s);
+          if (logResult.applied.length === 0) {
+            ui.log(logResult.summary);
+          } else {
+            for (const entry of logResult.applied) {
+              ui.log(
+                `${c(cyan, '✓')} ${entry.dirName}  ${c(dim, entry.migrationHash.slice(0, 16) + '…')}  ${entry.operationCount} op(s)`,
+              );
+            }
+            ui.log(`\n${logResult.summary}`);
+          }
+        }
+      });
+      process.exit(exitCode);
+    });
+  return command;
+}

package/src/commands/migration-plan.ts

@@ -18,6 +18,8 @@ import {
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import { findLatestMigration } from '@prisma-next/migration-tools/migration-graph';
 import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { join, relative } from 'pathe';
@@ -28,10 +30,10 @@ import {
   errorContractValidationFailed,
   errorFileNotFound,
   errorMigrationPlanningFailed,
-  errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -102,7 +104,7 @@ export interface MigrationPlanResult {
    * Surfacing these in the result (rather than only via `ui.step` log
    * lines) makes the cross-space side effect explicit to JSON consumers
    * and the success-summary renderer — the same multi-space side effect
-   * that `migration apply` will replay.
+   * that `migrate` will replay.
    */
   readonly emittedExtensionDirs: readonly { readonly spaceId: string; readonly dirName: string }[];
   readonly operations: readonly {
@@ -214,23 +216,25 @@ async function executeMigrationPlanCommand(
     const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
 
     if (options.from) {
-      const resolved = resolveBundleByPrefix(bundles, options.from);
-      if (!resolved.ok) {
-        const f = resolved.failure;
+      const refs = await readRefs(resolveMigrationPaths(options.config, config).refsDir);
+      const refResult = parseContractRef(options.from, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      fromHash = refResult.value.hash;
+      const matchingBundle = bundles.find((p) => p.metadata.to === fromHash);
+      if (!matchingBundle) {
         return notOk(
-          f.reason === 'ambiguous'
-            ? errorRuntime('Multiple matching migrations found', {
-                why: `Prefix "${options.from}" matches ${f.count} migrations in ${appMigrationsRelative}`,
-                fix: 'Provide a longer prefix to disambiguate, or omit --from to use the latest migration target.',
-              })
-            : 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, or omit --from to use the latest migration target.',
-              }),
+          errorUnexpected(
+            `No migration bundle found for --from "${options.from}" (resolved hash: ${fromHash})`,
+            {
+              why: `The ref resolved successfully but no on-disk migration package has an end-contract hash matching ${fromHash}.`,
+              fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
+            },
+          ),
         );
       }
-      fromHash = resolved.value.metadata.to;
-      fromContractSourceDir = resolved.value.dirPath;
+      fromContractSourceDir = matchingBundle.dirPath;
       fromContract = await readPredecessorEndContract(fromContractSourceDir);
     } else {
       const latestMigration = findLatestMigration(graph);
@@ -523,7 +527,10 @@ export function createMigrationPlanCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--name <slug>', 'Name slug for the migration directory', 'migration')
-    .option('--from <hash>', 'Explicit starting contract hash (overrides latest migration target)')
+    .option(
+      '--from <contract>',
+      'Starting contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
     .action(async (options: MigrationPlanOptions) => {
       const flags = parseGlobalFlags(options);
       const startTime = Date.now();
@@ -589,7 +596,7 @@ export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: Gl
     }
     lines.push('');
     lines.push(
-      `Next: review the extension migrations above, then run ${green_('prisma-next migration apply')}.`,
+      `Next: review the extension migrations above, then run ${green_('prisma-next migrate')}.`,
     );
   }
 
@@ -660,11 +667,11 @@ export function formatMigrationPlanOutput(result: MigrationPlanResult, flags: Gl
 
   lines.push('');
   // The "Next:" hint always points at the canonical apply path
-  // (`prisma-next migration apply`) regardless of how many spaces
-  // were materialised — `db update` is a dev-time convenience, not
-  // the canonical replay step.
+  // (`prisma-next migrate`) regardless of how many spaces were
+  // materialised — `db update` is a dev-time convenience, not the
+  // canonical replay step.
   lines.push(
-    `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migration apply')}.`,
+    `Next: review ${green_(result.dir ?? '<dir>')} if needed, then run ${green_('prisma-next migrate')}.`,
   );
 
   if (result.preview && result.preview.statements.length > 0) {