@prisma-next/cli 0.3.0-dev.12 → 0.3.0-dev.122

package/src/utils/global-flags.ts

@@ -1,42 +1,49 @@
 export interface GlobalFlags {
-  readonly json?: 'object' | 'ndjson';
+  readonly json?: boolean;
   readonly quiet?: boolean;
   readonly verbose?: number; // 0, 1, or 2
-  readonly timestamps?: boolean;
   readonly color?: boolean;
+  readonly interactive?: boolean;
+  readonly yes?: boolean;
 }
 
-export interface CliOptions {
+/**
+ * Common options parsed by Commander.js for every command.
+ * Extend this for command-specific options instead of duplicating these fields.
+ */
+export interface CommonCommandOptions {
   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;
+  readonly interactive?: boolean;
+  readonly 'no-interactive'?: boolean;
+  readonly yes?: boolean;
+  readonly y?: boolean;
 }
 
 /**
  * Parses global flags from CLI options.
- * Handles verbosity flags (-v, -vv, --trace), JSON output, quiet mode, timestamps, and color.
+ * Handles verbosity flags (-v, --trace), JSON output, quiet mode, color,
+ * interactivity (--interactive/--no-interactive), and auto-accept (-y/--yes).
  */
-export function parseGlobalFlags(options: CliOptions): GlobalFlags {
+export function parseGlobalFlags(options: CommonCommandOptions): GlobalFlags {
   const flags: {
-    json?: 'object' | 'ndjson';
+    json?: boolean;
     quiet?: boolean;
     verbose?: number;
-    timestamps?: boolean;
     color?: boolean;
+    interactive?: boolean;
+    yes?: boolean;
   } = {};
 
-  // JSON output
-  if (options.json === true || options.json === 'object') {
-    flags.json = 'object';
-  } else if (options.json === 'ndjson') {
-    flags.json = 'ndjson';
+  // JSON output: explicit --json flag or auto-detect piped stdout (Unix convention)
+  if (options.json || !process.stdout.isTTY) {
+    flags.json = true;
   }
 
   // Quiet mode
@@ -44,22 +51,18 @@ export function parseGlobalFlags(options: CliOptions): GlobalFlags {
     flags.quiet = true;
   }
 
-  // Verbosity: -v = 1, -vv or --trace = 2
-  if (options.vv || options.trace) {
+  // Verbosity: -v = 1, --trace = 2
+  // Env toggles: PRISMA_NEXT_TRACE=1 ≅ --trace, PRISMA_NEXT_DEBUG=1 ≅ -v
+  if (options.trace || process.env['PRISMA_NEXT_TRACE'] === '1') {
     flags.verbose = 2;
-  } else if (options.verbose || options.v) {
+  } else if (options.verbose || options.v || process.env['PRISMA_NEXT_DEBUG'] === '1') {
     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
+  // When JSON output is enabled, disable color to ensure clean JSON output
   if (process.env['NO_COLOR'] || flags.json) {
     flags.color = false;
   } else if (options['no-color']) {
@@ -71,5 +74,20 @@ export function parseGlobalFlags(options: CliOptions): GlobalFlags {
     flags.color = process.stdout.isTTY && !process.env['CI'];
   }
 
+  // Interactivity: --interactive/--no-interactive
+  // Default: interactive when stdout is a TTY
+  if (options['no-interactive']) {
+    flags.interactive = false;
+  } else if (options.interactive !== undefined) {
+    flags.interactive = options.interactive;
+  } else {
+    flags.interactive = !!process.stdout.isTTY;
+  }
+
+  // Auto-accept prompts: -y/--yes
+  if (options.yes || options.y) {
+    flags.yes = true;
+  }
+
   return flags as GlobalFlags;
 }

package/src/utils/migration-command-scaffold.ts

@@ -0,0 +1,187 @@
+import { readFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import type { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import { createControlClient } from '../control-api/client';
+import type { ControlClient } from '../control-api/types';
+import {
+  type CliStructuredError,
+  errorContractValidationFailed,
+  errorDatabaseConnectionRequired,
+  errorDriverRequired,
+  errorFileNotFound,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+} from './cli-errors';
+import { addGlobalOptions, maskConnectionUrl, resolveContractPath } from './command-helpers';
+import { formatStyledHeader } from './formatters/styled';
+import type { GlobalFlags } from './global-flags';
+import { createProgressAdapter } from './progress-adapter';
+import type { TerminalUI } from './terminal-ui';
+
+/**
+ * Resolved context for a migration command.
+ * Contains everything needed to invoke a control-api operation.
+ */
+export interface MigrationContext {
+  readonly client: ControlClient;
+  readonly contractJson: Record<string, unknown>;
+  readonly dbConnection: unknown;
+  readonly onProgress: ReturnType<typeof createProgressAdapter>;
+  readonly configPath: string;
+  readonly contractPath: string;
+  readonly contractPathAbsolute: string;
+  readonly config: Awaited<ReturnType<typeof loadConfig>>;
+}
+
+/**
+ * Command-specific configuration for the shared scaffold.
+ */
+export interface MigrationCommandDescriptor {
+  readonly commandName: string;
+  readonly description: string;
+  readonly url: string;
+}
+
+/**
+ * Prepares the shared context for migration commands (db init, db update).
+ *
+ * Handles: config loading, contract file reading, JSON parsing, connection resolution,
+ * driver/migration-support validation, client creation, and header output.
+ *
+ * Returns a Result with either the resolved context or a structured error.
+ */
+export async function prepareMigrationContext(
+  options: { readonly db?: string; readonly config?: string; readonly dryRun?: boolean },
+  flags: GlobalFlags,
+  ui: TerminalUI,
+  descriptor: MigrationCommandDescriptor,
+): Promise<Result<MigrationContext, CliStructuredError>> {
+  // Load config
+  const config = await loadConfig(options.config);
+  const configPath = options.config
+    ? relative(process.cwd(), resolve(options.config))
+    : 'prisma-next.config.ts';
+  const contractPathAbsolute = resolveContractPath(config);
+  const contractPath = relative(process.cwd(), contractPathAbsolute);
+
+  // Output header to stderr (decoration)
+  if (!flags.json && !flags.quiet) {
+    const details: Array<{ label: string; value: string }> = [
+      { label: 'config', value: configPath },
+      { label: 'contract', value: contractPath },
+    ];
+    if (options.db) {
+      details.push({ label: 'database', value: maskConnectionUrl(options.db) });
+    }
+    if (options.dryRun) {
+      details.push({ label: 'mode', value: 'dry run' });
+    }
+    const header = formatStyledHeader({
+      command: descriptor.commandName,
+      description: descriptor.description,
+      url: descriptor.url,
+      details,
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  // Load contract file
+  let contractJsonContent: string;
+  try {
+    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+      return notOk(
+        errorFileNotFound(contractPathAbsolute, {
+          why: `Contract file not found at ${contractPathAbsolute}`,
+          fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`,
+        }),
+      );
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  // Parse contract JSON
+  let contractJson: Record<string, unknown>;
+  try {
+    contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
+  } catch (error) {
+    return notOk(
+      errorContractValidationFailed(
+        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
+  }
+
+  // Resolve database connection (--db flag or config.db.connection)
+  const dbConnection = options.db ?? config.db?.connection;
+  if (!dbConnection) {
+    return notOk(
+      errorDatabaseConnectionRequired({
+        why: `Database connection is required for ${descriptor.commandName} (set db.connection in ${configPath}, or pass --db <url>)`,
+        commandName: descriptor.commandName,
+      }),
+    );
+  }
+
+  // Check for driver
+  if (!config.driver) {
+    return notOk(
+      errorDriverRequired({ why: `Config.driver is required for ${descriptor.commandName}` }),
+    );
+  }
+
+  // Check target supports migrations via optional descriptor capability
+  const targetWithMigrations = config.target as typeof config.target & {
+    readonly migrations?: unknown;
+  };
+  if (!targetWithMigrations.migrations) {
+    return notOk(
+      errorTargetMigrationNotSupported({
+        why: `Target "${config.target.id}" does not support migrations`,
+      }),
+    );
+  }
+
+  // Create control client
+  const client = createControlClient({
+    family: config.family,
+    target: config.target,
+    adapter: config.adapter,
+    driver: config.driver,
+    extensionPacks: config.extensionPacks ?? [],
+  });
+
+  // Create progress adapter
+  const onProgress = createProgressAdapter({ ui, flags });
+
+  return ok({
+    client,
+    contractJson,
+    dbConnection,
+    onProgress,
+    configPath,
+    contractPath,
+    contractPathAbsolute,
+    config,
+  });
+}
+
+/**
+ * Registers the shared CLI options for migration commands (db init, db update).
+ */
+export function addMigrationCommandOptions(command: Command): Command {
+  addGlobalOptions(command);
+  return command
+    .option('--db <url>', 'Database connection string')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .option('--dry-run', 'Preview planned operations without applying', false);
+}

package/src/utils/migration-types.ts

@@ -0,0 +1,12 @@
+export interface StatusRef {
+  readonly name: string;
+  readonly hash: string;
+  readonly active: boolean;
+}
+
+export interface StatusDiagnostic {
+  readonly code: string;
+  readonly severity: 'warn' | 'info';
+  readonly message: string;
+  readonly hints: readonly string[];
+}

package/src/utils/progress-adapter.ts

@@ -0,0 +1,75 @@
+import type { SpinnerResult } from '@clack/prompts';
+import type { ControlProgressEvent, OnControlProgress } from '../control-api/types';
+import type { GlobalFlags } from './global-flags';
+import type { TerminalUI } from './terminal-ui';
+
+/**
+ * Options for creating a progress adapter.
+ */
+interface ProgressAdapterOptions {
+  readonly ui: TerminalUI;
+  readonly flags: GlobalFlags;
+}
+
+/**
+ * State for tracking active spans in the progress adapter.
+ */
+interface SpanState {
+  readonly spinner: SpinnerResult;
+  readonly startTime: number;
+  readonly label: string;
+}
+
+/**
+ * Creates a progress adapter that converts control-api progress events
+ * into CLI spinner/progress output on stderr.
+ *
+ * The adapter:
+ * - Starts/succeeds spinners for top-level span boundaries
+ * - Prints per-operation lines for nested spans (e.g., migration operations under 'apply')
+ * - Respects quiet/json/non-TTY flags (no-op in those cases)
+ */
+export function createProgressAdapter(options: ProgressAdapterOptions): OnControlProgress {
+  const { ui, flags } = options;
+
+  // Skip progress if quiet, JSON output, or non-interactive
+  if (flags.quiet || flags.json || !ui.isInteractive) {
+    return () => {};
+  }
+
+  // Track active spans by spanId
+  const activeSpans = new Map<string, SpanState>();
+
+  return (event: ControlProgressEvent) => {
+    if (event.kind === 'spanStart') {
+      // Nested spans (with parentSpanId) are printed as step lines
+      if (event.parentSpanId) {
+        ui.step(`${event.label}...`);
+        return;
+      }
+
+      // Top-level spans get a spinner
+      const spinner = ui.spinner();
+      spinner.start(event.label);
+
+      activeSpans.set(event.spanId, {
+        spinner,
+        startTime: Date.now(),
+        label: event.label,
+      });
+    } else if (event.kind === 'spanEnd') {
+      const spanState = activeSpans.get(event.spanId);
+      if (spanState) {
+        const elapsed = Date.now() - spanState.startTime;
+        if (event.outcome === 'error') {
+          spanState.spinner.error(`${spanState.label} (failed)`);
+        } else if (event.outcome === 'skipped') {
+          spanState.spinner.stop(`${spanState.label} (skipped)`);
+        } else {
+          spanState.spinner.stop(`${spanState.label} (${elapsed}ms)`);
+        }
+        activeSpans.delete(event.spanId);
+      }
+    }
+  };
+}

package/src/utils/result-handler.ts

@@ -1,44 +1,43 @@
 import type { Result } from '@prisma-next/utils/result';
 import type { CliStructuredError } from './cli-errors';
+import { formatErrorJson, formatErrorOutput } from './formatters/errors';
 import type { GlobalFlags } from './global-flags';
-import { formatErrorJson, formatErrorOutput } from './output';
+import type { TerminalUI } from './terminal-ui';
 
 /**
  * Processes a CLI command result, handling both success and error cases.
  * Formats output appropriately and returns the exit code.
  * Never throws - returns exit code for commands to use with process.exit().
  *
- * @param result - The result from a CLI command
- * @param flags - Global flags for output formatting
- * @param onSuccess - Optional callback for successful results (for custom success output)
- * @returns The exit code that should be used (0 for success, non-zero for errors)
+ * Error output:
+ * - JSON mode: JSON error to stdout (piped) via ui.output(), human sees nothing on stderr.
+ * - Interactive: human-readable error to stderr.
  */
 export function handleResult<T>(
   result: Result<T, CliStructuredError>,
   flags: GlobalFlags,
+  ui: TerminalUI,
   onSuccess?: (value: T) => void,
 ): number {
   if (result.ok) {
-    // Success case
     if (onSuccess) {
       onSuccess(result.value);
     }
     return 0;
   }
 
-  // Error case - convert to CLI envelope
+  // Convert to CLI envelope
   const envelope = result.failure.toEnvelope();
 
-  // Output error based on flags
   if (flags.json) {
-    // JSON error to stderr
-    console.error(formatErrorJson(envelope));
+    // JSON error → stdout only
+    ui.output(formatErrorJson(envelope));
   } else {
-    // Human-readable error to stderr
-    console.error(formatErrorOutput(envelope, flags));
+    // Human-readable error → stderr
+    ui.error(formatErrorOutput(envelope, flags));
   }
 
-  // Infer exit code from error domain: CLI errors = 2, RTM errors = 1
+  // Infer exit code from error domain: CLI errors = 2, RUN errors = 1
   const exitCode = result.failure.domain === 'CLI' ? 2 : 1;
   return exitCode;
 }

package/src/utils/shutdown.ts

@@ -0,0 +1,92 @@
+/**
+ * Global shutdown controller for graceful SIGINT/SIGTERM handling.
+ *
+ * The CLI installs signal handlers once at startup. When a signal fires:
+ * 1. The AbortController is aborted — in-flight async work (DB queries, emit) can check `signal.aborted`.
+ * 2. A 3-second grace timer starts — gives `finally` blocks time to close connections.
+ * 3. If the process hasn't exited by then, force-exit with code 130 (128 + SIGINT).
+ * 4. A second signal during the grace period force-exits immediately.
+ */
+
+/**
+ * Creates a shutdown handler with its own AbortController.
+ * Exposed for testing — production code uses the singleton below.
+ */
+export interface ShutdownHandler {
+  readonly signal: AbortSignal;
+  readonly isShuttingDown: () => boolean;
+  readonly onSignal: () => void;
+  readonly clearGraceTimer: () => void;
+}
+
+export function createShutdownHandler(options?: {
+  readonly exit?: (code: number) => void;
+  readonly gracePeriodMs?: number;
+}): ShutdownHandler {
+  const exit = options?.exit ?? ((code: number) => process.exit(code));
+  const gracePeriodMs = options?.gracePeriodMs ?? 3000;
+
+  const controller = new AbortController();
+  let shuttingDown = false;
+  let graceTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const onSignal = () => {
+    if (shuttingDown) {
+      // Second signal — force exit
+      exit(130);
+      return;
+    }
+    shuttingDown = true;
+    controller.abort();
+
+    // Give finally blocks time to clean up, then force-exit
+    graceTimer = setTimeout(() => exit(130), gracePeriodMs);
+    graceTimer.unref();
+  };
+
+  return {
+    signal: controller.signal,
+    isShuttingDown: () => shuttingDown,
+    onSignal,
+    clearGraceTimer: () => {
+      if (graceTimer !== undefined) {
+        clearTimeout(graceTimer);
+        graceTimer = undefined;
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Singleton for production use
+// ---------------------------------------------------------------------------
+
+const globalHandler = createShutdownHandler();
+
+/**
+ * The global AbortSignal. Pass this to any async operation that should
+ * be cancellable on Ctrl+C (e.g., DB queries, long-running emit).
+ */
+export const shutdownSignal: AbortSignal = globalHandler.signal;
+
+/**
+ * Whether a shutdown has been initiated.
+ */
+export function isShuttingDown(): boolean {
+  return globalHandler.isShuttingDown();
+}
+
+/**
+ * Installs SIGINT and SIGTERM handlers. Call once at CLI startup.
+ *
+ * - First signal: aborts the controller, starts a 3s grace timer.
+ * - Second signal: force-exits immediately.
+ */
+let installed = false;
+
+export function installShutdownHandlers(): void {
+  if (installed) return;
+  installed = true;
+  process.on('SIGINT', globalHandler.onSignal);
+  process.on('SIGTERM', globalHandler.onSignal);
+}

package/src/utils/suggest-command.ts

@@ -0,0 +1,31 @@
+import { distance } from 'closest-match';
+
+/**
+ * Suggests similar command names for a mistyped input.
+ *
+ * Uses Levenshtein distance to find close matches. Only suggests commands
+ * within a reasonable distance threshold (40% of the input length, minimum 2).
+ * Returns up to 3 suggestions in case of ties.
+ *
+ * @returns Array of suggested command names (empty if nothing is close enough).
+ */
+export function suggestCommands(input: string, candidates: readonly string[]): string[] {
+  if (candidates.length === 0) return [];
+
+  // Threshold: at most 40% of the input length (min 2) to avoid absurd suggestions
+  const maxDistance = Math.max(2, Math.ceil(input.length * 0.4));
+
+  const scored = candidates
+    .map((name) => ({ name, dist: distance(input, name) }))
+    .filter((entry) => entry.dist <= maxDistance)
+    .sort((a, b) => a.dist - b.dist);
+
+  if (scored.length === 0) return [];
+
+  // Take the best distance, then include ties (up to 3)
+  const bestDist = scored[0]!.dist;
+  return scored
+    .filter((entry) => entry.dist === bestDist)
+    .slice(0, 3)
+    .map((entry) => entry.name);
+}