List system views through thread list

[code-monger-givenall]

What changed

Replaces the four old top-level system-view commands with one read-only listing:

• hey thread list --in sent
• hey thread list --in spam
• hey thread list --in trash
• hey thread list --in everything

The command supports --limit, opaque --page, --all, and the standard listing output flags. Every JSON row carries topic_id explicitly; both id and topic_id are thread IDs for hey thread read, not box item IDs for organization actions. Styled and Markdown output sanitize server-provided titles, subjects, and sender names.

The typed topic-list helpers in SDK v0.29.0 discard the geared-pagination Link header. This command therefore reads the same four fixed routes through the SDK document client, decodes generated.TopicListResponse, and retains only the opaque next-page cursor. Authentication, account scoping, caching, response limits, and hooks remain in the SDK.

Validation

• GOWORK=off TMPDIR=/tmp mise exec -- make check
• the smoke-test module compiles
• coverage-instrumented tests pass at 83.550%, above the 70.8% floor
• no live mailbox read or mutation was run

[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.

[jeremy]

This fills a real gap. On main the named box routes reach Imbox, The Feed, Paper Trail, Set Aside, Reply Later and Bubble Up, hey search --in trash is the only way to see Trash, and nothing lists Sent, Spam or Everything, even though the SDK has had Topics().GetSent, GetSpam, GetTrash and GetEverything for a while. I'd like to take it, with two changes.

1. Rebase onto main. hey box became hey box view, listings are built in internal/cmd/postings_listing.go over internal/mail.Source, paging is --limit, --page and --all, and the box view is the template for how a listing renders, truncates and reports next_page. Use terminal.SanitizeLine on subjects and sender names, as the earlier review noted; main has it.

2. One command rather than four top-level ones. The four routes return topics, whose IDs are what hey thread read takes, while every row hey box view shows carries a box item ID, which is what hey trash, hey move and hey seen take. Four new top-level nouns sitting next to the trash and spam verbs blur that line, and the spammed/trashed spellings exist only to dodge the collision. Folding them into one command states the ID kind once: hey thread list --in sent|spam|trash|everything, with --limit, --page, --all and the usual output flags, and topic_id on every JSON row. If the maintainer prefers a different spelling that's a rename, but the constraint is one command whose help says these are thread IDs.

Keep the tests and the SKILL.md section; they carry over. Once this lands, hey restore from #186 has a listing to point at for finding a trashed thread's ID.

[code-monger-givenall]

Rebased onto current main and folded the four old top-level commands into hey thread list --in sent|spam|trash|everything in 2bfd149.

The command carries explicit topic_id rows, --limit, opaque --page, --all, the standard listing formats, and terminal sanitization. The typed SDK methods do not expose the geared-pagination Link header, so the implementation reads those same four fixed routes through the SDK document client and decodes generated.TopicListResponse; account scoping, authentication, caching, response limits, and hooks remain inside the SDK.

Validation: GOWORK=off TMPDIR=/tmp mise exec -- make check passes with zero lint issues; the smoke module compiles; instrumented coverage is 83.550% against a 70.8% floor. No live mailbox call was run.