Kagi Mail CLI client
km CONTRIBUTING.md
3.8 kB · 88 lines
Markdown
at main

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 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 MethodErrors and SetErrors 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/.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.