ralphblaster-agent 0.1.1

package/src/logging/config.js

@@ -0,0 +1,179 @@
+/**
+ * Centralized logging configuration
+ *
+ * This module consolidates all logging-related configuration from:
+ * - src/config.js (logLevel, consoleColors, consoleFormat)
+ * - src/setup-log-batcher.js (maxBatchSize, flushInterval, useBatchEndpoint)
+ * - Environment variables (RALPHBLASTER_* with RALPH_* fallback for backward compatibility)
+ *
+ * @module logging/config
+ */
+
+/**
+ * Parse boolean from environment variable
+ * Treats 'false', '0', and empty string as false, everything else as true
+ * @param {string} value - Environment variable value
+ * @param {boolean} defaultValue - Default if not set
+ * @returns {boolean}
+ */
+function parseEnvBoolean(value, defaultValue) {
+  if (value === undefined || value === null) return defaultValue;
+  return value !== 'false' && value !== '0' && value !== '';
+}
+
+/**
+ * Parse positive integer from environment variable
+ * @param {string} value - Environment variable value
+ * @param {number} defaultValue - Default if not set or invalid
+ * @returns {number}
+ */
+function parseEnvInt(value, defaultValue) {
+  if (value === undefined || value === null) return defaultValue;
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed) || parsed <= 0) {
+    console.warn(`Invalid numeric value "${value}", using default: ${defaultValue}`);
+    return defaultValue;
+  }
+  return parsed;
+}
+
+/**
+ * Valid log levels in order of severity
+ * @type {string[]}
+ */
+const VALID_LOG_LEVELS = ['error', 'warn', 'info', 'debug'];
+
+/**
+ * Valid console format options
+ * @type {string[]}
+ */
+const VALID_CONSOLE_FORMATS = ['pretty', 'json'];
+
+/**
+ * Validate that a log level is valid
+ * @param {string} level - Log level to validate
+ * @returns {boolean} True if valid
+ */
+function isValidLogLevel(level) {
+  return VALID_LOG_LEVELS.includes(level);
+}
+
+/**
+ * Validate that a console format is valid
+ * @param {string} format - Console format to validate
+ * @returns {boolean} True if valid
+ */
+function isValidConsoleFormat(format) {
+  return VALID_CONSOLE_FORMATS.includes(format);
+}
+
+// Read configuration from environment variables with validation
+const rawLogLevel = process.env.RALPHBLASTER_LOG_LEVEL || 'info';
+const logLevel = isValidLogLevel(rawLogLevel) ? rawLogLevel : 'info';
+
+// Warn if invalid log level was provided
+if (!isValidLogLevel(rawLogLevel)) {
+  console.warn(`Invalid log level "${rawLogLevel}", using default: info. Valid levels: ${VALID_LOG_LEVELS.join(', ')}`);
+}
+
+const rawConsoleFormat = process.env.RALPHBLASTER_CONSOLE_FORMAT || 'pretty';
+const consoleFormat = isValidConsoleFormat(rawConsoleFormat) ? rawConsoleFormat : 'pretty';
+
+// Warn if invalid console format was provided
+if (!isValidConsoleFormat(rawConsoleFormat)) {
+  console.warn(`Invalid console format "${rawConsoleFormat}", using default: pretty. Valid formats: ${VALID_CONSOLE_FORMATS.join(', ')}`);
+}
+
+/**
+ * Centralized logging configuration object
+ * All logging-related settings are defined here in one place
+ */
+const loggingConfig = {
+  // ===== Console Output Settings =====
+
+  /**
+   * Log level - controls which messages are displayed
+   * @type {'error' | 'warn' | 'info' | 'debug'}
+   * @default 'info'
+   */
+  logLevel,
+
+  /**
+   * Enable/disable colored console output
+   * Set to 'false' to disable colors (useful for log files or CI environments)
+   * @type {boolean}
+   * @default true
+   */
+  consoleColors: parseEnvBoolean(process.env.RALPHBLASTER_CONSOLE_COLORS, true),
+
+  /**
+   * Console output format
+   * - 'pretty': Human-readable format with colors (default)
+   * - 'json': Structured JSON format for machine parsing
+   * @type {'pretty' | 'json'}
+   * @default 'pretty'
+   */
+  consoleFormat,
+
+  // ===== Log Batching Settings =====
+  // These settings control how logs are batched before being sent to the API
+  // to reduce the number of API calls and improve performance
+
+  /**
+   * Maximum number of logs to batch before forcing a flush
+   * Larger values reduce API calls but may delay log visibility
+   * Phase 1.3: Increased from 10 to 50 to match progress batch size
+   * Expected impact: 80% reduction in log API calls (50 req/s → 10 req/s)
+   * @type {number}
+   * @default 50
+   */
+  maxBatchSize: parseEnvInt(process.env.RALPHBLASTER_MAX_BATCH_SIZE, 50),
+
+  /**
+   * Time in milliseconds between automatic log flushes
+   * Smaller values improve log visibility but increase API calls
+   * @type {number}
+   * @default 2000 (2 seconds)
+   */
+  flushInterval: parseEnvInt(process.env.RALPHBLASTER_FLUSH_INTERVAL, 2000),
+
+  /**
+   * Whether to use the batch endpoint for sending logs
+   * When true, tries to send logs in a single batch API call
+   * Falls back to individual calls if batch endpoint fails
+   * @type {boolean}
+   * @default true
+   */
+  useBatchEndpoint: parseEnvBoolean(process.env.RALPHBLASTER_USE_BATCH_ENDPOINT, true),
+
+  // ===== Agent Identification =====
+
+  /**
+   * Agent ID for multi-agent support
+   * Used to identify which agent instance is running in multi-agent deployments
+   * @type {string}
+   * @default 'agent-default'
+   */
+  agentId: process.env.RALPHBLASTER_AGENT_ID || 'agent-default',
+
+  // ===== Validation Helpers =====
+
+  /**
+   * Valid log levels
+   * @type {string[]}
+   * @readonly
+   */
+  validLogLevels: VALID_LOG_LEVELS,
+
+  /**
+   * Valid console formats
+   * @type {string[]}
+   * @readonly
+   */
+  validConsoleFormats: VALID_CONSOLE_FORMATS
+};
+
+// Freeze the configuration to prevent accidental modifications
+Object.freeze(loggingConfig);
+
+module.exports = loggingConfig;

