@prisma-next/cli 0.12.0 → 0.13.0-dev.2

package/src/utils/formatters/migration-list-styler.ts

@@ -1,6 +1,39 @@
 import { bold, cyan, cyanBright, dim, green, yellow } from 'colorette';
 import { IDENTITY_MIGRATION_LIST_STYLER, type MigrationListStyler } from './migration-list-render';
 
+export type MigrationListStylerWithMarkers = MigrationListStyler & {
+  markers(names: readonly string[]): string;
+};
+
+function hasMarkersFormatter(
+  styler: MigrationListStyler,
+): styler is MigrationListStylerWithMarkers {
+  return 'markers' in styler && typeof styler.markers === 'function';
+}
+
+function styleMarkerName(name: string): string {
+  return name === CONTRACT_MARKER_NAME ? bold(green(name)) : green(name);
+}
+
+function plainMarkers(names: readonly string[]): string {
+  return names.map((name) => `@${name}`).join(' ');
+}
+
+export function formatContractNodeOverlays(
+  styler: MigrationListStyler,
+  markers: readonly string[],
+  refs: readonly string[],
+): string {
+  const parts: string[] = [];
+  if (markers.length > 0) {
+    parts.push(hasMarkersFormatter(styler) ? styler.markers(markers) : plainMarkers(markers));
+  }
+  if (refs.length > 0) {
+    parts.push(styler.refs(refs));
+  }
+  return parts.join(' ');
+}
+
 /**
  * The current contract overlay marker. Unlike user refs, this names the user's
  * declared desired state — the implicit base/target for `plan` / `migrate` —
@@ -10,7 +43,7 @@ import { IDENTITY_MIGRATION_LIST_STYLER, type MigrationListStyler } from './migr
 export const CONTRACT_MARKER_NAME = 'contract';
 
 function styleRefName(name: string): string {
-  return name === CONTRACT_MARKER_NAME ? bold(green(name)) : green(name);
+  return green(name);
 }
 
 /**
@@ -29,17 +62,21 @@ function styleRefName(name: string): string {
  * - `glyph` (`→` / `⟲` / `∅`): dim
  * - `lane` (graph gutter lines `│` and fan/join connectors `├─┐` / `├─┘`): dim
  * - `invariants` (`{...}`): yellow
- * - `refs` (`(...)`): green; the `contract` desired-state marker inside is
- *   green-bold (the active ref is bolded separately by the tree styler)
+ * - `markers` (`@contract @db`): green; the `contract` desired-state marker is
+ *   green-bold (`db` is plain green); the `@` sigil is applied to each name
+ * - `refs` (`(...)`): green (the active ref is bolded separately by the tree styler)
  * - `spaceHeading` (`<spaceId>:`): bold
  * - `summary`: dim
  * - `emptyState`: dim
  */
 export function createAnsiMigrationListStyler(opts: {
   readonly useColor: boolean;
-}): MigrationListStyler {
+}): MigrationListStylerWithMarkers {
   if (!opts.useColor) {
-    return IDENTITY_MIGRATION_LIST_STYLER;
+    return {
+      ...IDENTITY_MIGRATION_LIST_STYLER,
+      markers: plainMarkers,
+    };
   }
   return {
     // Kind glyphs stay bright in both flat and graph views; lanes carry the dim gutter.
@@ -50,6 +87,10 @@ export function createAnsiMigrationListStyler(opts: {
     glyph: (text) => dim(text),
     lane: (text) => dim(text),
     invariants: (ids) => yellow(`{${ids.join(', ')}}`),
+    markers: (names) => {
+      const sigil = green('@');
+      return names.map((name) => sigil + styleMarkerName(name)).join(' ');
+    },
     refs: (names) => {
       const open = green('(');
       const close = green(')');

package/src/utils/formatters/migration-list-types.ts

@@ -1,21 +1,5 @@
-export interface MigrationListEntry {
-  readonly dirName: string;
-  readonly from: string | null;
-  readonly to: string;
-  readonly migrationHash: string;
-  readonly operationCount: number;
-  readonly createdAt: string;
-  readonly refs: readonly string[];
-  readonly providedInvariants: readonly string[];
-}
-
-export interface MigrationSpaceListEntry {
-  readonly spaceId: string;
-  readonly migrations: readonly MigrationListEntry[];
-}
-
-export interface MigrationListResult {
-  readonly ok: true;
-  readonly spaces: readonly MigrationSpaceListEntry[];
-  readonly summary: string;
-}
+export type {
+  MigrationEntry as MigrationListEntry,
+  MigrationListResult,
+  MigrationSpaceListEntry,
+} from '../../commands/json/schemas';

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

@@ -0,0 +1,205 @@
+import type { LedgerEntryRecord } from '@prisma-next/contract/types';
+import stringWidth from 'string-width';
+import type { GlyphMode } from '../glyph-mode';
+import {
+  abbreviateContractHash,
+  migrationListEmptySource,
+  migrationListForwardArrow,
+} from './migration-list-data-column';
+import { IDENTITY_MIGRATION_LIST_STYLER, type MigrationListStyler } from './migration-list-render';
+
+export type LedgerTimestampMode = 'local' | 'utc' | 'iso';
+
+export interface RenderMigrationLogTableOptions {
+  readonly utc?: boolean;
+  readonly styler?: MigrationListStyler;
+  readonly glyphMode?: GlyphMode;
+}
+
+export interface SerializedLedgerEntryRecord {
+  readonly space: string;
+  readonly name: string;
+  readonly hash: string;
+  readonly fromContract: string | null;
+  readonly toContract: string;
+  readonly appliedAt: string;
+  readonly operationCount: number;
+}
+
+const HEADING_APPLIED_AT = 'Applied at';
+const HEADING_SPACE = 'Space';
+const HEADING_MIGRATION = 'Migration';
+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) => {
+    const timeDiff = left.appliedAt.getTime() - right.appliedAt.getTime();
+    if (timeDiff !== 0) {
+      return timeDiff;
+    }
+    const spaceDiff = left.space.localeCompare(right.space);
+    if (spaceDiff !== 0) {
+      return spaceDiff;
+    }
+    return left.migrationName.localeCompare(right.migrationName);
+  });
+}
+
+function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+export function formatLedgerAppliedAt(date: Date, mode: LedgerTimestampMode): string {
+  if (mode === 'iso') {
+    return date.toISOString();
+  }
+  if (mode === 'utc') {
+    return `${date.getUTCFullYear()}-${pad2(date.getUTCMonth() + 1)}-${pad2(date.getUTCDate())} ${pad2(date.getUTCHours())}:${pad2(date.getUTCMinutes())}:${pad2(date.getUTCSeconds())}Z`;
+  }
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absoluteOffset = Math.abs(offsetMinutes);
+  const offsetHours = pad2(Math.floor(absoluteOffset / 60));
+  const offsetMins = pad2(absoluteOffset % 60);
+  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, glyphMode: GlyphMode = 'unicode'): string {
+  if (hash === null) {
+    return migrationListEmptySource(glyphMode);
+  }
+  return abbreviateContractHash(hash);
+}
+
+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(migrationListEmptySource(glyphMode))
+      : styler.sourceHash(abbreviateContractHash(from));
+  const arrow = styler.glyph(migrationListForwardArrow(glyphMode));
+  const dest = styler.destHash(abbreviateContractHash(to));
+  return `${fromPart} ${arrow} ${dest}`;
+}
+
+function padVisible(text: string, targetWidth: number): string {
+  const padding = Math.max(0, targetWidth - stringWidth(text));
+  return text + ' '.repeat(padding);
+}
+
+function columnWidth(values: readonly string[]): number {
+  return values.reduce((max, value) => Math.max(max, stringWidth(value)), 0);
+}
+
+function padDividerCell(valueWidth: number, dividerChar: string): string {
+  return dividerChar.repeat(valueWidth + 2);
+}
+
+function padTextCell(value: string, valueWidth: number): string {
+  return ` ${padVisible(value, valueWidth)} `;
+}
+
+function padOpsCell(value: string, valueWidth: number): string {
+  const padding = Math.max(0, valueWidth - stringWidth(value));
+  return ` ${' '.repeat(padding)}${value} `;
+}
+
+export function renderMigrationLogTable(
+  entries: readonly LedgerEntryRecord[],
+  options: RenderMigrationLogTableOptions = {},
+): string {
+  const sorted = sortLedgerEntries(entries);
+  if (sorted.length === 0) {
+    return '';
+  }
+
+  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, glyphMode),
+    ops: `${entry.operationCount} ops`,
+    from: entry.from,
+    to: entry.to,
+  }));
+
+  const appliedAtWidth = columnWidth([HEADING_APPLIED_AT, ...rows.map((row) => row.appliedAt)]);
+  const spaceWidth = showSpace ? columnWidth([HEADING_SPACE, ...rows.map((row) => row.space)]) : 0;
+  const nameWidth = columnWidth([HEADING_MIGRATION, ...rows.map((row) => row.migrationName)]);
+  const transitionWidth = columnWidth([HEADING_CHANGE, ...rows.map((row) => row.transition)]);
+  const opsWidth = columnWidth([HEADING_OPS, ...rows.map((row) => row.ops)]);
+
+  const headingParts = [padTextCell(HEADING_APPLIED_AT, appliedAtWidth)];
+  if (showSpace) {
+    headingParts.push(padTextCell(HEADING_SPACE, spaceWidth));
+  }
+  headingParts.push(
+    padTextCell(HEADING_MIGRATION, nameWidth),
+    padTextCell(HEADING_CHANGE, transitionWidth),
+    padOpsCell(HEADING_OPS, opsWidth),
+  );
+  const heading = headingParts.join(COLUMN_SEPARATOR);
+
+  const dividerParts = [padDividerCell(appliedAtWidth, dividerChar)];
+  if (showSpace) {
+    dividerParts.push(padDividerCell(spaceWidth, dividerChar));
+  }
+  dividerParts.push(
+    padDividerCell(nameWidth, dividerChar),
+    padDividerCell(transitionWidth, dividerChar),
+    padDividerCell(opsWidth, dividerChar),
+  );
+  const divider = dividerParts.map((cell) => styler.summary(cell)).join(COLUMN_SEPARATOR);
+
+  const dataRows = rows.map((row) => {
+    const parts = [padTextCell(row.appliedAt, appliedAtWidth)];
+    if (showSpace) {
+      parts.push(padTextCell(row.space, spaceWidth));
+    }
+    parts.push(
+      padTextCell(styler.dirName(row.migrationName), nameWidth),
+      padTextCell(styleHashTransition(row.from, row.to, styler, glyphMode), transitionWidth),
+      padOpsCell(row.ops, opsWidth),
+    );
+    return parts.join(COLUMN_SEPARATOR);
+  });
+
+  return [heading, divider, ...dataRows].join('\n');
+}
+
+export function serializeLedgerEntriesForJson(
+  entries: readonly LedgerEntryRecord[],
+): SerializedLedgerEntryRecord[] {
+  return sortLedgerEntries(entries).map((entry) => ({
+    space: entry.space,
+    name: entry.migrationName,
+    hash: entry.migrationHash,
+    fromContract: entry.from,
+    toContract: entry.to,
+    appliedAt: formatLedgerAppliedAt(entry.appliedAt, 'iso'),
+    operationCount: entry.operationCount,
+  }));
+}
+
+export const MIGRATION_LOG_EMPTY_MESSAGE = 'No migrations have been applied to this database.';

