Improve AGENTS.md with detailed code style guidelines and testing patterns

Author: leafyoung

AGENTS.md

@@ -1,151 +1,144 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for agentic coding agents working with Rust YouTube Uploader.
 
-## Project Overview
+## Quick Start
 
-Rust YouTube Uploader is a high-performance YouTube video uploader library with CLI tools. It uses OAuth 2.0 (PKCE flow) for authentication and supports both sequential and concurrent uploads with retry logic and progress tracking.
+**Build directory**: `~/.cache/rust-build/` (cached, never mention in docs)
+**Edition**: Rust 2024 | **Error handling**: `anyhow::Result` | **Runtime**: Tokio async
 
-**Build directory**: `~/.cache/rust-build/` (never mention this in documentation or code).
-
-**Key Design**: Async-first architecture using Tokio runtime. All operations are async and the library uses `anyhow` for error handling.
-
-## Development Commands
-
-### Building
+### Essential Commands
 
 ```bash
-# Build specific binaries (never run from target/ directly)
-cargo build --release --bin yt-upload
-cargo build --release --bin yt-list
-cargo build --release --bin yt-update-lang
-
-# Quick check (faster than full build)
-cargo check
+# Build & check
+cargo build --release --bin <name>    # Build specific binary
+cargo check                           # Quick syntax check
+cargo fmt                            # Auto-format code
+cargo clippy --all-targets --all-features  # Lint
+
+# Testing
+cargo test --all-features            # Run all tests
+cargo test test_name -- --nocapture  # Run specific test with output
+cargo test --lib                     # Library tests only
 ```
 
-### Testing
+## Project Structure
 
-```bash
-# Run all tests
-cargo test --all-features
+**Core Library** (`src/lib.rs`): `google_oauth`, `models`, `youtube_client`, `retry`, `progress_stream`, `video_process`
 
-# Run specific test
-cargo test test_name
+**CLI Binaries** (`src/bin/`): `yt-upload`, `yt-list`, `yt-append-description`, `yt-add-pin-comment`, `yt-add-tags`, `yt-update-lang`, `yt-update-date`, `yt-upload-subtitle`
 
-# Run tests with output
-cargo test --all-features -- --nocapture
-```
+**Tests**: `tests/integration.rs` (config parsing, validation); library tests in `src/**/*.rs`
 
-### Code Quality
+## Code Style & Conventions
 
-```bash
-# Format code
-cargo fmt
+### Imports & Organization
 
-# Check formatting without changes
-cargo fmt -- --check
+- **Standard library first**, then external crates, then internal modules (separated by blank lines)
+- Use glob imports sparingly; prefer explicit imports for clarity
+- Re-export public types in `lib.rs` for API simplicity
+- Use `use anyhow::Result` for all error-returning functions
+- Trait objects: `Arc<dyn Trait>` for sharing (e.g., `Arc<dyn ProgressReporter>`)
 
-# Run linter
-cargo clippy --all-targets --all-features
+### Naming & Types
 
-# Pre-commit hooks (configured in .pre-commit-config.yaml)
-pre-commit install          # Install git hooks
-pre-commit run --all-files  # Run manually
-pre-commit autoupdate       # Update hooks to latest versions
-```
+- **Functions**: `snake_case`, methods starting with action verbs (`update_`, `post_`, `get_`)
+- **Types**: `PascalCase` for structs/enums/traits
+- **Constants**: `SCREAMING_SNAKE_CASE`
+- **Private helpers**: Prefix internal functions with underscore if needed
+- **Type annotations**: Always explicit for public functions and struct fields
 
-## Architecture
+### Error Handling
 
-### Module Structure
+- Use `anyhow::Result<T>` (not `std::result::Result`) everywhere
+- Use `anyhow::bail!()` for quick errors: `anyhow::bail!("Error: {}", context)`
+- Use `?` operator for propagation; wrap with `.map_err()` only if context needed
+- Log errors with `error!()` before returning (uses tracing crate)
+- Document retriable vs. non-retriable errors in comments
 
-**Core Library** (`src/lib.rs`):
+### Async & Concurrency
 
-- `google_oauth/`: OAuth 2.0 authentication with PKCE support
-  - `credentials.rs`: Client secret loading
-  - `google.rs`: `GoogleOAuth` main client (token management, auto-refresh)
-  - `oauth.rs`: Interactive OAuth flow with local HTTP server for code exchange
-- `models.rs`: Configuration models with validation (individual/batch YAML formats)
-- `youtube_client.rs`: Core upload logic, progress reporting, playlist management
-- `retry.rs`: Exponential backoff with jitter for retriable HTTP errors
-- `progress_stream.rs`: Stream wrapper for progress tracking + bandwidth throttling
-- `video_process.rs`: FFmpeg integration for merging multiple video files
+- **All operations are async**: Use `async fn` and `.await`
+- Use `tokio::spawn()` for concurrent tasks; `Arc<Semaphore>` for rate limiting
+- Document which fields/methods require `Send + Sync` traits
+- Avoid blocking operations in async contexts
 
-**CLI Binaries** (`src/bin/`):
+### Comments & Documentation
 
