@revealui/core 0.0.1-pre.0

package/dist/core/logging/UnifiedLoggerV2.ts

@@ -0,0 +1,555 @@
+/**
+ * Unified Logger V2
+ *
+ * Plugin-based unified logger that combines features from:
+ * - Infrastructure UnifiedLogger (PayloadCMS integration, TTY detection)
+ * - Core UnifiedLogger (file/remote logging, metrics)
+ *
+ * This is the new unified logger implementation with plugin architecture.
+ */
+
+import type { BaseLogContext, LogContext, LogMetadata } from '../types/contracts';
+
+// ======
+// TYPES
+// ======
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'success';
+
+// ======
+// TTY DETECTION & ANSI STRIPPING (from Infrastructure logger)
+// ======
+
+// Detect if output is redirected (not a TTY)
+const isTTY =
+  typeof process !== 'undefined' &&
+  (process.stdout?.isTTY ?? false) &&
+  (process.stderr?.isTTY ?? false);
+
+// Check environment variables for color control
+const shouldUseColors =
+  isTTY && process.env['NO_COLOR'] === undefined && process.env['FORCE_COLOR'] !== '0';
+
+/**
+ * Strip ANSI escape codes from text when output is redirected
+ */
+function stripAnsi(text: string): string {
+  if (shouldUseColors) return text;
+
+  // Remove standard ANSI escape sequences
+   
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences require control characters
+  let cleaned = text.replace(/\x1b\[[0-9;]*m/g, '');
+
+  // Remove cursor movement sequences
+   
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences require control characters
+  cleaned = cleaned.replace(/\x1b\[[0-9]*[ABCDEFGHJKSTfm]/g, '');
+
+  // Remove clear sequences
+   
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences require control characters
+  cleaned = cleaned.replace(/\x1b\[[0-9]*[KJ]/g, '');
+
+  // Remove other escape sequences
+   
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences require control characters
+  cleaned = cleaned.replace(/\x1b\[[?0-9;]*[hl]/g, '');
+
+  // Remove remaining escape sequences
+   
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences require control characters
+  cleaned = cleaned.replace(/\x1b\][0-9];.*?\x07/g, '');
+   
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequences require control characters
+  cleaned = cleaned.replace(/\x1b\].*?\x07/g, '');
+
+  return cleaned;
+}
+
+// Chalk-like styling (simplified, auto-strips when redirected)
+type ColorFn = (text: string) => string;
+const identity: ColorFn = x => x;
+
+const chalkLike = {
+  gray: shouldUseColors ? identity : (x: string) => stripAnsi(x),
+  blue: shouldUseColors ? identity : (x: string) => stripAnsi(x),
+  yellow: shouldUseColors ? identity : (x: string) => stripAnsi(x),
+  red: shouldUseColors ? identity : (x: string) => stripAnsi(x),
+  green: shouldUseColors ? identity : (x: string) => stripAnsi(x),
+  white: shouldUseColors ? identity : (x: string) => stripAnsi(x),
+  cyan: shouldUseColors ? identity : (x: string) => stripAnsi(x),
+  bold: Object.assign((shouldUseColors ? identity : (x: string) => stripAnsi(x)) as ColorFn, {
+    cyan: shouldUseColors ? identity : (((x: string) => stripAnsi(x)) as ColorFn),
+  }),
+};
+
+// Log level emojis and colors (from Infrastructure logger)
+const LOG_LEVEL_STYLES: Record<LogLevel, { emoji: string; color: ColorFn; name: string }> = {
+  debug: { emoji: '[SEARCH]', color: chalkLike.gray, name: 'DEBUG' },
+  info: { emoji: 'ℹ️', color: chalkLike.blue, name: 'INFO' },
+  warn: { emoji: '[WARNING]', color: chalkLike.yellow, name: 'WARN' },
+  error: { emoji: '[ERROR]', color: chalkLike.red, name: 'ERROR' },
+  success: { emoji: '[OK]', color: chalkLike.green, name: 'SUCCESS' },
+};
+
+export interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: Date;
+  context?: LogContext;
+  metadata?: LogMetadata;
+  service?: string;
+  operation?: string;
+  userId?: string;
+  requestId?: string;
+  duration?: number;
+  error?: Error;
+  data?: unknown;
+}
+
+export interface LoggerConfig {
+  level?: LogLevel;
+  enableConsole?: boolean;
+  plugins?: string[];
+  context?: BaseLogContext;
+  format?: 'json' | 'text' | 'structured';
+  includeStack?: boolean;
+  includeMetadata?: boolean;
+  // Seamless: allow passing context/service name directly
+  name?: string;
+}
+
+export interface LoggerPlugin {
+  name: string;
+  initialize(config: LoggerConfig): Promise<void> | void;
+  log(entry: LogEntry): Promise<void> | void;
+  cleanup?(): Promise<void> | void;
+}
+
+// ======
+// PLUGIN REGISTRY
+// ======
+
+const plugins = new Map<string, LoggerPlugin>();
+
+/**
+ * Register a logger plugin
+ */
+export function registerPlugin(plugin: LoggerPlugin): void {
+  plugins.set(plugin.name, plugin);
+}
+
+/**
+ * Unregister a plugin
+ */
+export function unregisterPlugin(name: string): void {
+  plugins.delete(name);
+}
+
+/**
+ * Get a plugin by name
+ */
+export function getPlugin(name: string): LoggerPlugin | undefined {
+  return plugins.get(name);
+}
+
+// ======
+// UNIFIED LOGGER CLASS
+// ======
+
+export class UnifiedLoggerV2 {
+  private readonly config: Required<LoggerConfig>;
+  private readonly context: BaseLogContext;
+  private readonly enabledPlugins: LoggerPlugin[] = [];
+  private readonly logLevels: Record<LogLevel, number> = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    success: 1,
+  };
+  // In-memory log entries (from Infrastructure logger)
+  private static readonly entries: LogEntry[] = [];
+  private readonly contextName: string; // For compatibility with Infrastructure logger
+
+  /**
+   * Create a new UnifiedLoggerV2 instance
+   *
+   * @param nameOrConfig - Context/service name (string) or full config object
+   * @param config - Optional config if first param is a string
+   *
+   * @example
+   * ```typescript
+   * // Simple usage with just a name
+   * const logger = new UnifiedLoggerV2('MyService');
+   * logger.info('Message');
+   *
+   * // With config
+   * const logger = new UnifiedLoggerV2('MyService', { level: 'debug' });
+   *
+   * // Full config
+   * const logger = new UnifiedLoggerV2({ name: 'MyService', level: 'debug' });
+   * ```
+   */
+  constructor(nameOrConfig?: string | LoggerConfig, config?: Partial<LoggerConfig>) {
+    // Handle seamless API: if first param is a string, treat it as the name
+    let finalConfig: LoggerConfig;
+    if (typeof nameOrConfig === 'string') {
+      finalConfig = {
+        name: nameOrConfig,
+        ...config,
+      };
+    } else {
+      finalConfig = nameOrConfig || {};
+    }
+
+    this.config = {
+      name: finalConfig.name || (typeof nameOrConfig === 'string' ? nameOrConfig : 'Logger'),
+      level: finalConfig.level || 'info',
+      enableConsole: finalConfig.enableConsole ?? true,
+      plugins: finalConfig.plugins || [],
+      context: finalConfig.context || {},
+      format: finalConfig.format || 'structured',
+      includeStack: finalConfig.includeStack ?? true,
+      includeMetadata: finalConfig.includeMetadata ?? true,
+    };
+
+    // Set context name from config.name or existing context
+    const contextName =
+      finalConfig.name ||
+      (this.config.context.service as string) ||
+      (this.config.context.operation as string) ||
+      'app';
+
+    // Update context with the name
+    this.context = {
+      ...this.config.context,
+      service: contextName,
+    };
+    this.contextName = contextName;
+
+    // Auto-enable PayloadCMS plugin if available (unless explicitly disabled)
+    if (
+      this.config.plugins.length === 0 &&
+      typeof process !== 'undefined' &&
+      process.env.NODE_ENV !== 'test'
+    ) {
+      const payloadPlugin = plugins.get('payload');
+      if (payloadPlugin) {
+        this.config.plugins.push('payload');
+      }
+    }
+
+    // Initialize enabled plugins
+    for (const pluginName of this.config.plugins) {
+      const plugin = plugins.get(pluginName);
+      if (plugin) {
+        this.enabledPlugins.push(plugin);
+        plugin.initialize(this.config);
+      }
+    }
+  }
+
+  // ======
+  // CONTEXT MANAGEMENT
+  // ======
+
+  setContext(key: keyof BaseLogContext, value: unknown): void {
+    // Using Record<string, unknown> because log context structure varies by logger implementation and cannot be strictly typed
+    (
+      this
+        .context as /* Using Record<string, unknown> because log context structure varies by logger implementation and cannot be strictly typed */ Record<
+        string,
+        unknown
+      >
+    )[key] = value;
+  }
+
+  getContext(): BaseLogContext {
+    return { ...this.context };
+  }
+
+  createChild(context: Partial<BaseLogContext>): UnifiedLoggerV2 {
+    const childLogger = new UnifiedLoggerV2({
+      ...this.config,
+      context: { ...this.context, ...context },
+    });
+    return childLogger;
+  }
+
+  /**
+   * Create a child logger with a sub-context (compatibility with Infrastructure logger)
+   */
+  child(sub: string, config?: Partial<LoggerConfig>): UnifiedLoggerV2 {
+    return new UnifiedLoggerV2({
+      ...this.config,
+      ...config,
+      context: { ...this.context, service: `${this.contextName}:${sub}` },
+    });
+  }
+
+  /**
+   * Create a logger for a specific service (compatibility with Infrastructure logger)
+   */
+  forService(serviceName: string, config?: Partial<LoggerConfig>): UnifiedLoggerV2 {
+    return new UnifiedLoggerV2({
+      ...this.config,
+      ...config,
+      context: { ...this.context, service: serviceName },
+    });
+  }
+
+  // ======
+  // LOGGING METHODS
+  // ======
+
+  /**
+   * Log debug message
+   * Seamless API: accepts message and optional data (matches Infrastructure logger)
+   */
+  debug(message: string, data?: unknown): void {
+    this.log('debug', message, undefined, undefined, data);
+  }
+
+  /**
+   * Log info message
+   * Seamless API: accepts message and optional data (matches Infrastructure logger)
+   */
+  info(message: string, data?: unknown): void {
+    this.log('info', message, undefined, undefined, data);
+  }
+
+  /**
+   * Log warning message
+   * Seamless API: accepts message and optional data (matches Infrastructure logger)
+   */
+  warn(message: string, data?: unknown): void {
+    this.log('warn', message, undefined, undefined, data);
+  }
+
+  /**
+   * Log error message
+   * Seamless API: accepts message and optional error/data (matches Infrastructure logger)
+   */
+  error(message: string, error?: Error | unknown, data?: unknown): void {
+    const err = error instanceof Error ? error : undefined;
+    const errorData = error instanceof Error ? data : error;
+    this.log('error', message, undefined, err, errorData);
+  }
+
+  /**
+   * Log success message
+   * Seamless API: accepts message and optional data (matches Infrastructure logger)
+   */
+  success(message: string, data?: unknown): void {
+    this.log('success', message, undefined, undefined, data);
+  }
+
+  /**
+   * Log progress message
+   * Seamless API: matches Infrastructure logger
+   */
+  progress(message: string): void {
+    this.log('info', `[...] ${message}`);
+  }
+
+  // ======
+  // CORE LOGGING LOGIC
+  // ======
+
+  private log(
+    level: LogLevel,
+    message: string,
+    context?: LogContext,
+    error?: Error,
+    data?: unknown
+  ): void {
+    // Check if log level is enabled
+    if (!this.isLevelEnabled(level)) {
+      return;
+    }
+
+    // Create log entry
+    const logEntry: LogEntry = {
+      level,
+      message,
+      timestamp: new Date(),
+      context: { ...this.context, ...context },
+      ...(this.context.service ? { service: this.context.service as string } : {}),
+      ...(this.context.operation ? { operation: this.context.operation as string } : {}),
+      ...(this.context.userId ? { userId: this.context.userId as string } : {}),
+      ...(this.context.requestId ? { requestId: this.context.requestId as string } : {}),
+      ...(error ? { error } : {}),
+      ...(data ? { data } : {}),
+    };
+
+    // Store in-memory entries (from Infrastructure logger)
+    UnifiedLoggerV2.entries.push(logEntry);
+    // Keep only last 1000 entries to prevent memory issues
+    if (UnifiedLoggerV2.entries.length > 1000) {
+      UnifiedLoggerV2.entries.shift();
+    }
+
+    // Output to console if enabled
+    if (this.config.enableConsole) {
+      this.logToConsole(logEntry);
+    }
+
+    // Output to plugins
+    for (const plugin of this.enabledPlugins) {
+      try {
+        plugin.log(logEntry);
+      } catch (pluginError) {
+        // Don't let plugin errors break logging
+        console.error(`Plugin ${plugin.name} error:`, pluginError);
+      }
+    }
+  }
+
+  // ======
+  // CONSOLE LOGGING
+  // ======
+
+  private logToConsole(entry: LogEntry): void {
+    const formatted = this.formatLogEntry(entry);
+
+    switch (entry.level) {
+      case 'error':
+        console.error(formatted);
+        break;
+      case 'warn':
+        console.warn(formatted);
+        break;
+      case 'debug':
+        console.debug(formatted);
+        break;
+      case 'success':
+        console.log(formatted);
+        break;
+      default:
+        console.log(formatted);
+    }
+  }
+
+  private formatLogEntry(entry: LogEntry): string {
+    if (this.config.format === 'json') {
+      return JSON.stringify(entry, null, 2);
+    }
+
+    const style = LOG_LEVEL_STYLES[entry.level];
+    const emoji = style.emoji;
+    const levelText = style.name;
+    const levelColor = style.color;
+    const context = this.contextName;
+    const message = entry.message;
+    const dataStr = entry.data ? ` ${JSON.stringify(entry.data, null, 2)}` : '';
+    const error = entry.error ? `\nError: ${entry.error.message}` : '';
+    const stack = entry.error && this.config.includeStack ? `\n${entry.error.stack}` : '';
+
+    // Format similar to Infrastructure logger
+    const formatted =
+      `${emoji} ${levelText} [${context}] ${message}${dataStr}${error}${stack}`.trim();
+
+    // Apply color and strip ANSI if needed
+    const colored = levelColor(formatted);
+    return shouldUseColors ? colored : stripAnsi(colored);
+  }
+
+  // ======
+  // IN-MEMORY ENTRIES (from Infrastructure logger)
+  // ======
+
+  /**
+   * Get all log entries
+   */
+  static getEntries(): LogEntry[] {
+    return [...UnifiedLoggerV2.entries];
+  }
+
+  /**
+   * Clear all log entries
+   */
+  static clearEntries(): void {
+    UnifiedLoggerV2.entries.length = 0;
+  }
+
+  /**
+   * Get entries for this logger instance
+   */
+  getEntries(): LogEntry[] {
+    return UnifiedLoggerV2.entries.filter(
+      entry => entry.service === this.contextName || entry.context?.service === this.contextName
+    );
+  }
+
+  // ======
+  // UTILITY METHODS
+  // ======
+
+  private isLevelEnabled(level: LogLevel): boolean {
+    const currentLevel = this.logLevels[this.config.level];
+    const messageLevel = this.logLevels[level];
+    return messageLevel >= currentLevel;
+  }
+
+  /**
+   * Cleanup resources
+   */
+  async cleanup(): Promise<void> {
+    for (const plugin of this.enabledPlugins) {
+      if (plugin.cleanup) {
+        try {
+          await plugin.cleanup();
+        } catch (error) {
+          console.error(`Plugin ${plugin.name} cleanup error:`, error);
+        }
+      }
+    }
+  }
+}
+
+// ======
+// FACTORY FUNCTION
+// ======
+
+/**
+ * Create a new logger instance
+ * Seamless API: accepts name (string) or config object
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * const logger = createLogger('MyService');
+ * logger.info('Message');
+ *
+ * // With config
+ * const logger = createLogger('MyService', { level: 'debug' });
+ *
+ * // Full config
+ * const logger = createLogger({ name: 'MyService', level: 'debug' });
+ * ```
+ */
+export function createLogger(
+  nameOrConfig?: string | LoggerConfig,
+  config?: Partial<LoggerConfig>
+): UnifiedLoggerV2 {
+  return new UnifiedLoggerV2(nameOrConfig, config);
+}
+
+// ======
+// SINGLETON INSTANCE (for backward compatibility)
+// ======
+
+let singletonInstance: UnifiedLoggerV2 | null = null;
+
+/**
+ * Get singleton logger instance
+ */
+export function getLogger(nameOrConfig?: string | LoggerConfig): UnifiedLoggerV2 {
+  if (!singletonInstance) {
+    singletonInstance = new UnifiedLoggerV2(nameOrConfig);
+  }
+  return singletonInstance;
+}
+

