error-handling-rules

Error Handling Rules: No Console Pollution, Proper Errors

🚨 CONSOLE POLLUTION - NEVER DO THESE (GEMINI CLI HAS 100+)

Forbidden Console Usage

// ❌ FORBIDDEN - Console pollution like Gemini CLI
console.log('debug info');
console.error('Something went wrong');
console.warn('Warning message');
console.info('Info message');
console.debug('Debug info');

// ✅ REQUIRED - Use proper logging
import { logger } from '../utils/logger.js';
logger.debug('debug info');
logger.error('Something went wrong');
logger.warn('Warning message');
logger.info('Info message');

Exception: CLI Entry Points Only

// ✅ ALLOWED - Only in CLI entry points (cli.ts, main.ts)
if (process.argv.includes('--version')) {
  console.log(version);  // Direct user output
  process.exit(0);
}

// ✅ ALLOWED - Only in test files
describe('test suite', () => {
  console.log('Test output');  // Test debugging
});

🛡️ PROPER ERROR HANDLING PATTERNS

1. Use Our UserError System

// ✅ REQUIRED - Structured error handling
import { createUserError, ErrorCategory } from '../errors/index.js';

throw createUserError('Clear error message', {
  category: ErrorCategory.VALIDATION,
  resolution: 'How to fix this issue',
  details: { additionalContext: 'value' }
});

// ❌ WRONG - Generic errors like Gemini CLI
throw new Error('something went wrong');
throw 'string error';  // Even worse

2. Proper Async Error Handling

// ✅ REQUIRED - Comprehensive async error handling
async function performOperation(): Promise<OperationResult> {
  try {
    const result = await riskyOperation();
    return { success: true, data: result };
  } catch (error) {
    // Handle known error types
    if (error instanceof UserError) {
      throw error;  // Re-throw our errors
    }
    
    if (error instanceof TypeError) {
      throw createUserError('Invalid input provided', {
        category: ErrorCategory.VALIDATION,
        resolution: 'Check input parameters',
        details: { originalError: error.message }
      });
    }
    
    // Handle unknown errors
    throw createUserError('Operation failed', {
      category: ErrorCategory.SYSTEM,
      resolution: 'Try again or contact support',
      details: { error: error instanceof Error ? error.message : 'Unknown error' }
    });
  }
}

// ❌ WRONG - Poor error handling like Gemini CLI
async function performOperation() {
  try {
    return await riskyOperation();
  } catch (error) {
    console.error('Error:', error);  // Console pollution
    throw error;  // No context
  }
}