@prisma-next/cli 0.3.0-dev.16 → 0.3.0-dev.163

package/src/control-api/contract-enrichment.ts

@@ -0,0 +1,119 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+
+type CapabilityMatrix = Record<string, Record<string, boolean>>;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function sortDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortDeep);
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  const next: Record<string, unknown> = {};
+  for (const [key, child] of entries) {
+    next[key] = sortDeep(child);
+  }
+  return next;
+}
+
+function sortDeepTyped<T>(value: T): T {
+  return sortDeep(value) as T;
+}
+
+function extractCapabilityMatrix(value: unknown): CapabilityMatrix {
+  if (!isPlainObject(value)) return {};
+
+  const out: CapabilityMatrix = {};
+  for (const [namespace, maybeCaps] of Object.entries(value)) {
+    if (!isPlainObject(maybeCaps)) continue;
+    const caps: Record<string, boolean> = {};
+    for (const [key, flag] of Object.entries(maybeCaps)) {
+      if (typeof flag === 'boolean') {
+        caps[key] = flag;
+      }
+    }
+    if (Object.keys(caps).length > 0) {
+      out[namespace] = caps;
+    }
+  }
+
+  return out;
+}
+
+function mergeCapabilities(left: CapabilityMatrix, right: CapabilityMatrix): CapabilityMatrix {
+  const next: CapabilityMatrix = { ...left };
+  for (const [namespace, capabilities] of Object.entries(right)) {
+    next[namespace] = {
+      ...(left[namespace] ?? {}),
+      ...capabilities,
+    };
+  }
+  return next;
+}
+
+function extractExtensionPackMeta(
+  component: TargetBoundComponentDescriptor<string, string>,
+): Record<string, unknown> {
+  const { kind, id, version, capabilities, types } = component;
+  const base: Record<string, unknown> = {
+    kind,
+    id,
+    familyId: component.familyId,
+    targetId: component.targetId,
+    version,
+  };
+  if (capabilities) {
+    base['capabilities'] = capabilities;
+  }
+  if (types) {
+    if (types.codecTypes) {
+      const { controlPlaneHooks: _, codecInstances: _ci, ...cleanedCodecTypes } = types.codecTypes;
+      base['types'] = { ...types, codecTypes: cleanedCodecTypes };
+    } else {
+      base['types'] = types;
+    }
+  }
+  return base;
+}
+
+/**
+ * Enriches a raw contract with framework-derived metadata:
+ * capabilities from all component descriptors and extension pack metadata
+ * from extension descriptors. Produces deterministically sorted output.
+ */
+export function enrichContract(
+  ir: Contract,
+  components: ReadonlyArray<TargetBoundComponentDescriptor<string, string>>,
+): Contract {
+  let mergedCapabilities = ir.capabilities;
+  const extensionPacksMeta: Record<string, unknown> = {};
+
+  for (const component of components) {
+    if (component.capabilities) {
+      mergedCapabilities = mergeCapabilities(
+        mergedCapabilities,
+        extractCapabilityMatrix(component.capabilities),
+      );
+    }
+    if (component.kind === 'extension') {
+      extensionPacksMeta[component.id] = extractExtensionPackMeta(component);
+    }
+  }
+
+  const extensionPacks =
+    Object.keys(extensionPacksMeta).length > 0
+      ? { ...ir.extensionPacks, ...extensionPacksMeta }
+      : ir.extensionPacks;
+
+  return {
+    ...ir,
+    capabilities: sortDeepTyped(mergedCapabilities),
+    extensionPacks: sortDeepTyped(extensionPacks),
+  };
+}

package/src/control-api/errors.ts

@@ -0,0 +1,9 @@
+export class ContractValidationError extends Error {
+  override readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = 'ContractValidationError';
+    this.cause = cause;
+  }
+}

package/src/control-api/operations/contract-emit.ts

