@orbytautomation/engine 0.5.0 → 0.6.0

package/dist/logging/EngineLogger.d.ts

@@ -20,334 +20,336 @@
  * - Monitoring systems
  * - Audit trails
  *
- * @module core
+ * @module logging
  */
 import { LogLevel, formatTimestamp } from '@dev-ecosystem/core';
-import { EngineLogEvent, EngineLogFormat, EngineLoggerConfig, EngineLogType, LogCategory, ErrorLogEvent, ExecutionLogEvent, LifecycleLogEvent, ParseLogEvent, PerformanceLogEvent, ValidationLogEvent, ExportedLogs } from '../types/log-types.js';
+import { type EngineLoggerConfig, type EngineLogFormat, type EngineLogEvent, type ExportedLogs, type LogCategory, type WorkflowContext, EngineLogType } from '../types/log-types.js';
 /**
- * Re-export formatTimestamp for external use
- * Allows other parts of the system to format timestamps consistently
+ * Internal contract used by CategoryLogger to call back into EngineLogger
+ * without a circular reference.  Not part of the public API.
+ * @internal
  */
-export { formatTimestamp };
+interface LogDispatcher {
+    _logWithCategory(level: LogLevel, message: string, context?: Record<string, unknown>, error?: Error, category?: LogCategory, typeOverride?: EngineLogType): void;
+}
+/**
+ * A thin wrapper that pins every log call to a specific category.
+ *
+ * Obtain instances via `EngineLogger.runtime`, `.analysis`, `.system`, or `.security`.
+ *
+ * ```typescript
+ * const logger = LoggerManager.getLogger();
+ *
+ * // inside run() — runtime category
+ * logger.runtime.info('Step started', { stepId });
+ *
+ * // inside explain() / validate() — analysis category
+ * logger.analysis.debug('Building execution plan');
+ * ```
+ */
+export declare class CategoryLogger {
+    private readonly parent;
+    private readonly category;
+    constructor(parent: LogDispatcher, category: LogCategory);
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+    fatal(message: string, error?: Error, context?: Record<string, unknown>): void;
+    /**
+     * Measure execution time of `fn` and log the result under this category.
+     *
+     * ```typescript
+     * const result = await logger.runtime.measureExecution(
+     *   'step:http-request',
+     *   () => httpAdapter.run(step),
+     *   { warn: 3000, error: 10000 },
+     * );
+     * ```
+     */
+    measureExecution<T>(label: string, fn: () => Promise<T>, thresholds?: {
+        warn?: number;
+        error?: number;
+    }): Promise<T>;
+}
 /**
  * Engine Logger
  *
  * Wraps ecosystem-core logging utilities with engine-specific configuration.
+ * Emits structured JSON logs and maintains a typed log history.
+ *
+ * ### Category sub-loggers
+ * Every log is tagged with a phase-based category so tooling / formatters can
+ * filter or colour-code entries without parsing the message text.
+ *
+ * | Sub-logger         | Category     | When to use                                       |
+ * |--------------------|--------------|---------------------------------------------------|
+ * | `logger.runtime`   | `runtime`    | `run()` — step start/complete/fail/retry          |
+ * | `logger.analysis`  | `analysis`   | `explain()` / `validate()` — plan & parse phase   |
+ * | `logger.system`    | `system`     | Engine init/shutdown, adapter registration        |
+ * | `logger.security`  | `security`   | Reserved-field violations, permission rejections  |
+ *
+ * Generic `logger.info(...)` etc. fall back to the category set at construction.
  */
