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:
parent
4829c3bbb9
commit
2cd65fd137
5 changed files with 374 additions and 27 deletions
131
CLAUDE.md
131
CLAUDE.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue