feat(mail): env password, list enhancements, and batch command (0.2.6)

[bscott]

Implements three feature requests (#8, #9, #10) for automated/headless email workflows. Reimplemented from scratch (issue branches used only as reference); builds clean, go vet clean, all tests pass.

#8 — Bridge password from env var

• GetPassword() checks PM_CLI_BRIDGE_PASSWORD before the system keyring → enables headless/CI use with no secret service.
• Interactive use unchanged (env var only consulted when set & non-empty). Env-takes-precedence is documented.

#9 — mail list enhancements

• Fixes the --unread undercount: --unread/--flagged now use server-side IMAP SEARCH, so results honor --limit instead of being thinned by client-side filtering. The two can be combined.
• Adds from_address, to, message_id, in_reply_to to list/search JSON (all already in the ENVELOPE — zero extra fetch). Previously from dropped the address whenever a display name was present.
• Adds --fields (project onto named JSON fields) and --compact (bare array). JSON-only; text output unchanged.
• ListMessages now takes a ListOptions struct; all callers updated.

#10 — mail batch

• New mail batch subcommand runs a JSON array of ops (label, unlabel, archive, move, flag, delete) over a single IMAP session.
• All ops validated before connecting; names with IMAP special chars rejected — including the source mailbox (closed a gap vs. the original proposal); 10MB input cap; errors sanitized via safetext.
• --stop-on-error halts after first failure; per-op results + totals reported.

Tests & docs

• New tests: env-var precedence, field parsing/projection, batch validation (incl. CRLF/wildcard rejection) and decode.
• docs/commands.md, new docs/batch-format.md, and the --help-json schema updated. Version bumped to 0.2.6.

⚠️ Sequencing note

mail batch routes through CopyMessages/DeleteMessages/MoveMessages. Its per-op success reporting is only fully accurate once #11 (silent no-op detection in STORE/COPY) lands — and #11's COPY check still needs the UIDPLUS/COPYUID verification flagged in that review. Recommend landing #11 before relying on batch's label/unlabel results.

---

Supersedes #12 (closed automatically when its branch was renamed to v0.2.6).

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[Juan-de-Costa-Rica]

Two things in mail batch we ran into while running this branch in production against Proton Bridge.

1. permanent is not wired through on delete. batchOp has no permanent field, and executeBatchOp calls DeleteMessages(mailbox, op.UIDs, false). Since mail delete --permanent exists as a flag outside batch, the same delete behaves differently depending on which path issues it. Our pipeline had been sending {"op":"delete","permanent":true} for some time believing those were permanent, while the messages were going to Trash.

2. That was silent, because unknown keys are dropped. decodeBatchOps uses a plain json.Unmarshal, so anything not on the struct is discarded without error:

$ echo '[{"op":"label","uids":["uid:99999999"],"label":"UNSORTED","bogus_unknown_key":true,"permanent":true}]' | pm-cli mail batch --json
{"results":[{"op":"label","success":false,"error":"no messages matched the given ID(s) in INBOX"}],"total":1,"succeeded":0,"failed":1}

Both keys accepted, neither honored. A json.Decoder with DisallowUnknownFields() would turn that into a parse-time error before any IMAP command runs, which fits the validate-everything-up-front approach already in MailBatchCmd.Run.

3. Minor: batchResult carries op but not the uids it answers for, so a caller pairing results back to inputs has to rely on array position. Echoing the uids would make that unambiguous.

Happy to send a PR for any of these if useful.