@prisma-next/cli 0.15.0 → 0.16.0-dev.1

package/src/utils/cli-errors.ts

@@ -287,7 +287,18 @@ export function errorPathUnreachable(failure: MigrateFailure): CliStructuredErro
   // 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.
+  //
+  // Never-planned spaces have an EMPTY migration graph, and contract-ref
+  // resolution only resolves full hashes against graph nodes — a
+  // `--to <hash>` remediation would reject its own input. `migration plan`
+  // without `--to` targets the working contract (the same contract the app
+  // space's synthesized head ref carries), so the bare form is the one that
+  // runs verbatim.
+  const neverPlanned = meta['kind'] === 'neverPlanned';
   const planCommand = (() => {
+    if (neverPlanned) {
+      return 'prisma-next migration plan --name <slug>';
+    }
     if (planFromHash !== null && targetHash !== null) {
       return `prisma-next migration plan --from ${planFromHash} --to ${targetHash} --name <slug>`;
     }
@@ -300,7 +311,9 @@ export function errorPathUnreachable(failure: MigrateFailure): CliStructuredErro
     return 'prisma-next migration plan';
   })();
   const applyCommand =
-    targetHash !== null ? `prisma-next migrate --to ${targetHash}` : 'prisma-next migrate';
+    targetHash !== null && !neverPlanned
+      ? `prisma-next migrate --to ${targetHash}`
+      : 'prisma-next migrate';
   return errorRuntime(failure.summary, {
     why:
       failure.why ??
@@ -347,7 +360,7 @@ 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
+ * `CONFIG.DB_CONNECTION_REQUIRED` envelope with `meta.missingFlags` (canonical long-form flags
  * per CLI Style Guide §Errors) so callers can react programmatically. Returns
  * `null` when both are present.
  */

package/src/utils/combine-verify-results.ts

@@ -78,7 +78,7 @@ export function combineVerifyResults(
   return {
     result: {
       ok,
-      ...(ok ? {} : { code: appResult.code ?? 'PN-RUN-3010' }),
+      ...(ok ? {} : { code: appResult.code ?? 'CONTRACT.MARKER_REQUIRED' }),
       summary,
       contract: appResult.contract,
       target: appResult.target,

package/src/utils/contract-space-aggregate-loader.ts

@@ -20,7 +20,7 @@ import { toDeclaredExtensionsFromRaw } from './extension-pack-inputs';
 
 const CONTRACT_SPACES_DOCS_URL = 'https://pris.ly/contract-spaces';
 
-function contractSpaceError5002(
+function contractSpaceViolationError(
   summary: string,
   options: {
     readonly why: string;
@@ -28,8 +28,7 @@ function contractSpaceError5002(
     readonly violations: readonly IntegrityViolation[];
   },
 ): CliStructuredError {
-  return new CliStructuredError('5002', summary, {
-    domain: 'MIG',
+  return new CliStructuredError('MIGRATION.CONTRACT_SPACE_VIOLATION', summary, {
     why: options.why,
     fix: options.fix,
     docsUrl: CONTRACT_SPACES_DOCS_URL,
@@ -38,7 +37,7 @@ function contractSpaceError5002(
 }
 
 /**
- * Build the `5002` structured-error envelope for a contract-space
+ * Build the `MIGRATION.CONTRACT_SPACE_VIOLATION` structured-error envelope for a contract-space
  * target mismatch. Shared between the declared-extension precheck (the
  * descriptor's configured target disagrees with the project target) and
  * the on-disk-contract check surfaced by `checkIntegrity`.
@@ -48,7 +47,7 @@ function targetMismatchError(
   expected: string,
   actual: string,
 ): CliStructuredError {
-  return contractSpaceError5002(`Contract-space target mismatch for "${spaceId}"`, {
+  return contractSpaceViolationError(`Contract-space target mismatch for "${spaceId}"`, {
     why: `Space "${spaceId}" targets "${actual}" but the project's adapter targets "${expected}".`,
     fix: 'Update the extension descriptor to target the configured database, or change the project adapter.',
     violations: [{ kind: 'targetMismatch', spaceId, expected, actual }],
@@ -89,9 +88,10 @@ function describeIntegrityViolation(violation: IntegrityViolation): string {
 /**
  * Map the integrity violations `checkIntegrity` reports into a single
  * CLI structured-error envelope, preserving the error codes the prior
- * throw-on-load loader emitted: `5001` (layout drift, bundled) and
- * `5002` (target / disjointness / contract-validation / structural
- * integrity). Returns `null` when there is nothing to refuse on.
+ * throw-on-load loader emitted: `MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION`
+ * (layout drift, bundled) and `MIGRATION.CONTRACT_SPACE_VIOLATION` (target /
+ * disjointness / contract-validation / structural integrity). Returns
+ * `null` when there is nothing to refuse on.
  *
  * Precedence reproduces the prior loader's first-failure ordering:
  * layout drift first (every offence bundled into one envelope), then
@@ -113,8 +113,7 @@ export function mapIntegrityViolations(
       layout.length === 1
         ? 'Contract-space layout violation detected'
         : `Contract-space layout violations detected (${layout.length})`;
-    return new CliStructuredError('5001', summary, {
-      domain: 'MIG',
+    return new CliStructuredError('MIGRATION.CONTRACT_SPACE_LAYOUT_VIOLATION', summary, {
       why: `The on-disk \`migrations/\` directory and your \`extensionPacks\` declaration are not in agreement.\n${lines.join('\n')}`,
       fix: 'Declare the extension in `extensionPacks` and re-emit its contract-space artefacts, or remove the orphan `migrations/<space>` directory.',
       docsUrl: CONTRACT_SPACES_DOCS_URL,
@@ -133,7 +132,7 @@ export function mapIntegrityViolations(
 
   const disjointness = violations.find((v) => v.kind === 'disjointness');
   if (disjointness && disjointness.kind === 'disjointness') {
-    return contractSpaceError5002(
+    return contractSpaceViolationError(
       `Contract-space disjointness violation: storage element "${disjointness.element}" claimed by multiple spaces`,
       {
         why: `Spaces ${disjointness.claimedBy.map((s) => `"${s}"`).join(', ')} all claim the storage element "${disjointness.element}". Each storage element must be owned by exactly one contract space.`,
@@ -145,7 +144,7 @@ export function mapIntegrityViolations(
 
   const contractUnreadable = violations.find((v) => v.kind === 'contractUnreadable');
   if (contractUnreadable && contractUnreadable.kind === 'contractUnreadable') {
-    return contractSpaceError5002(
+    return contractSpaceViolationError(
       `Contract-space contract validation failed for "${contractUnreadable.spaceId}"`,
       {
         why: contractUnreadable.detail,
@@ -160,7 +159,7 @@ export function mapIntegrityViolations(
   // is still computed; the gate just renders one envelope).
   const structural = violations[0]!;
   const spaceId = 'spaceId' in structural ? structural.spaceId : '*';
-  return contractSpaceError5002(`Contract-space integrity failure for "${spaceId}"`, {
+  return contractSpaceViolationError(`Contract-space integrity failure for "${spaceId}"`, {
     why: describeIntegrityViolation(structural),
     fix: 'Re-emit the affected migration package(s) or restore the on-disk `migrations/` directory from version control.',
     violations: [structural],

package/src/utils/formatters/errors.ts

@@ -7,6 +7,25 @@ import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
 import { formatPlannerWarningsBlock } from './migrations';
 
+/**
+ * The display label for a schema-diff issue in the shared error envelope,
+ * derived from which sides are present: expected-only is a missing object,
+ * actual-only an extra one, both a mismatch. `undefined` when the entry is not
+ * a schema-diff issue (it carries neither side) so the caller can fall through
+ * to its generic label.
+ */
+function schemaDiffIssueLabel(issue: {
+  readonly expected?: unknown;
+  readonly actual?: unknown;
+}): 'missing' | 'extra' | 'mismatch' | undefined {
+  const hasExpected = issue.expected !== undefined;
+  const hasActual = issue.actual !== undefined;
+  if (hasExpected && hasActual) return 'mismatch';
+  if (hasExpected) return 'missing';
+  if (hasActual) return 'extra';
+  return undefined;
+}
+
 /**
  * Formats error output for human-readable display.
  */
@@ -51,13 +70,15 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
   // Show issues list if present (always show a short list; show full list when verbose).
   // `issues` is a shared error-envelope field: PSL interpretation diagnostics stamp
   // `kind` and `message` (their diagnostic code and prose); schema-diff issues
-  // (`SchemaDiffIssue`) carry no `message` and stamp `reason` and `path` instead.
+  // (`SchemaDiffIssue`) carry no `message` and stamp `path` plus the
+  // `expected`/`actual` presence a label is derived from.
   if (error.meta?.['issues']) {
     const issues = error.meta['issues'] as readonly {
       kind?: string;
-      reason?: string;
       message?: string;
       path?: readonly string[];
+      expected?: unknown;
+      actual?: unknown;
     }[];
     if (issues.length > 0) {
       const maxToShow = isVerbose(flags, 1) ? issues.length : Math.min(3, issues.length);
@@ -66,7 +87,7 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
         : `  Issues (showing ${maxToShow} of ${issues.length}):`;
       lines.push(`${formatDimText(header)}`);
       for (const issue of issues.slice(0, maxToShow)) {
-        const label = issue.kind ?? issue.reason ?? 'issue';
+        const label = issue.kind ?? schemaDiffIssueLabel(issue) ?? 'issue';
         const message = issue.message ?? issue.path?.join('/') ?? '';
         lines.push(`${formatDimText(`    - [${label}] ${message}`)}`);
       }

package/src/utils/formatters/verify.ts

@@ -8,13 +8,14 @@ import type {
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import { issueOutcome } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { bold, cyan, dim, green, magenta, red, yellow } from 'colorette';
 import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
 
-/** Human-readable label for each failure reason, prefixed onto an issue's message for display. */
-const REASON_LABEL: Record<ExpectationFailureReason, string> = {
+/** Human-readable label for each outcome, prefixed onto an issue's message for display. */
+const OUTCOME_LABEL: Record<ExpectationFailureReason, string> = {
   'not-found': 'missing',
   'not-expected': 'extra',
   'not-equal': 'mismatch',
@@ -22,12 +23,12 @@ const REASON_LABEL: Record<ExpectationFailureReason, string> = {
 
 /**
  * The issue's display text: its own path, prefixed with a human label for
- * why it's flagged. Turning `reason` (and the path) into prose is this
- * formatter's job, not the differ's — the differ's issue is data (`path` +
- * `reason` + nodes), not prose.
+ * why it's flagged. Turning the presence-derived outcome (and the path) into
+ * prose is this formatter's job, not the differ's — the differ's issue is
+ * data (`path` + nodes), not prose.
  */
 function formatIssueMessage(issue: SchemaDiffIssue): string {
-  return `${REASON_LABEL[issue.reason]}: ${issue.path.join('/')}`;
+  return `${OUTCOME_LABEL[issueOutcome(issue)]}: ${issue.path.join('/')}`;
 }
 
 // ============================================================================

package/src/utils/integrity-violation-to-check-failure.ts

@@ -14,7 +14,7 @@ function migrationFileRelative(dirPath: string, fileName: string): string {
 
 /**
  * Map one {@link IntegrityViolation} onto a `migration check` failure row.
- * Sole catalogue mapping from integrity violations to `PN-MIG-CHECK-*`.
+ * Sole catalogue mapping from integrity violations to `MIGRATION.CHECK_*` codes.
  */
 export function integrityViolationToCheckFailure(
   violation: IntegrityViolation,
@@ -31,7 +31,7 @@ export function integrityViolationToCheckFailure(
     case 'hashMismatch':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-001',
+        code: 'MIGRATION.CHECK_HASH_MISMATCH',
         where: migrationFileRelative(
           join(migrationsDir, violation.spaceId, violation.dirName),
           'migration.json',
@@ -42,7 +42,7 @@ export function integrityViolationToCheckFailure(
     case 'providedInvariantsMismatch':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-002',
+        code: 'MIGRATION.CHECK_PROVIDED_INVARIANTS_MISMATCH',
         where: packageRelative(violation.spaceId, violation.dirName),
         why: `Migration "${violation.dirName}" providedInvariants in migration.json disagrees with ops.json.`,
         fix: 'Re-emit the migration package so migration.json and ops.json agree.',
@@ -50,7 +50,7 @@ export function integrityViolationToCheckFailure(
     case 'packageUnloadable':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-002',
+        code: 'MIGRATION.CHECK_PACKAGE_UNLOADABLE',
         where: packageRelative(violation.spaceId, violation.dirName),
         why: `Migration "${violation.dirName}" could not be loaded: ${violation.detail}`,
         fix: 'Re-emit the migration package or restore from version control.',
@@ -58,7 +58,7 @@ export function integrityViolationToCheckFailure(
     case 'sameSourceAndTarget':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-007',
+        code: 'MIGRATION.CHECK_NOOP_SELF_EDGE',
         where: packageRelative(violation.spaceId, violation.dirName),
         why: `Migration "${violation.dirName}" in space "${violation.spaceId}" has source equal to target (${violation.hash}) with no data invariant — a true no-op self-edge.`,
         fix: 'Add a data operation if this self-edge was meant to carry a data invariant, or delete the migration if it is a true no-op.',
@@ -66,7 +66,7 @@ export function integrityViolationToCheckFailure(
     case 'orphanSpaceDir':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-008',
+        code: 'MIGRATION.CHECK_ORPHAN_SPACE_DIR',
         where: spaceRelative(violation.spaceId),
         why: `Contract-space directory "${violation.spaceId}" exists on disk but no extension declares it.`,
         fix: 'Remove the orphan directory, or declare the extension in `extensionPacks`.',
@@ -74,7 +74,7 @@ export function integrityViolationToCheckFailure(
     case 'declaredButUnmigrated':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-009',
+        code: 'MIGRATION.CHECK_DECLARED_BUT_UNMIGRATED',
         where: spaceRelative(violation.spaceId),
         why: `Extension "${violation.spaceId}" is declared in \`extensionPacks\` but has no on-disk migrations directory.`,
         fix: 'Re-emit the extension contract-space artefacts with `prisma-next contract emit` and migration planning, or remove the extension from `extensionPacks` if it is unused.',
@@ -82,7 +82,7 @@ export function integrityViolationToCheckFailure(
     case 'headRefMissing':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-010',
+        code: 'MIGRATION.CHECK_HEAD_REF_MISSING',
         where: refRelative(violation.spaceId, 'head'),
         why: `Head ref \`refs/head.json\` is missing for contract space "${violation.spaceId}".`,
         fix: 'Re-emit the contract-space migrations and head ref artefacts, or restore `refs/head.json` from version control.',
@@ -90,7 +90,7 @@ export function integrityViolationToCheckFailure(
     case 'headRefNotInGraph':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-011',
+        code: 'MIGRATION.CHECK_HEAD_REF_NOT_IN_GRAPH',
         where: refRelative(violation.spaceId, 'head'),
         why: `Head ref ${violation.hash} for contract space "${violation.spaceId}" is not present in its migration graph.`,
         fix: 'Re-emit the contract space migrations, or restore the missing migration package.',
@@ -98,7 +98,7 @@ export function integrityViolationToCheckFailure(
     case 'refUnreadable':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-012',
+        code: 'MIGRATION.CHECK_REF_UNREADABLE',
         where: refRelative(violation.spaceId, violation.refName),
         why: `Ref "${violation.refName}" for contract space "${violation.spaceId}" is unreadable: ${violation.detail}`,
         fix: 'Repair or remove the corrupt ref file.',
@@ -106,7 +106,7 @@ export function integrityViolationToCheckFailure(
     case 'targetMismatch':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-013',
+        code: 'MIGRATION.CHECK_TARGET_MISMATCH',
         where: spaceRelative(violation.spaceId),
         why: `Contract space "${violation.spaceId}" targets "${violation.actual}" but the project targets "${violation.expected}".`,
         fix: 'Update the extension to target the configured database, or change the project target.',
@@ -114,7 +114,7 @@ export function integrityViolationToCheckFailure(
     case 'disjointness':
       return {
         space: 'app',
-        code: 'PN-MIG-CHECK-014',
+        code: 'MIGRATION.CHECK_SPACE_DISJOINTNESS_VIOLATION',
         where: migrationPathRelative(migrationsDir),
         why: `Storage element "${violation.element}" is claimed by multiple contract spaces: ${violation.claimedBy.join(', ')}.`,
         fix: 'Update the contracts so each storage element is owned by exactly one contract space.',
@@ -122,7 +122,7 @@ export function integrityViolationToCheckFailure(
     case 'contractUnreadable':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-015',
+        code: 'MIGRATION.CHECK_CONTRACT_UNREADABLE',
         where: migrationFileRelative(join(migrationsDir, violation.spaceId), 'contract.json'),
         why: `Contract for space "${violation.spaceId}" is unreadable: ${violation.detail}`,
         fix: 'Re-emit the extension contract artefacts, or fix the descriptor producing the invalid contract.',
@@ -130,7 +130,7 @@ export function integrityViolationToCheckFailure(
     case 'duplicateMigrationHash':
       return {
         space: violation.spaceId,
-        code: 'PN-MIG-CHECK-016',
+        code: 'MIGRATION.CHECK_DUPLICATE_MIGRATION_HASH',
         where: spaceRelative(violation.spaceId),
         why: `Multiple migrations in space "${violation.spaceId}" share migrationHash "${violation.migrationHash}" (${violation.dirNames.join(', ')}).`,
         fix: 'Re-emit one of the conflicting packages so each migrationHash is unique.',

package/src/utils/result-handler.ts

@@ -37,7 +37,9 @@ export function handleResult<T>(
     ui.error(formatErrorOutput(envelope, flags));
   }
 
-  // Infer exit code from error domain: CLI errors = 2, RUN errors = 1
-  const exitCode = result.failure.domain === 'CLI' ? 2 : 1;
+  // Every structured failure reaching this point is an expected failure and
+  // exits 2 (PRECONDITION), except a user-declined prompt, which exits 3
+  // (USER_ABORTED). See CLI Style Guide § Exit Codes / ADR 239 § Exit codes.
+  const exitCode = result.failure.code === 'CLI.INIT_USER_ABORTED' ? 3 : 2;
   return exitCode;
 }