@sylphx/flow 3.16.0 → 3.17.0

package/src/utils/display/logger.ts

@@ -1,10 +1,9 @@
 /**
  * Centralized logging utility for Sylphx Flow
- * Provides structured logging with different levels and output formats
+ * Provides structured logging with Pino backend and pretty printing
  */
 
-import { randomUUID } from 'node:crypto';
-import chalk from 'chalk';
+import pino from 'pino';
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 
@@ -33,27 +32,6 @@ export interface LoggerConfig {
   module?: string;
 }
 
-const LEVEL_PRIORITY: Record<LogLevel, number> = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-};
-
-const LEVEL_COLORS: Record<LogLevel, (text: string) => string> = {
-  debug: chalk.gray,
-  info: chalk.blue,
-  warn: chalk.yellow,
-  error: chalk.red,
-};
-
-const LEVEL_SYMBOLS: Record<LogLevel, string> = {
-  debug: '🔍',
-  info: 'ℹ',
-  warn: '⚠',
-  error: '✗',
-};
-
 /**
  * Logger interface for dependency injection and testing
  */
@@ -76,6 +54,7 @@ export interface Logger {
 interface LoggerState {
   config: LoggerConfig;
   context?: Record<string, unknown>;
+  pinoInstance: pino.Logger;
 }
 
 /**
@@ -86,6 +65,49 @@ interface CreateLoggerOptions {
   context?: Record<string, unknown>;
 }
 
+/**
+ * Map our log levels to Pino levels
+ */
+const LEVEL_MAP: Record<LogLevel, string> = {
+  debug: 'debug',
+  info: 'info',
+  warn: 'warn',
+  error: 'error',
+};
+
+/**
+ * Create a Pino instance based on configuration
+ */
+function createPinoInstance(config: LoggerConfig, context?: Record<string, unknown>): pino.Logger {
+  const isProduction = process.env.NODE_ENV === 'production';
+  const usePretty = config.format === 'pretty' && !isProduction;
+
+  const pinoConfig: pino.LoggerOptions = {
+    level: config.level,
+    base: context ? { ...context } : undefined,
+    timestamp: config.includeTimestamp ? pino.stdTimeFunctions.isoTime : false,
+  };
+
+  if (usePretty) {
+    // Use pino-pretty for development
+    return pino({
+      ...pinoConfig,
+      transport: {
+        target: 'pino-pretty',
+        options: {
+          colorize: config.colors,
+          translateTime: 'HH:MM:ss',
+          ignore: 'pid,hostname',
+          messageFormat: '{msg}',
+        },
+      },
+    });
+  }
+
+  // JSON output for production or when format is 'json'
+  return pino(pinoConfig);
+}
+
 /**
  * Create a logger instance with the specified configuration and context
  */
@@ -97,152 +119,19 @@ export function createLogger(options: Partial<LoggerConfig> | CreateLoggerOption
     : (options as Partial<LoggerConfig>);
   const initialContext = isOptionsStyle ? (options as CreateLoggerOptions).context : undefined;
 
-  const state: LoggerState = {
-    config: {
-      level: 'info',
-      format: 'pretty',
-      includeTimestamp: true,
-      includeContext: true,
-      colors: true,
-      ...config,
-    },
-    context: initialContext,
-  };
-
-  /**
-   * Check if a log level should be output
-   */
-  const shouldLog = (level: LogLevel): boolean => {
-    return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[state.config.level];
-  };
-
-  /**
-   * Create a log entry
-   */
-  const createLogEntry = (
-    level: LogLevel,
-    message: string,
-    error?: Error,
-    additionalContext?: Record<string, unknown>
-  ): LogEntry => {
-    const entry: LogEntry = {
-      id: randomUUID(),
-      timestamp: new Date().toISOString(),
-      level,
-      message,
-      module: state.context?.module,
-      function: state.context?.function,
-    };
-
-    // Merge contexts
-    if (state.config.includeContext) {
-      entry.context = { ...state.context, ...additionalContext };
-    }
-
-    // Add error information if provided
-    if (error) {
-      entry.error = {
-        name: error.name,
-        message: error.message,
-        stack: error.stack,
-      };
-
-      // Add error code if it's a CLIError
-      if ('code' in error && typeof error.code === 'string') {
-        entry.error.code = error.code;
-      }
-    }
-
-    return entry;
-  };
-
-  /**
-   * Format a log entry for output
-   */
-  const formatEntry = (entry: LogEntry): string => {
-    switch (state.config.format) {
-      case 'json':
-        return JSON.stringify(entry);
-
-      case 'simple': {
-        const levelStr = entry.level.toUpperCase().padEnd(5);
-        const moduleStr = entry.module ? `[${entry.module}] ` : '';
-        return `${levelStr} ${moduleStr}${entry.message}`;
-      }
-      default: {
-        const parts: string[] = [];
-
-        // Timestamp
-        if (state.config.includeTimestamp) {
-          const time = new Date(entry.timestamp).toLocaleTimeString();
-          parts.push(chalk.gray(time));
-        }
-
-        // Level symbol and name
-        const colorFn = state.config.colors ? LEVEL_COLORS[entry.level] : (s: string) => s;
-        parts.push(
-          `${colorFn(LEVEL_SYMBOLS[entry.level])} ${colorFn(entry.level.toUpperCase().padEnd(5))}`
-        );
-
-        // Module
-        if (entry.module) {
-          parts.push(chalk.cyan(`[${entry.module}]`));
-        }
-
-        // Function
-        if (entry.function) {
-          parts.push(chalk.gray(`${entry.function}()`));
-        }
-
-        // Message
-        parts.push(entry.message);
-
-        let result = parts.join(' ');
-
-        // Context
-        if (entry.context && Object.keys(entry.context).length > 0) {
-          const contextStr = JSON.stringify(entry.context, null, 2);
-          result += `\n${chalk.gray('  Context: ')}${chalk.gray(contextStr)}`;
-        }
-
-        // Error details
-        if (entry.error) {
-          result += `\n${chalk.red('  Error: ')}${chalk.red(entry.error.message)}`;
-          if (entry.error.code) {
-            result += `\n${chalk.red('  Code: ')}${chalk.red(entry.error.code)}`;
-          }
-          if (entry.error.stack) {
-            result += `\n${chalk.gray(entry.error.stack)}`;
-          }
-        }
-
-        return result;
-      }
-    }
+  const defaultConfig: LoggerConfig = {
+    level: 'info',
+    format: 'pretty',
+    includeTimestamp: true,
+    includeContext: true,
+    colors: true,
+    ...config,
   };
 
-  /**
-   * Internal logging method
-   */
-  const logInternal = (
-    level: LogLevel,
-    message: string,
-    error?: Error,
-    additionalContext?: Record<string, any>
-  ): void => {
-    if (!shouldLog(level)) {
-      return;
-    }
-
-    const entry = createLogEntry(level, message, error, additionalContext);
-    const formatted = formatEntry(entry);
-
-    // Output to appropriate stream
-    if (level === 'error') {
-      console.error(formatted);
-    } else {
-      console.log(formatted);
-    }
+  const state: LoggerState = {
+    config: defaultConfig,
+    context: initialContext,
+    pinoInstance: createPinoInstance(defaultConfig, initialContext),
   };
 
   /**
@@ -267,41 +156,75 @@ export function createLogger(options: Partial<LoggerConfig> | CreateLoggerOption
    */
   const setLevel = (level: LogLevel): void => {
     state.config.level = level;
+    state.pinoInstance.level = level;
   };
 
   /**
    * Update logger configuration
+   * Note: Recreates Pino instance when configuration changes
    */
   const updateConfig = (config: Partial<LoggerConfig>): void => {
     state.config = { ...state.config, ...config };
+    state.pinoInstance = createPinoInstance(state.config, state.context);
   };
 
   /**
    * Debug level logging
    */
   const debug = (message: string, context?: Record<string, unknown>): void => {
-    logInternal('debug', message, undefined, context);
+    if (context && state.config.includeContext) {
+      state.pinoInstance.debug(context, message);
+    } else {
+      state.pinoInstance.debug(message);
+    }
   };
 
   /**
    * Info level logging
    */
   const info = (message: string, context?: Record<string, unknown>): void => {
-    logInternal('info', message, undefined, context);
+    if (context && state.config.includeContext) {
+      state.pinoInstance.info(context, message);
+    } else {
+      state.pinoInstance.info(message);
+    }
   };
 
   /**
    * Warning level logging
    */
   const warn = (message: string, context?: Record<string, unknown>): void => {
-    logInternal('warn', message, undefined, context);
+    if (context && state.config.includeContext) {
+      state.pinoInstance.warn(context, message);
+    } else {
+      state.pinoInstance.warn(message);
+    }
   };
 
   /**
    * Error level logging
    */
   const error = (message: string, errorObj?: Error, context?: Record<string, unknown>): void => {
-    logInternal('error', message, errorObj, context);
+    const errorContext: Record<string, unknown> = { ...context };
+
+    if (errorObj) {
+      errorContext.err = {
+        name: errorObj.name,
+        message: errorObj.message,
+        stack: errorObj.stack,
+      };
+
+      // Add error code if it's a CLIError
+      if ('code' in errorObj && typeof errorObj.code === 'string') {
+        (errorContext.err as Record<string, unknown>).code = errorObj.code;
+      }
+    }
+
+    if (Object.keys(errorContext).length > 0 && state.config.includeContext) {
+      state.pinoInstance.error(errorContext, message);
+    } else {
+      state.pinoInstance.error(message);
+    }
   };
 
   /**

package/src/utils/prompt-helpers.ts

@@ -1,16 +1,27 @@
 /**
  * Prompt Helpers
  * Utilities for handling user prompts and error handling
+ *
+ * This module provides backward-compatible error handling that works with
+ * both legacy inquirer errors and the new Clack cancellation pattern.
  */
 
+import { isCancel } from '@clack/prompts';
 import { UserCancelledError } from './errors.js';
 
 /**
  * Check if error is a user cancellation (Ctrl+C or force closed)
- * @param error - Error to check
+ * Supports both legacy inquirer errors and Clack cancellation symbols
+ * @param error - Error or symbol to check
  * @returns True if error represents user cancellation
  */
 export function isUserCancellation(error: unknown): boolean {
+  // Handle Clack cancellation symbol
+  if (isCancel(error)) {
+    return true;
+  }
+
+  // Handle legacy inquirer errors
   if (error === null || typeof error !== 'object') {
     return false;
   }
@@ -19,9 +30,9 @@ export function isUserCancellation(error: unknown): boolean {
 }
 
 /**
- * Handle inquirer prompt errors with consistent error handling
+ * Handle inquirer/clack prompt errors with consistent error handling
  * Throws UserCancelledError for user cancellations, re-throws other errors
- * @param error - Error from inquirer prompt
+ * @param error - Error from prompt
  * @param message - Custom cancellation message
  * @throws {UserCancelledError} If user cancelled the prompt
  * @throws Original error if not a cancellation
@@ -34,8 +45,8 @@ export function handlePromptError(error: unknown, message: string): never {
 }
 
 /**
- * Wrap an inquirer prompt with consistent error handling
- * @param promptFn - Function that returns a promise from inquirer
+ * Wrap a prompt with consistent error handling
+ * @param promptFn - Function that returns a promise from a prompt library
  * @param errorMessage - Message to use if user cancels
  * @returns Promise with the prompt result
  * @throws {UserCancelledError} If user cancels the prompt

package/src/utils/prompts/index.ts

@@ -0,0 +1,232 @@
+/**
+ * Centralized Clack Prompts Wrapper
+ * Unified prompt utilities with consistent error handling and cancellation support
+ */
+
+import * as clack from '@clack/prompts';
+import chalk from 'chalk';
+import { UserCancelledError } from '../errors.js';
+
+// Re-export clack utilities for convenience
+export { cancel, group, intro, isCancel, log, note, outro } from '@clack/prompts';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SelectOption<T> {
+  label: string;
+  value: T;
+  hint?: string;
+}
+
+export interface MultiselectOption<T> {
+  label: string;
+  value: T;
+  hint?: string;
+}
+
+export interface SpinnerInstance {
+  start: (message?: string) => void;
+  stop: (message?: string) => void;
+  message: (message: string) => void;
+}
+
+// ============================================================================
+// Cancellation Handling
+// ============================================================================
+
+/**
+ * Handle cancellation by checking if result is a cancel symbol
+ * Throws UserCancelledError if cancelled
+ */
+export function handleCancellation<T>(
+  result: T | symbol,
+  message = 'Operation cancelled'
+): asserts result is T {
+  if (clack.isCancel(result)) {
+    clack.cancel(message);
+    throw new UserCancelledError(message);
+  }
+}
+
+/**
+ * Wrap a prompt result with automatic cancellation handling
+ */
+export function withCancellation<T>(result: T | symbol, message = 'Operation cancelled'): T {
+  handleCancellation(result, message);
+  return result;
+}
+
+// ============================================================================
+// Prompt Wrappers with Cancellation Handling
+// ============================================================================
+
+/**
+ * Select prompt with automatic cancellation handling
+ */
+export async function promptSelect<T extends string | number | boolean>(options: {
+  message: string;
+  options: SelectOption<T>[];
+  initialValue?: T;
+}): Promise<T> {
+  const result = await clack.select({
+    message: options.message,
+    options: options.options,
+    initialValue: options.initialValue,
+  });
+
+  handleCancellation(result, 'Selection cancelled');
+  return result as T;
+}
+
+/**
+ * Multiselect prompt with automatic cancellation handling
+ */
+export async function promptMultiselect<T extends string | number | boolean>(options: {
+  message: string;
+  options: MultiselectOption<T>[];
+  initialValues?: T[];
+  required?: boolean;
+}): Promise<T[]> {
+  const result = await clack.multiselect({
+    message: options.message,
+    options: options.options,
+    initialValues: options.initialValues,
+    required: options.required ?? false,
+  });
+
+  handleCancellation(result, 'Selection cancelled');
+  return result as T[];
+}
+
+/**
+ * Confirm prompt with automatic cancellation handling
+ */
+export async function promptConfirm(options: {
+  message: string;
+  initialValue?: boolean;
+}): Promise<boolean> {
+  const result = await clack.confirm({
+    message: options.message,
+    initialValue: options.initialValue ?? true,
+  });
+
+  handleCancellation(result, 'Confirmation cancelled');
+  return result;
+}
+
+/**
+ * Text input prompt with automatic cancellation handling
+ */
+export async function promptText(options: {
+  message: string;
+  placeholder?: string;
+  defaultValue?: string;
+  validate?: (value: string) => string | undefined;
+}): Promise<string> {
+  const result = await clack.text({
+    message: options.message,
+    placeholder: options.placeholder,
+    defaultValue: options.defaultValue,
+    validate: options.validate,
+  });
+
+  handleCancellation(result, 'Input cancelled');
+  return result;
+}
+
+/**
+ * Password input prompt with automatic cancellation handling
+ */
+export async function promptPassword(options: {
+  message: string;
+  mask?: string;
+  validate?: (value: string) => string | undefined;
+}): Promise<string> {
+  const result = await clack.password({
+    message: options.message,
+    mask: options.mask ?? '*',
+    validate: options.validate,
+  });
+
+  handleCancellation(result, 'Password input cancelled');
+  return result;
+}
+
+// ============================================================================
+// Spinner Wrapper
+// ============================================================================
+
+/**
+ * Create a spinner instance with consistent API
+ * Wraps Clack's spinner with additional convenience methods
+ */
+export function createSpinner(): SpinnerInstance {
+  const s = clack.spinner();
+
+  return {
+    start: (message?: string) => s.start(message),
+    stop: (message?: string) => s.stop(message),
+    message: (message: string) => s.message(message),
+  };
+}
+
+/**
+ * Run an async operation with a spinner
+ */
+export async function withSpinner<T>(
+  message: string,
+  fn: () => Promise<T>,
+  options?: {
+    successMessage?: string | ((result: T) => string);
+    errorMessage?: string | ((error: Error) => string);
+  }
+): Promise<T> {
+  const s = clack.spinner();
+  s.start(message);
+
+  try {
+    const result = await fn();
+    const successMsg =
+      typeof options?.successMessage === 'function'
+        ? options.successMessage(result)
+        : (options?.successMessage ?? message);
+    s.stop(chalk.green(`✓ ${successMsg}`));
+    return result;
+  } catch (error) {
+    const errorMsg =
+      typeof options?.errorMessage === 'function'
+        ? options.errorMessage(error as Error)
+        : (options?.errorMessage ?? `Failed: ${message}`);
+    s.stop(chalk.red(`✗ ${errorMsg}`));
+    throw error;
+  }
+}
+
+// ============================================================================
+// Group Prompts with Cancellation
+// ============================================================================
+
+/**
+ * Group multiple prompts together with shared cancellation handling
+ * If any prompt is cancelled, the entire group is cancelled
+ */
+export async function promptGroup<T extends Record<string, unknown>>(
+  prompts: {
+    [K in keyof T]: () => Promise<T[K] | symbol>;
+  },
+  options?: {
+    onCancel?: () => void;
+  }
+): Promise<T> {
+  const result = await clack.group(prompts, {
+    onCancel: () => {
+      options?.onCancel?.();
+      clack.cancel('Operation cancelled');
+      throw new UserCancelledError('Operation cancelled');
+    },
+  });
+
+  return result as T;
+}