prisma · wmadden-electric · Aug 11, 2026 · Aug 9, 2026 · Aug 9, 2026 · Aug 11, 2026
@@ -18,6 +18,7 @@ import {
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
+  closeQuietly,
   resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
@@ -237,7 +238,7 @@ async function executeDbInitCommand(
       }),
     );
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
 

@@ -20,6 +20,7 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  closeQuietly,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
@@ -230,7 +231,7 @@ async function executeDbSignCommand(
       }),
     );
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
 

@@ -20,6 +20,7 @@ import {
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
+  closeQuietly,
   resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
@@ -229,7 +230,7 @@ async function executeDbUpdateCommand(
       }),
     );
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
 

@@ -29,6 +29,7 @@ import {
 import { type CombinedVerifyResult, combineVerifyResults } from '../utils/combine-verify-results';
 import {
   addGlobalOptions,
+  closeQuietly,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
@@ -480,7 +481,7 @@ async function executeDbVerifyCommand(
   } catch (error) {
     return wrapVerifyError(error, contractPathAbsolute, 'db verify');
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
 
@@ -529,7 +530,7 @@ async function executeDbSchemaOnlyVerifyCommand(
   } catch (error) {
     return wrapVerifyError(error, contractPathAbsolute, 'db verify --schema-only');
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
 

@@ -11,7 +11,7 @@ import {
   errorDriverRequired,
   errorUnexpected,
 } from '../utils/cli-errors';
-import { maskConnectionUrl, sanitizeErrorMessage } from '../utils/command-helpers';
+import { closeQuietly, maskConnectionUrl, sanitizeErrorMessage } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions, GlobalFlags } from '../utils/global-flags';
 import { createProgressAdapter } from '../utils/progress-adapter';
@@ -178,6 +178,6 @@ export async function inspectLiveSchema(
       }),
     );
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
@@ -176,12 +176,28 @@ export const migrationShowResultSchema = successEnvelopeBaseSchema.and(
 
 export type MigrationShowResult = typeof migrationShowResultSchema.infer;
 
+/**
+ * The engine's `NextAction`, restated as the published shape of this CLI's own
+ * `--json` documents. It is not imported from the engine because these schemas
+ * ARE the wire contract — a change here is a change users see. The engine's
+ * plural `commands` form is absent because nothing here emits one.
+ */
+export const nextActionSchema = type({
+  kind: '"run-command" | "open-url" | "user-choice" | "edit-file" | "done"',
+  label: 'string',
+  'command?': 'string',
+  'url?': 'string',
+  'reason?': 'string',
+});
+
+export type NextActionJson = typeof nextActionSchema.infer;
+
 export const checkFailureSchema = type({
   space: 'string',
   code: 'string',
   where: 'string',
   why: 'string',
-  fix: 'string',
+  nextActions: nextActionSchema.array(),
 });
 
 export type CheckFailure = typeof checkFailureSchema.infer;

@@ -40,6 +40,7 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  closeQuietly,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
@@ -631,7 +632,7 @@ async function executeMigrateCommand(
       }),
     );
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
 

@@ -87,6 +87,7 @@ async function executeMigrationCheckCommand(
       ...(options.space !== undefined ? { spaceFilter: options.space } : {}),
       appMigrationsDir,
       appMigrationsRelative,
+      cwd: process.cwd(),
     });
   }
 
@@ -195,7 +196,10 @@ export function createMigrationCheckCommand(): Command {
         } else {
           for (const f of result.failures) {
             ui.log(`✗ [${f.code}] ${f.where}: ${f.why}`);
-            ui.log(`  fix: ${f.fix}`);
+            for (const action of f.nextActions) {
+              const command = action.command === undefined ? '' : `: ${action.command}`;
+              ui.log(`  next: ${action.label}${command}`);
+            }
           }
           ui.log(`\n${result.summary}`);
         }

@@ -6,7 +6,6 @@ import { Command } from 'commander';
 import { buildReadAggregate } from '../control-api/operations/contract-space-aggregate-loader';
 import { buildMigrationSpaceGraphEntries } from '../control-api/operations/migration-graph';
 import {
-  listRefsByContractHash,
   migrationSpaceListEntriesFromAggregate,
   runMigrationList,
 } from '../control-api/operations/migration-list';
