@windagency/valora 2.0.1

package/dist/utils/error-handler.js

@@ -0,0 +1,319 @@
+/**
+ * Enhanced Error Handling System
+ *
+ * Provides comprehensive error classification, recovery mechanisms,
+ * and standardized error handling patterns.
+ */
+import { getLogger } from '../output/logger.js';
+export class BaseError extends Error {
+    code;
+    cause;
+    context;
+    details;
+    docsLink;
+    fixSuggestions;
+    recovery;
+    userMessage;
+    constructor(message, code, details, context, recovery, cause, userMessage, fixSuggestions, docsLink) {
+        super(message);
+        this.code = code;
+        this.name = this.constructor.name;
+        this.details = details;
+        this.context = {
+            component: 'unknown',
+            operation: 'unknown',
+            timestamp: new Date(),
+            ...context
+        };
+        this.recovery = recovery;
+        this.cause = cause;
+        this.userMessage = userMessage;
+        this.fixSuggestions = fixSuggestions;
+        this.docsLink = docsLink;
+        // Capture stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        // Skip automatic logging in BaseError constructor to prevent infinite loops
+        // during early initialization. Errors should be logged explicitly where needed.
+    }
+}
+export class ConfigurationError extends BaseError {
+    constructor(message, details, context, userMessage, fixSuggestions, docsLink) {
+        super(message, 'CONFIGURATION_ERROR', details, context, undefined, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+export class ExecutionError extends BaseError {
+    constructor(message, details, context, recovery, userMessage, fixSuggestions, docsLink) {
+        super(message, 'EXECUTION_ERROR', details, context, recovery, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+export class NetworkError extends BaseError {
+    constructor(message, details, context, recovery, userMessage, fixSuggestions, docsLink) {
+        const defaultRecovery = {
+            backoffMs: 2000,
+            maxRetries: 5,
+            type: 'retry'
+        };
+        super(message, 'NETWORK_ERROR', details, context, recovery ?? defaultRecovery, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+export class ProviderError extends BaseError {
+    constructor(message, details, context, recovery, userMessage, fixSuggestions, docsLink) {
+        const defaultRecovery = {
+            backoffMs: 1000,
+            maxRetries: 3,
+            type: 'retry'
+        };
+        super(message, 'PROVIDER_ERROR', details, context, recovery ?? defaultRecovery, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+export class ResourceError extends BaseError {
+    constructor(message, details, context, recovery, userMessage, fixSuggestions, docsLink) {
+        const defaultRecovery = {
+            timeoutMs: 30000,
+            type: 'circuit-breaker'
+        };
+        super(message, 'RESOURCE_ERROR', details, context, recovery ?? defaultRecovery, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+export class SecurityError extends BaseError {
+    constructor(message, details, context, userMessage, fixSuggestions, docsLink) {
+        super(message, 'SECURITY_ERROR', details, context, undefined, undefined, userMessage, fixSuggestions, docsLink);
+        // Security errors should be logged with high priority
+        const logger = getLogger();
+        logger.error('SECURITY EVENT', this, {
+            alert: true,
+            security: true
+        });
+    }
+}
+export class SessionError extends BaseError {
+    constructor(message, details, context, userMessage, fixSuggestions, docsLink) {
+        super(message, 'SESSION_ERROR', details, context, undefined, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+export class TimeoutError extends BaseError {
+    constructor(message, details, context, recovery, userMessage, fixSuggestions, docsLink) {
+        const defaultRecovery = {
+            backoffMs: 500,
+            maxRetries: 2,
+            type: 'retry'
+        };
+        super(message, 'TIMEOUT_ERROR', details, context, recovery ?? defaultRecovery, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+export class ValidationError extends BaseError {
+    constructor(message, details, context, userMessage, fixSuggestions, docsLink) {
+        super(message, 'VALIDATION_ERROR', details, context, undefined, undefined, userMessage, fixSuggestions, docsLink);
+    }
+}
+/**
+ * Circuit Breaker for external service calls
+ */
+export class CircuitBreaker {
+    failureThreshold;
+    recoveryTimeoutMs;
+    failureCount = 0;
+    nextAttemptTime = 0;
+    state = 'closed';
+    constructor(failureThreshold = 5, recoveryTimeoutMs = 60000 // 1 minute
+    ) {
+        this.failureThreshold = failureThreshold;
+        this.recoveryTimeoutMs = recoveryTimeoutMs;
+    }
+    /**
+     * Execute operation with circuit breaker protection
+     */
+    async execute(operation, context) {
+        if (this.state === 'open') {
+            if (Date.now() < this.nextAttemptTime) {
+                throw new ResourceError('Circuit breaker is OPEN - service temporarily unavailable', { nextAttempt: new Date(this.nextAttemptTime), state: this.state }, context);
+            }
+            this.state = 'half-open';
+        }
+        try {
+            const result = await operation();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    getFailureCount() {
+        return this.failureCount;
+    }
+    getState() {
+        return this.state;
+    }
+    onFailure() {
+        if (this.state === 'half-open') {
+            // In half-open state, any failure immediately returns to open
+            this.state = 'open';
+            this.nextAttemptTime = Date.now() + this.recoveryTimeoutMs;
+            return;
+        }
+        this.failureCount++;
+        if (this.failureCount >= this.failureThreshold) {
+            this.state = 'open';
+            this.nextAttemptTime = Date.now() + this.recoveryTimeoutMs;
+        }
+    }
+    onSuccess() {
+        this.failureCount = 0;
+        this.state = 'closed';
+    }
+}
+/**
+ * Retry utility with exponential backoff
+ */
+export async function withRetry(operation, options) {
+    const { backoffFactor = 2, baseDelayMs = 1000, context, maxDelayMs = 30000, maxRetries = 3, retryCondition = isRetriableError } = options;
+    const attempts = Array.from({ length: maxRetries + 1 }, (_, i) => i);
+    let lastError;
+    for (const attempt of attempts) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry if this is the last attempt or error is not retriable
+            if (attempt === maxRetries || !retryCondition(lastError)) {
+                throw lastError;
+            }
+            // Calculate delay with exponential backoff
+            const delay = Math.min(baseDelayMs * Math.pow(backoffFactor, attempt), maxDelayMs);
+            const logger = getLogger();
+            logger.warn(`Operation failed, retrying in ${delay}ms`, {
+                attempt: attempt + 1,
+                context,
+                error: lastError.message,
+                maxRetries
+            });
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Safe async operation wrapper
+ */
+export async function safeAsync(operation, fallback, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const logger = getLogger();
+        logger.error('Safe async operation failed', error, { context });
+        return fallback;
+    }
+}
+/**
+ * Safe synchronous operation wrapper
+ */
+export function safeSync(operation, fallback, context) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        const logger = getLogger();
+        logger.error('Safe sync operation failed', error, { context });
+        return fallback;
+    }
+}
+/**
+ * Create error context helper
+ */
+export function createErrorContext(component, operation, additionalContext) {
+    return {
+        component,
+        operation,
+        timestamp: new Date(),
+        ...additionalContext
+    };
+}
+/**
+ * Format error for display with enhanced context
+ */
+export function formatError(error) {
+    if (error instanceof BaseError) {
+        const parts = [`${error.name}: ${error.message}`];
+        if (error.context) {
+            parts.push(`Component: ${error.context.component}`);
+            parts.push(`Operation: ${error.context.operation}`);
+            parts.push(`Timestamp: ${error.context.timestamp.toISOString()}`);
+        }
+        if (error.details) {
+            parts.push(`Details: ${JSON.stringify(error.details, null, 2)}`);
+        }
+        if (error.recovery) {
+            parts.push(`Recovery: ${error.recovery.type}`);
+        }
+        return parts.join('\n');
+    }
+    return `${error.name}: ${error.message}`;
+}
+// Re-export formatErrorMessage from error-utils for backward compatibility
+export { formatErrorMessage } from './error-utils.js';
+/**
+ * Check if error is retriable (enhanced version)
+ */
+export function isRetriableError(error) {
+    // Check for BaseError with recovery strategy
+    if (error instanceof BaseError && error.recovery) {
+        return error.recovery.type === 'retry';
+    }
+    // Check error message patterns
+    const retriableMessages = [
+        'timeout',
+        'ETIMEDOUT',
+        'ECONNRESET',
+        'ENOTFOUND',
+        'rate limit',
+        'too many requests',
+        'service unavailable',
+        'temporary failure',
+        'network error',
+        'connection refused'
+    ];
+    return retriableMessages.some((msg) => error.message.toLowerCase().includes(msg.toLowerCase()));
+}
+/**
+ * Check if error should trigger circuit breaker
+ */
+export function isCircuitBreakerError(error) {
+    if (error instanceof BaseError && error.recovery) {
+        return error.recovery.type === 'circuit-breaker';
+    }
+    const circuitBreakerMessages = [
+        'service unavailable',
+        'connection refused',
+        'ECONNREFUSED',
+        'ENOTFOUND',
+        'timeout',
+        'ETIMEDOUT',
+        'rate limit exceeded'
+    ];
+    return circuitBreakerMessages.some((msg) => error.message.toLowerCase().includes(msg.toLowerCase()));
+}
+// Global circuit breaker instances for different services
+const circuitBreakers = new Map();
+/**
+ * Get or create circuit breaker for a service
+ */
+export function getCircuitBreaker(serviceName) {
+    if (!circuitBreakers.has(serviceName)) {
+        circuitBreakers.set(serviceName, new CircuitBreaker());
+    }
+    return circuitBreakers.get(serviceName);
+}
+/**
+ * Execute operation with circuit breaker protection
+ */
+export async function withCircuitBreaker(serviceName, operation, context) {
+    const breaker = getCircuitBreaker(serviceName);
+    return breaker.execute(operation, context);
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/utils/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAsB1C,MAAM,OAAO,SAAU,SAAQ,KAAK;IAWlB;IAVQ,KAAK,CAAS;IACvB,OAAO,CAAe;IACtB,OAAO,CAA2B;IAClC,QAAQ,CAAU;IAClB,cAAc,CAAY;IAC1B,QAAQ,CAAoB;IAC5B,WAAW,CAAU;IAErC,YACC,OAAe,EACC,IAAY,EAC5B,OAAiC,EACjC,OAA+B,EAC/B,QAA2B,EAC3B,KAAa,EACb,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,KAAK,CAAC,OAAO,CAAC,CAAC;QATC,SAAI,GAAJ,IAAI,CAAQ;QAU5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG;YACd,SAAS,EAAE,SAAS;YACpB,SAAS,EAAE,SAAS;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,GAAG,OAAO;SACV,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEzB,sBAAsB;QACtB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC7B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACjD,CAAC;QAED,4EAA4E;QAC5E,gFAAgF;IACjF,CAAC;CACD;AAED,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAChD,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,KAAK,CACJ,OAAO,EACP,qBAAqB,EACrB,OAAO,EACP,OAAO,EACP,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,EACd,QAAQ,CACR,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,cAAe,SAAQ,SAAS;IAC5C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,QAA2B,EAC3B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,KAAK,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;IACjH,CAAC;CACD;AAED,MAAM,OAAO,YAAa,SAAQ,SAAS;IAC1C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,QAA2B,EAC3B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,MAAM,eAAe,GAAqB;YACzC,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,CAAC;YACb,IAAI,EAAE,OAAO;SACb,CAAC;QACF,KAAK,CACJ,OAAO,EACP,eAAe,EACf,OAAO,EACP,OAAO,EACP,QAAQ,IAAI,eAAe,EAC3B,SAAS,EACT,WAAW,EACX,cAAc,EACd,QAAQ,CACR,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC3C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,QAA2B,EAC3B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,MAAM,eAAe,GAAqB;YACzC,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,CAAC;YACb,IAAI,EAAE,OAAO;SACb,CAAC;QACF,KAAK,CACJ,OAAO,EACP,gBAAgB,EAChB,OAAO,EACP,OAAO,EACP,QAAQ,IAAI,eAAe,EAC3B,SAAS,EACT,WAAW,EACX,cAAc,EACd,QAAQ,CACR,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC3C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,QAA2B,EAC3B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,MAAM,eAAe,GAAqB;YACzC,SAAS,EAAE,KAAK;YAChB,IAAI,EAAE,iBAAiB;SACvB,CAAC;QACF,KAAK,CACJ,OAAO,EACP,gBAAgB,EAChB,OAAO,EACP,OAAO,EACP,QAAQ,IAAI,eAAe,EAC3B,SAAS,EACT,WAAW,EACX,cAAc,EACd,QAAQ,CACR,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC3C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,KAAK,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;QAChH,sDAAsD;QACtD,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,IAAI,EAAE;YACpC,KAAK,EAAE,IAAI;YACX,QAAQ,EAAE,IAAI;SACd,CAAC,CAAC;IACJ,CAAC;CACD;AAED,MAAM,OAAO,YAAa,SAAQ,SAAS;IAC1C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;IAChH,CAAC;CACD;AAED,MAAM,OAAO,YAAa,SAAQ,SAAS;IAC1C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,QAA2B,EAC3B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,MAAM,eAAe,GAAqB;YACzC,SAAS,EAAE,GAAG;YACd,UAAU,EAAE,CAAC;YACb,IAAI,EAAE,OAAO;SACb,CAAC;QACF,KAAK,CACJ,OAAO,EACP,eAAe,EACf,OAAO,EACP,OAAO,EACP,QAAQ,IAAI,eAAe,EAC3B,SAAS,EACT,WAAW,EACX,cAAc,EACd,QAAQ,CACR,CAAC;IACH,CAAC;CACD;AAED,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC7C,YACC,OAAe,EACf,OAAiC,EACjC,OAA+B,EAC/B,WAAoB,EACpB,cAAyB,EACzB,QAAiB;QAEjB,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;IACnH,CAAC;CACD;AAOD;;GAEG;AACH,MAAM,OAAO,cAAc;IAMR;IACA;IANV,YAAY,GAAG,CAAC,CAAC;IACjB,eAAe,GAAG,CAAC,CAAC;IACpB,KAAK,GAAiB,QAAQ,CAAC;IAEvC,YACkB,mBAA2B,CAAC,EAC5B,oBAA4B,KAAK,CAAC,WAAW;;QAD7C,qBAAgB,GAAhB,gBAAgB,CAAY;QAC5B,sBAAiB,GAAjB,iBAAiB,CAAgB;IAChD,CAAC;IAEJ;;OAEG;IACH,KAAK,CAAC,OAAO,CAAI,SAA2B,EAAE,OAA+B;QAC5E,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;gBACvC,MAAM,IAAI,aAAa,CACtB,2DAA2D,EAC3D,EAAE,WAAW,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,EAClE,OAAO,CACP,CAAC;YACH,CAAC;YACD,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;QAC1B,CAAC;QAED,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,OAAO,MAAM,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;IAED,eAAe;QACd,OAAO,IAAI,CAAC,YAAY,CAAC;IAC1B,CAAC;IAED,QAAQ;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACnB,CAAC;IAEO,SAAS;QAChB,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAChC,8DAA8D;YAC9D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,iBAAiB,CAAC;YAC3D,OAAO;QACR,CAAC;QAED,IAAI,CAAC,YAAY,EAAE,CAAC;QAEpB,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAChD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAC5D,CAAC;IACF,CAAC;IAEO,SAAS;QAChB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;IACvB,CAAC;CACD;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC9B,SAA2B,EAC3B,OAOC;IAED,MAAM,EACL,aAAa,GAAG,CAAC,EACjB,WAAW,GAAG,IAAI,EAClB,OAAO,EACP,UAAU,GAAG,KAAK,EAClB,UAAU,GAAG,CAAC,EACd,cAAc,GAAG,gBAAgB,EACjC,GAAG,OAAO,CAAC;IAEZ,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACrE,IAAI,SAA4B,CAAC;IAEjC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAChC,IAAI,CAAC;YACJ,OAAO,MAAM,SAAS,EAAE,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,SAAS,GAAG,KAAc,CAAC;YAE3B,oEAAoE;YACpE,IAAI,OAAO,KAAK,UAAU,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC1D,MAAM,SAAS,CAAC;YACjB,CAAC;YAED,2CAA2C;YAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;YAEnF,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,iCAAiC,KAAK,IAAI,EAAE;gBACvD,OAAO,EAAE,OAAO,GAAG,CAAC;gBACpB,OAAO;gBACP,KAAK,EAAE,SAAS,CAAC,OAAO;gBACxB,UAAU;aACV,CAAC,CAAC;YAEH,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC5D,CAAC;IACF,CAAC;IAED,MAAM,SAAU,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC9B,SAA2B,EAC3B,QAAY,EACZ,OAA+B;IAE/B,IAAI,CAAC;QACJ,OAAO,MAAM,SAAS,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAc,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACzE,OAAO,QAAQ,CAAC;IACjB,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAI,SAAkB,EAAE,QAAY,EAAE,OAA+B;IAC5F,IAAI,CAAC;QACJ,OAAO,SAAS,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAc,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACxE,OAAO,QAAQ,CAAC;IACjB,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CACjC,SAAiB,EACjB,SAAiB,EACjB,iBAA2C;IAE3C,OAAO;QACN,SAAS;QACT,SAAS;QACT,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,GAAG,iBAAiB;KACpB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACvC,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAElD,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,IAAK,KAAmB,CAAC,OAAO,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,SAAS,CAAE,KAAmB,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACjF,CAAC;QAED,IAAK,KAAmB,CAAC,QAAQ,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,aAAc,KAAmB,CAAC,QAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED,2EAA2E;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAY;IAC5C,6CAA6C;IAC7C,IAAI,KAAK,YAAY,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,OAAO,CAAC;IACxC,CAAC;IAED,+BAA+B;IAC/B,MAAM,iBAAiB,GAAG;QACzB,SAAS;QACT,WAAW;QACX,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,mBAAmB;QACnB,qBAAqB;QACrB,mBAAmB;QACnB,eAAe;QACf,oBAAoB;KACpB,CAAC;IAEF,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACjG,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAY;IACjD,IAAI,KAAK,YAAY,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,iBAAiB,CAAC;IAClD,CAAC;IAED,MAAM,sBAAsB,GAAG;QAC9B,qBAAqB;QACrB,oBAAoB;QACpB,cAAc;QACd,WAAW;QACX,SAAS;QACT,WAAW;QACX,qBAAqB;KACrB,CAAC;IAEF,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACtG,CAAC;AAED,0DAA0D;AAC1D,MAAM,eAAe,GAAG,IAAI,GAAG,EAA0B,CAAC;AAE1D;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACpD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,cAAc,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,eAAe,CAAC,GAAG,CAAC,WAAW,CAAE,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,WAAmB,EACnB,SAA2B,EAC3B,OAA+B;IAE/B,MAAM,OAAO,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/dist/utils/error-messages.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Centralized error message templates with user-friendly messages and fix suggestions
+ */
+export interface ErrorMessageTemplate {
+    docsLink?: string;
+    fixes: string[];
+    message: string;
+    title: string;
+}
+export declare const ERROR_MESSAGES: Record<string, ErrorMessageTemplate>;
+/**
+ * Get error message template by error code
+ */
+export declare function getErrorMessage(code: string): ErrorMessageTemplate | undefined;
+/**
+ * Check if error code has a template
+ */
+export declare function hasErrorMessage(code: string): boolean;
+/**
+ * Get all error codes
+ */
+export declare function getErrorCodes(): string[];
+//# sourceMappingURL=error-messages.d.ts.map

package/dist/utils/error-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-messages.d.ts","sourceRoot":"","sources":["../../src/utils/error-messages.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAuJ/D,CAAC;AAEF;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAE9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC"}

package/dist/utils/error-messages.js

@@ -0,0 +1,160 @@
+/**
+ * Centralized error message templates with user-friendly messages and fix suggestions
+ */
+import { getDocsUrl } from '../config/constants.js';
+export const ERROR_MESSAGES = {
+    API_KEY_INVALID: {
+        fixes: [
+            'Verify your API key is correct',
+            'Check if the API key has expired',
+            'Generate a new API key from your provider dashboard',
+            'Try using a different provider: valora plan --provider=cursor'
+        ],
+        message: 'The API key provided is invalid or has been revoked.',
+        title: 'Invalid API Key'
+    },
+    API_RATE_LIMIT: {
+        fixes: [
+            'Wait a few minutes and try again',
+            'Upgrade your provider plan for higher rate limits',
+            'Use a different provider: valora plan --provider=anthropic',
+            'Enable rate limiting in config: valora config setup'
+        ],
+        message: 'You have exceeded the rate limit for your API provider.',
+        title: 'Rate Limit Exceeded'
+    },
+    COMMAND_NOT_FOUND: {
+        docsLink: getDocsUrl('/commands'),
+        fixes: [
+            'Run: valora list (to see all available commands)',
+            'Check for typos in the command name',
+            'Run: valora help (for command documentation)',
+            'View available commands at the docs link above'
+        ],
+        message: 'The command you specified does not exist or could not be found.',
+        title: 'Command Not Found'
+    },
+    CONFIGURATION_INVALID: {
+        docsLink: getDocsUrl('/configuration'),
+        fixes: [
+            'Run: valora config setup (to reconfigure)',
+            'Check the configuration file for syntax errors',
+            'Validate your YAML syntax',
+            'Delete the config file and run setup again'
+        ],
+        message: 'The configuration file exists but contains invalid or malformed data. The configuration must be valid YAML and match the expected schema.',
+        title: 'Invalid Configuration'
+    },
+    CONFIGURATION_NOT_FOUND: {
+        docsLink: getDocsUrl('/setup'),
+        fixes: [
+            'Run: valora config setup (interactive setup)',
+            'Set environment variable: export ANTHROPIC_API_KEY=your-key',
+            'Use Cursor provider: valora plan --provider=cursor (no config needed)',
+            'Create config manually at ~/.valora/config.yaml'
+        ],
+        message: 'The AI orchestration engine requires configuration before it can be used. You need to set up at least one AI provider or use the Cursor provider.',
+        title: 'Configuration Not Found'
+    },
+    EXECUTION_TIMEOUT: {
+        fixes: [
+            'Try again with a simpler task',
+            'Break down the task into smaller steps',
+            'Check your network connection',
+            'Increase timeout: valora plan --timeout=300'
+        ],
+        message: 'The command execution exceeded the maximum allowed time.',
+        title: 'Execution Timeout'
+    },
+    FILE_PERMISSION_DENIED: {
+        fixes: [
+            'Check file permissions: ls -la <file>',
+            'Run with appropriate permissions',
+            'Ensure the directory is writable',
+            'Check if file is locked by another process'
+        ],
+        message: 'Permission denied when trying to access a file or directory.',
+        title: 'Permission Denied'
+    },
+    NETWORK_CONNECTION_FAILED: {
+        fixes: [
+            'Check your internet connection',
+            'Verify firewall settings',
+            'Try using a different network',
+            'Check if the AI provider is experiencing outages',
+            'Use a VPN if the provider is blocked in your region'
+        ],
+        message: 'Failed to establish a network connection to the AI provider.',
+        title: 'Network Connection Failed'
+    },
+    PROVIDER_NOT_CONFIGURED: {
+        docsLink: getDocsUrl('/providers'),
+        fixes: [
+            'Run: valora config setup (to configure providers)',
+            'Set API key environment variable for your provider',
+            'Use Cursor provider: --provider=cursor (no config needed)',
+            'Specify a different provider: --provider=anthropic'
+        ],
+        message: 'The specified AI provider is not configured. You need to add API credentials or use the Cursor provider which requires no configuration.',
+        title: 'Provider Not Configured'
+    },
+    PROVIDER_SERVICE_ERROR: {
+        fixes: [
+            'Check provider status page for outages',
+            'Try again in a few minutes',
+            'Use a different provider: valora plan --provider=openai',
+            'Contact provider support if issue persists'
+        ],
+        message: 'The AI provider service returned an error or is temporarily unavailable.',
+        title: 'Provider Service Error'
+    },
+    SESSION_CORRUPTED: {
+        fixes: [
+            'Delete corrupted session: valora session delete <session-id>',
+            'Start a new session: valora plan (without --session flag)',
+            'Check session directory permissions',
+            'Clean up sessions: valora session clean'
+        ],
+        message: 'The session data is corrupted or cannot be loaded.',
+        title: 'Session Corrupted'
+    },
+    SESSION_NOT_FOUND: {
+        fixes: [
+            'List available sessions: valora session list',
+            'Check session ID spelling',
+            'Start a new session: valora plan (without --session flag)',
+            'Sessions may have been cleaned up due to retention policy'
+        ],
+        message: 'The specified session does not exist or has been deleted.',
+        title: 'Session Not Found'
+    },
+    VALIDATION_FAILED: {
+        fixes: [
+            'Check the command arguments and options',
+            'Run: valora help <command> (for usage examples)',
+            'Ensure required arguments are provided',
+            'Verify argument types and formats'
+        ],
+        message: 'The command arguments or options failed validation.',
+        title: 'Validation Failed'
+    }
+};
+/**
+ * Get error message template by error code
+ */
+export function getErrorMessage(code) {
+    return ERROR_MESSAGES[code];
+}
+/**
+ * Check if error code has a template
+ */
+export function hasErrorMessage(code) {
+    return code in ERROR_MESSAGES;
+}
+/**
+ * Get all error codes
+ */
+export function getErrorCodes() {
+    return Object.keys(ERROR_MESSAGES);
+}
+//# sourceMappingURL=error-messages.js.map

package/dist/utils/error-messages.js.map

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

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Error Utilities
+ *
+ * Simple error formatting utilities that don't have external dependencies.
+ * This module intentionally has no imports that could cause circular dependencies.
+ */
+/**
+ * Extract error message from unknown error value
+ *
+ * This is the standard utility for formatting unknown caught errors.
+ * Replaces the common pattern: `error instanceof Error ? error.message : String(error)`
+ *
+ * @param error - The caught error value (can be any type)
+ * @param context - Optional context prefix for the message
+ * @returns Formatted error message string
+ */
+export declare function formatErrorMessage(error: unknown, context?: string): string;
+/**
+ * Check if a value is an Error object
+ */
+export declare function isError(value: unknown): value is Error;
+/**
+ * Get the stack trace from an error, or undefined if not available
+ */
+export declare function getErrorStack(error: unknown): string | undefined;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/error-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEhE"}

package/dist/utils/error-utils.js

@@ -0,0 +1,33 @@
+/**
+ * Error Utilities
+ *
+ * Simple error formatting utilities that don't have external dependencies.
+ * This module intentionally has no imports that could cause circular dependencies.
+ */
+/**
+ * Extract error message from unknown error value
+ *
+ * This is the standard utility for formatting unknown caught errors.
+ * Replaces the common pattern: `error instanceof Error ? error.message : String(error)`
+ *
+ * @param error - The caught error value (can be any type)
+ * @param context - Optional context prefix for the message
+ * @returns Formatted error message string
+ */
+export function formatErrorMessage(error, context) {
+    const message = error instanceof Error ? error.message : String(error);
+    return context ? `${context}: ${message}` : message;
+}
+/**
+ * Check if a value is an Error object
+ */
+export function isError(value) {
+    return value instanceof Error;
+}
+/**
+ * Get the stack trace from an error, or undefined if not available
+ */
+export function getErrorStack(error) {
+    return error instanceof Error ? error.stack : undefined;
+}
+//# sourceMappingURL=error-utils.js.map

package/dist/utils/error-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.js","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc,EAAE,OAAgB;IAClE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,KAAc;IACrC,OAAO,KAAK,YAAY,KAAK,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC3C,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC"}

package/dist/utils/file-lock.d.ts

@@ -0,0 +1,77 @@
+/**
+ * File Lock Utility - Atomic file operations with locking
+ *
+ * Provides thread-safe file operations for shared volumes across containers
+ */
+import type { FileLock } from '../types/exploration.types.js';
+/**
+ * Get error message from unknown error
+ */
+export interface LockOptions {
+    retries?: number;
+    retry_delay_ms?: number;
+    timeout_ms?: number;
+}
+export interface WriteOptions extends LockOptions {
+    pretty?: boolean;
+}
+export declare class FileLockManager {
+    private defaultOptions;
+    /**
+     * Acquire a lock on a file
+     */
+    acquireLock(filePath: string, lockerId: string, options?: LockOptions): Promise<FileLock>;
+    /**
+     * Release a lock
+     */
+    releaseLock(filePath: string, lockId: string, force?: boolean): Promise<void>;
+    /**
+     * Read a file with locking
+     */
+    readWithLock<T = unknown>(filePath: string, lockerId: string, options?: LockOptions): Promise<null | T>;
+    /**
+     * Write a file with locking (atomic write)
+     */
+    writeWithLock<T = unknown>(filePath: string, data: T, lockerId: string, options?: WriteOptions): Promise<void>;
+    /**
+     * Update a file with locking (read-modify-write)
+     */
+    updateWithLock<T = unknown>(filePath: string, lockerId: string, updater: (current: null | T) => T, options?: WriteOptions): Promise<T>;
+    /**
+     * Append to an array in a JSON file with locking
+     */
+    appendToArray<T = unknown>(filePath: string, item: T, lockerId: string, arrayKey?: string, options?: WriteOptions): Promise<void>;
+    /**
+     * Check if a file is locked
+     */
+    isLocked(filePath: string): Promise<boolean>;
+    /**
+     * Get lock information
+     */
+    getLockInfo(filePath: string): Promise<FileLock | null>;
+    /**
+     * Clean up expired locks
+     */
+    cleanupExpiredLocks(directory: string): Promise<number>;
+    /**
+     * Force remove all locks in a directory
+     */
+    forceRemoveAllLocks(directory: string): Promise<number>;
+    /**
+     * Get lock file path
+     */
+    private getLockPath;
+    /**
+     * Generate unique lock ID
+     */
+    private generateLockId;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+/**
+ * Get global file lock manager instance
+ */
+export declare function getFileLockManager(): FileLockManager;
+//# sourceMappingURL=file-lock.d.ts.map