123 lines
5.4 KiB
Markdown
123 lines
5.4 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
# 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.
|