@orbytautomation/engine 0.2.4 → 0.4.0

package/dist/errors/ErrorDetector.js

@@ -0,0 +1,370 @@
+/**
+ * Error Detector (Smart Error Classification)
+ *
+ * Automatically detects error types and assigns correct error codes.
+ * Makes the engine smart enough to classify errors without manual coding.
+ * Also enriches errors with debug information for developers.
+ *
+ * PHILOSOPHY:
+ * ==========
+ * Instead of manually throwing specific error codes everywhere,
+ * the detector analyzes the error context and assigns the right code.
+ * Debug information is automatically attached at detection time.
+ *
+ * USAGE:
+ * ======
+ * ```typescript
+ * // Instead of manual classification:
+ * if (field === 'version') {
+ *   throw SchemaError.missingField('version', 'workflow');
+ * }
+ *
+ * // Let detector classify automatically:
+ * const error = ErrorDetector.detect({
+ *   type: 'missing_field',
+ *   field: 'version',
+ *   location: 'workflow'
+ * });
+ * throw error; // Already has debug info attached!
+ * ```
+ *
+ * @module errors/detector
+ */
+import { SchemaError, ValidationError } from './WorkflowError.js';
+import { StepError } from './StepError.js';
+import { SecurityError } from './SecurityErrors.js';
+import { ErrorDebugger } from './ErrorDebugger.js';
+import { RESERVED_WORKFLOW_FIELDS, RESERVED_CONTEXT_FIELDS, RESERVED_STEP_FIELDS, RESERVED_ANNOTATION_PREFIXES, ROOT_FIELDS, WORKFLOW_FIELDS, STEP_FIELDS, CONTEXT_FIELDS, METADATA_FIELDS } from './FieldRegistry.js';
+import { findClosestMatch } from './TypoDetector.js';
+import { LoggerManager } from '../logging/LoggerManager.js';
+/**
+ * Error Detector
+ *
+ * Smart system that analyzes error context and produces correct OrbytError.
+ */
+export class ErrorDetector {
+    /**
+     * Detect and create appropriate error from context
+     *
+     * @param context - Error context with information about what went wrong
+     * @returns Properly classified OrbytError
+     *
+     * @example
+     * ```typescript
+     * const error = ErrorDetector.detect({
+     *   type: 'missing_field',
+     *   field: 'version',
+     *   location: 'workflow'
+     * });
+     * ```
+     */
+    /**
+     * Detect error from context and enrich with debug information
+     *
+     * This is the main entry point for error detection.
+     * All detected errors are automatically enriched with debug info.
+     *
+     * @param context - Error context
+     * @returns OrbytError with debug info attached
+     */
+    static detect(context) {
+        const logger = LoggerManager.getLogger();
+        let error;
+        logger.debug(`[ErrorDetector] Detecting error type: ${context.type}`, {
+            scenario: context.type,
+            field: context.field,
+            location: context.location,
+        });
+        // Auto-detect reserved fields
+        if (context.field && this.isReservedField(context.field)) {
+            error = this.handleReservedField(context);
+            logger.error(`[ErrorDetector] Reserved field detected: ${context.field}`, error, {
+                field: context.field,
+                location: context.location,
+            });
+            return this.enrichWithDebugInfo(error);
+        }
+        // Auto-detect reserved annotations
+        if (context.field && this.isReservedAnnotation(context.field)) {
+            error = SecurityError.reservedAnnotation(context.field, context.location || 'unknown');
+            logger.error(`[ErrorDetector] Reserved annotation detected: ${context.field}`, error);
+            return this.enrichWithDebugInfo(error);
+        }
+        // Dispatch to specific handlers based on scenario
+        switch (context.type) {
+            // Schema errors
+            case 'unknown_field':
+                error = this.handleUnknownField(context);
+                break;
+            case 'reserved_field':
+                error = this.handleReservedField(context);
+                break;
+            case 'invalid_type':
+                error = this.handleInvalidType(context);
+                break;
+            case 'missing_field':
+                error = this.handleMissingField(context);
+                break;
+            case 'invalid_enum':
+                error = this.handleInvalidEnum(context);
+                break;
+            case 'parse_error':
+                error = this.handleParseError(context);
+                break;
+            case 'invalid_adapter':
+                error = this.handleInvalidAdapter(context);
+                break;
+            // Validation errors
+            case 'duplicate_id':
+                error = this.handleDuplicateId(context);
+                break;
+            case 'unknown_step':
+                error = this.handleUnknownStep(context);
+                break;
+            case 'circular_dependency':
+                error = this.handleCircularDependency(context);
+                break;
+            case 'forward_reference':
+                error = this.handleForwardReference(context);
+                break;
+            case 'empty_workflow':
+                error = ValidationError.emptyWorkflow(context.location || 'workflow');
+                break;
+            case 'missing_input':
+                error = this.handleMissingInput(context);
+                break;
+            case 'invalid_condition':
+                error = this.handleInvalidCondition(context);
+                break;
+            case 'invalid_variable':
+                error = this.handleInvalidVariable(context);
+                break;
+            // Step errors
+            case 'step_not_found':
+                error = StepError.notFound(context.field || 'unknown', context.location || 'unknown');
+                break;
+            case 'step_timeout':
+                error = this.handleStepTimeout(context);
+                break;
+            case 'step_failed':
+                error = this.handleStepFailed(context);
+                break;
+            case 'step_dependency_failed':
+                error = this.handleStepDependencyFailed(context);
+                break;
+            case 'step_invalid_config':
+                error = this.handleStepInvalidConfig(context);
+                break;
+            // Security errors
+            case 'permission_denied':
+                error = this.handlePermissionDenied(context);
+                break;
+            // Unknown/generic
+            default:
+                error = this.handleUnknown(context);
+        }
+        // Enrich with debug information before returning
+        return this.enrichWithDebugInfo(error);
+    }
+    /**
+     * Detect error from raw exception
+     * Analyzes exception and tries to classify it
+     *
+     * @param error - Raw error/exception
+     * @param location - Where the error occurred
+     * @returns Classified OrbytError with debug info
+     */
+    static detectFromException(error, location) {
+        const message = error.message.toLowerCase();
+        const stack = error.stack;
+        // Try to detect error type from message
+        let scenario = 'unknown';
+        if (message.includes('yaml') || message.includes('parse') || message.includes('syntax')) {
+            scenario = 'parse_error';
+        }
+        else if (message.includes('unknown field') || message.includes('unexpected field')) {
+            scenario = 'unknown_field';
+        }
+        else if (message.includes('missing') || message.includes('required')) {
+            scenario = 'missing_field';
+        }
+        else if (message.includes('type') || message.includes('expected')) {
+            scenario = 'invalid_type';
+        }
+        else if (message.includes('circular') || message.includes('cycle')) {
+            scenario = 'circular_dependency';
+        }
+        else if (message.includes('duplicate')) {
+            scenario = 'duplicate_id';
+        }
+        else if (message.includes('timeout')) {
+            scenario = 'step_timeout';
+        }
+        else if (message.includes('permission') || message.includes('denied')) {
+            scenario = 'permission_denied';
+        }
+        // Use detect() which automatically enriches with debug info
+        return this.detect({
+            type: scenario,
+            location,
+            rawMessage: error.message,
+            stack,
+        });
+    }
+    // ==================== HELPER METHODS ====================
+    /**
+     * Check if field is reserved by engine
+     */
+    static isReservedField(field) {
+        return (RESERVED_WORKFLOW_FIELDS.includes(field) ||
+            RESERVED_CONTEXT_FIELDS.includes(field) ||
+            RESERVED_STEP_FIELDS.includes(field) ||
+            field.startsWith('_') ||
+            field.startsWith('__'));
+    }
+    /**
+     * Check if annotation uses reserved namespace
+     */
+    static isReservedAnnotation(annotation) {
+        return RESERVED_ANNOTATION_PREFIXES.some(prefix => annotation.startsWith(prefix));
+    }
+    /**
+     * Determine field type for security errors
+     */
+    static getFieldType(field) {
+        if (field.includes('billing') || field.includes('price') || field.includes('cost')) {
+            return 'billing';
+        }
+        if (field.includes('execution') || field.includes('run') || field.includes('workflow')) {
+            return 'execution';
+        }
+        if (field.includes('user') || field.includes('org') || field.includes('owner')) {
+            return 'identity';
+        }
+        if (field.includes('usage') || field.includes('counter') || field.includes('consumed')) {
+            return 'usage';
+        }
+        return 'internal';
+    }
+    // ==================== ERROR HANDLERS ====================
+    static handleUnknownField(context) {
+        const field = context.field || 'unknown';
+        const location = context.location || 'unknown';
+        // Get valid fields based on location
+        const validFields = this.getValidFieldsForLocation(location);
+        // Use TypoDetector to find closest match
+        const suggestion = findClosestMatch(field, validFields, 0.6);
+        return SchemaError.unknownField(field, location, suggestion);
+    }
+    /**
+     * Get valid field names based on location in workflow
+     */
+    static getValidFieldsForLocation(location) {
+        const locationLower = location.toLowerCase();
+        // Root level fields
+        if (locationLower === 'workflow' || locationLower.startsWith('workflow.')) {
+            if (locationLower.includes('steps[') || locationLower.includes('.step')) {
+                return [...STEP_FIELDS];
+            }
+            if (locationLower.includes('context')) {
+                return [...CONTEXT_FIELDS];
+            }
+            if (locationLower.includes('metadata')) {
+                return [...METADATA_FIELDS];
+            }
+            return [...ROOT_FIELDS, ...WORKFLOW_FIELDS];
+        }
+        // Step fields
+        if (locationLower.includes('step')) {
+            return [...STEP_FIELDS];
+        }
+        // Default: return all common fields
+        return [
+            ...ROOT_FIELDS,
+            ...WORKFLOW_FIELDS,
+            ...STEP_FIELDS,
+            ...CONTEXT_FIELDS,
+            ...METADATA_FIELDS
+        ];
+    }
+    static handleReservedField(context) {
+        const field = context.field || 'unknown';
+        const fieldType = this.getFieldType(field);
+        return SecurityError.reservedFieldOverride(field, context.location || 'unknown', fieldType);
+    }
+    static handleInvalidType(context) {
+        return SchemaError.invalidType(context.field || 'unknown', context.expected || 'unknown', context.actual || 'unknown', context.location || 'unknown');
+    }
+    static handleMissingField(context) {
+        return SchemaError.missingField(context.field || 'unknown', context.location || 'unknown');
+    }
+    static handleInvalidEnum(context) {
+        const validValues = context.data?.validValues || [];
+        return SchemaError.invalidEnum(context.field || 'unknown', context.actual || 'unknown', validValues, context.location || 'unknown');
+    }
+    static handleParseError(context) {
+        return SchemaError.parseError(context.location || 'unknown', context.data?.line, context.data?.column, context.rawMessage);
+    }
+    static handleInvalidAdapter(context) {
+        return SchemaError.invalidAdapter(context.field || context.actual || 'unknown', context.location || 'unknown', context.data?.validAdapters);
+    }
+    static handleDuplicateId(context) {
+        return ValidationError.duplicateId(context.field || 'unknown', context.location || 'unknown', context.data?.firstOccurrence);
+    }
+    static handleUnknownStep(context) {
+        return ValidationError.unknownStep(context.field || 'unknown', context.location || 'unknown', context.data?.availableSteps);
+    }
+    static handleCircularDependency(context) {
+        const cycle = context.data?.cycle || [context.field || 'unknown'];
+        return ValidationError.circularDependency(cycle, context.location || 'unknown');
+    }
+    static handleForwardReference(context) {
+        return ValidationError.forwardReference(context.field || 'unknown', context.data?.referencedStep || 'unknown', context.location || 'unknown');
+    }
+    static handleMissingInput(context) {
+        return ValidationError.missingInput(context.field || 'unknown', context.location || 'unknown');
+    }
+    static handleInvalidCondition(context) {
+        return ValidationError.invalidCondition(context.actual || context.rawMessage || 'unknown', context.location || 'unknown', context.data?.reason);
+    }
+    static handleInvalidVariable(context) {
+        return ValidationError.invalidVariable(context.field || 'unknown', context.location || 'unknown', context.data?.availableVars);
+    }
+    static handleStepTimeout(context) {
+        return StepError.timeout(context.field || 'unknown', context.location || 'unknown', context.data?.timeout);
+    }
+    static handleStepFailed(context) {
+        const error = context.rawMessage ? new Error(context.rawMessage) : new Error('Step execution failed');
+        return StepError.executionFailed(context.field || 'unknown', context.location || 'unknown', error, context.data?.exitCode);
+    }
+    static handleStepDependencyFailed(context) {
+        return StepError.dependencyFailed(context.field || 'unknown', context.data?.dependency || 'unknown', context.location || 'unknown');
+    }
+    static handleStepInvalidConfig(context) {
+        return StepError.invalidConfig(context.field || 'unknown', context.location || 'unknown', context.rawMessage);
+    }
+    static handlePermissionDenied(context) {
+        return SecurityError.permissionDenied(context.field || context.data?.resource || 'unknown', context.location || 'unknown', context.data?.requiredPermission);
+    }
+    static handleUnknown(context) {
+        // Create generic schema error for unknown cases
+        return SchemaError.parseError(context.location || 'unknown', undefined, undefined, context.rawMessage || 'Unknown error occurred');
+    }
+    /**
+     * Enrich error with debug information
+     *
+     * This is called automatically after error detection to attach
+     * detailed debug info including explanations, fix steps, examples, etc.
+     *
+     * @param error - Detected OrbytError
+     * @returns Same error with debug info attached (for console display)
+     * @private
+     */
+    static enrichWithDebugInfo(error) {
+        // Generate and store formatted debug output for console display
+        // This is done here so it's available when needed in WorkflowLoader
+        error.__debugOutput = ErrorDebugger.format(error);
+        return error;
+    }
+}
+//# sourceMappingURL=ErrorDetector.js.map