@@ -20,11 +19,11 @@ import {
 } from '../utils/command-helpers';
 import { renderMigrationGraphLegend } from '../utils/formatters/migration-graph-labels';
 import {
-  computeGlobalMaxDirNameWidth,
-  computeGlobalMaxEdgeTreePrefixWidth,
-  indentMigrationGraphTreeBlock,
-  renderMigrationGraphSpaceTree,
-} from '../utils/formatters/migration-graph-space-render';
+  buildMigrationGraphTreeSections,
+  type MigrationGraphTreeSection,
+  renderMigrationGraphDot,
+  renderMigrationGraphSections,
+} from '../utils/formatters/migration-graph-sections';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
 import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
@@ -41,12 +40,6 @@ interface MigrationGraphOptions extends CommonCommandOptions {
   readonly legend?: boolean;
 }
 
-export interface MigrationGraphTreeSection {
-  readonly space: string;
-  readonly tree: string;
-  readonly showHeading: boolean;
-}
-
 export interface MigrationGraphResult {
   readonly ok: true;
   /** App-space graph for the `--dot` Graphviz output. */
@@ -64,20 +57,7 @@ function computeGraphSummary(spaces: readonly MigrationSpaceGraphEntry[]): strin
 }
 
 export function formatMigrationGraphHumanOutput(result: MigrationGraphResult): string {
-  const sections: string[] = [];
-  for (const section of result.treeSections) {
-    if (section.showHeading) {
-      sections.push(`${section.space}:`);
-    }
-    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();
+  return renderMigrationGraphSections(result.treeSections, result.summary);
 }
 
 export async function executeMigrationGraphCommand(
@@ -144,56 +124,14 @@ export async function executeMigrationGraphCommand(
   }
 
   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.space)!.graph(),
-          liveContractHash,
-        }))
-    : [];
-  const globalMaxEdgeTreePrefixWidth =
-    globalLayoutInputs.length > 0
-      ? computeGlobalMaxEdgeTreePrefixWidth(globalLayoutInputs)
-      : undefined;
-  const globalMaxDirNameWidth =
-    globalLayoutInputs.length > 0 ? computeGlobalMaxDirNameWidth(globalLayoutInputs) : undefined;
+  const treeSections = buildMigrationGraphTreeSections({
+    aggregate,
+    scopedSpaces,
+    liveContractHash,
+    glyphMode: ui.resolveGlyphMode(options.ascii === true),
+    colorize: flags.color !== false,
+  });
 
-  const treeSections: MigrationGraphTreeSection[] = [];
-  for (const spaceEntry of scopedSpaces) {
-    const space = aggregate.space(spaceEntry.space);
-    if (space === undefined) {
-      continue;
-    }
-    const graph = space.graph();
-    const isAppSpace = spaceEntry.space === aggregate.app.spaceId;
-    const refsByHash = listRefsByContractHash(space);
-    const tree =
-      spaceEntry.migrations.length === 0
-        ? ''
-        : renderMigrationGraphSpaceTree({
-            graph,
-            migrations: spaceEntry.migrations,
-            liveContractHash,
-            glyphMode,
-            colorize,
-            isAppSpace,
-            refsByHash,
-            ...(globalMaxEdgeTreePrefixWidth !== undefined ? { globalMaxEdgeTreePrefixWidth } : {}),
-            ...(globalMaxDirNameWidth !== undefined ? { globalMaxDirNameWidth } : {}),
-          });
-    const displayTree =
-      showSpaceHeadings && tree.length > 0 ? indentMigrationGraphTreeBlock(tree, '  ') : tree;
-    treeSections.push({
-      space: spaceEntry.space,
-      tree: displayTree,
-      showHeading: showSpaceHeadings,
-    });
-  }
   const spaces: MigrationSpaceGraphEntry[] = [
     ...buildMigrationSpaceGraphEntries({ aggregate, scopedSpaces }),
   ];
