# 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