# AGENTS.md

Context for any AI coding agent working in this repo (Claude Code, OpenCode, Cursor,
Codex, Aider, Zed, …). Keep this file short and authoritative — anything that grows
beyond a quick reference belongs in a dedicated doc and should be linked from here.

## Project

`rsecure` is a small Rust CLI for file encryption using AES-256-GCM via the
[`aes-gcm`](https://crates.io/crates/aes-gcm) crate. It encrypts and decrypts files
or directories in 128 KiB chunks using STREAM (`EncryptorBE32`), parallelized with
`rayon` and shown via `indicatif` progress bars. CLI parsing is `clap` derive.

Source layout:

- `src/main.rs` — entry point, forbids `unsafe` crate-wide.
- `src/cli/` — `clap` argument definitions.
- `src/commands/` — one module per subcommand (`create_key`, `encrypt_file`, `decrypt_file`).
- `src/file_ops.rs`, `src/utils.rs` — shared helpers.
- `tests/cli.rs` — integration tests via `assert_cmd` + `predicates`.

## Setup & common commands

Rust toolchain is pinned via `rust-toolchain.toml` (currently 1.94.0). Use the
`Makefile` targets when possible — they match what CI runs.

```bash
make test         # cargo nextest run
make lint         # cargo clippy -- -D warnings
make fmt          # cargo fmt --all
make ci           # fmt + lint + test (run before pushing)
make build        # debug build
make release      # release build
```

Run a single test: `cargo nextest run -E 'test(/<name>/)'`.

## Conventions

- **Commits**: Conventional Commits, enforced by [cocogitto](https://docs.cocogitto.io/).
  Use `cog commit <type> "<msg>" [scope]` rather than `git commit -m`. Common types:
  `feat`, `fix`, `chore`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`.
- **No `unsafe`** in `rsecure` itself — `src/main.rs` declares `#![forbid(unsafe_code)]`.
  Dependencies may use unsafe; that is acceptable.
- **Auto-push**: a `post-commit` git hook pushes every commit to `origin/main`. Do not
  `git commit` work-in-progress to `main` — branch first.
- **Pre-commit hook** (`pre-commit.sh`) runs `pre-commit run -a`, `cargo nextest run`,
  `cargo fmt`, and `cargo check`. If a hook fails, fix the underlying issue and create
  a NEW commit — do not bypass with `--no-verify`.

## Releases

A new version is cut with the [release skill](.claude/skills/release/SKILL.md) — invoke
it via "release" / "bump version" in Claude Code, or follow the steps manually. In short:

```bash
cog bump --version X.Y.Z
```

`cog.toml`'s `pre_bump_hooks` update `Cargo.toml` (via `cargo set-version`), refresh
`Cargo.lock`, regenerate `CHANGELOG.md`, and create a tagged bump commit. The
`post_bump_hook` pushes the tag. The `Cargo.toml` version and the latest git tag
MUST stay in sync — verify before and after.

Required local tools: `cog` (cocogitto 7+) and `cargo-set-version` (from `cargo-edit`).

## CI

`.github/workflows/ci-cd.yml` runs on PRs, pushes to `main`/`dependabot/*`, and tag
pushes. Jobs: `security` (cargo-audit + cargo-deny), `linting` (fmt + check), `test`
(`cargo test`), `build` (cross-platform matrix), `goreleaser` and `publish-crate` on
tag. The `security` job also runs weekly on a cron to surface new advisories.

`cargo-deny` policy lives in `deny.toml` — keep advisories at `version = 2` and only
permissive licenses allowed.

## Security

This is a cryptographic tool. Read `SECURITY.md` before changing any code in
`src/commands/encrypt_file.rs`, `src/commands/decrypt_file.rs`, `src/commands/create_key.rs`,
or `src/file_ops.rs`. The threat model and what `rsecure` does and does not guarantee
are documented there. Vulnerability reports go through GitHub Security Advisories —
never open a public issue for a security bug.

## Things to avoid

- Do not introduce `unsafe` (`#![forbid(unsafe_code)]` will fail the build).
- Do not skip pre-commit hooks (`--no-verify`).
- Do not bump the version manually in `Cargo.toml` — use `cog bump`.
- Do not edit `CHANGELOG.md` by hand — it is regenerated by `cog changelog`.
- Do not commit credentials, key files, or `.enc` artifacts; the `.gitignore` covers
  the obvious cases but be aware when adding test fixtures.