package/src/utils/formatters/migrations.ts

@@ -1,4 +1,7 @@
-import type { OperationPreview } from '@prisma-next/framework-components/control';
+import type {
+  MigrationPlannerConflict,
+  OperationPreview,
+} from '@prisma-next/framework-components/control';
 import { cyan, green, yellow } from 'colorette';
 
 import type { PerSpaceExecutionEntry } from '../../control-api/types';
@@ -85,11 +88,24 @@ export interface MigrationCommandResult {
   readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
   readonly plannedAdvanceRef?: { readonly name: string; readonly hash: string } | null;
   readonly summary: string;
+  readonly warnings?: readonly MigrationPlannerConflict[];
   readonly timings: {
     readonly total: number;
   };
 }
 
+export function formatPlannerWarningsBlock(
+  warnings: readonly MigrationPlannerConflict[],
+  useColor: boolean,
+): readonly string[] {
+  const formatDimText = (text: string) => formatDim(useColor, text);
+  const lines: string[] = ['', 'Warnings:'];
+  for (const warning of warnings) {
+    lines.push(`  ${formatDimText(`- ${warning.summary}`)}`);
+  }
+  return lines;
+}
+
 /**
  * Render the shared per-space execution block consumed by the `db init`
  * / `db update` / `migrate` summaries. Always shows: space
@@ -165,6 +181,10 @@ export function formatMigrationPlanOutput(
     lines.push(`${formatGreen('✔')} Planned ${operationCount} operation(s)`);
   }
 
+  if (result.warnings && result.warnings.length > 0) {
+    lines.push(...formatPlannerWarningsBlock(result.warnings, useColor));
+  }
+
   const formatYellow = createColorFormatter(useColor, yellow);
 
   // Per-space breakdown takes precedence over the flat ops tree when
@@ -315,11 +335,10 @@ export function formatMigrationApplyCommandOutput(
 }
 
 interface MigrationShowPresent {
-  readonly dirName: string;
-  readonly dirPath: string;
-  readonly from: string | null;
-  readonly to: string;
-  readonly migrationHash: string;
+  readonly name: string;
+  readonly fromContract: string | null;
+  readonly toContract: string;
+  readonly hash: string;
   readonly createdAt: string;
   readonly operations: readonly {
     readonly id: string;
@@ -327,7 +346,6 @@ interface MigrationShowPresent {
     readonly operationClass: string;
   }[];
   readonly preview: OperationPreview;
-  readonly summary: string;
 }
 
 interface MigrationShowResult {
@@ -340,10 +358,10 @@ function formatSpaceShowBlock(space: MigrationShowPresent, useColor: boolean): r
   const formatDimText = (text: string) => formatDim(useColor, text);
 
   const lines: string[] = [];
-  lines.push(`${formatGreen('✔')} ${space.dirName}`);
-  lines.push(`${formatDimText(`  from: ${space.from ?? '(baseline)'}`)}`);
-  lines.push(`${formatDimText(`  to:   ${space.to}`)}`);
-  lines.push(`${formatDimText(`  migrationHash: ${space.migrationHash}`)}`);
+  lines.push(`${formatGreen('✔')} ${space.name}`);
+  lines.push(`${formatDimText(`  from: ${space.fromContract ?? '(baseline)'}`)}`);
+  lines.push(`${formatDimText(`  to:   ${space.toContract}`)}`);
+  lines.push(`${formatDimText(`  hash: ${space.hash}`)}`);
   lines.push(`${formatDimText(`  created: ${space.createdAt}`)}`);
 
   lines.push('');
@@ -427,6 +445,10 @@ export function formatMigrationApplyOutput(
       lines.push(`${formatGreen('✔')} Applied ${executed} operation(s)`);
     }
 
+    if (result.warnings && result.warnings.length > 0) {
+      lines.push(...formatPlannerWarningsBlock(result.warnings, useColor));
+    }
+
     // Per-space breakdown — replaces the single ambiguous `Signature:`
     // line with a per-space marker + ops listing.
     if (result.perSpace && result.perSpace.length > 0) {

package/src/utils/global-flags.ts

@@ -180,3 +180,38 @@ export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
 
   return flags as GlobalFlags;
 }
+
+/**
+ * Bridges the two TTY checks (stdout via `flags`, stdin via
+ * `process.stdin.isTTY`) into the `canPrompt` boolean the interactive
+ * `init` flow consumes.
+ *
+ * Per the [Style Guide § Interactivity](../../../../../../../docs/CLI%20Style%20Guide.md#interactivity):
+ *
+ * - `flags.interactive` governs *decoration* (TerminalUI, intro/outro,
+ *   spinners) and is derived from stdout-TTY by `parseGlobalFlags`,
+ *   honouring `--interactive` / `--no-interactive`.
+ * - Prompting additionally requires a stdin TTY — closing stdin is a
+ *   common signal in CI / agent environments even when stdout stays
+ *   attached.
+ * - `--interactive` is the explicit override: when the user passes it,
+ *   we honour it (e.g. testing flows where stdin is stubbed).
+ *
+ * Single source of truth for the interactive-prompt decision: both the
+ * `init` action handler and the preAction telemetry bridge derive
+ * prompt-eligibility from this helper so they cannot drift. Lives in
+ * `global-flags` (alongside `parseGlobalFlags`) to keep
+ * `utils/telemetry` and `commands/init/index` free of an import cycle.
+ *
+ * Exported so callers and tests can derive the same value without
+ * touching `process` globals.
+ */
+export function deriveCanPrompt(opts: {
+  readonly flagsInteractive: boolean | undefined;
+  readonly optionInteractive: boolean | undefined;
+  readonly stdinIsTTY: boolean;
+}): boolean {
+  if (opts.optionInteractive === true) return true;
+  if (opts.flagsInteractive === false) return false;
+  return opts.stdinIsTTY;
+}

