ralphblaster-agent 0.1.1

package/src/logging/destinations/base-destination.js

@@ -0,0 +1,85 @@
+/**
+ * BaseDestination - Abstract base class for log destinations
+ *
+ * Defines the common interface that all log destinations must implement.
+ * Each destination handles writing logs to a specific output (console, file, API, etc.)
+ * and manages its own lifecycle (initialization, flushing, cleanup).
+ *
+ * Destinations are pluggable and independent - they can be added or removed without
+ * affecting other destinations.
+ */
+class BaseDestination {
+  /**
+   * Create a new log destination
+   * @param {Object} [config={}] - Destination-specific configuration
+   */
+  constructor(config = {}) {
+    this.config = config;
+    this.isShuttingDown = false;
+  }
+
+  /**
+   * Write a log entry to this destination
+   * Must be implemented by subclasses.
+   * @param {string} level - Log level ('error', 'warn', 'info', 'debug')
+   * @param {string} message - Log message
+   * @param {Object} [metadata={}] - Structured metadata for filtering/searching
+   * @returns {Promise<void>}
+   * @abstract
+   */
+  async write(level, message, metadata = {}) {
+    throw new Error('write() must be implemented by subclass');
+  }
+
+  /**
+   * Flush any buffered logs
+   * Some destinations (like API batchers) buffer logs for efficiency.
+   * This ensures all pending logs are written immediately.
+   * @returns {Promise<void>}
+   */
+  async flush() {
+    // Default implementation - no buffering
+    // Override in subclasses that implement buffering
+  }
+
+  /**
+   * Close the destination and release resources
+   * Called during shutdown to clean up connections, streams, timers, etc.
+   * Should call flush() to ensure no logs are lost.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    this.isShuttingDown = true;
+    await this.flush();
+  }
+
+  /**
+   * Check if this destination should accept a log at the given level
+   * Allows destinations to filter logs based on their own criteria.
+   * @param {string} level - Log level to check
+   * @returns {boolean} True if this destination should handle this level
+   */
+  shouldLog(level) {
+    // Default: accept all levels
+    // Override in subclasses to implement filtering
+    return true;
+  }
+
+  /**
+   * Handle errors that occur during write operations
+   * Provides a consistent error handling strategy across destinations.
+   * By default, errors are silently caught to prevent log failures from
+   * disrupting the application.
+   * @param {Error} error - The error that occurred
+   * @param {string} level - Log level of the failed write
+   * @param {string} message - Log message of the failed write
+   * @protected
+   */
+  handleError(error, level, message) {
+    // Silent by default to prevent cascading failures
+    // Subclasses can override to implement error reporting
+    // (e.g., console.error for console destination)
+  }
+}
+
+module.exports = BaseDestination;

package/src/logging/destinations/batched-destination.js

