# Sopsy — Build Requirements
These are the acceptance requirements for completing `sopsy`. The functional spec lives in [AGENT.md](../AGENT.md); this file captures the *delivery* requirements agreed with the maintainer. Treat both as the definition of done.
## Scope
Implement **all** features and commands described in `AGENT.md`:
- `sopsy init` — bootstrap an encrypted repo (verify tools, generate Secure Enclave identity, print recipient, create `.sops.yaml`, `.env.example`, encrypt `.env.encrypted`, update `.gitignore`, create `.sopsy.yml`, run doctor).
- `sopsy doctor` — health checks (macOS/Apple Silicon/Secure Enclave/Touch ID, `sops`/`age-plugin-se`/`git`, `.sops.yaml`, repo health, break-glass warning).
- `sopsy edit <file>` — `EDITOR=… sops <file>` wrapper with nicer errors; forwards trailing `-- <sops args>`.
- `sopsy recipient add [name]` / `remove [name]` / `list` — mutate `.sops.yaml` recipients, then run `sops updatekeys -r .`.
- `sopsy recipient keygen` — generate a Secure Enclave identity and print it (no config changes); forwards trailing `-- <age flags>` to `age-plugin-se keygen`.
- `sopsy recipient break-glass -o <file>` — generate a portable emergency key, hand it off for offline storage, delete the local copy, and register it (also offered during `init`).
- `sopsy join <name>` / `sopsy approve <name>` — self-service onboarding: a newcomer records a pending request (`join`); any active member activates it and re-keys (`approve`), gated by a `join_request_ttl` freshness window.
- `sopsy check` — CI gate (exit 0/1): `.env` not committed and is ignored, `.sops.yaml` valid, every encrypted file matches a creation rule, no plaintext secrets in tracked files, all encrypted files parse, break-glass recipient exists.
Out of scope for v1 (do NOT build): Linux, TPM, YubiKey, KMS, 1Password/Vault integration, native Rust SOPS, Ratatui.
## Quality bar
1. **Tests with > 95% coverage.** Measure coverage (e.g. `cargo llvm-cov`).
1. **Test on real files** — real temp git repos, real `sops`/`age`/`age-plugin-se` where available; mock/fake binaries only where Secure Enclave hardware is required.
1. **GitHub Actions CI** that **fails** the build if tests, `cargo fmt --check`, or `cargo clippy -D warnings` fail.
1. **Idiomatic, best-practice Rust** throughout — for both library code and tests. Edition 2024 idioms, no `unwrap()`/`panic!` on recoverable paths (use `Result` + `anyhow`/`thiserror`), `clippy -D warnings` clean, small focused modules, doc comments on public items, table-driven/property tests where they fit.
1. **Dependencies must be healthy.** Only pull in crates that are actively maintained (recent commits), widely adopted (large community, many GitHub stars), and from reputable maintainers. Prefer the de-facto standard crate for each job; avoid abandoned, single-author-no-activity, or low-star libraries. Justify any non-obvious dependency choice in the commit message.
## UX requirements
- Terminal UI must be **colorful, playful, and very easy to use**. Use color freely, including animated lines that change color where it adds delight.
- **Interactive mode**: prompt the user with questions and multi-selects (via `inquire`); persist answers to `.sopsy.yml`.
- **Non-interactive mode**: everything settable via command-line flags so the tool is scriptable / CI-friendly. Interactive prompting must be suppressible.
## Documentation style
- Use **Mermaid diagrams** in markdown wherever they aid understanding (architecture, command flows, the encrypt/decrypt data flow, recipient/key lifecycle, CI gating).
- Use **GitHub admonitions** (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`) throughout `README.md` and everything under `docs/`.
- End-to-end tests must cover the **dotenv (`.env`) secret format**, not only YAML/JSON — sops supports `dotenv` as an input/output type and it's the primary use case here.
## Process requirements
- Architecture roughly per `AGENT.md` layout (`src/cli.rs`, `src/commands/`, `src/sops/`, `src/enclave/`, `src/git/`, `src/doctor/`, `tests/`).
- **Single pull request**; keep pushing commits to it until all functionality is done.
- Atomic commits (one logical change each), imperative subject ≤ 50 chars.
- **Document `README.md` at the end** once features are complete.
## Definition of done
- [ ] All commands above implemented (interactive + non-interactive).
- [ ] > 95% test coverage, tests exercise real files.
- [ ] CI workflow green, and red when tests/fmt/clippy fail.
- [ ] Colorful/playful UX with interactive multi-selects.
- [ ] README documented.
- [ ] Single PR with iterative commits, all merged-ready.
