feature/make it work

[cboone]

• docs: add plan to fix bugs, harden tests, and improve search UX
• docs: fix plan counts and clarify live scrut strategy
• fix: fix text search, harden tests, and improve search UX
• test: exercise SearchEmails snippet path and harden live checks

[Copilot]

Pull request overview

This PR fixes jm search text-query behavior, expands search UX capabilities (offset/sort/unread), and hardens the CLI scrut suite by isolating environment-dependent configuration. It also introduces an opt-in live integration scrut suite and updates documentation accordingly.

Changes:

• Fix SearchSnippet/get JMAP result referencing for text search, and add unit coverage for that request shape.
• Add search pagination/sort/unread support (flags + client implementation), plus improved search method-error messaging.
• Make CLI scrut tests deterministic by unsetting JMAP_* env vars; add opt-in tests/live.md and split make test-cli vs make test-cli-live.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
internal/client/email.go	Fix snippet reference to Email/query /ids; add offset/sort/unread; improve method-error context; set result offset.
internal/client/email_test.go	Add unit test ensuring SearchSnippet/get references Email/query /ids and populates snippets.
cmd/search.go	Add --offset, --sort, --unread flags and validation; reuse parseSort.
cmd/list.go	Extend parseSort to accept colon syntax (e.g. from:asc).
cmd/list_test.go	Add tests for colon sort syntax.
internal/client/mailbox.go	Cache mailbox list for the lifetime of a Client instance.
internal/client/client.go	Add per-client mailbox cache storage and a doFunc hook to enable request capture in unit tests.
tests/errors.md	Unset JMAP_* env vars for auth-failure expectations.
tests/flags.md	Unset JMAP_* env vars for auth-failure expectations.
tests/arguments.md	Unset JMAP_* env vars for auth-failure expectations.
tests/help.md	Update search help snapshot for new flags.
tests/live.md	Add opt-in live scrut tests for success paths, snippets, and text output.
Makefile	Split deterministic scrut runs (test-cli) from opt-in live runs (test-cli-live).
docs/CLI-REFERENCE.md	Document new search flags and colon sort syntax.
docs/plans/done/2026-02-08-fix-bugs-and-improve-search-tests-ux.md	Add completed plan/design notes reflecting the implemented changes.
docs/plans/todo/dapper-sauteeing-taco.md	Remove obsolete TODO plan.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

cmd/list.go:68

• With the new colon-to-space normalization, inputs like receivedAt:foo will now be treated as field=receivedAt with an unrecognized direction silently falling back to descending. Consider validating the direction token when present (accept only asc/desc, error otherwise) so typos don’t change sort behavior silently.

func parseSort(s string) (field string, ascending bool, err error) {
	s = strings.ReplaceAll(s, ":", " ")
	parts := strings.Fields(s)
	field = "receivedAt"
	ascending = false

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

cmd/list.go:79

• parseSort treats any second token other than asc as descending (including invalid values). This conflicts with the CLI help/docs that imply only asc/desc are accepted, and can hide typos like --sort "receivedAt des". Consider validating the direction token explicitly (accept only asc/desc, error otherwise) so users get immediate feedback.

func parseSort(s string) (field string, ascending bool, err error) {
	s = strings.ReplaceAll(s, ":", " ")
	parts := strings.Fields(s)
	field = "receivedAt"
	ascending = false

	if len(parts) >= 1 {
		normalized, ok := validSortFields[strings.ToLower(parts[0])]
		if !ok {
			return "", false, fmt.Errorf("unsupported sort field %q", parts[0])
		}
		field = normalized
	}
	if len(parts) >= 2 && strings.EqualFold(parts[1], "asc") {
		ascending = true
	}
	return field, ascending, nil

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.