feat(mail list): server-side unread/flagged filtering, envelope fields, and field selection

[kochj23]

Summary

Addresses the mail list limitations from the issue, in internal/imap
(client.go, types.go) and internal/cli (mail.go, cli.go):

• Server-side filtering. --unread now issues IMAP SEARCH UNSEEN and a
  new --flagged issues SEARCH FLAGGED. Previously --unread fetched N
  messages and filtered client-side, so you got back fewer than the limit; the
  count now respects --limit.
• Missing envelope fields. MessageSummary gains from_address, to,
  message_id, and in_reply_to. All four come straight from the ENVELOPE
  already fetched, so there is zero extra fetch cost. from_address lets you
  match on sender/domain without a per-message mail read; in_reply_to lets
  you reconstruct reply chains from list output.
• Field selection. --fields uid,from_address,subject projects JSON output
  to the requested keys, and --compact emits a bare JSON array instead of the
  wrapper object. Both affect --json mode only; text output is unchanged.

ListMessages was refactored to take a ListOptions struct instead of
positional parameters (as suggested in the issue), and all call sites (drafts,
watch) were updated. README documents the new flags, fields, and JSON shape.

Tests

Added internal/imap/list_options_test.go (real in-memory IMAP server, no new
dependency) and internal/cli/mail_list_fields_test.go, covering all seven
categories:

• Security – empty-mailbox filter returns cleanly (no error/panic);
  --fields rejects unknown/typo'd field names instead of silently ignoring
  them.
• Performance – server-side unread listing is bounded by the limit;
  projection scales linearly over 5k messages.
• Retry – repeated SEARCH+FETCH queries and repeated projections are stable
  and deterministic.
• Unit – paginateSeqNums pagination math; splitFieldList; projection
  keeps only requested keys.
• Integration – with the newest messages already read, SEARCH UNSEEN
  still returns the unread ones (the exact client-side-truncation bug); flagged
  filtering; projected output round-trips through JSON.
• Functional – envelope fields (from_address/to/message_id/
  in_reply_to) populated from the ENVELOPE; a requested-but-empty field is
  emitted as null for a stable shape.
• Frame – N/A (no new wire framing; envelope/search decoding and JSON
  encoding covered by the tests above); explicit skip placeholders retained.

go build ./... && go vet ./... && go test ./... all green.

Closes #9

🤖 Generated with Claude Code

[bscott]

Reviewed and verified locally: gofmt/go vet/go test clean. This is the strongest of the three — the extraction of listSeqSet/paginateSeqNums/newMessageSummary is a real improvement over the inline version, and moving --unread to a server-side SEARCH fixes the actual bug in #9 (client-side filtering could return far fewer than --limit). Pulling the extra envelope fields costs no additional fetch, which is the right observation.

Merging. Two follow-ups I'm pushing right after:

1. internal/cli/help.go wasn't updated. Per CLAUDE.md, new flags need to land in the --help-json schema — that output is the documented contract for agent integration, so --flagged, --fields, and --compact were invisible to it. I've added them (plus the pre-existing --offset/--page, which were also missing).
2. Test signature collision with fix(imap): error instead of silent success when STORE/COPY/MOVE target UIDs aren't present #15. Both PRs merge cleanly in git but conflict semantically: fix(imap): error instead of silent success when STORE/COPY/MOVE target UIDs aren't present #15's client_affected_test.go calls the old ListMessages(mailbox, limit, offset, unreadOnly). Updated those three call sites to ListOptions.

Also noting for later, not blocking: Search() still builds MessageSummary inline and doesn't populate FromAddress/To/MessageID/InReplyTo, so mail list and mail search now return different shapes. Worth routing Search() through newMessageSummary too.

Closes #9.