121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
`cull-gmail` is a Rust-based Gmail management library and CLI tool that enables automated email culling operations through the Gmail API. It supports message querying, filtering, batch operations (trash/delete), and rule-based retention policies.
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Build the project
|
|
cargo build
|
|
|
|
# Run all tests
|
|
cargo test
|
|
|
|
# Run specific test file
|
|
cargo test --test gmail_client_unit_tests
|
|
|
|
# Run ignored integration tests (Gmail API integration)
|
|
cargo test --test gmail_message_list_integration -- --ignored
|
|
|
|
# Format code
|
|
cargo fmt
|
|
|
|
# Run linter
|
|
cargo clippy
|
|
|
|
# Check for security vulnerabilities
|
|
cargo audit
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Workspace Structure
|
|
|
|
```
|
|
cull-gmail/
|
|
├── crates/cull-gmail/ # Library crate (public API)
|
|
│ ├── src/
|
|
│ │ ├── cli/ # CLI command implementations
|
|
│ │ │ ├── main.rs # CLI entry point
|
|
│ │ │ ├── labels_cli.rs # labels subcommand
|
|
│ │ │ ├── messages_cli.rs # messages subcommand
|
|
│ │ │ ├── rules_cli.rs # rules subcommand
|
|
│ │ │ ├── init_cli.rs # init subcommand
|
|
│ │ │ └── token_cli.rs # token subcommand
|
|
│ │ ├── client_config.rs # OAuth2 configuration
|
|
│ │ ├── gmail_client.rs # Gmail API client
|
|
│ │ ├── message_list.rs # Message list management
|
|
│ │ ├── rules.rs # Rules configuration
|
|
│ │ ├── retention.rs # Retention policy definitions
|
|
│ │ ├── rule_processor.rs # Rule execution logic
|
|
│ │ ├── eol_action.rs # End-of-life actions (trash/delete)
|
|
│ │ ├── error.rs # Error types
|
|
│ │ └── utils.rs # Utility functions
|
|
│ └── tests/ # Test files
|
|
├── docs/ # Documentation
|
|
└── .circleci/ # CI configuration
|
|
```
|
|
|
|
### Key Components
|
|
|
|
**GmailClient** (`gmail_client.rs`): Main client for Gmail API interactions. Handles authentication, message querying, and batch operations.
|
|
|
|
**Rules** (`rules.rs`): Configuration for automated retention policies with validation and execution.
|
|
|
|
**Retention** (`retention.rs`): Defines message age-based retention policies (e.g., "older_than:1y").
|
|
|
|
**RuleProcessor** (`rule_processor.rs`): Executes rules against message lists, applying appropriate actions.
|
|
|
|
**ClientConfig** (`client_config.rs`): Manages OAuth2 credentials and configuration file parsing.
|
|
|
|
**CLI** (`cli/`): Command-line interface with clap-based argument parsing.
|
|
|
|
## Gmail API Integration
|
|
|
|
- Uses `google-gmail1` crate (version 7.0.0) with `yup-oauth2` and `aws-lc-rs` features
|
|
- OAuth2 authentication with token caching in `~/.cull-gmail/gmail1/`
|
|
- Default page size: 200 messages (configurable via `DEFAULT_MAX_RESULTS`)
|
|
- Supports Gmail search syntax for queries
|
|
|
|
## Testing
|
|
|
|
- Unit tests: `cargo test`
|
|
- Integration tests: Located in `crates/cull-gmail/tests/`
|
|
- Gmail API integration tests are ignored by default (`#[ignore]`) and require `--ignored` flag
|
|
- Mock tests available in test suite for unit testing
|
|
|
|
## Configuration
|
|
|
|
- Default config path: `~/.cull-gmail/cull-gmail.toml`
|
|
- OAuth2 credential file path: `~/.cull-gmail/client_secret.json`
|
|
- Rules file: `~/.cull-gmail/rules.toml`
|
|
- Environment variables override config settings (e.g., `APP_CREDENTIAL_FILE`)
|
|
|
|
## Error Handling
|
|
|
|
The library uses a custom `Error` type with variants for:
|
|
- `NoLabelsFound`: Mailbox has no labels
|
|
- `LabelNotFoundInMailbox(String)`: Specific label not found
|
|
- `RuleNotFound(usize)`: Rule ID doesn't exist
|
|
- `GoogleGmail1(Box<google_gmail1::Error>)`: Gmail API errors
|
|
- `StdIO(std::io::Error)`: File I/O errors
|
|
- `Config(config::ConfigError)`: Configuration errors
|
|
|
|
## Logging
|
|
|
|
- Uses `log` crate with `env_logger`
|
|
- Verbosity controlled via CLI flags (`-v`, `-vv`, `-vvv`) and `RUST_LOG` environment variable
|
|
- Log levels: error, warn, info, debug, trace
|
|
|
|
## Code Style
|
|
|
|
- Rust edition 2024
|
|
- Minimum Rust version: 1.88
|
|
- Clippy lints configured in workspace
|
|
- Follows official Rust style guide
|
|
- Use `cargo fmt` for formatting
|
|
- Use `cargo clippy` for linting |