@orbytautomation/engine 0.2.4 → 0.4.0

package/dist/errors/ErrorDebugger.js

@@ -0,0 +1,290 @@
+/**
+ * Error Debugger (Smart Fix Suggestions)
+ *
+ * Analyzes errors and provides actionable fix suggestions.
+ * Makes debugging easy by suggesting concrete solutions.
+ *
+ * PHILOSOPHY:
+ * ==========
+ * Instead of just showing errors, guide users to fix them.
+ * Provide step-by-step solutions based on error context.
+ *
+ * USAGE:
+ * ======
+ * ```typescript
+ * // Get debug info for an error
+ * const debug = ErrorDebugger.analyze(error);
+ * console.log(debug.explanation);
+ * console.log(debug.fixSteps);
+ *
+ * // Get formatted debug output
+ * const output = ErrorDebugger.format(error);
+ * console.error(output);
+ * ```
+ *
+ * @module errors/debugger
+ */
+import { OrbytErrorCode } from './ErrorCodes.js';
+import { LoggerManager } from '../logging/LoggerManager.js';
+/**
+ * Error Debugger
+ *
+ * Smart system that analyzes errors and provides fix suggestions.
+ */
+export class ErrorDebugger {
+    /**
+     * Analyze error and generate debug information
+     *
+     * @param error - OrbytError to analyze
+     * @returns Debug information with fix suggestions
+     *
+     * @example
+     * ```typescript
+     * const debug = ErrorDebugger.analyze(error);
+     * console.log(debug.explanation);
+     * debug.fixSteps.forEach((step, i) => {
+     *   console.log(`${i + 1}. ${step}`);
+     * });
+     * ```
+     */
+    static analyze(error) {
+        const logger = LoggerManager.getLogger();
+        logger.debug(`[ErrorDebugger] Analyzing error: ${error.code}`, {
+            code: error.code,
+            message: error.message,
+            path: error.path,
+        });
+        // Get base information from error code
+        const baseInfo = this.getBaseDebugInfo(error.code);
+        // Enhance with context-specific information
+        const contextInfo = this.analyzeContext(error);
+        return {
+            ...baseInfo,
+            ...contextInfo,
+            // Override with more specific information if available
+            cause: contextInfo.cause || baseInfo.cause,
+            fixSteps: (contextInfo.fixSteps && contextInfo.fixSteps.length > 0) ? contextInfo.fixSteps : baseInfo.fixSteps,
+        };
+    }
+    /**
+     * Format debug information for display
+     *
+     * @param error - Error to format
+     * @param useColors - Whether to use ANSI colors (default: true)
+     * @returns Formatted debug output
+     */
+    static format(error, useColors = true) {
+        const debug = this.analyze(error);
+        const lines = [];
+        // Color codes
+        const c = useColors ? {
+            reset: '\x1b[0m',
+            bold: '\x1b[1m',
+            dim: '\x1b[2m',
+            blue: '\x1b[34m',
+            cyan: '\x1b[36m',
+            yellow: '\x1b[33m',
+            green: '\x1b[32m',
+            red: '\x1b[31m',
+        } : {
+            reset: '', bold: '', dim: '', blue: '', cyan: '', yellow: '', green: '', red: '',
+        };
+        // Header
+        lines.push(`${c.bold}${c.blue}━━━━ DEBUG INFO ━━━━${c.reset}`);
+        lines.push('');
+        // Explanation
+        lines.push(`${c.bold}What went wrong:${c.reset}`);
+        lines.push(debug.explanation);
+        lines.push('');
+        // Cause
+        lines.push(`${c.bold}Why it happened:${c.reset}`);
+        lines.push(debug.cause);
+        lines.push('');
+        // Fix steps
+        lines.push(`${c.bold}${c.green}How to fix:${c.reset}`);
+        debug.fixSteps.forEach((step, i) => {
+            lines.push(`${c.cyan}${i + 1}.${c.reset} ${step}`);
+        });
+        // Common mistakes
+        if (debug.commonMistakes && debug.commonMistakes.length > 0) {
+            lines.push('');
+            lines.push(`${c.bold}${c.yellow}Common mistakes:${c.reset}`);
+            debug.commonMistakes.forEach(mistake => {
+                lines.push(`${c.dim}•${c.reset} ${mistake}`);
+            });
+        }
+        // Example
+        if (debug.example) {
+            lines.push('');
+            lines.push(`${c.bold}Example:${c.reset}`);
+            lines.push(`${c.dim}${debug.example.description}${c.reset}`);
+            lines.push('');
+            lines.push(c.dim + '```' + c.reset);
+            lines.push(debug.example.code);
+            lines.push(c.dim + '```' + c.reset);
+        }
+        // Time estimate
+        if (debug.estimatedFixTime) {
+            lines.push('');
+            lines.push(`${c.dim}⏱  Estimated fix time: ${debug.estimatedFixTime}${c.reset}`);
+        }
+        return lines.join('\n');
+    }
+    // ==================== PRIVATE METHODS ====================
+    /**
+     * Get base debug information for error code
+     */
+    static getBaseDebugInfo(code) {
+        // Map of error codes to debug information
+        const debugMap = {
+            [OrbytErrorCode.SCHEMA_UNKNOWN_FIELD]: {
+                explanation: 'Your workflow contains a field that is not recognized by Orbyt.',
+                cause: 'This usually happens due to a typo in the field name or using a field that doesn\'t exist in the schema.',
+                fixSteps: [
+                    'Check the spelling of the field name',
+                    'Refer to Orbyt documentation for valid field names',
+                    'Remove the field if it\'s not needed',
+                ],
+                commonMistakes: [
+                    'Typos in field names (e.g., "varion" instead of "version")',
+                    'Using deprecated field names',
+                    'Copy-pasting from old workflow versions',
+                ],
+            },
+            [OrbytErrorCode.SCHEMA_RESERVED_FIELD]: {
+                explanation: 'You tried to use a field name that is reserved by Orbyt engine.',
+                cause: 'Reserved fields are used internally for billing, execution tracking, and security. Users cannot set these.',
+                fixSteps: [
+                    'Rename the field to something else',
+                    'Avoid using fields starting with "_" or "__"',
+                    'Avoid fields like "executionId", "billingMode", "userId"',
+                ],
+                commonMistakes: [
+                    'Using underscore-prefixed fields (_internal, __context)',
+                    'Trying to set billing fields manually',
+                    'Using engine-managed field names',
+                ],
+                docsLinks: ['https://docs.orbyt.dev/reserved-fields'],
+            },
+            [OrbytErrorCode.SCHEMA_MISSING_FIELD]: {
+                explanation: 'A required field is missing from your workflow definition.',
+                cause: 'Orbyt requires certain fields to be present for the workflow to be valid.',
+                fixSteps: [
+                    'Add the missing required field to your workflow',
+                    'Check field name spelling',
+                    'Refer to schema documentation for required fields',
+                ],
+                estimatedFixTime: '1-2 minutes',
+            },
+            [OrbytErrorCode.VALIDATION_DUPLICATE_ID]: {
+                explanation: 'Multiple steps in your workflow have the same ID.',
+                cause: 'Each step must have a unique identifier so Orbyt can track execution and dependencies.',
+                fixSteps: [
+                    'Find all steps with the duplicate ID',
+                    'Rename one (or both) to make IDs unique',
+                    'Use descriptive, meaningful IDs for clarity',
+                ],
+                commonMistakes: [
+                    'Copy-pasting steps without changing IDs',
+                    'Using generic IDs like "step1", "step2"',
+                ],
+                estimatedFixTime: '1 minute',
+            },
+            [OrbytErrorCode.VALIDATION_CIRCULAR_DEPENDENCY]: {
+                explanation: 'Your workflow has steps that depend on each other in a circle.',
+                cause: 'Step A depends on Step B, which depends on Step C, which depends on Step A. This creates an infinite loop.',
+                fixSteps: [
+                    'Review the dependency chain shown in the error',
+                    'Identify which dependency can be removed or reordered',
+                    'Break the circle by removing one dependency',
+                ],
+                commonMistakes: [
+                    'Not visualizing the dependency graph',
+                    'Adding dependencies without checking existing ones',
+                ],
+                urgent: true,
+                estimatedFixTime: '5-10 minutes',
+            },
+            [OrbytErrorCode.EXECUTION_TIMEOUT]: {
+                explanation: 'A step took too long to execute and was terminated.',
+                cause: 'The step exceeded its configured timeout limit.',
+                fixSteps: [
+                    'Increase the timeout value in step configuration',
+                    'Optimize the step\'s logic to run faster',
+                    'Check if the step is stuck in an infinite loop',
+                    'Verify external services are responding',
+                ],
+                commonMistakes: [
+                    'Setting timeout too low for long-running operations',
+                    'Not handling network delays',
+                    'Infinite loops in custom code',
+                ],
+                urgent: true,
+                estimatedFixTime: '10-30 minutes',
+            },
+        };
+        const info = debugMap[code];
+        if (info) {
+            return {
+                explanation: info.explanation || 'An error occurred in your workflow.',
+                cause: info.cause || 'The exact cause depends on the specific error code and context.',
+                fixSteps: info.fixSteps || [],
+                commonMistakes: info.commonMistakes,
+                docsLinks: info.docsLinks,
+                example: info.example,
+                urgent: info.urgent ?? false,
+                estimatedFixTime: info.estimatedFixTime,
+            };
+        }
+        // Default debug info for unknown codes
+        return {
+            explanation: 'An error occurred in your workflow.',
+            cause: 'The exact cause depends on the specific error code and context.',
+            fixSteps: [
+                'Review the error message carefully',
+                'Check the path/location mentioned in the error',
+                'Refer to Orbyt documentation',
+                'Contact support if issue persists',
+            ],
+            urgent: false,
+        };
+    }
+    /**
+     * Analyze error context for more specific information
+     */
+    static analyzeContext(error) {
+        const fixSteps = [];
+        // Add location-specific fix steps
+        if (error.path) {
+            fixSteps.push(`Look at: ${error.path}`);
+        }
+        // Add context-specific information
+        if (error.diagnostic.context) {
+            const ctx = error.diagnostic.context;
+            // For unknown field errors, add suggestion if available
+            if (ctx.suggestion) {
+                fixSteps.push(`Did you mean: "${ctx.suggestion}"?`);
+            }
+            // For enum errors, show valid values
+            if (ctx.validValues && Array.isArray(ctx.validValues)) {
+                fixSteps.push(`Use one of: ${ctx.validValues.join(', ')}`);
+            }
+            // For type errors, show expected type
+            if (ctx.expected) {
+                fixSteps.push(`Change type to: ${ctx.expected}`);
+            }
+        }
+        return { fixSteps };
+    }
+    /**
+     * Quick debug - one-line summary
+     *
+     * @param error - Error to summarize
+     * @returns One-line debug summary
+     */
+    static quickDebug(error) {
+        const debug = this.analyze(error);
+        return `💡 ${debug.fixSteps[0] || debug.cause}`;
+    }
+}
+//# sourceMappingURL=ErrorDebugger.js.map