package/src/logging/destinations/README.md

@@ -0,0 +1,290 @@
+# Log Destinations
+
+This directory contains the log destination abstraction layer for Ralph's logging system. Each destination represents a different output target for log messages (console, file, API, etc.).
+
+## Architecture
+
+All destinations extend `BaseDestination` and implement a common interface:
+
+- `write(level, message, metadata)` - Write a log entry
+- `flush()` - Flush any buffered logs
+- `close()` - Clean up resources and ensure no logs are lost
+- `shouldLog(level)` - Filter logs based on level
+- `handleError(error, level, message)` - Handle write errors gracefully
+
+This pluggable architecture allows destinations to be added, removed, or replaced independently.
+
+## Available Destinations
+
+### BaseDestination
+
+Abstract base class defining the common interface. All destinations must extend this class.
+
+**Key features:**
+- Defines standard lifecycle methods (write, flush, close)
+- Provides default error handling
+- Manages shutdown state
+
+### ConsoleDestination
+
+Outputs logs to console (stdout/stderr) with formatting and colors.
+
+**Configuration:**
+```javascript
+const destination = new ConsoleDestination({
+  colors: true,           // Enable ANSI colors
+  format: 'pretty',       // 'pretty' or 'json'
+  minLevel: 'info'        // Minimum log level to output
+});
+```
+
+**Features:**
+- Pretty formatting for human readability
+- JSON format for machine parsing
+- Color-coded by log level
+- Redacts sensitive data
+- No buffering - immediate output
+
+### FileDestination
+
+Writes logs to job-specific files in `.rb-logs/` directory.
+
+**Configuration:**
+```javascript
+const destination = new FileDestination({
+  workingDir: '/path/to/work',
+  job: { id: 123, task_title: 'Generate PRD' },
+  startTime: Date.now(),
+  jobType: 'PRD Generation',
+  useStream: true         // Use streams vs batch writes
+});
+```
+
+**Features:**
+- Creates organized log files per job
+- Streaming mode for real-time output
+- Batch mode for complete output
+- Automatic header/footer formatting
+- Safe error handling
+
+### ApiDestination
+
+Sends logs to API with intelligent batching to reduce overhead.
+
+**Configuration:**
+```javascript
+const destination = new ApiDestination({
+  apiClient: apiClientInstance,
+  jobId: 123,
+  maxBatchSize: 10,       // Flush after N logs
+  flushInterval: 2000,    // Flush every N ms
+  useBatchEndpoint: true  // Try batch endpoint first
+});
+```
+
+**Features:**
+- Batches multiple logs into single API calls
+- Automatic periodic flushing
+- Fallback to individual sends on batch failure
+- Graceful shutdown with final flush
+
+## Usage Example
+
+### Single Destination
+
+```javascript
+const { ConsoleDestination } = require('./logging/destinations');
+
+const logger = new ConsoleDestination({
+  colors: true,
+  format: 'pretty',
+  minLevel: 'debug'
+});
+
+await logger.write('info', 'Job started', { jobId: 123 });
+await logger.write('debug', 'Processing file', { file: 'example.js' });
+await logger.close();
+```
+
+### Multiple Destinations (with LogManager)
+
+```javascript
+const { ConsoleDestination, FileDestination, ApiDestination } = require('./logging/destinations');
+
+// Create destinations
+const console = new ConsoleDestination({ minLevel: 'info' });
+const file = new FileDestination({
+  workingDir: '/tmp',
+  job: { id: 1, task_title: 'Test' },
+  startTime: Date.now(),
+  jobType: 'Test'
+});
+const api = new ApiDestination({
+  apiClient,
+  jobId: 1
+});
+
+// Use with LogManager (future implementation)
+const manager = new LogManager([console, file, api]);
+await manager.log('info', 'Message to all destinations');
+await manager.close(); // Closes all destinations
+```
+
+## Creating Custom Destinations
+
+Extend `BaseDestination` and implement the required methods:
+
+```javascript
+const BaseDestination = require('./base-destination');
+
+class CustomDestination extends BaseDestination {
+  constructor(config) {
+    super(config);
+    // Initialize your destination
+  }
+
+  async write(level, message, metadata = {}) {
+    // Write log to your destination
+  }
+
+  async flush() {
+    // Flush any buffers
+  }
+
+  async close() {
+    this.isShuttingDown = true;
+    await this.flush();
+    // Clean up resources
+  }
+}
+
+module.exports = CustomDestination;
+```
+
+## Design Principles
+
+1. **Independence** - Each destination operates independently without dependencies on other destinations
+2. **Graceful Degradation** - Errors in one destination don't affect others
+3. **No Job Context** - Destinations accept context as parameters, not through global state
+4. **Async Support** - All operations support async/await for I/O operations
+5. **Pluggable** - Destinations can be added/removed without code changes
+6. **Testable** - Pure functions and dependency injection make testing easy
+
+## Error Handling
+
+Destinations handle their own errors gracefully:
+
+- **ConsoleDestination** - Attempts to write error to stderr
+- **FileDestination** - Falls back to console.error
+- **ApiDestination** - Silently fails to prevent cascading errors
+
+This prevents log failures from disrupting the application while still providing feedback when possible.
+
+### BatchedDestination
+
+Generic batching wrapper that can wrap any destination to add batching capabilities.
+
+**Configuration:**
+```javascript
+const { BatchedDestination, ConsoleDestination } = require('./logging/destinations');
+
+// Wrap any destination with batching
+const console = new ConsoleDestination();
+const batchedConsole = new BatchedDestination(console, {
+  maxBatchSize: 10,        // Flush after N logs
+  flushInterval: 2000,     // Flush every N ms
+  useBatchSend: true       // Try sendBatch() if available
+});
+```
+
+**Features:**
+- Wraps any BaseDestination implementation
+- Buffers logs and sends in batches
+- Automatic periodic flushing
+- Graceful fallback to individual sends
+- Composable - can wrap any destination
+
+**How it works:**
+1. Buffers incoming logs until `maxBatchSize` is reached
+2. Flushes automatically every `flushInterval` milliseconds
+3. If destination implements `sendBatch()`, uses it for efficiency
+4. Falls back to individual `write()` calls if batch sending fails
+5. Ensures all logs are flushed on `close()`
+
+### ApiDestinationUnbatched
+
+Low-level API destination without batching. Used internally by ApiDestination.
+
+**Note:** This should not be used directly - use `ApiDestination` instead, which wraps this with `BatchedDestination` for optimal performance.
+
+## Batching Pattern
+
+The batching pattern is composable and can be applied to any destination:
+
+```javascript
+// Example 1: Batched API destination (built-in)
+const api = new ApiDestination({ apiClient, jobId });
+
+// Example 2: Manual batching of any destination
+const file = new FileDestination({ workingDir, job, startTime, jobType });
+const batchedFile = new BatchedDestination(file, {
+  maxBatchSize: 20,
+  flushInterval: 5000
+});
+
+// Example 3: Custom destination with batching
+class SyslogDestination extends BaseDestination {
+  async write(level, message, metadata) {
+    // Send single log to syslog
+  }
+
+  async sendBatch(logs) {
+    // Optional: efficient batch send
+  }
+}
+
+const syslog = new SyslogDestination(config);
+const batchedSyslog = new BatchedDestination(syslog, {
+  maxBatchSize: 50,
+  flushInterval: 1000
+});
+```
+
+## Migration from SetupLogBatcher
+
+The old `SetupLogBatcher` class is deprecated. Migrate to the new destination-based approach:
+
+**Before:**
+```javascript
+const SetupLogBatcher = require('./setup-log-batcher');
+const batcher = new SetupLogBatcher(apiClient, jobId, {
+  maxBatchSize: 10,
+  flushInterval: 2000,
+  useBatchEndpoint: true
+});
+batcher.add('info', 'message', metadata);
+await batcher.flush();
+await batcher.shutdown();
+```
+
+**After:**
+```javascript
+const { ApiDestination } = require('./logging/destinations');
+const destination = new ApiDestination({
+  apiClient,
+  jobId,
+  maxBatchSize: 10,
+  flushInterval: 2000,
+  useBatchEndpoint: true
+});
+await destination.write('info', 'message', metadata);
+await destination.flush();
+await destination.close();
+```
+
+The old `SetupLogBatcher` is maintained for backward compatibility but internally uses the new destination-based implementation.
+
+## Next Steps
+
+- **LogManager** (Task #1) - Coordinates multiple destinations
+- **Unit Tests** (Task #7) - Comprehensive test coverage for all destinations

package/src/logging/destinations/api-destination-unbatched.js

@@ -0,0 +1,118 @@
+const BaseDestination = require('./base-destination');
+
+/**
+ * ApiDestinationUnbatched - Sends individual logs to API
+ *
+ * Provides direct API logging without batching. Designed to be wrapped by
+ * BatchedDestination for efficient batched sending.
+ *
+ * This class should NOT be used directly - use ApiDestination (which wraps
+ * this with BatchedDestination) for production use.
+ *
+ * Supports both single log and batch log endpoints:
+ * - write() - sends single log via apiClient.addSetupLog()
+ * - sendBatch() - sends multiple logs via apiClient.addSetupLogBatch()
+ */
+class ApiDestinationUnbatched extends BaseDestination {
+  /**
+   * Create a new unbatched API destination
+   * @param {Object} config - Configuration options
+   * @param {Object} config.apiClient - API client with addSetupLog() and addSetupLogBatch() methods
+   * @param {number} config.jobId - Job ID to associate logs with
+   * @param {boolean} [config.useBatchEndpoint=true] - Whether to use batch endpoint for sendBatch()
+   */
+  constructor(config) {
+    super(config);
+
+    if (!config.apiClient) {
+      throw new Error('ApiDestinationUnbatched requires apiClient in config');
+    }
+    if (config.jobId === undefined || config.jobId === null) {
+      throw new Error('ApiDestinationUnbatched requires jobId in config');
+    }
+
+    this.apiClient = config.apiClient;
+    this.jobId = config.jobId;
+    this.useBatchEndpoint = config.useBatchEndpoint !== false;
+  }
+
+  /**
+   * Write a single log entry to the API
+   * @param {string} level - Log level
+   * @param {string} message - Log message
+   * @param {Object} [metadata={}] - Structured metadata
+   * @returns {Promise<void>}
+   */
+  async write(level, message, metadata = {}) {
+    try {
+      await this.apiClient.addSetupLog(
+        this.jobId,
+        level,
+        message,
+        metadata && Object.keys(metadata).length > 0 ? metadata : null
+      );
+    } catch (error) {
+      this.handleError(error, level, message);
+    }
+  }
+
+  /**
+   * Send multiple log entries in a single batch API call
+   * This is called by BatchedDestination when flushing buffered logs.
+   * @param {Array<Object>} logs - Array of log entries with {timestamp, level, message, metadata}
+   * @returns {Promise<void>}
+   */
+  async sendBatch(logs) {
+    if (logs.length === 0) return;
+
+    try {
+      if (this.useBatchEndpoint && this.apiClient.addSetupLogBatch) {
+        // Use efficient batch endpoint
+        await this.apiClient.addSetupLogBatch(this.jobId, logs);
+      } else {
+        // Fall back to individual sends
+        await this.sendIndividually(logs);
+      }
+    } catch (error) {
+      // Re-throw to let BatchedDestination handle fallback
+      throw error;
+    }
+  }
+
+  /**
+   * Send logs individually
+   * Used as fallback when batch endpoint fails or is unavailable.
+   * @param {Array<Object>} logs - Array of log entries
+   * @returns {Promise<void>}
+   * @private
+   */
+  async sendIndividually(logs) {
+    const promises = logs.map(log =>
+      this.apiClient.addSetupLog(this.jobId, log.level, log.message, log.metadata)
+        .catch((error) => {
+          // Silently fail individual logs to prevent cascading errors
+          this.handleError(error, log.level, log.message);
+        })
+    );
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * Handle errors during API operations
+   * Silently fails to prevent cascading errors, but could be enhanced
+   * to report to a fallback destination (e.g., console or 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) {
+    // Silently fail - setup logs are best-effort and shouldn't disrupt job execution
+    // Logging errors about logging would create cascading failures and noise
+    // If API logging fails, the job continues unaffected
+    // console.error(`[ApiDestination Error] Failed to send log: ${error.message}`);
+  }
+}
+
+module.exports = ApiDestinationUnbatched;

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

@@ -0,0 +1,40 @@
+const BatchedDestination = require('./batched-destination');
+const ApiDestinationUnbatched = require('./api-destination-unbatched');
+
+/**
+ * ApiDestination - Sends logs to API with batching
+ *
+ * Provides API-based logging with automatic batching to reduce overhead.
+ * Wraps ApiDestinationUnbatched with BatchedDestination for efficient sending.
+ * Batches multiple log entries and flushes automatically based on buffer size or time interval.
+ *
+ * This is a convenience factory that creates a properly configured batched API destination.
+ */
+class ApiDestination extends BatchedDestination {
+  /**
+   * Create a new batched API destination
+   * @param {Object} config - Configuration options
+   * @param {Object} config.apiClient - API client with addSetupLog() and addSetupLogBatch() methods
+   * @param {number} config.jobId - Job ID to associate logs with
+   * @param {number} [config.maxBatchSize=10] - Maximum logs to buffer before flushing
+   * @param {number} [config.flushInterval=2000] - Interval in ms to auto-flush
+   * @param {boolean} [config.useBatchEndpoint=true] - Whether to use batch endpoint
+   */
+  constructor(config) {
+    // Create unbatched API destination
+    const unbatchedDestination = new ApiDestinationUnbatched({
+      apiClient: config.apiClient,
+      jobId: config.jobId,
+      useBatchEndpoint: config.useBatchEndpoint
+    });
+
+    // Wrap it with batching
+    super(unbatchedDestination, {
+      maxBatchSize: config.maxBatchSize,
+      flushInterval: config.flushInterval,
+      useBatchSend: config.useBatchEndpoint
+    });
+  }
+}
+
+module.exports = ApiDestination;