@prisma-next/cli 0.3.0-pr.99.6 → 0.3.0

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);
+}