@prisma-next/cli 0.11.0 → 0.12.0

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,239 @@ 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 fromHashMeta = typeof meta['fromHash'] === 'string' ? meta['fromHash'] : null;
+  // `buildPathNotFoundFailure` uses this sentinel in meta when the live marker is null.
+  const planFromHash = fromHashMeta === '<empty>' ? null : fromHashMeta;
+  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(', ')}.`
+      : '';
+  // Plan-then-apply recovery. The planner destination is the missing edge's
+  // target; `migration plan --to` (built for arbitrary targets) makes this a
+  // real command, so the diagnostic that sends you here is now honest.
+  const planCommand = (() => {
+    if (planFromHash !== null && targetHash !== null) {
+      return `prisma-next migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;
+    }
+    if (targetHash !== null) {
+      return `prisma-next migration plan --to ${targetHash} --name <slug>`;
+    }
+    if (planFromHash !== null) {
+      return `prisma-next migration plan --from ${planFromHash} --name <slug>`;
+    }
+    return 'prisma-next migration plan';
+  })();
+  const applyCommand =
+    targetHash !== null ? `prisma-next migrate --to ${targetHash}` : 'prisma-next migrate';
+  return errorRuntime(failure.summary, {
+    why:
+      failure.why ??
+      `Cannot reach target "${targetHash ?? '<unknown>'}" from current marker "${fromHashMeta ?? '<unknown>'}".${deadEndsSuffix}`,
+    fix: [
+      'Plan the missing edge, then apply it:',
+      `  1. ${planCommand}`,
+      `  2. ${applyCommand}`,
+      'A rollback (reverse) plan is expected to contain destructive (DROP) operations — review them before applying.',
+      'Narrower cases (rename inference, re-adding a NOT NULL column without a safe default, or a type change that needs data) may additionally need a hint in the planned migration.',
+      'Inspect the on-disk graph with `prisma-next migration list`, or `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

@@ -3,14 +3,12 @@ import type { ControlTargetDescriptor } from '@prisma-next/framework-components/
 import { hasMigrations } from '@prisma-next/framework-components/control';
 import type { NoInvariantPathStructuralEdge } from '@prisma-next/migration-tools/errors';
 import type { MigrationEdge, MigrationGraph } from '@prisma-next/migration-tools/graph';
-import { readMigrationsDir } from '@prisma-next/migration-tools/io';
 import type { PathDecision } from '@prisma-next/migration-tools/migration-graph';
-import { reconstructGraph } from '@prisma-next/migration-tools/migration-graph';
-import type { OnDiskMigrationPackage } from '@prisma-next/migration-tools/package';
 import { APP_SPACE_ID, spaceMigrationDirectory } from '@prisma-next/migration-tools/spaces';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
 import { relative, resolve } from 'pathe';
+import { errorRuntime } from './cli-errors';
 import { formatCommandHelp } from './formatters/help';
 import type { CommonCommandOptions } from './global-flags';
 import { parseGlobalFlags } from './global-flags';
@@ -94,12 +92,15 @@ export interface MigrationCommandOptions extends CommonCommandOptions {
 
 /**
  * Resolves the absolute path to contract.json from the config.
- * Centralises the fallback logic shared by every command that reads the contract.
  */
 export function resolveContractPath(config: { contract?: { output?: string } }): string {
-  return config.contract?.output
-    ? resolve(config.contract.output)
-    : resolve('src/prisma/contract.json');
+  if (config.contract?.output === undefined) {
+    throw errorRuntime('config.contract.output is required to resolve the contract path', {
+      why: 'CLI commands read the emitted contract from config.contract.output; the config has no value to read.',
+      fix: 'Ensure your prisma-next.config.ts goes through `defineConfig()`, which normalises a default output when the provider supplies an input path, or set `contract.output` explicitly.',
+    });
+  }
+  return resolve(config.contract.output);
 }
 
 /**
@@ -150,7 +151,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;
@@ -227,22 +228,6 @@ export function getTargetMigrations(target: ControlTargetDescriptor<string, stri
   return hasMigrations(target) ? target.migrations : undefined;
 }
 
-/**
- * Reads the migrations directory and builds the migration graph from all
- * packages. Throws on I/O or graph errors — callers handle error mapping.
- *
- * Every on-disk package is content-addressed (`migrationHash` is always a
- * string); there is no draft state to filter out.
- */
-export async function loadMigrationPackages(migrationsDir: string): Promise<{
-  bundles: readonly OnDiskMigrationPackage[];
-  graph: MigrationGraph;
-}> {
-  const bundles = await readMigrationsDir(migrationsDir);
-  const graph = reconstructGraph(bundles);
-  return { bundles, graph };
-}
-
 /**
  * The subset of the emitted contract.json that the framework layer can
  * safely type. The emitter adds these fields on top of the family-specific

package/src/utils/contract-at-errors.ts

@@ -0,0 +1,96 @@
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { notOk, type Result } from '@prisma-next/utils/result';
+import { join } from 'pathe';
+import {
+  CliStructuredError,
+  errorContractValidationFailed,
+  errorFileNotFound,
+  errorSnapshotMissing,
+  errorUnexpected,
+  mapMigrationToolsError,
+} from './cli-errors';
+
+export function mapContractAtError(
+  error: unknown,
+  options?: { readonly artifactRole?: 'from' | 'to' },
+): Result<never, CliStructuredError> {
+  if (MigrationToolsError.is(error)) {
+    switch (error.code) {
+      case 'MIGRATION.SNAPSHOT_MISSING': {
+        const refName =
+          typeof error.details?.['refName'] === 'string'
+            ? error.details['refName']
+            : typeof error.details?.['identifier'] === 'string'
+              ? error.details['identifier']
+              : 'unknown';
+        return notOk(errorSnapshotMissing(refName));
+      }
+      case 'MIGRATION.CONTRACT_DESERIALIZATION_FAILED': {
+        const filePath =
+          typeof error.details?.['filePath'] === 'string'
+            ? error.details['filePath']
+            : 'ref-snapshot';
+        const message =
+          typeof error.details?.['message'] === 'string' ? error.details['message'] : error.message;
+        const isRefSnapshot = filePath.endsWith('.contract.json');
+        return notOk(
+          errorContractValidationFailed(
+            isRefSnapshot
+              ? `Ref snapshot contract failed to deserialize: ${message}`
+              : `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
+            { where: { path: isRefSnapshot ? 'ref-snapshot' : filePath } },
+          ),
+        );
+      }
+      case 'MIGRATION.INVALID_JSON': {
+        const filePath =
+          typeof error.details?.['filePath'] === 'string' ? error.details['filePath'] : 'unknown';
+        const message =
+          typeof error.details?.['parseError'] === 'string'
+            ? error.details['parseError']
+            : error.message;
+        const role = options?.artifactRole ?? 'from';
+        return notOk(
+          errorContractValidationFailed(
+            role === 'to'
+              ? `Target contract at ${filePath} failed to deserialize: ${message}`
+              : `Predecessor contract at ${filePath} failed to deserialize: ${message}`,
+            { where: { path: filePath } },
+          ),
+        );
+      }
+      case 'MIGRATION.BUNDLE_NOT_FOUND_FOR_GRAPH_NODE':
+        return notOk(
+          errorUnexpected(error.message, {
+            why: error.why,
+            fix: error.fix,
+          }),
+        );
+      case 'MIGRATION.FILE_MISSING': {
+        const file =
+          typeof error.details?.['file'] === 'string' ? error.details['file'] : 'end-contract.json';
+        const dir = typeof error.details?.['dir'] === 'string' ? error.details['dir'] : '';
+        const jsonPath = dir ? join(dir, 'end-contract.json') : file;
+        const role = options?.artifactRole ?? 'from';
+        return notOk(
+          errorFileNotFound(jsonPath, {
+            why:
+              role === 'to'
+                ? `Target migration is missing its destination contract snapshot at ${jsonPath}`
+                : `Predecessor migration is missing its destination contract snapshot at ${jsonPath}`,
+            fix:
+              role === 'to'
+                ? 'Re-emit the target migration so its sibling `end-contract.json` / `end-contract.d.ts` are restored, then re-run this command.'
+                : 'Re-emit the predecessor migration (`prisma-next migration plan` from its source) so its sibling `end-contract.json` is restored, then re-run this command.',
+          }),
+        );
+      }
+      default:
+        return notOk(mapMigrationToolsError(error));
+    }
+  }
+  if (CliStructuredError.is(error)) {
+    return notOk(error);
+  }
+  throw error;
+}