@arela/uploader 1.1.3 → 1.2.0

package/.claude/worktrees/agent-multi-profile/src/services/LoggingService.js

@@ -0,0 +1,649 @@
+import { randomUUID } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+
+import appConfig from '../config/config.js';
+import FileOperations from '../utils/FileOperations.js';
+
+/**
+ * Logging Service
+ * Handles application logging with buffering, file output, console output, and event tracking
+ */
+export class LoggingService {
+  constructor() {
+    this.logFilePath = appConfig.logging.logFilePath;
+    this.isVerbose = appConfig.logging.verbose;
+    this.buffer = [];
+    this.bufferSize = appConfig.performance.logBufferSize;
+    this.flushInterval = appConfig.performance.logFlushInterval;
+    this.lastFlushTime = Date.now();
+    this.context = null;
+
+    // Event tracking (new in Fase 5)
+    this.uploadEvents = [];
+    this.retryEvents = [];
+    this.sessionStartTime = null;
+    this.sessionId = null;
+
+    this.#setupProcessHandlers();
+  }
+
+  /**
+   * Setup process handlers for graceful shutdown
+   * @private
+   */
+  #setupProcessHandlers() {
+    const flushAndExit = (exitCode = 0) => {
+      this.flush();
+      process.exit(exitCode);
+    };
+
+    process.on('exit', () => this.flush());
+    process.on('SIGINT', () => flushAndExit(0));
+    process.on('SIGTERM', () => flushAndExit(0));
+    process.on('uncaughtException', (error) => {
+      this.error(`Uncaught Exception: ${error.message}`);
+      flushAndExit(1);
+    });
+    process.on('unhandledRejection', (reason, promise) => {
+      this.error(`Unhandled Rejection at: ${promise}, reason: ${reason}`);
+      // Don't kill the process — allow it to continue processing remaining files
+    });
+  }
+
+  /**
+   * Prefix a message with the active context (agent profile name), so both the
+   * console echo and the file entry stay grep-able per profile
+   * @private
+   */
+  #withContext(message) {
+    return this.context ? `[${this.context}] ${message}` : message;
+  }
+
+  /**
+   * Write a log message
+   * @param {string} message - Log message
+   * @param {string} level - Log level (info, warn, error, debug)
+   */
+  writeLog(message, level = 'info') {
+    try {
+      const timestamp = new Date().toISOString();
+      const logEntry = `[${timestamp}] [${level.toUpperCase()}] ${message}`;
+
+      this.buffer.push(logEntry);
+
+      // Flush if buffer is full or enough time has passed
+      const now = Date.now();
+      if (
+        this.buffer.length >= this.bufferSize ||
+        now - this.lastFlushTime >= this.flushInterval
+      ) {
+        this.flush();
+      }
+    } catch (error) {
+      console.error(`❌ Error buffering log message: ${error.message}`);
+    }
+  }
+
+  /**
+   * Log info message
+   * @param {string} message - Message to log
+   */
+  info(message) {
+    message = this.#withContext(message);
+    this.writeLog(message, 'info');
+    // Echo to console: run banners, stats and the 🧩 observability lines were
+    // file-only, so operators watching the terminal never saw them (the v1
+    // canary summary was invisible until someone grepped arela-upload.log).
+    console.log(message);
+  }
+
+  /**
+   * Log warning message
+   * @param {string} message - Message to log
+   */
+  warn(message) {
+    message = this.#withContext(message);
+    this.writeLog(message, 'warn');
+    console.warn(`⚠️ ${message}`);
+  }
+
+  /**
+   * Log error message
+   * @param {string} message - Message to log
+   */
+  error(message) {
+    message = this.#withContext(message);
+    this.writeLog(message, 'error');
+    console.error(`❌ ${message}`);
+  }
+
+  /**
+   * Log debug message (only if verbose mode is enabled)
+   * @param {string} message - Message to log
+   */
+  debug(message) {
+    if (this.isVerbose) {
+      message = this.#withContext(message);
+      this.writeLog(message, 'debug');
+      console.log(`🔍 ${message}`);
+    }
+  }
+
+  /**
+   * Log verbose message (only if verbose mode is enabled)
+   * @param {string} message - Message to log
+   */
+  verbose(message) {
+    if (this.isVerbose) {
+      message = this.#withContext(message);
+      this.writeLog(message, 'verbose');
+      console.log(message);
+    }
+  }
+
+  /**
+   * Log success message
+   * @param {string} message - Message to log
+   */
+  success(message) {
+    message = this.#withContext(message);
+    this.writeLog(message, 'success');
+    console.log(`✅ ${message}`);
+  }
+
+  /**
+   * Flush log buffer to file
+   */
+  flush() {
+    if (this.buffer.length === 0) return;
+
+    try {
+      const logContent = this.buffer.join('\n') + '\n';
+      FileOperations.appendToFile(this.logFilePath, logContent);
+      this.buffer = [];
+      this.lastFlushTime = Date.now();
+    } catch (error) {
+      console.error(`❌ Error writing to log file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Clear the log file
+   */
+  clearLogFile() {
+    try {
+      if (FileOperations.fileExists(this.logFilePath)) {
+        fs.unlinkSync(this.logFilePath);
+      }
+    } catch (error) {
+      console.error(`❌ Error clearing log file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get log file path
+   * @returns {string} Path to log file
+   */
+  getLogFilePath() {
+    return this.logFilePath;
+  }
+
+  /**
+   * Redirect logging to a different file (agent mode uses ~/.arela/arela-agent.log
+   * instead of the cwd-bound arela-upload.log). Flushes pending entries first.
+   * @param {string} filePath - Absolute path to the new log file
+   */
+  setLogFilePath(filePath) {
+    this.flush();
+    this.logFilePath = filePath;
+  }
+
+  /**
+   * Set a context prefix added to every file log entry (e.g. the active agent
+   * profile name, so one shared log stays grep-able per profile).
+   * @param {string|null} prefix - Context name, or null to clear
+   */
+  setContext(prefix) {
+    this.context = prefix || null;
+  }
+
+  /**
+   * Check if verbose logging is enabled
+   * @returns {boolean} True if verbose logging is enabled
+   */
+  isVerboseEnabled() {
+    return this.isVerbose;
+  }
+
+  /**
+   * Set verbose mode
+   * @param {boolean} verbose - Enable/disable verbose mode
+   */
+  setVerbose(verbose) {
+    this.isVerbose = verbose;
+  }
+
+  /**
+   * Get current buffer size
+   * @returns {number} Number of buffered log entries
+   */
+  getBufferSize() {
+    return this.buffer.length;
+  }
+
+  /**
+   * Initialize session tracking (Fase 5)
+   * @param {string} sessionId - Unique session identifier
+   */
+  initializeSession(sessionId) {
+    this.sessionId = sessionId;
+    this.sessionStartTime = Date.now();
+    this.uploadEvents = [];
+    this.retryEvents = [];
+    this.info(`Session initialized: ${sessionId}`);
+  }
+
+  /**
+   * Record an upload event
+   * @param {Object} uploadEvent - Upload event details
+   */
+  recordUploadEvent(uploadEvent) {
+    const event = {
+      id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      ...uploadEvent,
+    };
+
+    this.uploadEvents.push(event);
+    this.info(
+      `Upload event recorded: ${event.strategy} (${event.fileCount} files, ` +
+        `${event.successCount} success, ${event.failureCount} failed)`,
+    );
+
+    return event.id;
+  }
+
+  /**
+   * Record a retry event
+   * @param {string} uploadEventId - ID of the original upload event
+   * @param {number} attemptNumber - Retry attempt number
+   * @param {string} error - Error message
+   * @param {number} backoffMs - Backoff time in milliseconds
+   */
+  recordRetryEvent(uploadEventId, attemptNumber, error, backoffMs) {
+    const event = {
+      id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      uploadEventId,
+      attemptNumber,
+      error,
+      backoffMs,
+    };
+
+    this.retryEvents.push(event);
+    this.warn(
+      `Retry attempt ${attemptNumber} for upload ${uploadEventId.substring(0, 8)}: ${error}`,
+    );
+
+    return event.id;
+  }
+
+  /**
+   * Get upload history
+   * @returns {Array} Array of upload events
+   */
+  getUploadHistory() {
+    return [...this.uploadEvents];
+  }
+
+  /**
+   * Get retry history
+   * @returns {Array} Array of retry events
+   */
+  getRetryHistory() {
+    return [...this.retryEvents];
+  }
+
+  /**
+   * Get session statistics
+   * @returns {Object} Session statistics
+   */
+  getSessionStatistics() {
+    const stats = {
+      sessionId: this.sessionId,
+      startTime: new Date(this.sessionStartTime).toISOString(),
+      duration: Date.now() - this.sessionStartTime,
+      totalUploadEvents: this.uploadEvents.length,
+      totalRetryEvents: this.retryEvents.length,
+      totalFileCount: this.uploadEvents.reduce(
+        (sum, e) => sum + e.fileCount,
+        0,
+      ),
+      totalSuccessCount: this.uploadEvents.reduce(
+        (sum, e) => sum + e.successCount,
+        0,
+      ),
+      totalFailureCount: this.uploadEvents.reduce(
+        (sum, e) => sum + e.failureCount,
+        0,
+      ),
+      successRate: 0,
+      byStrategy: {
+        individual: this.#getStrategyStats('individual'),
+        batch: this.#getStrategyStats('batch'),
+        fullStructure: this.#getStrategyStats('full-structure'),
+      },
+      retryStats: {
+        totalRetries: this.retryEvents.length,
+        uniqueUploadsWithRetries: new Set(
+          this.retryEvents.map((e) => e.uploadEventId),
+        ).size,
+        totalRetryDuration: this.retryEvents.reduce(
+          (sum, e) => sum + e.backoffMs,
+          0,
+        ),
+      },
+    };
+
+    // Calculate success rate
+    if (stats.totalFileCount > 0) {
+      stats.successRate =
+        (stats.totalSuccessCount / stats.totalFileCount) * 100;
+    }
+
+    return stats;
+  }
+
+  /**
+   * Get statistics for a specific strategy (private)
+   * @private
+   * @param {string} strategy - Strategy name
+   * @returns {Object} Strategy statistics
+   */
+  #getStrategyStats(strategy) {
+    const strategyEvents = this.uploadEvents.filter(
+      (e) => e.strategy === strategy,
+    );
+
+    return {
+      uploadCount: strategyEvents.length,
+      totalFiles: strategyEvents.reduce((sum, e) => sum + e.fileCount, 0),
+      totalSuccess: strategyEvents.reduce((sum, e) => sum + e.successCount, 0),
+      totalFailure: strategyEvents.reduce((sum, e) => sum + e.failureCount, 0),
+      totalDuration: strategyEvents.reduce((sum, e) => sum + e.duration, 0),
+      averageDuration:
+        strategyEvents.length > 0
+          ? strategyEvents.reduce((sum, e) => sum + e.duration, 0) /
+            strategyEvents.length
+          : 0,
+      successRate:
+        strategyEvents.length > 0
+          ? (strategyEvents.reduce((sum, e) => sum + e.successCount, 0) /
+              strategyEvents.reduce((sum, e) => sum + e.fileCount, 0)) *
+            100
+          : 0,
+    };
+  }
+
+  /**
+   * Format session report
+   * @returns {string} Formatted session report
+   */
+  formatSessionReport() {
+    const stats = this.getSessionStatistics();
+    const endTime = new Date();
+    const startTime = new Date(stats.startTime);
+    const durationMin = Math.floor(stats.duration / 60000);
+    const durationSec = Math.floor((stats.duration % 60000) / 1000);
+
+    let report = '';
+
+    // Header with visual separators
+    report +=
+      '\n┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n';
+    report +=
+      '┃                   📊 SESSION SUMMARY REPORT                       ┃\n';
+    report +=
+      '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\n\n';
+
+    // Session Information
+    report += '🕐 SESSION INFORMATION\n';
+    report +=
+      '─────────────────────────────────────────────────────────────────\n';
+    report += `│ Session ID:       ${this.#padRight(stats.sessionId, 49)}\n`;
+    report += `│ Duration:         ${this.#padRight(`${durationMin}m ${durationSec}s`, 49)}\n`;
+    report += `│ Start Time:       ${this.#padRight(stats.startTime, 49)}\n`;
+    report += `│ End Time:         ${this.#padRight(endTime.toISOString(), 49)}\n`;
+    report += `│ Total Uploads:    ${this.#padRight(`${stats.totalUploadEvents}`, 49)}\n`;
+    report += `│ Total Retries:    ${this.#padRight(`${stats.totalRetryEvents}`, 49)}\n\n`;
+
+    // Overall Statistics
+    report += '� OVERALL STATISTICS\n';
+    report +=
+      '─────────────────────────────────────────────────────────────────\n';
+    report += `│ Total Files Processed:   ${this.#padRight(`${stats.totalFileCount}`, 41)}\n`;
+    report += `│ Successful Files:        ${this.#padRight(`${stats.totalSuccessCount} (${stats.successRate.toFixed(1)}%)`, 41)}\n`;
+    report += `│ Failed Files:            ${this.#padRight(`${stats.totalFailureCount}`, 41)}\n`;
+    report += `│ Session Success Rate:    ${this.#padRight(`${stats.successRate.toFixed(1)}%`, 41)}\n\n`;
+
+    // Strategy breakdown
+    report += '🎯 BY STRATEGY BREAKDOWN\n';
+    report +=
+      '─────────────────────────────────────────────────────────────────\n';
+    report += this.#formatStrategyStatsDetailed(stats.byStrategy);
+
+    // Performance metrics
+    if (stats.totalFileCount > 0) {
+      const avgTimePerFile = stats.duration / stats.totalFileCount;
+      const filesPerMin = (
+        stats.totalFileCount /
+        (stats.duration / 60000)
+      ).toFixed(1);
+
+      report += '⚡ PERFORMANCE METRICS\n';
+      report +=
+        '─────────────────────────────────────────────────────────────────\n';
+      report += `│ Average Time per File:   ${this.#padRight(`${avgTimePerFile.toFixed(1)}ms`, 41)}\n`;
+      report += `│ Processing Speed:        ${this.#padRight(`${filesPerMin} files/min`, 41)}\n`;
+      report += `│ Total Session Duration:  ${this.#padRight(`${durationMin}m ${durationSec}s`, 41)}\n\n`;
+    }
+
+    // Retry statistics
+    if (stats.retryStats.totalRetries > 0) {
+      const avgRetryWait =
+        stats.retryStats.totalRetryDuration /
+        stats.retryStats.totalRetries /
+        1000;
+      report += '🔄 RETRY STATISTICS\n';
+      report +=
+        '─────────────────────────────────────────────────────────────────\n';
+      report += `│ Total Retries:           ${this.#padRight(`${stats.retryStats.totalRetries}`, 41)}\n`;
+      report += `│ Uploads with Retries:    ${this.#padRight(`${stats.retryStats.uniqueUploadsWithRetries}`, 41)}\n`;
+      report += `│ Total Retry Duration:    ${this.#padRight(`${(stats.retryStats.totalRetryDuration / 1000).toFixed(2)}s`, 41)}\n`;
+      report += `│ Retry Success Rate:      ${this.#padRight(`100%`, 41)}\n\n`;
+    }
+
+    // Intelligent recommendations
+    report += '💡 RECOMMENDATIONS\n';
+    report +=
+      '─────────────────────────────────────────────────────────────────\n';
+    report += this.#generateRecommendations(stats);
+
+    // Footer
+    report +=
+      '\n┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\n';
+
+    return report;
+  }
+
+  /**
+   * Pad string to the right with spaces (private)
+   * @private
+   * @param {string} str - String to pad
+   * @param {number} length - Target length
+   * @returns {string} Padded string
+   */
+  #padRight(str, length) {
+    const padding = Math.max(0, length - String(str).length);
+    return String(str) + ' '.repeat(padding);
+  }
+
+  /**
+   * Format detailed strategy statistics (private)
+   * @private
+   * @param {Object} strategies - Strategy statistics
+   * @returns {string} Formatted statistics
+   */
+  #formatStrategyStatsDetailed(strategies) {
+    let report = '';
+    const strategyEmojis = {
+      individual: '📁',
+      batch: '📦',
+      'full-structure': '🗂️',
+    };
+
+    for (const [strategyName, stats] of Object.entries(strategies)) {
+      if (stats.uploadCount > 0) {
+        const emoji = strategyEmojis[strategyName] || '📋';
+        const durationSec = (stats.totalDuration / 1000).toFixed(1);
+        const filesPerMin =
+          stats.totalDuration > 0
+            ? (stats.totalFiles / (stats.totalDuration / 60000)).toFixed(1)
+            : '0.0';
+
+        report += `${emoji} ${strategyName.toUpperCase()}\n`;
+        report += `│ ├─ Uploads:        ${this.#padRight(`${stats.uploadCount}`, 47)}\n`;
+        report += `│ ├─ Files:          ${this.#padRight(`${stats.totalFiles}`, 47)}\n`;
+        report += `│ ├─ Success:        ${this.#padRight(`${stats.totalSuccess} (${stats.successRate.toFixed(1)}%)`, 47)}\n`;
+        report += `│ ├─ Failed:         ${this.#padRight(`${stats.totalFiles - stats.totalSuccess}`, 47)}\n`;
+        report += `│ ├─ Duration:       ${this.#padRight(`${durationSec}s`, 47)}\n`;
+        report += `│ └─ Speed:          ${this.#padRight(`${filesPerMin} files/min`, 47)}\n`;
+        report += `│\n`;
+      }
+    }
+
+    return report;
+  }
+
+  /**
+   * Generate intelligent recommendations based on statistics (private)
+   * @private
+   * @param {Object} stats - Session statistics
+   * @returns {string} Formatted recommendations
+   */
+  #generateRecommendations(stats) {
+    const recommendations = [];
+
+    // Analyze success rate
+    if (stats.successRate >= 95) {
+      recommendations.push(
+        '✅ Excellent performance! Success rate is outstanding.',
+      );
+    } else if (stats.successRate >= 80) {
+      recommendations.push(
+        '⚠️  Good performance but consider investigating failures.',
+      );
+    } else {
+      recommendations.push(
+        '🚨 Low success rate - review error logs for issues.',
+      );
+    }
+
+    // Analyze retries
+    if (stats.retryStats.totalRetries === 0) {
+      recommendations.push(
+        '✅ No retries needed - upload system is very stable.',
+      );
+    } else if (stats.retryStats.totalRetries <= 5) {
+      recommendations.push(
+        '✅ Retries were minimal and successful - system handled errors well.',
+      );
+    } else {
+      recommendations.push(
+        '⚠️  High retry count - consider improving connection stability.',
+      );
+    }
+
+    // Analyze strategies
+    const byStrategy = stats.byStrategy;
+    const strategies = Object.entries(byStrategy)
+      .filter(([_, s]) => s.uploadCount > 0)
+      .sort((a, b) => {
+        const aSpeed =
+          a[1].totalDuration > 0
+            ? a[1].totalFiles / (a[1].totalDuration / 60000)
+            : 0;
+        const bSpeed =
+          b[1].totalDuration > 0
+            ? b[1].totalFiles / (b[1].totalDuration / 60000)
+            : 0;
+        return bSpeed - aSpeed;
+      });
+
+    if (strategies.length > 0) {
+      const fastest = strategies[0];
+      recommendations.push(
+        `💡 Fastest strategy: ${fastest[0]} (${(fastest[1].totalFiles / (fastest[1].totalDuration / 60000)).toFixed(1)} files/min)`,
+      );
+    }
+
+    if (stats.totalFileCount > 100) {
+      recommendations.push(
+        '💡 Large session detected - monitor memory usage for future sessions.',
+      );
+    }
+
+    // Format recommendations
+    let report = '';
+    recommendations.forEach((rec, idx) => {
+      if (idx < recommendations.length - 1) {
+        report += `│ ${rec}\n`;
+      } else {
+        report += `│ ${rec}\n`;
+      }
+    });
+
+    return report;
+  }
+
+  /**
+   * Format strategy statistics (private) - Legacy method
+   * @private
+   * @param {Object} strategies - Strategy statistics
+   * @returns {string} Formatted statistics
+   */
+  #formatStrategyStats(strategies) {
+    let report = '';
+
+    for (const [strategyName, stats] of Object.entries(strategies)) {
+      if (stats.uploadCount > 0) {
+        report += `├─ ${strategyName}:\n`;
+        report += `│  ├─ Uploads:  ${stats.uploadCount}\n`;
+        report += `│  ├─ Files:    ${stats.totalFiles}\n`;
+        report += `│  ├─ Success:  ${stats.totalSuccess} (${stats.successRate.toFixed(1)}%)\n`;
+        report += `│  └─ Duration: ${(stats.totalDuration / 1000).toFixed(1)}s\n`;
+      }
+    }
+
+    report += '\n';
+    return report;
+  }
+
+  /**
+   * Get session end statistics
+   * @returns {Object} Final session statistics
+   */
+  getSessionSummary() {
+    const stats = this.getSessionStatistics();
+    return {
+      ...stats,
+      endTime: new Date().toISOString(),
+      report: this.formatSessionReport(),
+    };
+  }
+}
+
+// Export singleton instance
+export const logger = new LoggingService();
+export default logger;