@@ -0,0 +1,174 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import type { Contract } from '@prisma-next/contract/types';
+import { emit } from '@prisma-next/emitter';
+import { createControlStack } from '@prisma-next/framework-components/control';
+import { abortable } from '@prisma-next/utils/abortable';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { dirname, isAbsolute, join, resolve } from 'pathe';
+import { loadConfig } from '../../config-loader';
+import { errorContractConfigMissing, errorRuntime } from '../../utils/cli-errors';
+import { assertFrameworkComponentsCompatible } from '../../utils/framework-components';
+import { enrichContract } from '../contract-enrichment';
+import type { ContractEmitOptions, ContractEmitResult } from '../types';
+
+interface ProviderFailureLike {
+  readonly summary: string;
+  readonly diagnostics: readonly unknown[];
+  readonly meta?: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isAbortError(error: unknown): boolean {
+  return isRecord(error) && typeof error['name'] === 'string' && error['name'] === 'AbortError';
+}
+
+function isProviderFailureLike(value: unknown): value is ProviderFailureLike {
+  return (
+    isRecord(value) && typeof value['summary'] === 'string' && Array.isArray(value['diagnostics'])
+  );
+}
+
+/**
+ * Executes the contract emit operation.
+ *
+ * This is an offline operation that:
+ * 1. Loads the Prisma Next config from the specified path
+ * 2. Resolves the contract source from config
+ * 3. Creates a control plane stack and family instance
+ * 4. Emits contract artifacts (JSON and DTS)
+ * 5. Writes files to the paths specified in config
+ *
+ * Supports AbortSignal for cancellation, enabling "last change wins" behavior.
+ *
+ * @param options - Options including configPath and optional signal
+ * @returns File paths and hashes of emitted artifacts
+ * @throws If config loading fails, contract is invalid, or file I/O fails
+ * @throws signal.reason if cancelled via AbortSignal (typically DOMException with name 'AbortError')
+ */
+export async function executeContractEmit(
+  options: ContractEmitOptions,
+): Promise<ContractEmitResult> {
+  const { configPath, signal = new AbortController().signal } = options;
+  const unlessAborted = abortable(signal);
+
+  // Load config using the existing config loader
+  const config = await unlessAborted(loadConfig(configPath));
+
+  // Validate contract config is present
+  if (!config.contract) {
+    throw errorContractConfigMissing({
+      why: 'Config.contract is required for emit. Define it in your config: contract: { source: ..., output: ... }',
+    });
+  }
+
+  const contractConfig = config.contract;
+
+  // Validate output path is present and ends with .json
+  if (!contractConfig.output) {
+    throw errorContractConfigMissing({
+      why: 'Contract config must have output path. This should not happen if defineConfig() was used.',
+    });
+  }
+  if (!contractConfig.output.endsWith('.json')) {
+    throw errorContractConfigMissing({
+      why: 'Contract config output path must end with .json (e.g., "src/prisma/contract.json")',
+    });
+  }
+
+  // Validate source exists and is callable
+  if (typeof contractConfig.source !== 'function') {
+    throw errorContractConfigMissing({
+      why: 'Contract config must include a valid source provider function',
+    });
+  }
+
+  // Normalize configPath and resolve artifact paths relative to config file directory
+  const normalizedConfigPath = resolve(configPath);
+  const configDir = dirname(normalizedConfigPath);
+  const outputJsonPath = isAbsolute(contractConfig.output)
+    ? contractConfig.output
+    : join(configDir, contractConfig.output);
+  // Colocate .d.ts with .json (contract.json → contract.d.ts)
+  const outputDtsPath = `${outputJsonPath.slice(0, -5)}.d.ts`;
+
+  const sourceContext = {
+    composedExtensionPacks: (config.extensionPacks ?? []).map((p) => p.id),
+  };
+
+  let providerResult: Awaited<ReturnType<typeof contractConfig.source>>;
+  try {
+    providerResult = await unlessAborted(contractConfig.source(sourceContext));
+  } catch (error) {
+    if (signal.aborted || isAbortError(error)) {
+      throw error;
+    }
+    throw errorRuntime('Failed to resolve contract source', {
+      why: error instanceof Error ? error.message : String(error),
+      fix: 'Ensure contract.source resolves to ok(Contract) or returns structured diagnostics.',
+    });
+  }
+
+  if (!isRecord(providerResult) || typeof providerResult.ok !== 'boolean') {
+    throw errorRuntime('Failed to resolve contract source', {
+      why: 'Contract source provider returned malformed result shape.',
+      fix: 'Ensure contract.source resolves to ok(Contract) or notOk({ summary, diagnostics }).',
+    });
+  }
+
+  if (providerResult.ok && !('value' in providerResult)) {
+    throw errorRuntime('Failed to resolve contract source', {
+      why: 'Contract source provider returned malformed success result: missing value.',
+      fix: 'Ensure contract.source success payload is ok(Contract).',
+    });
+  }
+
+  if (!providerResult.ok && !isProviderFailureLike(providerResult.failure)) {
+    throw errorRuntime('Failed to resolve contract source', {
+      why: 'Contract source provider returned malformed failure result: expected summary and diagnostics.',
+      fix: 'Ensure contract.source failure payload is notOk({ summary, diagnostics, meta? }).',
+    });
+  }
+
+  if (!providerResult.ok) {
+    throw errorRuntime('Failed to resolve contract source', {
+      why: providerResult.failure.summary,
+      fix: 'Fix contract source diagnostics and return ok(Contract).',
+      meta: {
+        diagnostics: providerResult.failure.diagnostics,
+        ...ifDefined('providerMeta', providerResult.failure.meta),
+      },
+    });
+  }
+
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
+  const rawComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+  const frameworkComponents = assertFrameworkComponentsCompatible(
+    config.family.familyId,
+    config.target.targetId,
+    rawComponents,
+  );
+  const enrichedIR = enrichContract(providerResult.value as Contract, frameworkComponents);
+
+  familyInstance.validateContract(enrichedIR);
+  const emitResult = await unlessAborted(emit(enrichedIR, stack, config.family.emission));
+
+  // Create directory if needed and write files (both colocated)
+  await unlessAborted(mkdir(dirname(outputJsonPath), { recursive: true }));
+  await unlessAborted(writeFile(outputJsonPath, emitResult.contractJson, 'utf-8'));
+  await unlessAborted(writeFile(outputDtsPath, emitResult.contractDts, 'utf-8'));
+
+  return {
+    storageHash: emitResult.storageHash,
+    ...ifDefined('executionHash', emitResult.executionHash),
+    profileHash: emitResult.profileHash,
+    files: {
+      json: outputJsonPath,
+      dts: outputDtsPath,
+    },
+  };
+}

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

@@ -1,29 +1,31 @@
-import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
-import type { ContractIR } from '@prisma-next/contract/ir';
+import type { Contract } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
   ControlDriverInstance,
   ControlFamilyInstance,
   MigrationPlan,
   MigrationPlannerResult,
-  MigrationPlanOperation,
   MigrationRunnerResult,
   TargetMigrationsCapability,
-} from '@prisma-next/core-control-plane/types';
+} from '@prisma-next/framework-components/control';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok } from '@prisma-next/utils/result';
 import type { DbInitResult, DbInitSuccess, OnControlProgress } from '../types';
