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

package/src/load-ts-contract.ts

@@ -1,15 +1,16 @@
 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 { pathToFileURL } from 'node:url';
+import type { Contract } from '@prisma-next/contract/types';
 import type { Plugin } from 'esbuild';
 import { build } from 'esbuild';
+import { join } from 'pathe';
 
 export interface LoadTsContractOptions {
   readonly allowlist?: ReadonlyArray<string>;
 }
 
-const DEFAULT_ALLOWLIST = ['@prisma-next/*'];
+const DEFAULT_ALLOWLIST = ['@prisma-next/*', 'node:crypto'];
 
 function isAllowedImport(importPath: string, allowlist: ReadonlyArray<string>): boolean {
   for (const pattern of allowlist) {
@@ -18,6 +19,11 @@ function isAllowedImport(importPath: string, allowlist: ReadonlyArray<string>):
       if (importPath === prefix || importPath.startsWith(`${prefix}/`)) {
         return true;
       }
+    } else if (pattern.endsWith('*')) {
+      const prefix = pattern.slice(0, -1);
+      if (importPath.startsWith(prefix)) {
+        return true;
+      }
     } else if (importPath === pattern) {
       return true;
     }
@@ -30,26 +36,31 @@ function validatePurity(value: unknown): void {
     return;
   }
 
-  const seen = new WeakSet();
+  const path = new WeakSet();
+
   function check(value: unknown): void {
     if (value === null || typeof value !== 'object') {
       return;
     }
 
-    if (seen.has(value)) {
+    if (path.has(value)) {
       throw new Error('Contract export contains circular references');
     }
-    seen.add(value);
+    path.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}"`);
+    try {
+      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]);
       }
-      check((value as Record<string, unknown>)[key]);
+    } finally {
+      path.delete(value);
     }
   }
 
@@ -92,7 +103,7 @@ function createImportAllowlistPlugin(allowlist: ReadonlyArray<string>, entryPath
 }
 
 /**
- * Loads a contract from a TypeScript file and returns it as ContractIR.
+ * Loads a contract from a TypeScript file and returns it as Contract.
  *
  * **Responsibility: Parsing Only**
  * This function loads and parses a TypeScript contract file. It does NOT normalize the contract.
@@ -103,13 +114,13 @@ function createImportAllowlistPlugin(allowlist: ReadonlyArray<string>, entryPath
  *
  * @param entryPath - Path to the TypeScript contract file
  * @param options - Optional configuration (import allowlist)
- * @returns The contract as ContractIR (should already be normalized)
+ * @returns The contract as Contract (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> {
+): Promise<Contract> {
   const allowlist = options?.allowlist ?? DEFAULT_ALLOWLIST;
 
   if (!existsSync(entryPath)) {
@@ -175,7 +186,7 @@ export async function loadContractFromTs(
     }
     writeFileSync(tempFile, bundleContent, 'utf-8');
 
-    const module = (await import(`file://${tempFile}`)) as {
+    const module = (await import(/* @vite-ignore */ pathToFileURL(tempFile).href)) as {
       default?: unknown;
       contract?: unknown;
     };
