@prisma-next/cli 0.3.0-dev.6 → 0.3.0-dev.64

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

@@ -0,0 +1,161 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createControlPlaneStack } from '@prisma-next/core-control-plane/stack';
+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 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`;
+
+  let providerResult: Awaited<ReturnType<typeof contractConfig.source>>;
+  try {
+    providerResult = await unlessAborted(contractConfig.source());
+  } 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(contractIR) 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(contractIR) 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(contractIR).',
+    });
+  }
+
+  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(contractIR).',
+      meta: {
+        diagnostics: providerResult.failure.diagnostics,
+        ...ifDefined('providerMeta', providerResult.failure.meta),
+      },
+    });
+  }
+
+  // Create control plane stack from config
+  const stack = createControlPlaneStack(config);
+  const familyInstance = config.family.create(stack);
+
+  // Emit contract via family instance
+  const emitResult = await unlessAborted(
+    familyInstance.emitContract({ contractIR: providerResult.value }),
+  );
+
+  // 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

@@ -0,0 +1,286 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  MigrationPlan,
+  MigrationPlannerResult,
+  MigrationRunnerResult,
+  TargetMigrationsCapability,
+} from '@prisma-next/core-control-plane/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { notOk, ok } from '@prisma-next/utils/result';
+import type { DbInitResult, DbInitSuccess, OnControlProgress } from '../types';
+import { extractSqlDdl } from './extract-sql-ddl';
+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 mode: 'plan' | 'apply';
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  /** Optional progress callback for observing operation progress */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Executes the dbInit operation.
+ *
+ * This is the core logic extracted from the CLI command, without any file I/O,
+ * process.exit(), or console output. It uses the Result pattern to return
+ * success or failure details.
+ *
+ * @param options - The options for executing dbInit
+ * @returns Result with DbInitSuccess on success, DbInitFailure on failure
+ */
+export async function executeDbInit<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteDbInitOptions<TFamilyId, TTargetId>,
+): Promise<DbInitResult> {
+  const { driver, familyInstance, contractIR, mode, migrations, frameworkComponents, onProgress } =
+    options;
+
+  // Create planner and runner from target migrations capability
+  const planner = migrations.createPlanner(familyInstance);
+  const runner = migrations.createRunner(familyInstance);
+
+  // Introspect live schema
+  const introspectSpanId = 'introspect';
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanStart',
+    spanId: introspectSpanId,
+    label: 'Introspecting database schema',
+  });
+  const schemaIR = await familyInstance.introspect({ driver });
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanEnd',
+    spanId: introspectSpanId,
+    outcome: 'ok',
+  });
+
+  // Policy for init mode (additive only)
+  const policy = { allowedOperationClasses: ['additive'] as const };
+
+  // Plan migration
+  const planSpanId = 'plan';
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanStart',
+    spanId: planSpanId,
+    label: 'Planning migration',
+  });
+  const plannerResult: MigrationPlannerResult = await planner.plan({
+    contract: contractIR,
+    schema: schemaIR,
+    policy,
+    frameworkComponents,
+  });
+
+  if (plannerResult.kind === 'failure') {
+    onProgress?.({
+      action: 'dbInit',
+      kind: 'spanEnd',
+      spanId: planSpanId,
+      outcome: 'error',
+    });
+    return notOk({
+      code: 'PLANNING_FAILED' as const,
+      summary: 'Migration planning failed due to conflicts',
+      conflicts: plannerResult.conflicts,
+      why: undefined,
+      meta: undefined,
+    });
+  }
+
+  const migrationPlan: MigrationPlan = plannerResult.plan;
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanEnd',
+    spanId: planSpanId,
+    outcome: 'ok',
+  });
+
+  // Check for existing marker - handle idempotency and mismatch errors
+  const checkMarkerSpanId = 'checkMarker';
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanStart',
+    spanId: checkMarkerSpanId,
+    label: 'Checking database signature',
+  });
+  const existingMarker = await familyInstance.readMarker({ driver });
+  if (existingMarker) {
+    const markerMatchesDestination =
+      existingMarker.storageHash === migrationPlan.destination.storageHash &&
+      (!migrationPlan.destination.profileHash ||
+        existingMarker.profileHash === migrationPlan.destination.profileHash);
+
+    if (markerMatchesDestination) {
+      // Already at destination - return success with no operations
+      onProgress?.({
+        action: 'dbInit',
+        kind: 'spanEnd',
+        spanId: checkMarkerSpanId,
+        outcome: 'skipped',
+      });
+      const result: DbInitSuccess = {
+        mode,
+        plan: { operations: [] },
+        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);
+    }
+
+    // Marker exists but doesn't match destination - fail
+    onProgress?.({
+      action: 'dbInit',
+      kind: 'spanEnd',
+      spanId: checkMarkerSpanId,
+      outcome: 'error',
+    });
+    return notOk({
+      code: 'MARKER_ORIGIN_MISMATCH' as const,
+      summary: 'Existing contract marker does not match plan destination',
+      marker: {
+        storageHash: existingMarker.storageHash,
+        profileHash: existingMarker.profileHash,
+      },
+      destination: {
+        storageHash: migrationPlan.destination.storageHash,
+        profileHash: migrationPlan.destination.profileHash,
+      },
+      why: undefined,
+      conflicts: undefined,
+      meta: undefined,
+    });
+  }
+
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanEnd',
+    spanId: checkMarkerSpanId,
+    outcome: 'ok',
+  });
+
+  // Plan mode - don't execute
+  if (mode === 'plan') {
+    const planSql =
+      familyInstance.familyId === 'sql' ? extractSqlDdl(migrationPlan.operations) : undefined;
+    const result: DbInitSuccess = {
+      mode: 'plan',
+      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);
+  }
+
+  // Apply mode - execute runner
+  const applySpanId = 'apply';
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanStart',
+    spanId: applySpanId,
+    label: 'Applying migration plan',
+  });
+
+  const callbacks = createOperationCallbacks(onProgress, 'dbInit', applySpanId);
+
+  const runnerResult: MigrationRunnerResult = await runner.execute({
+    plan: migrationPlan,
+    driver,
+    destinationContract: contractIR,
+    policy,
+    ...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.
+    executionChecks: {
+      prechecks: false,
+      postchecks: false,
+      idempotencyChecks: false,
+    },
+    frameworkComponents,
+  });
+
+  if (!runnerResult.ok) {
+    onProgress?.({
+      action: 'dbInit',
+      kind: 'spanEnd',
+      spanId: applySpanId,
+      outcome: 'error',
+    });
+    return notOk({
+      code: 'RUNNER_FAILED' as const,
+      summary: runnerResult.failure.summary,
+      why: runnerResult.failure.why,
+      meta: runnerResult.failure.meta,
+      conflicts: undefined,
+    });
+  }
+
+  const execution = runnerResult.value;
+
+  onProgress?.({
+    action: 'dbInit',
+    kind: 'spanEnd',
+    spanId: applySpanId,
+    outcome: 'ok',
+  });
+
+  const result: DbInitSuccess = {
+    mode: 'apply',
+    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
+      ? {
+          storageHash: migrationPlan.destination.storageHash,
+          profileHash: migrationPlan.destination.profileHash,
+        }
+      : { storageHash: migrationPlan.destination.storageHash },
+    summary: `Applied ${execution.operationsExecuted} operation(s), database signed`,
+  };
+  return ok(result);
+}

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

@@ -0,0 +1,221 @@
+import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type {
+  ControlDriverInstance,
+  ControlFamilyInstance,
+  MigrationPlannerResult,
+  MigrationRunnerResult,
+  TargetMigrationsCapability,
+} from '@prisma-next/core-control-plane/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { notOk, ok } from '@prisma-next/utils/result';
+import type { DbUpdateResult, DbUpdateSuccess, OnControlProgress } from '../types';
+import { extractSqlDdl } from './extract-sql-ddl';
+import { createOperationCallbacks, stripOperations } from './migration-helpers';
+
+// F12: db update allows additive, widening, and destructive operations.
+const DB_UPDATE_POLICY = {
+  allowedOperationClasses: ['additive', 'widening', 'destructive'] as const,
+} as const;
+
+/**
+ * Options for the executeDbUpdate operation.
+ * Config-agnostic: receives pre-resolved driver, family, contract, and migrations capability.
+ */
+export interface ExecuteDbUpdateOptions<TFamilyId extends string, TTargetId extends string> {
+  readonly driver: ControlDriverInstance<TFamilyId, TTargetId>;
+  readonly familyInstance: ControlFamilyInstance<TFamilyId>;
+  readonly contractIR: ContractIR;
+  readonly mode: 'plan' | 'apply';
+  readonly migrations: TargetMigrationsCapability<
+    TFamilyId,
+    TTargetId,
+    ControlFamilyInstance<TFamilyId>
+  >;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+  readonly acceptDataLoss?: boolean;
+  /** Optional progress callback for observing operation progress. */
+  readonly onProgress?: OnControlProgress;
+}
+
+/**
+ * Executes the db update operation: introspect → plan → (optionally) apply → marker.
+ *
+ * db update is a pure reconciliation command: it introspects the live schema, plans the diff
+ * to the destination contract, and applies operations. The marker is bookkeeping only — written
+ * after apply so that `verify` and `db init` can reference it, but never read or validated
+ * by db update itself. The runner creates the marker table if it does not exist.
+ */
+export async function executeDbUpdate<TFamilyId extends string, TTargetId extends string>(
+  options: ExecuteDbUpdateOptions<TFamilyId, TTargetId>,
+): Promise<DbUpdateResult> {
+  const { driver, familyInstance, contractIR, mode, migrations, frameworkComponents, onProgress } =
+    options;
+
+  const planner = migrations.createPlanner(familyInstance);
+  const runner = migrations.createRunner(familyInstance);
+
+  const introspectSpanId = 'introspect';
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanStart',
+    spanId: introspectSpanId,
+    label: 'Introspecting database schema',
+  });
+  const schemaIR = await familyInstance.introspect({ driver });
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanEnd',
+    spanId: introspectSpanId,
+    outcome: 'ok',
+  });
+
+  const policy = DB_UPDATE_POLICY;
+
+  const planSpanId = 'plan';
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanStart',
+    spanId: planSpanId,
+    label: 'Planning migration',
+  });
+  const plannerResult: MigrationPlannerResult = await planner.plan({
+    contract: contractIR,
+    schema: schemaIR,
+    policy,
+    frameworkComponents,
+  });
+  if (plannerResult.kind === 'failure') {
+    onProgress?.({
+      action: 'dbUpdate',
+      kind: 'spanEnd',
+      spanId: planSpanId,
+      outcome: 'error',
+    });
+    return notOk({
+      code: 'PLANNING_FAILED',
+      summary: 'Migration planning failed due to conflicts',
+      conflicts: plannerResult.conflicts,
+      why: undefined,
+      meta: undefined,
+    });
+  }
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanEnd',
+    spanId: planSpanId,
+    outcome: 'ok',
+  });
+
+  const migrationPlan = plannerResult.plan;
+
+  if (mode === 'plan') {
+    const planSql =
+      familyInstance.familyId === 'sql' ? extractSqlDdl(migrationPlan.operations) : undefined;
+    const result: DbUpdateSuccess = {
+      mode: 'plan',
+      plan: {
+        operations: stripOperations(migrationPlan.operations),
+        ...(planSql !== undefined ? { sql: planSql } : {}),
+      },
+      destination: {
+        storageHash: migrationPlan.destination.storageHash,
+        ...ifDefined('profileHash', migrationPlan.destination.profileHash),
+      },
+      summary: `Planned ${migrationPlan.operations.length} operation(s)`,
+    };
+    return ok(result);
+  }
+
+  // When applying, require explicit acceptance for destructive operations
+  if (!options.acceptDataLoss) {
+    const destructiveOps = migrationPlan.operations
+      .filter((op) => op.operationClass === 'destructive')
+      .map((op) => ({ id: op.id, label: op.label }));
+    if (destructiveOps.length > 0) {
+      return notOk({
+        code: 'DESTRUCTIVE_CHANGES',
+        summary: `Planned ${destructiveOps.length} destructive operation(s) that require confirmation`,
+        why: 'Use --plan to preview destructive operations, then re-run with --accept-data-loss to apply',
+        conflicts: undefined,
+        meta: { destructiveOperations: destructiveOps },
+      });
+    }
+  }
+
+  const applySpanId = 'apply';
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanStart',
+    spanId: applySpanId,
+    label: 'Applying migration plan',
+  });
+
+  const callbacks = createOperationCallbacks(onProgress, 'dbUpdate', applySpanId);
+
+  const runnerResult: MigrationRunnerResult = await runner.execute({
+    plan: migrationPlan,
+    driver,
+    destinationContract: contractIR,
+    policy,
+    ...(callbacks ? { callbacks } : {}),
+    // db update plans and applies from a single introspection pass, so per-operation pre/postchecks
+    // and idempotency probes are intentionally disabled to avoid redundant roundtrips.
+    executionChecks: {
+      prechecks: false,
+      postchecks: false,
+      idempotencyChecks: false,
+    },
+    frameworkComponents,
+  });
+
+  if (!runnerResult.ok) {
+    onProgress?.({
+      action: 'dbUpdate',
+      kind: 'spanEnd',
+      spanId: applySpanId,
+      outcome: 'error',
+    });
+    return notOk({
+      code: 'RUNNER_FAILED',
+      summary: runnerResult.failure.summary,
+      why: runnerResult.failure.why,
+      meta: runnerResult.failure.meta,
+      conflicts: undefined,
+    });
+  }
+
+  const execution = runnerResult.value;
+  onProgress?.({
+    action: 'dbUpdate',
+    kind: 'spanEnd',
+    spanId: applySpanId,
+    outcome: 'ok',
+  });
+
+  const result: DbUpdateSuccess = {
+    mode: 'apply',
+    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
+      ? {
+          storageHash: migrationPlan.destination.storageHash,
+          profileHash: migrationPlan.destination.profileHash,
+        }
+      : { storageHash: migrationPlan.destination.storageHash },
+    summary:
+      execution.operationsExecuted === 0
+        ? 'Database already matches contract, signature updated'
+        : `Applied ${execution.operationsExecuted} operation(s), signature updated`,
+  };
+  return ok(result);
+}