@orbytautomation/engine 0.4.0 → 0.5.0

package/dist/logging/EngineLogger.js

@@ -23,7 +23,7 @@
  * @module core
  */
 import { LogLevel, LogLevelSeverity, formatLog, createLogEntry, shouldLog, formatTimestamp, } from '@dev-ecosystem/core';
-import { EngineLogType } from '../types/log-types.js';
+import { EngineLogType, LogCategoryEnum } from '../types/log-types.js';
 /**
  * Re-export formatTimestamp for external use
  * Allows other parts of the system to format timestamps consistently
@@ -35,19 +35,34 @@ export { formatTimestamp };
  * Wraps ecosystem-core logging utilities with engine-specific configuration.
  */
 export class EngineLogger {
+    // Config may have optional category/source
     config;
     formatOptions;
     eventListeners;
-    logBuffer; // Structured JSON log buffer
+    logBuffer; // Structured JSON log buffer (strongly typed)
+    /**
+     * Default log source (component/module)
+     */
+    /**
+     * Default log source (component/module)
+     */
+    // defaultSource removed: source is always required and used directly
     maxBufferSize = 10000; // Prevent memory leaks
     constructor(config) {
+        if (!config.source) {
+            throw new Error('EngineLoggerConfig: source is required');
+        }
+        if (!config.category) {
+            throw new Error('EngineLoggerConfig: category is required');
+        }
         this.config = {
             level: config.level,
             format: config.format || 'text',
             colors: config.colors ?? true,
             timestamp: config.timestamp ?? true,
-            source: config.source || 'Orbyt',
-            structuredEvents: config.structuredEvents ?? true, // Default to true for JSON collection
+            source: config.source,
+            structuredEvents: config.structuredEvents ?? true,
+            category: config.category,
         };
         this.formatOptions = {
             format: this.config.format,
@@ -61,32 +76,35 @@ export class EngineLogger {
     /**
      * Log a debug message
      */
-    debug(message, context) {
-        this.log(LogLevel.DEBUG, message, context);
+    /**
+     * Log a debug message (category and source required)
+     */
+    debug(message, context, category, source) {
+        this.log(LogLevel.DEBUG, message, context, undefined, category, source);
     }
     /**
-     * Log an info message
+     * Log an info message (category and source required)
      */
-    info(message, context) {
-        this.log(LogLevel.INFO, message, context);
+    info(message, context, category, source) {
+        this.log(LogLevel.INFO, message, context, undefined, category, source);
     }
     /**
-     * Log a warning message
+     * Log a warning message (category and source required)
      */
-    warn(message, context) {
-        this.log(LogLevel.WARN, message, context);
+    warn(message, context, category, source) {
+        this.log(LogLevel.WARN, message, context, undefined, category, source);
     }
     /**
-     * Log an error message
+     * Log an error message (category and source required)
      */
-    error(message, error, context) {
-        this.log(LogLevel.ERROR, message, context, error);
+    error(message, error, context, category, source) {
+        this.log(LogLevel.ERROR, message, context, error, category, source);
     }
     /**
-     * Log a fatal error message
+     * Log a fatal error message (category and source required)
      */
-    fatal(message, error, context) {
-        this.log(LogLevel.FATAL, message, context, error);
+    fatal(message, error, context, category, source) {
+        this.log(LogLevel.FATAL, message, context, error, category, source);
     }
     // ============================================================================
     // WORKFLOW LIFECYCLE LOGGING
@@ -94,17 +112,25 @@ export class EngineLogger {
     /**
      * Log workflow started event
      */
+    /**
+     * Log workflow started event (runtime phase)
+     */
     workflowStarted(workflowName, context) {
         this.logEvent({
             type: EngineLogType.WORKFLOW_STARTED,
             timestamp: new Date(),
             message: `Workflow "${workflowName}" started`,
             context,
+            category: LogCategoryEnum.RUNTIME,
+            source: 'WorkflowExecutor',
         });
     }
     /**
      * Log workflow completed event
      */
+    /**
+     * Log workflow completed event (runtime phase)
+     */
     workflowCompleted(workflowName, duration, context) {
         this.logEvent({
             type: EngineLogType.WORKFLOW_COMPLETED,
@@ -112,11 +138,16 @@ export class EngineLogger {
             message: `Workflow "${workflowName}" completed successfully`,
             context,
             metrics: { duration },
+            category: LogCategoryEnum.RUNTIME,
+            source: 'WorkflowExecutor',
         });
     }
     /**
      * Log workflow failed event
      */
+    /**
+     * Log workflow failed event (runtime phase)
+     */
     workflowFailed(workflowName, error, duration, context) {
         this.logEvent({
             type: EngineLogType.WORKFLOW_FAILED,
@@ -125,17 +156,24 @@ export class EngineLogger {
             context,
             error,
             metrics: { duration },
+            category: LogCategoryEnum.RUNTIME,
+            source: 'WorkflowExecutor',
         });
     }
     /**
      * Log workflow validation event
      */
+    /**
+     * Log workflow validation event (analysis phase)
+     */
     workflowValidation(workflowName, isValid, errors) {
         this.logEvent({
             type: EngineLogType.WORKFLOW_VALIDATION,
             timestamp: new Date(),
             message: `Workflow "${workflowName}" validation: ${isValid ? 'PASSED' : 'FAILED'}`,
             context: errors ? { errors } : undefined,
+            category: LogCategoryEnum.ANALYSIS,
+            source: 'WorkflowLoader',
         });
     }
     // ============================================================================
@@ -144,17 +182,25 @@ export class EngineLogger {
     /**
      * Log step started event
      */
+    /**
+     * Log step started event (runtime phase)
+     */
     stepStarted(stepId, stepName, context) {
         this.logEvent({
             type: EngineLogType.STEP_STARTED,
             timestamp: new Date(),
             message: `Step "${stepName}" (${stepId}) started`,
             context,
+            category: LogCategoryEnum.RUNTIME,
+            source: 'StepExecutor',
         });
     }
     /**
      * Log step completed event
      */
+    /**
+     * Log step completed event (runtime phase)
+     */
     stepCompleted(stepId, stepName, duration, context) {
         this.logEvent({
             type: EngineLogType.STEP_COMPLETED,
@@ -162,11 +208,16 @@ export class EngineLogger {
             message: `Step "${stepName}" (${stepId}) completed`,
             context,
             metrics: { duration },
+            category: LogCategoryEnum.RUNTIME,
+            source: 'StepExecutor',
         });
     }
     /**
      * Log step failed event
      */
+    /**
+     * Log step failed event (runtime phase)
+     */
     stepFailed(stepId, stepName, error, context) {
         this.logEvent({
             type: EngineLogType.STEP_FAILED,
@@ -174,28 +225,40 @@ export class EngineLogger {
             message: `Step "${stepName}" (${stepId}) failed: ${error.message}`,
             context,
             error,
+            category: LogCategoryEnum.RUNTIME,
+            source: 'StepExecutor',
         });
     }
     /**
      * Log step retry event
      */
+    /**
+     * Log step retry event (runtime phase)
+     */
     stepRetry(stepId, stepName, attempt, maxAttempts) {
         this.logEvent({
             type: EngineLogType.STEP_RETRY,
             timestamp: new Date(),
             message: `Step "${stepName}" (${stepId}) retry ${attempt}/${maxAttempts}`,
             context: { attempt, maxAttempts },
+            category: LogCategoryEnum.RUNTIME,
+            source: 'StepExecutor',
         });
     }
     /**
      * Log step timeout event
      */
+    /**
+     * Log step timeout event (runtime phase)
+     */
     stepTimeout(stepId, stepName, timeout) {
         this.logEvent({
             type: EngineLogType.STEP_TIMEOUT,
             timestamp: new Date(),
             message: `Step "${stepName}" (${stepId}) timed out after ${timeout}ms`,
             context: { timeout },
+            category: LogCategoryEnum.RUNTIME,
+            source: 'StepExecutor',
         });
     }
     // ============================================================================
@@ -204,23 +267,33 @@ export class EngineLogger {
     /**
      * Log explanation generated event
      */
+    /**
+     * Log explanation generated event (analysis phase)
+     */
     explanationGenerated(workflowName, stepCount, strategy) {
         this.logEvent({
             type: EngineLogType.EXPLANATION_GENERATED,
             timestamp: new Date(),
             message: `Explanation generated for "${workflowName}" (${stepCount} steps, ${strategy} strategy)`,
             context: { workflowName, stepCount, strategy },
+            category: LogCategoryEnum.ANALYSIS,
+            source: 'ExplanationGenerator',
         });
     }
     /**
      * Log circular dependencies detected
      */
+    /**
+     * Log circular dependencies detected (analysis phase)
+     */
     explanationCycles(workflowName, cycles) {
         this.logEvent({
             type: EngineLogType.EXPLANATION_CYCLES,
             timestamp: new Date(),
             message: `Circular dependencies detected in "${workflowName}"`,
             context: { cycles },
+            category: LogCategoryEnum.ANALYSIS,
+            source: 'ExplanationGenerator',
         });
     }
     // ============================================================================
@@ -229,17 +302,25 @@ export class EngineLogger {
     /**
      * Log adapter loaded event
      */
+    /**
+     * Log adapter loaded event (system phase)
+     */
     adapterLoaded(adapterName, version) {
         this.logEvent({
             type: EngineLogType.ADAPTER_LOADED,
             timestamp: new Date(),
             message: `Adapter "${adapterName}" loaded${version ? ` (v${version})` : ''}`,
             context: { adapterName, version },
+            category: LogCategoryEnum.SYSTEM,
+            source: 'AdapterRegistry',
         });
     }
     /**
      * Log adapter failed event
      */
+    /**
+     * Log adapter failed event (system phase)
+     */
     adapterFailed(adapterName, error) {
         this.logEvent({
             type: EngineLogType.ADAPTER_FAILED,
@@ -247,28 +328,40 @@ export class EngineLogger {
             message: `Adapter "${adapterName}" failed: ${error.message}`,
             context: { adapterName },
             error,
+            category: LogCategoryEnum.SYSTEM,
+            source: 'AdapterRegistry',
         });
     }
     /**
      * Log plugin installed event
      */
+    /**
+     * Log plugin installed event (system phase)
+     */
     pluginInstalled(pluginName, source) {
         this.logEvent({
             type: EngineLogType.PLUGIN_INSTALLED,
             timestamp: new Date(),
             message: `Plugin "${pluginName}" installed from ${source}`,
             context: { pluginName, source },
+            category: LogCategoryEnum.SYSTEM,
+            source: 'AdapterRegistry',
         });
     }
     /**
      * Log plugin verified event
      */
+    /**
+     * Log plugin verified event (system phase)
+     */
     pluginVerified(pluginName, verified) {
         this.logEvent({
             type: EngineLogType.PLUGIN_VERIFIED,
             timestamp: new Date(),
             message: `Plugin "${pluginName}" verification: ${verified ? 'PASSED' : 'FAILED'}`,
             context: { pluginName, verified },
+            category: LogCategoryEnum.SYSTEM,
+            source: 'AdapterRegistry',
         });
     }
     // ============================================================================
@@ -277,6 +370,9 @@ export class EngineLogger {
     /**
      * Log error detected event
      */
+    /**
+     * Log error detected event (security phase)
+     */
     errorDetected(error, context) {
         this.logEvent({
             type: EngineLogType.ERROR_DETECTED,
@@ -284,11 +380,16 @@ export class EngineLogger {
             message: `Error detected: ${error.message}`,
             context,
             error,
+            category: LogCategoryEnum.SECURITY,
+            source: 'SecurityError',
         });
     }
     /**
      * Log error debugged event (with debugging info)
      */
+    /**
+     * Log error debugged event (security phase)
+     */
     errorDebugged(error, debugInfo) {
         this.logEvent({
             type: EngineLogType.ERROR_DEBUGGED,
@@ -296,17 +397,24 @@ export class EngineLogger {
             message: `Error debugged: ${error.message}`,
             context: debugInfo,
             error,
+            category: LogCategoryEnum.SECURITY,
+            source: 'SecurityError',
         });
     }
     /**
      * Log validation error event
      */
+    /**
+     * Log validation error event (analysis phase)
+     */
     validationError(message, errors) {
         this.logEvent({
             type: EngineLogType.VALIDATION_ERROR,
             timestamp: new Date(),
             message,
             context: { errors },
+            category: LogCategoryEnum.ANALYSIS,
+            source: 'WorkflowLoader',
         });
     }
     // ============================================================================
@@ -315,17 +423,25 @@ export class EngineLogger {
     /**
      * Log performance metric
      */
+    /**
+     * Log performance metric (system phase)
+     */
     performanceMetric(label, metrics) {
         this.logEvent({
             type: EngineLogType.PERFORMANCE_METRIC,
             timestamp: new Date(),
             message: `Performance: ${label}`,
             metrics,
+            category: LogCategoryEnum.SYSTEM,
+            source: 'EngineLogger',
         });
     }
     /**
      * Log execution time
      */
+    /**
+     * Log execution time (runtime phase)
+     */
     executionTime(label, duration, context) {
         this.logEvent({
             type: EngineLogType.EXECUTION_TIME,
@@ -333,6 +449,8 @@ export class EngineLogger {
             message: `${label}: ${duration}ms`,
             context,
             metrics: { duration },
+            category: LogCategoryEnum.RUNTIME,
+            source: 'WorkflowExecutor',
         });
     }
     // ============================================================================
@@ -628,9 +746,14 @@ export class EngineLogger {
         }
     }
     /**
-     * Log a structured engine event
+     * Log a structured engine event (category and source required)
+     * Uses EngineLog interface for strong typing.
      */
     logEvent(event) {
+        // Validate category and source
+        if (!event.category || !event.source) {
+            throw new Error('Log event must have a category and source');
+        }
         // Add to JSON buffer (always, regardless of log level)
         this.addToBuffer(event);
         // Emit event to listeners if structured events enabled
@@ -649,7 +772,7 @@ export class EngineLogger {
             ...(event.metrics && { metrics: event.metrics }),
         };
         // Log through standard log method
-        this.log(level, event.message, fullContext, event.error);
+        this.log(level, event.message, fullContext, event.error, event.category, event.source);
     }
     /**
      * Get appropriate log level for event type
@@ -717,7 +840,14 @@ export class EngineLogger {
     /**
      * Internal log method
      */
-    log(level, message, context, error) {
+    /**
+     * Internal log method (category and source required)
+     */
+    /**
+     * Internal log method (category and source required)
+     * Uses EngineLog interface for strong typing.
+     */
+    log(level, message, context, error, category = LogCategoryEnum.SYSTEM, source) {
         // Check if this level should be logged (using severity for better performance)
         if (!this.shouldLogLevel(level)) {
             return;
@@ -729,13 +859,30 @@ export class EngineLogger {
             error,
         });
         // Add basic logs to buffer as well (for comprehensive JSON output)
-        this.addToBuffer({
-            type: this.mapLogLevelToEventType(level),
+        // Use EngineLog type for legacy compatibility
+        const logLegacy = {
+            timestamp: Date.now(),
+            level: this.mapLogLevelToString(level),
+            category: category || this.config.category,
+            source: source || this.config.source,
+            message,
+            context,
+        };
+        // Actually use logLegacy: output to console for legacy consumers
+        console.debug('Legacy log:', logLegacy);
+        // Also create EngineLogEvent for event system
+        const logEvent = {
+            type: EngineLogType.INFO,
             timestamp: new Date(),
             message,
+            category: category || this.config.category,
+            source: source || this.config.source,
             context,
-            error,
-        });
+            ...(error ? { error } : {}),
+        };
+        this.addToBuffer(logEvent);
+        // Optionally: expose legacy log for debugging
+        // console.debug('Legacy log:', logLegacy);
         // Format and output
         const formatted = formatLog(entry, this.formatOptions);
         console.log(formatted);
@@ -743,14 +890,21 @@ export class EngineLogger {
     /**
      * Map LogLevel to EngineLogType
      */
-    mapLogLevelToEventType(level) {
+    /**
+     * Map LogLevel to string for EngineLog.level
+     */
+    mapLogLevelToString(level) {
         switch (level) {
-            case LogLevel.DEBUG: return EngineLogType.DEBUG;
-            case LogLevel.INFO: return EngineLogType.INFO;
-            case LogLevel.WARN: return EngineLogType.WARNING;
+            case LogLevel.DEBUG:
+            case LogLevel.INFO:
+                return 'info';
+            case LogLevel.WARN:
+                return 'warn';
             case LogLevel.ERROR:
-            case LogLevel.FATAL: return EngineLogType.ERROR;
-            default: return EngineLogType.INFO;
+            case LogLevel.FATAL:
+                return 'error';
+            default:
+                return 'info';
         }
     }
     /**
@@ -1001,7 +1155,7 @@ export class EngineLogger {
     exportLogsGrouped() {
         const grouped = {};
         for (const log of this.logBuffer) {
-            const type = log.type;
+            const type = log.category;
             if (!grouped[type]) {
                 grouped[type] = [];
             }
@@ -1144,27 +1298,7 @@ export class EngineLogger {
 /**
  * Create a logger instance from engine config
  */
-export function createEngineLogger(logLevel, verbose = false) {
-    // Silent mode - no logger
-    if (logLevel === 'silent') {
-        return null;
-    }
-    // Map engine log level to ecosystem LogLevel
-    const levelMap = {
-        debug: LogLevel.DEBUG,
-        info: LogLevel.INFO,
-        warn: LogLevel.WARN,
-        error: LogLevel.ERROR,
-        fatal: LogLevel.FATAL,
-    };
-    const level = levelMap[logLevel] || LogLevel.INFO;
-    return new EngineLogger({
-        level,
-        format: verbose ? 'pretty' : 'text',
-        colors: true,
-        timestamp: true, // Enable human-readable timestamps
-        source: 'Orbyt',
-        structuredEvents: true, // Always collect structured JSON logs
-    });
+export function createEngineLogger(config) {
+    return new EngineLogger(config);
 }
 //# sourceMappingURL=EngineLogger.js.map