+import { extractOperationStatements } from './extract-operation-statements';
+import { createOperationCallbacks, stripOperations } from './migration-helpers';
 
 /**
  * Options for executing dbInit operation.
  */
 export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extends string> {
   readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
-  readonly familyInstance: ControlFamilyInstance<TFamilyId>;
-  readonly contractIR: ContractIR;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId, unknown>;
+  readonly contract: Contract;
   readonly mode: 'plan' | 'apply';
   readonly migrations: TargetMigrationsCapability<
     TFamilyId,
     TTargetId,
-    ControlFamilyInstance<TFamilyId>
+    ControlFamilyInstance<TFamilyId, unknown>
   >;
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
   /** Optional progress callback for observing operation progress */
@@ -43,7 +45,7 @@ export interface ExecuteDbInitOptions<TFamilyId extends string, TTargetId extend
 export async function executeDbInit<TFamilyId extends string, TTargetId extends string>(
   options: ExecuteDbInitOptions<TFamilyId, TTargetId>,
 ): Promise<DbInitResult> {
-  const { driver, familyInstance, contractIR, mode, migrations, frameworkComponents, onProgress } =
+  const { driver, familyInstance, contract, mode, migrations, frameworkComponents, onProgress } =
     options;
 
   // Create planner and runner from target migrations capability
@@ -78,7 +80,7 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     label: 'Planning migration',
   });
   const plannerResult: MigrationPlannerResult = await planner.plan({
-    contract: contractIR,
+    contract,
     schema: schemaIR,
     policy,
     frameworkComponents,
@@ -114,12 +116,12 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     action: 'dbInit',
     kind: 'spanStart',
     spanId: checkMarkerSpanId,
-    label: 'Checking contract marker',
+    label: 'Checking database signature',
   });
   const existingMarker = await familyInstance.readMarker({ driver });
   if (existingMarker) {
     const markerMatchesDestination =
-      existingMarker.coreHash === migrationPlan.destination.coreHash &&
+      existingMarker.storageHash === migrationPlan.destination.storageHash &&
       (!migrationPlan.destination.profileHash ||
         existingMarker.profileHash === migrationPlan.destination.profileHash);
 
@@ -134,15 +136,23 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
       const result: DbInitSuccess = {
         mode,
         plan: { operations: [] },
-        ...(mode === 'apply'
-          ? {
-              execution: { operationsPlanned: 0, operationsExecuted: 0 },
-              marker: {
-                coreHash: existingMarker.coreHash,
+        destination: {
+          storageHash: migrationPlan.destination.storageHash,
+          ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+        },
+        ...ifDefined(
+          'execution',
+          mode === 'apply' ? { operationsPlanned: 0, operationsExecuted: 0 } : undefined,
+        ),
+        ...ifDefined(
+          'marker',
+          mode === 'apply'
+            ? {
+                storageHash: existingMarker.storageHash,
                 profileHash: existingMarker.profileHash,
-              },
-            }
-          : {}),
+              }
+            : undefined,
+        ),
         summary: 'Database already at target contract state',
       };
       return ok(result);
@@ -159,11 +169,11 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
       code: 'MARKER_ORIGIN_MISMATCH' as const,
       summary: 'Existing contract marker does not match plan destination',
       marker: {
-        coreHash: existingMarker.coreHash,
+        storageHash: existingMarker.storageHash,
         profileHash: existingMarker.profileHash,
       },
       destination: {
-        coreHash: migrationPlan.destination.coreHash,
+        storageHash: migrationPlan.destination.storageHash,
         profileHash: migrationPlan.destination.profileHash,
       },
       why: undefined,
@@ -181,9 +191,17 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
 
   // Plan mode - don't execute
   if (mode === 'plan') {
+    const planSql = extractOperationStatements(familyInstance.familyId, migrationPlan.operations);
     const result: DbInitSuccess = {
       mode: 'plan',
-      plan: { operations: migrationPlan.operations },
+      plan: {
+        operations: stripOperations(migrationPlan.operations),
+        ...ifDefined('sql', planSql),
+      },
+      destination: {
+        storageHash: migrationPlan.destination.storageHash,
+        ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+      },
       summary: `Planned ${migrationPlan.operations.length} operation(s)`,
     };
     return ok(result);
@@ -198,34 +216,14 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     label: 'Applying migration plan',
   });
 