@@ -199,7 +210,7 @@ export async function loadContractFromTs(
 
     validatePurity(contract);
 
-    return contract as ContractIR;
+    return contract as Contract;
   } catch (error) {
     try {
       if (tempFile) {

package/src/utils/cli-errors.ts

@@ -1,8 +1,8 @@
 /**
- * Re-export all domain error factories from core-control-plane for convenience.
+ * Re-export all domain error factories from @prisma-next/errors 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 type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';
 export {
   CliStructuredError,
   errorConfigFileNotFound,
@@ -14,13 +14,19 @@ export {
   errorDriverRequired,
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
-  errorHashMismatch,
-  errorJsonFormatNotSupported,
-  errorMarkerMissing,
   errorMigrationPlanningFailed,
   errorQueryRunnerFactoryRequired,
-  errorRuntime,
   errorTargetMigrationNotSupported,
-  errorTargetMismatch,
   errorUnexpected,
-} from '@prisma-next/core-control-plane/errors';
+} from '@prisma-next/errors/control';
+export {
+  ERROR_CODE_DESTRUCTIVE_CHANGES,
+  errorDestructiveChanges,
+  errorHashMismatch,
+  errorMarkerMissing,
+  errorMarkerRequired,
+  errorRunnerFailed,
+  errorRuntime,
+  errorSchemaVerificationFailed,
+  errorTargetMismatch,
+} from '@prisma-next/errors/execution';

package/src/utils/command-helpers.ts

@@ -1,4 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import type { ControlTargetDescriptor } from '@prisma-next/framework-components/control';
+import { hasMigrations } from '@prisma-next/framework-components/control';
+import type { PathDecision } from '@prisma-next/migration-tools/dag';
+import { reconstructGraph } from '@prisma-next/migration-tools/dag';
+import { readMigrationsDir } from '@prisma-next/migration-tools/io';
+import type {
+  AttestedMigrationBundle,
+  DraftMigrationBundle,
+  MigrationGraph,
+} from '@prisma-next/migration-tools/types';
+import { isAttested, isDraft } from '@prisma-next/migration-tools/types';
+import { ifDefined } from '@prisma-next/utils/defined';
 import type { Command } from 'commander';
+import { relative, resolve } from 'pathe';
+import { formatCommandHelp } from './formatters/help';
+import type { CommonCommandOptions } from './global-flags';
+import { parseGlobalFlags } from './global-flags';
+
+const longDescriptions = new WeakMap<Command, string>();
+const commandExamples = new WeakMap<Command, readonly string[]>();
 
 /**
  * Sets both short and long descriptions for a command.
@@ -12,15 +32,294 @@ export function setCommandDescriptions(
 ): 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;
+    longDescriptions.set(command, longDescription);
   }
   return command;
 }
 
+/**
+ * Sets copy-pastable examples for a command, shown in help text.
+ */
+export function setCommandExamples(command: Command, examples: readonly string[]): Command {
+  commandExamples.set(command, examples);
+  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;
+  return longDescriptions.get(command);
+}
+
+/**
+ * Gets examples from a command if set via setCommandExamples.
+ */
+export function getCommandExamples(command: Command): readonly string[] | undefined {
+  return commandExamples.get(command);
+}
+
+/**
+ * Shared CLI options interface for migration commands (db init, db update).
+ * These are the Commander.js parsed options common to both commands.
+ */
+export interface MigrationCommandOptions extends CommonCommandOptions {
+  readonly db?: string;
+  readonly config?: string;
+  readonly dryRun?: boolean;
+}
+
+/**
+ * Resolves the absolute path to contract.json from the config.
+ * Centralises the fallback logic shared by every command that reads the contract.
+ */
+export function resolveContractPath(config: { contract?: { output?: string } }): string {
+  return config.contract?.output
+    ? resolve(config.contract.output)
+    : resolve('src/prisma/contract.json');
+}
+
+/**
+ * Resolves the migrations directory and config path from CLI options.
+ * Shared by migration-apply, migration-plan, and migration-status.
+ */
+export function resolveMigrationPaths(
+  configOption: string | undefined,
+  config: { migrations?: { dir?: string } },
+): {
+  configPath: string;
+  migrationsDir: string;
+  migrationsRelative: string;
+  refsPath: string;
+} {
+  const configPath = configOption
+    ? relative(process.cwd(), resolve(configOption))
+    : 'prisma-next.config.ts';
+  const migrationsDir = resolve(
+    configOption ? resolve(configOption, '..') : process.cwd(),
+    config.migrations?.dir ?? 'migrations',
+  );
+  const migrationsRelative = relative(process.cwd(), migrationsDir);
+  const refsPath = resolve(migrationsDir, 'refs.json');
+  return { configPath, migrationsDir, migrationsRelative, refsPath };
+}
+
+/**
+ * Slim representation of a PathDecision for CLI JSON output.
+ * Strips internal fields (createdAt, labels) from path entries.
+ */
+export interface PathDecisionResult {
+  readonly fromHash: string;
+  readonly toHash: string;
+  readonly alternativeCount: number;
+  readonly tieBreakReasons: readonly string[];
+  readonly refName?: string;
+  readonly selectedPath: readonly {
+    readonly dirName: string;
+    readonly migrationId: string;
+    readonly from: string;
+    readonly to: string;
+  }[];
+}
+
+/**
+ * Maps a PathDecision to the slim CLI output representation.
+ */
+export function toPathDecisionResult(decision: PathDecision): PathDecisionResult {
+  return {
+    fromHash: decision.fromHash,
+    toHash: decision.toHash,
+    alternativeCount: decision.alternativeCount,
+    tieBreakReasons: decision.tieBreakReasons,
+    ...ifDefined('refName', decision.refName),
+    selectedPath: decision.selectedPath.map((entry) => ({
+      dirName: entry.dirName,
+      migrationId: entry.migrationId,
+      from: entry.from,
+      to: entry.to,
+    })),
+  };
+}
+
+export function targetSupportsMigrations(target: ControlTargetDescriptor<string, string>): boolean {
+  return hasMigrations(target);
+}
+
+export function getTargetMigrations(target: ControlTargetDescriptor<string, string>) {
+  return hasMigrations(target) ? target.migrations : undefined;
+}
+
+/**
+ * Reads the migrations directory, filters to attested bundles, and builds
+ * the migration graph. Throws on I/O or graph errors — callers handle
+ * error mapping.
+ */
+export async function loadMigrationBundles(migrationsDir: string): Promise<{
+  bundles: readonly AttestedMigrationBundle[];
+  graph: MigrationGraph;
+}> {
+  const allBundles = await readMigrationsDir(migrationsDir);
+  const bundles = allBundles.filter(isAttested);
+  const graph = reconstructGraph(bundles);
+  return { bundles, graph };
+}
+
+export interface MigrationBundleSet {
+  readonly attested: readonly AttestedMigrationBundle[];
+  readonly drafts: readonly DraftMigrationBundle[];
+  readonly graph: MigrationGraph;
+}
+
+export async function loadAllBundles(migrationsDir: string): Promise<MigrationBundleSet> {
+  const all = await readMigrationsDir(migrationsDir);
+  const attested = all.filter(isAttested);
+  const drafts = all.filter(isDraft);
+  const graph = reconstructGraph(attested);
+  return { attested, drafts, graph };
+}
+
+/**
+ * The subset of the emitted contract.json that the framework layer can
+ * safely type. The emitter adds these fields on top of the family-specific
+ * storage/models/relations. Other fields exist in the JSON but are opaque
+ * at this layer — the index signature preserves them for downstream
+ * consumers that operate at the family level (e.g., the control client).
+ */
+export interface ContractEnvelope {
+  readonly storageHash: string;
+  readonly schemaVersion: string;
+  readonly target: string;
+  readonly targetFamily: string;
+  readonly profileHash?: string;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Reads and parses contract.json, validating the framework-level envelope
+ * fields (storageHash, schemaVersion, target, targetFamily).
+ *
+ * Family-specific validation (storage structure, codec mappings, etc.)
+ * happens downstream in the control client via the family instance.
+ */
+export async function readContractEnvelope(config: {
+  contract?: { output?: string };
+}): Promise<ContractEnvelope> {
+  const contractPath = resolveContractPath(config);
+  const content = await readFile(contractPath, 'utf-8');
+  const json = JSON.parse(content) as Record<string, unknown>;
+
+  const { schemaVersion, target, targetFamily, profileHash } = json;
+  const storage = json['storage'] as Record<string, unknown> | undefined;
+  const storageHash = storage?.['storageHash'];
+
+  if (typeof storageHash !== 'string') {
+    throw new Error(
+      `Contract at ${relative(process.cwd(), contractPath)} is missing a valid storage.storageHash. Run \`prisma-next contract emit\` to regenerate.`,
+    );
+  }
+  if (typeof schemaVersion !== 'string') {
+    throw new Error(
+      `Contract at ${relative(process.cwd(), contractPath)} is missing schemaVersion.`,
+    );
+  }
+  if (typeof target !== 'string') {
+    throw new Error(`Contract at ${relative(process.cwd(), contractPath)} is missing target.`);
+  }
+  if (typeof targetFamily !== 'string') {
+    throw new Error(
+      `Contract at ${relative(process.cwd(), contractPath)} is missing targetFamily.`,
+    );
+  }
+
+  return {
+    ...json,
+    storageHash,
+    schemaVersion,
+    target,
+    targetFamily,
+    ...(typeof profileHash === 'string' ? { profileHash } : {}),
+  };
+}
+
+/**
+ * Masks credentials in a database connection URL.
+ * Handles standard URLs (username + password + query params) and libpq-style key=value strings.
+ */
+export function maskConnectionUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    if (parsed.username) {
+      parsed.username = '****';
+    }
+    if (parsed.password) {
+      parsed.password = '****';
+    }
+    // Also mask password in query parameters (e.g., ?password=secret, ?sslpassword=secret)
+    for (const key of [...parsed.searchParams.keys()]) {
+      if (/password/i.test(key)) {
+        parsed.searchParams.set(key, '****');
+      }
+    }
+    return parsed.toString();
+  } catch {
+    // Fallback for libpq-style key=value connection strings (e.g., "host=localhost password=secret user=admin")
+    return url
+      .replace(/password\s*=\s*\S+/gi, 'password=****')
+      .replace(/user\s*=\s*\S+/gi, 'user=****');
+  }
+}
+
+/**
+ * Strips raw connection URL fragments from an error message to prevent credential leakage.
+ * Call this before surfacing driver errors to the user.
+ */
+export function sanitizeErrorMessage(message: string, connectionUrl?: string): string {
+  if (!connectionUrl) {
+    return message;
+  }
+  try {
+    const parsed = new URL(connectionUrl);
+    // Replace the full URL (with and without trailing slash)
+    let sanitized = message;
+    sanitized = sanitized.replaceAll(connectionUrl, maskConnectionUrl(connectionUrl));
+    // Also replace the password and username individually if they appear
+    if (parsed.password) {
+      sanitized = sanitized.replaceAll(parsed.password, '****');
+    }
+    if (parsed.username) {
+      sanitized = sanitized.replaceAll(parsed.username, '****');
+    }
+    return sanitized;
+  } catch {
+    // For libpq-style strings, mask password and user values in the message
+    return message
+      .replace(/password\s*=\s*\S+/gi, 'password=****')
+      .replace(/user\s*=\s*\S+/gi, 'user=****');
+  }
+}
+
+/**
+ * Registers the global CLI options shared by every command:
+ * --json, -q/--quiet, -v/--verbose, --trace, --color, --no-color,
+ * --interactive, --no-interactive, -y/--yes.
+ *
+ * Also sets up the styled help formatter.
+ */
+export function addGlobalOptions(command: Command): Command {
+  return command
+    .configureHelp({
+      formatHelp: (cmd) => {
+        const flags = parseGlobalFlags({});
+        return formatCommandHelp({ command: cmd, flags });
+      },
+    })
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Quiet mode: errors only')
+    .option('-v, --verbose', 'Verbose output: debug info, timings')
+    .option('--trace', 'Trace output: deep internals, stack traces')
+    .option('--color', 'Force color output')
+    .option('--no-color', 'Disable color output')
+    .option('--interactive', 'Force interactive mode')
+    .option('--no-interactive', 'Disable interactive prompts')
+    .option('-y, --yes', 'Auto-accept prompts');
 }

package/src/utils/formatters/emit.ts

@@ -0,0 +1,67 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+import { relative } from 'pathe';
+
+import type { GlobalFlags } from '../global-flags';
+import { isVerbose } from './helpers';
+
+// EmitContractResult type for CLI output formatting (includes file paths)
+export interface EmitContractResult {
+  readonly storageHash: string;
+  readonly executionHash?: string;
+  readonly profileHash: string;
+  readonly outDir: string;
+  readonly files: {
+    readonly json: string;
+    readonly dts: string;
+  };
+  readonly timings: {
+    readonly total: number;
+  };
+}
+
+/**
+ * Formats human-readable output for contract emit.
+ */
+export function formatEmitOutput(result: EmitContractResult, flags: GlobalFlags): string {
+  if (flags.quiet) {
+    return '';
+  }
+
+  const lines: string[] = [];
+
+  // Convert absolute paths to relative paths from cwd
+  const jsonPath = relative(process.cwd(), result.files.json);
+  const dtsPath = relative(process.cwd(), result.files.dts);
+
+  lines.push(`✔ Emitted contract.json → ${jsonPath}`);
+  lines.push(`✔ Emitted contract.d.ts → ${dtsPath}`);
+  lines.push(`  storageHash: ${result.storageHash}`);
+  if (result.executionHash) {
+    lines.push(`  executionHash: ${result.executionHash}`);
+  }
+  if (result.profileHash) {
+    lines.push(`  profileHash: ${result.profileHash}`);
+  }
+  if (isVerbose(flags, 1)) {
+    lines.push(`  Total time: ${result.timings.total}ms`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats JSON output for contract emit.
+ */
+export function formatEmitJson(result: EmitContractResult): string {
+  const output = {
+    ok: true,
+    storageHash: result.storageHash,
+    ...ifDefined('executionHash', result.executionHash),
+    ...(result.profileHash ? { profileHash: result.profileHash } : {}),
+    outDir: result.outDir,
+    files: result.files,
+    timings: result.timings,
+  };
+
+  return JSON.stringify(output, null, 2);
+}

package/src/utils/formatters/errors.ts

@@ -0,0 +1,82 @@
+import { red } from 'colorette';
+
+import type { CliErrorConflict, CliErrorEnvelope } from '../cli-errors';
+import type { GlobalFlags } from '../global-flags';
+import { createColorFormatter, formatDim, isVerbose } from './helpers';
+
+/**
+ * Formats error output for human-readable display.
+ */
+export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags): string {
+  const lines: string[] = [];
+
+  const useColor = flags.color !== false;
+  const formatRed = createColorFormatter(useColor, red);
+  const formatDimText = (text: string) => formatDim(useColor, text);
+
+  lines.push(`${formatRed('✖')} ${error.summary} (${error.code})`);
+
+  if (error.why) {
+    lines.push(`${formatDimText(`  Why: ${error.why}`)}`);
+  }
+  if (error.fix) {
+    lines.push(`${formatDimText(`  Fix: ${error.fix}`)}`);
+  }
+  if (error.where?.path) {
+    const whereLine = error.where.line
+      ? `${error.where.path}:${error.where.line}`
+      : error.where.path;
+    lines.push(`${formatDimText(`  Where: ${whereLine}`)}`);
+  }
+  // Show conflicts list if present (always show a short list; show full list when verbose)
+  if (error.meta?.['conflicts']) {
+    const conflicts = error.meta['conflicts'] as readonly CliErrorConflict[];
+    if (conflicts.length > 0) {
+      const maxToShow = isVerbose(flags, 1) ? conflicts.length : Math.min(3, conflicts.length);
+      const header = isVerbose(flags, 1)
+        ? '  Conflicts:'
+        : `  Conflicts (showing ${maxToShow} of ${conflicts.length}):`;
+      lines.push(`${formatDimText(header)}`);
+      for (const conflict of conflicts.slice(0, maxToShow)) {
+        lines.push(`${formatDimText(`    - [${conflict.kind}] ${conflict.summary}`)}`);
+      }
+      if (!isVerbose(flags, 1) && conflicts.length > maxToShow) {
+        lines.push(`${formatDimText('  Re-run with -v/--verbose to see all conflicts')}`);
+      }
+    }
+  }
+  // Show issues list if present (always show a short list; show full list when verbose)
+  if (error.meta?.['issues']) {
+    const issues = error.meta['issues'] as readonly { kind?: string; message?: string }[];
+    if (issues.length > 0) {
+      const maxToShow = isVerbose(flags, 1) ? issues.length : Math.min(3, issues.length);
+      const header = isVerbose(flags, 1)
+        ? '  Issues:'
+        : `  Issues (showing ${maxToShow} of ${issues.length}):`;
+      lines.push(`${formatDimText(header)}`);
+      for (const issue of issues.slice(0, maxToShow)) {
+        const kind = issue.kind ?? 'issue';
+        const message = issue.message ?? '';
+        lines.push(`${formatDimText(`    - [${kind}] ${message}`)}`);
+      }
+      if (!isVerbose(flags, 1) && issues.length > maxToShow) {
+        lines.push(`${formatDimText('  Re-run with -v/--verbose to see all issues')}`);
+      }
+    }
+  }
+  if (error.docsUrl && isVerbose(flags, 1)) {
+    lines.push(formatDimText(error.docsUrl));
+  }
+  if (isVerbose(flags, 2) && error.meta) {
+    lines.push(`${formatDimText(`  Meta: ${JSON.stringify(error.meta, null, 2)}`)}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats error output as JSON.
+ */
+export function formatErrorJson(error: CliErrorEnvelope): string {
+  return JSON.stringify(error, null, 2);
+}