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).
type fooOpts struct{ /* flags and args */ }
func newFooCmd(f *Factory) *cobra.Command {
o := &fooOpts{}
c := &cobra.Command{
Use: "foo <id>", 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 viaf.JMAP(ctx). - Output through
p.Emit(v, human):vis what--jsonserialises (its JSON keys must match the fields passed toAddOutputFlags);humanprints for people. Usep.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)(oridref.Emailwith--message). List commands callf.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.ErrAuthRequiredmaps to exit 4; anything else is exit 1. Surface JMAPMethodErrors andSetErrors 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.
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/.netand 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.