Add structured query filters to search command

[patrick91]

Summary

Implements structured query filters for the search command, enabling precise searches beyond FTS5 full-text queries. This feature is essential for agent-friendly usage and programmatic querying of the Gmail database.

Features

New Filter Options

All filters are optional and combine with AND logic:

• --from <email> - Filter by sender (partial match)
• --to <email> - Filter by recipient (partial match)
• --after <date> - Messages after date (supports "today", "yesterday", ISO dates)
• --before <date> - Messages before date
• --has - Messages with attachments
• --label <label> - Filter by Gmail label
• --subject <text> - Filter by subject (partial match)

Usage Examples

# Filter by sender
gmail search --from alice@example.com

# Filter by date range
gmail search --after 2024-01-01 --before 2024-12-31

# Messages with attachments from specific sender
gmail search --from finance@ --has

# Combine FTS5 query with filters
gmail search "invoice" --from finance@ --after today

# Filter by label and date
gmail search --label INBOX --after yesterday

Implementation Details

• New module: src/gmail_cli/db/filters.py - Contains SearchFilters dataclass, date parsing, and SQL building
• Enhanced queries: Updated search_messages() to handle three scenarios:
  1. FTS5 query only (original behavior)
  2. Filters only (new)
  3. FTS5 + filters combined (new)
• Security: Uses parameterized queries to prevent SQL injection
• JSON support: Handles JSON fields (labels) with SQLite's json_each() function
• Performance: Applies indexed filters first (from_addr, date_utc) for efficiency
• Backward compatible: Existing search commands work unchanged

Test Coverage

Added comprehensive test suite with 30 tests:

• ✅ Date parsing (today, yesterday, ISO formats, invalid input)
• ✅ SQL filter building (individual and combined filters)
• ✅ End-to-end search functionality (all filter combinations)
• ✅ Edge cases (no results, partial matches, date ranges)

All tests passing with 100% coverage of filter functionality.

Dependencies

• Added python-dateutil>=2.8.0 for flexible date parsing
• Added pytest>=7.0.0 as dev dependency for testing

Why This Matters

This feature enables:

• Agent integration: LLMs can now perform precise queries programmatically
• Advanced filtering: Users can narrow down results beyond text matching
• Date-based searches: Essential for finding recent or historical messages
• Attachment filtering: Quickly find messages with files
• Label-based queries: Leverage Gmail's organizational structure

Closes part of the roadmap for making gmail-cli agent-friendly.