Watchtower DAP Windows Debugging

/** * Extended Error interface for Watchtower errors */ interface WatchtowerError extends Error { code?: string; category?: string; severity?: string; details?: any; } /** * Comprehensive Error Taxonomy * * Defines error categories, codes, and user-friendly messages * for the Watchtower debugging system with Windows-specific diagnostics. */ /** * Error Category Enum */ export enum ErrorCategory { // Transport and connection errors TRANSPORT_CONNECTION = 'transport_connection', TRANSPORT_TIMEOUT = 'transport_timeout', TRANSPORT_PROTOCOL = 'transport_protocol', // Session management errors SESSION_INVALID = 'session_invalid', SESSION_TIMEOUT = 'session_timeout', SESSION_CONFLICT = 'session_conflict', SESSION_CAPABILITY = 'session_capability', // Adapter errors ADAPTER_NOT_FOUND = 'adapter_not_found', ADAPTER_VERSION_MISMATCH = 'adapter_version_mismatch', ADAPTER_LAUNCH_FAILED = 'adapter_launch_failed', ADAPTER_COMMUNICATION = 'adapter_communication', ADAPTER_PLATFORM = 'adapter_platform', // Debug protocol errors DAP_REQUEST_FAILED = 'dap_request_failed', DAP_VALIDATION_FAILED = 'dap_validation_failed', DAP_PARSE_ERROR = 'dap_parse_error', DAP_TIMEOUT = 'dap_timeout', // Configuration errors CONFIG_INVALID = 'config_invalid', CONFIG_MISSING = 'config_missing', CONFIG_PERMISSION = 'config_permission', // Security errors SECURITY_PERMISSION_DENIED = 'security_permission_denied', SECURITY_PATH_TRAVERSAL = 'security_path_traversal', SECURITY_INJECTION = 'security_injection', // System errors SYSTEM_RESOURCE = 'system_resource', SYSTEM_FILE_NOT_FOUND = 'system_file_not_found', SYSTEM_PERMISSION = 'system_permission', SYSTEM_NETWORK = 'system_network', // Performance errors PERFORMANCE_THRESHOLD = 'performance_threshold', MEMORY_EXCEEDED = 'memory_exceeded', TIMEOUT_EXCEEDED = 'timeout_exceeded', } /** * Severity Level Enum */ export enum Severity { LOW = 'low', MEDIUM = 'medium', HIGH = 'high', CRITICAL = 'critical', } /** * Error Code Interface */ export interface ErrorCode { code: string; category: ErrorCategory; severity: Severity; message: string; userMessage: string; suggestions: string[]; recoverySteps?: string[]; mitigation?: string; windowsSpecific?: boolean; } /** * Error Registry */ export const ErrorCodes: Record<string, ErrorCode> = { // Transport Errors TRANSPORT_001: { code: 'TRANSPORT_001', category: ErrorCategory.TRANSPORT_CONNECTION, severity: Severity.HIGH, message: 'Failed to establish connection to debug adapter', userMessage: 'Unable to connect to the debug adapter', suggestions: [ 'Check if the debug adapter is installed', 'Verify the adapter executable path', 'Ensure adapter is in PATH or provide full path', 'Check network connectivity for remote adapters', ], recoverySteps: [ 'Restart the debug session', 'Reinstall the debug adapter', 'Check system logs for detailed error information', ], windowsSpecific: true, }, TRANSPORT_002: { code: 'TRANSPORT_002', category: ErrorCategory.TRANSPORT_TIMEOUT, severity: Severity.MEDIUM, message: 'Connection to debug adapter timed out', userMessage: 'Connection to debug adapter timed out', suggestions: [ 'Increase timeout in configuration', 'Check if adapter is responding', 'Verify system resources are available', ], recoverySteps: [ 'Restart the adapter service', 'Check system performance', 'Increase timeout values in settings', ], }, TRANSPORT_003: { code: 'TRANSPORT_003', category: ErrorCategory.TRANSPORT_PROTOCOL, severity: Severity.HIGH, message: 'Invalid DAP protocol message received', userMessage: 'Communication error with debug adapter', suggestions: [ 'Check adapter compatibility with DAP version', 'Update debug adapter to latest version', 'Verify protocol implementation', ], recoverySteps: [ 'Restart the debugging session', 'Update debug adapter', 'Check for protocol updates', ], }, // Session Errors SESSION_001: { code: 'SESSION_001', category: ErrorCategory.SESSION_INVALID, severity: Severity.HIGH, message: 'Invalid session ID provided', userMessage: 'Invalid debugging session', suggestions: [ 'Check if session is still active', 'Verify session ID is correct', 'Start a new debugging session', ], recoverySteps: [ 'Restart the debug session', 'Clear session cache', 'Check system logs for session details', ], }, SESSION_002: { code: 'SESSION_002', category: ErrorCategory.SESSION_TIMEOUT, severity: Severity.MEDIUM, message: 'Session timeout occurred', userMessage: 'Debugging session timed out', suggestions: [ 'Increase session timeout settings', 'Keep debugging session active', 'Check for idle timeouts', ], recoverySteps: [ 'Restart the debugging session', 'Adjust timeout configuration', 'Monitor session activity', ], }, SESSION_003: { code: 'SESSION_003', category: ErrorCategory.SESSION_CONFLICT, severity: Severity.HIGH, message: 'Session conflict detected', userMessage: 'Conflicting debugging session detected', suggestions: [ 'Close conflicting debugging sessions', 'Use different session identifiers', 'Check for multiple instances', ], recoverySteps: [ 'Terminate conflicting sessions', 'Restart Watchtower server', 'Check for zombie processes', ], }, // Adapter Errors ADAPTER_001: { code: 'ADAPTER_001', category: ErrorCategory.ADAPTER_NOT_FOUND, severity: Severity.HIGH, message: 'Debug adapter not found in system', userMessage: 'Debug adapter not found', suggestions: [ 'Install the required debug adapter', 'Add adapter to PATH environment variable', 'Specify full adapter path in configuration', ], windowsSpecific: true, recoverySteps: [ 'Install Visual Studio for vsdbg', 'Install .NET SDK for netcoredbg', 'Install Python with debugpy', 'Install VS Code with JavaScript extension', ], }, ADAPTER_002: { code: 'ADAPTER_002', category: ErrorCategory.ADAPTER_VERSION_MISMATCH, severity: Severity.MEDIUM, message: 'Debug adapter version mismatch', userMessage: 'Debug adapter version not supported', suggestions: [ 'Update debug adapter to compatible version', 'Downgrade adapter to supported version', 'Check adapter compatibility requirements', ], recoverySteps: [ 'Update adapter to latest compatible version', 'Check version requirements in documentation', 'Clear adapter cache', ], }, ADAPTER_003: { code: 'ADAPTER_003', category: ErrorCategory.ADAPTER_LAUNCH_FAILED, severity: Severity.HIGH, message: 'Failed to launch debug adapter process', userMessage: 'Unable to start debug adapter', suggestions: [ 'Check adapter executable permissions', 'Verify system resources are available', 'Check for conflicting processes', ], windowsSpecific: true, recoverySteps: [ 'Run as administrator', 'Check system resources', 'Restart adapter service', 'Check Windows Event Viewer for details', ], }, ADAPTER_004: { code: 'ADAPTER_004', category: ErrorCategory.ADAPTER_PLATFORM, severity: Severity.CRITICAL, message: 'Debug adapter not compatible with current platform', userMessage: 'Debug adapter not supported on this system', suggestions: [ 'Use Windows-compatible debug adapters', 'Install platform-specific adapters', 'Check system requirements', ], windowsSpecific: true, recoverySteps: [ 'Install Windows-compatible adapters', 'Check system architecture', 'Use Windows-native adapters only', ], }, // Debug Protocol Errors DAP_001: { code: 'DAP_001', category: ErrorCategory.DAP_REQUEST_FAILED, severity: Severity.HIGH, message: 'DAP request failed', userMessage: 'Debug operation failed', suggestions: [ 'Check debug adapter state', 'Verify request parameters', 'Check for session timeouts', ], recoverySteps: [ 'Restart debugging session', 'Check debug logs for details', 'Verify request syntax', ], }, DAP_002: { code: 'DAP_002', category: ErrorCategory.DAP_VALIDATION_FAILED, severity: Severity.MEDIUM, message: 'DAP request validation failed', userMessage: 'Invalid debugging request', suggestions: [ 'Check request parameter types', 'Verify required fields are present', 'Check parameter value ranges', ], recoverySteps: [ 'Validate request parameters', 'Check schema documentation', 'Test with minimal parameters', ], }, // Configuration Errors CONFIG_001: { code: 'CONFIG_001', category: ErrorCategory.CONFIG_INVALID, severity: Severity.MEDIUM, message: 'Invalid configuration detected', userMessage: 'Configuration error', suggestions: [ 'Check configuration file syntax', 'Validate configuration values', 'Use default configuration as reference', ], recoverySteps: [ 'Validate configuration with --validate', 'Check configuration file format', 'Reset to default configuration', ], }, // Security Errors SECURITY_001: { code: 'SECURITY_001', category: ErrorCategory.SECURITY_PERMISSION_DENIED, severity: Severity.HIGH, message: 'Permission denied for requested operation', userMessage: 'Access denied', suggestions: [ 'Check file permissions', 'Run as administrator', 'Verify user account privileges', ], windowsSpecific: true, recoverySteps: [ 'Run Watchtower as administrator', 'Check file and directory permissions', 'Verify user account in appropriate groups', ], }, // System Errors SYSTEM_001: { code: 'SYSTEM_001', category: ErrorCategory.SYSTEM_RESOURCE, severity: Severity.HIGH, message: 'System resource limit exceeded', userMessage: 'System resources exhausted', suggestions: ['Check available memory', 'Monitor CPU usage', 'Close unnecessary applications'], recoverySteps: [ 'Increase system memory', 'Close resource-intensive applications', 'Check system health', ], }, // Performance Errors PERFORMANCE_001: { code: 'PERFORMANCE_001', category: ErrorCategory.PERFORMANCE_THRESHOLD, severity: Severity.MEDIUM, message: 'Performance threshold exceeded', userMessage: 'Debugging performance degraded', suggestions: ['Check system performance', 'Reduce debug complexity', 'Optimize debug settings'], recoverySteps: [ 'Adjust performance thresholds', 'Monitor system metrics', 'Optimize debugging configuration', ], }, }; /** * Get error code details */ export function getErrorCode(code: string): ErrorCode | null { return ErrorCodes[code] || null; } /** * Create error with code */ export function createError(code: string, details?: any): Error { const errorCode = getErrorCode(code); if (!errorCode) { return new Error(`Unknown error code: ${code}`); } const error = new Error(errorCode.userMessage) as WatchtowerError; error.name = 'WatchtowerError'; error.code = code; error.category = errorCode.category; error.severity = errorCode.severity; error.details = details; return error; } /** * Format error for user display */ export function formatError(error: WatchtowerError): string { if (error.code && ErrorCodes[error.code]) { const errorCode = ErrorCodes[error.code]; let message = `${errorCode?.userMessage || 'Unknown error'}\n\n`; if (errorCode && errorCode.suggestions.length > 0) { message += 'Suggestions:\n'; errorCode.suggestions.forEach(suggestion => { message += ` • ${suggestion}\n`; }); } if (errorCode && errorCode.windowsSpecific) { message += '\n⚠️ This error is Windows-specific and may require Windows-specific solutions.\n'; } return message; } return error.message || 'Unknown error occurred'; } /** * Get error recovery recommendations */ export function getRecoverySteps(errorCode: string): string[] { const code = getErrorCode(errorCode); return code?.recoverySteps || []; } /** * Check if error requires immediate attention */ export function isCriticalError(errorCode: string): boolean { const code = getErrorCode(errorCode); return code?.severity === Severity.CRITICAL; } /** * Get error suggestions */ export function getErrorSuggestions(errorCode: string): string[] { const code = getErrorCode(errorCode); return code?.suggestions || []; } /** * Error category mapping for logging */ export const ErrorCategories = { TRANSPORT_CONNECTION: 'Connection Issues', TRANSPORT_TIMEOUT: 'Timeout Issues', TRANSPORT_PROTOCOL: 'Protocol Issues', SESSION_INVALID: 'Session Issues', SESSION_TIMEOUT: 'Session Timeouts', SESSION_CONFLICT: 'Session Conflicts', SESSION_CAPABILITY: 'Capability Issues', ADAPTER_NOT_FOUND: 'Adapter Not Found', ADAPTER_VERSION_MISMATCH: 'Version Mismatch', ADAPTER_LAUNCH_FAILED: 'Launch Failure', ADAPTER_COMMUNICATION: 'Communication Issues', ADAPTER_PLATFORM: 'Platform Issues', DAP_REQUEST_FAILED: 'Request Failed', DAP_VALIDATION_FAILED: 'Validation Failed', DAP_PARSE_ERROR: 'Parse Error', DAP_TIMEOUT: 'Timeout', CONFIG_INVALID: 'Configuration', CONFIG_MISSING: 'Missing Configuration', CONFIG_PERMISSION: 'Permission Issues', SECURITY_PERMISSION_DENIED: 'Security', SECURITY_PATH_TRAVERSAL: 'Security', SECURITY_INJECTION: 'Security', SYSTEM_RESOURCE: 'System', SYSTEM_FILE_NOT_FOUND: 'File System', SYSTEM_PERMISSION: 'System', SYSTEM_NETWORK: 'Network', PERFORMANCE_THRESHOLD: 'Performance', MEMORY_EXCEEDED: 'Memory', TIMEOUT_EXCEEDED: 'Timeout', }; /** * Error severity colors for console output */ export const SeverityColors = { [Severity.LOW]: '\x1b[36m', // Cyan [Severity.MEDIUM]: '\x1b[33m', // Yellow [Severity.HIGH]: '\x1b[31m', // Red [Severity.CRITICAL]: '\x1b[35m', // Magenta reset: '\x1b[0m', // Reset };