-  const callbacks = onProgress
-    ? {
-        onOperationStart: (op: MigrationPlanOperation) => {
-          onProgress({
-            action: 'dbInit',
-            kind: 'spanStart',
-            spanId: `operation:${op.id}`,
-            parentSpanId: applySpanId,
-            label: op.label,
-          });
-        },
-        onOperationComplete: (op: MigrationPlanOperation) => {
-          onProgress({
-            action: 'dbInit',
-            kind: 'spanEnd',
-            spanId: `operation:${op.id}`,
-            outcome: 'ok',
-          });
-        },
-      }
-    : undefined;
+  const callbacks = createOperationCallbacks(onProgress, 'dbInit', applySpanId);
 
   const runnerResult: MigrationRunnerResult = await runner.execute({
     plan: migrationPlan,
     driver,
-    destinationContract: contractIR,
+    destinationContract: contract,
     policy,
-    ...(callbacks ? { callbacks } : {}),
+    ...ifDefined('callbacks', callbacks),
     // db init plans and applies back-to-back from a fresh introspection, so per-operation
     // pre/postchecks and the idempotency probe are usually redundant overhead. We still
     // enforce marker/origin compatibility and a full schema verification after apply.
@@ -264,18 +262,24 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
 
   const result: DbInitSuccess = {
     mode: 'apply',
-    plan: { operations: migrationPlan.operations },
+    plan: {
+      operations: stripOperations(migrationPlan.operations),
+    },
+    destination: {
+      storageHash: migrationPlan.destination.storageHash,
+      ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+    },
     execution: {
       operationsPlanned: execution.operationsPlanned,
       operationsExecuted: execution.operationsExecuted,
     },
     marker: migrationPlan.destination.profileHash
       ? {
-          coreHash: migrationPlan.destination.coreHash,
+          storageHash: migrationPlan.destination.storageHash,
           profileHash: migrationPlan.destination.profileHash,
         }
-      : { coreHash: migrationPlan.destination.coreHash },
-    summary: `Applied ${execution.operationsExecuted} operation(s), marker written`,
+      : { storageHash: migrationPlan.destination.storageHash },
+    summary: `Applied ${execution.operationsExecuted} operation(s), database signed`,
   };
   return ok(result);
 }