feat: implement just-based build system with distinct binary names

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>
This commit is contained in:
Ole-Morten Duesund 2025-08-03 19:01:42 +02:00
commit 2cd65fd137
5 changed files with 374 additions and 27 deletions

131
CLAUDE.md
View file

@ -5,44 +5,112 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview
mail2couch is a utility for backing up mail from various sources (primarily IMAP) to CouchDB. The project supports two implementations:
- **Go implementation**: Located in `/go/` directory (currently the active implementation)
- **Rust implementation**: Planned but not yet implemented
- **Go implementation**: Located in `/go/` directory, builds as `mail2couch-go`
- **Rust implementation**: Located in `/rust/` directory, builds as `mail2couch-rs` (fully functional, more advanced)
## Development Commands
### Go Implementation (Primary)
### Universal Build Commands (Recommended)
```bash
# Build both implementations
just build
# Build individual implementations
just build-go # Builds go/mail2couch-go
just build-rust # Builds rust/target/release/mail2couch-rs
# Build optimized release versions
just build-release
# Install both binaries to /usr/local/bin
sudo just install
# Run tests for both implementations
just test
# Clean all build artifacts
just clean
# Format and check code
just fmt
just check
# Show binary sizes
just sizes
# Compare versions
just versions
# List all available recipes
just --list
```
### Go Implementation
```bash
# Build the application
cd go && go build -o mail2couch .
cd go && go build -o mail2couch-go .
# Run the application with automatic config discovery
cd go && ./mail2couch
cd go && ./mail2couch-go
# Run with specific config file
cd go && ./mail2couch --config /path/to/config.json
cd go && ./mail2couch-go --config /path/to/config.json
# Run with message limit (useful for large mailboxes)
cd go && ./mail2couch --max-messages 100
cd go && ./mail2couch-go --max-messages 100
# Run with both config and message limit
cd go && ./mail2couch --config /path/to/config.json --max-messages 50
# Run with dry-run mode
cd go && ./mail2couch-go --dry-run
# Run linting/static analysis
cd go && go vet ./...
# Run unit tests
cd go && go test ./...
# Check dependencies
cd go && go mod tidy
```
### Rust Implementation
```bash
# Build the application (release mode recommended)
cd rust && cargo build --release
# Run the application with automatic config discovery
cd rust && ./target/release/mail2couch-rs
# Run with specific config file
cd rust && ./target/release/mail2couch-rs --config /path/to/config.json
# Run with message limit
cd rust && ./target/release/mail2couch-rs --max-messages 100
# Run with dry-run mode
cd rust && ./target/release/mail2couch-rs --dry-run
# Run linting/static analysis
cd rust && cargo clippy -- -D warnings
# Run unit tests
cd rust && cargo test
# Format code
cd rust && cargo fmt
```
### Integration Testing
```bash
# Run integration tests with Podman containers
cd test && ./run-tests.sh
# Run specialized tests
cd test && ./test-wildcard-patterns.sh
cd test && ./test-incremental-sync.sh
# Run unit tests (none currently implemented)
cd go && go test ./...
# Check dependencies
cd go && go mod tidy
```
## Architecture
@ -90,11 +158,11 @@ This design ensures the same `config.json` format will work for both Go and Rust
### Current Implementation Status
#### Both Implementations
- ✅ Configuration loading with automatic file discovery
- ✅ Command line flag support for config file path
- ✅ Command line flag support (--config/-c, --max-messages/-m, --dry-run/-n)
- ✅ Per-account CouchDB database creation and management
- ✅ IMAP connection and mailbox listing
- ✅ Build error fixes
- ✅ Real IMAP message retrieval and parsing
- ✅ Email storage to CouchDB framework with native attachments
- ✅ Folder filtering logic with wildcard support (`*`, `?`, `[abc]` patterns)
@ -104,15 +172,40 @@ This design ensures the same `config.json` format will work for both Go and Rust
- ✅ Sync vs Archive mode implementation
- ✅ CouchDB attachment storage for email attachments
- ✅ Full message body and attachment handling with MIME multipart support
- ✅ Command line argument support (GNU-style --max-messages/-m and --config/-c flags)
- ✅ Per-account CouchDB databases for better organization
- ✅ Incremental sync functionality with IMAP SEARCH and sync metadata tracking
- ❌ Rust implementation
- ✅ Comprehensive --dry-run mode for safe configuration testing
#### Rust Implementation Additional Features
- ✅ Asynchronous processing with concurrent network operations
- ✅ Server-side IMAP keyword filtering (more efficient)
- ✅ Automatic retry logic with exponential backoff
- ✅ Structured error handling with detailed context
- ✅ Enhanced CLI with rich help system
- ✅ Comprehensive unit test coverage
- ✅ Emoji-enhanced logging for better user experience
#### Go Implementation Characteristics
- ✅ Sequential processing (simple and reliable)
- ✅ Minimal dependencies and fast compilation
- ✅ Client-side keyword filtering
- ✅ Basic error handling with continue-on-error semantics
### Key Dependencies
#### Go Implementation
- `github.com/emersion/go-imap/v2`: IMAP client library
- `github.com/go-kivik/kivik/v4`: CouchDB client library
- `github.com/spf13/pflag`: GNU-style command line flags
- `github.com/emersion/go-message`: Email parsing
#### Rust Implementation
- `async-imap`: Asynchronous IMAP client
- `reqwest`: HTTP client for CouchDB API
- `tokio`: Async runtime and utilities
- `clap`: Command line argument parsing
- `serde`: Serialization framework
- `mail-parser`: Email parsing with MIME support
### Incremental Sync Implementation