@@ -248,14 +186,7 @@ export function createMigrationGraphCommand(): Command {
       const result = await executeMigrationGraphCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (graphResult) => {
         if (options.dot) {
-          const lines = ['digraph migrations {'];
-          for (const edge of graphResult.graph.migrationByHash.values()) {
-            const from = edge.from.slice(0, 12);
-            const to = edge.to.slice(0, 12);
-            lines.push(`  "${from}" -> "${to}" [label="${edge.dirName}"];`);
-          }
-          lines.push('}');
-          ui.output(lines.join('\n'));
+          ui.output(renderMigrationGraphDot(graphResult.graph));
         } else if (flags.json) {
           const jsonResult: MigrationGraphJsonResult = {
             ok: true,

@@ -8,6 +8,7 @@ import { mapCaughtMigrationError } from '../control-api/operations/caught-errors
 import { type CliStructuredError, errorUnexpected, requireLiveDatabase } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  closeQuietly,
   maskConnectionUrl,
   resolveMigrationPaths,
   setCommandDescriptions,
@@ -107,7 +108,7 @@ export async function executeMigrationLogCommand(
       }),
     );
   } finally {
-    await client.close();
+    await closeQuietly(client);
   }
 }
 

@@ -19,7 +19,8 @@ import {
   type CliStructuredError,
   errorContractValidationFailed,
   errorFileNotFound,
-  errorRuntime,
+  errorMigrationPackageNotFound,
+  errorNoMigrations,
   errorUnexpected,
 } from '../utils/cli-errors';
 import {
@@ -187,26 +188,25 @@ async function executeMigrationShowCommand(
 
   let appPkg: OnDiskMigrationPackage;
   if (looksLikePath(target)) {
-    const resolved = resolveAppTargetPath(target, appMigrationsDir, appMigrationsRelative);
+    const resolved = resolveAppTargetPath(
+      process.cwd(),
+      target,
+      appMigrationsDir,
+      appMigrationsRelative,
+    );
     if (!resolved.ok) return resolved;
     const matched = findPackageByDirPath(packages, resolved.value);
     if (!matched) {
       return notOk(
-        errorRuntime('MIGRATION.PACKAGE_NOT_FOUND', 'Migration package not found', {
-          why: `No loaded migration package at ${relative(process.cwd(), resolved.value)}`,
-          fix: 'Pass a directory name, hash prefix, or path to an on-disk app-space migration package.',
-        }),
+        errorMigrationPackageNotFound(
+          `No loaded migration package at ${relative(process.cwd(), resolved.value)}`,
+        ),
       );
     }
     appPkg = matched;
   } else {
     if (packages.length === 0) {
-      return notOk(
-        errorRuntime('MIGRATION.NO_MIGRATIONS', 'No migrations found', {
-          why: `No migration packages found in ${appMigrationsRelative}`,
-          fix: 'Run `prisma-next migration plan` to create a migration first.',
-        }),
-      );
+      return notOk(errorNoMigrations(appMigrationsRelative));
     }
     const migResult = resolveMigrationRef(target, { graph, refs });
     if (!migResult.ok) {
@@ -217,10 +217,9 @@ async function executeMigrationShowCommand(
     );
     if (!matchedPkg) {
       return notOk(
-        errorRuntime('MIGRATION.PACKAGE_NOT_FOUND', 'Migration package not found', {
-          why: `Resolved migration "${migResult.value.dirName}" but the package was not loaded`,
-          fix: 'The migrations directory may be corrupted. Inspect the migration.json files.',
-        }),
+        errorMigrationPackageNotFound(
+          `Resolved migration "${migResult.value.dirName}" but the package was not loaded`,
+        ),
       );
     }
     appPkg = matchedPkg;

@@ -36,6 +36,7 @@ import { readMigrationRefs } from '../control-api/operations/refs';
 import { CliStructuredError, errorUnexpected, requireLiveDatabase } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  closeQuietly,
   maskConnectionUrl,
   readContractEnvelope,
   resolveMigrationPaths,
@@ -441,7 +442,7 @@ export async function executeMigrationStatusCommand(
         }),
       );
     } finally {
-      await client.close();
+      await closeQuietly(client);
     }
   }