indusagi-coding-agent 0.1.23 → 0.1.25

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

@@ -0,0 +1,541 @@
+/**
+ * @fileoverview Error Handling and Recovery Utilities
+ *
+ * This module provides robust error handling utilities for transforming technical
+ * errors into user-friendly messages, categorizing errors, and providing recovery
+ * suggestions. Error handling is critical for:
+ *
+ * 1. **User Experience**: Transform cryptic technical errors into actionable messages
+ * 2. **Error Categorization**: Classify errors by type (TypeError, FileNotFound, etc.)
+ * 3. **Recovery Suggestions**: Provide users with steps to resolve issues
+ * 4. **Security**: Avoid leaking sensitive information in error messages
+ * 5. **Logging and Debugging**: Format errors for logs and debugging
+ * 6. **Error Codes**: Standardize error codes for programmatic error handling
+ *
+ * ## Error Code Conventions
+ *
+ * ### System Errors (E-prefix)
+ * - E001: Unknown error
+ * - E002: Validation error
+ * - E003: Configuration error
+ * - E004: Permission denied
+ * - E005: Resource not found
+ * - E006: Timeout error
+ * - E007: Network error
+ * - E008: Parse error
+ *
+ * ### Node.js System Errors (POSIX)
+ * - EACCES: Permission denied
+ * - EEXIST: File already exists
+ * - EISDIR: Is a directory
+ * - ENOENT: No such file or directory
+ * - ENOTDIR: Not a directory
+ * - EPERM: Operation not permitted
+ * - ETIMEDOUT: Connection timed out
+ * - ECONNREFUSED: Connection refused
+ *
+ * ## Error Type Hierarchy
+ *
+ * JavaScript error types provide context about what went wrong:
+ * - **Error**: Generic error, safe fallback
+ * - **TypeError**: Type mismatch or invalid operation
+ * - **ReferenceError**: Undefined variable or property
+ * - **RangeError**: Value out of valid range
+ * - **SyntaxError**: Malformed code or JSON
+ * - **EvalError**: eval() function error (rarely thrown)
+ * - **URIError**: Invalid URI function argument
+ *
+ * ## Security Considerations
+ *
+ * Error messages can leak sensitive information:
+ * - File system paths
+ * - Internal variable names
+ * - API endpoints
+ * - Database structure
+ * - Configuration secrets
+ *
+ * Always sanitize error messages before displaying to users.
+ *
+ * @author Coding Agent
+ * @version 1.0.0
+ */
+/**
+ * Standard error code enum for consistent error identification.
+ *
+ * Error codes allow programmatic error handling and localization.
+ * Each code corresponds to an error category and recovery strategy.
+ *
+ * @example
+ * ```typescript
+ * if (error.code === ErrorCode.EACCES) {
+ *   // Show permission error UI
+ *   showPermissionError();
+ * }
+ * ```
+ */
+export declare enum ErrorCode {
+    UNKNOWN = "E001",
+    VALIDATION = "E002",
+    CONFIG = "E003",
+    PERMISSION = "E004",
+    NOT_FOUND = "E005",
+    TIMEOUT = "E006",
+    NETWORK = "E007",
+    PARSE_ERROR = "E008",
+    EACCES = "EACCES",// Permission denied
+    EEXIST = "EEXIST",// File exists
+    EISDIR = "EISDIR",// Is a directory
+    ENOENT = "ENOENT",// No such file or directory
+    ENOTDIR = "ENOTDIR",// Not a directory
+    EPERM = "EPERM",// Operation not permitted
+    ETIMEDOUT = "ETIMEDOUT",// Connection timed out
+    ECONNREFUSED = "ECONNREFUSED"
+}
+/**
+ * Structured error information for consistent error handling.
+ *
+ * @interface FormattedError
+ * @property code - Machine-readable error code
+ * @property message - User-friendly error message
+ * @property technicalDetails - Detailed technical information (internal use only)
+ * @property stack - Stack trace for debugging
+ * @property suggestions - User-facing recovery suggestions
+ * @property originalError - Original error object reference
+ * @property timestamp - Error occurrence time
+ */
+export interface FormattedError {
+    code: string;
+    message: string;
+    technicalDetails: string;
+    stack?: string;
+    suggestions: string[];
+    originalError: unknown;
+    timestamp: Date;
+}
+/**
+ * Categorizes an error into a standard error type.
+ *
+ * Error type identification enables targeted error handling and appropriate
+ * UI/messaging responses.
+ *
+ * @param error - The error to categorize
+ * @returns Standard error type name
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const value: any = null;
+ *   value.property.nested = 123; // TypeError: Cannot read property 'property'
+ * } catch (error) {
+ *   const type = categorizeError(error);
+ *   // type === 'TypeError'
+ *   if (type === 'TypeError') {
+ *     showTypeErrorRecovery();
+ *   }
+ * }
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // Error type routing
+ * function handleError(error: unknown) {
+ *   const errorType = categorizeError(error);
+ *
+ *   switch (errorType) {
+ *     case 'TypeError':
+ *       logMetric('type_error');
+ *       break;
+ *     case 'ReferenceError':
+ *       logMetric('reference_error');
+ *       break;
+ *     case 'SyntaxError':
+ *       logMetric('syntax_error');
+ *       break;
+ *     default:
+ *       logMetric('unknown_error');
+ *   }
+ * }
+ * ```
+ */
+export declare function categorizeError(error: unknown): string;
+/**
+ * Extracts and formats stack trace from an error.
+ *
+ * Stack traces are essential for debugging but should never be shown to
+ * end users due to security concerns. Use for logging and diagnostics.
+ *
+ * @param error - The error to extract stack from
+ * @returns Formatted stack trace string or empty string
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   riskyOperation();
+ * } catch (error) {
+ *   const stack = extractStackTrace(error);
+ *   // stack:
+ *   // "Error: Something went wrong
+ *   //  at riskyOperation (/path/to/file.ts:42:10)
+ *   //  at main (/path/to/file.ts:1:5)"
+ *   logger.error(stack);
+ * }
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // Log error details without exposing to users
+ * function logErrorForSupport(error: unknown): void {
+ *   const stack = extractStackTrace(error);
+ *   const timestamp = new Date().toISOString();
+ *   const entry = `[${timestamp}] ${String(error)}\n${stack}`;
+ *
+ *   fs.appendFileSync('error.log', entry + '\n');
+ * }
+ *
+ * // Send to error tracking service
+ * function reportToSentry(error: unknown): void {
+ *   const stack = extractStackTrace(error);
+ *   Sentry.captureException(error, {
+ *     extra: { stack }
+ *   });
+ * }
+ * ```
+ */
+export declare function extractStackTrace(error: unknown): string;
+/**
+ * Sanitizes error messages to prevent information leakage.
+ *
+ * Removes sensitive information like:
+ * - File system paths
+ * - Environment variables
+ * - Internal file names
+ * - Memory addresses
+ * - API endpoints
+ *
+ * @param message - Raw error message
+ * @returns Sanitized error message safe for user display
+ *
+ * @example
+ * ```typescript
+ * // Input (dangerous):
+ * const raw = 'Error reading /home/user/secret.key: EACCES';
+ * const safe = sanitizeErrorMessage(raw);
+ * // Output: 'Error reading file: Permission denied'
+ *
+ * // Input (dangerous):
+ * const raw2 = 'Failed to connect to DATABASE_URL=postgres://user:pass@host';
+ * const safe2 = sanitizeErrorMessage(raw2);
+ * // Output: 'Failed to connect to database'
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // Safe error display in UI
+ * function showUserError(error: unknown): void {
+ *   const message = extractErrorMessage(error);
+ *   const safe = sanitizeErrorMessage(message);
+ *
+ *   showNotification({
+ *     type: 'error',
+ *     message: safe,
+ *     duration: 5000
+ *   });
+ * }
+ *
+ * // Log technical details separately
+ * function logErrorSecurely(error: unknown): void {
+ *   const technical = extractErrorMessage(error);
+ *   const safe = sanitizeErrorMessage(technical);
+ *
+ *   // Log full details to secure server log
+ *   internalLogger.error(technical);
+ *
+ *   // Show safe version to user
+ *   userNotification.error(safe);
+ * }
+ * ```
+ */
+export declare function sanitizeErrorMessage(message: string): string;
+/**
+ * Extracts the error message from various error types.
+ *
+ * Handles Error objects, plain objects with message property, and stringified errors.
+ *
+ * @param error - The error to extract message from
+ * @returns Error message string
+ *
+ * @example
+ * ```typescript
+ * extractErrorMessage(new Error('File not found'))
+ * // 'File not found'
+ *
+ * extractErrorMessage({ message: 'Custom error' })
+ * // 'Custom error'
+ *
+ * extractErrorMessage('Simple string error')
+ * // 'Simple string error'
+ *
+ * extractErrorMessage(null)
+ * // 'An unknown error occurred'
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // Unified error message extraction
+ * async function executeWithErrorHandling<T>(
+ *   fn: () => Promise<T>
+ * ): Promise<T> {
+ *   try {
+ *     return await fn();
+ *   } catch (error) {
+ *     const message = extractErrorMessage(error);
+ *     throw new Error(`Operation failed: ${message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function extractErrorMessage(error: unknown): string;
+/**
+ * Gets recovery suggestions based on error type.
+ *
+ * Provides users with actionable steps to resolve common errors.
+ *
+ * @param error - The error to get suggestions for
+ * @param errorCode - Optional error code for more specific suggestions
+ * @returns Array of suggestion strings
+ *
+ * @example
+ * ```typescript
+ * const error = new Error('ENOENT: no such file or directory');
+ * const suggestions = getRecoverySuggestions(error, ErrorCode.ENOENT);
+ * // [
+ * //   'Check that the file path is correct',
+ * //   'Verify the file exists in the specified location',
+ * //   'Try using an absolute file path instead of relative'
+ * // ]
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // Show recovery steps in UI
+ * function showDetailedError(error: unknown) {
+ *   const message = extractErrorMessage(error);
+ *   const suggestions = getRecoverySuggestions(error);
+ *
+ *   showErrorDialog({
+ *     title: 'Operation Failed',
+ *     message: sanitizeErrorMessage(message),
+ *     suggestions: suggestions,
+ *     actions: [
+ *       { label: 'Try Again', handler: retry },
+ *       { label: 'Cancel', handler: cancel }
+ *     ]
+ *   });
+ * }
+ * ```
+ */
+export declare function getRecoverySuggestions(error: unknown, errorCode?: string): string[];
+/**
+ * Main error formatting function for user-friendly error display.
+ *
+ * Transforms a raw error into a structured, sanitized error object suitable
+ * for display to end users while preserving technical details for logging.
+ *
+ * @param error - The error to format
+ * @param options - Optional formatting options
+ * @param options.code - Override error code
+ * @param options.includeStack - Include stack trace in output (default: false for users)
+ * @param options.sanitize - Sanitize message for user display (default: true)
+ * @returns Formatted error object with user-friendly message
+ *
+ * @throws Never throws, always returns a valid FormattedError
+ *
+ * @example
+ * ```typescript
+ * // File system error
+ * try {
+ *   fs.readFileSync('/etc/shadow'); // EACCES
+ * } catch (error) {
+ *   const formatted = formatErrorForUser(error, { code: ErrorCode.EACCES });
+ *   // {
+ *   //   code: 'EACCES',
+ *   //   message: 'Permission denied. Check file permissions.',
+ *   //   technicalDetails: 'Error: EACCES: permission denied, open ...',
+ *   //   suggestions: [
+ *   //     'Check file/directory permissions',
+ *   //     'Try running with elevated privileges if necessary',
+ *   //     'Ensure the file owner allows read/write access'
+ *   //   ],
+ *   //   timestamp: 2024-01-15T10:30:45.123Z
+ *   // }
+ * }
+ * ```
+ *
+ * ```typescript
+ * // API validation error
+ * const error = new TypeError('Cannot read property "name" of undefined');
+ * const formatted = formatErrorForUser(error);
+ * // {
+ * //   code: 'E002',
+ * //   message: 'Invalid input provided',
+ * //   technicalDetails: 'TypeError: Cannot read property "name" of undefined',
+ * //   suggestions: [
+ * //     'Verify that variables are initialized before use',
+ * //     'Check that function arguments are of correct type',
+ * //     'Ensure objects have expected properties'
+ * //   ],
+ * //   timestamp: 2024-01-15T10:30:45.123Z
+ * // }
+ * ```
+ *
+ * ```typescript
+ * // Network timeout
+ * const error = new Error('ETIMEDOUT: connection timed out');
+ * const formatted = formatErrorForUser(error, { code: ErrorCode.ETIMEDOUT });
+ * // {
+ * //   code: 'ETIMEDOUT',
+ * //   message: 'Request timed out. Please try again.',
+ * //   suggestions: [
+ * //     'Check your internet connection',
+ * //     'Try again in a few moments',
+ * //     'Verify the server is online'
+ * //   ],
+ * //   timestamp: 2024-01-15T10:30:45.123Z
+ * // }
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // In Express middleware
+ * app.use((err, req, res, next) => {
+ *   const formatted = formatErrorForUser(err);
+ *
+ *   // Log full technical details
+ *   internalLogger.error(formatted.technicalDetails);
+ *
+ *   // Send user-friendly response
+ *   res.status(500).json({
+ *     error: formatted.message,
+ *     code: formatted.code,
+ *     suggestions: formatted.suggestions
+ *   });
+ * });
+ *
+ * // In CLI applications
+ * async function main() {
+ *   try {
+ *     await performAction();
+ *   } catch (error) {
+ *     const formatted = formatErrorForUser(error);
+ *     console.error(`Error: ${formatted.message}`);
+ *     console.error('Recovery steps:');
+ *     formatted.suggestions.forEach((s, i) => {
+ *       console.error(`  ${i + 1}. ${s}`);
+ *     });
+ *     process.exit(1);
+ *   }
+ * }
+ *
+ * // In React components
+ * function ErrorBoundary(props: any) {
+ *   const [error, setError] = React.useState<FormattedError | null>(null);
+ *
+ *   if (error) {
+ *     const formatted = formatErrorForUser(error.originalError);
+ *     return (
+ *       <ErrorDisplay
+ *         message={formatted.message}
+ *         suggestions={formatted.suggestions}
+ *         onRetry={retry}
+ *       />
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare function formatErrorForUser(error: unknown, options?: {
+    code?: string;
+    includeStack?: boolean;
+    sanitize?: boolean;
+}): FormattedError;
+/**
+ * Wraps a promise to handle errors gracefully.
+ *
+ * Returns [data, error] tuple similar to Go's error handling pattern.
+ * Makes error handling explicit and type-safe.
+ *
+ * @param promise - Promise to wrap
+ * @returns Tuple of [data, error]
+ *
+ * @example
+ * ```typescript
+ * const [data, error] = await handlePromise(fetch('/api/users'));
+ *
+ * if (error) {
+ *   const formatted = formatErrorForUser(error);
+ *   showErrorNotification(formatted.message);
+ *   return;
+ * }
+ *
+ *   // data is guaranteed to exist here
+ * processUsers(data);
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // Cleaner async/await error handling
+ * async function loadUserData(userId: string) {
+ *   const [user, error] = await handlePromise(
+ *     fetch(`/api/users/${userId}`).then(r => r.json())
+ *   );
+ *
+ *   if (error) {
+ *     return { success: false, error: formatErrorForUser(error) };
+ *   }
+ *
+ *   return { success: true, data: user };
+ * }
+ * ```
+ */
+export declare function handlePromise<T>(promise: Promise<T>): Promise<[T | null, Error | null]>;
+/**
+ * Retries an operation with exponential backoff.
+ *
+ * Useful for transient failures (network issues, temporary unavailability).
+ *
+ * @param fn - Async function to retry
+ * @param maxAttempts - Maximum number of attempts (default: 3)
+ * @param baseDelay - Base delay in milliseconds (default: 1000)
+ * @returns Promise that resolves with function result or rejects with last error
+ *
+ * @example
+ * ```typescript
+ * const data = await retryWithBackoff(
+ *   () => fetch('/api/data').then(r => r.json()),
+ *   3,
+ *   1000
+ * );
+ * // Attempts:
+ * // 1. Immediately
+ * // 2. After ~1000ms
+ * // 3. After ~2000ms
+ * ```
+ *
+ * @usage
+ * ```typescript
+ * // Resilient API calls
+ * async function fetchUserWithRetry(userId: string) {
+ *   return retryWithBackoff(
+ *     async () => {
+ *       const response = await fetch(`/api/users/${userId}`);
+ *       if (!response.ok) throw new Error('API error');
+ *       return response.json();
+ *     },
+ *     3,
+ *     1000
+ *   );
+ * }
+ * ```
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelay?: number): Promise<T>;
+//# sourceMappingURL=error-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH;;;;;;;;;;;;;GAaG;AACH,oBAAY,SAAS;IAEnB,OAAO,SAAS;IAChB,UAAU,SAAS;IACnB,MAAM,SAAS;IACf,UAAU,SAAS;IACnB,SAAS,SAAS;IAClB,OAAO,SAAS;IAChB,OAAO,SAAS;IAChB,WAAW,SAAS;IAGpB,MAAM,WAAW,CAAU,oBAAoB;IAC/C,MAAM,WAAW,CAAU,cAAc;IACzC,MAAM,WAAW,CAAU,iBAAiB;IAC5C,MAAM,WAAW,CAAU,4BAA4B;IACvD,OAAO,YAAY,CAAQ,kBAAkB;IAC7C,KAAK,UAAU,CAAY,0BAA0B;IACrD,SAAS,cAAc,CAAI,uBAAuB;IAClD,YAAY,iBAAiB;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAStD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CASxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAwB5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAY1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,EAAE,CAiEV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqHG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GACA,cAAc,CAgDhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC,CAQnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,GAAE,MAAU,EACvB,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,CAAC,CAAC,CAiBZ"}