package/dist/errors/ErrorDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorDetector.js","sourceRoot":"","sources":["../../src/errors/ErrorDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACH,wBAAwB,EACxB,uBAAuB,EACvB,oBAAoB,EACpB,4BAA4B,EAC5B,WAAW,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,eAAe,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAsE5D;;;;GAIG;AACH,MAAM,OAAO,aAAa;IACtB;;;;;;;;;;;;;;OAcG;IACH;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,CAAC,OAAqB;QAC/B,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,EAAE,CAAC;QACzC,IAAI,KAAiB,CAAC;QAEtB,MAAM,CAAC,KAAK,CAAC,yCAAyC,OAAO,CAAC,IAAI,EAAE,EAAE;YAClE,QAAQ,EAAE,OAAO,CAAC,IAAI;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC7B,CAAC,CAAC;QAEH,8BAA8B;QAC9B,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvD,KAAK,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;YAC1C,MAAM,CAAC,KAAK,CAAC,4CAA4C,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE;gBAC7E,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC7B,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QAC3C,CAAC;QAED,mCAAmC;QACnC,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5D,KAAK,GAAG,aAAa,CAAC,kBAAkB,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC,CAAC;YACvF,MAAM,CAAC,KAAK,CAAC,iDAAiD,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;YACtF,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QAC3C,CAAC;QAED,kDAAkD;QAClD,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACnB,gBAAgB;YAChB,KAAK,eAAe;gBAChB,KAAK,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;gBACzC,MAAM;YACV,KAAK,gBAAgB;gBACjB,KAAK,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;gBAC1C,MAAM;YACV,KAAK,cAAc;gBACf,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBACxC,MAAM;YACV,KAAK,eAAe;gBAChB,KAAK,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;gBACzC,MAAM;YACV,KAAK,cAAc;gBACf,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBACxC,MAAM;YACV,KAAK,aAAa;gBACd,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBACvC,MAAM;YACV,KAAK,iBAAiB;gBAClB,KAAK,GAAG,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;gBAC3C,MAAM;YAEV,oBAAoB;YACpB,KAAK,cAAc;gBACf,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBACxC,MAAM;YACV,KAAK,cAAc;gBACf,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBACxC,MAAM;YACV,KAAK,qBAAqB;gBACtB,KAAK,GAAG,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC;gBAC/C,MAAM;YACV,KAAK,mBAAmB;gBACpB,KAAK,GAAG,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;gBAC7C,MAAM;YACV,KAAK,gBAAgB;gBACjB,KAAK,GAAG,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,IAAI,UAAU,CAAC,CAAC;gBACtE,MAAM;YACV,KAAK,eAAe;gBAChB,KAAK,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;gBACzC,MAAM;YACV,KAAK,mBAAmB;gBACpB,KAAK,GAAG,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;gBAC7C,MAAM;YACV,KAAK,kBAAkB;gBACnB,KAAK,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;gBAC5C,MAAM;YAEV,cAAc;YACd,KAAK,gBAAgB;gBACjB,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC,CAAC;gBACtF,MAAM;YACV,KAAK,cAAc;gBACf,KAAK,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBACxC,MAAM;YACV,KAAK,aAAa;gBACd,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBACvC,MAAM;YACV,KAAK,wBAAwB;gBACzB,KAAK,GAAG,IAAI,CAAC,0BAA0B,CAAC,OAAO,CAAC,CAAC;gBACjD,MAAM;YACV,KAAK,qBAAqB;gBACtB,KAAK,GAAG,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC;gBAC9C,MAAM;YAEV,kBAAkB;YAClB,KAAK,mBAAmB;gBACpB,KAAK,GAAG,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;gBAC7C,MAAM;YAEV,kBAAkB;YAClB;gBACI,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QAED,iDAAiD;QACjD,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAY,EAAE,QAAiB;QACtD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAE1B,wCAAwC;QACxC,IAAI,QAAQ,GAAkB,SAAS,CAAC;QAExC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtF,QAAQ,GAAG,aAAa,CAAC;QAC7B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;YACnF,QAAQ,GAAG,eAAe,CAAC;QAC/B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACrE,QAAQ,GAAG,eAAe,CAAC;QAC/B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAClE,QAAQ,GAAG,cAAc,CAAC;QAC9B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACnE,QAAQ,GAAG,qBAAqB,CAAC;QACrC,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YACvC,QAAQ,GAAG,cAAc,CAAC;QAC9B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,QAAQ,GAAG,cAAc,CAAC;QAC9B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtE,QAAQ,GAAG,mBAAmB,CAAC;QACnC,CAAC;QAED,4DAA4D;QAC5D,OAAO,IAAI,CAAC,MAAM,CAAC;YACf,IAAI,EAAE,QAAQ;YACd,QAAQ;YACR,UAAU,EAAE,KAAK,CAAC,OAAO;YACzB,KAAK;SACR,CAAC,CAAC;IACP,CAAC;IAED,2DAA2D;IAE3D;;OAEG;IACK,MAAM,CAAC,eAAe,CAAC,KAAa;QACxC,OAAO,CACF,wBAA8C,CAAC,QAAQ,CAAC,KAAK,CAAC;YAC9D,uBAA6C,CAAC,QAAQ,CAAC,KAAK,CAAC;YAC7D,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC;YAC3D,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YACrB,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CACzB,CAAC;IACN,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,oBAAoB,CAAC,UAAkB;QAClD,OAAO,4BAA4B,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACtF,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,YAAY,CAAC,KAAa;QACrC,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACjF,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACrF,OAAO,WAAW,CAAC;QACvB,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7E,OAAO,UAAU,CAAC;QACtB,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACrF,OAAO,OAAO,CAAC;QACnB,CAAC;QACD,OAAO,UAAU,CAAC;IACtB,CAAC;IAED,2DAA2D;IAEnD,MAAM,CAAC,kBAAkB,CAAC,OAAqB;QACnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC;QACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC;QAE/C,qCAAqC;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC;QAE7D,yCAAyC;QACzC,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;QAE7D,OAAO,WAAW,CAAC,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACjE,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,yBAAyB,CAAC,QAAgB;QACrD,MAAM,aAAa,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QAE7C,oBAAoB;QACpB,IAAI,aAAa,KAAK,UAAU,IAAI,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACxE,IAAI,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACtE,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC;YAC5B,CAAC;YACD,IAAI,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBACpC,OAAO,CAAC,GAAG,cAAc,CAAC,CAAC;YAC/B,CAAC;YACD,IAAI,aAAa,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBACrC,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC;YAChC,CAAC;YACD,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,eAAe,CAAC,CAAC;QAChD,CAAC;QAED,cAAc;QACd,IAAI,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC;QAC5B,CAAC;QAED,oCAAoC;QACpC,OAAO;YACH,GAAG,WAAW;YACd,GAAG,eAAe;YAClB,GAAG,WAAW;YACd,GAAG,cAAc;YACjB,GAAG,eAAe;SACrB,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,mBAAmB,CAAC,OAAqB;QACpD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC;QACzC,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC3C,OAAO,aAAa,CAAC,qBAAqB,CACtC,KAAK,EACL,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,SAAS,CACZ,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,iBAAiB,CAAC,OAAqB;QAClD,OAAO,WAAW,CAAC,WAAW,CAC1B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,MAAM,IAAI,SAAS,EAC3B,OAAO,CAAC,QAAQ,IAAI,SAAS,CAChC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,kBAAkB,CAAC,OAAqB;QACnD,OAAO,WAAW,CAAC,YAAY,CAC3B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,CAChC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,iBAAiB,CAAC,OAAqB;QAClD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,WAAW,IAAI,EAAE,CAAC;QACpD,OAAO,WAAW,CAAC,WAAW,CAC1B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,MAAM,IAAI,SAAS,EAC3B,WAAW,EACX,OAAO,CAAC,QAAQ,IAAI,SAAS,CAChC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,gBAAgB,CAAC,OAAqB;QACjD,OAAO,WAAW,CAAC,UAAU,CACzB,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,IAAI,EAClB,OAAO,CAAC,IAAI,EAAE,MAAM,EACpB,OAAO,CAAC,UAAU,CACrB,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,oBAAoB,CAAC,OAAqB;QACrD,OAAO,WAAW,CAAC,cAAc,CAC7B,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,IAAI,SAAS,EAC5C,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,aAAa,CAC9B,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,iBAAiB,CAAC,OAAqB;QAClD,OAAO,eAAe,CAAC,WAAW,CAC9B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,eAAe,CAChC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,iBAAiB,CAAC,OAAqB;QAClD,OAAO,eAAe,CAAC,WAAW,CAC9B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,cAAc,CAC/B,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,wBAAwB,CAAC,OAAqB;QACzD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;QAClE,OAAO,eAAe,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,IAAI,SAAS,CAAC,CAAC;IACpF,CAAC;IAEO,MAAM,CAAC,sBAAsB,CAAC,OAAqB;QACvD,OAAO,eAAe,CAAC,gBAAgB,CACnC,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,IAAI,EAAE,cAAc,IAAI,SAAS,EACzC,OAAO,CAAC,QAAQ,IAAI,SAAS,CAChC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,kBAAkB,CAAC,OAAqB;QACnD,OAAO,eAAe,CAAC,YAAY,CAC/B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,CAChC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,sBAAsB,CAAC,OAAqB;QACvD,OAAO,eAAe,CAAC,gBAAgB,CACnC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,IAAI,SAAS,EACjD,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,CACvB,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,qBAAqB,CAAC,OAAqB;QACtD,OAAO,eAAe,CAAC,eAAe,CAClC,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,aAAa,CAC9B,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,iBAAiB,CAAC,OAAqB;QAClD,OAAO,SAAS,CAAC,OAAO,CACpB,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,OAAO,CACxB,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,gBAAgB,CAAC,OAAqB;QACjD,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACtG,OAAO,SAAS,CAAC,eAAe,CAC5B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,KAAK,EACL,OAAO,CAAC,IAAI,EAAE,QAAQ,CACzB,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,0BAA0B,CAAC,OAAqB;QAC3D,OAAO,SAAS,CAAC,gBAAgB,CAC7B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,IAAI,EAAE,UAAU,IAAI,SAAS,EACrC,OAAO,CAAC,QAAQ,IAAI,SAAS,CAChC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,uBAAuB,CAAC,OAAqB;QACxD,OAAO,SAAS,CAAC,aAAa,CAC1B,OAAO,CAAC,KAAK,IAAI,SAAS,EAC1B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,UAAU,CACrB,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,sBAAsB,CAAC,OAAqB;QACvD,OAAO,aAAa,CAAC,gBAAgB,CACjC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,EAAE,QAAQ,IAAI,SAAS,EACpD,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,OAAO,CAAC,IAAI,EAAE,kBAAkB,CACnC,CAAC;IACN,CAAC;IAEO,MAAM,CAAC,aAAa,CAAC,OAAqB;QAC9C,gDAAgD;QAChD,OAAO,WAAW,CAAC,UAAU,CACzB,OAAO,CAAC,QAAQ,IAAI,SAAS,EAC7B,SAAS,EACT,SAAS,EACT,OAAO,CAAC,UAAU,IAAI,wBAAwB,CACjD,CAAC;IACN,CAAC;IAED;;;;;;;;;OASG;IACK,MAAM,CAAC,mBAAmB,CAAC,KAAiB;QAChD,gEAAgE;QAChE,oEAAoE;QACnE,KAAa,CAAC,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAE3D,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}

