@orbytautomation/engine 0.2.4 → 0.4.0

package/dist/logging/EngineLogger.js

@@ -0,0 +1,1170 @@
+/**
+ * Engine Logger
+ *
+ * Provides structured logging for the Orbyt Engine using ecosystem-core utilities.
+ * Supports multiple output formats and log levels with proper filtering.
+ *
+ * Features:
+ * - Severity-based log level filtering using LogLevelSeverity
+ * - Multiple output formats (pretty, text, json, structured)
+ * - Color support with ANSI codes
+ * - Engine-generated timestamps (consistent across CLI, API, web dashboards)
+ * - Context and error tracking
+ * - Performance measurement with automatic severity adjustment
+ * - Efficient level comparison using numeric severity
+ *
+ * Timestamps are generated by the engine to ensure consistency across:
+ * - CLI output
+ * - API responses
+ * - Web dashboard logs
+ * - Monitoring systems
+ * - Audit trails
+ *
+ * @module core
+ */
+import { LogLevel, LogLevelSeverity, formatLog, createLogEntry, shouldLog, formatTimestamp, } from '@dev-ecosystem/core';
+import { EngineLogType } from '../types/log-types.js';
+/**
+ * Re-export formatTimestamp for external use
+ * Allows other parts of the system to format timestamps consistently
+ */
+export { formatTimestamp };
+/**
+ * Engine Logger
+ *
+ * Wraps ecosystem-core logging utilities with engine-specific configuration.
+ */
+export class EngineLogger {
+    config;
+    formatOptions;
+    eventListeners;
+    logBuffer; // Structured JSON log buffer
+    maxBufferSize = 10000; // Prevent memory leaks
+    constructor(config) {
+        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
+        };
+        this.formatOptions = {
+            format: this.config.format,
+            colors: this.config.colors,
+            timestamp: this.config.timestamp,
+            includeSource: true,
+        };
+        this.eventListeners = new Map();
+        this.logBuffer = [];
+    }
+    /**
+     * Log a debug message
+     */
+    debug(message, context) {
+        this.log(LogLevel.DEBUG, message, context);
+    }
+    /**
+     * Log an info message
+     */
+    info(message, context) {
+        this.log(LogLevel.INFO, message, context);
+    }
+    /**
+     * Log a warning message
+     */
+    warn(message, context) {
+        this.log(LogLevel.WARN, message, context);
+    }
+    /**
+     * Log an error message
+     */
+    error(message, error, context) {
+        this.log(LogLevel.ERROR, message, context, error);
+    }
+    /**
+     * Log a fatal error message
+     */
+    fatal(message, error, context) {
+        this.log(LogLevel.FATAL, message, context, error);
+    }
+    // ============================================================================
+    // WORKFLOW LIFECYCLE LOGGING
+    // ============================================================================
+    /**
+     * Log workflow started event
+     */
+    workflowStarted(workflowName, context) {
+        this.logEvent({
+            type: EngineLogType.WORKFLOW_STARTED,
+            timestamp: new Date(),
+            message: `Workflow "${workflowName}" started`,
+            context,
+        });
+    }
+    /**
+     * Log workflow completed event
+     */
+    workflowCompleted(workflowName, duration, context) {
+        this.logEvent({
+            type: EngineLogType.WORKFLOW_COMPLETED,
+            timestamp: new Date(),
+            message: `Workflow "${workflowName}" completed successfully`,
+            context,
+            metrics: { duration },
+        });
+    }
+    /**
+     * Log workflow failed event
+     */
+    workflowFailed(workflowName, error, duration, context) {
+        this.logEvent({
+            type: EngineLogType.WORKFLOW_FAILED,
+            timestamp: new Date(),
+            message: `Workflow "${workflowName}" failed: ${error.message}`,
+            context,
+            error,
+            metrics: { duration },
+        });
+    }
+    /**
+     * Log workflow validation event
+     */
+    workflowValidation(workflowName, isValid, errors) {
+        this.logEvent({
+            type: EngineLogType.WORKFLOW_VALIDATION,
+            timestamp: new Date(),
+            message: `Workflow "${workflowName}" validation: ${isValid ? 'PASSED' : 'FAILED'}`,
+            context: errors ? { errors } : undefined,
+        });
+    }
+    // ============================================================================
+    // STEP LIFECYCLE LOGGING
+    // ============================================================================
+    /**
+     * Log step started event
+     */
+    stepStarted(stepId, stepName, context) {
+        this.logEvent({
+            type: EngineLogType.STEP_STARTED,
+            timestamp: new Date(),
+            message: `Step "${stepName}" (${stepId}) started`,
+            context,
+        });
+    }
+    /**
+     * Log step completed event
+     */
+    stepCompleted(stepId, stepName, duration, context) {
+        this.logEvent({
+            type: EngineLogType.STEP_COMPLETED,
+            timestamp: new Date(),
+            message: `Step "${stepName}" (${stepId}) completed`,
+            context,
+            metrics: { duration },
+        });
+    }
+    /**
+     * Log step failed event
+     */
+    stepFailed(stepId, stepName, error, context) {
+        this.logEvent({
+            type: EngineLogType.STEP_FAILED,
+            timestamp: new Date(),
+            message: `Step "${stepName}" (${stepId}) failed: ${error.message}`,
+            context,
+            error,
+        });
+    }
+    /**
+     * Log step retry event
+     */
+    stepRetry(stepId, stepName, attempt, maxAttempts) {
+        this.logEvent({
+            type: EngineLogType.STEP_RETRY,
+            timestamp: new Date(),
+            message: `Step "${stepName}" (${stepId}) retry ${attempt}/${maxAttempts}`,
+            context: { attempt, maxAttempts },
+        });
+    }
+    /**
+     * Log step timeout event
+     */
+    stepTimeout(stepId, stepName, timeout) {
+        this.logEvent({
+            type: EngineLogType.STEP_TIMEOUT,
+            timestamp: new Date(),
+            message: `Step "${stepName}" (${stepId}) timed out after ${timeout}ms`,
+            context: { timeout },
+        });
+    }
+    // ============================================================================
+    // EXPLANATION LOGGING
+    // ============================================================================
+    /**
+     * Log explanation generated event
+     */
+    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 },
+        });
+    }
+    /**
+     * Log circular dependencies detected
+     */
+    explanationCycles(workflowName, cycles) {
+        this.logEvent({
+            type: EngineLogType.EXPLANATION_CYCLES,
+            timestamp: new Date(),
+            message: `Circular dependencies detected in "${workflowName}"`,
+            context: { cycles },
+        });
+    }
+    // ============================================================================
+    // ADAPTER & PLUGIN LOGGING
+    // ============================================================================
+    /**
+     * Log adapter loaded event
+     */
+    adapterLoaded(adapterName, version) {
+        this.logEvent({
+            type: EngineLogType.ADAPTER_LOADED,
+            timestamp: new Date(),
+            message: `Adapter "${adapterName}" loaded${version ? ` (v${version})` : ''}`,
+            context: { adapterName, version },
+        });
+    }
+    /**
+     * Log adapter failed event
+     */
+    adapterFailed(adapterName, error) {
+        this.logEvent({
+            type: EngineLogType.ADAPTER_FAILED,
+            timestamp: new Date(),
+            message: `Adapter "${adapterName}" failed: ${error.message}`,
+            context: { adapterName },
+            error,
+        });
+    }
+    /**
+     * Log plugin installed event
+     */
+    pluginInstalled(pluginName, source) {
+        this.logEvent({
+            type: EngineLogType.PLUGIN_INSTALLED,
+            timestamp: new Date(),
+            message: `Plugin "${pluginName}" installed from ${source}`,
+            context: { pluginName, source },
+        });
+    }
+    /**
+     * Log plugin verified event
+     */
+    pluginVerified(pluginName, verified) {
+        this.logEvent({
+            type: EngineLogType.PLUGIN_VERIFIED,
+            timestamp: new Date(),
+            message: `Plugin "${pluginName}" verification: ${verified ? 'PASSED' : 'FAILED'}`,
+            context: { pluginName, verified },
+        });
+    }
+    // ============================================================================
+    // ERROR & DEBUG LOGGING
+    // ============================================================================
+    /**
+     * Log error detected event
+     */
+    errorDetected(error, context) {
+        this.logEvent({
+            type: EngineLogType.ERROR_DETECTED,
+            timestamp: new Date(),
+            message: `Error detected: ${error.message}`,
+            context,
+            error,
+        });
+    }
+    /**
+     * Log error debugged event (with debugging info)
+     */
+    errorDebugged(error, debugInfo) {
+        this.logEvent({
+            type: EngineLogType.ERROR_DEBUGGED,
+            timestamp: new Date(),
+            message: `Error debugged: ${error.message}`,
+            context: debugInfo,
+            error,
+        });
+    }
+    /**
+     * Log validation error event
+     */
+    validationError(message, errors) {
+        this.logEvent({
+            type: EngineLogType.VALIDATION_ERROR,
+            timestamp: new Date(),
+            message,
+            context: { errors },
+        });
+    }
+    // ============================================================================
+    // PERFORMANCE LOGGING
+    // ============================================================================
+    /**
+     * Log performance metric
+     */
+    performanceMetric(label, metrics) {
+        this.logEvent({
+            type: EngineLogType.PERFORMANCE_METRIC,
+            timestamp: new Date(),
+            message: `Performance: ${label}`,
+            metrics,
+        });
+    }
+    /**
+     * Log execution time
+     */
+    executionTime(label, duration, context) {
+        this.logEvent({
+            type: EngineLogType.EXECUTION_TIME,
+            timestamp: new Date(),
+            message: `${label}: ${duration}ms`,
+            context,
+            metrics: { duration },
+        });
+    }
+    // ============================================================================
+    // FIELD-LEVEL EXECUTION LOGGING (Dynamic Explanation)
+    // ============================================================================
+    /**
+     * Log field execution - captures every field that gets executed
+     * This enables dynamic explanation generation from runtime logs
+     */
+    fieldExecution(type, field, value, context) {
+        // Filter out internal fields (starting with _)
+        if (field.startsWith('_'))
+            return;
+        this.debug(`[Field] ${type}.${field} = ${this.formatValue(value)}`, {
+            fieldType: type,
+            fieldName: field,
+            value: this.sanitizeValue(value),
+            ...context,
+        });
+    }
+    /**
+     * Log input processing
+     */
+    inputProcessed(inputName, value, source) {
+        this.debug(`[Input] ${inputName} received from ${source}`, {
+            input: inputName,
+            source,
+            value: this.sanitizeValue(value),
+        });
+    }
+    /**
+     * Log output generation
+     */
+    outputGenerated(outputName, value, step) {
+        this.debug(`[Output] ${outputName} generated${step ? ` by ${step}` : ''}`, {
+            output: outputName,
+            step,
+            value: this.sanitizeValue(value),
+        });
+    }
+    /**
+     * Log context variable access
+     */
+    contextAccessed(variable, value, step) {
+        this.debug(`[Context] ${variable} accessed by ${step}`, {
+            variable,
+            step,
+            value: this.sanitizeValue(value),
+        });
+    }
+    /**
+     * Log secret access (without exposing values)
+     */
+    secretAccessed(secretKey, step) {
+        this.debug(`[Secret] ${secretKey} accessed by ${step}`, {
+            secretKey,
+            step,
+            exposed: false, // Never log secret values
+        });
+    }
+    /**
+     * Log variable resolution
+     */
+    variableResolved(variable, resolvedValue, context) {
+        this.debug(`[Variable] ${variable} resolved`, {
+            variable,
+            resolved: this.sanitizeValue(resolvedValue),
+            ...context,
+        });
+    }
+    /**
+     * Log adapter action execution
+     */
+    adapterActionExecuted(adapter, action, duration, success) {
+        const message = `[Adapter] ${adapter}.${action} ${success ? 'completed' : 'failed'} in ${duration}ms`;
+        const context = { adapter, action, duration, success };
+        if (success) {
+            this.info(message, context);
+        }
+        else {
+            this.error(message, undefined, context);
+        }
+    }
+    // ============================================================================
+    // PARSING & VALIDATION LOGGING
+    // ============================================================================
+    /**
+     * Log parsing start
+     */
+    parsingStarted(source, format) {
+        this.debug(`[Parser] Parsing ${format} from ${source}`, {
+            source,
+            format,
+        });
+    }
+    /**
+     * Log parsing success
+     */
+    parsingCompleted(source, duration, stats) {
+        this.info(`[Parser] Parsed successfully in ${duration}ms`, {
+            source,
+            duration,
+            ...stats,
+        });
+    }
+    /**
+     * Log parsing error
+     */
+    parsingFailed(source, error, context) {
+        this.error(`[Parser] Parsing failed: ${error.message}`, error, {
+            source,
+            ...context,
+        });
+    }
+    /**
+     * Log validation start
+     */
+    validationStarted(target, type) {
+        this.debug(`[Validator] Validating ${type}: ${target}`, {
+            target,
+            type,
+        });
+    }
+    /**
+     * Log validation success
+     */
+    validationPassed(target, type, duration) {
+        this.info(`[Validator] Validation passed: ${target}`, {
+            target,
+            type,
+            duration,
+        });
+    }
+    /**
+     * Log validation failure
+     */
+    validationFailed(target, type, errors) {
+        this.error(`[Validator] Validation failed: ${target}`, undefined, {
+            target,
+            type,
+            errors,
+            errorCount: errors.length,
+        });
+    }
+    // ============================================================================
+    // ERROR DETECTION & DEBUGGING LOGGING
+    // ============================================================================
+    /**
+     * Log error enrichment (when ErrorDetector adds debugging info)
+     */
+    errorEnriched(error, debugInfo) {
+        this.debug(`[ErrorDetector] Error enriched with debugging info`, {
+            errorType: error.name,
+            errorMessage: error.message,
+            ...debugInfo,
+        });
+    }
+    /**
+     * Log error debugging output
+     */
+    errorDebugOutput(error, explanation, fixSteps) {
+        this.info(`[ErrorDebugger] Generated debugging output for ${error.name}`, {
+            errorType: error.name,
+            explanation,
+            fixSteps,
+            stepCount: fixSteps.length,
+        });
+    }
+    // ============================================================================
+    // EXECUTION PHASE LOGGING
+    // ============================================================================
+    /**
+     * Log execution phase start
+     */
+    phaseStarted(phase, stepIds) {
+        this.info(`[Execution] Phase ${phase} started with ${stepIds.length} step(s)`, {
+            phase,
+            stepIds,
+            stepCount: stepIds.length,
+        });
+    }
+    /**
+     * Log execution phase completion
+     */
+    phaseCompleted(phase, duration, successCount, failureCount) {
+        this.info(`[Execution] Phase ${phase} completed in ${duration}ms`, {
+            phase,
+            duration,
+            successCount,
+            failureCount,
+            totalSteps: successCount + failureCount,
+        });
+    }
+    // ============================================================================
+    // UTILITY METHODS
+    // ============================================================================
+    /**
+     * Format value for logging (truncate large values)
+     */
+    formatValue(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (typeof value === 'string') {
+            return value.length > 100 ? `${value.substring(0, 97)}...` : value;
+        }
+        if (typeof value === 'object') {
+            const str = JSON.stringify(value);
+            return str.length > 200 ? `${str.substring(0, 197)}...` : str;
+        }
+        return String(value);
+    }
+    /**
+     * Sanitize value for logging (remove sensitive data)
+     */
+    sanitizeValue(value) {
+        if (value === null || value === undefined)
+            return value;
+        // For objects, recursively sanitize
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            const sanitized = {};
+            for (const [key, val] of Object.entries(value)) {
+                // Skip internal fields
+                if (key.startsWith('_'))
+                    continue;
+                // Mask sensitive fields
+                if (this.isSensitiveField(key)) {
+                    sanitized[key] = '***REDACTED***';
+                }
+                else if (typeof val === 'object') {
+                    sanitized[key] = this.sanitizeValue(val);
+                }
+                else {
+                    sanitized[key] = val;
+                }
+            }
+            return sanitized;
+        }
+        return value;
+    }
+    /**
+     * Check if field name suggests sensitive data
+     */
+    isSensitiveField(fieldName) {
+        const sensitivePatterns = [
+            'password', 'secret', 'token', 'key', 'credential',
+            'apikey', 'api_key', 'auth', 'private',
+        ];
+        const lowerField = fieldName.toLowerCase();
+        return sensitivePatterns.some(pattern => lowerField.includes(pattern));
+    }
+    /**
+     * Log with a custom level
+     */
+    logWithLevel(level, message, context) {
+        this.log(level, message, context);
+    }
+    /**
+     * Log only if severity meets minimum threshold
+     */
+    logIfSeverity(minSeverity, level, message, context) {
+        if (LogLevelSeverity[level] >= minSeverity) {
+            this.log(level, message, context);
+        }
+    }
+    /**
+     * Measure and log execution time with appropriate log level based on duration
+     */
+    async measureExecution(label, fn, thresholds) {
+        const start = Date.now();
+        try {
+            const result = await fn();
+            const duration = Date.now() - start;
+            // Choose log level based on duration thresholds
+            let level = LogLevel.DEBUG;
+            if (thresholds?.error && duration > thresholds.error) {
+                level = LogLevel.ERROR;
+            }
+            else if (thresholds?.warn && duration > thresholds.warn) {
+                level = LogLevel.WARN;
+            }
+            else {
+                level = LogLevel.INFO;
+            }
+            this.log(level, `${label} completed`, { duration: `${duration}ms` });
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - start;
+            this.log(LogLevel.ERROR, `${label} failed`, { duration: `${duration}ms` }, error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Log a structured engine event
+     */
+    logEvent(event) {
+        // Add to JSON buffer (always, regardless of log level)
+        this.addToBuffer(event);
+        // Emit event to listeners if structured events enabled
+        if (this.config.structuredEvents) {
+            this.emitEvent(event);
+        }
+        // Determine log level based on event type
+        const level = this.getLogLevelForEventType(event.type);
+        // Check if this level should be logged
+        if (!this.shouldLogLevel(level)) {
+            return;
+        }
+        // Build context with metrics if present
+        const fullContext = {
+            ...event.context,
+            ...(event.metrics && { metrics: event.metrics }),
+        };
+        // Log through standard log method
+        this.log(level, event.message, fullContext, event.error);
+    }
+    /**
+     * Get appropriate log level for event type
+     */
+    getLogLevelForEventType(type) {
+        // Error events
+        if (type.includes('failed') || type.includes('error') || type.includes('timeout')) {
+            return LogLevel.ERROR;
+        }
+        // Warning events
+        if (type.includes('retry') || type.includes('cycles') || type === EngineLogType.WARNING) {
+            return LogLevel.WARN;
+        }
+        // Debug events
+        if (type === EngineLogType.DEBUG || type.includes('debug')) {
+            return LogLevel.DEBUG;
+        }
+        // Default to INFO
+        return LogLevel.INFO;
+    }
+    /**
+     * Emit event to registered listeners
+     */
+    emitEvent(event) {
+        const listeners = this.eventListeners.get(event.type) || [];
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                // Don't let listener errors crash the logger
+                console.error('Error in log event listener:', error);
+            }
+        }
+        // Also emit to wildcard listeners
+        const wildcardListeners = this.eventListeners.get(EngineLogType.INFO) || [];
+        for (const listener of wildcardListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.error('Error in wildcard log event listener:', error);
+            }
+        }
+    }
+    /**
+     * Subscribe to specific log event types
+     */
+    on(type, listener) {
+        if (!this.eventListeners.has(type)) {
+            this.eventListeners.set(type, []);
+        }
+        this.eventListeners.get(type).push(listener);
+        // Return unsubscribe function
+        return () => {
+            const listeners = this.eventListeners.get(type);
+            if (listeners) {
+                const index = listeners.indexOf(listener);
+                if (index > -1) {
+                    listeners.splice(index, 1);
+                }
+            }
+        };
+    }
+    /**
+     * Internal log method
+     */
+    log(level, message, context, error) {
+        // Check if this level should be logged (using severity for better performance)
+        if (!this.shouldLogLevel(level)) {
+            return;
+        }
+        // Create log entry
+        const entry = createLogEntry(level, message, {
+            source: this.config.source,
+            context,
+            error,
+        });
+        // Add basic logs to buffer as well (for comprehensive JSON output)
+        this.addToBuffer({
+            type: this.mapLogLevelToEventType(level),
+            timestamp: new Date(),
+            message,
+            context,
+            error,
+        });
+        // Format and output
+        const formatted = formatLog(entry, this.formatOptions);
+        console.log(formatted);
+    }
+    /**
+     * Map LogLevel to EngineLogType
+     */
+    mapLogLevelToEventType(level) {
+        switch (level) {
+            case LogLevel.DEBUG: return EngineLogType.DEBUG;
+            case LogLevel.INFO: return EngineLogType.INFO;
+            case LogLevel.WARN: return EngineLogType.WARNING;
+            case LogLevel.ERROR:
+            case LogLevel.FATAL: return EngineLogType.ERROR;
+            default: return EngineLogType.INFO;
+        }
+    }
+    /**
+     * Check if a level should be logged using severity comparison
+     */
+    shouldLogLevel(level) {
+        return LogLevelSeverity[level] >= LogLevelSeverity[this.config.level];
+    }
+    /**
+     * Check if a level is more severe than another
+     */
+    isMoreSevere(level, compareWith) {
+        return LogLevelSeverity[level] > LogLevelSeverity[compareWith];
+    }
+    /**
+     * Get severity difference between two levels
+     */
+    getSeverityDiff(level1, level2) {
+        return LogLevelSeverity[level1] - LogLevelSeverity[level2];
+    }
+    /**
+     * Get the numeric severity of the current log level
+     */
+    getCurrentSeverity() {
+        return LogLevelSeverity[this.config.level];
+    }
+    /**
+     * Get the numeric severity of a log level
+     */
+    getSeverity(level) {
+        return LogLevelSeverity[level];
+    }
+    /**
+     * Update logger configuration
+     */
+    setLevel(level) {
+        this.config.level = level;
+    }
+    /**
+     * Set level by severity (0-4)
+     */
+    setLevelBySeverity(severity) {
+        const levels = Object.entries(LogLevelSeverity)
+            .find(([_, sev]) => sev === severity);
+        if (levels) {
+            this.config.level = levels[0];
+        }
+    }
+    /**
+     * Update colors setting
+     */
+    setColors(enabled) {
+        this.config.colors = enabled;
+        this.formatOptions.colors = enabled;
+    }
+    /**
+     * Update format
+     */
+    setFormat(format) {
+        this.config.format = format;
+        this.formatOptions.format = format;
+    }
+    /**
+     * Update timestamp setting
+     */
+    setTimestamp(enabled) {
+        this.config.timestamp = enabled;
+        this.formatOptions.timestamp = enabled;
+    }
+    /**
+     * Update timestamp format
+     *
+     * @param _format - 'time' | 'datetime' | 'full' (reserved for future use)
+     */
+    setTimestampFormat(_format) {
+        // Timestamp format is handled by ecosystem-core formatTimestamp function
+        // This method is kept for API compatibility but doesn't modify formatOptions
+    }
+    /**
+     * Format a timestamp using engine's timestamp formatter
+     * Useful for consistent timestamp formatting across the system
+     *
+     * @param date - Date to format (defaults to current time)
+     * @param format - Format type ('time', 'datetime', or 'full')
+     * @returns Formatted timestamp string
+     */
+    formatTimestamp(date, format = 'time') {
+        return formatTimestamp(date || new Date(), format);
+    }
+    /**
+     * Check if a level will be logged (uses shouldLog from ecosystem-core)
+     */
+    willLog(level) {
+        return shouldLog(level, this.config.level);
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Check if debug logging is enabled
+     */
+    isDebugEnabled() {
+        return this.willLog(LogLevel.DEBUG);
+    }
+    /**
+     * Check if info logging is enabled
+     */
+    isInfoEnabled() {
+        return this.willLog(LogLevel.INFO);
+    }
+    /**
+     * Check if warn logging is enabled
+     */
+    isWarnEnabled() {
+        return this.willLog(LogLevel.WARN);
+    }
+    /**
+     * Check if error logging is enabled
+     */
+    isErrorEnabled() {
+        return this.willLog(LogLevel.ERROR);
+    }
+    // ============================================================================
+    // JSON LOG BUFFER MANAGEMENT
+    // ============================================================================
+    /**
+     * Add event to JSON log buffer
+     */
+    addToBuffer(event) {
+        // Add to buffer
+        this.logBuffer.push(event);
+        // Prevent buffer overflow
+        if (this.logBuffer.length > this.maxBufferSize) {
+            this.logBuffer.shift(); // Remove oldest log
+        }
+    }
+    /**
+     * Get all logs as JSON array
+     * This is what CLI, API, dashboards, and explanation system will consume
+     */
+    getJSONLogs() {
+        return [...this.logBuffer]; // Return copy to prevent external mutations
+    }
+    /**
+     * Get logs filtered by type
+     */
+    getLogsByType(type) {
+        return this.logBuffer.filter(log => log.type === type);
+    }
+    /**
+     * Get logs filtered by time range
+     */
+    getLogsByTimeRange(startTime, endTime) {
+        return this.logBuffer.filter(log => log.timestamp >= startTime && log.timestamp <= endTime);
+    }
+    /**
+     * Get logs filtered by multiple criteria
+     */
+    getLogsFiltered(filter) {
+        let filtered = this.logBuffer;
+        if (filter.types) {
+            filtered = filtered.filter(log => filter.types.includes(log.type));
+        }
+        if (filter.startTime) {
+            filtered = filtered.filter(log => log.timestamp >= filter.startTime);
+        }
+        if (filter.endTime) {
+            filtered = filtered.filter(log => log.timestamp <= filter.endTime);
+        }
+        if (filter.hasError !== undefined) {
+            filtered = filtered.filter(log => filter.hasError ? !!log.error : !log.error);
+        }
+        if (filter.searchText) {
+            const searchLower = filter.searchText.toLowerCase();
+            filtered = filtered.filter(log => log.message.toLowerCase().includes(searchLower));
+        }
+        return filtered;
+    }
+    /**
+     * Get logs by category: Parse events
+     */
+    getParseLogEvents() {
+        return this.logBuffer.filter(log => log.type === EngineLogType.WORKFLOW_VALIDATION);
+    }
+    /**
+     * Get logs by category: Validation events
+     */
+    getValidationLogEvents() {
+        return this.logBuffer.filter(log => log.type === EngineLogType.WORKFLOW_VALIDATION ||
+            log.type === EngineLogType.VALIDATION_ERROR);
+    }
+    /**
+     * Get logs by category: Execution events
+     */
+    getExecutionLogEvents() {
+        return this.logBuffer.filter(log => log.type === EngineLogType.WORKFLOW_STARTED ||
+            log.type === EngineLogType.WORKFLOW_COMPLETED ||
+            log.type === EngineLogType.WORKFLOW_FAILED ||
+            log.type === EngineLogType.STEP_STARTED ||
+            log.type === EngineLogType.STEP_COMPLETED ||
+            log.type === EngineLogType.STEP_FAILED ||
+            log.type === EngineLogType.STEP_RETRY ||
+            log.type === EngineLogType.STEP_TIMEOUT ||
+            log.type === EngineLogType.EXECUTION_TIME ||
+            log.type === EngineLogType.QUEUE_PROCESSING);
+    }
+    /**
+     * Get logs by category: Error events
+     */
+    getErrorLogEvents() {
+        return this.logBuffer.filter(log => log.type === EngineLogType.ERROR_DETECTED ||
+            log.type === EngineLogType.ERROR_DEBUGGED ||
+            log.type === EngineLogType.VALIDATION_ERROR ||
+            log.type === EngineLogType.WORKFLOW_FAILED ||
+            log.type === EngineLogType.STEP_FAILED ||
+            log.type === EngineLogType.ADAPTER_FAILED ||
+            log.type === EngineLogType.ERROR);
+    }
+    /**
+     * Get logs by category: Lifecycle events
+     */
+    getLifecycleLogEvents() {
+        return this.logBuffer.filter(log => log.type === EngineLogType.ENGINE_STARTED ||
+            log.type === EngineLogType.ENGINE_STOPPED ||
+            log.type === EngineLogType.ADAPTER_LOADED ||
+            log.type === EngineLogType.PLUGIN_INSTALLED ||
+            log.type === EngineLogType.PLUGIN_VERIFIED);
+    }
+    /**
+     * Get logs by category: Performance events
+     */
+    getPerformanceLogEvents() {
+        return this.logBuffer.filter(log => log.type === EngineLogType.PERFORMANCE_METRIC ||
+            log.type === EngineLogType.EXECUTION_TIME);
+    }
+    /**
+     * Export logs as formatted JSON string
+     */
+    exportLogsAsJSON(pretty = true) {
+        return JSON.stringify(this.logBuffer, null, pretty ? 2 : 0);
+    }
+    /**
+     * Export logs grouped by type
+     */
+    exportLogsGrouped() {
+        const grouped = {};
+        for (const log of this.logBuffer) {
+            const type = log.type;
+            if (!grouped[type]) {
+                grouped[type] = [];
+            }
+            grouped[type].push(log);
+        }
+        return grouped;
+    }
+    /**
+     * Get log statistics
+     */
+    getLogStats() {
+        const stats = {
+            total: this.logBuffer.length,
+            byType: {},
+            withErrors: 0,
+            withMetrics: 0,
+            timeRange: {
+                first: this.logBuffer[0]?.timestamp,
+                last: this.logBuffer[this.logBuffer.length - 1]?.timestamp,
+            },
+        };
+        for (const log of this.logBuffer) {
+            // Count by type
+            stats.byType[log.type] = (stats.byType[log.type] || 0) + 1;
+            // Count errors and metrics
+            if (log.error)
+                stats.withErrors++;
+            if (log.metrics)
+                stats.withMetrics++;
+        }
+        return stats;
+    }
+    /**
+     * Clear log buffer
+     */
+    clearLogs() {
+        this.logBuffer = [];
+    }
+    /**
+     * Set maximum buffer size
+     */
+    setMaxBufferSize(size) {
+        this.maxBufferSize = size;
+        // Trim buffer if needed
+        while (this.logBuffer.length > this.maxBufferSize) {
+            this.logBuffer.shift();
+        }
+    }
+    /**
+     * Get current buffer size
+     */
+    getBufferSize() {
+        return this.logBuffer.length;
+    }
+    /**
+     * Export logs in a comprehensive format for consumers (CLI, API, dashboards)
+     */
+    exportLogs() {
+        const stats = this.getLogStats();
+        const grouped = this.exportLogsGrouped();
+        // Build execution summary from logs
+        const execution = this.buildExecutionSummary();
+        return {
+            raw: this.getJSONLogs(),
+            grouped,
+            stats,
+            execution,
+        };
+    }
+    /**
+     * Build execution summary from collected logs
+     * This powers dynamic explanation generation
+     */
+    buildExecutionSummary() {
+        const workflowLogs = this.logBuffer.filter(log => log.type === EngineLogType.WORKFLOW_STARTED ||
+            log.type === EngineLogType.WORKFLOW_COMPLETED ||
+            log.type === EngineLogType.WORKFLOW_FAILED);
+        const stepLogs = this.logBuffer.filter(log => log.type === EngineLogType.STEP_STARTED ||
+            log.type === EngineLogType.STEP_COMPLETED ||
+            log.type === EngineLogType.STEP_FAILED);
+        const errorLogs = this.logBuffer.filter(log => log.error !== undefined ||
+            log.type === EngineLogType.ERROR_DETECTED ||
+            log.type === EngineLogType.VALIDATION_ERROR);
+        const metricLogs = this.logBuffer.filter(log => log.type === EngineLogType.PERFORMANCE_METRIC ||
+            log.type === EngineLogType.EXECUTION_TIME);
+        // Extract workflow info
+        let workflow;
+        const workflowStarted = workflowLogs.find(log => log.type === EngineLogType.WORKFLOW_STARTED);
+        const workflowEnded = workflowLogs.find(log => log.type === EngineLogType.WORKFLOW_COMPLETED ||
+            log.type === EngineLogType.WORKFLOW_FAILED);
+        if (workflowStarted && workflowEnded) {
+            workflow = {
+                name: workflowStarted.context?.workflowName || 'Unknown',
+                status: workflowEnded.type === EngineLogType.WORKFLOW_COMPLETED ? 'completed' : 'failed',
+                duration: workflowEnded.metrics?.duration,
+            };
+        }
+        // Extract step info
+        const steps = [];
+        const stepMap = new Map();
+        for (const log of stepLogs) {
+            const stepId = log.context?.stepId || '';
+            const stepName = log.context?.stepName || '';
+            if (!stepMap.has(stepId)) {
+                stepMap.set(stepId, { id: stepId, name: stepName });
+            }
+            const step = stepMap.get(stepId);
+            if (log.type === EngineLogType.STEP_COMPLETED) {
+                step.status = 'completed';
+                step.duration = log.metrics?.duration;
+            }
+            else if (log.type === EngineLogType.STEP_FAILED) {
+                step.status = 'failed';
+            }
+            else {
+                step.status = 'started';
+            }
+        }
+        steps.push(...stepMap.values());
+        // Extract error info
+        const errors = errorLogs.map(log => ({
+            step: log.context?.stepId || log.context?.stepName,
+            message: log.message,
+            error: log.error,
+        }));
+        // Extract metrics
+        const metrics = metricLogs.map(log => ({
+            label: log.context?.label || 'Unknown',
+            duration: log.metrics?.duration,
+            memory: log.metrics?.memory,
+        }));
+        return {
+            workflow,
+            steps,
+            errors,
+            metrics,
+        };
+    }
+}
+/**
+ * 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
+    });
+}
+//# sourceMappingURL=EngineLogger.js.map