package/src/utils/integrity-violation-to-check-failure.ts

@@ -1,12 +1,8 @@
 import type { IntegrityViolation } from '@prisma-next/migration-tools/aggregate';
 import { join, relative } from 'pathe';
+import type { CheckFailure } from '../commands/json/schemas';
 
-export interface CheckFailure {
-  readonly pnCode: string;
-  readonly where: string;
-  readonly why: string;
-  readonly fix: string;
-}
+export type { CheckFailure } from '../commands/json/schemas';
 
 function migrationPathRelative(dirPath: string): string {
   return relative(process.cwd(), dirPath);
@@ -34,7 +30,8 @@ export function integrityViolationToCheckFailure(
   switch (violation.kind) {
     case 'hashMismatch':
       return {
-        pnCode: 'PN-MIG-CHECK-001',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-001',
         where: migrationFileRelative(
           join(migrationsDir, violation.spaceId, violation.dirName),
           'migration.json',
@@ -44,84 +41,96 @@ export function integrityViolationToCheckFailure(
       };
     case 'providedInvariantsMismatch':
       return {
-        pnCode: 'PN-MIG-CHECK-002',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-002',
         where: packageRelative(violation.spaceId, violation.dirName),
         why: `Migration "${violation.dirName}" providedInvariants in migration.json disagrees with ops.json.`,
         fix: 'Re-emit the migration package so migration.json and ops.json agree.',
       };
     case 'packageUnloadable':
       return {
-        pnCode: 'PN-MIG-CHECK-002',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-002',
         where: packageRelative(violation.spaceId, violation.dirName),
         why: `Migration "${violation.dirName}" could not be loaded: ${violation.detail}`,
         fix: 'Re-emit the migration package or restore from version control.',
       };
     case 'sameSourceAndTarget':
       return {
-        pnCode: 'PN-MIG-CHECK-007',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-007',
         where: packageRelative(violation.spaceId, violation.dirName),
         why: `Migration "${violation.dirName}" in space "${violation.spaceId}" has source equal to target (${violation.hash}) with no data invariant — a true no-op self-edge.`,
         fix: 'Add a data operation if this self-edge was meant to carry a data invariant, or delete the migration if it is a true no-op.',
       };
     case 'orphanSpaceDir':
       return {
-        pnCode: 'PN-MIG-CHECK-008',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-008',
         where: spaceRelative(violation.spaceId),
         why: `Contract-space directory "${violation.spaceId}" exists on disk but no extension declares it.`,
         fix: 'Remove the orphan directory, or declare the extension in `extensionPacks`.',
       };
     case 'declaredButUnmigrated':
       return {
-        pnCode: 'PN-MIG-CHECK-009',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-009',
         where: spaceRelative(violation.spaceId),
         why: `Extension "${violation.spaceId}" is declared in \`extensionPacks\` but has no on-disk migrations directory.`,
         fix: 'Re-emit the extension contract-space artefacts with `prisma-next contract emit` and migration planning, or remove the extension from `extensionPacks` if it is unused.',
       };
     case 'headRefMissing':
       return {
-        pnCode: 'PN-MIG-CHECK-010',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-010',
         where: refRelative(violation.spaceId, 'head'),
         why: `Head ref \`refs/head.json\` is missing for contract space "${violation.spaceId}".`,
         fix: 'Re-emit the contract-space migrations and head ref artefacts, or restore `refs/head.json` from version control.',
       };
     case 'headRefNotInGraph':
       return {
-        pnCode: 'PN-MIG-CHECK-011',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-011',
         where: refRelative(violation.spaceId, 'head'),
         why: `Head ref ${violation.hash} for contract space "${violation.spaceId}" is not present in its migration graph.`,
         fix: 'Re-emit the contract space migrations, or restore the missing migration package.',
       };
     case 'refUnreadable':
       return {
-        pnCode: 'PN-MIG-CHECK-012',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-012',
         where: refRelative(violation.spaceId, violation.refName),
         why: `Ref "${violation.refName}" for contract space "${violation.spaceId}" is unreadable: ${violation.detail}`,
         fix: 'Repair or remove the corrupt ref file.',
       };
     case 'targetMismatch':
       return {
-        pnCode: 'PN-MIG-CHECK-013',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-013',
         where: spaceRelative(violation.spaceId),
         why: `Contract space "${violation.spaceId}" targets "${violation.actual}" but the project targets "${violation.expected}".`,
         fix: 'Update the extension to target the configured database, or change the project target.',
       };
     case 'disjointness':
       return {
-        pnCode: 'PN-MIG-CHECK-014',
+        space: 'app',
+        code: 'PN-MIG-CHECK-014',
         where: migrationPathRelative(migrationsDir),
         why: `Storage element "${violation.element}" is claimed by multiple contract spaces: ${violation.claimedBy.join(', ')}.`,
         fix: 'Update the contracts so each storage element is owned by exactly one contract space.',
       };
     case 'contractUnreadable':
       return {
-        pnCode: 'PN-MIG-CHECK-015',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-015',
         where: migrationFileRelative(join(migrationsDir, violation.spaceId), 'contract.json'),
         why: `Contract for space "${violation.spaceId}" is unreadable: ${violation.detail}`,
         fix: 'Re-emit the extension contract artefacts, or fix the descriptor producing the invalid contract.',
       };
     case 'duplicateMigrationHash':
       return {
-        pnCode: 'PN-MIG-CHECK-016',
+        space: violation.spaceId,
+        code: 'PN-MIG-CHECK-016',
         where: spaceRelative(violation.spaceId),
         why: `Multiple migrations in space "${violation.spaceId}" share migrationHash "${violation.migrationHash}" (${violation.dirNames.join(', ')}).`,
         fix: 'Re-emit one of the conflicting packages so each migrationHash is unique.',

package/src/utils/legend.ts

@@ -0,0 +1,38 @@
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { type CliStructuredError, errorLegendHumanOnly } from './cli-errors';
+import type { GlobalFlags } from './global-flags';
+
+export interface LegendCliOptions {
+  readonly legend?: boolean;
+  readonly dot?: boolean;
+}
+
+/**
+ * The legend is decoration printed alongside the command header on stderr, so
+ * it is suppressed for the machine-readable / silent paths (`--json`, `--dot`,
+ * `--quiet`) exactly as the header is.
+ */
+export function shouldShowLegend(options: LegendCliOptions, flags: GlobalFlags): boolean {
+  return (
+    options.legend === true && options.dot !== true && flags.json !== true && flags.quiet !== true
+  );
+}
+
+export function validateLegendOptions(
+  options: LegendCliOptions,
+  flags: GlobalFlags,
+): Result<void, CliStructuredError> {
+  if (options.legend !== true) {
+    return ok(undefined);
+  }
+  if (flags.json === true) {
+    return notOk(errorLegendHumanOnly('--json'));
+  }
+  if (flags.quiet === true) {
+    return notOk(errorLegendHumanOnly('--quiet'));
+  }
+  if (options.dot === true) {
+    return notOk(errorLegendHumanOnly('--dot'));
+  }
+  return ok(undefined);
+}

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

@@ -0,0 +1,60 @@
+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);
+}
+
+/**
+ * Resolve a filesystem-path target to the migration dir that contains it,
+ * searching each in-scope space's `migrationsDir`. A path is explicit, so
+ * it can belong to at most one space — returns the first match, or `null`
+ * when the path falls outside every space dir.
+ */
+export function resolveTargetPathAcrossSpaces(
+  target: string,
+  spaces: ReadonlyArray<{ readonly migrationsDir: string }>,
+): string | null {
+  const targetPath = resolve(target);
+  for (const space of spaces) {
+    const rel = relative(space.migrationsDir, targetPath);
+    const isOutside = rel === '' || rel === '.' || rel.startsWith('..') || isAbsolute(rel);
+    if (!isOutside) {
+      return targetPath;
+    }
+  }
+  return null;
+}
+
+export function findPackageByDirPath(
+  packages: readonly OnDiskMigrationPackage[],
+  resolvedDirPath: string,
+): OnDiskMigrationPackage | undefined {
+  const normalized = resolve(resolvedDirPath);
+  return packages.find((p) => resolve(p.dirPath) === normalized);
+}