Add read-only system email views

[code-monger-givenall]

What changed

Adds four read-only commands for the HEY system views:

• hey sent
• hey spammed
• hey trashed
• hey everything

spammed is intentionally different from hey spam <id>, which marks an email as spam. Likewise, trashed lists Trash while hey trash <id> moves an email there.

Each command uses the corresponding typed Topics() SDK method, supports --page, and returns thread IDs that work with hey threads. Empty JSON results are always [], not null.

The commands are included in root help, .surface, the README, API coverage, the bundled HEY skill, unit tests, and smoke coverage.

Tests

• env GOWORK=off mise x go@1.26.6 golangci-lint@2.12.2 -- make check
• The nested smoke-test module compiles successfully.
• Unit tests cover all four routes, page forwarding, styled output, validation before requests, result IDs, and the empty-array JSON contract.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds new “topic view” commands to the HEY CLI for listing system mailbox topics (Sent, Spam, Trash), along with tests and documentation updates.

Changes:

• Introduce hey sent, hey spam, and hey trashed commands with paging and styled/JSON output support.
• Add unit + smoke tests covering JSON/styled output and invalid paging.
• Update docs/help/coverage/surface metadata to include the new commands.

Reviewed changes

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

Show a summary per file

File	Description
tests/smoke/topic_views_test.go	Smoke tests for the new topic view commands and paging.
skills/hey/SKILL.md	Adds triggers + usage docs for hey sent/spam/trashed and paging.
internal/cmd/topic_views_test.go	Unit tests around HTTP request shape, output formats, empty results, and invalid page handling.
internal/cmd/topic_views.go	Implements the new commands and shared rendering/summary logic.
internal/cmd/root.go	Registers the new commands in the root CLI.
internal/cmd/help.go	Adds commands to curated help categories and examples.
README.md	Documents new commands in the quick-start examples.
API-COVERAGE.md	Marks the new endpoints as covered.
.surface	Adds the new commands/flags to surfaced CLI list.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (4)

skills/hey/SKILL.md:92

• The new table/flow entries use inconsistent capitalization and phrasing (e.g., “List Spam” vs “List sent email”), which makes the docs look uneven and slightly harder to scan. Consider standardizing to sentence case and consistent nouns (e.g., “List sent topics”, “List spam topics”, “List trash topics”).

| List sent email | `hey sent --json` |
| List Spam | `hey spam --json` |
| List Trash | `hey trashed --json` |

skills/hey/SKILL.md:130

• The new table/flow entries use inconsistent capitalization and phrasing (e.g., “List Spam” vs “List sent email”), which makes the docs look uneven and slightly harder to scan. Consider standardizing to sentence case and consistent nouns (e.g., “List sent topics”, “List spam topics”, “List trash topics”).

├── List sent email? → hey sent --json
├── List Spam? → hey spam --json
├── List Trash? → hey trashed --json

tests/smoke/topic_views_test.go:24

• This smoke test doesn’t assert anything about the result (it discards the response), so it only verifies that the command doesn’t error. To better cover pagination behavior, assert at least that the response is OK (and ideally that it returns a list of topics / a non-empty summary) after requesting --page 2.

func TestTopicViewPage(t *testing.T) {
	_ = heyJSON(t, "sent", "--page", "2")
}

internal/cmd/topic_views_test.go:63

• The helper decides whether to decode an output.Response by searching the raw args string for --json, which is brittle (e.g., future tests combining --json with output-modifying flags like --quiet, --ids-only, --count, etc., could produce non-envelope output and make this helper fail). Consider making runTopicView take an explicit expectEnvelope bool (or similar), or decide based on the actual selected output format instead of substring matching.

	if strings.Contains(strings.Join(args, " "), "--json") && buf.Len() > 0 {
		if err := json.Unmarshal(buf.Bytes(), &resp); err != nil {
			t.Fatalf("decode response: %v\n%s", err, buf.String())
		}
	}

[code-monger-givenall]

I also picked up the later review notes in this refresh. The docs now use consistent sentence case, the smoke checks assert a summary and array-shaped data, and the read-only Spam command is now spammed so it does not collide with the existing mutation.

[Copilot]

Pull request overview

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

Suppressed comments (1)

internal/cmd/topic_views.go:136

• The styled path writes API-supplied subjects and sender names directly to the terminal. These are untrusted email fields, so embedded control/escape characters can manipulate terminal output; sanitize both values with terminalSafeText before truncating/rendering them.

				truncate(topic.Name, 48),
				topicViewSender(topic),

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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