mail-muncher AGENTS.md

AGENTS.md

Working notes for coding agents. Conventions and invariants only — the README is the user-facing documentation and is not repeated here.

What this is

mail-muncher gives a program its own read-only mailbox. It archives mail matching user-written rules to .eml and markdown files on disk, and serves that archive to agents over MCP. Go, no cgo, single binary. Two providers (Gmail API, IMAP) sit behind one interface; a pipeline fetches, parses, evaluates a match tree, and writes through sinks.

Commands

Go 1.25+. No code generation, no build tags, no other toolchain.

make build   # go build -o ./mail-muncher, version stamped from git describe
make test    # go test ./...
make lint    # golangci-lint run if installed, else go vet ./...
make fmt     # go fmt ./...
make tidy    # go mod tidy

These are green on a clean checkout. If they are not, that is a bug worth reporting rather than working around.

golangci-lint is optional and CI does not run it. Without the binary, make lint prints golangci-lint not found; falling back to go vet and runs go vet. The full set is pinned in .golangci.yml and is worth running locally before any change to error handling, file paths, or anything that writes to disk — it is not a CI gate because it was measured at 51 minutes on a GitHub runner. CI runs gofmt -l ., go mod tidy verification, go build, go vet, and go test -race.

Invariants a change must not break

These are the product, not preferences. A change that breaks one is wrong even if it compiles and the suite passes.

• No new OAuth scope. internal/provider/gmail/auth.go declares exactly one — gmail.readonly — and it is the only scope constant in the tree.
• Nothing that can send, delete, or modify mail. No Gmail Modify/Trash/Delete/Send/Insert/BatchModify; no IMAP STORE/EXPUNGE/APPEND/MOVE/COPY. IMAP opens mailboxes with EXAMINE (SelectOptions{ReadOnly: true}) and fetches with BODY.PEEK[] so reading never sets \Seen. This is enforced mechanically by TestProviderSourceNeverCallsAWriteCapableMailboxMethod in internal/provider/, which AST-walks provider source and fails on any write verb. If that test fires, the change is the problem, not the test.
• No credentials, tokens, real email addresses, or real message ids in a diff. Fixtures use example.com, acme.example, and .test. The OAuth client fixture at internal/provider/gmail/testdata/credentials.json is deliberately fake and must stay that way.
• The provider seam holds. Adding a provider must require zero changes to internal/pipeline, internal/filter, or internal/sink. A if provider == "imap" outside internal/provider/ means the interface is wrong; fix the interface.