package/dist/errors/ErrorFormatter.d.ts

@@ -2,27 +2,74 @@
  * Error Formatter
  *
  * Formats Orbyt errors for CLI display with colors and helpful formatting.
- * Provides human-readable error output for developers.
+ * Provides human-readable error output for developers with:
+ * - Colored output for severity levels
+ * - Exit code information
+ * - Error category and retryability
+ * - Contextual debugging information
+ * - Integration with EngineLogger for proper log management
+ *
+ * USAGE:
+ * =====
+ * ```typescript
+ * // Format single error
+ * const formatted = formatError(error);
+ * console.error(formatted);
+ *
+ * // Format multiple errors
+ * const formatted = formatErrors(errors);
+ * console.error(formatted);
+ *
+ * // Detailed format with all diagnostics
+ * const detailed = formatDetailedError(error);
+ * console.error(detailed);
+ *
+ * // Log error using EngineLogger
+ * logErrorToEngine(error, logger);
+ * ```
  *
  * @module errors
  */
 import { OrbytError } from './OrbytError.js';
+import { ErrorSeverity } from './ErrorCodes.js';
+import type { EngineLogger } from '../logging/EngineLogger.js';
+import { LogLevel } from '@dev-ecosystem/core';
 /**
  * Format error for CLI display
  *
  * @param error - Orbyt error to format
  * @param useColors - Whether to use ANSI colors (default: true)
+ * @param verbose - Show additional diagnostic info (default: false)
  * @returns Formatted error string
  */
