@prisma-next/cli 0.12.0-dev.39 → 0.12.0-dev.40

package/src/commands/migration-log.ts

@@ -1,15 +1,15 @@
 import type { LedgerEntryRecord } from '@prisma-next/contract/types';
 import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+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 { createControlClient } from '../control-api/client';
 import {
   CliStructuredError,
-  errorDatabaseConnectionRequired,
-  errorDriverRequired,
   errorUnexpected,
   mapMigrationToolsError,
+  requireLiveDatabase,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -24,6 +24,7 @@ import { createAnsiMigrationListStyler } from '../utils/formatters/migration-lis
 import {
   MIGRATION_LOG_EMPTY_MESSAGE,
   renderMigrationLogTable,
+  type SerializedLedgerEntryRecord,
   serializeLedgerEntriesForJson,
 } from '../utils/formatters/migration-log-table';
 import { formatStyledHeader } from '../utils/formatters/styled';
@@ -36,6 +37,12 @@ interface MigrationLogOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
   readonly utc?: boolean;
+  readonly ascii?: boolean;
+}
+
+export interface MigrationLogResult {
+  readonly ok: true;
+  readonly entries: readonly SerializedLedgerEntryRecord[];
 }
 
 export async function executeMigrationLogCommand(
@@ -47,16 +54,14 @@ export async function executeMigrationLogCommand(
   const { configPath } = 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' }));
+  const missingDb = requireLiveDatabase({
+    dbConnection,
+    hasDriver: !!config.driver,
+    why: `migration log needs a database connection and driver to read the ledger (set db.connection in ${configPath}, or pass --db <url>)`,
+    commandName: 'migration log',
+  });
+  if (missingDb) {
+    return notOk(missingDb);
   }
   if (!targetSupportsMigrations(config.target)) {
     return notOk(errorUnexpected('Target does not support migrations'));
@@ -81,7 +86,7 @@ export async function executeMigrationLogCommand(
     family: config.family,
     target: config.target,
     adapter: config.adapter,
-    driver: config.driver,
+    ...ifDefined('driver', config.driver),
     extensionPacks: config.extensionPacks ?? [],
   });
 
@@ -108,7 +113,8 @@ export function createMigrationLogCommand(): Command {
     command,
     'Show executed migration history',
     'Reads the database ledger and displays every applied migration edge\n' +
-      'in chronological order, including rollbacks and re-applies.',
+      'in chronological order, including rollbacks and re-applies, merged\n' +
+      'across all contract spaces. Requires a database connection.',
   );
   setCommandExamples(command, [
     'prisma-next migration log --db $DATABASE_URL',
@@ -125,19 +131,30 @@ export function createMigrationLogCommand(): Command {
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--utc', 'Render human timestamps in UTC instead of local time')
+    .option('--ascii', 'Use ASCII glyphs (pipe-friendly)')
     .action(async (options: MigrationLogOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);
       const result = await executeMigrationLogCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (entries) => {
         if (flags.json) {
-          ui.output(JSON.stringify(serializeLedgerEntriesForJson(entries), null, 2));
+          const result: MigrationLogResult = {
+            ok: true,
+            entries: serializeLedgerEntriesForJson(entries),
+          };
+          ui.output(JSON.stringify(result, null, 2));
         } else if (!flags.quiet) {
           if (entries.length === 0) {
             ui.output(MIGRATION_LOG_EMPTY_MESSAGE);
           } else {
             const styler = createAnsiMigrationListStyler({ useColor: ui.useColor });
-            ui.output(renderMigrationLogTable(entries, { utc: options.utc === true, styler }));
+            ui.output(
+              renderMigrationLogTable(entries, {
+                utc: options.utc === true,
+                styler,
+                glyphMode: ui.resolveGlyphMode(options.ascii === true),
+              }),
+            );
           }
         }
       });

package/src/commands/migration-show.ts

@@ -13,7 +13,7 @@ import { castAs } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { isAbsolute, relative, resolve } from 'pathe';
+import { relative } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import {
@@ -36,6 +36,11 @@ import { formatMigrationShowOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import {
+  findPackageByDirPath,
+  looksLikePath,
+  resolveAppTargetPath,
+} from '../utils/migration-path-target';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
@@ -65,33 +70,6 @@ export interface MigrationShowResult {
   readonly migration: MigrationShowPresent;
 }
 
-function looksLikePath(target: string): boolean {
-  return target.includes('/') || target.includes('\\');
-}
-
-export function resolveAppTargetPath(
-  target: string,
-  appMigrationsDir: string,
-  appMigrationsRelative: string,
-): Result<string, CliStructuredError> {
-  const targetPath = resolve(target);
-  const relativeToApp = relative(appMigrationsDir, targetPath);
-  const isOutsideAppDir =
-    relativeToApp === '' ||
-    relativeToApp === '.' ||
-    relativeToApp.startsWith('..') ||
-    isAbsolute(relativeToApp);
-  if (isOutsideAppDir) {
-    return notOk(
-      errorRuntime('Target must point to an app-space migration', {
-        why: `Expected a path under ${appMigrationsRelative}, got ${target}`,
-        fix: 'Pass an app-space migration directory or use a hash prefix.',
-      }),
-    );
-  }
-  return ok(targetPath);
-}
-
 function pkgToPresent(
   spaceId: string,
   pkg: OnDiskMigrationPackage,
@@ -117,14 +95,6 @@ function pkgToPresent(
   };
 }
 
-function findPackageByDirPath(
-  packages: readonly OnDiskMigrationPackage[],
-  resolvedDirPath: string,
-): OnDiskMigrationPackage | undefined {
-  const normalized = resolve(resolvedDirPath);
-  return packages.find((p) => resolve(p.dirPath) === normalized);
-}
-
 async function executeMigrationShowCommand(
   target: string,
   options: MigrationShowOptions,
@@ -260,11 +230,13 @@ export function createMigrationShowCommand(): Command {
     command,
     'Display migration package contents',
     'Shows the operations, statement preview, and metadata for one app-space migration.\n' +
-      'Accepts a directory path, directory name, or hash prefix.',
+      'Accepts a directory path, directory name, or hash prefix.\n' +
+      'Offline — does not consult the database.',
   );
   setCommandExamples(command, [
     'prisma-next migration show 20260101_100000_add_user',
     'prisma-next migration show sha256:a1b2c3',
+    'prisma-next migration show 20260101_100000_add_user --json',
   ]);
   setCommandSeeAlso(command, [
     { verb: 'migration status', oneLiner: 'Show migration path and pending status' },
@@ -273,7 +245,7 @@ export function createMigrationShowCommand(): Command {
     { verb: 'migration graph', oneLiner: 'Show the migration graph topology' },
   ]);
   addGlobalOptions(command)
-    .argument('<target>', 'Migration reference: directory name, hash/prefix, or path')
+    .argument('<target>', 'Migration reference: directory name, hash/prefix, ref, or path')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string, options: MigrationShowOptions) => {
       const flags = parseGlobalFlagsOrExit(options);

package/src/commands/migration-status.ts

@@ -21,10 +21,10 @@ import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import {
   CliStructuredError,
-  errorDatabaseConnectionRequired,
   errorUnexpected,
   mapMigrationToolsError,
   mapRefResolutionError,
+  requireLiveDatabase,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -76,6 +76,7 @@ interface MigrationStatusOptions extends CommonCommandOptions {
   readonly from?: string;
   readonly space?: string;
   readonly legend?: boolean;
+  readonly ascii?: boolean;
 }
 
 export interface MigrationStatusMigrationEntry extends MigrationListEntry {
@@ -271,13 +272,16 @@ async function executeMigrationStatusCommand(
   const hasDriver = !!config.driver;
   const usingFromOverride = options.from !== undefined;
 
-  if (!usingFromOverride && (!dbConnection || !hasDriver)) {
-    return notOk(
-      errorDatabaseConnectionRequired({
-        why: 'migration status needs a database connection to read the marker and ledger (or pass --from for offline path preview)',
-        retryCommand: 'prisma-next migration status --from <contract>',
-      }),
-    );
+  if (!usingFromOverride) {
+    const missingDb = requireLiveDatabase({
+      dbConnection,
+      hasDriver,
+      why: 'migration status needs a database connection to read the marker and ledger (or pass --from for offline path preview)',
+      retryCommand: 'prisma-next migration status --from <contract>',
+    });
+    if (missingDb) {
+      return notOk(missingDb);
+    }
   }
 
   let allRefs: Refs = {};
@@ -374,7 +378,7 @@ async function executeMigrationStatusCommand(
       ui.stderr(
         renderMigrationGraphLegend({
           colorize: flags.color !== false,
-          glyphMode: ui.resolveGlyphMode(false),
+          glyphMode: ui.resolveGlyphMode(options.ascii === true),
         }),
       );
       ui.stderr('');
@@ -449,7 +453,7 @@ async function executeMigrationStatusCommand(
 
   const showAppliedOverlay = connected && !usingFromOverride;
   const showDbMarker = connected && !usingFromOverride;
-  const glyphMode = ui.resolveGlyphMode(false);
+  const glyphMode = ui.resolveGlyphMode(options.ascii === true);
   const colorize = flags.color !== false;
 
   const statusSpaces: MigrationStatusSpaceResult[] = [];
@@ -630,7 +634,8 @@ export function createMigrationStatusCommand(): Command {
     command,
     'Show migration path and pending status',
     'Shows which migrations are pending between the database marker and\n' +
-      'the target contract. Requires a database connection for live status.\n' +
+      'the target contract. Requires a database connection.\n' +
+      'Pass --from for an offline path preview without a database.\n' +
       'Use `migration graph` for topology, `migration log` for history,\n' +
       'and `migration list` for on-disk enumeration.',
   );
@@ -638,6 +643,8 @@ export function createMigrationStatusCommand(): Command {
     'prisma-next migration status --db $DATABASE_URL',
     'prisma-next migration status --to production --db $DATABASE_URL',
     'prisma-next migration status --from sha256:abc --to production',
+    'prisma-next migration status --from sha256:abc --to production --json',
+    'prisma-next migration status --ascii --from sha256:abc --to production',
     'prisma-next migration status --legend --from sha256:abc --to production',
   ]);
   setCommandSeeAlso(command, [
@@ -659,6 +666,7 @@ export function createMigrationStatusCommand(): Command {
       'Origin contract reference; same grammar as --to. Supplying --from switches to offline path computation.',
     )
     .option('--legend', 'Print a key for the tree glyphs and lane colors')
+    .option('--ascii', 'Use ASCII glyphs (pipe-friendly)')
     .action(async (options: MigrationStatusOptions) => {
       const flags = parseGlobalFlagsOrExit(options);
       const ui = createTerminalUI(flags);

package/src/utils/cli-errors.ts

@@ -28,6 +28,7 @@ import {
 import { errorRuntime } from '@prisma-next/errors/execution';
 import type { MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { RefResolutionError } from '@prisma-next/migration-tools/ref-resolution';
+import { ifDefined } from '@prisma-next/utils/defined';
 import type { MigrateFailure } from '../control-api/types';
 
 export {
@@ -342,6 +343,33 @@ export function mapMigrationToolsError(error: MigrationToolsError): CliStructure
   });
 }
 
+/**
+ * Shared "needs a live database" precondition for read verbs that consult the
+ * marker/ledger (`migration log`, `migration status`). A command needs both a
+ * connection string and a control-plane driver; either missing yields the same
+ * `PN-CLI-4005` envelope with `meta.missingFlags` (canonical long-form flags
+ * per CLI Style Guide §Errors) so callers can react programmatically. Returns
+ * `null` when both are present.
+ */
+export function requireLiveDatabase(args: {
+  readonly dbConnection: unknown;
+  readonly hasDriver: boolean;
+  readonly why: string;
+  readonly commandName?: string;
+  readonly retryCommand?: string;
+}): CliStructuredError | null {
+  if (args.dbConnection && args.hasDriver) {
+    return null;
+  }
+  const missingFlags = args.dbConnection ? [] : ['--db'];
+  return errorDatabaseConnectionRequired({
+    why: args.why,
+    missingFlags,
+    ...ifDefined('commandName', args.commandName),
+    ...ifDefined('retryCommand', args.retryCommand),
+  });
+}
+
 /**
  * Maps a `RefResolutionError` from the contract/migration reference
  * resolver into a CLI structured error envelope.

package/src/utils/formatters/migration-log-table.ts

@@ -1,9 +1,10 @@
 import type { LedgerEntryRecord } from '@prisma-next/contract/types';
 import stringWidth from 'string-width';
+import type { GlyphMode } from '../glyph-mode';
 import {
   abbreviateContractHash,
-  MIGRATION_LIST_EMPTY_SOURCE,
-  MIGRATION_LIST_FORWARD_EDGE_GLYPH,
+  migrationListEmptySource,
+  migrationListForwardArrow,
 } from './migration-list-data-column';
 import { IDENTITY_MIGRATION_LIST_STYLER, type MigrationListStyler } from './migration-list-render';
 
@@ -12,6 +13,7 @@ export type LedgerTimestampMode = 'local' | 'utc' | 'iso';
 export interface RenderMigrationLogTableOptions {
   readonly utc?: boolean;
   readonly styler?: MigrationListStyler;
+  readonly glyphMode?: GlyphMode;
 }
 
 export interface SerializedLedgerEntryRecord {
@@ -31,6 +33,7 @@ const HEADING_CHANGE = 'Change';
 const HEADING_OPS = 'Ops';
 const COLUMN_SEPARATOR = ' ';
 const DIVIDER_CHAR = '─';
+const ASCII_DIVIDER_CHAR = '-';
 
 export function sortLedgerEntries(entries: readonly LedgerEntryRecord[]): LedgerEntryRecord[] {
   return [...entries].sort((left, right) => {
@@ -65,27 +68,32 @@ export function formatLedgerAppliedAt(date: Date, mode: LedgerTimestampMode): st
   return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())} ${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())} ${sign}${offsetHours}:${offsetMins}`;
 }
 
-export function formatHashEndpoint(hash: string | null): string {
+export function formatHashEndpoint(hash: string | null, glyphMode: GlyphMode = 'unicode'): string {
   if (hash === null) {
-    return MIGRATION_LIST_EMPTY_SOURCE;
+    return migrationListEmptySource(glyphMode);
   }
   return abbreviateContractHash(hash);
 }
 
-export function formatHashTransition(from: string | null, to: string): string {
-  return `${formatHashEndpoint(from)} ${MIGRATION_LIST_FORWARD_EDGE_GLYPH} ${abbreviateContractHash(to)}`;
+export function formatHashTransition(
+  from: string | null,
+  to: string,
+  glyphMode: GlyphMode = 'unicode',
+): string {
+  return `${formatHashEndpoint(from, glyphMode)} ${migrationListForwardArrow(glyphMode)} ${abbreviateContractHash(to)}`;
 }
 
 export function styleHashTransition(
   from: string | null,
   to: string,
   styler: MigrationListStyler,
+  glyphMode: GlyphMode = 'unicode',
 ): string {
   const fromPart =
     from === null
-      ? styler.glyph(MIGRATION_LIST_EMPTY_SOURCE)
+      ? styler.glyph(migrationListEmptySource(glyphMode))
       : styler.sourceHash(abbreviateContractHash(from));
-  const arrow = styler.glyph(MIGRATION_LIST_FORWARD_EDGE_GLYPH);
+  const arrow = styler.glyph(migrationListForwardArrow(glyphMode));
   const dest = styler.destHash(abbreviateContractHash(to));
   return `${fromPart} ${arrow} ${dest}`;
 }
@@ -99,8 +107,8 @@ function columnWidth(values: readonly string[]): number {
   return values.reduce((max, value) => Math.max(max, stringWidth(value)), 0);
 }
 
-function padDividerCell(valueWidth: number): string {
-  return DIVIDER_CHAR.repeat(valueWidth + 2);
+function padDividerCell(valueWidth: number, dividerChar: string): string {
+  return dividerChar.repeat(valueWidth + 2);
 }
 
 function padTextCell(value: string, valueWidth: number): string {
@@ -122,13 +130,15 @@ export function renderMigrationLogTable(
   }
 
   const styler = options.styler ?? IDENTITY_MIGRATION_LIST_STYLER;
+  const glyphMode = options.glyphMode ?? 'unicode';
+  const dividerChar = glyphMode === 'ascii' ? ASCII_DIVIDER_CHAR : DIVIDER_CHAR;
   const showSpace = new Set(sorted.map((entry) => entry.space)).size > 1;
   const timestampMode: LedgerTimestampMode = options.utc ? 'utc' : 'local';
   const rows = sorted.map((entry) => ({
     appliedAt: formatLedgerAppliedAt(entry.appliedAt, timestampMode),
     space: entry.space,
     migrationName: entry.migrationName,
-    transition: formatHashTransition(entry.from, entry.to),
+    transition: formatHashTransition(entry.from, entry.to, glyphMode),
     ops: `${entry.operationCount} ops`,
     from: entry.from,
     to: entry.to,
@@ -151,14 +161,14 @@ export function renderMigrationLogTable(
   );
   const heading = headingParts.join(COLUMN_SEPARATOR);
 
-  const dividerParts = [padDividerCell(appliedAtWidth)];
+  const dividerParts = [padDividerCell(appliedAtWidth, dividerChar)];
   if (showSpace) {
-    dividerParts.push(padDividerCell(spaceWidth));
+    dividerParts.push(padDividerCell(spaceWidth, dividerChar));
   }
   dividerParts.push(
-    padDividerCell(nameWidth),
-    padDividerCell(transitionWidth),
-    padDividerCell(opsWidth),
+    padDividerCell(nameWidth, dividerChar),
+    padDividerCell(transitionWidth, dividerChar),
+    padDividerCell(opsWidth, dividerChar),
   );
   const divider = dividerParts.map((cell) => styler.summary(cell)).join(COLUMN_SEPARATOR);
 
@@ -169,7 +179,7 @@ export function renderMigrationLogTable(
     }
     parts.push(
       padTextCell(styler.dirName(row.migrationName), nameWidth),
-      padTextCell(styleHashTransition(row.from, row.to, styler), transitionWidth),
+      padTextCell(styleHashTransition(row.from, row.to, styler, glyphMode), transitionWidth),
       padOpsCell(row.ops, opsWidth),
     );
     return parts.join(COLUMN_SEPARATOR);

package/src/utils/migration-path-target.ts

@@ -0,0 +1,39 @@
+import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { isAbsolute, relative, resolve } from 'pathe';
+import { type CliStructuredError, errorRuntime } from './cli-errors';
+
+export function looksLikePath(target: string): boolean {
+  return target.includes('/') || target.includes('\\');
+}
+
+export function resolveAppTargetPath(
+  target: string,
+  appMigrationsDir: string,
+  appMigrationsRelative: string,
+): Result<string, CliStructuredError> {
+  const targetPath = resolve(target);
+  const relativeToApp = relative(appMigrationsDir, targetPath);
+  const isOutsideAppDir =
+    relativeToApp === '' ||
+    relativeToApp === '.' ||
+    relativeToApp.startsWith('..') ||
+    isAbsolute(relativeToApp);
+  if (isOutsideAppDir) {
+    return notOk(
+      errorRuntime('Target must point to an app-space migration', {
+        why: `Expected a path under ${appMigrationsRelative}, got ${target}`,
+        fix: 'Pass an app-space migration directory or use a hash prefix.',
+      }),
+    );
+  }
+  return ok(targetPath);
+}
+
+export function findPackageByDirPath(
+  packages: readonly OnDiskMigrationPackage[],
+  resolvedDirPath: string,
+): OnDiskMigrationPackage | undefined {
+  const normalized = resolve(resolvedDirPath);
+  return packages.find((p) => resolve(p.dirPath) === normalized);
+}