93 lines
4.1 KiB
Markdown
93 lines
4.1 KiB
Markdown
# WARP.md
|
|
|
|
This file provides guidance to WARP (warp.dev) when working with code in this repository.
|
|
|
|
## Core Development Commands
|
|
|
|
### Build and Test
|
|
- Build: `cargo build`
|
|
- Test: `cargo test`
|
|
- Format: `cargo fmt --all`
|
|
- Lint: `cargo clippy --all-targets --all-features -- -D warnings`
|
|
- CI test runner: `cargo nextest run --profile ci`
|
|
|
|
### CLI Development
|
|
- Install CLI locally: `cargo install --path .`
|
|
- Run CLI without installing: `cargo run --bin cull-gmail -- --help`
|
|
- Test a single test by pattern: `cargo test test_rules_new_creates_default_rules`
|
|
|
|
### Init Command Examples
|
|
- Interactive setup: `cargo run --bin cull-gmail -- init --interactive`
|
|
- Dry-run preview: `cargo run --bin cull-gmail -- init --dry-run`
|
|
- Force overwrite: `cargo run --bin cull-gmail -- init --force`
|
|
- Custom config dir: `cargo run --bin cull-gmail -- init --config-dir /tmp/test-config`
|
|
|
|
### Special Tests
|
|
- Run ignored Gmail API integration test: `cargo test --test gmail_message_list_integration -- --ignored`
|
|
- Requires valid OAuth2 credentials configured
|
|
- Only use with test Gmail account
|
|
- Run ignored init OAuth integration test: `CULL_GMAIL_TEST_CREDENTIAL_FILE=/path/to/creds.json cargo test --test init_integration_tests test_init_oauth_integration -- --ignored`
|
|
- Requires `CULL_GMAIL_TEST_CREDENTIAL_FILE` environment variable with path to valid OAuth2 credential file
|
|
- Tests complete init flow including OAuth2 token generation
|
|
|
|
## High-level Architecture
|
|
|
|
### Crates
|
|
- **Library**: `cull_gmail` - Core Gmail management functionality
|
|
- **Binary**: `cull-gmail` - CLI application
|
|
|
|
### Core Components
|
|
- **GmailClient**: Async Gmail API client with OAuth2 authentication, refresh token persistence, and Gmail API request helpers
|
|
- **Rules/EolRule**: Rule-based message lifecycle engine that loads from TOML configuration and evaluates messages to yield actions (trash/delete)
|
|
- **ClientConfig**: Configuration loader that merges TOML files with environment variables using `APP_` prefix
|
|
- **MessageList**: Abstraction over sets of Gmail message IDs with support for batch list, trash, and delete operations
|
|
- **CLI**: Command-line interface with subcommands for `labels`, `messages`, `rules`, and `token`; implements dry-run-first behavior for safety
|
|
|
|
### CLI Subcommands
|
|
- `init` - Initialize cull-gmail configuration, credentials, and OAuth2 tokens with guided setup
|
|
- `labels` - List and inspect available Gmail labels
|
|
- `messages` - Query, filter, and perform batch operations on Gmail messages
|
|
- `rules` - Configure and execute automated message retention rules
|
|
- `token` - Export/import OAuth2 tokens for ephemeral environments
|
|
|
|
### Runtime
|
|
- **Async/await**: All network operations use Tokio async runtime
|
|
- **OAuth2**: Uses installed application flow with token caching to `~/.cull-gmail/gmail1/`
|
|
- **Safety**: Dry-run mode by default; destructive actions require explicit execution flags
|
|
|
|
## Configuration
|
|
|
|
### Directory Structure
|
|
- **Config directory**: `~/.cull-gmail/`
|
|
- **Main config**: `cull-gmail.toml`
|
|
- **Rules config**: `rules.toml`
|
|
- **OAuth2 tokens**: `gmail1/` subdirectory
|
|
|
|
### Configuration Sources (in precedence order)
|
|
1. Environment variables with `APP_` prefix
|
|
2. TOML configuration files
|
|
3. Built-in defaults
|
|
|
|
### OAuth2 Setup Requirements
|
|
1. Google Cloud Console project with Gmail API enabled
|
|
2. OAuth2 desktop application credentials
|
|
3. Download credential JSON to config directory
|
|
4. First run triggers browser authentication flow
|
|
|
|
## Testing
|
|
|
|
### Test Organization
|
|
- **Unit tests**: Alongside modules in `src/`
|
|
- **Integration tests**: In `tests/` directory
|
|
- **CI runner**: Uses nextest with `ci` profile from `.config/nextest.toml`
|
|
|
|
### Test Categories
|
|
- Standard tests: `cargo test` or `cargo nextest run --profile ci`
|
|
- Gmail API integration test (ignored by default): Requires valid credentials and network access
|
|
|
|
### Important Notes
|
|
- **MSRV**: Rust 1.88+ (edition 2024)
|
|
- **Required runtime**: Tokio for all async operations
|
|
- **Gmail API**: Requires valid OAuth2 credentials for real testing
|
|
- **Logging**: Use `RUST_LOG=cull_gmail=debug` for detailed operation logs
|
|
- **Safety**: All operations default to dry-run mode; use explicit execution flags for actual changes |