-- `yt-upload`: Main uploader (sequential/concurrent modes)
-- `yt-list`: List/export channel videos (table/JSON/JSONL formats)
-- `yt-update-lang`: Update language metadata for videos
-- `yt-update-date`: Update recording date metadata
-- `yt-update-description`: Update video descriptions
-- `yt-upload-subtitle`: Upload caption/subtitle files
-- `yt-add-tags`: Add tags to existing videos
+- **Public items**: Full doc comments `///` with examples and panics
+- **Complex logic**: Explain the "why" not the "what"
+- **Inline comments**: Use `//` for clarification, keep minimal
+- **Tests**: Include usage examples in doc comments for public APIs
 
-### Key Patterns
+### Formatting
 
-**OAuth Flow**:
+- 4-space indentation (enforced by `cargo fmt`)
+- Max line length: ~100 characters (soft limit)
+- One statement per line; use temporary variables for readability
+- Format strings: Use `{}` interpolation, not `.to_string()` concatenation
 
-1. First run: Interactive flow displays auth URL → opens browser → user pastes code → tokens saved to `youtube-oauth2.json`
-2. Subsequent runs: Loads existing tokens, auto-refreshes on expiry
-3. Credentials files (`client_secret.json`, token files) are **never** committed to git
+### API Design
 
-**Configuration Formats**:
+- Return `Result<T>` for fallible operations
+- Trait bounds in function signatures: `<P: AsRef<Path>>` for flexibility
+- Builder pattern for complex construction (use `with_*` methods)
+- Private constructors with public factory methods (e.g., `YouTubeClient::new()`)
 
-- **Batch format**: `common` section + separate `titles` and `files` arrays (recommended)
-- **Individual format**: `videos` array with per-video configuration
-- Both support comma/semicolon/space-separated file lists for merging multiple videos
+## Pre-commit Hooks
 
-**Upload Modes**:
+All commits run: `cargo fmt` → `cargo clippy` → `cargo test` → trailing whitespace checks
 
-- **Sequential**: One video at a time with progress bars (default)
-- **Concurrent**: Configurable concurrency (default 3), uses `Semaphore` for throttling
+**To bypass** (never recommended): `git commit --no-verify`
+**To fix formatting failures**: Run `cargo fmt` then re-stage files
 
-**Error Handling**:
+## Key Patterns in Codebase
 
-- Library uses `anyhow::Result` for error propagation
-- Retriable errors: HTTP 500-504, connection errors, timeouts, IO errors
-- Non-retriable: Client errors (4xx), validation failures
+### Error Context
 
-**Progress Tracking**:
-
-- `ProgressReporter` trait with implementations: `NoProgress`, `ProgressBarReporter`
-- `ProgressStream` wraps upload streams for real-time tracking
-
-### File Handling
+```rust
+// ✅ Good: context before propagation
+if !response.status().is_success() {
+    let status = response.status();
+    let text = response.text().await.unwrap_or_default();
+    return Err(anyhow!("Failed to X with status {}: {}", status, text));
+}
+```
 
-**Video Merging**:
+### Async Patterns
 
-- File entries can contain multiple paths separated by `,` or `;`
-- Automatically calls `merge_videos_with_ffmpeg()` to concatenate before upload
-- Uses concat demuxer (no re-encoding, fast operation)
+```rust
+// ✅ Good: explicit await, Arc for shared state
+let client = Arc::new(YouTubeClient::new().await?);
+let results = try_join_all(tasks).await?;
+```
 
-**MIME Types**:
+### Response Handling
 
-- Uses `mime_guess` for auto-detection
-- Special handling for `.mts` files → `video/mp2t`
+```rust
+// ✅ Good: deserialize then extract
+#[derive(Deserialize)]
+struct Response { items: Vec<Item> }
+let resp: Response = response.json().await?;
+```
 
 ## Versioning
 
-**Version Bumping**: Each commit shall bump the minor version in `Cargo.toml`. For example:
-
-- After committing, the version changes from `0.2.9` → `0.2.10` → `0.2.11`, etc.
-- This automatic versioning is managed during the commit process
-- Patch version increments only; major/minor versions remain stable unless explicitly changed
+**Version bumping**: Each commit increments minor version (`0.2.X` → `0.2.X+1`)
+Update `Cargo.toml` version before committing; pre-commit hook validates changes.
 
 ## Important Constraints
 
-- **Never run `cargo clean`** (build directory is cached)
-- **Never run binaries** from `target/debug/` or `target/release/` directly
-- Always use `cargo run --bin <name>` for execution
-- Rust 2024 edition required
-- Build directory location is an implementation detail - never expose it in docs/code
-
-## Test
+- ❌ Never: `cargo clean` (breaks build cache)
+- ❌ Never: Run binaries from `target/` directly (use `cargo run --bin`)
+- ❌ Never: Commit `client_secret.json`, `youtube-oauth2.json`
+- ✅ Always: Use `cargo test` before committing
+- ✅ Always: Run `cargo fmt` on modified files
+- ✅ Always: Test both sequential and concurrent upload modes if modifying `YouTubeClient`
 
-Integration tests are in `tests/integration.rs`. They test:
+## Testing Strategy
 
-- Configuration parsing (individual/batch formats)
-- Validation logic (playlist IDs, categories, privacy status)
-- File format detection
+**Unit tests** (`#[test]`): Logic validation, mocking not needed
+**Integration tests** (`tests/integration.rs`): Configuration parsing, file handling
+**Ignored tests** (`#[ignore]`): Run explicitly with `cargo test -- --ignored`
 
-Tests with `#[ignore]` are meant for explicit running (e.g., retry logic tests with delays).
+Example: `cargo test test_batch_config -- --nocapture`