@prisma-next/core-control-plane 0.3.0-dev.8 → 0.3.0-dev.81

package/src/errors.ts

@@ -1,8 +1,12 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { SchemaIssue, VerifyDatabaseSchemaResult } from './types';
+
 /**
  * CLI error envelope for output formatting.
  * This is the serialized form of a CliStructuredError.
  */
 export interface CliErrorEnvelope {
+  readonly ok: false;
   readonly code: string;
   readonly domain: string;
   readonly severity: 'error' | 'warn' | 'info';
@@ -66,7 +70,7 @@ export class CliStructuredError extends Error {
     this.domain = options?.domain ?? 'CLI';
     this.severity = options?.severity ?? 'error';
     this.why = options?.why;
-    this.fix = options?.fix;
+    this.fix = options?.fix === options?.why ? undefined : options?.fix;
     this.where = options?.where
       ? {
           path: options.where.path,
@@ -83,6 +87,7 @@ export class CliStructuredError extends Error {
   toEnvelope(): CliErrorEnvelope {
     const codePrefix = this.domain === 'CLI' ? 'PN-CLI-' : 'PN-RTM-';
     return {
+      ok: false as const,
       code: `${codePrefix}${this.code}`,
       domain: this.domain,
       severity: this.severity,
@@ -94,6 +99,23 @@ export class CliStructuredError extends Error {
       docsUrl: this.docsUrl,
     };
   }
+
+  /**
+   * Type guard to check if an error is a CliStructuredError.
+   * Uses duck-typing to work across module boundaries where instanceof may fail.
+   */
+  static is(error: unknown): error is CliStructuredError {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    const candidate = error as CliStructuredError;
+    return (
+      candidate.name === 'CliStructuredError' &&
+      typeof candidate.code === 'string' &&
+      (candidate.domain === 'CLI' || candidate.domain === 'RTM') &&
+      typeof candidate.toEnvelope === 'function'
+    );
+  }
 }
 
 // ============================================================================
@@ -171,13 +193,19 @@ export function errorFileNotFound(
 }
 
 /**
- * Database URL is required but not provided.
+ * Database connection is required but not provided.
  */
-export function errorDatabaseUrlRequired(options?: { readonly why?: string }): CliStructuredError {
-  return new CliStructuredError('4005', 'Database URL is required', {
+export function errorDatabaseConnectionRequired(options?: {
+  readonly why?: string;
+  readonly commandName?: string;
+}): CliStructuredError {
+  const runHint = options?.commandName
+    ? `Run \`prisma-next ${options.commandName} --db <url>\``
+    : 'Provide `--db <url>`';
+  return new CliStructuredError('4005', 'Database connection is required', {
     domain: 'CLI',
-    why: options?.why ?? 'Database URL is required for this command',
-    fix: 'Provide `--db <url>` or set `db: { url: "postgres://…" }` in prisma-next.config.ts',
+    why: options?.why ?? 'Database connection is required for this command',
+    fix: `${runHint}, or set \`db: { connection: "postgres://…" }\` in prisma-next.config.ts`,
   });
 }
 
@@ -316,16 +344,16 @@ export function errorConfigValidation(
     readonly why?: string;
   },
 ): CliStructuredError {
-  return new CliStructuredError('4001', 'Config file not found', {
+  return new CliStructuredError('4009', 'Config validation error', {
     domain: 'CLI',
     why: options?.why ?? `Config must have a "${field}" field`,
-    fix: "Run 'prisma-next init' to create a config file",
+    fix: 'Check your prisma-next.config.ts and ensure all required fields are provided',
     docsUrl: 'https://prisma-next.dev/docs/cli/config',
   });
 }
 
 // ============================================================================
-// Runtime Errors (PN-RTM-3000-3003)
+// Runtime Errors (PN-RTM-3000-3030)
 // ============================================================================
 
 /**
@@ -335,10 +363,10 @@ export function errorMarkerMissing(options?: {
   readonly why?: string;
   readonly dbUrl?: string;
 }): CliStructuredError {
-  return new CliStructuredError('3001', 'Marker missing', {
+  return new CliStructuredError('3001', 'Database not signed', {
     domain: 'RTM',
-    why: options?.why ?? 'Contract marker not found in database',
-    fix: 'Run `prisma-next db sign --db <url>` to create marker',
+    why: options?.why ?? 'No database signature (marker) found',
+    fix: 'Run `prisma-next db sign --db <url>` to sign the database',
   });
 }
 
@@ -385,6 +413,82 @@ export function errorTargetMismatch(
   });
 }
 
+/**
+ * Database marker is required but not found.
+ * Used by commands that require a pre-existing marker as a precondition.
+ */
+export function errorMarkerRequired(options?: {
+  readonly why?: string;
+  readonly fix?: string;
+}): CliStructuredError {
+  return new CliStructuredError('3010', 'Database must be signed first', {
+    domain: 'RTM',
+    why: options?.why ?? 'No database signature (marker) found',
+    fix: options?.fix ?? 'Run `prisma-next db init` first to sign the database',
+  });
+}
+
+/**
+ * Schema verification found mismatches between the database and the contract.
+ * The full verification tree is preserved in `meta.verificationResult`.
+ */
+export function errorSchemaVerificationFailed(options: {
+  readonly summary: string;
+  readonly verificationResult: VerifyDatabaseSchemaResult;
+  readonly issues?: readonly SchemaIssue[];
+}): CliStructuredError {
+  return new CliStructuredError('3004', options.summary, {
+    domain: 'RTM',
+    why: 'Database schema does not satisfy the contract',
+    fix: 'Run `prisma-next db update` to reconcile, or adjust your contract to match the database',
+    meta: {
+      verificationResult: options.verificationResult,
+      ...ifDefined('issues', options.issues),
+    },
+  });
+}
+
+/**
+ * Migration runner failed during execution.
+ */
+export function errorRunnerFailed(
+  summary: string,
+  options?: {
+    readonly why?: string;
+    readonly fix?: string;
+    readonly meta?: Record<string, unknown>;
+  },
+): CliStructuredError {
+  return new CliStructuredError('3020', summary, {
+    domain: 'RTM',
+    why: options?.why ?? 'Migration runner failed',
+    fix: options?.fix ?? 'Inspect the reported conflict and reconcile schema drift',
+    ...(options?.meta ? { meta: options.meta } : {}),
+  });
+}
+
+/** Error code for destructive changes that require explicit confirmation. */
+export const ERROR_CODE_DESTRUCTIVE_CHANGES = '3030';
+
+/**
+ * Destructive operations require explicit confirmation via -y/--yes.
+ */
+export function errorDestructiveChanges(
+  summary: string,
+  options?: {
+    readonly why?: string;
+    readonly fix?: string;
+    readonly meta?: Record<string, unknown>;
+  },
+): CliStructuredError {
+  return new CliStructuredError(ERROR_CODE_DESTRUCTIVE_CHANGES, summary, {
+    domain: 'RTM',
+    why: options?.why ?? 'Planned operations include destructive changes that require confirmation',
+    fix: options?.fix ?? 'Re-run with `-y` to apply, or use `--dry-run` to preview first',
+    ...(options?.meta ? { meta: options.meta } : {}),
+  });
+}
+
 /**
  * Generic runtime error.
  */

package/src/exports/constants.ts

@@ -0,0 +1 @@
+export { EMPTY_CONTRACT_HASH } from '../constants';

package/src/exports/emission.ts

@@ -2,5 +2,5 @@
 
 export { canonicalizeContract } from '../emission/canonicalization';
 export { emit } from '../emission/emit';
-export { computeCoreHash, computeProfileHash } from '../emission/hashing';
+export { computeExecutionHash, computeProfileHash, computeStorageHash } from '../emission/hashing';
 export type { EmitOptions, EmitResult } from '../emission/types';

package/src/exports/errors.ts

@@ -1,21 +1,26 @@
 export type { CliErrorConflict, CliErrorEnvelope } from '../errors';
 export {
   CliStructuredError,
+  ERROR_CODE_DESTRUCTIVE_CHANGES,
   errorConfigFileNotFound,
   errorConfigValidation,
   errorContractConfigMissing,
   errorContractMissingExtensionPacks,
   errorContractValidationFailed,
-  errorDatabaseUrlRequired,
+  errorDatabaseConnectionRequired,
+  errorDestructiveChanges,
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
   errorHashMismatch,
   errorJsonFormatNotSupported,
   errorMarkerMissing,
+  errorMarkerRequired,
   errorMigrationPlanningFailed,
   errorQueryRunnerFactoryRequired,
+  errorRunnerFailed,
   errorRuntime,
+  errorSchemaVerificationFailed,
   errorTargetMigrationNotSupported,
   errorTargetMismatch,
   errorUnexpected,

package/src/exports/types.ts

@@ -1,4 +1,3 @@
-export { createControlPlaneStack } from '../stack';
 export type {
   // Control* types (ADR 151)
   ControlAdapterDescriptor,

package/src/migrations.ts

@@ -10,6 +10,7 @@
  */
 
 import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
 import type { Result } from '@prisma-next/utils/result';
 import type { ControlDriverInstance, ControlFamilyInstance } from './types';
 
@@ -49,6 +50,10 @@ export interface MigrationPlanOperation {
   readonly operationClass: MigrationOperationClass;
 }
 
+// ============================================================================
+// Plan Types (Display-Oriented)
+// ============================================================================
+
 /**
  * A migration plan for display purposes.
  * Contains only the fields needed for CLI output (summary, JSON envelope).
@@ -56,9 +61,17 @@ export interface MigrationPlanOperation {
 export interface MigrationPlan {
   /** The target ID this plan is for (e.g., 'postgres'). */
   readonly targetId: string;
+  /**
+   * Origin contract identity that the plan expects the database to currently be at.
+   * If omitted or null, the runner skips origin validation entirely.
+   */
+  readonly origin?: {
+    readonly storageHash: string;
+    readonly profileHash?: string;
+  } | null;
   /** Destination contract identity that the plan intends to reach. */
   readonly destination: {
-    readonly coreHash: string;
+    readonly storageHash: string;
     readonly profileHash?: string;
   };
   /** Ordered list of operations to execute. */
@@ -244,4 +257,17 @@ export interface TargetMigrationsCapability<
 > {
   createPlanner(family: TFamilyInstance): MigrationPlanner<TFamilyId, TTargetId>;
   createRunner(family: TFamilyInstance): MigrationRunner<TFamilyId, TTargetId>;
+  /**
+   * Synthesizes a family-specific schema IR from a contract for offline planning.
+   * The returned schema can be passed to `planner.plan({ schema })` as the "from" state.
+   *
+   * @param contract - The contract to convert, or null for a new project (empty schema).
+   * @param frameworkComponents - Active framework components, used to derive database
+   *   dependencies (e.g. extensions) that should be reflected in the schema IR.
+   * @returns Family-specific schema IR (e.g., `SqlSchemaIR` for SQL targets).
+   */
+  contractToSchema(
+    contract: ContractIR | null,
+    frameworkComponents?: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>,
+  ): unknown;
 }

package/src/schema-view.ts

@@ -15,7 +15,7 @@
  * // SqlSchemaIR structure:
  * // {
  * //   tables: { user: { columns: {...}, primaryKey: {...}, ... }, ... },
- * //   extensions: ['pgvector'],
+ * //   dependencies: [{ id: 'postgres.extension.vector' }],
  * //   annotations: {...}
  * // }
  *
@@ -47,9 +47,9 @@
  * //         ]
  * //       },
  * //       {
- * //         kind: 'extension',
- * //         id: 'extension-pgvector',
- * //         label: 'extension pgvector',
+ * //         kind: 'dependency',
+ * //         id: 'dependency-postgres.extension.pgvector',
+ * //         label: 'pgvector extension is enabled',
  * //         meta: { ... }
  * //       }
  * //     ]
@@ -72,7 +72,7 @@ export type SchemaNodeKind =
   | 'entity'
   | 'field'
   | 'index'
-  | 'extension';
+  | 'dependency';
 
 /**
  * A node in the schema tree.

package/src/types.ts

@@ -53,17 +53,17 @@ export interface ControlFamilyInstance<TFamilyId extends string, TSchemaIR = unk
    * 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
+   * (like storageHash/executionHash, 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.
+   * Compares target, storageHash, and profileHash.
    *
    * @param options.contractIR - The validated contract (from validateContractIR). Must have
-   *   coreHash and target fields for verification. These fields are present in emitted
+   *   storageHash and target fields for verification. These fields are present in emitted
    *   contracts but not in the ContractIR type definition.
    */
   verify(options: {
@@ -316,9 +316,14 @@ export interface ControlAdapterDescriptor<
 /**
  * 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,
@@ -327,8 +332,9 @@ export interface ControlDriverDescriptor<
     TFamilyId,
     TTargetId
   >,
+  TConnection = string,
 > extends DriverDescriptor<TFamilyId, TTargetId> {
-  create(url: string): Promise<TDriverInstance>;
+  create(connection: TConnection): Promise<TDriverInstance>;
 }
 
 /**
@@ -357,11 +363,11 @@ export interface VerifyDatabaseResult {
   readonly code?: string;
   readonly summary: string;
   readonly contract: {
-    readonly coreHash: string;
+    readonly storageHash: string;
     readonly profileHash?: string;
   };
   readonly marker?: {
-    readonly coreHash?: string;
+    readonly storageHash?: string;
     readonly profileHash?: string;
   };
   readonly target: {
@@ -393,15 +399,20 @@ export interface SchemaIssue {
     | 'extra_unique_constraint'
     | 'extra_index'
     | 'type_mismatch'
+    | 'type_missing'
+    | 'type_values_mismatch'
     | 'nullability_mismatch'
     | 'primary_key_mismatch'
     | 'foreign_key_mismatch'
     | 'unique_constraint_mismatch'
     | 'index_mismatch'
-    | 'extension_missing';
-  readonly table: string;
+    | 'dependency_missing'
+    | 'default_missing'
+    | 'default_mismatch';
+  readonly table?: string;
   readonly column?: string;
   readonly indexOrConstraint?: string;
+  readonly typeName?: string;
   readonly expected?: string;
   readonly actual?: string;
   readonly message: string;
@@ -431,7 +442,7 @@ export interface VerifyDatabaseSchemaResult {
   readonly code?: string;
   readonly summary: string;
   readonly contract: {
-    readonly coreHash: string;
+    readonly storageHash: string;
     readonly profileHash?: string;
   };
   readonly target: {
@@ -464,7 +475,8 @@ export interface VerifyDatabaseSchemaResult {
 export interface EmitContractResult {
   readonly contractJson: string;
   readonly contractDts: string;
-  readonly coreHash: string;
+  readonly storageHash: string;
+  readonly executionHash?: string;
   readonly profileHash: string;
 }
 
@@ -499,7 +511,7 @@ export interface SignDatabaseResult {
   readonly ok: boolean;
   readonly summary: string;
   readonly contract: {
-    readonly coreHash: string;
+    readonly storageHash: string;
     readonly profileHash?: string;
   };
   readonly target: {
@@ -510,7 +522,7 @@ export interface SignDatabaseResult {
     readonly created: boolean;
     readonly updated: boolean;
     readonly previous?: {
-      readonly coreHash?: string;
+      readonly storageHash?: string;
       readonly profileHash?: string;
     };
   };

package/dist/chunk-473ODD3P.js

@@ -1,14 +0,0 @@
-// src/stack.ts
-function createControlPlaneStack(input) {
-  return {
-    target: input.target,
-    adapter: input.adapter,
-    driver: input.driver,
-    extensionPacks: input.extensionPacks ?? []
-  };
-}
-
-export {
-  createControlPlaneStack
-};
-//# sourceMappingURL=chunk-473ODD3P.js.map

package/dist/chunk-473ODD3P.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/stack.ts"],"sourcesContent":["import type {\n  ControlAdapterDescriptor,\n  ControlDriverDescriptor,\n  ControlExtensionDescriptor,\n  ControlPlaneStack,\n  ControlTargetDescriptor,\n} from './types';\n\n/**\n * Creates a ControlPlaneStack from component descriptors.\n *\n * Provides sensible defaults:\n * - `driver` defaults to `undefined` (optional for commands that don't need DB connection)\n * - `extensionPacks` defaults to `[]` (empty array)\n *\n * @example\n * ```ts\n * const stack = createControlPlaneStack({\n *   target: postgresTarget,\n *   adapter: postgresAdapter,\n *   driver: postgresDriver, // optional\n *   extensionPacks: [pgvector], // optional\n * });\n * ```\n */\nexport function createControlPlaneStack<TFamilyId extends string, TTargetId extends string>(input: {\n  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;\n  readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;\n  readonly driver?: ControlDriverDescriptor<TFamilyId, TTargetId> | undefined;\n  readonly extensionPacks?: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[] | undefined;\n}): ControlPlaneStack<TFamilyId, TTargetId> {\n  return {\n    target: input.target,\n    adapter: input.adapter,\n    driver: input.driver,\n    extensionPacks: input.extensionPacks ?? [],\n  };\n}\n"],"mappings":";AAyBO,SAAS,wBAA4E,OAKhD;AAC1C,SAAO;AAAA,IACL,QAAQ,MAAM;AAAA,IACd,SAAS,MAAM;AAAA,IACf,QAAQ,MAAM;AAAA,IACd,gBAAgB,MAAM,kBAAkB,CAAC;AAAA,EAC3C;AACF;","names":[]}