@prisma-next/core-control-plane 0.3.0-dev.2 → 0.3.0-dev.21

package/src/types.ts

@@ -0,0 +1,530 @@
+import type {
+  AdapterDescriptor,
+  AdapterInstance,
+  DriverDescriptor,
+  DriverInstance,
+  ExtensionDescriptor,
+  ExtensionInstance,
+  FamilyDescriptor,
+  FamilyInstance,
+  TargetBoundComponentDescriptor,
+  TargetDescriptor,
+  TargetInstance,
+} from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { ContractMarkerRecord, TargetFamilyHook } from '@prisma-next/contract/types';
+import type { TargetMigrationsCapability } from './migrations';
+import type { CoreSchemaView } from './schema-view';
+
+// Re-export migration types for convenience
+export type {
+  MigrationOperationClass,
+  MigrationOperationPolicy,
+  MigrationPlan,
+  MigrationPlanner,
+  MigrationPlannerConflict,
+  MigrationPlannerFailureResult,
+  MigrationPlannerResult,
+  MigrationPlannerSuccessResult,
+  MigrationPlanOperation,
+  MigrationRunner,
+  MigrationRunnerExecutionChecks,
+  MigrationRunnerFailure,
+  MigrationRunnerResult,
+  MigrationRunnerSuccessValue,
+  TargetMigrationsCapability,
+} from './migrations';
+
+// ============================================================================
+// Control*Instance Base Interfaces (ADR 151)
+// ============================================================================
+
+/**
+ * Control-plane family instance interface.
+ * Extends the base FamilyInstance with control-plane domain actions.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TSchemaIR - The schema IR type returned by introspect() (family-specific)
+ */
+export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR = unknown>
+  extends FamilyInstance<TFamilyId> {
+  /**
+   * Validates a contract JSON and returns a validated ContractIR (without mappings).
+   * Mappings are runtime-only and should not be part of ContractIR.
+   *
+   * Note: The returned ContractIR may include additional fields from the emitted contract
+   * (like coreHash, profileHash) that are not part of the ContractIR type but are preserved
+   * for use by verify/sign operations.
+   */
+  validateContractIR(contractJson: unknown): ContractIR;
+
+  /**
+   * Verifies the database marker against the contract.
+   * Compares target, coreHash, and profileHash.
+   *
+   * @param options.contractIR - The validated contract (from validateContractIR). Must have
+   *   coreHash and target fields for verification. These fields are present in emitted
+   *   contracts but not in the ContractIR type definition.
+   */
+  verify(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR: unknown;
+    readonly expectedTargetId: string;
+    readonly contractPath: string;
+    readonly configPath?: string;
+  }): Promise<VerifyDatabaseResult>;
+
+  /**
+   * Verifies the database schema against the contract.
+   * Compares contract requirements against live database schema.
+   */
+  schemaVerify(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR: unknown;
+    readonly strict: boolean;
+    readonly contractPath: string;
+    readonly configPath?: string;
+    /**
+     * Active framework components participating in this composition.
+     * All components must have matching familyId and targetId.
+     */
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, string>>;
+  }): Promise<VerifyDatabaseSchemaResult>;
+
+  /**
+   * Signs the database with the contract marker.
+   * Writes or updates the contract marker if schema verification passes.
+   * This operation is idempotent - if the marker already matches, no changes are made.
+   */
+  sign(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR: unknown;
+    readonly contractPath: string;
+    readonly configPath?: string;
+  }): Promise<SignDatabaseResult>;
+
+  /**
+   * Reads the contract marker from the database.
+   * Returns null if no marker exists.
+   */
+  readMarker(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+  }): Promise<ContractMarkerRecord | null>;
+
+  /**
+   * Introspects the database schema and returns a family-specific schema IR.
+   *
+   * This is a read-only operation that returns a snapshot of the live database schema.
+   * The method is family-owned and delegates to target/adapter-specific introspectors
+   * to perform the actual schema introspection.
+   *
+   * @param options - Introspection options
+   * @param options.driver - Control plane driver for database connection
+   * @param options.contractIR - Optional contract for contract-guided introspection.
+   *   When provided, families may use it for filtering, optimization, or validation
+   *   during introspection. The contract does not change the meaning of "what exists"
+   *   in the database - it only guides how introspection is performed.
+   * @returns Promise resolving to the family-specific Schema IR (e.g., `SqlSchemaIR` for SQL).
+   *   The IR represents the complete schema snapshot at the time of introspection.
+   */
+  introspect(options: {
+    readonly driver: ControlDriverInstance<TFamilyId, string>;
+    readonly contractIR?: unknown;
+  }): Promise<TSchemaIR>;
+
+  /**
+   * Optionally projects a family-specific Schema IR into a core schema view.
+   * Families that provide this method enable rich tree output for CLI visualization.
+   * Families that do not provide it still support introspection via raw Schema IR.
+   */
+  toSchemaView?(schema: TSchemaIR): CoreSchemaView;
+
+  /**
+   * Emits contract JSON and DTS as strings.
+   * Uses the instance's preassembled state (operation registry, type imports, extension IDs).
+   * Handles stripping mappings and validation internally.
+   */
+  emitContract(options: { readonly contractIR: ContractIR | unknown }): Promise<EmitContractResult>;
+}
+
+/**
+ * Control-plane target instance interface.
+ * Extends the base TargetInstance with control-plane specific behavior.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+export interface ControlTargetInstance<TFamilyId extends string, TTargetId extends string>
+  extends TargetInstance<TFamilyId, TTargetId> {}
+
+/**
+ * Control-plane adapter instance interface.
+ * Extends the base AdapterInstance with control-plane specific behavior.
+ * Families extend this with family-specific adapter interfaces.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+export interface ControlAdapterInstance<TFamilyId extends string, TTargetId extends string>
+  extends AdapterInstance<TFamilyId, TTargetId> {}
+
+/**
+ * Control-plane driver instance interface.
+ * Extends the base DriverInstance with control-plane specific behavior.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+export interface ControlDriverInstance<TFamilyId extends string, TTargetId extends string>
+  extends DriverInstance<TFamilyId, TTargetId> {
+  query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<{ readonly rows: Row[] }>;
+  close(): Promise<void>;
+}
+
+/**
+ * Control-plane extension instance interface.
+ * Extends the base ExtensionInstance with control-plane specific behavior.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+export interface ControlExtensionInstance<TFamilyId extends string, TTargetId extends string>
+  extends ExtensionInstance<TFamilyId, TTargetId> {}
+
+/**
+ * Operation context for propagating metadata through control-plane operation call chains.
+ * Inspired by OpenTelemetry's Context and Sentry's Scope patterns.
+ *
+ * This context carries informational metadata (like file paths) that can be used for
+ * error reporting, logging, and debugging, but is not required for structural correctness.
+ * It allows subsystems to propagate context without coupling to file I/O concerns.
+ *
+ * @example
+ * ```typescript
+ * const context: OperationContext = {
+ *   contractPath: './contract.json',
+ *   configPath: './prisma-next.config.ts',
+ * };
+ *
+ * await runner.execute({ plan, driver, destinationContract: contract, context });
+ * ```
+ */
+export interface OperationContext {
+  /**
+   * Path to the contract file (if applicable).
+   * Used for error reporting and metadata, not for file I/O.
+   */
+  readonly contractPath?: string;
+
+  /**
+   * Path to the configuration file (if applicable).
+   * Used for error reporting and metadata, not for file I/O.
+   */
+  readonly configPath?: string;
+
+  /**
+   * Additional metadata that can be propagated through the call chain.
+   * Extensible for future needs without breaking changes.
+   */
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+// ============================================================================
+// Control*Descriptor Interfaces (ADR 151)
+// ============================================================================
+
+/**
+ * A bundle of control-plane component descriptors for a specific family and target.
+ *
+ * This struct groups the target, adapter, driver (optional), and extension packs
+ * needed to create a family instance and run CLI commands. Use `createControlPlaneStack()`
+ * to construct with sensible defaults.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ */
+export interface ControlPlaneStack<TFamilyId extends string, TTargetId extends string> {
+  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
+  readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;
+  readonly driver: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;
+  readonly extensionPacks: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[];
+}
+
+/**
+ * Descriptor for a control-plane family (e.g., SQL).
+ * Provides the family hook and factory method.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TFamilyInstance - The family instance type
+ */
+export interface ControlFamilyDescriptor<
+  TFamilyId extends string,
+  TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>,
+> extends FamilyDescriptor<TFamilyId> {
+  readonly hook: TargetFamilyHook;
+  create<TTargetId extends string>(stack: ControlPlaneStack<TFamilyId, TTargetId>): TFamilyInstance;
+}
+
+/**
+ * Descriptor for a control-plane target component (e.g., Postgres target).
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TTargetInstance - The target instance type
+ * @template TFamilyInstance - The family instance type for migrations (optional)
+ */
+export interface ControlTargetDescriptor<
+  TFamilyId extends string,
+  TTargetId extends string,
+  TTargetInstance extends ControlTargetInstance<TFamilyId, TTargetId> = ControlTargetInstance<
+    TFamilyId,
+    TTargetId
+  >,
+  TFamilyInstance extends ControlFamilyInstance<TFamilyId> = ControlFamilyInstance<TFamilyId>,
+> extends TargetDescriptor<TFamilyId, TTargetId> {
+  /**
+   * Optional migrations capability.
+   * Targets that support migrations expose this property.
+   * The capability is parameterized by family and target IDs to ensure type-level
+   * compatibility of framework components.
+   */
+  readonly migrations?: TargetMigrationsCapability<TFamilyId, TTargetId, TFamilyInstance>;
+  create(): TTargetInstance;
+}
+
+/**
+ * Descriptor for a control-plane adapter component (e.g., Postgres adapter).
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TAdapterInstance - The adapter instance type
+ */
+export interface ControlAdapterDescriptor<
+  TFamilyId extends string,
+  TTargetId extends string,
+  TAdapterInstance extends ControlAdapterInstance<TFamilyId, TTargetId> = ControlAdapterInstance<
+    TFamilyId,
+    TTargetId
+  >,
+> extends AdapterDescriptor<TFamilyId, TTargetId> {
+  create(): TAdapterInstance;
+}
+
+/**
+ * Descriptor for a control-plane driver component (e.g., Postgres driver).
+ *
+ * The connection input type is driver-specific. For example:
+ * - Postgres uses a connection string (URL)
+ * - Other drivers may accept structured objects (e.g., file paths, credentials)
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TDriverInstance - The driver instance type
+ * @template TConnection - The connection input type (defaults to `string` for URL-based drivers)
+ */
+export interface ControlDriverDescriptor<
+  TFamilyId extends string,
+  TTargetId extends string,
+  TDriverInstance extends ControlDriverInstance<TFamilyId, TTargetId> = ControlDriverInstance<
+    TFamilyId,
+    TTargetId
+  >,
+  TConnection = string,
+> extends DriverDescriptor<TFamilyId, TTargetId> {
+  create(connection: TConnection): Promise<TDriverInstance>;
+}
+
+/**
+ * Descriptor for a control-plane extension component (e.g., pgvector).
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TExtensionInstance - The extension instance type
+ */
+export interface ControlExtensionDescriptor<
+  TFamilyId extends string,
+  TTargetId extends string,
+  TExtensionInstance extends ControlExtensionInstance<
+    TFamilyId,
+    TTargetId
+  > = ControlExtensionInstance<TFamilyId, TTargetId>,
+> extends ExtensionDescriptor<TFamilyId, TTargetId> {
+  create(): TExtensionInstance;
+}
+
+/**
+ * Result type for database marker verification operations.
+ */
+export interface VerifyDatabaseResult {
+  readonly ok: boolean;
+  readonly code?: string;
+  readonly summary: string;
+  readonly contract: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  readonly marker?: {
+    readonly coreHash?: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly missingCodecs?: readonly string[];
+  readonly codecCoverageSkipped?: boolean;
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+
+/**
+ * Schema issue type for schema verification results.
+ */
+export interface SchemaIssue {
+  readonly kind:
+    | 'missing_table'
+    | 'missing_column'
+    | 'extra_table'
+    | 'extra_column'
+    | 'extra_primary_key'
+    | 'extra_foreign_key'
+    | 'extra_unique_constraint'
+    | 'extra_index'
+    | 'type_mismatch'
+    | 'nullability_mismatch'
+    | 'primary_key_mismatch'
+    | 'foreign_key_mismatch'
+    | 'unique_constraint_mismatch'
+    | 'index_mismatch'
+    | 'extension_missing';
+  readonly table: string;
+  readonly column?: string;
+  readonly indexOrConstraint?: string;
+  readonly expected?: string;
+  readonly actual?: string;
+  readonly message: string;
+}
+
+/**
+ * Contract-shaped verification tree node for schema verification results.
+ * Family-agnostic structure that follows the contract structure.
+ */
+export interface SchemaVerificationNode {
+  readonly status: 'pass' | 'warn' | 'fail';
+  readonly kind: string;
+  readonly name: string;
+  readonly contractPath: string;
+  readonly code: string;
+  readonly message: string;
+  readonly expected: unknown;
+  readonly actual: unknown;
+  readonly children: readonly SchemaVerificationNode[];
+}
+
+/**
+ * Result type for database schema verification operations.
+ */
+export interface VerifyDatabaseSchemaResult {
+  readonly ok: boolean;
+  readonly code?: string;
+  readonly summary: string;
+  readonly contract: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly schema: {
+    readonly issues: readonly SchemaIssue[];
+    readonly root: SchemaVerificationNode;
+    readonly counts: {
+      readonly pass: number;
+      readonly warn: number;
+      readonly fail: number;
+      readonly totalNodes: number;
+    };
+  };
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath?: string;
+    readonly strict: boolean;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+
+/**
+ * Result type for contract emission operations.
+ */
+export interface EmitContractResult {
+  readonly contractJson: string;
+  readonly contractDts: string;
+  readonly coreHash: string;
+  readonly profileHash: string;
+}
+
+/**
+ * Result envelope for schema introspection operations.
+ * Used by CLI for JSON output when introspecting database schemas.
+ *
+ * @template TSchemaIR - The family-specific Schema IR type (e.g., `SqlSchemaIR` for SQL)
+ */
+export interface IntrospectSchemaResult<TSchemaIR> {
+  readonly ok: true;
+  readonly summary: string;
+  readonly target: {
+    readonly familyId: string;
+    readonly id: string;
+  };
+  readonly schema: TSchemaIR;
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly dbUrl?: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+
+/**
+ * Result type for database signing operations.
+ * Returned when writing or updating the contract marker in the database.
+ */
+export interface SignDatabaseResult {
+  readonly ok: boolean;
+  readonly summary: string;
+  readonly contract: {
+    readonly coreHash: string;
+    readonly profileHash?: string;
+  };
+  readonly target: {
+    readonly expected: string;
+    readonly actual?: string;
+  };
+  readonly marker: {
+    readonly created: boolean;
+    readonly updated: boolean;
+    readonly previous?: {
+      readonly coreHash?: string;
+      readonly profileHash?: string;
+    };
+  };
+  readonly meta?: {
+    readonly configPath?: string;
+    readonly contractPath: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}

package/dist/chunk-U5RYT6PT.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * CLI error envelope for output formatting.\n * This is the serialized form of a CliStructuredError.\n */\nexport interface CliErrorEnvelope {\n  readonly code: string;\n  readonly domain: string;\n  readonly severity: 'error' | 'warn' | 'info';\n  readonly summary: string;\n  readonly why: string | undefined;\n  readonly fix: string | undefined;\n  readonly where:\n    | {\n        readonly path: string | undefined;\n        readonly line: number | undefined;\n      }\n    | undefined;\n  readonly meta: Record<string, unknown> | undefined;\n  readonly docsUrl: string | undefined;\n}\n\n/**\n * Minimal conflict data structure expected by CLI output.\n */\nexport interface CliErrorConflict {\n  readonly kind: string;\n  readonly summary: string;\n  readonly why?: string;\n}\n\n/**\n * Structured CLI error that contains all information needed for error envelopes.\n * Call sites throw these errors with full context.\n */\nexport class CliStructuredError extends Error {\n  readonly code: string;\n  readonly domain: 'CLI' | 'RTM';\n  readonly severity: 'error' | 'warn' | 'info';\n  readonly why: string | undefined;\n  readonly fix: string | undefined;\n  readonly where:\n    | {\n        readonly path: string | undefined;\n        readonly line: number | undefined;\n      }\n    | undefined;\n  readonly meta: Record<string, unknown> | undefined;\n  readonly docsUrl: string | undefined;\n\n  constructor(\n    code: string,\n    summary: string,\n    options?: {\n      readonly domain?: 'CLI' | 'RTM';\n      readonly severity?: 'error' | 'warn' | 'info';\n      readonly why?: string;\n      readonly fix?: string;\n      readonly where?: { readonly path?: string; readonly line?: number };\n      readonly meta?: Record<string, unknown>;\n      readonly docsUrl?: string;\n    },\n  ) {\n    super(summary);\n    this.name = 'CliStructuredError';\n    this.code = code;\n    this.domain = options?.domain ?? 'CLI';\n    this.severity = options?.severity ?? 'error';\n    this.why = options?.why;\n    this.fix = options?.fix;\n    this.where = options?.where\n      ? {\n          path: options.where.path,\n          line: options.where.line,\n        }\n      : undefined;\n    this.meta = options?.meta;\n    this.docsUrl = options?.docsUrl;\n  }\n\n  /**\n   * Converts this error to a CLI error envelope for output formatting.\n   */\n  toEnvelope(): CliErrorEnvelope {\n    const codePrefix = this.domain === 'CLI' ? 'PN-CLI-' : 'PN-RTM-';\n    return {\n      code: `${codePrefix}${this.code}`,\n      domain: this.domain,\n      severity: this.severity,\n      summary: this.message,\n      why: this.why,\n      fix: this.fix,\n      where: this.where,\n      meta: this.meta,\n      docsUrl: this.docsUrl,\n    };\n  }\n}\n\n// ============================================================================\n// Config Errors (PN-CLI-4001-4007)\n// ============================================================================\n\n/**\n * Config file not found or missing.\n */\nexport function errorConfigFileNotFound(\n  configPath?: string,\n  options?: {\n    readonly why?: string;\n  },\n): CliStructuredError {\n  return new CliStructuredError('4001', 'Config file not found', {\n    domain: 'CLI',\n    ...(options?.why ? { why: options.why } : { why: 'Config file not found' }),\n    fix: \"Run 'prisma-next init' to create a config file\",\n    docsUrl: 'https://prisma-next.dev/docs/cli/config',\n    ...(configPath ? { where: { path: configPath } } : {}),\n  });\n}\n\n/**\n * Contract configuration missing from config.\n */\nexport function errorContractConfigMissing(options?: {\n  readonly why?: string;\n}): CliStructuredError {\n  return new CliStructuredError('4002', 'Contract configuration missing', {\n    domain: 'CLI',\n    why: options?.why ?? 'The contract configuration is required for emit',\n    fix: 'Add contract configuration to your prisma-next.config.ts',\n    docsUrl: 'https://prisma-next.dev/docs/cli/contract-emit',\n  });\n}\n\n/**\n * Contract validation failed.\n */\nexport function errorContractValidationFailed(\n  reason: string,\n  options?: {\n    readonly where?: { readonly path?: string; readonly line?: number };\n  },\n): CliStructuredError {\n  return new CliStructuredError('4003', 'Contract validation failed', {\n    domain: 'CLI',\n    why: reason,\n    fix: 'Re-run `prisma-next contract emit`, or fix the contract file and try again',\n    docsUrl: 'https://prisma-next.dev/docs/contracts',\n    ...(options?.where ? { where: options.where } : {}),\n  });\n}\n\n/**\n * File not found.\n */\nexport function errorFileNotFound(\n  filePath: string,\n  options?: {\n    readonly why?: string;\n    readonly fix?: string;\n    readonly docsUrl?: string;\n  },\n): CliStructuredError {\n  return new CliStructuredError('4004', 'File not found', {\n    domain: 'CLI',\n    why: options?.why ?? `File not found: ${filePath}`,\n    fix: options?.fix ?? 'Check that the file path is correct',\n    where: { path: filePath },\n    ...(options?.docsUrl ? { docsUrl: options.docsUrl } : {}),\n  });\n}\n\n/**\n * Database URL is required but not provided.\n */\nexport function errorDatabaseUrlRequired(options?: { readonly why?: string }): CliStructuredError {\n  return new CliStructuredError('4005', 'Database URL is required', {\n    domain: 'CLI',\n    why: options?.why ?? 'Database URL is required for this command',\n    fix: 'Provide `--db <url>` or set `db: { url: \"postgres://…\" }` in prisma-next.config.ts',\n  });\n}\n\n/**\n * Query runner factory is required but not provided in config.\n */\nexport function errorQueryRunnerFactoryRequired(options?: {\n  readonly why?: string;\n}): CliStructuredError {\n  return new CliStructuredError('4006', 'Query runner factory is required', {\n    domain: 'CLI',\n    why: options?.why ?? 'Config.db.queryRunnerFactory is required for db verify',\n    fix: 'Add db.queryRunnerFactory to prisma-next.config.ts',\n    docsUrl: 'https://prisma-next.dev/docs/cli/db-verify',\n  });\n}\n\n/**\n * Family verify.readMarker is required but not provided.\n */\nexport function errorFamilyReadMarkerSqlRequired(options?: {\n  readonly why?: string;\n}): CliStructuredError {\n  return new CliStructuredError('4007', 'Family readMarker() is required', {\n    domain: 'CLI',\n    why: options?.why ?? 'Family verify.readMarker is required for db verify',\n    fix: 'Ensure family.verify.readMarker() is exported by your family package',\n    docsUrl: 'https://prisma-next.dev/docs/cli/db-verify',\n  });\n}\n\n/**\n * JSON output format not supported.\n */\nexport function errorJsonFormatNotSupported(options: {\n  readonly command: string;\n  readonly format: string;\n  readonly supportedFormats: readonly string[];\n}): CliStructuredError {\n  return new CliStructuredError('4008', 'Unsupported JSON format', {\n    domain: 'CLI',\n    why: `The ${options.command} command does not support --json ${options.format}`,\n    fix: `Use --json ${options.supportedFormats.join(' or ')}, or omit --json for human output`,\n    meta: {\n      command: options.command,\n      format: options.format,\n      supportedFormats: options.supportedFormats,\n    },\n  });\n}\n\n/**\n * Driver is required for DB-connected commands but not provided.\n */\nexport function errorDriverRequired(options?: { readonly why?: string }): CliStructuredError {\n  return new CliStructuredError('4010', 'Driver is required for DB-connected commands', {\n    domain: 'CLI',\n    why: options?.why ?? 'Config.driver is required for DB-connected commands',\n    fix: 'Add a control-plane driver to prisma-next.config.ts (e.g. import a driver descriptor and set `driver: postgresDriver`)',\n    docsUrl: 'https://prisma-next.dev/docs/cli/config',\n  });\n}\n\n/**\n * Contract requires extension packs that are not provided by config descriptors.\n */\nexport function errorContractMissingExtensionPacks(options: {\n  readonly missingExtensionPacks: readonly string[];\n  readonly providedComponentIds: readonly string[];\n}): CliStructuredError {\n  const missing = [...options.missingExtensionPacks].sort();\n  return new CliStructuredError('4011', 'Missing extension packs in config', {\n    domain: 'CLI',\n    why:\n      missing.length === 1\n        ? `Contract requires extension pack '${missing[0]}', but CLI config does not provide a matching descriptor.`\n        : `Contract requires extension packs ${missing.map((p) => `'${p}'`).join(', ')}, but CLI config does not provide matching descriptors.`,\n    fix: 'Add the missing extension descriptors to `extensions` in prisma-next.config.ts',\n    docsUrl: 'https://prisma-next.dev/docs/cli/config',\n    meta: {\n      missingExtensionPacks: missing,\n      providedComponentIds: [...options.providedComponentIds].sort(),\n    },\n  });\n}\n\n/**\n * Migration planning failed due to conflicts.\n */\nexport function errorMigrationPlanningFailed(options: {\n  readonly conflicts: readonly CliErrorConflict[];\n  readonly why?: string;\n}): CliStructuredError {\n  // Build \"why\" from conflict summaries - these contain the actual problem description\n  const conflictSummaries = options.conflicts.map((c) => c.summary);\n  const computedWhy = options.why ?? conflictSummaries.join('\\n');\n\n  // Build \"fix\" from conflict \"why\" fields - these contain actionable advice\n  const conflictFixes = options.conflicts\n    .map((c) => c.why)\n    .filter((why): why is string => typeof why === 'string');\n  const computedFix =\n    conflictFixes.length > 0\n      ? conflictFixes.join('\\n')\n      : 'Use `db schema-verify` to inspect conflicts, or ensure the database is empty';\n\n  return new CliStructuredError('4020', 'Migration planning failed', {\n    domain: 'CLI',\n    why: computedWhy,\n    fix: computedFix,\n    meta: { conflicts: options.conflicts },\n    docsUrl: 'https://prisma-next.dev/docs/cli/db-init',\n  });\n}\n\n/**\n * Target does not support migrations (missing createPlanner/createRunner).\n */\nexport function errorTargetMigrationNotSupported(options?: {\n  readonly why?: string;\n}): CliStructuredError {\n  return new CliStructuredError('4021', 'Target does not support migrations', {\n    domain: 'CLI',\n    why: options?.why ?? 'The configured target does not provide migration planner/runner',\n    fix: 'Select a target that provides migrations (it must export `target.migrations` for db init)',\n    docsUrl: 'https://prisma-next.dev/docs/cli/db-init',\n  });\n}\n\n/**\n * Config validation error (missing required fields).\n */\nexport function errorConfigValidation(\n  field: string,\n  options?: {\n    readonly why?: string;\n  },\n): CliStructuredError {\n  return new CliStructuredError('4001', 'Config file not found', {\n    domain: 'CLI',\n    why: options?.why ?? `Config must have a \"${field}\" field`,\n    fix: \"Run 'prisma-next init' to create a config file\",\n    docsUrl: 'https://prisma-next.dev/docs/cli/config',\n  });\n}\n\n// ============================================================================\n// Runtime Errors (PN-RTM-3000-3003)\n// ============================================================================\n\n/**\n * Contract marker not found in database.\n */\nexport function errorMarkerMissing(options?: {\n  readonly why?: string;\n  readonly dbUrl?: string;\n}): CliStructuredError {\n  return new CliStructuredError('3001', 'Marker missing', {\n    domain: 'RTM',\n    why: options?.why ?? 'Contract marker not found in database',\n    fix: 'Run `prisma-next db sign --db <url>` to create marker',\n  });\n}\n\n/**\n * Contract hash does not match database marker.\n */\nexport function errorHashMismatch(options?: {\n  readonly why?: string;\n  readonly expected?: string;\n  readonly actual?: string;\n}): CliStructuredError {\n  return new CliStructuredError('3002', 'Hash mismatch', {\n    domain: 'RTM',\n    why: options?.why ?? 'Contract hash does not match database marker',\n    fix: 'Migrate database or re-sign if intentional',\n    ...(options?.expected || options?.actual\n      ? {\n          meta: {\n            ...(options.expected ? { expected: options.expected } : {}),\n            ...(options.actual ? { actual: options.actual } : {}),\n          },\n        }\n      : {}),\n  });\n}\n\n/**\n * Contract target does not match config target.\n */\nexport function errorTargetMismatch(\n  expected: string,\n  actual: string,\n  options?: {\n    readonly why?: string;\n  },\n): CliStructuredError {\n  return new CliStructuredError('3003', 'Target mismatch', {\n    domain: 'RTM',\n    why:\n      options?.why ??\n      `Contract target does not match config target (expected: ${expected}, actual: ${actual})`,\n    fix: 'Align contract target and config target',\n    meta: { expected, actual },\n  });\n}\n\n/**\n * Generic runtime error.\n */\nexport function errorRuntime(\n  summary: string,\n  options?: {\n    readonly why?: string;\n    readonly fix?: string;\n    readonly meta?: Record<string, unknown>;\n  },\n): CliStructuredError {\n  return new CliStructuredError('3000', summary, {\n    domain: 'RTM',\n    ...(options?.why ? { why: options.why } : { why: 'Verification failed' }),\n    ...(options?.fix ? { fix: options.fix } : { fix: 'Check contract and database state' }),\n    ...(options?.meta ? { meta: options.meta } : {}),\n  });\n}\n\n// ============================================================================\n// Generic Error\n// ============================================================================\n\n/**\n * Generic unexpected error.\n */\nexport function errorUnexpected(\n  message: string,\n  options?: {\n    readonly why?: string;\n    readonly fix?: string;\n  },\n): CliStructuredError {\n  return new CliStructuredError('4999', 'Unexpected error', {\n    domain: 'CLI',\n    why: options?.why ?? message,\n    fix: options?.fix ?? 'Check the error message and try again',\n  });\n}\n"],"mappings":"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","names":[]}