# 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`).
2. **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.
3. **GitHub Actions CI** that **fails** the build if tests, `cargo fmt --check`, or
   `cargo clippy -D warnings` fail.
4. **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.
5. **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.