@@ -0,0 +1,198 @@
+const BaseDestination = require('./base-destination');
+
+/**
+ * BatchedDestination - Generic batching wrapper for any log destination
+ *
+ * Wraps any destination implementing the BaseDestination interface and adds batching
+ * capabilities. This reduces overhead for destinations that benefit from batched sends
+ * (e.g., network-based destinations like API, syslog, etc.).
+ *
+ * Key features:
+ * - Buffers logs and sends in batches to reduce overhead
+ * - Automatic flush on buffer size or time interval
+ * - Immediate flush on shutdown to prevent log loss
+ * - Graceful fallback to individual sends if batch send fails
+ * - Composable - can wrap any destination that implements write()
+ *
+ * Example usage:
+ * ```javascript
+ * const apiDestination = new ApiDestination(config);
+ * const batchedApi = new BatchedDestination(apiDestination, {
+ *   maxBatchSize: 10,
+ *   flushInterval: 2000
+ * });
+ * ```
+ */
+class BatchedDestination extends BaseDestination {
+  /**
+   * Create a new batched destination wrapper
+   * @param {BaseDestination} destination - The underlying destination to wrap
+   * @param {Object} [config={}] - Batching configuration
+   * @param {number} [config.maxBatchSize=10] - Maximum logs to buffer before flushing
+   * @param {number} [config.flushInterval=2000] - Interval in ms to auto-flush buffered logs
+   * @param {boolean} [config.useBatchSend=true] - Whether to try batch sending (via sendBatch)
+   */
+  constructor(destination, config = {}) {
+    super(config);
+
+    if (!destination) {
+      throw new Error('BatchedDestination requires a destination to wrap');
+    }
+
+    this.destination = destination;
+    this.buffer = [];
+
+    // Configuration
+    this.maxBatchSize = config.maxBatchSize || 10;
+    this.flushInterval = config.flushInterval || 2000; // 2 seconds
+    this.useBatchSend = config.useBatchSend !== false; // Default true
+
+    // Start automatic flush timer
+    this.flushTimer = setInterval(() => this.flush(), this.flushInterval);
+
+    // Track if we're shutting down
+    this.isShuttingDown = false;
+  }
+
+  /**
+   * Add a log entry to the buffer
+   * If buffer is full, automatically flushes.
+   * If shutting down, sends immediately without batching.
+   * @param {string} level - Log level ('error', 'warn', 'info', 'debug')
+   * @param {string} message - Log message
+   * @param {Object} [metadata={}] - Structured metadata
+   * @returns {Promise<void>}
+   */
+  async write(level, message, metadata = {}) {
+    if (this.isShuttingDown) {
+      // If shutting down, send immediately without batching
+      try {
+        await this.destination.write(level, message, metadata);
+      } catch (error) {
+        this.handleError(error, level, message);
+      }
+      return;
+    }
+
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      metadata: metadata && Object.keys(metadata).length > 0 ? metadata : undefined
+    };
+
+    this.buffer.push(logEntry);
+
+    // Flush if buffer is full
+    if (this.buffer.length >= this.maxBatchSize) {
+      await this.flush();
+    }
+  }
+
+  /**
+   * Flush buffered logs to the wrapped destination
+   * Tries batch send first (if destination supports it), falls back to individual sends.
+   * Safe to call when buffer is empty (no-op).
+   * @returns {Promise<void>}
+   */
+  async flush() {
+    if (this.buffer.length === 0) return;
+
+    const batch = [...this.buffer];
+    this.buffer = [];
+
+    try {
+      // Check if destination supports batch sending
+      if (this.useBatchSend && typeof this.destination.sendBatch === 'function') {
+        // Try batch send (more efficient)
+        await this.destination.sendBatch(batch);
+      } else {
+        // Fall back to individual sends
+        await this.sendIndividually(batch);
+      }
+    } catch (error) {
+      // If batch send fails, try individual sends as fallback
+      try {
+        await this.sendIndividually(batch);
+      } catch (fallbackError) {
+        this.handleError(fallbackError, 'error', 'Failed to send buffered logs');
+      }
+    }
+  }
+
+  /**
+   * Send logs individually (fallback method)
+   * Used when batch sending fails or is unavailable.
+   * Silently fails individual log sends to prevent cascading errors.
+   * @param {Array<Object>} logs - Array of log entries with {timestamp, level, message, metadata}
+   * @returns {Promise<void>}
+   * @private
+   */
+  async sendIndividually(logs) {
+    const promises = logs.map(log =>
+      this.destination.write(log.level, log.message, log.metadata)
+        .catch((error) => {
+          this.handleError(error, log.level, log.message);
+        })
+    );
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Shutdown the batcher and flush remaining logs
+   * Stops the automatic flush timer and ensures all buffered logs are sent.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    this.isShuttingDown = true;
+
+    // Stop automatic flush timer
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    // Flush any remaining logs
+    await this.flush();
+
+    // Close the wrapped destination
+    if (this.destination && typeof this.destination.close === 'function') {
+      await this.destination.close();
+    }
+  }
+
+  /**
+   * Get current buffer size (for testing/debugging)
+   * @returns {number} Number of logs currently buffered
+   */
+  getBufferSize() {
+    return this.buffer.length;
+  }
+
+  /**
+   * Check if this destination should accept a log at the given level
+   * Delegates to the wrapped destination
+   * @param {string} level - Log level to check
+   * @returns {boolean} True if this destination should handle this level
+   */
+  shouldLog(level) {
+    return this.destination.shouldLog(level);
+  }
+
+  /**
+   * Handle errors during batching operations
+   * @param {Error} error - The error that occurred
+   * @param {string} level - Log level of failed write
+   * @param {string} message - Log message of failed write
+   * @protected
+   */
+  handleError(error, level, message) {
+    // Delegate to wrapped destination's error handling
+    if (typeof this.destination.handleError === 'function') {
+      this.destination.handleError(error, level, message);
+    }
+  }
+}
+
+module.exports = BatchedDestination;

