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

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

@@ -12,11 +12,11 @@ import {
   type ContractSpaceAggregate,
   type ContractSpaceMember,
   graphWalkStrategy,
+  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 {
@@ -56,15 +56,6 @@ 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`.
@@ -125,7 +116,6 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     migrationsDir,
     extensionPacks,
     targetId,
-    appMigrationPackages,
     refHash,
     refInvariants,
     refName,
@@ -138,7 +128,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) {
@@ -161,12 +150,15 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
   const atHeadResolutions = new Map<string, AggregatePerSpacePlan>();
   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 +189,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 +216,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 =
@@ -369,7 +361,7 @@ function buildAtHeadResolution(args: {
       providedInvariants: [],
     },
     displayOps: [],
-    destinationContract: member.contract,
+    destinationContract: member.contract(),
     strategy: 'graph-walk',
     migrationEdges: [],
   };
@@ -407,7 +399,7 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
     (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

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';
 
@@ -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`.

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.
  */

package/src/utils/cli-errors.ts

@@ -28,6 +28,7 @@ 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';
 
 export {
   ERROR_CODE_DESTRUCTIVE_CHANGES,
@@ -68,6 +69,229 @@ export {
   errorUnexpected,
 };
 
+export function errorRefSetHashNotInGraph(
+  resolvedHash: string,
+  reachableHashes: readonly string[],
+  graphTipHash: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';
+  const fix =
+    reachableHashes.length > 0
+      ? graphTipHash !== null
+        ? `Set the ref to a graph-node hash such as ${graphTipHash}, or run \`prisma-next migration plan\` to extend the graph.`
+        : 'Set the ref to a hash that appears in the migration graph.'
+      : 'Run `prisma-next migration plan` first.';
+  return errorRuntime(`Resolved contract hash is not in the migration graph: ${resolvedHash}`, {
+    why:
+      reachableHashes.length > 0
+        ? `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`
+        : 'The migration graph is empty — no hashes reachable.',
+    fix,
+    meta: {
+      code: 'MIGRATION.HASH_NOT_IN_GRAPH',
+      resolvedHash,
+      reachableHashes: [...reachableHashes],
+      ...(graphTipHash !== null ? { graphTipHash } : {}),
+    },
+  });
+}
+
+export function errorRefSetEmptySentinel(hash: string): CliStructuredError {
+  return errorRuntime(`Cannot set ref to the empty-database sentinel: ${hash}`, {
+    why: 'The empty-database sentinel is a planner internal; it is not a valid ref target.',
+    fix: 'Set the ref to a contract hash from the migration graph, or use another ref name.',
+    meta: {
+      code: 'MIGRATION.REF_SET_EMPTY_SENTINEL',
+      hash,
+    },
+  });
+}
+
+/**
+ * `--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
+ * any fs work — the input is syntactically rejected the same way an on-disk
+ * directory with that name would be skipped by the enumerator.
+ */
+export function errorInvalidSpaceId(spaceId: string): CliStructuredError {
+  return errorRuntime(`Invalid contract space id: ${spaceId}`, {
+    why: 'Contract space ids must match [a-z][a-z0-9_-]{0,63} (lowercase, starts with a letter, max 64 characters — the rule applied to every on-disk space directory).',
+    fix: 'Pass a space id that matches the directory naming rule, or omit --space to list every space.',
+    meta: {
+      code: 'MIGRATION.INVALID_SPACE_ID',
+      spaceId,
+    },
+  });
+}
+
+/**
+ * `migration list --space <id>` was given a contract-space id that has no
+ * directory under `migrations/`. Distinct from "the space exists but is
+ * empty" — that path renders the empty-state line and exits 0 per the
+ * slice spec § Empty-state. This error fires only when `<projectMigrationsDir>/<spaceId>`
+ * does not exist on disk.
+ *
+ * `availableSpaces` lists the contract-space directory names actually
+ * present, sorted lex-asc, so the diagnostic can suggest a near match
+ * without making the user reach for `ls`.
+ */
+export function errorSpaceNotFound(
+  spaceId: string,
+  availableSpaces: readonly string[],
+): CliStructuredError {
+  const availableList =
+    availableSpaces.length > 0
+      ? availableSpaces.join(', ')
+      : '(none — no contract spaces on disk yet)';
+  const fix =
+    availableSpaces.length > 0
+      ? `Pick one of: ${availableList}. Run \`prisma-next migration list\` (no --space) to see every space's migrations.`
+      : 'Author a migration with `prisma-next migration new` to create the first contract-space directory.';
+  return errorRuntime(`Unknown contract space: ${spaceId}`, {
+    why: `No directory named "${spaceId}" exists under the migrations root.`,
+    fix,
+    meta: {
+      code: 'MIGRATION.SPACE_NOT_FOUND',
+      spaceId,
+      availableSpaces: [...availableSpaces],
+    },
+  });
+}
+
+export function errorRefSetBundleNotFound(hash: string): CliStructuredError {
+  return errorRuntime(`No migration bundle matches graph-node hash ${hash}`, {
+    why: `The hash is a graph node but no on-disk bundle has metadata.to = ${hash}.`,
+    fix: 'Run `pnpm fixtures:check`, or re-emit the migration that produces this hash so its bundle is restored.',
+    meta: {
+      code: 'MIGRATION.REF_SET_BUNDLE_NOT_FOUND',
+      hash,
+    },
+  });
+}
+
+export function errorPlanForgotTheFlag(
+  resolvedHash: string,
+  reachableRefs: ReadonlyArray<{ readonly name: string; readonly hash: string }>,
+  graphTipHash: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableRefs.length > 0
+      ? reachableRefs.map((r) => `${r.name} (${r.hash})`).join(', ')
+      : '(none)';
+  const refFix =
+    reachableRefs.length > 0
+      ? `Run migration plan with ${reachableRefs.map((r) => `--from ${r.name}`).join(' or ')}.`
+      : graphTipHash !== null
+        ? `Run migration plan --from ${graphTipHash}.`
+        : 'Commit pending migrations first, then run migration plan.';
+  return errorRuntime(`Resolved from-hash is not in the migration graph: ${resolvedHash}`, {
+    why: `The migration graph reaches ${reachableList}; resolved ${resolvedHash} isn't a graph node.`,
+    fix: refFix,
+    meta: {
+      code: 'MIGRATION.HASH_NOT_IN_GRAPH',
+      resolvedHash,
+      reachableRefs: reachableRefs.map((r) => r.name),
+      ...(graphTipHash !== null ? { graphTipHash } : {}),
+    },
+  });
+}
+
+export function errorSnapshotMissing(
+  identifier: string,
+  options?: { readonly viaRef?: boolean },
+): CliStructuredError {
+  const viaRef = options?.viaRef !== false;
+  const fix = viaRef
+    ? `Run "prisma-next db update --advance-ref ${identifier}" to repopulate the snapshot, or "prisma-next ref delete ${identifier}" to clear the orphan pointer.`
+    : `No contract source exists for hash "${identifier}" on an empty migration graph. Use --from with a ref name that has a paired snapshot, or run db update first.`;
+  return errorRuntime(
+    viaRef
+      ? `Ref "${identifier}" has no paired contract snapshot`
+      : `No contract source for from-hash "${identifier}"`,
+    {
+      why: viaRef
+        ? `Ref "${identifier}" exists but its paired snapshot files are missing.`
+        : `Hash "${identifier}" is not a graph node and no paired ref snapshot supplies a contract.`,
+      fix,
+      meta: {
+        code: 'MIGRATION.SNAPSHOT_MISSING',
+        identifier,
+        viaRef,
+      },
+    },
+  );
+}
+
+export function errorMarkerMismatch(
+  markerHash: string,
+  reachableHashes: readonly string[],
+  graphTip: string | null,
+): CliStructuredError {
+  const reachableList =
+    reachableHashes.length > 0 ? reachableHashes.join(', ') : '(none — migration graph is empty)';
+  const planFromFix =
+    graphTip !== null
+      ? `Run \`prisma-next migration plan --from ${graphTip}\` if the live marker is canonical and the on-disk graph needs catching up.`
+      : 'Run `prisma-next migration plan` if the live marker is canonical and the on-disk graph needs catching up.';
+  return errorRuntime('Database marker is not reachable in the on-disk migration graph', {
+    why: `DB marker is ${markerHash}, but the on-disk migration graph reaches: ${reachableList}.`,
+    fix: [
+      planFromFix,
+      `Run \`prisma-next ref set db ${markerHash}\` if the on-disk graph is canonical and the local \`db\` ref drifted.`,
+      'Investigate whether the database was migrated by an out-of-band process.',
+    ].join('\n'),
+    meta: {
+      code: 'MIGRATION.MARKER_MISMATCH',
+      markerHash,
+      reachableHashes: [...reachableHashes],
+      ...(graphTip !== null ? { graphTip } : {}),
+    },
+  });
+}
+
+export function errorPathUnreachable(failure: MigrationApplyFailure): CliStructuredError {
+  const meta = failure.meta ?? {};
+  const fromHash = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
+  const targetHash =
+    typeof meta['targetHash'] === 'string'
+      ? meta['targetHash']
+      : typeof meta['target'] === 'string'
+        ? meta['target']
+        : null;
+  const deadEnds = meta['deadEnds'];
+  const deadEndsSuffix =
+    Array.isArray(deadEnds) && deadEnds.length > 0
+      ? ` Dead-ends: ${deadEnds.map(String).join(', ')}.`
+      : '';
+  const planFix = (() => {
+    if (fromHash !== null && targetHash !== null) {
+      return `Run \`prisma-next migration plan --from ${fromHash} --to ${targetHash}\` to introduce the missing path.`;
+    }
+    if (targetHash !== null) {
+      return `Run \`prisma-next migration plan --to ${targetHash}\` to introduce the missing path.`;
+    }
+    if (fromHash !== null) {
+      return `Run \`prisma-next migration plan --from ${fromHash}\` to introduce the missing path.`;
+    }
+    return 'Run `prisma-next migration plan` to introduce the missing path.';
+  })();
+  return errorRuntime(failure.summary, {
+    why:
+      failure.why ??
+      `Cannot reach target "${targetHash ?? '<unknown>'}" from current marker "${fromHash ?? '<unknown>'}".${deadEndsSuffix}`,
+    fix: [
+      'Run `prisma-next migration list` to see the on-disk graph.',
+      planFix,
+      'Run `prisma-next migration show <bundle>` for any bundle in the path you expected.',
+    ].join('\n'),
+    meta: {
+      ...meta,
+      code: 'MIGRATION.PATH_UNREACHABLE',
+    },
+  });
+}
+
 /**
  * Maps a `MigrationToolsError` raised by the migration-tools loader/graph
  * surface (`readMigrationPackage`, `readMigrationsDir`, `readRefs`,

package/src/utils/command-helpers.ts

@@ -154,7 +154,7 @@ export function resolveMigrationPaths(
 
 /**
  * Slim representation of a PathDecision for CLI JSON output.
- * Strips internal fields (createdAt, labels) from path entries.
+ * Strips internal fields (createdAt) from path entries.
  */
 export interface PathDecisionResult {
   readonly fromHash: string;
@@ -242,9 +242,14 @@ export async function loadMigrationPackages(migrationsDir: string): Promise<{
   bundles: readonly OnDiskMigrationPackage[];
   graph: MigrationGraph;
 }> {
-  const bundles = await readMigrationsDir(migrationsDir);
-  const graph = reconstructGraph(bundles);
-  return { bundles, graph };
+  // `readMigrationsDir` is tolerant: it retains hash-/invariant-mismatched
+  // packages and omits unparseable ones, reporting both via `problems`.
+  // This helper preserves its historical `{ bundles, graph }` contract by
+  // exposing the retained packages; callers that need to surface load
+  // problems read them from the tolerant primitive directly.
+  const { packages } = await readMigrationsDir(migrationsDir);
+  const graph = reconstructGraph(packages);
+  return { bundles: packages, graph };
 }
 
 /**