# Contributing to km ## Layout `cmd/` holds cobra wiring, one file per command. `internal/` holds everything else; see PLAN.md §3 for the map and the contracts every package codes against. ## The command pattern Copy `cmd/mailbox.go` (`mailbox list`) and `cmd/mail_list.go` (`mail list`). ```go type fooOpts struct{ /* flags and args */ } func newFooCmd(f *Factory) *cobra.Command { o := &fooOpts{} c := &cobra.Command{ Use: "foo ", Short: "…", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { p, err := f.Printer(cmd) // applies --json/--jq/--template if err != nil { return err } return runFoo(cmd.Context(), f, p, o) }, } render.AddOutputFlags(c, fooFields) // only on list/view/status commands return c } func runFoo(ctx context.Context, f *Factory, p *render.Printer, o *fooOpts) error { … } ``` - Get services lazily: `svc, err := f.Mail(ctx)`; raw JMAP via `f.JMAP(ctx)`. - Output through `p.Emit(v, human)`: `v` is what `--json` serialises (its JSON keys must match the fields passed to `AddOutputFlags`); `human` prints for people. Use `p.Table`, which aligns on a TTY and writes TSV in a pipe. - Thread/email ids from the user go through `f.IDs.Resolve(arg, idref.Thread)` (or `idref.Email` with `--message`). List commands call `f.IDs.Remember`. - TTY checks: `f.IO.StdoutTTY`, `f.IO.StdinTTY`. Prompts: `f.Prompt.Confirm`, `f.Prompt.Edit`. Never read the terminal directly. - Errors: return them. `usagef(...)` for bad usage (exit 2); `jmap.ErrAuthRequired` maps to exit 4; anything else is exit 1. Surface JMAP `MethodError`s and `SetError`s with their type and description. - Do not edit `cmd/root.go`; your command's constructor is already registered there. ## Testing `cmd/helpers_test.go` gives you `newTestEnv(t, tty)`: a Factory wired to a fake JMAP server (`internal/jmaptest`) loaded with `testdata/mailstore.json`, a fixed clock (`testNow`, 2026-11-14 12:00 UTC), and a `fakePrompter`. ```go e := newTestEnv(t, true) // true: stdin/stdout are a TTY, width 100 out := e.mustRun("mail", "list") // runs the real command tree golden(t, "mail_list_tty.txt", out) // cmd/testdata/golden/; -update rewrites e.Srv.Calls("Email/set") // recorded requests, for assertions e.Srv.Mail.Get("Email", "e-a1") // store state after a write e.Srv.Handle("X/y", handler) // add or override a method handler e.Prompt.Answers = []bool{true} // queue confirmation answers ``` The fake store implements `/get` and `/set` for Mailbox, Email, Identity, EmailSubmission (with `onSuccessUpdateEmail`), SieveScript and VacationResponse; `Email/query` with the common filters, `collapseThreads` and paging; `Thread/get`; back-references; uploads and downloads. Anything else, register in your test with `e.Srv.Handle`. `testdata/session.json` is a redacted copy of Kagi Mail's real session. `e.Srv.UseSessionFixture("../testdata/session.json")` advertises its capabilities instead of the minimal default. Live tests are opt-in and read-only: `KM_LIVE=1 go test ./internal/mail -run Live -v`. Before you hand work back: `gofmt -l .` prints nothing, and `go build ./... && go vet ./... && go test ./...` passes. ## Rules - The live mailbox is someone's real mail. Only the maintainer runs commands against it, and only read-only ones, except inside a scratch mailbox `km-test`. Test mail goes only to the account's own address. - Never put tokens, real addresses or real message content in the repository, fixtures or logs. Fixtures use `example.com`/`.org`/`.net` and lorem ipsum. - Dependencies are limited to those in `go.mod`. Ask before adding one. - Stay inside the files your work package owns. If a shared contract or helper needs to change, report it rather than changing it.