Date: 2025-02-23

Status

Accepted

Context

We have multiple error handling and logging approaches across components:

• setup_tools.rb uses direct puts and abort
• setup_project.rb uses logger and structured error handling
• System::Validator uses abort with formatted messages
• Tests need to capture both stdout and logging output

We need to standardize these approaches for consistency and maintainability.

Decision

We will implement the following error handling and logging strategy:

1. Logger Usage

   • All components should use a configurable logger
   • Debug level for detailed operations
   • Info level for progress updates
   • Error level for failure conditions
   • Support null logger for testing

2. Error Handling Patterns

   • Use abort for unrecoverable system-level errors
   • Raise exceptions for recoverable errors
   • Standardize error message format
   • Include context in error messages
   • Proper error class hierarchy

3. User Feedback

   • Logger for operational details
   • Direct stdout for user-facing messages
   • Clear error formatting
   • Progress indicators for long operations
   • Debug output when requested

4. Testing Support

   • Consistent stdout/stderr capture
   • Logger configuration in tests
   • Error condition simulation
   • Output verification helpers

Consequences

Positive

• Consistent error handling across components
• Clear distinction between user and debug output
• Better error context for debugging
• Testable error conditions
• Flexible logging configuration

Negative

• More complex logging setup required
• Need to maintain logging standards
• Additional error handling code
• Multiple output streams to manage