package/dist/core/logging/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Unified Logging Module
+ *
+ * Seamless logging API - UnifiedLoggerV2 works directly with simple name strings.
+ * No compatibility adapters needed - the logger is designed to work seamlessly.
+ */
+
+export {
+  UnifiedLoggerV2,
+  UnifiedLoggerV2 as UnifiedLogger, // Alias for convenience
+  createLogger,
+  getLogger,
+  registerPlugin,
+  unregisterPlugin,
+  getPlugin,
+  type LogLevel,
+  type LogEntry,
+  type LoggerConfig,
+  type LoggerPlugin,
+} from './UnifiedLoggerV2';
+
+export * from './plugins';
+
+// ======
+// CONVENIENCE FUNCTIONS (not compatibility adapters - just convenience)
+// ======
+
+import { createLogger as createLoggerInternal, getPlugin, registerPlugin } from './UnifiedLoggerV2';
+import type { LoggerConfig, UnifiedLoggerV2 } from './UnifiedLoggerV2';
+import type { PayloadCMSPlugin } from './plugins/PayloadCMSPlugin';
+
+// Register default plugins
+import { PayloadCMSPlugin as PayloadPlugin } from './plugins/PayloadCMSPlugin';
+
+// Auto-register PayloadCMS plugin
+registerPlugin(new PayloadPlugin());
+
+/**
+ * Create a logger with a context/service name
+ * This is a convenience function - you can also use createLogger() directly
+ *
+ * @example
+ * ```typescript
+ * import { createContextLogger } from '@revealui/core/core/logging';
+ * const logger = createContextLogger('MyService');
+ * logger.info('Message');
+ * ```
+ */
+export function createContextLogger(name: string, config?: Partial<LoggerConfig>): UnifiedLoggerV2 {
+  return createLoggerInternal(name, config);
+}
+
+/**
+ * Create a logger for a service
+ * This is a convenience function - you can also use createLogger() directly
+ *
+ * @example
+ * ```typescript
+ * import { createServiceLogger } from '@revealui/core/core/logging';
+ * const logger = createServiceLogger('MyService');
+ * logger.info('Message');
+ * ```
+ */
+export function createServiceLogger(name: string, config?: Partial<LoggerConfig>): UnifiedLoggerV2 {
+  return createLoggerInternal(name, config);
+}
+
+/**
+ * Initialize PayloadCMS integration for logging
+ * Call this once during app initialization
+ */
+export function initializeUnifiedLogging(payloadLike: {
+  logger?: Record<string, (msg: string, data?: unknown) => void>;
+}): void {
+  const payloadPlugin = getPlugin('payload') as PayloadCMSPlugin | undefined;
+  if (payloadPlugin) {
+    payloadPlugin.setPayloadLike(payloadLike);
+  }
+}
+