# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

`dot` is a CLI dotfiles manager for Unix-like systems, written in Rust. It manages configuration files by moving them into a centralized repository and creating symbolic links at their original locations. Published to crates.io as `dot_rust`.

## Build & Development Commands

```bash
cargo build                  # Build debug
cargo build --release        # Build release
cargo test                   # Run all tests (unit + integration)
cargo test --lib             # Run unit tests only
cargo test --test integration # Run integration tests only
cargo test <test_name>       # Run a single test by name
cargo clippy                 # Lint
cargo fmt                    # Format code
```

## Architecture

The crate exposes both a library (`src/lib.rs`) and a binary (`src/main.rs`). The binary uses the library's public modules.

**Core modules:**

- **`cli`** — Clap-based CLI definition and `run()` entry point. Parses subcommands (`init`, `add`, `remove`, `sync`) and dispatches to the corresponding command struct.
- **`commands/`** — Each command implements the `Command` trait (`execute(self) -> Result<()>`). Commands are self-contained structs: `InitCommand`, `AddCommand`, `RemoveCommand`, `SyncCommand`. Each exposes a static method (e.g., `add_to_manifest`, `sync_manifest`) that separates core logic from I/O for testability.
- **`manifest`** — `Manifest` struct wrapping a `BTreeMap<PathBuf, PathBuf>` serialized as TOML (`dot.toml`). Maps local filenames to their original paths (stored with `~` prefix). Methods come in pairs: `load`/`load_from`, `save`/`save_to`, `get`/`get_with_home` — the `_with_home` variants allow injecting a fake home directory for testing.
- **`path`** — Tilde expansion/collapse utilities and lexical absolute path resolution. Same `_with_home` pattern for testability.
- **`error`** — `thiserror`-based `Error` enum and `Result` type alias used throughout.

**Key pattern:** Functions that depend on the home directory have `_with_home` variants that accept `Option<PathBuf>` to enable deterministic testing without relying on the actual home directory.

## Conventions

- Commits follow **conventional commits** format (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`, etc.).
- Unit tests live alongside their modules in `#[cfg(test)] mod tests`. Integration tests are in `tests/integration.rs` and use `tempfile::TempDir` for isolation.
- The manifest file is always named `dot.toml` (constant `MANIFEST_FILE`).