Add rich metadata access and better error handling

[patrick91]

Summary

Implements two agent-friendly features for gmail-cli from Issue #6:

• Rich Metadata Access (Issue Add rich metadata access and better error handling #8) - Full headers, RFC822 format, thread trees
• Better Error Handling (Issue #10) - Structured errors, validation, dry-run mode

Note: Data extraction (Issue #9) is intentionally skipped - LLMs can extract structured data from the raw text we provide via JSON output.

Feature 1: Rich Metadata Access

Exposes full headers, RFC822 format, and thread tree structure.

New CLI Options

# Show all headers in readable format
gmail read <id> --headers

# Get raw RFC822 message (fetch from API)
gmail read <id> --format raw

# Show thread as tree structure
gmail thread <id> --tree

Implementation Details

• read command: Added --headers and --format raw options
• thread command: Added --tree flag for hierarchical view
• New module: db/thread_tree.py - Builds thread trees using In-Reply-To headers
• Client enhancement: GmailClient.get_message_raw() fetches RFC822 format from Gmail API

Feature 2: Better Error Handling

Structured error codes, query validation, dry-run mode, clear error messages.

New CLI Options

# Dry run to see what would be synced
gmail sync full --dry-run

# Validation errors shown in structured format
gmail read invalid_id --json

Implementation Details

• New exception classes with error codes:

  • GmailCliException (base class)
  • InvalidQueryError, RateLimitError, MessageNotFoundError
  • SyncError, AuthenticationError, ValidationError

• Centralized error handler (error_handler.py):

  • Supports both JSON and pretty output
  • Consistent error formatting across commands

• Input validators (validators.py):

  • Message ID validation
  • Date range validation
  • FTS5 query syntax validation

• Dry-run support in sync command:

  • Shows current count, total messages, estimated size/time
  • No actual syncing performed

Files Changed

New Files (5)

• src/gmail_cli/error_handler.py - Centralized error handling
• src/gmail_cli/validators.py - Input validation functions
• src/gmail_cli/db/thread_tree.py - Thread tree builder
• tests/test_error_handling.py - 11 passing tests
• tests/test_metadata.py - 6 passing tests

Modified Files (4)

• src/gmail_cli/exceptions.py - Added 6 exception classes
• src/gmail_cli/sync/engine.py - Dry-run support
• src/gmail_cli/sync/client.py - RFC822 format fetch
• src/gmail_cli/cli.py - Enhanced read/thread commands, error handling

Testing

All tests passing ✓ (47/47)

• 11 new error handling tests
• 6 new metadata tests
• 30 existing tests (still passing)

pytest tests/ -v
# ============================== 47 passed in 0.21s ==============================

Related Issues

Closes #8
Closes #10
Part of #6