-export declare function formatError(error: OrbytError, useColors?: boolean): string;
+export declare function formatError(error: OrbytError, useColors?: boolean, verbose?: boolean): string;
 /**
  * Format multiple errors for CLI display
  *
  * @param errors - Array of Orbyt errors
  * @param useColors - Whether to use ANSI colors
+ * @param verbose - Show additional diagnostic info
  * @returns Formatted errors string
  */
-export declare function formatErrors(errors: OrbytError[], useColors?: boolean): string;
+export declare function formatErrors(errors: OrbytError[], useColors?: boolean, verbose?: boolean): string;
+/**
+ * Format error with full diagnostic information
+ * Useful for debugging and detailed error analysis
+ *
+ * @param error - Orbyt error to format
+ * @param useColors - Whether to use ANSI colors
+ * @returns Detailed formatted error string
+ */
+export declare function formatDetailedError(error: OrbytError, useColors?: boolean): string;
+/**
+ * Format error summary (one-line format)
+ * Useful for logging or compact display
+ *
+ * @param error - Orbyt error to format
+ * @param useColors - Whether to use ANSI colors
+ * @returns One-line error summary
+ */
+export declare function formatErrorSummary(error: OrbytError, useColors?: boolean): string;
 /**
  * Create a simple box around text (for emphasis)
  *
@@ -31,4 +78,46 @@ export declare function formatErrors(errors: OrbytError[], useColors?: boolean):
  * @returns Boxed text string
  */
 export declare function createBox(text: string, useColors?: boolean): string;
