@prisma-next/cli 0.16.0-dev.30 → 0.16.0-dev.31

package/src/control-api/client.ts

@@ -4,6 +4,7 @@ import type {
   LedgerEntryRecord,
 } from '@prisma-next/contract/types';
 import { emit as emitContractArtifacts } from '@prisma-next/emitter';
+import { CliStructuredError } from '@prisma-next/errors/control';
 import type { AuthoringPslBlockDescriptorNamespace } from '@prisma-next/framework-components/authoring';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -27,13 +28,13 @@ import {
   hasSchemaView,
 } from '@prisma-next/framework-components/control';
 import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
-
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok } from '@prisma-next/utils/result';
+import { structuredError } from '@prisma-next/utils/structured-error';
 
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import { enrichContract } from './contract-enrichment';
-import { ContractValidationError } from './errors';
 import { executeDbInit } from './operations/db-init';
 import { executeDbUpdate } from './operations/db-update';
 import { type ExecuteDbVerifyResult, executeDbVerify } from './operations/db-verify';
@@ -128,20 +129,25 @@ class ControlClientImpl implements ControlClient {
     this.init();
 
     if (this.driver) {
-      throw new Error('Already connected. Call close() before reconnecting.');
+      throw new CliStructuredError(
+        'DRIVER.ALREADY_CONNECTED',
+        'Already connected. Call close() before reconnecting.',
+      );
     }
 
     // Resolve connection: argument > default from options
     const resolvedConnection = connection ?? this.defaultConnection;
     if (resolvedConnection === undefined) {
-      throw new Error(
+      throw new CliStructuredError(
+        'CONFIG.DB_CONNECTION_REQUIRED',
         'No connection provided. Pass a connection to connect() or provide a default connection when creating the client.',
       );
     }
 
     // Check for driver descriptor
     if (!this.stack?.driver) {
-      throw new Error(
+      throw new CliStructuredError(
+        'CONFIG.DRIVER_REQUIRED',
         'Driver is not configured. Pass a driver descriptor when creating the control client to enable database operations.',
       );
     }
@@ -167,7 +173,8 @@ class ControlClientImpl implements ControlClient {
   private buildControlAdapter(): ControlAdapterInstance<string, string> {
     this.init();
     if (!this.stack?.adapter) {
-      throw new Error(
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
         `Target "${this.options.target.targetId}" requires an adapter for migrations`,
       );
     }
@@ -188,7 +195,10 @@ class ControlClientImpl implements ControlClient {
     }
 
     if (!this.driver || !this.familyInstance || !this.frameworkComponents) {
-      throw new Error('Not connected. Call connect(connection) first.');
+      throw new CliStructuredError(
+        'DRIVER.NOT_CONNECTED',
+        'Not connected. Call connect(connection) first.',
+      );
     }
     return {
       driver: this.driver,
@@ -229,7 +239,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     // Emit verify span
@@ -282,7 +292,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     // Emit schemaVerify span
@@ -336,7 +346,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     // Emit sign span
@@ -381,7 +391,10 @@ class ControlClientImpl implements ControlClient {
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
-      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
+        `Target "${this.options.target.targetId}" does not support migrations`,
+      );
     }
 
     const adapter = this.buildControlAdapter();
@@ -391,7 +404,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     return executeDbInit({
@@ -415,7 +428,10 @@ class ControlClientImpl implements ControlClient {
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
-      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
+        `Target "${this.options.target.targetId}" does not support migrations`,
+      );
     }
 
     const adapter = this.buildControlAdapter();
@@ -425,7 +441,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     return executeDbUpdate({
@@ -490,7 +506,10 @@ class ControlClientImpl implements ControlClient {
     const { driver, familyInstance, frameworkComponents } = await this.ensureConnected();
 
     if (!hasMigrations(this.options.target)) {
-      throw new Error(`Target "${this.options.target.targetId}" does not support migrations`);
+      throw new CliStructuredError(
+        'MIGRATION.TARGET_UNSUPPORTED',
+        `Target "${this.options.target.targetId}" does not support migrations`,
+      );
     }
 
     let contract: Contract;
@@ -498,7 +517,7 @@ class ControlClientImpl implements ControlClient {
       contract = familyInstance.deserializeContract(options.contract);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new ContractValidationError(message, error);
+      throw structuredError('CONTRACT.VALIDATION_FAILED', message, { cause: error });
     }
 
     return executeMigrate({
@@ -593,7 +612,7 @@ class ControlClientImpl implements ControlClient {
     this.init();
 
     if (!this.familyInstance) {
-      throw new Error('Family instance was not initialized. This is a bug.');
+      throw new InternalError('Family instance was not initialized. This is a bug.');
     }
 
     let contractRaw: unknown;

package/src/control-api/operations/db-run.ts

@@ -24,6 +24,7 @@ import {
 } from '@prisma-next/migration-tools/aggregate';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok } from '@prisma-next/utils/result';
 import { CliStructuredError } from '../../utils/cli-errors';
 import {
@@ -200,7 +201,7 @@ export async function executeRun<TFamilyId extends string, TTargetId extends str
   // `destination` is the storage hash users see in CLI output.
   const appResolution = orderedResolutions.find((r) => r.spaceId === aggregate.app.spaceId);
   if (!appResolution) {
-    throw new Error(
+    throw new InternalError(
       'Aggregate planner returned no plan for the app space — the planner is supposed to always emit one.',
     );
   }

package/src/control-api/operations/migrate.ts

@@ -24,6 +24,7 @@ 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 { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok } from '@prisma-next/utils/result';
 import {
   type BuildAggregateInputs,
@@ -247,7 +248,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
       .map((spaceId) => {
         const entry = perSpacePlans.get(spaceId) ?? atHeadResolutions.get(spaceId);
         if (entry === undefined) {
-          throw new Error(`Unreachable: missing per-space plan for "${spaceId}"`);
+          throw new InternalError(`Unreachable: missing per-space plan for "${spaceId}"`);
         }
         return { spaceId, entry };
       });
@@ -306,7 +307,7 @@ export async function executeMigrate<TFamilyId extends string, TTargetId extends
       }
       const entry = atHeadResolutions.get(spaceId);
       if (entry === undefined) {
-        throw new Error(`Unreachable: missing per-space plan for "${spaceId}"`);
+        throw new InternalError(`Unreachable: missing per-space plan for "${spaceId}"`);
       }
       return { spaceId, entry };
     });

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

@@ -12,6 +12,7 @@ import type {
 } from '@prisma-next/framework-components/control';
 import type { ContractSpaceAggregate, PerSpacePlan } from '@prisma-next/migration-tools/aggregate';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import type { OnControlProgress, PerSpaceExecutionEntry } from '../types';
 
@@ -243,7 +244,7 @@ export function collectOrdered(
   return applyOrder.map((spaceId) => {
     const entry = perSpace.get(spaceId);
     if (!entry) {
-      throw new Error(`planner output missing per-space plan for "${spaceId}"`);
+      throw new InternalError(`planner output missing per-space plan for "${spaceId}"`);
     }
     return { spaceId, entry };
   });

package/src/load-ts-contract.ts

@@ -2,6 +2,8 @@ import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import type { Contract } from '@prisma-next/contract/types';
+import { CliStructuredError } from '@prisma-next/errors/control';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import type { Plugin } from 'esbuild';
 import { build } from 'esbuild';
 import { join, resolve as resolvePath } from 'pathe';
@@ -10,6 +12,30 @@ export interface LoadTsContractOptions {
   readonly allowlist?: ReadonlyArray<string>;
 }
 
+type ContractSourceErrorCode =
+  | 'CONTRACT.EXPORT_INVALID'
+  | 'CONTRACT.SOURCE_LOAD_FAILED'
+  | 'CONTRACT.SOURCE_IMPORT_DISALLOWED';
+
+function contractSourceError(
+  code: ContractSourceErrorCode,
+  message: string,
+  options?: {
+    readonly meta?: Record<string, unknown>;
+    readonly cause?: unknown;
+  },
+): CliStructuredError {
+  const error = new CliStructuredError(
+    code,
+    message,
+    options?.meta !== undefined ? { meta: options.meta } : undefined,
+  );
+  if (options?.cause !== undefined) {
+    error.cause = options.cause;
+  }
+  return error;
+}
+
 const DEFAULT_ALLOWLIST = ['@prisma-next/*', 'node:crypto'];
 
 function isAllowedImport(importPath: string, allowlist: ReadonlyArray<string>): boolean {
@@ -31,7 +57,7 @@ function isAllowedImport(importPath: string, allowlist: ReadonlyArray<string>):
   return false;
 }
 
-function validatePurity(value: unknown): void {
+function validatePurity(value: unknown, entryPath: string): void {
   if (typeof value !== 'object' || value === null) {
     return;
   }
@@ -44,7 +70,11 @@ function validatePurity(value: unknown): void {
     }
 
     if (path.has(value)) {
-      throw new Error('Contract export contains circular references');
+      throw contractSourceError(
+        'CONTRACT.EXPORT_INVALID',
+        'Contract export contains circular references',
+        { meta: { path: entryPath, reason: 'circular' } },
+      );
     }
     path.add(value);
 
@@ -52,10 +82,18 @@ function validatePurity(value: unknown): void {
       for (const key in value) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (descriptor && (descriptor.get || descriptor.set)) {
-          throw new Error(`Contract export contains getter/setter at key "${key}"`);
+          throw contractSourceError(
+            'CONTRACT.EXPORT_INVALID',
+            `Contract export contains getter/setter at key "${key}"`,
+            { meta: { path: entryPath, reason: 'getter', key } },
+          );
         }
         if (descriptor && typeof descriptor.value === 'function') {
-          throw new Error(`Contract export contains function at key "${key}"`);
+          throw contractSourceError(
+            'CONTRACT.EXPORT_INVALID',
+            `Contract export contains function at key "${key}"`,
+            { meta: { path: entryPath, reason: 'function', key } },
+          );
         }
         check((value as Record<string, unknown>)[key]);
       }
@@ -72,9 +110,17 @@ function validatePurity(value: unknown): void {
       if (error.message.includes('getter') || error.message.includes('circular')) {
         throw error;
       }
-      throw new Error(`Contract export is not JSON-serializable: ${error.message}`);
+      throw contractSourceError(
+        'CONTRACT.EXPORT_INVALID',
+        `Contract export is not JSON-serializable: ${error.message}`,
+        { meta: { path: entryPath, reason: 'not-json-serializable' }, cause: error },
+      );
     }
-    throw new Error('Contract export is not JSON-serializable');
+    throw contractSourceError(
+      'CONTRACT.EXPORT_INVALID',
+      'Contract export is not JSON-serializable',
+      { meta: { path: entryPath, reason: 'not-json-serializable' } },
+    );
   }
 }
 
@@ -129,7 +175,8 @@ function createImportAllowlistPlugin(
  * @param entryPath - Path to the TypeScript contract file
  * @param options - Optional configuration (import allowlist)
  * @returns The contract as Contract (should already be normalized)
- * @throws Error if the contract cannot be loaded or is not JSON-serializable
+ * @throws structured errors: `CLI.FILE_NOT_FOUND`, `CONTRACT.SOURCE_LOAD_FAILED`,
+ *   `CONTRACT.SOURCE_IMPORT_DISALLOWED`, `CONTRACT.MODULE_EXPORT_MISSING`, `CONTRACT.EXPORT_INVALID`
  */
 export async function loadContractFromTs(
   entryPath: string,
@@ -138,7 +185,9 @@ export async function loadContractFromTs(
   const allowlist = options?.allowlist ?? DEFAULT_ALLOWLIST;
 
   if (!existsSync(entryPath)) {
-    throw new Error(`Contract file not found: ${entryPath}`);
+    throw new CliStructuredError('CLI.FILE_NOT_FOUND', `Contract file not found: ${entryPath}`, {
+      where: { path: entryPath },
+    });
   }
 
   const tempFile = join(
@@ -169,22 +218,28 @@ export async function loadContractFromTs(
 
     if (result.errors.length > 0) {
       const errorMessages = result.errors.map((e: { text: string }) => e.text).join('\n');
-      throw new Error(`Failed to bundle contract file: ${errorMessages}`);
+      throw contractSourceError(
+        'CONTRACT.SOURCE_LOAD_FAILED',
+        `Failed to bundle contract file: ${errorMessages}`,
+        { meta: { path: entryPath, stage: 'bundle' } },
+      );
     }
 
     if (!result.outputFiles || result.outputFiles.length === 0) {
-      throw new Error('No output files generated from bundling');
+      throw new InternalError('No output files generated from bundling');
     }
 
     if (disallowedFromEntry.size > 0) {
-      throw new Error(
+      throw contractSourceError(
+        'CONTRACT.SOURCE_IMPORT_DISALLOWED',
         `Disallowed imports detected. Only imports matching the allowlist are permitted:\n  Allowlist: ${allowlist.join(', ')}\n  Disallowed imports: ${[...disallowedFromEntry].join(', ')}`,
+        { meta: { allowlist: [...allowlist], disallowed: [...disallowedFromEntry] } },
       );
     }
 
     const bundleContent = result.outputFiles[0]?.text;
     if (bundleContent === undefined) {
-      throw new Error('Bundle content is undefined');
+      throw new InternalError('Bundle content is undefined');
     }
     writeFileSync(tempFile, bundleContent, 'utf-8');
 
@@ -201,16 +256,22 @@ export async function loadContractFromTs(
     } else if (module.contract !== undefined) {
       contract = module.contract;
     } else {
-      throw new Error(
+      throw new CliStructuredError(
+        'CONTRACT.MODULE_EXPORT_MISSING',
         `Contract file must export a contract as default export or named export 'contract'. Found exports: ${Object.keys(module as Record<string, unknown>).join(', ') || 'none'}`,
+        { where: { path: entryPath } },
       );
     }
 
     if (typeof contract !== 'object' || contract === null) {
-      throw new Error(`Contract export must be an object, got ${typeof contract}`);
+      throw contractSourceError(
+        'CONTRACT.EXPORT_INVALID',
+        `Contract export must be an object, got ${typeof contract}`,
+        { meta: { path: entryPath, reason: 'not-object' } },
+      );
     }
 
-    validatePurity(contract);
+    validatePurity(contract, entryPath);
 
     // Blind cast: the loaded module was authored by user code
     // (typically via `defineContract` / a contract builder) and
@@ -233,6 +294,10 @@ export async function loadContractFromTs(
     if (error instanceof Error) {
       throw error;
     }
-    throw new Error(`Failed to load contract from ${entryPath}: ${String(error)}`);
+    throw contractSourceError(
+      'CONTRACT.SOURCE_LOAD_FAILED',
+      `Failed to load contract from ${entryPath}: ${String(error)}`,
+      { meta: { path: entryPath, stage: 'import' }, cause: error },
+    );
   }
 }

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

@@ -1,4 +1,5 @@
 import type { VerifyDatabaseSchemaResult } from '@prisma-next/framework-components/control';
+import { InternalError } from '@prisma-next/utils/internal-error';
 
 /**
  * The combined per-space contract-satisfaction result plus the standalone
@@ -42,7 +43,7 @@ export function combineVerifyResults(
 ): CombinedVerifyResult {
   const appResult = perSpace.get(appSpaceId) ?? perSpace.values().next().value;
   if (appResult === undefined) {
-    throw new Error(
+    throw new InternalError(
       'Aggregate verifier returned no per-space verify results — this is a wiring bug.',
     );
   }

package/src/utils/command-helpers.ts

@@ -8,7 +8,7 @@ import { APP_SPACE_ID, spaceMigrationDirectory } from '@prisma-next/migration-to
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
 import { relative, resolve } from 'pathe';
-import { errorRuntime } from './cli-errors';
+import { CliStructuredError, errorRuntime } from './cli-errors';
 import { formatCommandHelp } from './formatters/help';
 import type { CommonCommandOptions } from './global-flags';
 import { parseGlobalFlags } from './global-flags';
@@ -263,21 +263,31 @@ export async function readContractEnvelope(config: {
   const storageHash = storage?.['storageHash'];
 
   if (typeof storageHash !== 'string') {
-    throw new Error(
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
       `Contract at ${relative(process.cwd(), contractPath)} is missing a valid storage.storageHash. Run \`prisma-next contract emit\` to regenerate.`,
+      { where: { path: contractPath } },
     );
   }
   if (typeof schemaVersion !== 'string') {
-    throw new Error(
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
       `Contract at ${relative(process.cwd(), contractPath)} is missing schemaVersion.`,
+      { where: { path: contractPath } },
     );
   }
   if (typeof target !== 'string') {
-    throw new Error(`Contract at ${relative(process.cwd(), contractPath)} is missing target.`);
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
+      `Contract at ${relative(process.cwd(), contractPath)} is missing target.`,
+      { where: { path: contractPath } },
+    );
   }
   if (typeof targetFamily !== 'string') {
-    throw new Error(
+    throw new CliStructuredError(
+      'CONTRACT.VALIDATION_FAILED',
       `Contract at ${relative(process.cwd(), contractPath)} is missing targetFamily.`,
+      { where: { path: contractPath } },
     );
   }
 

package/src/utils/formatters/migration-graph-grid-layout.ts

@@ -7,6 +7,7 @@
  */
 
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import {
   type Cell,
   type CellLine,
@@ -1124,7 +1125,7 @@ function assertSingleOwner(row: CellsRow, isFocus: boolean): void {
       if (isFocus) {
         const roles = new Set(top.map((cl) => cl.line.role));
         if (roles.size > 1) {
-          throw new Error(
+          throw new InternalError(
             'migration-graph layout: single-owner invariant violated — two differently-roled lines share the top plane in one cell',
           );
         }