package/src/logging/destinations/console-destination.js

@@ -0,0 +1,172 @@
+const BaseDestination = require('./base-destination');
+const {
+  formatMessage,
+  formatLevel,
+  formatMetadata,
+  redactSensitiveData,
+  formatConsoleData
+} = require('../formatter');
+
+/**
+ * ConsoleDestination - Outputs logs to console (stdout/stderr)
+ *
+ * Formats logs for human-readable console output with optional colors.
+ * Supports both pretty (formatted) and JSON output modes.
+ * Does not buffer - writes immediately for real-time visibility.
+ */
+class ConsoleDestination extends BaseDestination {
+  /**
+   * Create a new console destination
+   * @param {Object} [config={}] - Configuration options
+   * @param {boolean} [config.colors=true] - Enable colored output
+   * @param {string} [config.format='pretty'] - Output format: 'pretty' or 'json'
+   * @param {string} [config.minLevel='info'] - Minimum log level to output
+   */
+  constructor(config = {}) {
+    super(config);
+
+    this.colors = config.colors !== false;
+    this.format = config.format || 'pretty';
+    this.minLevel = config.minLevel || 'info';
+
+    // Log level priorities for filtering
+    this.levelPriorities = {
+      error: 0,
+      warn: 1,
+      info: 2,
+      debug: 3
+    };
+  }
+
+  /**
+   * Check if this destination should log at the given level
+   * @param {string} level - Log level to check
+   * @returns {boolean} True if should log
+   */
+  shouldLog(level) {
+    const levelPriority = this.levelPriorities[level];
+    const minPriority = this.levelPriorities[this.minLevel];
+
+    if (levelPriority === undefined || minPriority === undefined) {
+      return false;
+    }
+
+    return levelPriority <= minPriority;
+  }
+
+  /**
+   * Write a log entry to console
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {Object} [metadata={}] - Structured metadata
+   * @returns {Promise<void>}
+   */
+  async write(level, message, metadata = {}) {
+    if (!this.shouldLog(level)) {
+      return;
+    }
+
+    try {
+      // Redact sensitive data before output
+      const safeMessage = redactSensitiveData(message);
+      const safeMetadata = redactSensitiveData(metadata);
+
+      let output;
+
+      if (this.format === 'json') {
+        output = this.formatJson(level, safeMessage, safeMetadata);
+      } else {
+        output = this.formatPretty(level, safeMessage, safeMetadata);
+      }
+
+      // Write to stderr for errors, stdout for everything else
+      if (level === 'error') {
+        console.error(output);
+      } else {
+        console.log(output);
+      }
+    } catch (error) {
+      this.handleError(error, level, message);
+    }
+  }
+
+  /**
+   * Format log entry as JSON
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {Object} metadata - Log metadata
+   * @returns {string} JSON formatted log
+   * @private
+   */
+  formatJson(level, message, metadata) {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message
+    };
+
+    // Add metadata if present
+    if (metadata && Object.keys(metadata).length > 0) {
+      entry.metadata = metadata;
+    }
+
+    return formatMetadata(entry, { indent: 0 });
+  }
+
+  /**
+   * Format log entry for pretty console output
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {Object} metadata - Log metadata
+   * @returns {string} Pretty formatted log
+   * @private
+   */
+  formatPretty(level, message, metadata) {
+    const timestamp = new Date().toISOString();
+    const formattedLevel = formatLevel(level, {
+      colors: this.colors,
+      uppercase: true
+    });
+
+    // Format message with metadata inline
+    const formattedMessage = formatMessage(message, metadata, {
+      includeMetadata: true,
+      maxFieldLength: 100
+    });
+
+    // Build output line
+    let output = `[${timestamp}] ${formattedLevel} ${formattedMessage}`;
+
+    // Add detailed metadata if present (excluding fields already shown inline)
+    const detailedData = formatConsoleData(metadata, {
+      indent: '  ',
+      maxKeys: 20,
+      maxValueLength: 200
+    });
+
+    if (detailedData) {
+      output += detailedData;
+    }
+
+    return output;
+  }
+
+  /**
+   * Handle errors during console writing
+   * Attempts to output error to stderr as last resort
+   * @param {Error} error - The error that occurred
+   * @param {string} level - Log level of failed write
+   * @param {string} message - Log message of failed write
+   * @protected
+   */
+  handleError(error, level, message) {
+    try {
+      // Try to output a minimal error message
+      console.error(`[ConsoleDestination Error] Failed to write log: ${error.message}`);
+    } catch {
+      // If even this fails, give up silently
+    }
+  }
+}
+
+module.exports = ConsoleDestination;

