- Add environment variable overrides for sensitive credentials in both Go and Rust implementations
- Support MAIL2COUCH_COUCHDB_USER and MAIL2COUCH_COUCHDB_PASSWORD for CouchDB credentials
- Support MAIL2COUCH_IMAP_<NAME>_USER and MAIL2COUCH_IMAP_<NAME>_PASSWORD for IMAP credentials
- Implement automatic name normalization for mail source names to environment variable format
- Add runtime display of active environment variable overrides
- Enhance --help output in both implementations with comprehensive environment variable documentation
- Add detailed environment variable section to README with usage examples and security benefits
- Create comprehensive ENVIRONMENT_VARIABLES.md reference guide with SystemD, Docker, and CI/CD examples
- Update all documentation indices and cross-references
- Include security best practices and troubleshooting guidance
- Maintain full backward compatibility with existing configuration files
This enhancement addresses the high-priority security requirement to eliminate plaintext
passwords from configuration files while providing production-ready credential management
for both development and deployment scenarios.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove all documentation files from root directory
- All content has been moved to docs/ directory with updated status
- Clean up project structure for better organization
- Documentation now properly reflects production-ready status
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Move all documentation to docs/ directory for better organization
- Update ANALYSIS.md with current production status and resolved issues
- Completely rewrite IMPLEMENTATION_COMPARISON.md with feature parity matrix
- Update TODO.md to reflect completed milestones and future roadmap
- Create comprehensive docs/README.md as documentation index
- Update main README.md with project status and documentation links
- All documentation now reflects August 2025 production-ready status
- Both implementations verified as feature-complete with identical output
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix all Rust clippy warnings with targeted #[allow] attributes for justified cases
- Implement server-side IMAP SEARCH keyword filtering in Go implementation
- Add graceful fallback from server-side to client-side filtering when IMAP server lacks SEARCH support
- Ensure both implementations use identical filtering logic for consistent results
- Complete comprehensive testing of filtering and attachment handling functionality
- Verify production readiness with proper linting standards for both Go and Rust
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add DocumentSkippedError custom error type to distinguish between skipped and stored documents
- Fix counter bug where skipped messages were incorrectly reported as "stored"
- Enhance status reporting to show "X skipped as duplicates" for better visibility
- Fix Rust implementation binary attachment handling to support all file types (images, PDFs, etc.)
- Update test scripts to use correct binary names (mail2couch-go, mail2couch-rs)
- Add comprehensive test configurations for implementation comparison
Before: "Summary: Processed 30 messages, stored 30 new messages" (misleading when all were duplicates)
After: "Summary: Processed 30 messages, stored 0 new messages" with detailed "Stored 0/30 messages from INBOX (30 skipped as duplicates)"
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Create systemd user service files for both Go and Rust implementations
- Add comprehensive timer configurations: 30-minute, hourly, and daily schedules
- Include security settings, resource limits, and proper service dependencies
- Add justfile recipes for service management (install, enable, disable, status)
- Remove deprecated Makefile in favor of just-based build system
- Fix Rust compilation warnings in imap.rs
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update justfile installation system to provide better user experience:
Installation Improvements:
- `just install` - installs to ~/bin (user-local, no sudo required)
- `just system-install` - installs to /usr/local/bin (system-wide, requires sudo)
- `just uninstall` - removes from ~/bin
- `just system-uninstall` - removes from /usr/local/bin (requires sudo)
Benefits:
- User-local installation by default (follows Unix best practices)
- No sudo required for personal installations
- Clear separation between user and system installs
- Easy uninstallation for both scenarios
- Helpful PATH reminder for ~/bin installation
Documentation Updates:
- Update CLAUDE.md with new installation commands
- Update IMPLEMENTATION_COMPARISON.md deployment examples
- Include uninstall instructions for both methods
This follows modern software distribution practices where user-local
installation is preferred for development tools, with system-wide
installation available when needed for shared environments.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace Makefile with justfile for better build management:
Build System Changes:
- Add comprehensive justfile with recipes for both implementations
- Configure Go to build as `mail2couch-go`
- Configure Rust to build as `mail2couch-rs` via Cargo.toml
- Add universal build, test, clean, and install recipes
- Include development convenience recipes and utility commands
New Justfile Features:
- `just build` - builds both implementations
- `just install` - installs both to /usr/local/bin
- `just test` - runs tests for both implementations
- `just sizes` - shows binary size comparison
- `just versions` - compares version outputs
- `just --list` - shows all available recipes
Documentation Updates:
- Update CLAUDE.md with justfile usage examples
- Replace make commands with just equivalents
- Add new utility commands (sizes, versions)
- Update IMPLEMENTATION_COMPARISON.md deployment sections
Benefits of just over make:
- Better command-line interface with `--list`
- More intuitive recipe syntax
- Better suited for development workflows
- Cross-platform compatibility
- Built-in help and documentation
Binary Naming:
- Go implementation: `mail2couch-go` (11M)
- Rust implementation: `mail2couch-rs` (8.3M)
- Clear distinction prevents conflicts
- Parallel installation support
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add detailed technical comparison document covering:
Architecture & Design:
- Go: Sequential simplicity with minimal abstraction
- Rust: Async orchestration with comprehensive error handling
Performance & Scalability:
- Concurrency models (sequential vs async)
- IMAP filtering efficiency (client-side vs server-side)
- Error recovery and resilience patterns
Developer Experience:
- Code complexity and learning curves
- Dependency management approaches
- Compilation speed vs feature richness
Feature Matrix:
- Complete feature comparison table
- Use case recommendations
- Performance benchmarks and resource usage
Strategic Guidance:
- Migration guide for Go to Rust users
- Deployment considerations for both implementations
- Future development roadmap and focus areas
Provides clear guidance for users to choose the best implementation
for their specific needs, from personal use to production deployments.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix incorrect date reference - dry-run mode was implemented in
August 2025, not December 2024. The project was created recently.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update comprehensive analysis to document the successful implementation
of dry-run mode in both Go and Rust versions:
- Mark dry-run mode as ✅ RESOLVED in original issues tracking
- Update comparative analysis pros to include dry-run capabilities
- Add new "Recent Implementation Updates" section documenting:
- Go implementation features and CLI integration
- Rust implementation features with async-safe operation skipping
- Implementation benefits for risk mitigation and debugging
- Strike through completed dry-run requirement in Tier 1 critical needs
- Renumber sections to accommodate new implementation updates section
This reflects the current state where both implementations now provide
comprehensive dry-run functionality as identified as a critical need
in the original analysis.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive dry-run functionality to the Rust implementation that allows
users to test their configuration without making any changes to CouchDB:
- Added --dry-run/-n command line flag with clap argument parsing
- Extended CommandLineArgs struct with dry_run field
- Updated bash completion script to include new flag
- Comprehensive dry-run logic throughout sync coordinator:
- Skip database creation with informative logging
- Skip sync metadata retrieval and use config fallback
- Skip deleted message handling in sync mode
- Skip message and attachment storage with detailed simulation
- Skip sync metadata updates with summary information
- Enhanced summary output to clearly indicate dry-run vs normal mode
- Updated all tests to include new dry_run field
- Maintains all IMAP operations for realistic mail discovery testing
This brings the Rust implementation to feature parity with the Go version
for safe configuration testing as identified in ANALYSIS.md.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive dry-run functionality that allows users to test their
configuration without making any changes to CouchDB. The feature includes:
- New --dry-run/-n command line flag with help and completion support
- Skips all CouchDB write operations while preserving IMAP operations
- Provides detailed logging of what would be done in normal mode
- Shows sample message data and metadata updates that would occur
- Maintains all existing functionality when dry-run is disabled
This addresses the critical usability need identified in ANALYSIS.md for
safe configuration testing before making database changes.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Combine the previous `ANALYSIS.md` with a new, comprehensive
review of both the Go and Rust implementations.
This new report:
- Acknowledges that the Rust version is now fully functional and
feature-rich, resolving a key point from the old analysis.
- Highlights which original issues have been addressed (e.g., Rust
implementation status, performance, filtering) and which remain
(e.g., security, web interface, dry-run mode).
- Provides a detailed side-by-side comparison of the two versions,
covering architecture, features, and complexity.
- Outlines a tiered roadmap for future improvements, prioritizing
critical needs like security and usability enhancements.
Add server-side folder filtering using IMAP LIST patterns and enhance
message filtering to use IMAP SEARCH with keyword filters when available.
Key improvements:
- Add list_filtered_mailboxes() method using IMAP LIST with patterns
- Use server-side filtering instead of client-side folder filtering
- Enhance message search to use IMAP SEARCH for subject/sender keywords
- Add has_keyword_filters() method to MessageFilter
- Reduce network traffic by leveraging IMAP server capabilities
- Remove dependency on client-side filter_folders function
This achieves full feature parity with the updated Go implementation
and ensures both versions use IMAP standards optimally.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace client-side wildcard filtering with IMAP LIST pattern matching
for improved efficiency and accuracy. This fixes the issue where patterns
like "Work*" were not matching folders like "Work/Projects".
Key improvements:
- Use IMAP LIST with patterns for server-side filtering
- Remove dependency on doublestar library
- Add ListFilteredMailboxes() method with proper IMAP pattern support
- Remove obsolete ShouldProcessMailbox() client-side filtering
- Significantly reduce network traffic by filtering at server
This ensures the Go implementation correctly processes folder patterns
and achieves feature parity with the Rust implementation.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Both implementations create matching document structures and counts
- Attachment storage works identically in both (3 docs with 3 attachments each)
- Document schemas are identical with proper CouchDB native attachment support
- Rust implementation correctly handles folder filtering (includes Work/Projects)
- Both use same document ID format with proper URL encoding
- Database verification confirms feature parity achieved
Added no-filter test configs for fair comparison between implementations.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fixed document ID conflicts caused by unencoded slashes in mailbox names
- Added URL encoding for all document IDs used in CouchDB REST API calls
- Mailbox names with slashes (e.g., 'Work/Projects') now create proper document IDs
- Resolves issue where 'Work/Projects_1' was incorrectly stored as document 'Work' with attachment 'Projects_1'
- Added urlencoding dependency for proper URL-safe document ID handling
All messages now store successfully without conflicts across all mailboxes.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Removed attachment metadata from initial document storage
- Attachments are now stored separately using CouchDB native attachment API
- This matches the Go implementation approach and resolves CouchDB validation errors
- All messages with attachments now store successfully
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit completes the Rust implementation of mail2couch with full feature
parity to the Go version, including:
- Complete IMAP client with TLS support and retry logic
- Advanced email parsing with MIME multipart support using mail-parser
- Email attachment extraction and CouchDB storage
- Sync mode implementation with deleted message handling
- Enhanced error handling and retry mechanisms
- Identical command-line interface with bash completion
- Test configurations for both implementations
The Rust implementation now provides:
- Memory safety and type safety guarantees
- Modern async/await patterns with tokio/async-std
- Comprehensive error handling with anyhow/thiserror
- Structured logging and progress reporting
- Performance optimizations and retry logic
Test configurations created:
- rust/config-test-rust.json - Rust implementation test config
- go/config-test-go.json - Go implementation test config
- test-config-comparison.md - Detailed comparison documentation
- test-both-implementations.sh - Automated testing script
Both implementations can now be tested side-by-side with identical
configurations to validate feature parity and performance.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add async-native-tls dependency for secure IMAP connections
- Implement ImapStream enum supporting both TLS and plain connections
- Add automatic TLS detection based on port (993=TLS, 143=plain, 3143=test)
- Add comprehensive Read/Write trait implementations for stream wrapper
- Add debug logging for connection type verification
- Create example configurations for Gmail, Outlook, and other providers
- Add TLS_SUPPORT.md documentation with security guidelines
- Test with existing test environment and TLS detection logic
- Maintain backward compatibility with plain IMAP for testing
The Rust implementation now supports secure connections to production
email providers while maintaining compatibility with test environments.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add comprehensive Rust implementation matching Go functionality
- Configuration loading with automatic file discovery
- GNU-style command line parsing with clap (--config/-c, --max-messages/-m)
- CouchDB client integration with document storage and sync metadata
- IMAP client functionality with message fetching and parsing
- Folder filtering with wildcard pattern support (*, ?, [abc])
- Message filtering by subject, sender, and recipient keywords
- Incremental sync functionality with metadata tracking
- Bash completion generation matching Go implementation
- Cross-compatible document schemas and database structures
- Successfully tested with existing test environment
Note: TLS support and advanced email parsing features pending
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add --generate-bash-completion flag to output bash completion script
- Provide intelligent completions for config files (*.json) and message counts
- Support tab completion for all available command line options
- Generate professional script with proper comments and error handling
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Adds a detailed analysis of the mail2couch project, covering its
purpose, architecture, and implementation details. The document
provides a summary of the project's functionality based on a review
of the README, schema files, and the Go source code.
The analysis includes:
- A high-level summary of what the project does.
- A detailed explanation of how it works, based on code review.
- Identification of potential problems, such as plaintext password
storage and the incomplete Rust implementation.
- A list of missing features, including the planned webmail UI
and OAuth2 support.
- Concrete suggestions for improvements, such as adding a --dry-run
mode, improving security, and clarifying the status of the Rust code.
- Add pflag dependency for POSIX/GNU-style command line parsing
- Replace Go standard flag package with pflag for better UX
- Implement long options with double dashes (--config, --max-messages, --help)
- Add short option aliases with single dashes (-c, -m, -h)
- Update help message with proper formatting and application description
- Update all documentation to reflect new flag syntax
- Update test scripts to use new command line format
GNU-style options provide better usability:
- Long descriptive options with --flag-name format
- Short single-character aliases for common options
- Standard help flag behavior with --help/-h
- Compatible with shell completion and standard conventions
Command line interface now supports:
- --config/-c FILE: Path to configuration file
- --max-messages/-m N: Message processing limit per mailbox
- --help/-h: Show help message and exit
All existing functionality preserved with improved command line experience.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add complete CouchDB document schema specifications in couchdb-schemas.md
- Create example JSON documents for mail and sync metadata structures
- Implement Rust schema definitions with full serde support and type safety
- Add validation script to ensure schema consistency across implementations
- Document field definitions, data types, and validation rules
- Provide Rust Cargo.toml with appropriate dependencies for future implementation
This establishes a solid foundation for the planned Rust implementation while ensuring
100% compatibility with existing Go implementation databases. Both implementations will
use identical document structures, field names, and database naming conventions.
Schema Features:
- Mail documents with native CouchDB attachment support
- Sync metadata for incremental synchronization
- Predictable document ID patterns for efficient access
- Cross-language type mappings and validation rules
- Example documents for testing and reference
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove obsolete CouchDB design documents (webmail.json, dashboard.json)
- Clean up webmail-related code from couch/couch.go (WebmailViews, CreateWebmailViews, etc.)
- Update documentation to focus on core mail-to-CouchDB storage functionality
- Add Future Plans section describing planned webmail viewer as separate component
- Apply go fmt formatting and ensure code quality standards
- Update test documentation to show raw CouchDB API access patterns
- Remove compiled binary from repository
This refactor simplifies the codebase to focus on its core purpose: efficiently
backing up emails from IMAP to CouchDB. The webmail interface will be developed
as a separate, optional component to maintain clean separation of concerns.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Documentation Enhancements
- Create comprehensive README with installation, configuration, and usage examples
- Add simple, advanced, and provider-specific configuration examples
- Document all features: incremental sync, wildcard patterns, keyword filtering, attachment support
- Include production deployment guidance and troubleshooting section
- Add architecture documentation with database structure and document format examples
## Configuration Cleanup
- Remove unnecessary `database` field from CouchDB configuration
- Add `m2c_` prefix to all CouchDB database names for better namespace isolation
- Update GenerateAccountDBName() to consistently prefix databases with `m2c_`
- Clean up all configuration examples to remove deprecated database field
## Test Environment Simplification
- Simplify test script structure to eliminate confusion and redundancy
- Remove redundant populate-test-messages.sh wrapper script
- Update run-tests.sh to be comprehensive automated test with cleanup
- Maintain clear separation: automated tests vs manual testing environment
- Update all test scripts to expect m2c-prefixed database names
## Configuration Examples Added
- config-simple.json: Basic single Gmail account setup
- config-advanced.json: Multi-account with complex filtering and different providers
- config-providers.json: Real-world configurations for Gmail, Outlook, Yahoo, iCloud
## Benefits
- Clear documentation for users from beginner to advanced
- Namespace isolation prevents database conflicts in shared CouchDB instances
- Simplified test workflow eliminates user confusion about which scripts to use
- Comprehensive examples cover common email provider configurations
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Wildcard Folder Selection
- Add support for wildcard patterns (`*`, `?`, `[abc]`) using filepath.Match
- Implement special case: `"*"` selects ALL available folders
- Support for complex include/exclude pattern combinations
- Maintain backwards compatibility with exact string matching
- Enable subfolder pattern matching (e.g., `Work/*`, `*/Drafts`)
## Keyword Filtering
- Add SubjectKeywords, SenderKeywords, RecipientKeywords to MessageFilter config
- Implement case-insensitive keyword matching across message fields
- Support multiple keywords per filter type with inclusive OR logic
- Add ShouldProcessMessage method for message-level filtering
## Enhanced Test Environment
- Create comprehensive wildcard pattern test scenarios
- Add 12 test folders covering various pattern types: Work/*, Important/*, Archive/*, exact matches
- Implement dedicated wildcard test script (test-wildcard-patterns.sh)
- Update test configurations to demonstrate real-world wildcard usage patterns
- Enhance test data generation with folder-specific messages for validation
## Documentation
- Create FOLDER_PATTERNS.md with comprehensive wildcard examples and use cases
- Update CLAUDE.md to reflect all implemented features and current status
- Enhance test README with detailed wildcard pattern explanations
- Provide configuration examples for common email organization scenarios
## Message Origin Tracking
- Verify all messages in CouchDB properly tagged with origin folder in `mailbox` field
- Maintain per-account database isolation for better organization
- Document ID format: `{folder}_{uid}` ensures uniqueness across folders
Key patterns supported:
- `["*"]` - All folders (with excludes)
- `["Work*", "Important*"]` - Prefix matching
- `["Work/*", "Archive/*"]` - Subfolder patterns
- `["INBOX", "Sent"]` - Exact matches
- Complex include/exclude combinations
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- 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>
- Create separate CouchDB database for each mail source (account)
- Store email attachments as native CouchDB attachments
- Add GenerateAccountDBName() for CouchDB-compatible database naming
- Update MailDocument structure to support _attachments field
- Implement StoreAttachment() for CouchDB attachment API
- Add placeholder attachment testing for every 3rd message
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Update CLAUDE.md with keyword filtering in Next Steps section
- Add detailed TODO.md with feature specification, use cases, and implementation notes
- Document subjectKeywords, senderKeywords, and recipientKeywords functionality
- Include JSON configuration examples and priority assessment
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add TODO comments in config structure for future keyword filtering
- Document planned subjectKeywords, senderKeywords, and recipientKeywords support
- Create TODO.md with detailed feature specification and use cases
- Update CLAUDE.md with keyword filtering in next steps
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add configuration system with automatic file discovery (current dir, config subdir, user home, XDG config)
- Implement IMAP client with TLS connection, authentication, and mailbox listing
- Add CouchDB integration with database creation and document storage
- Support folder filtering (include/exclude) and date filtering (since parameter)
- Include duplicate detection to prevent re-storing existing messages
- Add comprehensive error handling and logging throughout
- Structure code in clean packages: config, mail, couch
- Application currently uses placeholder messages to test the storage pipeline
- Ready for real IMAP message parsing implementation
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
