ai-debug-local-mcp
Version:
🎯 ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh
297 lines • 9.8 kB
JavaScript
/**
* Centralized Error Handling for AI Debug Local MCP
*
* Provides consistent error handling across the entire codebase with:
* - Custom error classes for different error types
* - Error codes for programmatic handling
* - Structured error responses
* - Retry logic determination
* - User-friendly error formatting
*
* This replaces the 563 scattered throw statements with a consistent pattern.
*/
export var ErrorCode;
(function (ErrorCode) {
// General errors
ErrorCode["UNKNOWN"] = "UNKNOWN";
ErrorCode["PROCESSING_ERROR"] = "PROCESSING_ERROR";
ErrorCode["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
ErrorCode["PERMISSION_ERROR"] = "PERMISSION_ERROR";
// Session errors
ErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
ErrorCode["SESSION_EXPIRED"] = "SESSION_EXPIRED";
// Framework errors
ErrorCode["FRAMEWORK_MISMATCH"] = "FRAMEWORK_MISMATCH";
ErrorCode["FRAMEWORK_NOT_DETECTED"] = "FRAMEWORK_NOT_DETECTED";
// Tool errors
ErrorCode["TOOL_NOT_FOUND"] = "TOOL_NOT_FOUND";
ErrorCode["TOOL_EXECUTION_ERROR"] = "TOOL_EXECUTION_ERROR";
// Browser errors
ErrorCode["BROWSER_ERROR"] = "BROWSER_ERROR";
ErrorCode["BROWSER_LAUNCH_FAILED"] = "BROWSER_LAUNCH_FAILED";
ErrorCode["BROWSER_NAVIGATION_FAILED"] = "BROWSER_NAVIGATION_FAILED";
// Network errors
ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
ErrorCode["NETWORK_TIMEOUT"] = "NETWORK_TIMEOUT";
// Validation errors
ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
ErrorCode["INVALID_ARGUMENTS"] = "INVALID_ARGUMENTS";
// Configuration errors
ErrorCode["CONFIGURATION_ERROR"] = "CONFIGURATION_ERROR";
ErrorCode["MISSING_API_KEY"] = "MISSING_API_KEY";
})(ErrorCode || (ErrorCode = {}));
/**
* Base error class for all AI Debug errors
*/
export class AIDebugError extends Error {
code;
timestamp;
context;
constructor(message, code = ErrorCode.UNKNOWN, context) {
super(message);
this.name = 'AIDebugError';
this.code = code;
this.timestamp = new Date();
this.context = context;
// Maintain proper stack trace for where our error was thrown
if (Error.captureStackTrace) {
Error.captureStackTrace(this, this.constructor);
}
}
}
/**
* Session-related errors
*/
export class SessionNotFoundError extends AIDebugError {
sessionId;
constructor(sessionId) {
super(`Debug session ${sessionId} not found`, ErrorCode.SESSION_NOT_FOUND);
this.name = 'SessionNotFoundError';
this.sessionId = sessionId;
}
}
/**
* Framework mismatch errors
*/
export class FrameworkMismatchError extends AIDebugError {
expected;
actual;
constructor(expected, actual) {
super(`Framework mismatch: expected ${expected} but got ${actual}`, ErrorCode.FRAMEWORK_MISMATCH);
this.name = 'FrameworkMismatchError';
this.expected = expected;
this.actual = actual;
}
}
/**
* Tool not found errors
*/
export class ToolNotFoundError extends AIDebugError {
toolName;
constructor(toolName) {
super(`Tool not found: ${toolName}`, ErrorCode.TOOL_NOT_FOUND);
this.name = 'ToolNotFoundError';
this.toolName = toolName;
}
}
/**
* Browser-related errors
*/
export class BrowserError extends AIDebugError {
cause;
constructor(message, cause, context) {
super(message, ErrorCode.BROWSER_ERROR, context || {});
this.name = 'BrowserError';
this.cause = cause;
}
}
/**
* Network-related errors
*/
export class NetworkError extends AIDebugError {
statusCode;
url;
constructor(message, statusCode, url) {
super(message, ErrorCode.NETWORK_ERROR, { statusCode, url });
this.name = 'NetworkError';
this.statusCode = statusCode;
this.url = url;
}
}
/**
* Validation errors
*/
export class ValidationError extends AIDebugError {
field;
expectedType;
constructor(message, field, expectedType) {
super(message, ErrorCode.VALIDATION_ERROR, { field, expectedType });
this.name = 'ValidationError';
this.field = field;
this.expectedType = expectedType;
}
}
/**
* Configuration errors
*/
export class ConfigurationError extends AIDebugError {
configKey;
constructor(message, configKey) {
super(message, ErrorCode.CONFIGURATION_ERROR, { configKey });
this.name = 'ConfigurationError';
this.configKey = configKey;
}
}
/**
* Error handler utility functions
*/
export const errorHandler = {
/**
* Handle an error and return a structured response
*/
handle(error, logger) {
// Log the error if logger is provided
if (logger) {
if (error instanceof AIDebugError) {
logger.error(`${error.name}:`, {
message: error.message,
code: error.code,
context: error.context,
timestamp: error.timestamp
});
}
else if (error instanceof Error) {
logger.error('Error:', {
message: error.message,
stack: error.stack
});
}
else {
logger.error('Unknown error:', error);
}
}
// Handle AIDebugError instances
if (error instanceof AIDebugError) {
const details = {};
// Add specific error properties to details
if (error instanceof SessionNotFoundError) {
details.sessionId = error.sessionId;
}
else if (error instanceof FrameworkMismatchError) {
details.expected = error.expected;
details.actual = error.actual;
}
else if (error instanceof ToolNotFoundError) {
details.toolName = error.toolName;
}
else if (error instanceof NetworkError) {
if (error.statusCode)
details.statusCode = error.statusCode;
if (error.url)
details.url = error.url;
}
else if (error instanceof ValidationError) {
if (error.field)
details.field = error.field;
if (error.expectedType)
details.expectedType = error.expectedType;
}
else if (error instanceof ConfigurationError) {
if (error.configKey)
details.configKey = error.configKey;
}
return {
error: true,
code: error.code,
message: error.message,
details
};
}
// Handle standard Error instances
if (error instanceof Error) {
return {
error: true,
code: ErrorCode.UNKNOWN,
message: error.message,
details: {}
};
}
// Handle string errors
if (typeof error === 'string') {
return {
error: true,
code: ErrorCode.UNKNOWN,
message: error,
details: {}
};
}
// Handle unknown error types
return {
error: true,
code: ErrorCode.UNKNOWN,
message: 'An unknown error occurred',
details: typeof error === 'object' && error !== null ? error : {}
};
},
/**
* Wrap an existing error with additional context
*/
wrap(error, message, code = ErrorCode.PROCESSING_ERROR, context) {
const wrappedError = new AIDebugError(`${message}: ${error.message}`, code, context);
wrappedError.cause = error;
return wrappedError;
},
/**
* Check if an error is retryable
*/
isRetryable(error) {
if (error instanceof NetworkError || error instanceof BrowserError) {
return true;
}
if (error instanceof AIDebugError) {
return [
ErrorCode.NETWORK_ERROR,
ErrorCode.NETWORK_TIMEOUT,
ErrorCode.BROWSER_ERROR,
ErrorCode.TIMEOUT_ERROR
].includes(error.code);
}
return false;
},
/**
* Format error for user display
*/
formatForUser(error) {
if (error instanceof ValidationError) {
let message = `Validation Error: ${error.message}`;
if (error.field) {
message += `\nField: ${error.field}`;
}
if (error.expectedType) {
message += `\nExpected type: ${error.expectedType}`;
}
return message;
}
if (error instanceof SessionNotFoundError) {
return `Session Error: ${error.message}\nPlease ensure the session ID is correct and the session is still active.`;
}
if (error instanceof FrameworkMismatchError) {
return `Framework Error: ${error.message}\nThis tool requires ${error.expected} but detected ${error.actual}.`;
}
if (error instanceof NetworkError) {
let message = `Network Error: ${error.message}`;
if (error.statusCode) {
message += ` (Status: ${error.statusCode})`;
}
return message;
}
if (error instanceof AIDebugError) {
return `${error.name.replace('Error', ' Error')}: ${error.message}`;
}
if (error instanceof Error) {
return `Error: ${error.message}`;
}
return 'An unexpected error occurred';
}
};
//# sourceMappingURL=error-handler.js.map