package/dist/errors/ErrorDebugger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorDebugger.js","sourceRoot":"","sources":["../../src/errors/ErrorDebugger.ts"],"names":[],"mappings":"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"}

package/dist/errors/ErrorDetector.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 { OrbytError } from './OrbytError.js';
+/**
+ * Error context for detection
+ * Provides information about what went wrong
+ */
+export interface ErrorContext {
+    /** Type of error scenario */
+    type: ErrorScenario;
+    /** Field name (if applicable) */
+    field?: string;
+    /** Location in workflow where error occurred */
+    location?: string;
+    /** Expected value/type */
+    expected?: string;
+    /** Actual value/type received */
+    actual?: string;
+    /** Related data for context */
+    data?: Record<string, any>;
+    /** Raw error message (if from exception) */
+    rawMessage?: string;
+    /** Stack trace (for internal errors) */
+    stack?: string;
+}
+/**
+ * Error scenarios that detector can identify
+ */
+export type ErrorScenario = 'unknown_field' | 'reserved_field' | 'invalid_type' | 'missing_field' | 'invalid_enum' | 'parse_error' | 'invalid_adapter' | 'duplicate_id' | 'unknown_step' | 'circular_dependency' | 'forward_reference' | 'empty_workflow' | 'missing_input' | 'invalid_condition' | 'invalid_variable' | 'step_not_found' | 'step_timeout' | 'step_failed' | 'step_dependency_failed' | 'step_invalid_config' | 'reserved_field_override' | 'reserved_annotation' | 'permission_denied' | 'unknown';
+/**
+ * Error Detector
+ *
+ * Smart system that analyzes error context and produces correct OrbytError.
+ */
+export declare 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: ErrorContext): OrbytError;
+    /**
+     * 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: Error, location?: string): OrbytError;
+    /**
+     * Check if field is reserved by engine
+     */
+    private static isReservedField;
+    /**
+     * Check if annotation uses reserved namespace
+     */
+    private static isReservedAnnotation;
+    /**
+     * Determine field type for security errors
+     */
+    private static getFieldType;
+    private static handleUnknownField;
+    /**
+     * Get valid field names based on location in workflow
+     */
+    private static getValidFieldsForLocation;
+    private static handleReservedField;
+    private static handleInvalidType;
+    private static handleMissingField;
+    private static handleInvalidEnum;
+    private static handleParseError;
+    private static handleInvalidAdapter;
+    private static handleDuplicateId;
+    private static handleUnknownStep;
+    private static handleCircularDependency;
+    private static handleForwardReference;
+    private static handleMissingInput;
+    private static handleInvalidCondition;
+    private static handleInvalidVariable;
+    private static handleStepTimeout;
+    private static handleStepFailed;
+    private static handleStepDependencyFailed;
+    private static handleStepInvalidConfig;
+    private static handlePermissionDenied;
+    private static handleUnknown;
+    /**
+     * 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
+     */
+    private static enrichWithDebugInfo;
+}
+//# sourceMappingURL=ErrorDetector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorDetector.d.ts","sourceRoot":"","sources":["../../src/errors/ErrorDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAmB7C;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,6BAA6B;IAC7B,IAAI,EAAE,aAAa,CAAC;IAEpB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAEnB,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,eAAe,GACf,cAAc,GACd,aAAa,GACb,iBAAiB,GAGjB,cAAc,GACd,cAAc,GACd,qBAAqB,GACrB,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,kBAAkB,GAGlB,gBAAgB,GAChB,cAAc,GACd,aAAa,GACb,wBAAwB,GACxB,qBAAqB,GAGrB,yBAAyB,GACzB,qBAAqB,GACrB,mBAAmB,GAGnB,SAAS,CAAC;AAEhB;;;;GAIG;AACH,qBAAa,aAAa;IACtB;;;;;;;;;;;;;;OAcG;IACH;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,UAAU;IA6GhD;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU;IAoCvE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAU9B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAInC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAkB3B,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAajC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAgCxC,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAUlC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAShC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAOjC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAUhC,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAS/B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAQnC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAQhC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAQhC,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAKvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAQrC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAOjC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAQrC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAQpC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAQhC,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAU/B,OAAO,CAAC,MAAM,CAAC,0BAA0B;IAQzC,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAQtC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAQrC,OAAO,CAAC,MAAM,CAAC,aAAa;IAU5B;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAOrC"}