feat: implement real IMAP message parsing with native CouchDB attachments

- Replace placeholder message generation with actual IMAP message fetching using go-message library
- Add per-account CouchDB databases for better organization and isolation
- Implement native CouchDB attachment storage with proper revision management
- Add command line argument parsing with --max-messages flag for controlling message processing limits
- Support both sync and archive modes with proper document synchronization
- Add comprehensive test environment with Podman containers (GreenMail IMAP server + CouchDB)
- Implement full MIME multipart parsing for proper body and attachment extraction
- Add TLS and plain IMAP connection support based on port configuration
- Update configuration system to support sync vs archive modes
- Create test scripts and sample data for development and testing

Key technical improvements:
- Real email envelope and header processing with go-imap v2 API
- MIME Content-Type and Content-Disposition parsing for attachment detection
- CouchDB document ID generation using mailbox_uid format for uniqueness
- Duplicate detection and prevention to avoid re-storing existing messages
- Proper error handling and connection management for IMAP operations

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -22,6 +22,12 @@ cd go && ./mail2couch
 # Run with specific config file
 cd go && ./mail2couch -config /path/to/config.json
 
+# Run with message limit (useful for large mailboxes)
+cd go && ./mail2couch -max-messages 100
+
+# Run with both config and message limit
+cd go && ./mail2couch -config /path/to/config.json -max-messages 50
+
 # Run linting/static analysis
 cd go && go vet ./...
 
@@ -54,10 +60,13 @@ cd go && go mod tidy
 ### Configuration Structure
 
 The application uses `config.json` for configuration with the following structure:
-- `couchDb`: Database connection settings (URL, credentials, database name)
+- `couchDb`: Database connection settings (URL, credentials, database name - note: the database field is now ignored as each mail source gets its own database)
 - `mailSources`: Array of mail sources with individual settings:
   - Protocol support (currently only IMAP)
   - Connection details (host, port, credentials)
+  - `mode`: Either "sync" or "archive" (defaults to "archive" if not specified)
+    - **sync**: 1-to-1 relationship - CouchDB documents match exactly what's in the mail account (may remove documents from CouchDB)
+    - **archive**: Archive mode - CouchDB keeps all messages ever seen, even if deleted from mail account (never removes documents)
   - Filtering options for folders and messages
   - Enable/disable per source
 
@@ -76,14 +85,16 @@ This design ensures the same `config.json` format will work for both Go and Rust
 
 - ✅ Configuration loading with automatic file discovery
 - ✅ Command line flag support for config file path
-- ✅ CouchDB client initialization and database creation
+- ✅ Per-account CouchDB database creation and management
 - ✅ IMAP connection and mailbox listing
 - ✅ Build error fixes
 - ✅ Email message retrieval framework (with placeholder data)
-- ✅ Email storage to CouchDB framework
+- ✅ Email storage to CouchDB framework with native attachments
 - ✅ Folder filtering logic
 - ✅ Date filtering support
 - ✅ Duplicate detection and prevention
+- ✅ Sync vs Archive mode implementation
+- ✅ CouchDB attachment storage for email attachments
 - ❌ Real IMAP message parsing (currently uses placeholder data)
 - ❌ Full message body and attachment handling
 - ❌ Incremental sync functionality
@@ -97,10 +108,13 @@ This design ensures the same `config.json` format will work for both Go and Rust
 ### Development Notes
 
 - The main entry point is `main.go` which orchestrates the configuration loading, CouchDB setup, and mail source processing
+- Each mail source gets its own CouchDB database named using `GenerateAccountDBName()` function
 - Each mail source is processed sequentially with proper error handling
 - The application currently uses placeholder message data for testing the storage pipeline
 - Message filtering by folder (include/exclude) and date (since) is implemented
 - Duplicate detection prevents re-storing existing messages
+- Sync vs Archive mode determines whether to remove documents from CouchDB when they're no longer in the mail account
+- Email attachments are stored as native CouchDB attachments linked to the email document
 - No tests are currently implemented
 - The application uses automatic config file discovery as documented above