package/src/logging/destinations/file-destination.js

@@ -0,0 +1,208 @@
+const BaseDestination = require('./base-destination');
+const LogFileHelper = require('../../utils/log-file-helper');
+const fs = require('fs');
+const fsPromises = require('fs').promises;
+
+/**
+ * FileDestination - Writes logs to job-specific log files
+ *
+ * Wraps LogFileHelper to provide file-based logging through the destination interface.
+ * Supports both streaming (for real-time output) and batch writing modes.
+ * Each job gets its own log file in the .rb-logs directory.
+ */
+class FileDestination extends BaseDestination {
+  /**
+   * Create a new file destination
+   * @param {Object} config - Configuration options
+   * @param {string} config.workingDir - Working directory for log files
+   * @param {Object} config.job - Job object with id and task_title
+   * @param {number} config.startTime - Job start timestamp
+   * @param {string} config.jobType - Type of job (e.g., 'PRD Generation')
+   * @param {boolean} [config.useStream=true] - Use streaming mode vs batch writes
+   */
+  constructor(config) {
+    super(config);
+
+    if (!config.workingDir) {
+      throw new Error('FileDestination requires workingDir in config');
+    }
+    if (!config.job) {
+      throw new Error('FileDestination requires job in config');
+    }
+    if (!config.startTime) {
+      throw new Error('FileDestination requires startTime in config');
+    }
+    if (!config.jobType) {
+      throw new Error('FileDestination requires jobType in config');
+    }
+
+    this.workingDir = config.workingDir;
+    this.job = config.job;
+    this.startTime = config.startTime;
+    this.jobType = config.jobType;
+    this.useStream = config.useStream !== false;
+
+    // Will be initialized on first write
+    this.logFile = null;
+    this.logStream = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize log file/stream on first write
+   * @returns {Promise<void>}
+   * @private
+   */
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+
+    try {
+      if (this.useStream) {
+        // Create log file with stream for real-time writing
+        const result = await LogFileHelper.createJobLogStream(
+          this.workingDir,
+          this.job,
+          this.startTime,
+          this.jobType
+        );
+        this.logFile = result.logFile;
+        this.logStream = result.logStream;
+      } else {
+        // For non-streaming mode, we'll use append operations
+        // Create initial log file with header
+        this.logFile = await LogFileHelper.createJobLogWithContent(
+          this.workingDir,
+          this.job,
+          this.startTime,
+          this.jobType,
+          '' // Empty content, we'll append logs
+        );
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      this.handleError(error, 'error', 'Failed to initialize file destination');
+      throw error; // Re-throw to indicate initialization failure
+    }
+  }
+
+  /**
+   * Write a log entry to the log file
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {Object} [metadata={}] - Structured metadata
+   * @returns {Promise<void>}
+   */
+  async write(level, message, metadata = {}) {
+    try {
+      // Initialize on first write
+      if (!this.initialized) {
+        await this.initialize();
+      }
+
+      // Format log entry
+      const timestamp = new Date().toISOString();
+      const formattedLevel = level.toUpperCase().padEnd(5);
+      let logLine = `[${timestamp}] ${formattedLevel} ${message}`;
+
+      // Add metadata if present
+      if (metadata && Object.keys(metadata).length > 0) {
+        const metadataStr = JSON.stringify(metadata);
+        logLine += ` | ${metadataStr}`;
+      }
+
+      logLine += '\n';
+
+      // Write to file
+      if (this.useStream && this.logStream) {
+        // Streaming mode - write immediately
+        this.logStream.write(logLine);
+      } else if (this.logFile) {
+        // Batch mode - append to file
+        await fsPromises.appendFile(this.logFile, logLine);
+      }
+    } catch (error) {
+      this.handleError(error, level, message);
+    }
+  }
+
+  /**
+   * Flush any buffered writes
+   * For streams, this is a no-op as writes are immediate.
+   * @returns {Promise<void>}
+   */
+  async flush() {
+    // Stream writes are immediate, no buffering to flush
+    // Non-stream mode uses fsPromises.appendFile which is also immediate
+  }
+
+  /**
+   * Close the log file and write completion footer
+   * @returns {Promise<void>}
+   */
+  async close() {
+    if (!this.initialized) {
+      return;
+    }
+
+    this.isShuttingDown = true;
+
+    try {
+      // Flush any pending writes
+      await this.flush();
+
+      // Write completion footer
+      if (this.useStream && this.logStream) {
+        LogFileHelper.writeCompletionFooterToStream(
+          this.logStream,
+          this.jobType,
+          {}
+        );
+        // Close the stream
+        await new Promise((resolve, reject) => {
+          this.logStream.end((err) => {
+            if (err) reject(err);
+            else resolve();
+          });
+        });
+      } else if (this.logFile) {
+        await LogFileHelper.writeCompletionFooter(
+          this.logFile,
+          this.jobType,
+          {}
+        );
+      }
+    } catch (error) {
+      this.handleError(error, 'error', 'Failed to close file destination');
+    }
+  }
+
+  /**
+   * Get the log file path
+   * Useful for reporting or accessing the log file after job completion.
+   * @returns {string|null} Path to log file, or null if not initialized
+   */
+  getLogFilePath() {
+    return this.logFile;
+  }
+
+  /**
+   * Handle errors during file operations
+   * Outputs to console.error since we can't write to the log file
+   * @param {Error} error - The error that occurred
+   * @param {string} level - Log level of failed write
+   * @param {string} message - Log message of failed write
+   * @protected
+   */
+  handleError(error, level, message) {
+    // Can't log to file since that's what failed, use console instead
+    console.error(
+      `[FileDestination Error] Failed to write to log file: ${error.message}`,
+      `\nOriginal log: [${level}] ${message}`
+    );
+  }
+}
+
+module.exports = FileDestination;

package/src/logging/destinations/index.js

@@ -0,0 +1,29 @@
+/**
+ * Log Destinations Module
+ *
+ * Exports all available log destinations for easy importing.
+ * Each destination implements the BaseDestination interface and can be
+ * used independently or coordinated by LogManager.
+ */
+
+const BaseDestination = require('./base-destination');
+const ConsoleDestination = require('./console-destination');
+const FileDestination = require('./file-destination');
+const ApiDestination = require('./api-destination');
+const BatchedDestination = require('./batched-destination');
+const ApiDestinationUnbatched = require('./api-destination-unbatched');
+const ProgressBatchDestination = require('./progress-batch-destination');
+const ProgressBatchDestinationUnbatched = require('./progress-batch-destination-unbatched');
+const LogManager = require('../log-manager');
+
+module.exports = {
+  BaseDestination,
+  ConsoleDestination,
+  FileDestination,
+  ApiDestination,
+  BatchedDestination,
+  ApiDestinationUnbatched,
+  ProgressBatchDestination,
+  ProgressBatchDestinationUnbatched,
+  LogManager
+};