indusagi-coding-agent 0.1.59 → 0.1.60

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

@@ -1,541 +0,0 @@
-/**
- * @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/helpers/error-handler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../app/helpers/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"}