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.

[bscott]

Closing in favor of #18, which carries forward this PR's unique contribution.

This PR bundled three features. Two of them landed independently in the meantime:

• PM_CLI_BRIDGE_PASSWORD (feat: read bridge password from environment variable #8) → merged via feat(config): read Bridge password from PM_CLI_BRIDGE_PASSWORD env var #14
• mail list server-side filtering, envelope fields, field selection (feat: server-side filtering, field selection, and additional envelope fields for mail list #9) → merged via feat(mail list): server-side unread/flagged filtering, envelope fields, and field selection #16

Those overlapped this branch across five files (cli.go, mail.go, config.go, client.go, types.go). #16's version was the stronger implementation — it extracts listSeqSet/paginateSeqNums/newMessageSummary rather than inlining the logic, and ships ~500 lines of tests including an in-memory IMAP server.

Two things this PR did better were ported into #18 rather than lost:

• help.go was updated here and not in feat(mail list): server-side unread/flagged filtering, envelope fields, and field selection #16. Picked up in fix: repair build after #14/#15/#16 and guard COPYUID check #17 for the list flags, and feat(mail): add batch subcommand, docs, and CHANGELOG (0.2.6) #18 adds the mail batch entry.
• docs/commands.md documented the env var and new list flags; feat(mail): add batch subcommand, docs, and CHANGELOG (0.2.6) #18 takes that file whole.

Two defects from this branch are also fixed in #18: the --help-json batch examples used \" inside raw string literals (emitting literal backslashes into the agent schema), and docs/commands.md listed seq as a --fields name where the shipped implementation uses seq_num.

Note #12 was an identical duplicate of this branch (same head SHA b38b298) and was already closed.

One item from this PR that did not carry over, worth a follow-up: Search() was updated here to populate from_address/to/message_id/in_reply_to. #16 only changed ListMessages, so mail list and mail search currently return different JSON shapes.