@prisma-next/cli 0.3.0-dev.3 → 0.3.0-dev.30

package/src/load-ts-contract.ts

@@ -0,0 +1,217 @@
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { Plugin } from 'esbuild';
+import { build } from 'esbuild';
+
+export interface LoadTsContractOptions {
+  readonly allowlist?: ReadonlyArray<string>;
+}
+
+const DEFAULT_ALLOWLIST = ['@prisma-next/*'];
+
+function isAllowedImport(importPath: string, allowlist: ReadonlyArray<string>): boolean {
+  for (const pattern of allowlist) {
+    if (pattern.endsWith('/*')) {
+      const prefix = pattern.slice(0, -2);
+      if (importPath === prefix || importPath.startsWith(`${prefix}/`)) {
+        return true;
+      }
+    } else if (importPath === pattern) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function validatePurity(value: unknown): void {
+  if (typeof value !== 'object' || value === null) {
+    return;
+  }
+
+  const seen = new WeakSet();
+  function check(value: unknown): void {
+    if (value === null || typeof value !== 'object') {
+      return;
+    }
+
+    if (seen.has(value)) {
+      throw new Error('Contract export contains circular references');
+    }
+    seen.add(value);
+
+    for (const key in value) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor && (descriptor.get || descriptor.set)) {
+        throw new Error(`Contract export contains getter/setter at key "${key}"`);
+      }
+      if (descriptor && typeof descriptor.value === 'function') {
+        throw new Error(`Contract export contains function at key "${key}"`);
+      }
+      check((value as Record<string, unknown>)[key]);
+    }
+  }
+
+  try {
+    check(value);
+    JSON.stringify(value);
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.message.includes('getter') || error.message.includes('circular')) {
+        throw error;
+      }
+      throw new Error(`Contract export is not JSON-serializable: ${error.message}`);
+    }
+    throw new Error('Contract export is not JSON-serializable');
+  }
+}
+
+function createImportAllowlistPlugin(allowlist: ReadonlyArray<string>, entryPath: string): Plugin {
+  return {
+    name: 'import-allowlist',
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (args.kind === 'entry-point') {
+          return undefined;
+        }
+        if (args.path.startsWith('.') || args.path.startsWith('/')) {
+          return undefined;
+        }
+        const isFromEntryPoint = args.importer === entryPath || args.importer === '<stdin>';
+        if (isFromEntryPoint && !isAllowedImport(args.path, allowlist)) {
+          return {
+            path: args.path,
+            external: true,
+          };
+        }
+        return undefined;
+      });
+    },
+  };
+}
+
+/**
+ * Loads a contract from a TypeScript file and returns it as ContractIR.
+ *
+ * **Responsibility: Parsing Only**
+ * This function loads and parses a TypeScript contract file. It does NOT normalize the contract.
+ * The contract should already be normalized if it was built using the contract builder.
+ *
+ * Normalization must happen in the contract builder when the contract is created.
+ * This function only validates that the contract is JSON-serializable and returns it as-is.
+ *
+ * @param entryPath - Path to the TypeScript contract file
+ * @param options - Optional configuration (import allowlist)
+ * @returns The contract as ContractIR (should already be normalized)
+ * @throws Error if the contract cannot be loaded or is not JSON-serializable
+ */
+export async function loadContractFromTs(
+  entryPath: string,
+  options?: LoadTsContractOptions,
+): Promise<ContractIR> {
+  const allowlist = options?.allowlist ?? DEFAULT_ALLOWLIST;
+
+  if (!existsSync(entryPath)) {
+    throw new Error(`Contract file not found: ${entryPath}`);
+  }
+
+  const tempFile = join(
+    tmpdir(),
+    `prisma-next-contract-${Date.now()}-${Math.random().toString(36).slice(2)}.mjs`,
+  );
+
+  try {
+    const result = await build({
+      entryPoints: [entryPath],
+      bundle: true,
+      format: 'esm',
+      platform: 'node',
+      target: 'es2022',
+      outfile: tempFile,
+      write: false,
+      metafile: true,
+      plugins: [createImportAllowlistPlugin(allowlist, entryPath)],
+      logLevel: 'error',
+    });
+
+    if (result.errors.length > 0) {
+      const errorMessages = result.errors.map((e: { text: string }) => e.text).join('\n');
+      throw new Error(`Failed to bundle contract file: ${errorMessages}`);
+    }
+
+    if (!result.outputFiles || result.outputFiles.length === 0) {
+      throw new Error('No output files generated from bundling');
+    }
+
+    const disallowedImports: string[] = [];
+    if (result.metafile) {
+      const inputs = result.metafile.inputs;
+      for (const [, inputData] of Object.entries(inputs)) {
+        const imports =
+          (inputData as { imports?: Array<{ path: string; external?: boolean }> }).imports || [];
+        for (const imp of imports) {
+          if (
+            imp.external &&
+            !imp.path.startsWith('.') &&
+            !imp.path.startsWith('/') &&
+            !isAllowedImport(imp.path, allowlist)
+          ) {
+            disallowedImports.push(imp.path);
+          }
+        }
+      }
+    }
+
+    if (disallowedImports.length > 0) {
+      throw new Error(
+        `Disallowed imports detected. Only imports matching the allowlist are permitted:\n  Allowlist: ${allowlist.join(', ')}\n  Disallowed imports: ${disallowedImports.join(', ')}\n\nOnly @prisma-next/* packages are allowed in contract files.`,
+      );
+    }
+
+    const bundleContent = result.outputFiles[0]?.text;
+    if (bundleContent === undefined) {
+      throw new Error('Bundle content is undefined');
+    }
+    writeFileSync(tempFile, bundleContent, 'utf-8');
+
+    const module = (await import(`file://${tempFile}`)) as {
+      default?: unknown;
+      contract?: unknown;
+    };
+    unlinkSync(tempFile);
+
+    let contract: unknown;
+
+    if (module.default !== undefined) {
+      contract = module.default;
+    } else if (module.contract !== undefined) {
+      contract = module.contract;
+    } else {
+      throw new Error(
+        `Contract file must export a contract as default export or named export 'contract'. Found exports: ${Object.keys(module as Record<string, unknown>).join(', ') || 'none'}`,
+      );
+    }
+
+    if (typeof contract !== 'object' || contract === null) {
+      throw new Error(`Contract export must be an object, got ${typeof contract}`);
+    }
+
+    validatePurity(contract);
+
+    return contract as ContractIR;
+  } catch (error) {
+    try {
+      if (tempFile) {
+        unlinkSync(tempFile);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    if (error instanceof Error) {
+      throw error;
+    }
+    throw new Error(`Failed to load contract from ${entryPath}: ${String(error)}`);
+  }
+}

package/src/utils/cli-errors.ts

@@ -0,0 +1,26 @@
+/**
+ * Re-export all domain error factories from core-control-plane for convenience.
+ * CLI-specific errors (e.g., Commander.js argument validation) can be added here if needed.
+ */
+export type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/core-control-plane/errors';
+export {
+  CliStructuredError,
+  errorConfigFileNotFound,
+  errorConfigValidation,
+  errorContractConfigMissing,
+  errorContractMissingExtensionPacks,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFamilyReadMarkerSqlRequired,
+  errorFileNotFound,
+  errorHashMismatch,
+  errorJsonFormatNotSupported,
+  errorMarkerMissing,
+  errorMigrationPlanningFailed,
+  errorQueryRunnerFactoryRequired,
+  errorRuntime,
+  errorTargetMigrationNotSupported,
+  errorTargetMismatch,
+  errorUnexpected,
+} from '@prisma-next/core-control-plane/errors';

package/src/utils/command-helpers.ts

@@ -0,0 +1,26 @@
+import type { Command } from 'commander';
+
+/**
+ * Sets both short and long descriptions for a command.
+ * The short description is used in command trees and headers.
+ * The long description is shown at the bottom of help output.
+ */
+export function setCommandDescriptions(
+  command: Command,
+  shortDescription: string,
+  longDescription?: string,
+): Command {
+  command.description(shortDescription);
+  if (longDescription) {
+    // Store long description in a custom property for our formatters to access
+    (command as Command & { _longDescription?: string })._longDescription = longDescription;
+  }
+  return command;
+}
+
+/**
+ * Gets the long description from a command if it was set via setCommandDescriptions.
+ */
+export function getLongDescription(command: Command): string | undefined {
+  return (command as Command & { _longDescription?: string })._longDescription;
+}

package/src/utils/framework-components.ts

@@ -0,0 +1,177 @@
+import {
+  checkContractComponentRequirements,
+  type TargetBoundComponentDescriptor,
+} from '@prisma-next/contract/framework-components';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { ControlPlaneStack } from '@prisma-next/core-control-plane/types';
+import { errorConfigValidation, errorContractMissingExtensionPacks } from './cli-errors';
+
+/**
+ * Asserts that all framework components are compatible with the expected family and target.
+ *
+ * This function validates that each component in the framework components array:
+ * - Has kind 'target', 'adapter', 'extension', or 'driver'
+ * - Has familyId matching expectedFamilyId
+ * - Has targetId matching expectedTargetId
+ *
+ * This validation happens at the CLI composition boundary, before passing components
+ * to typed planner/runner instances. It fills the gap between runtime validation
+ * (via `validateConfig()`) and compile-time type enforcement.
+ *
+ * @param expectedFamilyId - The expected family ID (e.g., 'sql')
+ * @param expectedTargetId - The expected target ID (e.g., 'postgres')
+ * @param frameworkComponents - Array of framework components to validate
+ * @returns The same array typed as TargetBoundComponentDescriptor
+ * @throws CliStructuredError if any component is incompatible
+ *
+ * @example
+ * ```ts
+ * const config = await loadConfig();
+ * const frameworkComponents = [config.target, config.adapter, ...(config.extensionPacks ?? [])];
+ *
+ * // Validate and type-narrow components before passing to planner
+ * const typedComponents = assertFrameworkComponentsCompatible(
+ *   config.family.familyId,
+ *   config.target.targetId,
+ *   frameworkComponents
+ * );
+ *
+ * const planner = target.migrations.createPlanner(familyInstance);
+ * planner.plan({ contract, schema, policy, frameworkComponents: typedComponents });
+ * ```
+ */
+export function assertFrameworkComponentsCompatible<
+  TFamilyId extends string,
+  TTargetId extends string,
+>(
+  expectedFamilyId: TFamilyId,
+  expectedTargetId: TTargetId,
+  frameworkComponents: ReadonlyArray<unknown>,
+): ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>> {
+  for (let i = 0; i < frameworkComponents.length; i++) {
+    const component = frameworkComponents[i];
+
+    // Check that component is an object
+    if (typeof component !== 'object' || component === null) {
+      throw errorConfigValidation('frameworkComponents[]', {
+        why: `Framework component at index ${i} must be an object`,
+      });
+    }
+
+    const record = component as Record<string, unknown>;
+
+    // Check kind
+    if (!Object.hasOwn(record, 'kind')) {
+      throw errorConfigValidation('frameworkComponents[].kind', {
+        why: `Framework component at index ${i} must have 'kind' property`,
+      });
+    }
+
+    const kind = record['kind'];
+    if (kind !== 'target' && kind !== 'adapter' && kind !== 'extension' && kind !== 'driver') {
+      throw errorConfigValidation('frameworkComponents[].kind', {
+        why: `Framework component at index ${i} has invalid kind '${String(kind)}' (must be 'target', 'adapter', 'extension', or 'driver')`,
+      });
+    }
+
+    // Check familyId
+    if (!Object.hasOwn(record, 'familyId')) {
+      throw errorConfigValidation('frameworkComponents[].familyId', {
+        why: `Framework component at index ${i} (kind: ${String(kind)}) must have 'familyId' property`,
+      });
+    }
+
+    const familyId = record['familyId'];
+    if (familyId !== expectedFamilyId) {
+      throw errorConfigValidation('frameworkComponents[].familyId', {
+        why: `Framework component at index ${i} (kind: ${String(kind)}) has familyId '${String(familyId)}' but expected '${expectedFamilyId}'`,
+      });
+    }
+
+    // Check targetId
+    if (!Object.hasOwn(record, 'targetId')) {
+      throw errorConfigValidation('frameworkComponents[].targetId', {
+        why: `Framework component at index ${i} (kind: ${String(kind)}) must have 'targetId' property`,
+      });
+    }
+
+    const targetId = record['targetId'];
+    if (targetId !== expectedTargetId) {
+      throw errorConfigValidation('frameworkComponents[].targetId', {
+        why: `Framework component at index ${i} (kind: ${String(kind)}) has targetId '${String(targetId)}' but expected '${expectedTargetId}'`,
+      });
+    }
+  }
+
+  // Type assertion is safe because we've validated all components above
+  return frameworkComponents as ReadonlyArray<TargetBoundComponentDescriptor<TFamilyId, TTargetId>>;
+}
+
+/**
+ * Validates that a contract is compatible with the configured target, adapter,
+ * and extension packs. Throws on family/target mismatches or missing extension packs.
+ *
+ * This check ensures the emitted contract matches the CLI config before running
+ * commands that depend on the contract (e.g., db verify, db sign).
+ *
+ * @param contract - The contract IR to validate (must include targetFamily, target, extensionPacks).
+ * @param stack - The control plane stack (target, adapter, driver, extensionPacks).
+ *
+ * @throws {CliStructuredError} errorConfigValidation when contract.targetFamily or contract.target
+ *   doesn't match the configured family/target.
+ * @throws {CliStructuredError} errorContractMissingExtensionPacks when the contract requires
+ *   extension packs that are not provided in the config (includes all missing packs in error.meta).
+ *
+ * @example
+ * ```ts
+ * import { assertContractRequirementsSatisfied } from './framework-components';
+ *
+ * const config = await loadConfig();
+ * const contractIR = await loadContractJson(config.contract.output);
+ * const stack = createControlPlaneStack({ target: config.target, adapter: config.adapter, ... });
+ *
+ * // Throws if contract is incompatible with config
+ * assertContractRequirementsSatisfied({ contract: contractIR, stack });
+ * ```
+ */
+export function assertContractRequirementsSatisfied<
+  TFamilyId extends string,
+  TTargetId extends string,
+>({
+  contract,
+  stack,
+}: {
+  readonly contract: Pick<ContractIR, 'targetFamily' | 'target' | 'extensionPacks'>;
+  readonly stack: ControlPlaneStack<TFamilyId, TTargetId>;
+}): void {
+  const providedComponentIds = new Set<string>([stack.target.id, stack.adapter.id]);
+  for (const extension of stack.extensionPacks) {
+    providedComponentIds.add(extension.id);
+  }
+
+  const result = checkContractComponentRequirements({
+    contract,
+    expectedTargetFamily: stack.target.familyId,
+    expectedTargetId: stack.target.targetId,
+    providedComponentIds,
+  });
+
+  if (result.familyMismatch) {
+    throw errorConfigValidation('contract.targetFamily', {
+      why: `Contract was emitted for family '${result.familyMismatch.actual}' but CLI config is wired to '${result.familyMismatch.expected}'.`,
+    });
+  }
+
+  if (result.targetMismatch) {
+    throw errorConfigValidation('contract.target', {
+      why: `Contract target '${result.targetMismatch.actual}' does not match CLI target '${result.targetMismatch.expected}'.`,
+    });
+  }
+
+  if (result.missingExtensionPackIds.length > 0) {
+    throw errorContractMissingExtensionPacks({
+      missingExtensionPacks: result.missingExtensionPackIds,
+      providedComponentIds: [...providedComponentIds],
+    });
+  }
+}

package/src/utils/global-flags.ts

@@ -0,0 +1,75 @@
+export interface GlobalFlags {
+  readonly json?: 'object' | 'ndjson';
+  readonly quiet?: boolean;
+  readonly verbose?: number; // 0, 1, or 2
+  readonly timestamps?: boolean;
+  readonly color?: boolean;
+}
+
+export interface CliOptions {
+  readonly json?: string | boolean;
+  readonly quiet?: boolean;
+  readonly q?: boolean;
+  readonly verbose?: boolean;
+  readonly v?: boolean;
+  readonly vv?: boolean;
+  readonly trace?: boolean;
+  readonly timestamps?: boolean;
+  readonly color?: boolean;
+  readonly 'no-color'?: boolean;
+}
+
+/**
+ * Parses global flags from CLI options.
+ * Handles verbosity flags (-v, -vv, --trace), JSON output, quiet mode, timestamps, and color.
+ */
+export function parseGlobalFlags(options: CliOptions): GlobalFlags {
+  const flags: {
+    json?: 'object' | 'ndjson';
+    quiet?: boolean;
+    verbose?: number;
+    timestamps?: boolean;
+    color?: boolean;
+  } = {};
+
+  // JSON output
+  if (options.json === true || options.json === 'object') {
+    flags.json = 'object';
+  } else if (options.json === 'ndjson') {
+    flags.json = 'ndjson';
+  }
+
+  // Quiet mode
+  if (options.quiet || options.q) {
+    flags.quiet = true;
+  }
+
+  // Verbosity: -v = 1, -vv or --trace = 2
+  if (options.vv || options.trace) {
+    flags.verbose = 2;
+  } else if (options.verbose || options.v) {
+    flags.verbose = 1;
+  } else {
+    flags.verbose = 0;
+  }
+
+  // Timestamps
+  if (options.timestamps) {
+    flags.timestamps = true;
+  }
+
+  // Color: respect NO_COLOR env var, --color/--no-color flags
+  // When JSON output is enabled (any format), disable color to ensure clean JSON output
+  if (process.env['NO_COLOR'] || flags.json) {
+    flags.color = false;
+  } else if (options['no-color']) {
+    flags.color = false;
+  } else if (options.color !== undefined) {
+    flags.color = options.color;
+  } else {
+    // Default: enable color if TTY
+    flags.color = process.stdout.isTTY && !process.env['CI'];
+  }
+
+  return flags as GlobalFlags;
+}