+/**
+ * Map ErrorSeverity to LogLevel
+ * Converts Orbyt's error severity to ecosystem-core's log level
+ *
+ * @param severity - Error severity
+ * @returns Corresponding log level
+ */
+export declare function errorSeverityToLogLevel(severity: ErrorSeverity): LogLevel;
+/**
+ * Log an error to EngineLogger with proper formatting
+ *
+ * This is the primary way to log errors during workflow loading and execution.
+ * It maps Orbyt's ErrorSeverity to ecosystem-core's LogLevel and includes
+ * all relevant context.
+ *
+ * @param error - Orbyt error to log
+ * @param logger - EngineLogger instance
+ * @param includeDebugInfo - Whether to include full diagnostic info (default: true)
+ */
+export declare function logErrorToEngine(error: OrbytError, logger: EngineLogger, includeDebugInfo?: boolean): void;
+/**
+ * Log multiple errors to EngineLogger
+ *
+ * @param errors - Array of Orbyt errors
+ * @param logger - EngineLogger instance
+ * @param includeDebugInfo - Whether to include full diagnostic info
+ */
+export declare function logErrorsToEngine(errors: OrbytError[], logger: EngineLogger, includeDebugInfo?: boolean): void;
+/**
+ * Format and log error (combined operation)
+ * Returns formatted string AND logs to EngineLogger if provided
+ *
+ * @param error - Orbyt error
+ * @param logger - Optional EngineLogger instance
+ * @param options - Formatting options
+ * @returns Formatted error string
+ */
+export declare function formatAndLogError(error: OrbytError, logger?: EngineLogger, options?: {
+    useColors?: boolean;
+    verbose?: boolean;
+    includeDebugInfo?: boolean;
+}): string;
 //# sourceMappingURL=ErrorFormatter.d.ts.map

package/dist/errors/ErrorFormatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorFormatter.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorFormatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAkB7C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,GAAE,OAAc,GAAG,MAAM,CAwChF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,SAAS,GAAE,OAAc,GAAG,MAAM,CA6BpF;AAqCD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,OAAc,GAAG,MAAM,CAazE"}
+{"version":3,"file":"ErrorFormatter.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorFormatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAiB/C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,UAAU,EACjB,SAAS,GAAE,OAAc,EACzB,OAAO,GAAE,OAAe,GACvB,MAAM,CA6DR;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAAE,EACpB,SAAS,GAAE,OAAc,EACzB,OAAO,GAAE,OAAe,GACvB,MAAM,CA6BR;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,GAAE,OAAc,GAAG,MAAM,CA6BxF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,GAAE,OAAc,GAAG,MAAM,CAevF;AAqCD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,OAAc,GAAG,MAAM,CAazE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,aAAa,GAAG,QAAQ,CAgBzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,YAAY,EACpB,gBAAgB,GAAE,OAAc,GAC/B,IAAI,CA6CN;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,MAAM,EAAE,YAAY,EACpB,gBAAgB,GAAE,OAAc,GAC/B,IAAI,CAWN;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACA,MAAM,CAUR"}