# Go preferred libraries

Read [baseline.md](baseline.md) before this file. Prefer the standard library
until a library earns its keep. When a library is needed, these are the usual Go
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.