Restrict posting actions to email threads

[ivankuznetsov]

Summary

hey move, hey trash, and hey ignore now require the exact flag --kind topic. Missing and non-email kinds fail before config, authentication, or any SDK request, while existing bulk-ID behavior stays unchanged.

Fresh main already contains the posting actions from #173, #175, and #176. This rebase drops PR #152's superseded command implementations and applies only the email-thread safety guard to the current commands. The CLI does not manage HEY World posts.

Validation

• make fmt-check
• make vet
• go test ./internal/...
• make tidy-check
• make check-surface
• go test -race -count=1 ./internal/...
• make build
• A malformed-config regression proves kind validation runs before root setup
• Compound Engineering review completed; its id versus topic_id wording finding was fixed and regression-tested

Risk

--kind is a caller-supplied safety assertion, not an authorization boundary. The server remains responsible for rejecting an ID that is invalid for an action.

---

Summary by cubic

Adds six CLI commands to move or ignore a single email posting, and validates the posting kind before setup/auth to fail fast on non-email content. Blocks list-only output modes from mutating state.

• Commands: paper-trail, feed, set-aside, reply-later, trash, ignore (use as hey <command> <posting-id> --kind topic; aliases for some, e.g., papertrail, trail, aside, later).
• Requires --kind topic; rejects world/post and other kinds before setup or any request, with a clearer message for trash.
• Accepts exactly one posting ID; trash moves to Trash only (no permanent delete).
• Errors early if --ids-only or --count are set; no request is sent.
• Updates help, README, and skills/hey with singular guidance and state-change warnings; adds unit tests and real-server smoke tests for all six actions.

^{Written for commit 3aa17df. Summary will update on new commits.}

[Copilot]

Pull request overview

Adds six single-posting management commands backed by the HEY SDK.

Changes:

• Adds routing, trash, and ignore commands.
• Adds unit tests and CLI surface entries.
• Updates README, help, and agent guidance.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

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

Show a summary per file

File	Description
skills/hey/SKILL.md	Documents commands and approval requirements.
README.md	Adds usage examples.
internal/cmd/root.go	Registers the commands.
internal/cmd/posting_actions.go	Implements posting actions.
internal/cmd/posting_actions_test.go	Adds mocked endpoint tests.
internal/cmd/help.go	Adds commands to curated help.
.surface	Updates the CLI surface snapshot.

Comments suppressed due to low confidence (5)

internal/cmd/posting_actions.go:81

• The help text and machine-readable agent_notes describe multiple postings/IDs, but this command accepts exactly one. This contradicts the command's cardinality contract and can mislead users or agents into attempting a batch; make both descriptions singular.

		"Move postings to Trash",
		"moved to Trash",
		"State-changing action. Confirm the exact posting IDs and obtain explicit user approval before moving each posting to Trash.",

internal/cmd/posting_actions.go:105

• The help text and machine-readable agent_notes describe multiple postings/IDs, but this command accepts exactly one. This contradicts the command's cardinality contract and can mislead users or agents into attempting a batch; make both descriptions singular.

		"Move postings to Set Aside",
		"moved to Set Aside",
		"State-changing action. Confirm the exact posting IDs and obtain explicit user approval before moving each posting to Set Aside.",

internal/cmd/posting_actions.go:93

• The help text and machine-readable agent_notes describe multiple postings/IDs, but this command accepts exactly one. This contradicts the command's cardinality contract and can mislead users or agents into attempting a batch; make both descriptions singular.

		"Move postings to The Feed",
		"moved to The Feed",
		"State-changing action. Confirm the exact posting IDs and obtain explicit user approval before moving each posting to The Feed.",

internal/cmd/posting_actions.go:118

• The help text and machine-readable agent_notes describe multiple postings/IDs, but this command accepts exactly one. This contradicts the command's cardinality contract and can mislead users or agents into attempting a batch; make both descriptions singular.

		"Move postings to Reply Later",
		"moved to Reply Later",
		"State-changing action. Confirm the exact posting IDs and obtain explicit user approval before moving each posting to Reply Later.",

internal/cmd/posting_actions.go:131

• The help text and machine-readable agent_notes describe multiple postings/IDs, but this command accepts exactly one. This contradicts the command's cardinality contract and can mislead users or agents into attempting a batch; make both descriptions singular.

		"Ignore postings",
		"ignored",
		"State-changing action. Confirm the exact posting IDs and obtain explicit user approval before ignoring each posting.",

---

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Suppressed comments (1)

internal/cmd/posting_actions.go:66

• --markdown still reaches the mutation, but writeOK(nil, ...) renders (no results) in that format and discards the summary (Writer.writeMarkdown treats nil as an empty slice). Thus a successful command such as hey trash 12345 --markdown reports no results instead of confirming the state change. Render the action summary for Markdown as well (or reject Markdown before runSingle).

	if writer.IsStyled() {
		fmt.Fprintln(cmd.OutOrStdout(), summary+".")
		return nil
	}

	return writeOK(nil, output.WithSummary(summary))

[code-monger-givenall]

I ran into one edge case while testing this against a mixed Imbox. hey box can return world/post records alongside email topics. Passing one of those numeric IDs to hey trash gets a successful response from the email trash endpoint, leaves the World post untouched, and currently prints that it moved to Trash.

I opened ivankuznetsov/hey-cli#1 against this branch. It requires callers to pass the posting kind and rejects world/post before authentication or any HTTP request. The full check and race suites pass, and a live guard check logged no request. No World content was changed.