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

# 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

4.3 KiB Raw Blame History