# Preferred libraries

Prefer the standard library until a library earns its keep. When a library is
needed, these are the usual defaults.

| Need | Default | Notes |
| --- | --- | --- |
| TOML config | `github.com/BurntSushi/toml` | Preferred for direct, boring TOML parsing. Avoid heavy config frameworks by default. |
| CLI commands | `github.com/spf13/cobra` + `charm.land/fang/v2` | Cobra for command structure; Fang for polished help, errors, version, and signal handling. Tiny tools may use stdlib. |
| TUI implementation | Charm v2 stack via `golang-tui` | Load `golang-tui` for Bubble Tea, Lip Gloss, Bubbles, testing, layout, keymap, terminal, and performance details. |
| MCP server | `github.com/modelcontextprotocol/go-sdk` | Use typed parameter structs, tool annotations, stdio by default. |
| Wails desktop | `github.com/wailsapp/wails/v2` | Go owns domain logic; frontend renders state and calls bindings. |
| Light web server | `net/http`, `html/template`, `embed` | Default web stack for mostly server-rendered apps. |
| User-provided HTML sanitisation | `github.com/microcosm-cc/bluemonday` | Use strict or UGC policies intentionally. |
| SQLite without CGO | `modernc.org/sqlite` through `database/sql` | Useful for easily shipped binaries. Reconsider if CGO is already required. |
| RSS/Atom | `github.com/mmcdole/gofeed` | Fine for feed ingestion. |
| Git access in-process | `github.com/go-git/go-git/v5` | Useful when shelling out to git is not acceptable. |
| Behaviour specs | `github.com/regen-network/gocuke` | Explicit opt-in only. Ask whether the project wants gocuke before adding it. |
| Property tests | `pgregory.net/rapid` | Add around parsers, state machines, and merge logic. |
| Comparisons in tests | `github.com/google/go-cmp/cmp` | Prefer over ad-hoc string diffs for structured values. |
| Linux packages | `nfpm` | Prefer for `.deb`, `.rpm`, `.apk`, and Arch package artifacts. |

## Dependency rules

- Add dependencies with the relevant CLI (`go get`, `go install`, package
  manager command); do not hand-edit manifests.
- Keep direct dependencies direct and intentional. Run `go mod tidy` after
  changes.
- Prefer concrete types. Avoid broad maps, `any`, or reflection unless parsing a
  real untyped boundary.
- If a project already made a different good choice, preserve it unless the user
  asked for an opinionated migration.