@prisma-next/cli 0.12.0-dev.6 → 0.12.0-dev.60

package/src/control-api/types.ts

@@ -2,7 +2,11 @@ import type {
   ContractSourceDiagnostics,
   ContractSourceProvider,
 } from '@prisma-next/config/config-types';
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
@@ -67,7 +71,7 @@ export type ControlActionName =
   | 'dbInit'
   | 'dbUpdate'
   | 'dbVerify'
-  | 'migrationApply'
+  | 'migrate'
   | 'verify'
   | 'schemaVerify'
   | 'sign'
@@ -391,6 +395,7 @@ export interface DbInitSuccess {
    */
   readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
 }
 
 /**
@@ -406,6 +411,7 @@ export interface DbInitFailure {
   readonly summary: string;
   readonly why: string | undefined;
   readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
   readonly meta: Record<string, unknown> | undefined;
   readonly marker?: {
     readonly storageHash?: string;
@@ -461,6 +467,7 @@ export interface DbUpdateSuccess {
    */
   readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
 }
 
 /**
@@ -476,6 +483,7 @@ export interface DbUpdateFailure {
   readonly summary: string;
   readonly why: string | undefined;
   readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
   readonly meta: Record<string, unknown> | undefined;
 }
 
@@ -532,17 +540,17 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
 // ============================================================================
 
 /**
- * Options for the aggregate-walking `migrationApply` operation.
+ * Options for the aggregate-walking `migrate` operation.
  *
  * The control-api operation is responsible for: loading the
  * contract-space aggregate, reading per-space marker rows from the
  * live database, plotting per-space paths via `graphWalkStrategy`
  * (replay-only — no synth, no introspection), and dispatching
- * through the shared `applyMigration` primitive. The CLI command
+ * through the shared `runMigration` primitive. The CLI command
  * just resolves the descriptor surface (config, refs, contract
  * envelope, app-space migration packages) and hands the inputs in.
  */
