@dollhousemcp/mcp-server 1.5.2 → 1.6.0

package/dist/utils/ErrorHandler.js

@@ -0,0 +1,201 @@
+/**
+ * Centralized error handling utilities for consistent error processing
+ * Preserves stack traces and provides user-friendly messages
+ */
+import { logger } from './logger.js';
+/**
+ * Error categories for better error handling
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    ErrorCategory["USER_ERROR"] = "USER_ERROR";
+    ErrorCategory["SYSTEM_ERROR"] = "SYSTEM_ERROR";
+    ErrorCategory["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCategory["AUTH_ERROR"] = "AUTH_ERROR";
+    ErrorCategory["VALIDATION_ERROR"] = "VALIDATION_ERROR"; // Validation failures
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Custom error class with additional context
+ */
+export class ApplicationError extends Error {
+    category;
+    code;
+    details;
+    originalError;
+    constructor(message, category = ErrorCategory.SYSTEM_ERROR, code, details, originalError) {
+        super(message);
+        this.name = 'ApplicationError';
+        this.category = category;
+        this.code = code;
+        this.details = details;
+        this.originalError = originalError;
+        // Maintain proper stack trace with truncation to prevent memory issues
+        if (originalError?.stack) {
+            const truncatedOriginalStack = ErrorHandler.truncateStack(originalError.stack);
+            this.stack = `${this.stack}\nCaused by: ${truncatedOriginalStack}`;
+        }
+    }
+}
+/**
+ * Utility class for consistent error handling
+ */
+export class ErrorHandler {
+    /**
+     * Maximum stack trace depth to prevent memory issues
+     */
+    static MAX_STACK_DEPTH = 10;
+    /**
+     * Maximum length for stack trace strings
+     */
+    static MAX_STACK_LENGTH = 5000;
+    /**
+     * Truncate stack trace to prevent memory issues
+     */
+    static truncateStack(stack) {
+        if (!stack)
+            return undefined;
+        // Limit total length
+        if (stack.length > this.MAX_STACK_LENGTH) {
+            stack = stack.substring(0, this.MAX_STACK_LENGTH) + '\n... (truncated)';
+        }
+        // Limit number of stack frames
+        const lines = stack.split('\n');
+        if (lines.length > this.MAX_STACK_DEPTH) {
+            return lines.slice(0, this.MAX_STACK_DEPTH).join('\n') + '\n... (truncated)';
+        }
+        return stack;
+    }
+    /**
+     * Extract error information while preserving context
+     */
+    static extractErrorInfo(error) {
+        // Handle ApplicationError
+        if (error instanceof ApplicationError) {
+            return {
+                message: error.message,
+                category: error.category,
+                code: error.code,
+                details: error.details,
+                stack: this.truncateStack(error.stack),
+                originalError: error.originalError
+            };
+        }
+        // Handle standard Error
+        if (error instanceof Error) {
+            return {
+                message: error.message,
+                category: ErrorCategory.SYSTEM_ERROR,
+                stack: this.truncateStack(error.stack),
+                originalError: error
+            };
+        }
+        // Handle string errors
+        if (typeof error === 'string') {
+            return {
+                message: error,
+                category: ErrorCategory.SYSTEM_ERROR
+            };
+        }
+        // Handle unknown errors
+        return {
+            message: 'An unknown error occurred',
+            category: ErrorCategory.SYSTEM_ERROR,
+            details: error
+        };
+    }
+    /**
+     * Get user-friendly error message
+     */
+    static getUserMessage(error) {
+        const errorInfo = this.extractErrorInfo(error);
+        // Provide user-friendly messages based on category
+        switch (errorInfo.category) {
+            case ErrorCategory.AUTH_ERROR:
+                return `Authentication error: ${errorInfo.message}`;
+            case ErrorCategory.VALIDATION_ERROR:
+                return `Validation error: ${errorInfo.message}`;
+            case ErrorCategory.NETWORK_ERROR:
+                return `Network error: ${errorInfo.message}. Please check your connection and try again.`;
+            case ErrorCategory.USER_ERROR:
+                return errorInfo.message; // User errors should already be user-friendly
+            default:
+                // For system errors, provide a generic message
+                return 'An unexpected error occurred. Please try again later.';
+        }
+    }
+    /**
+     * Log error with appropriate level and context
+     */
+    static logError(context, error, additionalInfo) {
+        const errorInfo = this.extractErrorInfo(error);
+        const logData = {
+            context,
+            category: errorInfo.category,
+            code: errorInfo.code,
+            message: errorInfo.message,
+            ...additionalInfo
+        };
+        // Log based on category
+        switch (errorInfo.category) {
+            case ErrorCategory.USER_ERROR:
+            case ErrorCategory.VALIDATION_ERROR:
+                logger.warn(`${context}: ${errorInfo.message}`, logData);
+                break;
+            case ErrorCategory.AUTH_ERROR:
+                logger.warn(`${context}: Authentication error`, logData);
+                break;
+            case ErrorCategory.NETWORK_ERROR:
+                logger.error(`${context}: Network error`, {
+                    ...logData,
+                    stack: errorInfo.stack
+                });
+                break;
+            default:
+                logger.error(`${context}: System error`, {
+                    ...logData,
+                    stack: errorInfo.stack,
+                    details: errorInfo.details
+                });
+        }
+        // Log stack trace in debug mode for all errors (already truncated)
+        if (errorInfo.stack) {
+            logger.debug(`${context} - Stack trace:`, { stack: errorInfo.stack });
+        }
+    }
+    /**
+     * Create an error with context preservation
+     */
+    static createError(message, category = ErrorCategory.SYSTEM_ERROR, code, originalError) {
+        const original = originalError instanceof Error ? originalError : undefined;
+        return new ApplicationError(message, category, code, undefined, original);
+    }
+    /**
+     * Wrap an error with additional context
+     */
+    static wrapError(error, context, category) {
+        const errorInfo = this.extractErrorInfo(error);
+        return new ApplicationError(`${context}: ${errorInfo.message}`, category || errorInfo.category, errorInfo.code, errorInfo.details, errorInfo.originalError);
+    }
+    /**
+     * Check if error is of a specific category
+     */
+    static isErrorCategory(error, category) {
+        const errorInfo = this.extractErrorInfo(error);
+        return errorInfo.category === category;
+    }
+    /**
+     * Format error for API response
+     */
+    static formatForResponse(error) {
+        const errorInfo = this.extractErrorInfo(error);
+        const userMessage = this.getUserMessage(error);
+        return {
+            success: false,
+            message: userMessage,
+            error: errorInfo.code || errorInfo.category,
+            // Only include details in development
+            details: process.env.NODE_ENV === 'development' ? errorInfo.details : undefined
+        };
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiRXJyb3JIYW5kbGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3V0aWxzL0Vycm9ySGFuZGxlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7O0dBR0c7QUFFSCxPQUFPLEVBQUUsTUFBTSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBRXJDOztHQUVHO0FBQ0gsTUFBTSxDQUFOLElBQVksYUFNWDtBQU5ELFdBQVksYUFBYTtJQUN2QiwwQ0FBeUIsQ0FBQTtJQUN6Qiw4Q0FBNkIsQ0FBQTtJQUM3QixnREFBK0IsQ0FBQTtJQUMvQiwwQ0FBeUIsQ0FBQTtJQUN6QixzREFBcUMsQ0FBQSxDQUFDLHNCQUFzQjtBQUM5RCxDQUFDLEVBTlcsYUFBYSxLQUFiLGFBQWEsUUFNeEI7QUFjRDs7R0FFRztBQUNILE1BQU0sT0FBTyxnQkFBaUIsU0FBUSxLQUFLO0lBQ3pCLFFBQVEsQ0FBZ0I7SUFDeEIsSUFBSSxDQUFVO0lBQ2QsT0FBTyxDQUEyQjtJQUNsQyxhQUFhLENBQVM7SUFFdEMsWUFDRSxPQUFlLEVBQ2YsV0FBMEIsYUFBYSxDQUFDLFlBQVksRUFDcEQsSUFBYSxFQUNiLE9BQWlDLEVBQ2pDLGFBQXFCO1FBRXJCLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsa0JBQWtCLENBQUM7UUFDL0IsSUFBSSxDQUFDLFFBQVEsR0FBRyxRQUFRLENBQUM7UUFDekIsSUFBSSxDQUFDLElBQUksR0FBRyxJQUFJLENBQUM7UUFDakIsSUFBSSxDQUFDLE9BQU8sR0FBRyxPQUFPLENBQUM7UUFDdkIsSUFBSSxDQUFDLGFBQWEsR0FBRyxhQUFhLENBQUM7UUFFbkMsdUVBQXVFO1FBQ3ZFLElBQUksYUFBYSxFQUFFLEtBQUssRUFBRSxDQUFDO1lBQ3pCLE1BQU0sc0JBQXNCLEdBQUcsWUFBWSxDQUFDLGFBQWEsQ0FBQyxhQUFhLENBQUMsS0FBSyxDQUFDLENBQUM7WUFDL0UsSUFBSSxDQUFDLEtBQUss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LEVBQ2pCLFNBQVMsQ0FBQyxhQUFhLENBQ3hCLENBQUM7SUFDSixDQUFDO0lBRUQ7O09BRUc7SUFDSCxNQUFNLENBQUMsZUFBZSxDQUFDLEtBQWMsRUFBRSxRQUF1QjtRQUM1RCxNQUFNLFNBQVMsR0FBRyxJQUFJLENBQUMsZ0JBQWdCLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDL0MsT0FBTyxTQUFTLENBQUMsUUFBUSxLQUFLLFFBQVEsQ0FBQztJQUN6QyxDQUFDO0lBRUQ7O09BRUc7SUFDSCxNQUFNLENBQUMsaUJBQWlCLENBQUMsS0FBYztRQU1yQyxNQUFNLFNBQVMsR0FBRyxJQUFJLENBQUMsZ0JBQWdCLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDL0MsTUFBTSxXQUFXLEdBQUcsSUFBSSxDQUFDLGNBQWMsQ0FBQyxLQUFLLENBQUMsQ0FBQztRQUUvQyxPQUFPO1lBQ0wsT0FBTyxFQUFFLEtBQUs7WUFDZCxPQUFPLEVBQUUsV0FBVztZQUNwQixLQUFLLEVBQUUsU0FBUyxDQUFDLElBQUksSUFBSSxTQUFTLENBQUMsUUFBUTtZQUMzQyxzQ0FBc0M7WUFDdEMsT0FBTyxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsUUFBUSxLQUFLLGFBQWEsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUMsU0FBUztTQUNoRixDQUFDO0lBQ0osQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQ2VudHJhbGl6ZWQgZXJyb3IgaGFuZGxpbmcgdXRpbGl0aWVzIGZvciBjb25zaXN0ZW50IGVycm9yIHByb2Nlc3NpbmdcbiAqIFByZXNlcnZlcyBzdGFjayB0cmFjZXMgYW5kIHByb3ZpZGVzIHVzZXItZnJpZW5kbHkgbWVzc2FnZXNcbiAqL1xuXG5pbXBvcnQgeyBsb2dnZXIgfSBmcm9tICcuL2xvZ2dlci5qcyc7XG5cbi8qKlxuICogRXJyb3IgY2F0ZWdvcmllcyBmb3IgYmV0dGVyIGVycm9yIGhhbmRsaW5nXG4gKi9cbmV4cG9ydCBlbnVtIEVycm9yQ2F0ZWdvcnkge1xuICBVU0VSX0VSUk9SID0gJ1VTRVJfRVJST1InLCAgICAgICAgLy8gVXNlciBpbnB1dCBpc3N1ZXNcbiAgU1lTVEVNX0VSUk9SID0gJ1NZU1RFTV9FUlJPUicsICAgIC8vIEludGVybmFsIHN5c3RlbSBmYWlsdXJlc1xuICBORVRXT1JLX0VSUk9SID0gJ05FVFdPUktfRVJST1InLCAgLy8gQVBJL25ldHdvcmsgaXNzdWVzXG4gIEFVVEhfRVJST1IgPSAnQVVUSF9FUlJPUicsICAgICAgICAvLyBBdXRoZW50aWNhdGlvbi9hdXRob3JpemF0aW9uXG4gIFZBTElEQVRJT05fRVJST1IgPSAnVkFMSURBVElPTl9FUlJPUicgLy8gVmFsaWRhdGlvbiBmYWlsdXJlc1xufVxuXG4vKipcbiAqIFN0cnVjdHVyZWQgZXJyb3IgaW5mb3JtYXRpb25cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBFcnJvckluZm8ge1xuICBtZXNzYWdlOiBzdHJpbmc7XG4gIGNhdGVnb3J5OiBFcnJvckNhdGVnb3J5O1xuICBjb2RlPzogc3RyaW5nO1xuICBkZXRhaWxzPzogUmVjb3JkPHN0cmluZywgdW5rbm93bj47XG4gIHN0YWNrPzogc3RyaW5nO1xuICBvcmlnaW5hbEVycm9yPzogRXJyb3I7XG59XG5cbi8qKlxuICogQ3VzdG9tIGVycm9yIGNsYXNzIHdpdGggYWRkaXRpb25hbCBjb250ZXh0XG4gKi9cbmV4cG9ydCBjbGFzcyBBcHBsaWNhdGlvbkVycm9yIGV4dGVuZHMgRXJyb3Ige1xuICBwdWJsaWMgcmVhZG9ubHkgY2F0ZWdvcnk6IEVycm9yQ2F0ZWdvcnk7XG4gIHB1YmxpYyByZWFkb25seSBjb2RlPzogc3RyaW5nO1xuICBwdWJsaWMgcmVhZG9ubHkgZGV0YWlscz86IFJlY29yZDxzdHJpbmcsIHVua25vd24+O1xuICBwdWJsaWMgcmVhZG9ubHkgb3JpZ2luYWxFcnJvcj86IEVycm9yO1xuXG4gIGNvbnN0cnVjdG9yKFxuICAgIG1lc3NhZ2U6IHN0cmluZyxcbiAgICBjYXRlZ29yeTogRXJyb3JDYXRlZ29yeSA9IEVycm9yQ2F0ZWdvcnkuU1lTVEVNX0VSUk9SLFxuICAgIGNvZGU/OiBzdHJpbmcsXG4gICAgZGV0YWlscz86IFJlY29yZDxzdHJpbmcsIHVua25vd24+LFxuICAgIG9yaWdpbmFsRXJyb3I/OiBFcnJvclxuICApIHtcbiAgICBzdXBlcihtZXNzYWdlKTtcbiAgICB0aGlzLm5hbWUgPSAnQXBwbGljYXRpb25FcnJvcic7XG4gICAgdGhpcy5jYXRlZ29yeSA9IGNhdGVnb3J5O1xuICAgIHRoaXMuY29kZSA9IGNvZGU7XG4gICAgdGhpcy5kZXRhaWxzID0gZGV0YWlscztcbiAgICB0aGlzLm9yaWdpbmFsRXJyb3IgPSBvcmlnaW5hbEVycm9yO1xuXG4gICAgLy8gTWFpbnRhaW4gcHJvcGVyIHN0YWNrIHRyYWNlIHdpdGggdHJ1bmNhdGlvbiB0byBwcmV2ZW50IG1lbW9yeSBpc3N1ZXNcbiAgICBpZiAob3JpZ2luYWxFcnJvcj8uc3RhY2spIHtcbiAgICAgIGNvbnN0IHRydW5jYXRlZE9yaWdpbmFsU3RhY2sgPSBFcnJvckhhbmRsZXIudHJ1bmNhdGVTdGFjayhvcmlnaW5hbEVycm9yLnN0YWNrKTtcbiAgICAgIHRoaXMuc3RhY2sgPSBgJHt0aGlzLnN0YWNrfVxcbkNhdXNlZCBieTogJHt0cnVuY2F0ZWRPcmlnaW5hbFN0YWNrfWA7XG4gICAgfVxuICB9XG59XG5cbi8qKlxuICogVXRpbGl0eSBjbGFzcyBmb3IgY29uc2lzdGVudCBlcnJvciBoYW5kbGluZ1xuICovXG5leHBvcnQgY2xhc3MgRXJyb3JIYW5kbGVyIHtcbiAgLyoqXG4gICAqIE1heGltdW0gc3RhY2sgdHJhY2UgZGVwdGggdG8gcHJldmVudCBtZW1vcnkgaXNzdWVzXG4gICAqL1xuICBwcml2YXRlIHN0YXRpYyByZWFkb25seSBNQVhfU1RBQ0tfREVQVEggPSAxMDtcbiAgXG4gIC8qKlxuICAgKiBNYXhpbXVtIGxlbmd0aCBmb3Igc3RhY2sgdHJhY2Ugc3RyaW5nc1xuICAgKi9cbiAgcHJpdmF0ZSBzdGF0aWMgcmVhZG9ubHkgTUFYX1NUQUNLX0xFTkdUSCA9IDUwMDA7XG4gIFxuICAvKipcbiAgICogVHJ1bmNhdGUgc3RhY2sgdHJhY2UgdG8gcHJldmVudCBtZW1vcnkgaXNzdWVzXG4gICAqL1xuICBwdWJsaWMgc3RhdGljIHRydW5jYXRlU3RhY2soc3RhY2s/OiBzdHJpbmcpOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICAgIGlmICghc3RhY2spIHJldHVybiB1bmRlZmluZWQ7XG4gICAgXG4gICAgLy8gTGltaXQgdG90YWwgbGVuZ3RoXG4gICAgaWYgKHN0YWNrLmxlbmd0aCA+IHRoaXMuTUFYX1NUQUNLX0xFTkdUSCkge1xuICAgICAgc3RhY2sgPSBzdGFjay5zdWJzdHJpbmcoMCwgdGhpcy5NQVhfU1RBQ0tfTEVOR1RIKSArICdcXG4uLi4gKHRydW5jYXRlZCknO1xuICAgIH1cbiAgICBcbiAgICAvLyBMaW1pdCBudW1iZXIgb2Ygc3RhY2sgZnJhbWVzXG4gICAgY29uc3QgbGluZXMgPSBzdGFjay5zcGxpdCgnXFxuJyk7XG4gICAgaWYgKGxpbmVzLmxlbmd0aCA+IHRoaXMuTUFYX1NUQUNLX0RFUFRIKSB7XG4gICAgICByZXR1cm4gbGluZXMuc2xpY2UoMCwgdGhpcy5NQVhfU1RBQ0tfREVQVEgpLmpvaW4oJ1xcbicpICsgJ1xcbi4uLiAodHJ1bmNhdGVkKSc7XG4gICAgfVxuICAgIFxuICAgIHJldHVybiBzdGFjaztcbiAgfVxuICBcbiAgLyoqXG4gICAqIEV4dHJhY3QgZXJyb3IgaW5mb3JtYXRpb24gd2hpbGUgcHJlc2VydmluZyBjb250ZXh0XG4gICAqL1xuICBzdGF0aWMgZXh0cmFjdEVycm9ySW5mbyhlcnJvcjogdW5rbm93bik6IEVycm9ySW5mbyB7XG4gICAgLy8gSGFuZGxlIEFwcGxpY2F0aW9uRXJyb3JcbiAgICBpZiAoZXJyb3IgaW5zdGFuY2VvZiBBcHBsaWNhdGlvbkVycm9yKSB7XG4gICAgICByZXR1cm4ge1xuICAgICAgICBtZXNzYWdlOiBlcnJvci5tZXNzYWdlLFxuICAgICAgICBjYXRlZ29yeTogZXJyb3IuY2F0ZWdvcnksXG4gICAgICAgIGNvZGU6IGVycm9yLmNvZGUsXG4gICAgICAgIGRldGFpbHM6IGVycm9yLmRldGFpbHMsXG4gICAgICAgIHN0YWNrOiB0aGlzLnRydW5jYXRlU3RhY2soZXJyb3Iuc3RhY2spLFxuICAgICAgICBvcmlnaW5hbEVycm9yOiBlcnJvci5vcmlnaW5hbEVycm9yXG4gICAgICB9O1xuICAgIH1cblxuICAgIC8vIEhhbmRsZSBzdGFuZGFyZCBFcnJvclxuICAgIGlmIChlcnJvciBpbnN0YW5jZW9mIEVycm9yKSB7XG4gICAgICByZXR1cm4ge1xuICAgICAgICBtZXNzYWdlOiBlcnJvci5tZXNzYWdlLFxuICAgICAgICBjYXRlZ29yeTogRXJyb3JDYXRlZ29yeS5TWVNURU1fRVJST1IsXG4gICAgICAgIHN0YWNrOiB0aGlzLnRydW5jYXRlU3RhY2soZXJyb3Iuc3RhY2spLFxuICAgICAgICBvcmlnaW5hbEVycm9yOiBlcnJvclxuICAgICAgfTtcbiAgICB9XG5cbiAgICAvLyBIYW5kbGUgc3RyaW5nIGVycm9yc1xuICAgIGlmICh0eXBlb2YgZXJyb3IgPT09ICdzdHJpbmcnKSB7XG4gICAgICByZXR1cm4ge1xuICAgICAgICBtZXNzYWdlOiBlcnJvcixcbiAgICAgICAgY2F0ZWdvcnk6IEVycm9yQ2F0ZWdvcnkuU1lTVEVNX0VSUk9SXG4gICAgICB9O1xuICAgIH1cblxuICAgIC8vIEhhbmRsZSB1bmtub3duIGVycm9yc1xuICAgIHJldHVybiB7XG4gICAgICBtZXNzYWdlOiAnQW4gdW5rbm93biBlcnJvciBvY2N1cnJlZCcsXG4gICAgICBjYXRlZ29yeTogRXJyb3JDYXRlZ29yeS5TWVNURU1fRVJST1IsXG4gICAgICBkZXRhaWxzOiBlcnJvciBhcyBSZWNvcmQ8c3RyaW5nLCB1bmtub3duPiB8IHVuZGVmaW5lZFxuICAgIH07XG4gIH1cblxuICAvKipcbiAgICogR2V0IHVzZXItZnJpZW5kbHkgZXJyb3IgbWVzc2FnZVxuICAgKi9cbiAgc3RhdGljIGdldFVzZXJNZXNzYWdlKGVycm9yOiB1bmtub3duKTogc3RyaW5nIHtcbiAgICBjb25zdCBlcnJvckluZm8gPSB0aGlzLmV4dHJhY3RFcnJvckluZm8oZXJyb3IpO1xuICAgIFxuICAgIC8vIFByb3ZpZGUgdXNlci1mcmllbmRseSBtZXNzYWdlcyBiYXNlZCBvbiBjYXRlZ29yeVxuICAgIHN3aXRjaCAoZXJyb3JJbmZvLmNhdGVnb3J5KSB7XG4gICAgICBjYXNlIEVycm9yQ2F0ZWdvcnkuQVVUSF9FUlJPUjpcbiAgICAgICAgcmV0dXJuIGBBdXRoZW50aWNhdGlvbiBlcnJvcjogJHtlcnJvckluZm8ubWVzc2FnZX1gO1xuICAgICAgY2FzZSBFcnJvckNhdGVnb3J5LlZBTElEQVRJT05fRVJST1I6XG4gICAgICAgIHJldHVybiBgVmFsaWRhdGlvbiBlcnJvcjogJHtlcnJvckluZm8ubWVzc2FnZX1gO1xuICAgICAgY2FzZSBFcnJvckNhdGVnb3J5Lk5FVFdPUktfRVJST1I6XG4gICAgICAgIHJldHVybiBgTmV0d29yayBlcnJvcjogJHtlcnJvckluZm8ubWVzc2FnZX0uIFBsZWFzZSBjaGVjayB5b3VyIGNvbm5lY3Rpb24gYW5kIHRyeSBhZ2Fpbi5gO1xuICAgICAgY2FzZSBFcnJvckNhdGVnb3J5LlVTRVJfRVJST1I6XG4gICAgICAgIHJldHVybiBlcnJvckluZm8ubWVzc2FnZTsgLy8gVXNlciBlcnJvcnMgc2hvdWxkIGFscmVhZHkgYmUgdXNlci1mcmllbmRseVxuICAgICAgZGVmYXVsdDpcbiAgICAgICAgLy8gRm9yIHN5c3RlbSBlcnJvcnMsIHByb3ZpZGUgYSBnZW5lcmljIG1lc3NhZ2VcbiAgICAgICAgcmV0dXJuICdBbiB1bmV4cGVjdGVkIGVycm9yIG9jY3VycmVkLiBQbGVhc2UgdHJ5IGFnYWluIGxhdGVyLic7XG4gICAgfVxuICB9XG5cbiAgLyoqXG4gICAqIExvZyBlcnJvciB3aXRoIGFwcHJvcHJpYXRlIGxldmVsIGFuZCBjb250ZXh0XG4gICAqL1xuICBzdGF0aWMgbG9nRXJyb3IoXG4gICAgY29udGV4dDogc3RyaW5nLFxuICAgIGVycm9yOiB1bmtub3duLFxuICAgIGFkZGl0aW9uYWxJbmZvPzogUmVjb3JkPHN0cmluZywgdW5rbm93bj5cbiAgKTogdm9pZCB7XG4gICAgY29uc3QgZXJyb3JJbmZvID0gdGhpcy5leHRyYWN0RXJyb3JJbmZvKGVycm9yKTtcbiAgICBcbiAgICBjb25zdCBsb2dEYXRhID0ge1xuICAgICAgY29udGV4dCxcbiAgICAgIGNhdGVnb3J5OiBlcnJvckluZm8uY2F0ZWdvcnksXG4gICAgICBjb2RlOiBlcnJvckluZm8uY29kZSxcbiAgICAgIG1lc3NhZ2U6IGVycm9ySW5mby5tZXNzYWdlLFxuICAgICAgLi4uYWRkaXRpb25hbEluZm9cbiAgICB9O1xuXG4gICAgLy8gTG9nIGJhc2VkIG9uIGNhdGVnb3J5XG4gICAgc3dpdGNoIChlcnJvckluZm8uY2F0ZWdvcnkpIHtcbiAgICAgIGNhc2UgRXJyb3JDYXRlZ29yeS5VU0VSX0VSUk9SOlxuICAgICAgY2FzZSBFcnJvckNhdGVnb3J5LlZBTElEQVRJT05fRVJST1I6XG4gICAgICAgIGxvZ2dlci53YXJuKGAke2NvbnRleHR9OiAke2Vycm9ySW5mby5tZXNzYWdlfWAsIGxvZ0RhdGEpO1xuICAgICAgICBicmVhaztcbiAgICAgIGNhc2UgRXJyb3JDYXRlZ29yeS5BVVRIX0VSUk9SOlxuICAgICAgICBsb2dnZXIud2FybihgJHtjb250ZXh0fTogQXV0aGVudGljYXRpb24gZXJyb3JgLCBsb2dEYXRhKTtcbiAgICAgICAgYnJlYWs7XG4gICAgICBjYXNlIEVycm9yQ2F0ZWdvcnkuTkVUV09SS19FUlJPUjpcbiAgICAgICAgbG9nZ2VyLmVycm9yKGAke2NvbnRleHR9OiBOZXR3b3JrIGVycm9yYCwge1xuICAgICAgICAgIC4uLmxvZ0RhdGEsXG4gICAgICAgICAgc3RhY2s6IGVycm9ySW5mby5zdGFja1xuICAgICAgICB9KTtcbiAgICAgICAgYnJlYWs7XG4gICAgICBkZWZhdWx0OlxuICAgICAgICBsb2dnZXIuZXJyb3IoYCR7Y29udGV4dH06IFN5c3RlbSBlcnJvcmAsIHtcbiAgICAgICAgICAuLi5sb2dEYXRhLFxuICAgICAgICAgIHN0YWNrOiBlcnJvckluZm8uc3RhY2ssXG4gICAgICAgICAgZGV0YWlsczogZXJyb3JJbmZvLmRldGFpbHNcbiAgICAgICAgfSk7XG4gICAgfVxuXG4gICAgLy8gTG9nIHN0YWNrIHRyYWNlIGluIGRlYnVnIG1vZGUgZm9yIGFsbCBlcnJvcnMgKGFscmVhZHkgdHJ1bmNhdGVkKVxuICAgIGlmIChlcnJvckluZm8uc3RhY2spIHtcbiAgICAgIGxvZ2dlci5kZWJ1ZyhgJHtjb250ZXh0fSAtIFN0YWNrIHRyYWNlOmAsIHsgc3RhY2s6IGVycm9ySW5mby5zdGFjayB9KTtcbiAgICB9XG4gIH1cblxuICAvKipcbiAgICogQ3JlYXRlIGFuIGVycm9yIHdpdGggY29udGV4dCBwcmVzZXJ2YXRpb25cbiAgICovXG4gIHN0YXRpYyBjcmVhdGVFcnJvcihcbiAgICBtZXNzYWdlOiBzdHJpbmcsXG4gICAgY2F0ZWdvcnk6IEVycm9yQ2F0ZWdvcnkgPSBFcnJvckNhdGVnb3J5LlNZU1RFTV9FUlJPUixcbiAgICBjb2RlPzogc3RyaW5nLFxuICAgIG9yaWdpbmFsRXJyb3I/OiB1bmtub3duXG4gICk6IEFwcGxpY2F0aW9uRXJyb3Ige1xuICAgIGNvbnN0IG9yaWdpbmFsID0gb3JpZ2luYWxFcnJvciBpbnN0YW5jZW9mIEVycm9yID8gb3JpZ2luYWxFcnJvciA6IHVuZGVmaW5lZDtcbiAgICByZXR1cm4gbmV3IEFwcGxpY2F0aW9uRXJyb3IobWVzc2FnZSwgY2F0ZWdvcnksIGNvZGUsIHVuZGVmaW5lZCwgb3JpZ2luYWwpO1xuICB9XG5cbiAgLyoqXG4gICAqIFdyYXAgYW4gZXJyb3Igd2l0aCBhZGRpdGlvbmFsIGNvbnRleHRcbiAgICovXG4gIHN0YXRpYyB3cmFwRXJyb3IoXG4gICAgZXJyb3I6IHVua25vd24sXG4gICAgY29udGV4dDogc3RyaW5nLFxuICAgIGNhdGVnb3J5PzogRXJyb3JDYXRlZ29yeVxuICApOiBBcHBsaWNhdGlvbkVycm9yIHtcbiAgICBjb25zdCBlcnJvckluZm8gPSB0aGlzLmV4dHJhY3RFcnJvckluZm8oZXJyb3IpO1xuICAgIHJldHVybiBuZXcgQXBwbGljYXRpb25FcnJvcihcbiAgICAgIGAke2NvbnRleHR9OiAke2Vycm9ySW5mby5tZXNzYWdlfWAsXG4gICAgICBjYXRlZ29yeSB8fCBlcnJvckluZm8uY2F0ZWdvcnksXG4gICAgICBlcnJvckluZm8uY29kZSxcbiAgICAgIGVycm9ySW5mby5kZXRhaWxzLFxuICAgICAgZXJyb3JJbmZvLm9yaWdpbmFsRXJyb3JcbiAgICApO1xuICB9XG5cbiAgLyoqXG4gICAqIENoZWNrIGlmIGVycm9yIGlzIG9mIGEgc3BlY2lmaWMgY2F0ZWdvcnlcbiAgICovXG4gIHN0YXRpYyBpc0Vycm9yQ2F0ZWdvcnkoZXJyb3I6IHVua25vd24sIGNhdGVnb3J5OiBFcnJvckNhdGVnb3J5KTogYm9vbGVhbiB7XG4gICAgY29uc3QgZXJyb3JJbmZvID0gdGhpcy5leHRyYWN0RXJyb3JJbmZvKGVycm9yKTtcbiAgICByZXR1cm4gZXJyb3JJbmZvLmNhdGVnb3J5ID09PSBjYXRlZ29yeTtcbiAgfVxuXG4gIC8qKlxuICAgKiBGb3JtYXQgZXJyb3IgZm9yIEFQSSByZXNwb25zZVxuICAgKi9cbiAgc3RhdGljIGZvcm1hdEZvclJlc3BvbnNlKGVycm9yOiB1bmtub3duKToge1xuICAgIHN1Y2Nlc3M6IGZhbHNlO1xuICAgIG1lc3NhZ2U6IHN0cmluZztcbiAgICBlcnJvcjogc3RyaW5nO1xuICAgIGRldGFpbHM/OiBSZWNvcmQ8c3RyaW5nLCB1bmtub3duPjtcbiAgfSB7XG4gICAgY29uc3QgZXJyb3JJbmZvID0gdGhpcy5leHRyYWN0RXJyb3JJbmZvKGVycm9yKTtcbiAgICBjb25zdCB1c2VyTWVzc2FnZSA9IHRoaXMuZ2V0VXNlck1lc3NhZ2UoZXJyb3IpO1xuICAgIFxuICAgIHJldHVybiB7XG4gICAgICBzdWNjZXNzOiBmYWxzZSxcbiAgICAgIG1lc3NhZ2U6IHVzZXJNZXNzYWdlLFxuICAgICAgZXJyb3I6IGVycm9ySW5mby5jb2RlIHx8IGVycm9ySW5mby5jYXRlZ29yeSxcbiAgICAgIC8vIE9ubHkgaW5jbHVkZSBkZXRhaWxzIGluIGRldmVsb3BtZW50XG4gICAgICBkZXRhaWxzOiBwcm9jZXNzLmVudi5OT0RFX0VOViA9PT0gJ2RldmVsb3BtZW50JyA/IGVycm9ySW5mby5kZXRhaWxzIDogdW5kZWZpbmVkXG4gICAgfTtcbiAgfVxufSJdfQ==

package/dist/utils/FileDiscoveryUtil.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Utility class for efficient file discovery operations
+ * Provides optimized file search with caching and security
+ *
+ * IMPLEMENTATION (PR #503 - PR #496 Recommendation):
+ * 1. PERFORMANCE: Single readdir operation instead of multiple file checks
+ * 2. PERFORMANCE: 5-second cache TTL for repeated searches
+ * 3. SECURITY: Unicode normalization for all search inputs
+ * 4. MEMORY: Efficient cache management with 100 entry limit
+ *
+ * This addresses the PR #496 review recommendation to extract file discovery
+ * logic to a reusable utility class for better performance and maintainability.
+ */
+export interface FileSearchOptions {
+    extensions?: string[];
+    partialMatch?: boolean;
+    maxResults?: number;
+    cacheResults?: boolean;
+}
+export declare class FileDiscoveryUtil {
+    private static readonly CACHE_TTL;
+    private static cache;
+    /**
+     * Find files in a directory with optimized search
+     * Uses single readdir operation and filters results
+     */
+    static findFiles(directory: string, searchName: string, options?: FileSearchOptions): Promise<string[]>;
+    /**
+     * Build search patterns for different file extensions
+     */
+    private static buildSearchPatterns;
+    /**
+     * Check if filename matches pattern
+     */
+    private static matchesPattern;
+    /**
+     * Get cached results if still valid
+     */
+    private static getCached;
+    /**
+     * Cache results with timestamp
+     */
+    private static setCached;
+    /**
+     * Clear the cache
+     */
+    static clearCache(): void;
+    /**
+     * Find a single file (convenience method)
+     */
+    static findFile(directory: string, searchName: string, options?: FileSearchOptions): Promise<string | null>;
+}
+//# sourceMappingURL=FileDiscoveryUtil.d.ts.map

package/dist/utils/FileDiscoveryUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileDiscoveryUtil.d.ts","sourceRoot":"","sources":["../../src/utils/FileDiscoveryUtil.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAOD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAQ;IACzC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAiC;IAErD;;;OAGG;WACU,SAAS,CACpB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC;IAkFpB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAoBlC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAO7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAaxB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAiBxB;;OAEG;IACH,MAAM,CAAC,UAAU,IAAI,IAAI;IAKzB;;OAEG;WACU,QAAQ,CACnB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAO1B"}

package/dist/utils/FileDiscoveryUtil.js

@@ -0,0 +1,169 @@
+/**
+ * Utility class for efficient file discovery operations
+ * Provides optimized file search with caching and security
+ *
+ * IMPLEMENTATION (PR #503 - PR #496 Recommendation):
+ * 1. PERFORMANCE: Single readdir operation instead of multiple file checks
+ * 2. PERFORMANCE: 5-second cache TTL for repeated searches
+ * 3. SECURITY: Unicode normalization for all search inputs
+ * 4. MEMORY: Efficient cache management with 100 entry limit
+ *
+ * This addresses the PR #496 review recommendation to extract file discovery
+ * logic to a reusable utility class for better performance and maintainability.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { logger } from './logger.js';
+import { UnicodeValidator } from '../security/validators/unicodeValidator.js';
+export class FileDiscoveryUtil {
+    static CACHE_TTL = 5000; // 5 seconds cache TTL
+    static cache = new Map();
+    /**
+     * Find files in a directory with optimized search
+     * Uses single readdir operation and filters results
+     */
+    static async findFiles(directory, searchName, options = {}) {
+        const { extensions = ['.json', '.yaml', '.yml', '.md'], partialMatch = true, maxResults = 10, cacheResults = true } = options;
+        // Normalize search name for security
+        const normalizedSearch = UnicodeValidator.normalize(searchName);
+        if (!normalizedSearch.isValid) {
+            logger.warn('Invalid Unicode in search name', {
+                issues: normalizedSearch.detectedIssues
+            });
+            return [];
+        }
+        const safeName = normalizedSearch.normalizedContent.toLowerCase();
+        // Check cache if enabled
+        const cacheKey = `${directory}:${safeName}:${JSON.stringify(options)}`;
+        if (cacheResults) {
+            const cached = this.getCached(cacheKey);
+            if (cached) {
+                logger.debug('File search cache hit', { directory, searchName });
+                return cached;
+            }
+        }
+        try {
+            // Single readdir operation for efficiency
+            const files = await fs.readdir(directory);
+            // Build search patterns
+            const searchPatterns = this.buildSearchPatterns(safeName, extensions);
+            // Filter files efficiently
+            const matches = [];
+            for (const file of files) {
+                const fileLower = file.toLowerCase();
+                // Check each pattern
+                for (const pattern of searchPatterns) {
+                    if (this.matchesPattern(fileLower, pattern, partialMatch)) {
+                        const fullPath = path.join(directory, file);
+                        matches.push(fullPath);
+                        if (matches.length >= maxResults) {
+                            break;
+                        }
+                    }
+                }
+                if (matches.length >= maxResults) {
+                    break;
+                }
+            }
+            // Cache results if enabled
+            if (cacheResults && matches.length > 0) {
+                this.setCached(cacheKey, matches);
+            }
+            // Log file discovery for monitoring
+            if (matches.length > 0) {
+                logger.debug('Files discovered', {
+                    directory,
+                    searchName,
+                    count: matches.length
+                });
+            }
+            return matches;
+        }
+        catch (error) {
+            logger.error('File discovery failed', {
+                directory,
+                searchName,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return [];
+        }
+    }
+    /**
+     * Build search patterns for different file extensions
+     */
+    static buildSearchPatterns(baseName, extensions) {
+        const patterns = [baseName];
+        // Add extension variations
+        for (const ext of extensions) {
+            patterns.push(`${baseName}${ext}`);
+        }
+        // Add common variations
+        const nameWithoutExtension = baseName.replace(/\.[^.]+$/, '');
+        if (nameWithoutExtension !== baseName) {
+            patterns.push(nameWithoutExtension);
+            for (const ext of extensions) {
+                patterns.push(`${nameWithoutExtension}${ext}`);
+            }
+        }
+        return patterns;
+    }
+    /**
+     * Check if filename matches pattern
+     */
+    static matchesPattern(filename, pattern, partialMatch) {
+        if (partialMatch) {
+            return filename.includes(pattern);
+        }
+        return filename === pattern;
+    }
+    /**
+     * Get cached results if still valid
+     */
+    static getCached(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        const age = Date.now() - entry.timestamp;
+        if (age > this.CACHE_TTL) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.files;
+    }
+    /**
+     * Cache results with timestamp
+     */
+    static setCached(key, files) {
+        // Limit cache size to prevent memory issues
+        if (this.cache.size > 100) {
+            // Remove oldest entries
+            const entries = Array.from(this.cache.entries());
+            entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+            for (let i = 0; i < 50; i++) {
+                this.cache.delete(entries[i][0]);
+            }
+        }
+        this.cache.set(key, {
+            files,
+            timestamp: Date.now()
+        });
+    }
+    /**
+     * Clear the cache
+     */
+    static clearCache() {
+        this.cache.clear();
+        logger.debug('File discovery cache cleared');
+    }
+    /**
+     * Find a single file (convenience method)
+     */
+    static async findFile(directory, searchName, options) {
+        const files = await this.findFiles(directory, searchName, {
+            ...options,
+            maxResults: 1
+        });
+        return files.length > 0 ? files[0] : null;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiRmlsZURpc2NvdmVyeVV0aWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdXRpbHMvRmlsZURpc2NvdmVyeVV0aWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7OztHQVlHO0FBRUgsT0FBTyxLQUFLLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDbEMsT0FBTyxLQUFLLElBQUksTUFBTSxNQUFNLENBQUM7QUFDN0IsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUNyQyxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSw0Q0FBNEMsQ0FBQztBQWU5RSxNQUFNLE9BQU8saUJBQWlCO0lBQ3BCLE1BQU0sQ0FBVSxTQUFTLEdBQUcsSUFBSSxDQUFDLENBQUMsc0JBQXNCO0lBQ3hELE1BQU0sQ0FBQyxLQUFLLEdBQUcsSUFBSSxHQUFHLEVBQXNCLENBQUM7SUFFckQ7OztPQUdHO0lBQ0gsTUFBTSxDQUFDLEtBQUssQ0FBQyxTQUFTLENBQ3BCLFNBQWlCLEVBQ2pCLFVBQWtCLEVBQ2xCLFVBQTZCLEVBQUU7UUFFL0IsTUFBTSxFQUNKLFVBQVUsR0FBRyxDQUFDLE9BQU8sRUFBRSxPQUFPLEVBQUUsTUFBTSxFQUFFLEtBQUssQ0FBQyxFQUM5QyxZQUFZLEdBQUcsSUFBSSxFQUNuQixVQUFVLEdBQUcsRUFBRSxFQUNmLFlBQVksR0FBRyxJQUFJLEVBQ3BCLEdBQUcsT0FBTyxDQUFDO1FBRVoscUNBQXFDO1FBQ3JDLE1BQU0sZ0JBQWdCLEdBQUcsZ0JBQWdCLENBQUMsU0FBUyxDQUFDLFVBQVUsQ0FBQyxDQUFDO1FBQ2hFLElBQUksQ0FBQyxnQkFBZ0IsQ0FBQyxPQUFPLEVBQUUsQ0FBQztZQUM5QixNQUFNLENBQUMsSUFBSSxDQUFDLGdDQUFnQyxFQUFFO2dCQUM1QyxNQUFNLEVBQUUsZ0JBQWdCLENBQUMsY0FBYzthQUN4QyxDQUFDLENBQUM7WUFDSCxPQUFPLEVBQUUsQ0FBQztRQUNaLENBQUM7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QixFQUNqQixVQUFrQixFQUNsQixPQUEyQjtRQUUzQixNQUFNLEtBQUssR0FBRyxNQUFNLElBQUksQ0FBQyxTQUFTLENBQUMsU0FBUyxFQUFFLFVBQVUsRUFBRTtZQUN4RCxHQUFHLE9BQU87WUFDVixVQUFVLEVBQUUsQ0FBQztTQUNkLENBQUMsQ0FBQztRQUNILE9BQU8sS0FBSyxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDO0lBQzVDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIFV0aWxpdHkgY2xhc3MgZm9yIGVmZmljaWVudCBmaWxlIGRpc2NvdmVyeSBvcGVyYXRpb25zXG4gKiBQcm92aWRlcyBvcHRpbWl6ZWQgZmlsZSBzZWFyY2ggd2l0aCBjYWNoaW5nIGFuZCBzZWN1cml0eVxuICogXG4gKiBJTVBMRU1FTlRBVElPTiAoUFIgIzUwMyAtIFBSICM0OTYgUmVjb21tZW5kYXRpb24pOlxuICogMS4gUEVSRk9STUFOQ0U6IFNpbmdsZSByZWFkZGlyIG9wZXJhdGlvbiBpbnN0ZWFkIG9mIG11bHRpcGxlIGZpbGUgY2hlY2tzXG4gKiAyLiBQRVJGT1JNQU5DRTogNS1zZWNvbmQgY2FjaGUgVFRMIGZvciByZXBlYXRlZCBzZWFyY2hlc1xuICogMy4gU0VDVVJJVFk6IFVuaWNvZGUgbm9ybWFsaXphdGlvbiBmb3IgYWxsIHNlYXJjaCBpbnB1dHNcbiAqIDQuIE1FTU9SWTogRWZmaWNpZW50IGNhY2hlIG1hbmFnZW1lbnQgd2l0aCAxMDAgZW50cnkgbGltaXRcbiAqIFxuICogVGhpcyBhZGRyZXNzZXMgdGhlIFBSICM0OTYgcmV2aWV3IHJlY29tbWVuZGF0aW9uIHRvIGV4dHJhY3QgZmlsZSBkaXNjb3ZlcnlcbiAqIGxvZ2ljIHRvIGEgcmV1c2FibGUgdXRpbGl0eSBjbGFzcyBmb3IgYmV0dGVyIHBlcmZvcm1hbmNlIGFuZCBtYWludGFpbmFiaWxpdHkuXG4gKi9cblxuaW1wb3J0ICogYXMgZnMgZnJvbSAnZnMvcHJvbWlzZXMnO1xuaW1wb3J0ICogYXMgcGF0aCBmcm9tICdwYXRoJztcbmltcG9ydCB7IGxvZ2dlciB9IGZyb20gJy4vbG9nZ2VyLmpzJztcbmltcG9ydCB7IFVuaWNvZGVWYWxpZGF0b3IgfSBmcm9tICcuLi9zZWN1cml0eS92YWxpZGF0b3JzL3VuaWNvZGVWYWxpZGF0b3IuanMnO1xuaW1wb3J0IHsgU2VjdXJpdHlNb25pdG9yIH0gZnJvbSAnLi4vc2VjdXJpdHkvc2VjdXJpdHlNb25pdG9yLmpzJztcblxuZXhwb3J0IGludGVyZmFjZSBGaWxlU2VhcmNoT3B0aW9ucyB7XG4gIGV4dGVuc2lvbnM/OiBzdHJpbmdbXTtcbiAgcGFydGlhbE1hdGNoPzogYm9vbGVhbjtcbiAgbWF4UmVzdWx0cz86IG51bWJlcjtcbiAgY2FjaGVSZXN1bHRzPzogYm9vbGVhbjtcbn1cblxuaW50ZXJmYWNlIENhY2hlRW50cnkge1xuICBmaWxlczogc3RyaW5nW107XG4gIHRpbWVzdGFtcDogbnVtYmVyO1xufVxuXG5leHBvcnQgY2xhc3MgRmlsZURpc2NvdmVyeVV0aWwge1xuICBwcml2YXRlIHN0YXRpYyByZWFkb25seSBDQUNIRV9UVEwgPSA1MDAwOyAvLyA1IHNlY29uZHMgY2FjaGUgVFRMXG4gIHByaXZhdGUgc3RhdGljIGNhY2hlID0gbmV3IE1hcDxzdHJpbmcsIENhY2hlRW50cnk+KCk7XG4gIFxuICAvKipcbiAgICogRmluZCBmaWxlcyBpbiBhIGRpcmVjdG9yeSB3aXRoIG9wdGltaXplZCBzZWFyY2hcbiAgICogVXNlcyBzaW5nbGUgcmVhZGRpciBvcGVyYXRpb24gYW5kIGZpbHRlcnMgcmVzdWx0c1xuICAgKi9cbiAgc3RhdGljIGFzeW5jIGZpbmRGaWxlcyhcbiAgICBkaXJlY3Rvcnk6IHN0cmluZyxcbiAgICBzZWFyY2hOYW1lOiBzdHJpbmcsXG4gICAgb3B0aW9uczogRmlsZVNlYXJjaE9wdGlvbnMgPSB7fVxuICApOiBQcm9taXNlPHN0cmluZ1tdPiB7XG4gICAgY29uc3Qge1xuICAgICAgZXh0ZW5zaW9ucyA9IFsnLmpzb24nLCAnLnlhbWwnLCAnLnltbCcsICcubWQnXSxcbiAgICAgIHBhcnRpYWxNYXRjaCA9IHRydWUsXG4gICAgICBtYXhSZXN1bHRzID0gMTAsXG4gICAgICBjYWNoZVJlc3VsdHMgPSB0cnVlXG4gICAgfSA9IG9wdGlvbnM7XG4gICAgXG4gICAgLy8gTm9ybWFsaXplIHNlYXJjaCBuYW1lIGZvciBzZWN1cml0eVxuICAgIGNvbnN0IG5vcm1hbGl6ZWRTZWFyY2ggPSBVbmljb2RlVmFsaWRhdG9yLm5vcm1hbGl6ZShzZWFyY2hOYW1lKTtcbiAgICBpZiAoIW5vcm1hbGl6ZWRTZWFyY2guaXNWYWxpZCkge1xuICAgICAgbG9nZ2VyLndhcm4oJ0ludmFsaWQgVW5pY29kZSBpbiBzZWFyY2ggbmFtZScsIHtcbiAgICAgICAgaXNzdWVzOiBub3JtYWxpemVkU2VhcmNoLmRldGVjdGVkSXNzdWVzXG4gICAgICB9KTtcbiAgICAgIHJldHVybiBbXTtcbiAgICB9XG4gICAgY29uc3Qgc2FmZU5hbWUgPSBub3JtYWxpemVkU2VhcmNoLm5vcm1hbGl6ZWRDb250ZW50LnRvTG93ZXJDYXNlKCk7XG4gICAgXG4gICAgLy8gQ2hlY2sgY2FjaGUgaWYgZW5hYmxlZFxuICAgIGNvbnN0IGNhY2hlS2V5ID0gYCR7ZGlyZWN0b3J5fToke3NhZmVOYW1lfToke0pTT04uc3RyaW5naWZ5KG9wdGlvbnMpfWA7XG4gICAgaWYgKGNhY2hlUmVzdWx0cykge1xuICAgICAgY29uc3QgY2FjaGVkID0gdGhpcy5nZXRDYWNoZWQoY2FjaGVLZXkpO1xuICAgICAgaWYgKGNhY2hlZCkge1xuICAgICAgICBsb2dnZXIuZGVidWcoJ0ZpbGUgc2VhcmNoIGNhY2hlIGhpdCcsIHsgZGlyZWN0b3J5LCBzZWFyY2hOYW1lIH0pO1xuICAgICAgICByZXR1cm4gY2FjaGVkO1xuICAgICAgfVxuICAgIH1cbiAgICBcbiAgICB0cnkge1xuICAgICAgLy8gU2luZ2xlIHJlYWRkaXIgb3BlcmF0aW9uIGZvciBlZmZpY2llbmN5XG4gICAgICBjb25zdCBmaWxlcyA9IGF3YWl0IGZzLnJlYWRkaXIoZGlyZWN0b3J5KTtcbiAgICAgIFxuICAgICAgLy8gQnVpbGQgc2VhcmNoIHBhdHRlcm5zXG4gICAgICBjb25zdCBzZWFyY2hQYXR0ZXJucyA9IHRoaXMuYnVpbGRTZWFyY2hQYXR0ZXJucyhzYWZlTmFtZSwgZXh0ZW5zaW9ucyk7XG4gICAgICBcbiAgICAgIC8vIEZpbHRlciBmaWxlcyBlZmZpY2llbnRseVxuICAgICAgY29uc3QgbWF0Y2hlczogc3RyaW5nW10gPSBbXTtcbiAgICAgIGZvciAoY29uc3QgZmlsZSBvZiBmaWxlcykge1xuICAgICAgICBjb25zdCBmaWxlTG93ZXIgPSBmaWxlLnRvTG93ZXJDYXNlKCk7XG4gICAgICAgIFxuICAgICAgICAvLyBDaGVjayBlYWNoIHBhdHRlcm5cbiAgICAgICAgZm9yIChjb25zdCBwYXR0ZXJuIG9mIHNlYXJjaFBhdHRlcm5zKSB7XG4gICAgICAgICAgaWYgKHRoaXMubWF0Y2hlc1BhdHRlcm4oZmlsZUxvd2VyLCBwYXR0ZXJuLCBwYXJ0aWFsTWF0Y2gpKSB7XG4gICAgICAgICAgICBjb25zdCBmdWxsUGF0aCA9IHBhdGguam9pbihkaXJlY3RvcnksIGZpbGUpO1xuICAgICAgICAgICAgbWF0Y2hlcy5wdXNoKGZ1bGxQYXRoKTtcbiAgICAgICAgICAgIFxuICAgICAgICAgICAgaWYgKG1hdGNoZXMubGVuZ3RoID49IG1heFJlc3VsdHMpIHtcbiAgICAgICAgICAgICAgYnJlYWs7XG4gICAgICAgICAgICB9XG4gICAgICAgICAgfVxuICAgICAgICB9XG4gICAgICAgIFxuICAgICAgICBpZiAobWF0Y2hlcy5sZW5ndGggPj0gbWF4UmVzdWx0cykge1xuICAgICAgICAgIGJyZWFrO1xuICAgICAgICB9XG4gICAgICB9XG4gICAgICBcbiAgICAgIC8vIENhY2hlIHJlc3VsdHMgaWYgZW5hYmxlZFxuICAgICAgaWYgKGNhY2hlUmVzdWx0cyAmJiBtYXRjaGVzLmxlbmd0aCA+IDApIHtcbiAgICAgICAgdGhpcy5zZXRDYWNoZWQoY2FjaGVLZXksIG1hdGNoZXMpO1xuICAgICAgfVxuICAgICAgXG4gICAgICAvLyBMb2cgZmlsZSBkaXNjb3ZlcnkgZm9yIG1vbml0b3JpbmdcbiAgICAgIGlmIChtYXRjaGVzLmxlbmd0aCA+IDApIHtcbiAgICAgICAgbG9nZ2VyLmRlYnVnKCdGaWxlcyBkaXNjb3ZlcmVkJywge1xuICAgICAgICAgIGRpcmVjdG9yeSxcbiAgICAgICAgICBzZWFyY2hOYW1lLFxuICAgICAgICAgIGNvdW50OiBtYXRjaGVzLmxlbmd0aFxuICAgICAgICB9KTtcbiAgICAgIH1cbiAgICAgIFxuICAgICAgcmV0dXJuIG1hdGNoZXM7XG4gICAgfSBjYXRjaCAoZXJyb3IpIHtcbiAgICAgIGxvZ2dlci5lcnJvcignRmlsZSBkaXNjb3ZlcnkgZmFpbGVkJywge1xuICAgICAgICBkaXJlY3RvcnksXG4gICAgICAgIHNlYXJjaE5hbWUsXG4gICAgICAgIGVycm9yOiBlcnJvciBpbnN0YW5jZW9mIEVycm9yID8gZXJyb3IubWVzc2FnZSA6IFN0cmluZyhlcnJvcilcbiAgICAgIH0pO1xuICAgICAgcmV0dXJuIFtdO1xuICAgIH1cbiAgfVxuICBcbiAgLyoqXG4gICAqIEJ1aWxkIHNlYXJjaCBwYXR0ZXJucyBmb3IgZGlmZmVyZW50IGZpbGUgZXh0ZW5zaW9uc1xuICAgKi9cbiAgcHJpdmF0ZSBzdGF0aWMgYnVpbGRTZWFyY2hQYXR0ZXJucyhiYXNlTmFtZTogc3RyaW5nLCBleHRlbnNpb25zOiBzdHJpbmdbXSk6IHN0cmluZ1tdIHtcbiAgICBjb25zdCBwYXR0ZXJuczogc3RyaW5nW10gPSBbYmFzZU5hbWVdO1xuICAgIFxuICAgIC8vIEFkZCBleHRlbnNpb24gdmFyaWF0aW9uc1xuICAgIGZvciAoY29uc3QgZXh0IG9mIGV4dGVuc2lvbnMpIHtcbiAgICAgIHBhdHRlcm5zLnB1c2goYCR7YmFzZU5hbWV9JHtleHR9YCk7XG4gICAgfVxuICAgIFxuICAgIC8vIEFkZCBjb21tb24gdmFyaWF0aW9uc1xuICAgIGNvbnN0IG5hbWVXaXRob3V0RXh0ZW5zaW9uID0gYmFzZU5hbWUucmVwbGFjZSgvXFwuW14uXSskLywgJycpO1xuICAgIGlmIChuYW1lV2l0aG91dEV4dGVuc2lvbiAhPT0gYmFzZU5hbWUpIHtcbiAgICAgIHBhdHRlcm5zLnB1c2gobmFtZVdpdGhvdXRFeHRlbnNpb24pO1xuICAgICAgZm9yIChjb25zdCBleHQgb2YgZXh0ZW5zaW9ucykge1xuICAgICAgICBwYXR0ZXJucy5wdXNoKGAke25hbWVXaXRob3V0RXh0ZW5zaW9ufSR7ZXh0fWApO1xuICAgICAgfVxuICAgIH1cbiAgICBcbiAgICByZXR1cm4gcGF0dGVybnM7XG4gIH1cbiAgXG4gIC8qKlxuICAgKiBDaGVjayBpZiBmaWxlbmFtZSBtYXRjaGVzIHBhdHRlcm5cbiAgICovXG4gIHByaXZhdGUgc3RhdGljIG1hdGNoZXNQYXR0ZXJuKGZpbGVuYW1lOiBzdHJpbmcsIHBhdHRlcm46IHN0cmluZywgcGFydGlhbE1hdGNoOiBib29sZWFuKTogYm9vbGVhbiB7XG4gICAgaWYgKHBhcnRpYWxNYXRjaCkge1xuICAgICAgcmV0dXJuIGZpbGVuYW1lLmluY2x1ZGVzKHBhdHRlcm4pO1xuICAgIH1cbiAgICByZXR1cm4gZmlsZW5hbWUgPT09IHBhdHRlcm47XG4gIH1cbiAgXG4gIC8qKlxuICAgKiBHZXQgY2FjaGVkIHJlc3VsdHMgaWYgc3RpbGwgdmFsaWRcbiAgICovXG4gIHByaXZhdGUgc3RhdGljIGdldENhY2hlZChrZXk6IHN0cmluZyk6IHN0cmluZ1tdIHwgbnVsbCB7XG4gICAgY29uc3QgZW50cnkgPSB0aGlzLmNhY2hlLmdldChrZXkpO1xuICAgIGlmICghZW50cnkpIHJldHVybiBudWxsO1xuICAgIFxuICAgIGNvbnN0IGFnZSA9IERhdGUubm93KCkgLSBlbnRyeS50aW1lc3RhbXA7XG4gICAgaWYgKGFnZSA+IHRoaXMuQ0FDSEVfVFRMKSB7XG4gICAgICB0aGlzLmNhY2hlLmRlbGV0ZShrZXkpO1xuICAgICAgcmV0dXJuIG51bGw7XG4gICAgfVxuICAgIFxuICAgIHJldHVybiBlbnRyeS5maWxlcztcbiAgfVxuICBcbiAgLyoqXG4gICAqIENhY2hlIHJlc3VsdHMgd2l0aCB0aW1lc3RhbXBcbiAgICovXG4gIHByaXZhdGUgc3RhdGljIHNldENhY2hlZChrZXk6IHN0cmluZywgZmlsZXM6IHN0cmluZ1tdKTogdm9pZCB7XG4gICAgLy8gTGltaXQgY2FjaGUgc2l6ZSB0byBwcmV2ZW50IG1lbW9yeSBpc3N1ZXNcbiAgICBpZiAodGhpcy5jYWNoZS5zaXplID4gMTAwKSB7XG4gICAgICAvLyBSZW1vdmUgb2xkZXN0IGVudHJpZXNcbiAgICAgIGNvbnN0IGVudHJpZXMgPSBBcnJheS5mcm9tKHRoaXMuY2FjaGUuZW50cmllcygpKTtcbiAgICAgIGVudHJpZXMuc29ydCgoYSwgYikgPT4gYVsxXS50aW1lc3RhbXAgLSBiWzFdLnRpbWVzdGFtcCk7XG4gICAgICBmb3IgKGxldCBpID0gMDsgaSA8IDUwOyBpKyspIHtcbiAgICAgICAgdGhpcy5jYWNoZS5kZWxldGUoZW50cmllc1tpXVswXSk7XG4gICAgICB9XG4gICAgfVxuICAgIFxuICAgIHRoaXMuY2FjaGUuc2V0KGtleSwge1xuICAgICAgZmlsZXMsXG4gICAgICB0aW1lc3RhbXA6IERhdGUubm93KClcbiAgICB9KTtcbiAgfVxuICBcbiAgLyoqXG4gICAqIENsZWFyIHRoZSBjYWNoZVxuICAgKi9cbiAgc3RhdGljIGNsZWFyQ2FjaGUoKTogdm9pZCB7XG4gICAgdGhpcy5jYWNoZS5jbGVhcigpO1xuICAgIGxvZ2dlci5kZWJ1ZygnRmlsZSBkaXNjb3ZlcnkgY2FjaGUgY2xlYXJlZCcpO1xuICB9XG4gIFxuICAvKipcbiAgICogRmluZCBhIHNpbmdsZSBmaWxlIChjb252ZW5pZW5jZSBtZXRob2QpXG4gICAqL1xuICBzdGF0aWMgYXN5bmMgZmluZEZpbGUoXG4gICAgZGlyZWN0b3J5OiBzdHJpbmcsXG4gICAgc2VhcmNoTmFtZTogc3RyaW5nLFxuICAgIG9wdGlvbnM/OiBGaWxlU2VhcmNoT3B0aW9uc1xuICApOiBQcm9taXNlPHN0cmluZyB8IG51bGw+IHtcbiAgICBjb25zdCBmaWxlcyA9IGF3YWl0IHRoaXMuZmluZEZpbGVzKGRpcmVjdG9yeSwgc2VhcmNoTmFtZSwge1xuICAgICAgLi4ub3B0aW9ucyxcbiAgICAgIG1heFJlc3VsdHM6IDFcbiAgICB9KTtcbiAgICByZXR1cm4gZmlsZXMubGVuZ3RoID4gMCA/IGZpbGVzWzBdIDogbnVsbDtcbiAgfVxufSJdfQ==

package/dist/utils/GitHubRateLimiter.d.ts

@@ -0,0 +1,88 @@
+/**
+ * GitHubRateLimiter - Specialized rate limiter for GitHub API calls
+ *
+ * Features:
+ * - Respects GitHub's authenticated (5000/hour) and unauthenticated (60/hour) limits
+ * - Client-side queuing when approaching limits
+ * - Request prioritization for critical operations
+ * - Comprehensive logging for quota management
+ * - Early termination when exact matches are found
+ */
+import { RateLimitStatus } from './RateLimiter.js';
+export interface GitHubRateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: Date;
+    used: number;
+}
+export interface GitHubApiRequest {
+    id: string;
+    operation: string;
+    priority: 'high' | 'normal' | 'low';
+    timestamp: number;
+    resolve: (value: any) => void;
+    reject: (error: any) => void;
+}
+export interface GitHubRateStatus extends RateLimitStatus {
+    queueLength: number;
+    currentLimit: number;
+    rateLimitInfo?: GitHubRateLimitInfo;
+}
+export declare class GitHubRateLimiter {
+    private rateLimiter;
+    private requestQueue;
+    private processing;
+    private lastRateLimitInfo?;
+    private isAuthenticated;
+    constructor();
+    /**
+     * Update rate limits based on current authentication status
+     */
+    private updateLimitsForAuthStatus;
+    /**
+     * Setup periodic check for rate limit status
+     */
+    private setupPeriodicStatusCheck;
+    /**
+     * Queue a GitHub API request with rate limiting
+     * @param operation Description of the operation
+     * @param apiCall Function that makes the actual API call
+     * @param priority Request priority (high, normal, low)
+     * @returns Promise that resolves with the API response
+     */
+    queueRequest<T>(operation: string, apiCall: () => Promise<T>, priority?: 'high' | 'normal' | 'low'): Promise<T>;
+    /**
+     * Add request to queue with priority ordering
+     */
+    private addToQueue;
+    /**
+     * Process the request queue
+     */
+    private processQueue;
+    /**
+     * Get current rate limit status
+     */
+    getStatus(): GitHubRateStatus;
+    /**
+     * Check if an error is a GitHub rate limit error
+     */
+    private isGitHubRateLimitError;
+    /**
+     * Handle GitHub rate limit error response
+     */
+    private handleGitHubRateLimit;
+    /**
+     * Log API usage for monitoring and diagnostics
+     */
+    private logApiUsage;
+    /**
+     * Clear the request queue (for testing or emergency situations)
+     */
+    clearQueue(): void;
+    /**
+     * Reset the rate limiter (for testing)
+     */
+    reset(): void;
+}
+export declare const githubRateLimiter: GitHubRateLimiter;
+//# sourceMappingURL=GitHubRateLimiter.d.ts.map

package/dist/utils/GitHubRateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubRateLimiter.d.ts","sourceRoot":"","sources":["../../src/utils/GitHubRateLimiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAkC,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAOnF,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,IAAI,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAC9B,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,iBAAiB,CAAC,CAAsB;IAChD,OAAO,CAAC,eAAe,CAAS;;IAQhC;;OAEG;YACW,yBAAyB;IA2CvC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAShC;;;;;;OAMG;IACG,YAAY,CAAC,CAAC,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,GAAE,MAAM,GAAG,QAAQ,GAAG,KAAgB,GAC7C,OAAO,CAAC,CAAC,CAAC;IAwDb;;OAEG;IACH,OAAO,CAAC,UAAU;IAuBlB;;OAEG;YACW,YAAY;IA0C1B;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAa7B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAM9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA6C7B;;OAEG;IACH,OAAO,CAAC,WAAW;IA8BnB;;OAEG;IACH,UAAU,IAAI,IAAI;IAalB;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd;AAGD,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}