-export declare class EngineLogger {
+export declare class EngineLogger implements LogDispatcher {
     private config;
     private formatOptions;
-    private eventListeners;
-    private logBuffer;
-    /**
-     * Default log source (component/module)
-     */
-    /**
-     * Default log source (component/module)
-     */
-    private maxBufferSize;
+    private logHistory;
+    /** Workflow context set by the engine before run/explain/validate */
+    private workflowContext;
+    /** Use inside `run()` and step-execution paths. Category: `runtime` */
+    readonly runtime: CategoryLogger;
+    /** Use inside `explain()` and `validate()` paths. Category: `analysis` */
+    readonly analysis: CategoryLogger;
+    /** Use for engine init, shutdown, adapter registration. Category: `system` */
+    readonly system: CategoryLogger;
+    /** Use for reserved-field violations, permission rejections. Category: `security` */
+    readonly security: CategoryLogger;
     constructor(config: EngineLoggerConfig);
     /**
      * Log a debug message
      */
+    debug(message: string, context?: Record<string, unknown>): void;
     /**
-     * Log a debug message (category and source required)
-     */
-    debug(message: string, context?: Record<string, unknown>, category?: LogCategory, source?: string): void;
-    /**
-     * Log an info message (category and source required)
-     */
-    info(message: string, context?: Record<string, unknown>, category?: LogCategory, source?: string): void;
-    /**
-     * Log a warning message (category and source required)
-     */
-    warn(message: string, context?: Record<string, unknown>, category?: LogCategory, source?: string): void;
-    /**
-     * Log an error message (category and source required)
-     */
-    error(message: string, error?: Error, context?: Record<string, unknown>, category?: LogCategory, source?: string): void;
-    /**
-     * Log a fatal error message (category and source required)
+     * Log an info message
      */
-    fatal(message: string, error?: Error, context?: Record<string, unknown>, category?: LogCategory, source?: string): void;
+    info(message: string, context?: Record<string, unknown>): void;
     /**
-     * Log workflow started event
+     * Log a warning message
      */
+    warn(message: string, context?: Record<string, unknown>): void;
     /**
-     * Log workflow started event (runtime phase)
+     * Log an error message
      */
-    workflowStarted(workflowName: string, context?: Record<string, unknown>): void;
-    /**
-     * Log workflow completed event
-     */
-    /**
-     * Log workflow completed event (runtime phase)
-     */
-    workflowCompleted(workflowName: string, duration: number, context?: Record<string, unknown>): void;
-    /**
-     * Log workflow failed event
-     */
-    /**
-     * Log workflow failed event (runtime phase)
-     */
-    workflowFailed(workflowName: string, error: Error, duration: number, context?: Record<string, unknown>): void;
-    /**
-     * Log workflow validation event
-     */
-    /**
-     * Log workflow validation event (analysis phase)
-     */
-    workflowValidation(workflowName: string, isValid: boolean, errors?: string[]): void;
-    /**
-     * Log step started event
-     */
-    /**
-     * Log step started event (runtime phase)
-     */
-    stepStarted(stepId: string, stepName: string, context?: Record<string, unknown>): void;
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
     /**
-     * Log step completed event
+     * Log a fatal error message
      */
+    fatal(message: string, error?: Error, context?: Record<string, unknown>): void;
     /**
-     * Log step completed event (runtime phase)
-     */
-    stepCompleted(stepId: string, stepName: string, duration: number, context?: Record<string, unknown>): void;
-    /**
-     * Log step failed event
-     */
-    /**
-     * Log step failed event (runtime phase)
-     */
-    stepFailed(stepId: string, stepName: string, error: Error, context?: Record<string, unknown>): void;
-    /**
-     * Log step retry event
-     */
-    /**
-     * Log step retry event (runtime phase)
-     */
-    stepRetry(stepId: string, stepName: string, attempt: number, maxAttempts: number): void;
-    /**
-     * Log step timeout event
-     */
-    /**
-     * Log step timeout event (runtime phase)
-     */
-    stepTimeout(stepId: string, stepName: string, timeout: number): void;
-    /**
-     * Log explanation generated event
-     */
-    /**
-     * Log explanation generated event (analysis phase)
-     */
-    explanationGenerated(workflowName: string, stepCount: number, strategy: string): void;
-    /**
-     * Log circular dependencies detected
-     */
-    /**
-     * Log circular dependencies detected (analysis phase)
-     */
-    explanationCycles(workflowName: string, cycles: string[][]): void;
-    /**
-     * Log adapter loaded event
-     */
-    /**
-     * Log adapter loaded event (system phase)
-     */
-    adapterLoaded(adapterName: string, version?: string): void;
-    /**
-     * Log adapter failed event
-     */
-    /**
-     * Log adapter failed event (system phase)
+     * Log with a custom level
      */
-    adapterFailed(adapterName: string, error: Error): void;
+    logWithLevel(level: LogLevel, message: string, context?: Record<string, unknown>): void;
     /**
-     * Log plugin installed event
+     * Log only if severity meets minimum threshold
      */
+    logIfSeverity(minSeverity: number, level: LogLevel, message: string, context?: Record<string, unknown>): void;
     /**
-     * Log plugin installed event (system phase)
+     * Measure and log execution time with appropriate log level based on duration.
+     *
+     * Pass `category` to override (`'runtime'` during `run()`, `'analysis'` during `explain()`).
+     * Prefer `logger.runtime.measureExecution(...)` or `logger.analysis.measureExecution(...)`.
      */
-    pluginInstalled(pluginName: string, source: string): void;
+    measureExecution<T>(label: string, fn: () => Promise<T>, thresholds?: {
+        warn?: number;
+        error?: number;
+    }, category?: LogCategory): Promise<T>;
     /**
-     * Log plugin verified event
+     * Central log dispatcher — used directly by `CategoryLogger` sub-loggers
+     * and by the private `log()` helper below.
+     *
+     * @param level            - Severity level
+     * @param message          - Human-readable message
+     * @param context          - Optional key-value metadata (merged with workflow ctx)
+     * @param error            - Optional error object
+     * @param categoryOverride - Pin to a specific category (defaults to config category)
+     * @param typeOverride     - Explicit `EngineLogType`; inferred from level when omitted
+     *
+     * @internal  Called via sub-loggers (`runtime`, `analysis`, etc.) or internally.
      */
+    _logWithCategory(level: LogLevel, message: string, context?: Record<string, unknown>, error?: Error, categoryOverride?: LogCategory, typeOverride?: EngineLogType): void;
     /**
-     * Log plugin verified event (system phase)
+     * Private shorthand — uses the default category from config.
+     * Prefer the categorised sub-loggers (`runtime`, `analysis`, etc.) for new code.
      */
-    pluginVerified(pluginName: string, verified: boolean): void;
+    private log;
     /**
-     * Log error detected event
+     * Export collected logs as a structured ExportedLogs object.
+     * Includes `byCategory` statistics and the active `workflowContext` snapshot.
      */
+    exportLogs(): ExportedLogs;
     /**
-     * Log error detected event (security phase)
+     * Get all collected logs as a JSON string
      */
-    errorDetected(error: Error, context?: Record<string, unknown>): void;
+    getJSONLogs(): string;
     /**
-     * Log error debugged event (with debugging info)
+     * Clear the log history (does NOT clear the workflow context)
      */
+    clearHistory(): void;
     /**
-     * Log error debugged event (security phase)
+     * Attach workflow context so every subsequent log entry automatically
+     * includes a `workflow` field.  Call this before `run()`, `explain()`,
+     * or `validate()` with the parsed workflow data.
+     *
+     * ```typescript
+     * logger.setWorkflowContext({
+     *   name:        workflow.name,
+     *   version:     workflow.version,
+     *   kind:        workflow.kind,
+     *   stepCount:   workflow.steps.length,
+     *   filePath:    resolvedPath,
+     * });
+     * ```
      */
-    errorDebugged(error: Error, debugInfo: {
-        explanation: string;
-        fixSteps: string[];
-    }): void;
+    setWorkflowContext(ctx: WorkflowContext): void;
     /**
-     * Log validation error event
+     * Detach the workflow context (e.g. after a run completes).
+     * Logs emitted after this call will no longer include the `workflow` field.
      */
+    clearWorkflowContext(): void;
     /**
-     * Log validation error event (analysis phase)
+     * Returns a read-only snapshot of the currently active workflow context,
+     * or `null` if none has been set.
      */
-    validationError(message: string, errors: string[]): void;
+    getWorkflowContext(): Readonly<WorkflowContext> | null;
     /**
-     * Log performance metric
+     * Partially update the active workflow context without replacing it.
+     * Only the supplied fields are merged in; the rest are preserved.
+     *
+     * Useful for enriching the context mid-run (e.g. after the execution
+     * strategy is determined):
+     *
+     * ```typescript
+     * logger.patchWorkflowContext({ executionStrategy: 'parallel' });
+     * ```
+     *
+     * If no context has been set yet, the patch is applied as if it were
+     * a fresh `setWorkflowContext` call.
      */
+    patchWorkflowContext(partial: Partial<WorkflowContext>): void;
     /**
-     * Log performance metric (system phase)
+     * Build a log-context object for a step event.
+     *
+     * Use this wherever you log step lifecycle events so context is consistent:
+     * ```typescript
+     * logger.runtime.info('Step started', logger.stepCtx({ id: step.id, adapter: step.adapter }));
+     * logger.runtime.error('Step failed', error, logger.stepCtx({ id: step.id, adapter: step.adapter }));
+     * ```
+     */
+    stepCtx(step: {
+        id: string;
+        adapter?: string;
+        name?: string;
+        [extra: string]: unknown;
+    }): Record<string, unknown>;
+    /**
+     * Build a log-context object for a workflow-level event.
+     *
+     * Returns a flat object suitable for passing as `context` to any log call.
+     * If no workflow context is set, returns `{}`.
+     *
+     * ```typescript
+     * logger.system.info('Workflow validated', logger.workflowCtx());
+     * ```
      */
-    performanceMetric(label: string, metrics: {
-        duration?: number;
-        memory?: number;
-        cpu?: number;
-    }): void;
+    workflowCtx(): Record<string, unknown>;
     /**
-     * Log execution time
+     * Log workflow execution started (runtime category).
+     * Called at the top of `WorkflowExecutor.execute()`.
      */
+    workflowStarted(workflowName: string, context?: Record<string, unknown>): void;
     /**
-     * Log execution time (runtime phase)
+     * Log a workflow input field that was resolved (runtime category).
      */
-    executionTime(label: string, duration: number, context?: Record<string, unknown>): void;
+    inputProcessed(key: string, value: unknown, source: string): void;
     /**
-     * Log field execution - captures every field that gets executed
-     * This enables dynamic explanation generation from runtime logs
+     * Log a context field used during execution (runtime category).
      */
-    fieldExecution(type: string, field: string, value: any, context?: Record<string, unknown>): void;
+    fieldExecution(fieldType: string, key: string, value: unknown): void;
     /**
-     * Log input processing
+     * Log step execution started (runtime category).
+     * ```typescript
+     * logger.stepStarted(step.id, step.name, { adapter: step.adapter });
+     * ```
      */
-    inputProcessed(inputName: string, value: any, source: string): void;
+    stepStarted(stepId: string, stepName: string, context?: Record<string, unknown>): void;
     /**
-     * Log output generation
+     * Log step execution completed (runtime category).
      */
-    outputGenerated(outputName: string, value: any, step?: string): void;
+    stepCompleted(stepId: string, stepName: string, duration: number, context?: Record<string, unknown>): void;
     /**
-     * Log context variable access
+     * Log step timeout (runtime category).
      */
-    contextAccessed(variable: string, value: any, step: string): void;
+    stepTimeout(stepId: string, stepName: string, timeoutMs: number): void;
     /**
-     * Log secret access (without exposing values)
+     * Log step retry attempt (runtime category).
      */
-    secretAccessed(secretKey: string, step: string): void;
+    stepRetry(stepId: string, stepName: string, attempt: number, maxAttempts: number): void;
     /**
-     * Log variable resolution
+     * Log step failure after all attempts (runtime category).
      */
-    variableResolved(variable: string, resolvedValue: any, context: Record<string, unknown>): void;
+    stepFailed(stepId: string, stepName: string, error: Error, context?: Record<string, unknown>): void;
     /**
-     * Log adapter action execution
+     * Log adapter action execution result (runtime category).
      */
     adapterActionExecuted(adapter: string, action: string, duration: number, success: boolean): void;
     /**
-     * Log parsing start
+     * Log validation phase started (analysis category).
      */
-    parsingStarted(source: string, format: string): void;
+    validationStarted(type: string, schema: string): void;
     /**
-     * Log parsing success
+     * Log validation passed (analysis category).
      */
-    parsingCompleted(source: string, duration: number, stats?: Record<string, unknown>): void;
+    validationPassed(type: string, schema: string): void;
     /**
-     * Log parsing error
+     * Log validation failure (analysis category).
      */
-    parsingFailed(source: string, error: Error, context?: Record<string, unknown>): void;
+    validationFailed(type: string, schema: string, errors: string[]): void;
     /**
-     * Log validation start
+     * Log parsing started (analysis category).
      */
-    validationStarted(target: string, type: string): void;
+    parsingStarted(format: string, source: string): void;
     /**
-     * Log validation success
+     * Log parsing completed (analysis category).
      */
-    validationPassed(target: string, type: string, duration?: number): void;
+    parsingCompleted(format: string, duration: number, context?: Record<string, unknown>): void;
     /**
-     * Log validation failure
+     * Log parsing failure (analysis category).
      */
-    validationFailed(target: string, type: string, errors: string[]): void;
+    parsingFailed(format: string, error: Error, context?: Record<string, unknown>): void;
     /**
-     * Log error enrichment (when ErrorDetector adds debugging info)
-     */
-    errorEnriched(error: Error, debugInfo: Record<string, unknown>): void;
-    /**
-     * Log error debugging output
-     */
-    errorDebugOutput(error: Error, explanation: string, fixSteps: string[]): void;
-    /**
-     * Log execution phase start
-     */
-    phaseStarted(phase: number, stepIds: string[]): void;
-    /**
-     * Log execution phase completion
-     */
-    phaseCompleted(phase: number, duration: number, successCount: number, failureCount: number): void;
-    /**
-     * Format value for logging (truncate large values)
-     */
-    private formatValue;
-    /**
-     * Sanitize value for logging (remove sensitive data)
-     */
-    private sanitizeValue;
-    /**
-     * Check if field name suggests sensitive data
-     */
-    private isSensitiveField;
-    /**
-     * Log with a custom level
-     */
-    logWithLevel(level: LogLevel, message: string, context?: Record<string, unknown>): void;
-    /**
-     * Log only if severity meets minimum threshold
-     */
-    logIfSeverity(minSeverity: number, level: LogLevel, message: string, context?: Record<string, unknown>): void;
-    /**
-     * Measure and log execution time with appropriate log level based on duration
-     */
-    measureExecution<T>(label: string, fn: () => Promise<T>, thresholds?: {
-        warn?: number;
-        error?: number;
-    }): Promise<T>;
-    /**
-     * Log a structured engine event (category and source required)
-     * Uses EngineLog interface for strong typing.
-     */
-    private logEvent;
-    /**
-     * Get appropriate log level for event type
-     */
-    private getLogLevelForEventType;
-    /**
-     * Emit event to registered listeners
-     */
-    private emitEvent;
-    /**
-     * Subscribe to specific log event types
-     */
-    on(type: EngineLogType, listener: (event: EngineLogEvent) => void): () => void;
-    /**
-     * Internal log method
-     */
-    /**
-     * Internal log method (category and source required)
-     */
-    /**
-     * Internal log method (category and source required)
-     * Uses EngineLog interface for strong typing.
+     * Emit a log with an explicit `EngineLogType`.
+     *
+     * Useful when you want the structured event type to be distinct from the
+     * generic level-based inference — e.g. to mark a `STEP_RETRY` event:
+     *
+     * ```typescript
+     * logger.logEvent(EngineLogType.STEP_RETRY, LogLevel.WARN, 'Retrying step', {
+     *   stepId: 'http-request',
+     *   attempt: 2,
+     * }, 'runtime');
+     * ```
      */
-    private log;
+    logEvent(type: EngineLogType, level: LogLevel, message: string, context?: Record<string, unknown>, category?: LogCategory): void;
     /**
-     * Map LogLevel to EngineLogType
-     */
+     * Return log events that match every supplied filter field.
+     * Omit a field to skip that filter.
+     *
+     * ```typescript
+     * // All runtime errors for the current workflow
+     * logger.filterHistory({ category: 'runtime', withErrors: true });
+     *
+     * // All analysis events since the explain started
+     * const since = new Date();
+     * logger.filterHistory({ category: 'analysis', since });
+     * ```
+     */
+    filterHistory(filter?: {
+        category?: LogCategory;
+        type?: EngineLogType;
+        since?: Date;
+        until?: Date;
+        source?: string;
+        /** Filter to logs that contain a specific workflow name */
+        workflowName?: string;
+        /** Only return events that have an error attached */
+        withErrors?: boolean;
+    }): EngineLogEvent[];
     /**
-     * Map LogLevel to string for EngineLog.level
+     * Return all history entries grouped by category.
+     * Convenience wrapper around `filterHistory`.
      */
-    private mapLogLevelToString;
+    getHistoryByCategory(): Record<LogCategory, EngineLogEvent[]>;
     /**
      * Check if a level should be logged using severity comparison
      */
@@ -427,102 +429,15 @@ export declare class EngineLogger {
      * Check if error logging is enabled
      */
     isErrorEnabled(): boolean;
-    /**
-     * Add event to JSON log buffer
-     */
-    private addToBuffer;
-    /**
-     * Get all logs as JSON array
-     * This is what CLI, API, dashboards, and explanation system will consume
-     */
-    getJSONLogs(): EngineLogEvent[];
-    /**
-     * Get logs filtered by type
-     */
-    getLogsByType(type: EngineLogType): EngineLogEvent[];
-    /**
-     * Get logs filtered by time range
-     */
-    getLogsByTimeRange(startTime: Date, endTime: Date): EngineLogEvent[];
-    /**
-     * Get logs filtered by multiple criteria
-     */
-    getLogsFiltered(filter: {
-        types?: EngineLogType[];
-        startTime?: Date;
-        endTime?: Date;
-        hasError?: boolean;
-        searchText?: string;
-    }): EngineLogEvent[];
-    /**
-     * Get logs by category: Parse events
-     */
-    getParseLogEvents(): ParseLogEvent[];
-    /**
-     * Get logs by category: Validation events
-     */
-    getValidationLogEvents(): ValidationLogEvent[];
-    /**
-     * Get logs by category: Execution events
-     */
-    getExecutionLogEvents(): ExecutionLogEvent[];
-    /**
-     * Get logs by category: Error events
-     */
-    getErrorLogEvents(): ErrorLogEvent[];
-    /**
-     * Get logs by category: Lifecycle events
-     */
-    getLifecycleLogEvents(): LifecycleLogEvent[];
-    /**
-     * Get logs by category: Performance events
-     */
-    getPerformanceLogEvents(): PerformanceLogEvent[];
-    /**
-     * Export logs as formatted JSON string
-     */
-    exportLogsAsJSON(pretty?: boolean): string;
-    /**
-     * Export logs grouped by type
-     */
-    exportLogsGrouped(): Record<string, EngineLogEvent[]>;
-    /**
-     * Get log statistics
-     */
-    getLogStats(): {
-        total: number;
-        byType: Record<string, number>;
-        withErrors: number;
-        withMetrics: number;
-        timeRange: {
-            first?: Date;
-            last?: Date;
-        };
-    };
-    /**
-     * Clear log buffer
-     */
-    clearLogs(): void;
-    /**
-     * Set maximum buffer size
-     */
-    setMaxBufferSize(size: number): void;
-    /**
-     * Get current buffer size
-     */
-    getBufferSize(): number;
-    /**
-     * Export logs in a comprehensive format for consumers (CLI, API, dashboards)
-     */
-    exportLogs(): ExportedLogs;
-    /**
-     * Build execution summary from collected logs
-     * This powers dynamic explanation generation
-     */
-    private buildExecutionSummary;
 }
 /**
  * Create a logger instance from engine config
  */
-export declare function createEngineLogger(config: EngineLoggerConfig): EngineLogger;
+export declare function createEngineLogger(logLevel: 'debug' | 'info' | 'warn' | 'error' | 'silent', verbose?: boolean): EngineLogger | null;
+export type { EngineLoggerConfig, EngineLogFormat };
+/**
+ * Re-export formatTimestamp for external use
+ * Allows other parts of the system to format timestamps consistently
+ */
+export { formatTimestamp };
 //# sourceMappingURL=EngineLogger.d.ts.map