-export interface MigrationApplyOptions {
+export interface MigrateOptions {
   /** Already-validated app contract (the canonical "where we are heading" hash). */
   readonly contract: unknown;
   /** Migrations root directory (`migrations/` under the project). */
@@ -567,7 +575,7 @@ export interface MigrationApplyOptions {
    */
   readonly refName?: string;
   /**
-   * Database connection. If provided, migrationApply will connect before executing.
+   * Database connection. If provided, migrate will connect before executing.
    * If omitted, the client must already be connected.
    */
   readonly connection?: unknown;
@@ -611,7 +619,7 @@ export interface MigrationApplyStep {
  * Per-space aggregate detail (markers, ops grouped by space) lives
  * on `perSpace[]`; this list is the per-edge view.
  */
-export interface MigrationApplyAppliedEntry {
+export interface MigrateRanEntry {
   readonly spaceId: string;
   readonly dirName: string;
   readonly migrationHash: string;
@@ -621,13 +629,13 @@ export interface MigrationApplyAppliedEntry {
 }
 
 /**
- * Successful migrationApply result. Carries both the top-level fields
- * (`markerHash` is the **app member's** post-apply marker) and the
+ * Successful migrate result. Carries both the top-level fields
+ * (`markerHash` is the **app member's** post-migrate marker) and the
  * per-space breakdown (`perSpace` — markers / operations in canonical
  * schedule order).
  */
 /**
- * Path-decision summary for the **app member** post-apply. Surfaced
+ * Path-decision summary for the **app member** post-migrate. Surfaced
  * at the top level (and consumed by the cli-journeys suite, which
  * inspects `requiredInvariants`/`satisfiedInvariants`/
  * `selectedPath` to validate invariant routing).
@@ -635,7 +643,7 @@ export interface MigrationApplyAppliedEntry {
  * Per-space path decisions for extension members are not surfaced —
  * extensions own their own ref/invariant control.
  */
-export interface MigrationApplyPathDecision {
+export interface MigratePathDecision {
   readonly fromHash: string;
   readonly toHash: string;
   readonly alternativeCount: number;
@@ -652,10 +660,10 @@ export interface MigrationApplyPathDecision {
   }[];
 }
 
-export interface MigrationApplySuccess {
+export interface MigrateSuccess {
   readonly migrationsApplied: number;
   readonly markerHash: string;
-  readonly applied: readonly MigrationApplyAppliedEntry[];
+  readonly applied: readonly MigrateRanEntry[];
   readonly summary: string;
   /**
    * Per-space breakdown in canonical schedule order (extensions
@@ -666,31 +674,31 @@ export interface MigrationApplySuccess {
   /**
    * Path-decision data for the app member. Present whenever the
    * graph-walk strategy ran for the app (i.e. always for the
-   * aggregate-walking apply path). Absent only for the no-op
+   * aggregate-walking migrate path). Absent only for the no-op
    * "Already up to date" early return when the app has no plan.
    */
-  readonly pathDecision?: MigrationApplyPathDecision;
+  readonly pathDecision?: MigratePathDecision;
 }
 
 /**
- * Failure codes for migrationApply operation.
+ * Failure codes for migrate operation.
  */
-export type MigrationApplyFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
+export type MigrateFailureCode = 'RUNNER_FAILED' | 'MIGRATION_PATH_NOT_FOUND';
 
 /**
- * Failure details for migrationApply operation.
+ * Failure details for migrate operation.
  */
-export interface MigrationApplyFailure {
-  readonly code: MigrationApplyFailureCode;
+export interface MigrateFailure {
+  readonly code: MigrateFailureCode;
   readonly summary: string;
   readonly why: string | undefined;
   readonly meta: Record<string, unknown> | undefined;
 }
 
 /**
- * Result type for migrationApply operation.
+ * Result type for migrate operation.
  */
-export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyFailure>;
+export type MigrateResult = Result<MigrateSuccess, MigrateFailure>;
 
 // ============================================================================
 // Standalone Contract Emit Types
@@ -877,17 +885,26 @@ export interface ControlClient {
   readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
 
   /**
-   * Applies pre-planned on-disk migrations to the database.
+   * Reads the per-migration ledger journal for `space` in apply order.
+   * Returns an empty array when the ledger store does not yet exist or
+   * has no rows for that space.
+   */
+  readLedger(space?: string): Promise<readonly LedgerEntryRecord[]>;
+
+  /**
+   * Advances the database along the migration graph to the target contract.
    * Each migration runs in its own transaction with full execution checks.
-   * Resume-safe: re-running after failure picks up from the last applied migration.
+   * Resume-safe: re-running after failure picks up from the last run migration.
    *
-   * @param options.originHash - Explicit source hash for the apply path
-   * @param options.destinationHash - Explicit destination hash for the apply path
-   * @param options.pendingMigrations - Ordered migrations to execute
-   * @returns Result pattern: Ok with applied details, NotOk with failure details
+   * @param options.contract - The target contract to migrate to
+   * @param options.migrationsDir - Root migrations directory (`migrations/` under the project)
+   * @param options.refHash - Optional app-space ref override hash
+   * @param options.refInvariants - Required invariants on the user-supplied ref
+   * @param options.refName - Resolved name of the user-supplied app-space ref
+   * @returns Result pattern: Ok with migration details, NotOk with failure details
    * @throws If not connected, target doesn't support migrations, or infrastructure failure
    */
-  migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult>;
+  migrate(options: MigrateOptions): Promise<MigrateResult>;
 
   /**
    * Introspects the database schema.

package/src/utils/cli-errors.ts

@@ -28,7 +28,8 @@ 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 type { MigrationApplyFailure } from '../control-api/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { MigrateFailure } from '../control-api/types';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -108,6 +109,23 @@ export function errorRefSetEmptySentinel(hash: string): CliStructuredError {
   });
 }
 
+/**
+ * `--legend` was combined with a machine-readable or silent output flag.
+ * The legend is human-only decoration on stderr.
+ */
+export function errorLegendHumanOnly(
+  conflictingFlag: '--json' | '--dot' | '--quiet',
+): CliStructuredError {
+  return errorRuntime('`--legend` is only available for human-readable output', {
+    why: `\`--legend\` prints a glyph key to stderr and cannot be combined with ${conflictingFlag}.`,
+    fix: `Omit ${conflictingFlag} to print the legend alongside the tree, or omit --legend when using ${conflictingFlag}.`,
+    meta: {
+      code: 'MIGRATION.LEGEND_HUMAN_ONLY',
+      conflictingFlag,
+    },
+  });
+}
+
 /**
  * `--space <id>` was given a value that doesn't satisfy the contract-space
  * naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before
@@ -250,7 +268,7 @@ export function errorMarkerMismatch(
   });
 }
 
-export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {
+export function errorPathUnreachable(failure: MigrateFailure): CliStructuredError {
   const meta = failure.meta ?? {};
   const fromHashMeta = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
   // `buildPathNotFoundFailure` uses this sentinel in meta when the live marker is null.
@@ -325,10 +343,60 @@ 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.
  */
+/**
+ * A migration ref (dirName or hash-prefix) resolves in more than one contract
+ * space. The user must qualify with `--space <id>` to disambiguate.
+ */
+export function errorAmbiguousMigrationRef(
+  ref: string,
+  spaceIds: readonly string[],
+): CliStructuredError {
+  const spaceList = spaceIds.join(', ');
+  return errorRuntime(
+    `Ambiguous migration reference: "${ref}" resolves in multiple spaces — qualify with --space <id>`,
+    {
+      why: `"${ref}" matches migrations in spaces: ${spaceList}.`,
+      fix: `Qualify with --space <id> to select one space. Available matching spaces: ${spaceList}.`,
+      meta: {
+        code: 'MIGRATION.AMBIGUOUS_MIGRATION_REF',
+        ref,
+        spaceIds: [...spaceIds],
+      },
+    },
+  );
+}
+
 export function mapRefResolutionError(error: RefResolutionError): CliStructuredError {
   switch (error.kind) {
     case 'not-found':

package/src/utils/formatters/errors.ts

@@ -1,8 +1,11 @@
+import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
+import { blindCast } from '@prisma-next/utils/casts';
 import { red } from 'colorette';
 
 import type { CliErrorConflict, CliErrorEnvelope } from '../cli-errors';
 import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
+import { formatPlannerWarningsBlock } from './migrations';
 
 /**
  * Formats error output for human-readable display.
@@ -67,6 +70,14 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
   if (error.docsUrl && isVerbose(flags, 1)) {
     lines.push(formatDimText(error.docsUrl));
   }
+  const plannerWarnings = error.meta?.['plannerWarnings'];
+  if (Array.isArray(plannerWarnings) && plannerWarnings.length > 0) {
+    const typedWarnings = blindCast<
+      readonly MigrationPlannerConflict[],
+      'mapDbUpdateFailure (db-update.ts) writes meta.plannerWarnings as MigrationPlannerConflict[]; meta is typed Record<string, unknown> so the channel erases the element type'
+    >(plannerWarnings);
+    lines.push(...formatPlannerWarningsBlock(typedWarnings, useColor));
+  }
   if (isVerbose(flags, 2) && error.meta) {
     lines.push(`${formatDimText(`  Meta: ${JSON.stringify(error.meta, null, 2)}`)}`);
   }

package/src/utils/formatters/migration-graph-lane-colors.ts

@@ -0,0 +1,194 @@
+import { createColors } from 'colorette';
+import type { StructuralCell } from './migration-graph-layout';
+
+export type LaneColorizer = (text: string) => string;
+
+const { magenta, cyan, green, yellow, blueBright, red } = createColors({ useColor: true });
+
+export const LANE_COLOR_CYCLE: readonly LaneColorizer[] = [
+  magenta,
+  cyan,
+  green,
+  yellow,
+  blueBright,
+  red,
+];
+
+/**
+ * The leftmost lane (column 0) renders neutral — no palette hue. Columns ≥ 1
+ * rotate through {@link LANE_COLOR_CYCLE}.
+ */
+export const NEUTRAL_LANE_COLUMN = 0;
+
+/**
+ * The hue for a gutter column. The leftmost lane (column 0) is **neutral** — it
+ * has nothing to be told apart from in the common single-lane linear case, so
+ * the renderer dims it rather than tinting it; the rotating palette is reserved
+ * for columns ≥ 1 (where a second lane exists to distinguish). Callers must dim
+ * column 0 themselves; this returns identity for it as a guard. A lane freed and
+ * reused by a later branch keeps its column's hue — coloring is by position, not
+ * branch identity, exactly like `git log --graph`.
+ */
+export function laneColorForColumn(column: number): LaneColorizer {
+  if (column <= NEUTRAL_LANE_COLUMN) {
+    return (text) => text;
+  }
+  const colorizer = LANE_COLOR_CYCLE[(column - 1) % LANE_COLOR_CYCLE.length];
+  return colorizer ?? ((text) => text);
+}
+
+/**
+ * Style a structural glyph by its resolved colour column. Column 0 and the
+ * neutral sentinel render dim (`dimLane`); columns ≥ 1 take a palette hue.
+ */
+export function stylerForLaneColumn(
+  colorColumn: number,
+  colorize: boolean,
+  dimLane: (text: string) => string,
+): LaneColorizer {
+  if (!colorize || colorColumn <= NEUTRAL_LANE_COLUMN) {
+    return dimLane;
+  }
+  return laneColorForColumn(colorColumn);
+}
+
+/**
+ * The colour-source column for each cell of a row, resolved together because a
+ * routed back-arc spans columns and must read as **one hue** rather than a
+ * per-column "rainbow".
+ */
+export interface RowArcLaneColors {
+  /** Colour column for a cell's structural glyph (lane / spine / arc body). */
+  readonly lane: readonly number[];
+  /** Colour column for a node arc-pair's connector half (`◂` / `─`). */
+  readonly connector: readonly number[];
+  /**
+   * Colour column for the trailing `─` of a landing tee (`┴─`). The junction
+   * (`lane`) keeps its own column; the dash leads into the next converging arc.
+   */
+  readonly dash: readonly number[];
+}
+
+/**
+ * Resolve per-cell colour columns for a node/arc row. Scanning right-to-left
+ * lets each arc segment inherit the hue of the arc it leads into.
+ */
+export function resolveRowArcLaneColors(cells: readonly StructuralCell[]): RowArcLaneColors {
+  const lane = new Array<number>(cells.length);
+  const connector = new Array<number>(cells.length);
+  const dash = new Array<number>(cells.length);
+  let arcCorner = NEUTRAL_LANE_COLUMN;
+  let landingAnchor = NEUTRAL_LANE_COLUMN;
+  for (let column = cells.length - 1; column >= 0; column--) {
+    const cell = cells[column];
+    connector[column] = landingAnchor !== NEUTRAL_LANE_COLUMN ? landingAnchor : arcCorner;
+    switch (cell?.kind) {
+      case 'arc-branch-corner':
+        arcCorner = column;
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-land-corner':
+        arcCorner = column;
+        landingAnchor = column;
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-branch-tee':
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-land-tee':
+        lane[column] = column;
+        dash[column] = landingAnchor === NEUTRAL_LANE_COLUMN ? column : landingAnchor;
+        landingAnchor = column;
+        break;
+      case 'arc-crossing':
+      case 'arc-land-bridge': {
+        const served = landingAnchor !== NEUTRAL_LANE_COLUMN ? landingAnchor : arcCorner;
+        lane[column] = served;
+        dash[column] = served;
+        break;
+      }
+      case 'horizontal-pass':
+        lane[column] = arcCorner === NEUTRAL_LANE_COLUMN ? column : arcCorner;
+        dash[column] = lane[column] ?? column;
+        break;
+      case 'node':
+        lane[column] = column;
+        dash[column] = column;
+        arcCorner = NEUTRAL_LANE_COLUMN;
+        landingAnchor = NEUTRAL_LANE_COLUMN;
+        break;
+      default:
+        lane[column] = column;
+        dash[column] = column;
+        arcCorner = NEUTRAL_LANE_COLUMN;
+        landingAnchor = NEUTRAL_LANE_COLUMN;
+    }
+  }
+  return { lane, connector, dash };
+}
+
+/**
+ * Per-cell colour for a forward branch/merge connector row, split into the
+ * cell's junction `glyph` and its trailing `dash`.
+ */
+export interface ConnectorLaneColors {
+  /** Colour column for a cell's junction glyph (`├` / `┬` / `┴` / `╮` / `╯`). */
+  readonly glyph: readonly number[];
+  /** Colour column for a tee's trailing `─` — the branch it leads into. */
+  readonly dash: readonly number[];
+}
+
+/**
+ * Resolve per-cell connector colours. Scanning right-to-left, a corner or an
+ * intermediate tee anchors its own lane, but a tee's trailing dash leads into
+ * the branch on its right.
+ */
+export function resolveConnectorLaneColors(
+  cells: readonly StructuralCell[],
+  startLane: number,
+): ConnectorLaneColors {
+  const glyph = new Array<number>(cells.length);
+  const dash = new Array<number>(cells.length);
+  let owner = NEUTRAL_LANE_COLUMN;
+  for (let column = cells.length - 1; column >= 0; column--) {
+    const cell = cells[column];
+    switch (cell?.kind) {
+      case 'branch-corner':
+      case 'merge-corner':
+        owner = column;
+        glyph[column] = column;
+        dash[column] = column;
+        break;
+      case 'branch-tee':
+      case 'merge-tee':
+        if (column === startLane) {
+          const served = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+          glyph[column] = column;
+          dash[column] = served;
+        } else {
+          dash[column] = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+          glyph[column] = column;
+          owner = column;
+        }
+        break;
+      case 'arc-crossing':
+        glyph[column] = column;
+        dash[column] = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+        owner = column;
+        break;
+      case 'horizontal-pass': {
+        const served = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+        glyph[column] = served;
+        dash[column] = served;
+        break;
+      }
+      default:
+        glyph[column] = column;
+        dash[column] = column;
+    }
+  }
+  return { glyph, dash };
+}