feat(error-handling): implement user-friendly error handling with debug mode

[finxo]

Summary

Implement a global exception handler to provide user-friendly error messages for end-users while maintaining full debuggability for developers through a --debug flag.

Problem Statement

Currently, when an unexpected error occurs, the application crashes and displays a full Python traceback to the console. This approach has several drawbacks:

• Intimidating for non-technical users - Stack traces are confusing and overwhelming
• Unhelpful - Doesn't provide actionable guidance on next steps
• Unprofessional - Makes the tool appear unpolished and incomplete

Proposed Solution

Introduce a dual-mode error handling system that adapts based on the execution context:

1. Default (User-Facing) Mode

When an uncaught exception occurs in normal operation:

• Display a clean, user-friendly error message:

  💥 An unexpected error occurred. 
  A detailed error report has been saved to: ~/.titan/logs/titan-crash.log
  Please report this issue by creating an issue on our GitHub repository.
  

• Automatically log full exception details and traceback to ~/.titan/logs/titan-crash.log
• Provide clear instructions for reporting issues

2. Debug (Developer) Mode

When the --debug flag is used:

• Bypass the global exception handler
• Display the full, raw Python traceback directly to the console
• Enable immediate debugging without needing to check log files

Implementation Plan

1. Create Global Exception Handler

   • Wrap the main application entry point in titan_cli/__main__.py with a try...except Exception as e: block

2. Implement Logging Utility

   • Create a logging utility to capture exception objects
   • Write formatted tracebacks to ~/.titan/logs/
   • Ensure log directory is created if it doesn't exist

3. Design Friendly Error UI

   • Utilize TextRenderer and PanelRenderer for polished error messages
   • Create a consistent, branded error display format

4. Add --debug Flag

   • Add a debug: bool option to the main typer.callback() in titan_cli/cli.py
   • Make it a global flag accessible throughout the application

5. Implement Conditional Logic

   • Check debug flag state (via context variable or state manager)
   • Route to appropriate error handler based on flag state
   • Re-raise exceptions in debug mode to preserve default traceback behavior

Benefits

• Improved User Experience - Non-technical users receive helpful, actionable messages
• Maintained Developer Experience - Full debugging capabilities preserved with --debug
• Professional Appearance - Polished error handling enhances tool credibility
• Better Issue Reporting - Automatic crash logs facilitate bug reports and troubleshooting

Acceptance Criteria

• Global exception handler implemented in main entry point
• Log directory creation and crash log writing functional
• User-friendly error UI designed and implemented
• --debug flag added and functional
• Conditional error handling logic working correctly
• Documentation updated with error handling behavior
• Tests added for both user-facing and debug modes