@prisma-next/cli 0.12.0-dev.5 → 0.12.0-dev.50

package/src/control-api/operations/{apply.ts → run-migration.ts}

@@ -1,3 +1,8 @@
+/**
+ * Shared runner tail (`runMigration` + `buildPerSpaceBreakdown`/`collectOrdered`).
+ * Backs no command directly; consumed by db-run and migrate.
+ */
+
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
   ControlDriverInstance,
@@ -11,32 +16,32 @@ import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import type { OnControlProgress, PerSpaceExecutionEntry } from '../types';
 
 /**
- * Span id emitted via `onProgress` for the apply phase. Stable
+ * Span id emitted via `onProgress` for the run phase. Stable
  * identifier consumed by the structured-output renderer and by tests.
  */
-const APPLY_SPAN_ID = 'apply' as const;
+const RUN_SPAN_ID = 'apply' as const;
 
 /**
- * Action that originated this apply call. Threaded into `OnControlProgress`
+ * Action that originated this run call. Threaded into `OnControlProgress`
  * events so the parent CLI command can attribute the span correctly,
  * and used to compose action-specific summary phrasing.
  */
-export type ApplyAction = 'dbInit' | 'dbUpdate' | 'migrationApply';
+export type RunAction = 'dbInit' | 'dbUpdate' | 'migrate';
 
 /**
- * Failure variant emitted by {@link applyMigration} when the runner
- * itself rejects the apply. Mirrors the failure shape callers
+ * Failure variant emitted by {@link runMigration} when the runner
+ * itself rejects the run. Mirrors the failure shape callers
  * already wrap into their own action-specific failure envelopes
- * (`DbInitFailure`, `DbUpdateFailure`, `MigrationApplyFailure`) so each
+ * (`DbInitFailure`, `DbUpdateFailure`, `MigrateFailure`) so each
  * caller keeps owning its own discriminated failure code.
  */
-export interface ApplyRunnerFailure {
+export interface RunnerFailure {
   readonly summary: string;
   readonly why?: string;
   readonly meta: Record<string, unknown>;
 }
 
-export interface ApplyMigrationInputs<TFamilyId extends string, TTargetId extends string> {
+export interface RunMigrationInputs<TFamilyId extends string, TTargetId extends string> {
   readonly aggregate: ContractSpaceAggregate;
   /**
    * Per-space plans, keyed by `spaceId`. Produced by either the full
@@ -62,22 +67,22 @@ export interface ApplyMigrationInputs<TFamilyId extends string, TTargetId extend
   >;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
   readonly policy: MigrationOperationPolicy;
-  readonly action: ApplyAction;
+  readonly action: RunAction;
   readonly onProgress?: OnControlProgress;
 }
 
 /**
  * Resolved per-space plan in canonical schedule order. Surfaced from
- * {@link applyMigration} to callers so each one can build its own
+ * {@link runMigration} to callers so each one can build its own
  * action-specific success envelope (e.g. `DbInitSuccess` vs
- * `MigrationApplySuccess`) without re-deriving the ordering.
+ * `MigrateSuccess`) without re-deriving the ordering.
  */
 export interface OrderedResolution {
   readonly spaceId: string;
   readonly entry: PerSpacePlan;
 }
 
-export interface ApplyMigrationValue {
+export interface RunMigrationValue {
   readonly orderedResolutions: readonly OrderedResolution[];
   readonly totalOpsPlanned: number;
   readonly totalOpsExecuted: number;
@@ -89,10 +94,10 @@ export interface ApplyMigrationValue {
   readonly perSpace: readonly PerSpaceExecutionEntry[];
 }
 
-export type ApplyMigrationResult = Result<ApplyMigrationValue, ApplyRunnerFailure>;
+export type RunMigrationResult = Result<RunMigrationValue, RunnerFailure>;
 
 /**
- * Runner-driving tail shared by every apply caller — `db init`,
+ * Runner-driving tail shared by every run caller — `db init`,
  * `db update`, and `migrate`. Consumes already-resolved per-space
  * plans (the planner-vs-replay distinction is owned by the caller) and
  * dispatches them to the runner in canonical order.
@@ -107,9 +112,9 @@ export type ApplyMigrationResult = Result<ApplyMigrationValue, ApplyRunnerFailur
  * so callers don't have to duplicate it; the `action` field on each
  * progress event is taken from the caller's `action` argument.
  */
-export async function applyMigration<TFamilyId extends string, TTargetId extends string>(
-  inputs: ApplyMigrationInputs<TFamilyId, TTargetId>,
-): Promise<ApplyMigrationResult> {
+export async function runMigration<TFamilyId extends string, TTargetId extends string>(
+  inputs: RunMigrationInputs<TFamilyId, TTargetId>,
+): Promise<RunMigrationResult> {
   const {
     aggregate,
     perSpacePlans,
@@ -130,7 +135,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
   onProgress?.({
     action,
     kind: 'spanStart',
-    spanId: APPLY_SPAN_ID,
+    spanId: RUN_SPAN_ID,
     label: progressLabelForAction(action),
   });
 
@@ -141,6 +146,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
     destinationContract: r.entry.destinationContract,
     policy,
     frameworkComponents,
+    migrationEdges: r.entry.migrationEdges,
     // Per-space post-apply schema verification is non-strict: each
     // space's `destinationContract` describes only its own slice; a
     // strict verifier would treat every other space's tables as
@@ -151,7 +157,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
   const runnerResult = await runner.execute({ driver, perSpaceOptions });
 
   if (!runnerResult.ok) {
-    onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'error' });
+    onProgress?.({ action, kind: 'spanEnd', spanId: RUN_SPAN_ID, outcome: 'error' });
     return notOk({
       summary: runnerResult.failure.summary,
       ...ifDefined('why', runnerResult.failure.why),
@@ -162,7 +168,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
       },
     });
   }
-  onProgress?.({ action, kind: 'spanEnd', spanId: APPLY_SPAN_ID, outcome: 'ok' });
+  onProgress?.({ action, kind: 'spanEnd', spanId: RUN_SPAN_ID, outcome: 'ok' });
 
   const totalOpsPlanned = runnerResult.value.perSpaceResults.reduce(
     (sum, r) => sum + r.value.operationsPlanned,
@@ -194,7 +200,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
  * advances as the last step of each space's transaction) and `false`
  * for plan-mode (no marker has been written yet).
  *
- * Exported alongside {@link applyMigration} so plan-mode callers can
+ * Exported alongside {@link runMigration} so plan-mode callers can
  * assemble the same per-space block without going through the runner.
  */
 export function buildPerSpaceBreakdown(
@@ -243,18 +249,18 @@ export function collectOrdered(
 }
 
 /**
- * Action-appropriate label for the `spanStart` event the apply
- * primitive emits. `applyMigration` is shared by `db init`, `db update`,
+ * Action-appropriate label for the `spanStart` event the run
+ * primitive emits. `runMigration` is shared by `db init`, `db update`,
  * and `migrate`; the span label tracks the user-visible action
  * so structured-progress output reads naturally for each surface.
  */
-export function progressLabelForAction(action: ApplyAction): string {
+export function progressLabelForAction(action: RunAction): string {
   switch (action) {
     case 'dbInit':
       return 'Initialising database across spaces';
     case 'dbUpdate':
       return 'Updating database across spaces';
-    case 'migrationApply':
-      return 'Applying migration plan across spaces';
+    case 'migrate':
+      return 'Running migration plan across spaces';
   }
 }

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)}`)}`);
   }