arc/AGENTS.md

Arc – AGENTS.md

Arc is a delta-based version control system written in Rust. See docs/spec.md for the full specification.

Required Context

• Always load the rust skill before writing or modifying any Rust code in this project.
• Always read docs/spec.md before starting any implementation work. It contains the full specification, design rules, command definitions, and phased implementation plan that all changes must conform to.

Build & Quality Commands

All commands must be run inside the Nix dev shell. cargo build alone is not a valid build method.

# Format code
nix develop -c cargo fmt

# Type/compilation check
nix develop -c cargo check

# Lint (must produce zero warnings)
nix develop -c cargo clippy -- -D warnings

# Run all tests
nix develop -c cargo test

# Full Nix build (the only valid build method)
nix build

Run in this order: fmt → check → clippy → test → nix build.

Project Structure

arc/
├── src/
│   ├── main.rs          # Entry point, CLI dispatch
│   ├── cli.rs           # Clap CLI definitions and alias expansion
│   ├── model.rs         # Core data model (commits, deltas, metadata)
│   ├── repo.rs          # Repository operations (init, state)
│   ├── store.rs         # ZSTD + bincode storage layer
│   ├── tracking.rs      # Auto-change detection
│   ├── diff.rs          # Diff computation
│   ├── merge.rs         # Three-way merge
│   ├── refs.rs          # Bookmarks and tags
│   ├── inspect.rs       # log, show, history commands
│   ├── modify.rs        # revert, reset, graft commands
│   ├── stash.rs         # Named stash system
│   ├── config.rs        # YAML config (local + global, rule 21)
│   ├── ignore.rs        # .ignore / .arcignore support
│   ├── signing.rs       # Optional SSH key commit signing
│   ├── bridge.rs        # Git bridge (push/pull/clone/migrate/sync)
│   ├── remote.rs        # Remote management
│   ├── resolve.rs       # Commit/ref resolution
│   ├── check.rs         # Validation utilities
│   ├── error.rs         # Error types (anyhow for app, thiserror for lib)
│   └── ui.rs            # Terminal output formatting (colored)
├── tests/               # Integration tests (one file per feature area)
├── docs/
│   └── spec.md          # Full specification and implementation plan
├── Cargo.toml
├── flake.nix            # Nix flake (nixpkgs-unstable, flake-parts, fenix, crane)
└── flake.lock

Key Design Rules

• Delta-based, not snapshot-based. Commits store incremental deltas, not full snapshots.
• No staging area. Changes are automatically tracked; arc commit captures the full worktree diff.
• Bookmarks, not branches. arc mark manages bookmarks; they map to git branches when pushed.
• Tags are immutable. Once created, tags cannot be modified.
• Commits are immutable. Previous commits cannot be edited or amended.
• Storage format: ZSTD-compressed bincode for deltas and commit data.
• Config format: YAML. Local config takes precedence over global (rule 21).
• Ignore files: .ignore or .arcignore.
• Default bookmark: main. Default remote: origin.
• Aliases defined in config are expanded at CLI level before dispatch.
• Git bridge: All remote operations (push, pull, clone, migrate, sync) use git2 for compatibility.
• Commit signing: Optional, via SSH keys (ed25519).

Dependencies

Crate	Purpose
clap	CLI parsing with derive macros
serde	Serialization/deserialization
serde_yaml	YAML config files
bincode	Binary serialization for delta storage
zstd	ZSTD compression for stored deltas
sha2	SHA-256 commit hashing
hex	Hex encoding for commit IDs
git2	Git bridge (vendored libgit2 + openssl)
ssh-key	SSH key commit signing (ed25519)
colored	Terminal color output
tempfile	Temporary directories in tests (dev-dep)

Testing Conventions

• All tests live in the tests/ directory as integration tests (one file per feature area).
• Tests must use tempfile::TempDir for isolated repositories.
• Test both happy paths and error/edge cases.
• Use descriptive test function names that explain the behavior under test.
• Run tests with: nix develop -c cargo test

Commit Conventions

Use conventional commits:

• feat: <message> — new features
• fix: <message> — bug fixes
• refactor: <message> — code changes that are not features or fixes
• docs: <message> — documentation changes
• build: <message> — build system changes
• test: <message> — test additions or changes

Code Style

• Follow standard Rust naming conventions (snake_case functions, PascalCase types).
• Use anyhow / thiserror for error handling; no .unwrap() in production code.
• Prefer &str over &String, &[T] over &Vec<T> in function parameters.
• No #![deny(warnings)] in crate roots; use clippy flags instead.
• Do not add code comments unless the code is genuinely complex.