feat(mail): add message modify and trash shortcuts

[bubbmon233]

Generated by the harness-coding skill.

• Branch: feat/c8c09bb
• Target: main

Sprints

ID	Title	Status	Commit
S1	Add mail message modify/trash shortcuts	passed	2eb534d

---

This MR was created autonomously. Quality gates were enforced by the repo's own pre-commit hooks.

Summary by CodeRabbit

• New Features
  • Added mail +message-modify for add/remove label and/or move-to-folder actions with 20-message batching and --dry-run planning.
  • Added mail +message-trash for soft-deletes in 20-message batches, requiring --yes.
• Bug Fixes
  • Updated “mark as read” follow-up examples to use +message-modify to remove UNREAD.
  • Strengthened validation to reject whitespace/control characters and prevent conflicting label operations (including adding trash).
• Documentation
  • Refreshed mail workflow guidance and command references to prefer +message-modify / +message-trash.
• Tests
  • Added extensive shortcut behavior tests and refreshed E2E coverage and OAuth scope expectations.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Two new mail CLI shortcuts are added: +message-modify for label/read/folder changes and +message-trash for soft deletion. Shared normalization and batching helpers support both commands, which are registered, tested, and documented.

Changes

Mail message management shortcuts

Layer / File(s)	Summary
Shared normalization and summary helpers shortcuts/mail/message_manage_helpers.go	Defines system label/folder mappings, message ID and label/folder normalization, batch chunking, request body construction, validation plans, runtime validation, and summary emission.
+message-modify implementation shortcuts/mail/mail_message_modify.go	Adds the shortcut definition plus validation, dry-run planning, execution batching, and input normalization for label and folder changes.
+message-trash implementation shortcuts/mail/mail_message_trash.go	Adds the shortcut definition plus validation, dry-run planning, and batched soft-delete execution.
Shortcut registration and hint update shortcuts/mail/shortcuts.go, shortcuts/mail/mail_shortcut_test.go, shortcuts/mail/helpers.go	Registers both shortcuts, updates the test token scope, and changes the post-send read hint to use +message-modify.
Shortcut tests shortcuts/mail/mail_message_manage_test.go	Covers normalization, metadata, validation, batching, dry-run output, confirmation handling, and aggregated partial-failure behavior for both shortcuts.
Docs and coverage updates skills/lark-mail/references/lark-mail-message-modify.md, skills/lark-mail/references/lark-mail-message-trash.md, skills/lark-mail/SKILL.md, skill-template/domains/mail.md, skills/lark-mail/references/lark-mail-*.md, tests/cli_e2e/mail/coverage.md	Adds shortcut reference docs, updates workflow and quick-reference guidance, replaces mark-as-read examples, and refreshes Mail CLI E2E coverage metrics.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested labels: feature

Suggested reviewers: chanthuang, infeng, YangJunzhou-01

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is largely incomplete and does not follow the required Summary, Changes, Test Plan, and Related Issues template.	Add the required template sections with a brief summary, key changes, test verification, and related issues or None.
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.13% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding mail message modify and trash shortcuts.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@bb71d4ade43aefe0a1ef5f8a755229199df4a0e2

🧩 Skill update

npx skills add bubbmon233/cli#feat/c8c09bb -y -g

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/mail/mail_message_manage_test.go`:
- Around line 64-66: The validation tests around normalizeMessageManageIDs and
the related message-manage cases only prove that an error occurred, so they can
miss incorrect problem typing or wrong field names. Update the assertions to
inspect errs.ProblemOf for the expected typed validation problem fields
(category, subtype, and param), and use errors.As against *errs.ValidationError
when verifying Param for --message-ids, --add-label-ids, and --add-folder. Keep
the checks anchored to normalizeMessageManageIDs and the affected test cases so
they validate the exact error shape, not just the message text.

In `@shortcuts/mail/mail_message_modify.go`:
- Around line 85-99: The batch modify flow in executeMessageModify currently
records per-message failures in summary but always returns nil, so a run with
only failures still exits successfully. After emitMessageManageSummary, check
whether summary.SuccessMessageIDs is empty and summary.FailedMessageIDs is
non-empty, and in that case return a typed/non-zero error instead of nil; apply
the same fix to executeMessageTrash since it has the same pattern.

In `@shortcuts/mail/message_manage_helpers.go`:
- Around line 183-208: `validateCustomMessageManageLabels` is missing the
label-read scope preflight, and `MailMessageModify` does not declare the
folder-read scope needed by the `--add-folder` path. Update
`validateCustomMessageManageLabels` to call `validateLabelReadScope(rt)` before
the `CallAPITyped` label checks, and adjust `MailMessageModify` so
`mail:user_mailbox.folder:read` is included conditionally when folder validation
is used, keeping the existing `validateCustomMessageManageFolder` flow and its
`mailboxPath` lookups intact.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6bc67455-485e-41e4-a8ec-9dbd4e1f38bc

📥 Commits

Reviewing files that changed from the base of the PR and between 3f9ace8 and 2eb534d.

📒 Files selected for processing (15)

• shortcuts/mail/helpers.go
• shortcuts/mail/mail_message_manage_test.go
• shortcuts/mail/mail_message_modify.go
• shortcuts/mail/mail_message_trash.go
• shortcuts/mail/mail_shortcut_test.go
• shortcuts/mail/message_manage_helpers.go
• shortcuts/mail/shortcuts.go
• skill-template/domains/mail.md
• skills/lark-mail/SKILL.md
• skills/lark-mail/references/lark-mail-forward.md
• skills/lark-mail/references/lark-mail-message-modify.md
• skills/lark-mail/references/lark-mail-message-trash.md
• skills/lark-mail/references/lark-mail-reply-all.md
• skills/lark-mail/references/lark-mail-reply.md
• tests/cli_e2e/mail/coverage.md

[bubbmon233]

🤖 AI Review | CR 汇总 | 有风险（2 个 P2）

增量审查：基于之前 3 条已 resolved 的 review thread，本次新增 2 条 P2 评论。主要风险是 +message-modify 的 folder read scope 被无条件 pre-flight，以及新提示命令没有复用已有 shell quoting。