@prisma-next/cli 0.11.0 → 0.12.0

package/src/control-api/operations/migration-apply.ts

@@ -7,16 +7,16 @@ import type {
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
 import {
-  type AggregatePerSpacePlan,
   type ContractMarkerRecordLike,
   type ContractSpaceAggregate,
   type ContractSpaceMember,
   graphWalkStrategy,
+  type PerSpacePlan,
+  requireHeadRef,
 } from '@prisma-next/migration-tools/aggregate';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { errorNoInvariantPath } from '@prisma-next/migration-tools/errors';
 import { findPathWithDecision } from '@prisma-next/migration-tools/migration-graph';
-import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import {
@@ -24,14 +24,14 @@ import {
   buildContractSpaceAggregate,
 } from '../../utils/contract-space-aggregate-loader';
 import type {
-  AggregatePerSpaceExecutionEntry,
   MigrationApplyFailure,
   MigrationApplyPathDecision,
   MigrationApplyResult,
   MigrationApplySuccess,
   OnControlProgress,
+  PerSpaceExecutionEntry,
 } from '../types';
-import { applyAggregate, buildPerSpaceBreakdown } from './apply-aggregate';
+import { applyMigration, buildPerSpaceBreakdown } from './apply';
 
 /**
  * Inputs for the aggregate-walking `migrate` control-api
@@ -56,21 +56,10 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
   readonly migrationsDir: string;
   readonly extensionPacks: ReadonlyArray<ControlExtensionDescriptor<TFamilyId, TTargetId>>;
   readonly targetId: TTargetId;
-  /**
-   * Already-loaded app-space migration packages. The CLI command
-   * loads these via `loadMigrationPackages(appMigrationsDir)`; the
-   * operation hydrates the app member's graph with them. Required
-   * because the framework-neutral aggregate loader doesn't know how
-   * to read the user's `migrations/` directory layout (it's family-
-   * aware: ops.json shape, manifest keys, etc.).
-   */
-  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
   /**
    * Optional app-space ref override. When provided, the app member's
    * graph-walk targets this hash instead of `member.headRef.hash`.
    * Extensions are unaffected — they always walk to their own head.
-   *
-   * Sub-spec § `--ref <hash>` semantics under multi-space.
    */
   readonly refHash?: string;
   /**
@@ -106,7 +95,7 @@ export interface ExecuteMigrationApplyOptions<TFamilyId extends string, TTargetI
  *    marker to `member.headRef.hash` (or `refHash` for the app
  *    member when provided). Empty-graph members fail loudly — a
  *    "never planned" space is a user-error condition for replay.
- * 4. Hand off to {@link applyAggregate} (the runner-driving tail
+ * 4. Hand off to {@link applyMigration} (the runner-driving tail
  *    shared with `db init` / `db update`). Marker advancement is
  *    inside the per-space transaction.
  *
@@ -125,7 +114,6 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     migrationsDir,
     extensionPacks,
     targetId,
-    appMigrationPackages,
     refHash,
     refInvariants,
     refName,
@@ -138,7 +126,6 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     appContract: contract,
     extensionPacks,
     deserializeContract: (json) => familyInstance.deserializeContract(json),
-    appMigrationPackages,
   };
   const loaded = await buildContractSpaceAggregate(loadInputs);
   if (!loaded.ok) {
@@ -152,21 +139,24 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
   // when provided, otherwise its own head; extensions always walk
   // to their own head ref.
   const allMembers: ReadonlyArray<ContractSpaceMember> = [aggregate.app, ...aggregate.extensions];
-  const perSpacePlans = new Map<string, AggregatePerSpacePlan>();
+  const perSpacePlans = new Map<string, PerSpacePlan>();
   // Already-at-head empty-graph members (typically extensions whose
   // head ref is the empty sentinel, or whose live marker already
   // matches the target). Kept out of the runner schedule so we don't
   // write spurious markers for greenfield extensions, but merged back
   // into the success envelope so every loaded member is represented.
-  const atHeadResolutions = new Map<string, AggregatePerSpacePlan>();
+  const atHeadResolutions = new Map<string, PerSpacePlan>();
   for (const member of allMembers) {
     const isAppMember = member.spaceId === aggregate.app.spaceId;
-    const targetHash = isAppMember && refHash !== undefined ? refHash : member.headRef.hash;
+    // The aggregate passed the integrity gate, so every member's head ref
+    // is resolved (the app's is synthesised from the live contract).
+    const headRef = requireHeadRef(member);
+    const targetHash = isAppMember && refHash !== undefined ? refHash : headRef.hash;
     const liveMarker = markerRows.get(member.spaceId) ?? null;
 
     // Empty-graph members fail loudly: replay needs an on-disk path
     // and an empty graph means the user has never planned this space.
-    if (member.migrations.graph.nodes.size === 0) {
+    if (member.graph().nodes.size === 0) {
       // Edge case: target == EMPTY (greenfield, nothing to do) or
       // the live marker already matches the target. Loader integrity
       // allows this for extensions whose head ref is the empty
@@ -197,9 +187,9 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     const targetInvariants =
       isAppMember && refHash !== undefined && refInvariants !== undefined
         ? refInvariants
-        : member.headRef.invariants;
+        : headRef.invariants;
     const targetMember: ContractSpaceMember =
-      targetHash === member.headRef.hash && targetInvariants === member.headRef.invariants
+      targetHash === headRef.hash && targetInvariants === headRef.invariants
         ? member
         : { ...member, headRef: { hash: targetHash, invariants: targetInvariants } };
 
@@ -224,7 +214,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
       // is never a graph node, producing an empty `structuralPath` and
       // a less actionable diagnostic.
       const fromHash = liveMarker?.storageHash ?? EMPTY_CONTRACT_HASH;
-      const structural = findPathWithDecision(targetMember.migrations.graph, fromHash, targetHash, {
+      const structural = findPathWithDecision(targetMember.graph(), fromHash, targetHash, {
         required: new Set<string>(),
       });
       const structuralPath =
@@ -286,7 +276,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     );
   }
 
-  const applied = await applyAggregate({
+  const applied = await applyMigration({
     aggregate,
     perSpacePlans,
     applyOrder,
@@ -346,7 +336,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
 }
 
 /**
- * Build a zero-op {@link AggregatePerSpacePlan} for an empty-graph
+ * Build a zero-op {@link PerSpacePlan} for an empty-graph
  * member whose live marker already matches the target. Lets the apply
  * pipeline thread the member through `perSpacePlans` -> `applyOrder`
  * -> the success envelope's `perSpace[]` block so the result reflects
@@ -357,7 +347,7 @@ function buildAtHeadResolution(args: {
   readonly member: ContractSpaceMember;
   readonly targetHash: string;
   readonly liveMarker: ContractMarkerRecordLike | null;
-}): AggregatePerSpacePlan {
+}): PerSpacePlan {
   const { aggregateTargetId, member, targetHash, liveMarker } = args;
   return {
     plan: {
@@ -369,7 +359,7 @@ function buildAtHeadResolution(args: {
       providedInvariants: [],
     },
     displayOps: [],
-    destinationContract: member.contract,
+    destinationContract: member.contract(),
     strategy: 'graph-walk',
     migrationEdges: [],
   };
@@ -377,7 +367,7 @@ function buildAtHeadResolution(args: {
 
 function sumPlannedOps(
   applyOrder: readonly string[],
-  perSpacePlans: ReadonlyMap<string, AggregatePerSpacePlan>,
+  perSpacePlans: ReadonlyMap<string, PerSpacePlan>,
 ): number {
   let total = 0;
   for (const spaceId of applyOrder) {
@@ -392,28 +382,27 @@ interface BuildSuccessArgs {
   readonly aggregate: ContractSpaceAggregate;
   readonly orderedResolutions: ReadonlyArray<{
     readonly spaceId: string;
-    readonly entry: AggregatePerSpacePlan;
+    readonly entry: PerSpacePlan;
   }>;
-  readonly perSpace: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly perSpace: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly totalOpsExecuted: number;
   readonly summary: string;
 }
 
 function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
   // The marker hash surfaced at the top level is the **app member's**
-  // post-apply marker (today's single-space `markerHash` field).
+  // post-apply marker (the top-level `markerHash` field).
   // Per-space markers live on `perSpace[].marker.storageHash`.
   const appResolution = args.orderedResolutions.find(
     (r) => r.spaceId === args.aggregate.app.spaceId,
   );
   const appMarkerHash =
-    appResolution?.entry.plan.destination.storageHash ?? args.aggregate.app.headRef.hash;
+    appResolution?.entry.plan.destination.storageHash ?? requireHeadRef(args.aggregate.app).hash;
 
   // Per-migration entries (one per authored edge) preserve the
-  // single-space `migrationsApplied` count semantics for back-compat
-  // with existing JSON-shape consumers (e.g. `parsed.applied.length`
-  // in integration tests). The aggregate per-space breakdown lives on
-  // `perSpace[]`.
+  // `migrationsApplied` count semantics for back-compat with existing
+  // JSON-shape consumers (e.g. `parsed.applied.length` in integration
+  // tests). The aggregate per-space breakdown lives on `perSpace[]`.
   const applied = args.orderedResolutions.flatMap((r) => {
     const edges = r.entry.migrationEdges ?? [];
     return edges.map((edge) => ({
@@ -458,26 +447,46 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
   };
 }
 
-function buildNeverPlannedFailure(spaceId: string, targetHash: string): MigrationApplyFailure {
+/**
+ * Build the `neverPlanned` failure raised when a contract space has no on-disk
+ * migration graph but migrate was asked to reach a target hash. The `why`
+ * states only the condition; the recovery sequence is composed by
+ * `errorPathUnreachable`'s `fix`.
+ *
+ * @internal Exported for testing only.
+ */
+export function buildNeverPlannedFailure(
+  spaceId: string,
+  targetHash: string,
+): MigrationApplyFailure {
   return {
     code: 'MIGRATION_PATH_NOT_FOUND',
     summary: `No on-disk migrations for contract space "${spaceId}"`,
-    why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}". Run \`prisma-next migration plan\` first to materialise the path.`,
+    why: `migrate is replay-only: every contract space must have an authored migration graph on disk. Space "${spaceId}" has no migrations under \`migrations/${spaceId}/\` but its head ref targets "${targetHash}".`,
     meta: { spaceId, target: targetHash, kind: 'neverPlanned' },
   };
 }
 
-function buildPathNotFoundFailure(
+/**
+ * Build the `pathUnreachable` failure raised when an emitted contract has no
+ * on-disk migration edge from the current marker to the target. The `why`
+ * states only the condition (no edge between the two named states, and migrate
+ * replays edges rather than inventing them); the recovery sequence — plan the
+ * edge, then re-apply — is composed by `errorPathUnreachable`'s `fix`, so the
+ * two read as one non-redundant plan-then-apply story.
+ *
+ * @internal Exported for testing only.
+ */
+export function buildPathNotFoundFailure(
   spaceId: string,
   marker: ContractMarkerRecordLike | null,
   targetHash: string,
 ): MigrationApplyFailure {
   const fromHash = marker?.storageHash ?? '<empty>';
-  // The single-space-degenerate phrasing names the user-visible
-  // condition (a contract has been emitted that no on-disk
-  // migration reaches) so the error reads naturally for the
-  // single-space app case. Multi-space callers see the same
-  // condition expressed against the offending space.
+  // The app-case phrasing names the user-visible condition (a
+  // contract has been emitted that no on-disk migration reaches) so
+  // the error reads naturally for the app member. Extension spaces
+  // see the same condition expressed against the offending space.
   const summary =
     spaceId === 'app'
       ? 'Current contract has no planned migration path'
@@ -485,7 +494,7 @@ function buildPathNotFoundFailure(
   return {
     code: 'MIGRATION_PATH_NOT_FOUND',
     summary,
-    why: `Cannot reach target "${targetHash}" from current marker "${fromHash}" in space "${spaceId}". The on-disk migration graph for this space does not connect the two states. Run \`prisma-next migration plan\` to materialise the path.`,
+    why: `No migration edge connects the current state "${fromHash}" to the target "${targetHash}" in contract space "${spaceId}". The on-disk migration graph does not join the two, and migrate replays existing edges — it never invents one.`,
     meta: { spaceId, fromHash, targetHash, kind: 'pathUnreachable' },
   };
 }

package/src/control-api/types.ts

@@ -18,7 +18,6 @@ import type {
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
 import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
-import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import type { Result } from '@prisma-next/utils/result';
 import type { ExecuteDbVerifyResult } from './operations/db-verify';
 
@@ -246,7 +245,7 @@ export interface DbUpdateOptions {
  * Options for the dbVerify operation.
  *
  * Drives the loader → aggregate-verifier pipeline. `strict` maps to
- * `verifyAggregate({ mode: 'strict' | 'lenient' })`; `skipSchema`
+ * `verifyMigration({ mode: 'strict' | 'lenient' })`; `skipSchema`
  * mirrors the `--marker-only` CLI flag and short-circuits the schema
  * portion of the verifier.
  */
@@ -327,7 +326,7 @@ export interface EmitOptions {
  * to the user instead of being collapsed into a single ambiguous
  * top-level hash.
  */
-export interface AggregatePerSpaceExecutionEntry {
+export interface PerSpaceExecutionEntry {
   readonly spaceId: string;
   /** `'app'` for the application's contract space; `'extension'` for any extension space. */
   readonly kind: 'app' | 'extension';
@@ -388,9 +387,9 @@ export interface DbInitSuccess {
    * alphabetically, then app). Present whenever the aggregate flow
    * produced one — both `mode: 'plan'` and `mode: 'apply'`.
    *
-   * See {@link AggregatePerSpaceExecutionEntry}.
+   * See {@link PerSpaceExecutionEntry}.
    */
-  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
 }
 
@@ -458,9 +457,9 @@ export interface DbUpdateSuccess {
   };
   /**
    * Per-space breakdown in canonical schedule order (extensions
-   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   * alphabetically, then app). See {@link PerSpaceExecutionEntry}.
    */
-  readonly perSpace?: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
 }
 
@@ -539,7 +538,7 @@ export type EmitResult = Result<EmitSuccess, EmitFailure>;
  * 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 `applyAggregate` primitive. The CLI command
+ * through the shared `applyMigration` primitive. The CLI command
  * just resolves the descriptor surface (config, refs, contract
  * envelope, app-space migration packages) and hands the inputs in.
  */
@@ -548,12 +547,6 @@ export interface MigrationApplyOptions {
   readonly contract: unknown;
   /** Migrations root directory (`migrations/` under the project). */
   readonly migrationsDir: string;
-  /**
-   * Already-loaded app-space migration packages. The CLI loads these
-   * via `loadMigrationPackages(appMigrationsDir)` before invoking
-   * `migrationApply`.
-   */
-  readonly appMigrationPackages: ReadonlyArray<OnDiskMigrationPackage>;
   /**
    * Optional app-space ref override. When provided, the app member's
    * graph-walk targets this hash instead of `contract.storage.storageHash`.
@@ -584,11 +577,11 @@ export interface MigrationApplyOptions {
 
 /**
  * A single on-disk migration package surfaced to the operation. The
- * SQL family already produces this shape via `loadMigrationPackages`;
- * the operation hands it through to the framework-neutral aggregate
- * loader's `appMigrationPackages` slot.
+ * SQL family surfaces this shape from the tolerant contract-space
+ * aggregate's app packages; the operation hands it through to the
+ * framework-neutral aggregate loader's `appMigrationPackages` slot.
  *
- * (Originally named `MigrationApplyStep` for the legacy single-space
+ * (Originally named `MigrationApplyStep` for the earlier app-only
  * apply path; the name is kept for compatibility with existing CLI
  * callers and tests.)
  */
@@ -612,8 +605,8 @@ export interface MigrationApplyStep {
  */
 /**
  * One entry per authored migration package applied. Preserves the
- * single-space `migrationsApplied` count semantics (each entry is
- * one migration directory) so `applied.length === migrationsApplied`.
+ * `migrationsApplied` count semantics (each entry is one migration
+ * directory) so `applied.length === migrationsApplied`.
  *
  * Per-space aggregate detail (markers, ops grouped by space) lives
  * on `perSpace[]`; this list is the per-edge view.
@@ -628,16 +621,15 @@ export interface MigrationApplyAppliedEntry {
 }
 
 /**
- * Successful migrationApply result. Carries both the legacy
- * single-space fields (`markerHash` is the **app member's** post-apply
- * marker, surfaced for back-compat with single-space callers) and the
+ * Successful migrationApply result. Carries both the top-level fields
+ * (`markerHash` is the **app member's** post-apply marker) and the
  * per-space breakdown (`perSpace` — markers / operations in canonical
  * schedule order).
  */
 /**
  * Path-decision summary for the **app member** post-apply. Surfaced
- * for back-compat with single-space callers (and the cli-journeys
- * suite, which inspects `requiredInvariants`/`satisfiedInvariants`/
+ * at the top level (and consumed by the cli-journeys suite, which
+ * inspects `requiredInvariants`/`satisfiedInvariants`/
  * `selectedPath` to validate invariant routing).
  *
  * Per-space path decisions for extension members are not surfaced —
@@ -667,10 +659,10 @@ export interface MigrationApplySuccess {
   readonly summary: string;
   /**
    * Per-space breakdown in canonical schedule order (extensions
-   * alphabetically, then app). See {@link AggregatePerSpaceExecutionEntry}.
+   * alphabetically, then app). See {@link PerSpaceExecutionEntry}.
    * Always present for the aggregate-walking operation.
    */
-  readonly perSpace: ReadonlyArray<AggregatePerSpaceExecutionEntry>;
+  readonly perSpace: ReadonlyArray<PerSpaceExecutionEntry>;
   /**
    * Path-decision data for the app member. Present whenever the
    * graph-walk strategy ran for the app (i.e. always for the
@@ -719,6 +711,13 @@ export type MigrationApplyResult = Result<MigrationApplySuccess, MigrationApplyF
 export interface ContractEmitOptions {
   /** Path to the prisma-next.config.ts file */
   readonly configPath: string;
+  /**
+   * Directory to write contract artifacts into. When set, `contract.json` and
+   * `contract.d.ts` are written inside this directory, taking precedence over
+   * any output path from the loaded config. The value must be an absolute path;
+   * resolution against cwd is the caller's responsibility.
+   */
+  readonly outputPath?: string;
   /** Optional AbortSignal for cancelling the in-flight emit */
   readonly signal?: AbortSignal;
   /** Optional progress callback for observing source-resolution and emit spans */

package/src/migration-cli.ts

@@ -461,8 +461,8 @@ function writeStructuredError(stream: MigrationCliWritable, err: CliStructuredEr
  * `null` when the file is missing and throwing `MIGRATION.INVALID_JSON`
  * when the file is present but cannot be parsed as JSON. The CLI feeds
  * this into `buildMigrationArtifacts` so the pure builder can preserve
- * fields owned by `migration plan` (contract bookends, hints, labels,
- * `createdAt`) across re-emits.
+ * fields owned by `migration plan` (contract bookends, `createdAt`) across
+ * re-emits.
  *
  * Author-time path: this loader still does not verify the manifest hash
  * or schema — that is the apply-time loader's job. Hash mismatch is the
@@ -472,8 +472,8 @@ function writeStructuredError(stream: MigrationCliWritable, err: CliStructuredEr
  * however, is now surfaced rather than swallowed: a malformed
  * `migration.json` indicates either a hand-edit gone wrong or partial
  * write, and silently rebuilding from `describe()` would discard the
- * user's on-disk content (preserved bookends, hints, labels,
- * `createdAt`) without any indication something was wrong on disk.
+ * user's on-disk content (preserved bookends, `createdAt`) without any
+ * indication something was wrong on disk.
  * Apply-time consumers always route through the verifying
  * `readMigrationPackage` in `@prisma-next/migration-tools/io` instead.
  */