mailmate 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b395d407ecab6e32e9e9d94da136031b0edd5cfa0302809721940a0dcefa2ba7
-  data.tar.gz: 80d7dc99046e899093e57422153e1b413f7688b5e1d080aa9ae7898778b92136
+  metadata.gz: 7d4531494a2e95ee32395c937a293085b055c6868327f9914702da62a7b039c6
+  data.tar.gz: 3251b2608c1ede51d85425c205a274993d51b58b9cace6f04eb53981a04345bb
 SHA512:
-  metadata.gz: 55136934383ab2be45fec5c5787242594a33208b6d71bffedf0b0ee4a0e1176f5876b4b09611c9716afcf34e6d7132a687e6c907a27f586b9a89f5ef7c9e4da1
-  data.tar.gz: 481da51efb264b36587908af1ab321d5f63c2174a3f2502be5722bb45600243433c210e30ad869737e531a8d4bffa97ffd371835265346c27dfef177d74ff24f
+  metadata.gz: 4a162097210b4578cc6118e70607258523cbf1b0a82e50a6c50b9b10a3a30bef05c5dd394ab50204920d7967bb9103073a457259f1e4ec570920daff09b1031e
+  data.tar.gz: 84fa48ec99f5e9df866899d4c805df8de7c1b427fd8ba868732baf79ad9c9b6c3c55cae92e00fec928ecc3c43fca7cd4572d8f2828f4a270494310dbdd7c97f7

data/README.md

@@ -60,6 +60,16 @@ This repo doubles as a Claude Code plugin marketplace. Inside Claude Code:
 
 The plugin's MCP server self-provisions on first launch — Ruby (if needed) and gem dependencies go into `~/.mailmate-mcp`; nothing touches your system Ruby, Homebrew, or shell profile. It runs the plugin's bundled source, so plugin updates take effect without waiting for a gem release. Uninstall: `/plugin uninstall mailmate`, then `rm -rf ~/.mailmate-mcp`.
 
+### Claude Cowork (desktop app)
+
+The same plugin works in Cowork on the macOS desktop app — verified end to end, including a from-scratch first run:
+
+1. In Cowork: **Customize → Plugins → + → Add marketplace** → `brianmd/mailmate`, then install **mailmate** from the Discover tab.
+2. Ask Claude about your mail. The first launch provisions the runtime inside Cowork's sandbox, which can take a minute or two, and Cowork will ask you to **allow the connector's commands and file access** — those approvals are the gate to your local mail store.
+3. The Claude desktop app must be running on the Mac where MailMate lives; `send`, `draft`, `modify`, and `open` additionally need the MailMate app running (as always).
+
+Cowork runs the connector through the desktop app's sandboxed bridge, so its provisioning leaves nothing on your real filesystem — not even `~/.mailmate-mcp` (only the Claude Code path creates that directory).
+
 ### One-line installer (any MCP client)
 
 ```bash
@@ -163,7 +173,7 @@ mmsearch 'd 2026-05'
 mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
 ```
 
-**Quicksearch syntax.** The search-string is a list of specs combined with **AND** (`or`/parens not yet supported). Wrap multi-word terms in `"double quotes"`.
+**Quicksearch syntax.** The search-string is a list of specs combined with **AND**; a bare `or` separates alternatives, and AND binds tighter (no parens — write `(f bob or f ann) s invoice` out as `f bob s invoice or f ann s invoice`). After `or`, a bare first term inherits the modifier in force: `d 2024 or 2025 or 2y`. Wrap multi-word terms in `"double quotes"` (also how to search for the literal word "or"). `mmsearch --help` is the canonical, always-current rendering of this table.
 
 | Modifier | Scope |
 |---|---|
@@ -175,9 +185,13 @@ mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
 | `a <term>` | Any address header contains. |
 | `b <term>` | Body (plain text) contains. |
 | `m <term>` | Common headers OR body. |
-| `d <date>` | Received date: `Y`, `Y-M`, `Y-M-D`, or relative `1d`/`2w`/`3m`/`1y`. |
+| `d <date>` | Received: `Nh` (rolling clock hours, `24h` = last 24 hours), `Nd`/`Nw`/`Nm`/`Ny` (N calendar units ending today — `1d` = today, `2d` = yesterday + today), or absolute `Y`, `Y-M`, `Y-M-D`. Slash dates are month-first American (`8/9/2026` = Aug 9); `--european` flips to day-first. Comparisons on absolute dates: `d >2026-08` (after), `d <2026-08` (before), also `>=`/`<=`. |
 | `T <tag>` | Tags / IMAP keywords (`K` is a synonym). |
-| `!<value>` | Negate, e.g. `f !smith` = From does NOT contain smith. |
+| `is:<state>` | Message state: `is:unread`, `is:read`, `is:flagged`, `is:replied`, `is:draft` (Gmail synonyms `starred`/`answered` work; `-is:unread` negates). |
+| `has:attachment` | Root MIME type is `multipart/mixed` — the standard attachment layout. |
+| `!<value>` | Negate, e.g. `f !smith` = From does NOT contain smith; works on dates too (`d !3d` = more than 3 days ago). |
+
+Dates match on the **display-zone day** — the same day the `date`/`time` output columns show. An impossible date term or combination (`d 2026-02-31`, `d >2026 d <2025`) is a usage error, not a silent empty result. Familiar foreign `key:value` tokens (`from:bob`, `date:today`, `after:2026-08-01`, `older_than:2w`) are auto-translated to quicksearch with each rewrite announced on stderr; unrecognized keys (`is:unread`) are searched as literal text, and an empty result says so.
 
 The `--mailbox` argument accepts an account, an `account/path`, a bare mailbox name matched across accounts, or a **smart-mailbox name** (e.g. `Newsletters`, `Receipts`, `Priority`) whose filter is ANDed into the search.
 
@@ -348,22 +362,28 @@ EOF
 mm-send -t friend@example.com -s "Photos" /path/to/photo1.jpg /path/to/photo2.jpg <<<"See attached."
 ```
 
-#### Replies and threading
+#### Replies, forwards, and threading
 
-MailMate auto-generates the outgoing `Message-ID` for every send — never the caller's job. `In-Reply-To` and `References` are pure pass-through: whatever you set via `--header` ships verbatim, and **what you don't set is absent**. A reply with a `Re: …` subject but no threading headers shows up as a brand-new conversation in modern mail clients (they thread on headers, not subjects).
+**A `Re:` subject does not thread.** Modern clients thread on headers, so a reply without `In-Reply-To` / `References` shows up in the recipient's client as a brand-new conversation — and nothing in your own view reveals it. MailMate generates the outgoing `Message-ID` itself; that part is never your job.
 
-To make a reply land in-thread, pass both headers:
+Point `mm-send` at the parent and it derives the rest:
 
 ```bash
-mm-send -f you@x -t them@y -s "Re: foo" \
-  --header "In-Reply-To: <parent-message-id@domain>" \
-  --header "References: <root-mid> <parent-mid>" \
-  --send-now <<<"body"
+# Reply — derives In-Reply-To, References, recipient and "Re:" subject.
+mm-send -f you@x --reply-to "<parent-message-id@domain>" --send-now <<<"body"
+
+# Reply-all: adds the other recipients, minus your own identities.
+mm-send -f you@x --reply-all-to 12345 --send-now <<<"body"
+
+# Forward: "Fwd:" subject and the forwarded block; you supply the recipient.
+mm-send -f you@x --forward 12345 -t someone@example.com <<<"FYI"
 ```
 
-Construct `References` as the source message's `References` header (if any) with the source's `Message-ID` appended. If the source is itself a thread root with no `References`, just use its `Message-ID` alone.
+The parent is an eml-id or an RFC Message-ID. **Fields you pass explicitly win; fields you omit follow normal reply rules**, and overriding a visible field never drops the threading headers. `--no-quote` suppresses the quoted original. `--print-prefill` prints the derived fields as JSON and sends nothing — the hook for other tools that fill their own compose form.
+
+Hand-assembly via `--header` still works and is the escape hatch when the parent isn't in MailMate's index. The `mailmate-mcp` `send` / `draft` tools take `in_reply_to` and `references` directly.
 
-The same passthrough applies to the `mailmate-mcp` `send` tool — see the `from`, `in_reply_to`, and `references` fields.
+> **Canonical reference:** [docs/Composing and threading.md](docs/Composing%20and%20threading.md) — the References chain, the merge rule, header safety, identity selection. Everything above summarizes it; when the two disagree, that file is right.
 
 ### `mm-draft` — compose without sending
 
@@ -373,10 +393,9 @@ The same passthrough applies to the `mailmate-mcp` `send` tool — see the `from
 # Opens a draft in MailMate; never sends.
 echo "Quick **markdown** body." | mm-draft -t friend@example.com -s "Hello"
 
-# Threading headers and attachments work exactly as in mm-send.
-mm-draft -f you@x -t them@y -s "Re: foo" \
-  --header "In-Reply-To: <parent-message-id@domain>" \
-  --header "References: <root-mid> <parent-mid>" <<<"body"
+# Reply/forward derivation, threading headers and attachments all work
+# exactly as in mm-send — the only difference is that this cannot send.
+mm-draft -f you@x --reply-to "<parent-message-id@domain>" <<<"body"
 
 # Passing --send-now is refused (exit 2):
 mm-draft -t friend@example.com -s "nope" --send-now <<<"body"
@@ -414,6 +433,14 @@ A few rough edges to be aware of:
 
 ## Status
 
+1.8.0 — Reply derivation, and message-state specs.
+
+**Composing:** replies and forwards are now derived from the parent instead of hand-assembled. `mm-send` / `mm-draft` gain `--reply-to <id>`, `--reply-all-to <id>`, `--forward <id>` (eml-id or Message-ID), which compute `In-Reply-To`, the full `References` chain, recipients and the `Re:`/`Fwd:` subject, plus `--no-quote` and `--print-prefill` (derived fields as JSON, sends nothing). The MCP `send`/`draft` tools take the same `reply_to` / `reply_all_to` / `forward` arguments. Explicitly-passed fields win over derived ones, and overriding a visible field never drops the threading headers. A forward deliberately does *not* thread into the original conversation. The chain is built in exactly one place (`Mailmate::ReplyPrefill`), and `--header` values now route through one sanitizer (`Mailmate::HeaderValue`) — previously the MCP's own argv builder lacked the CR/LF defense that stops a parent `Message-ID` smuggling extra headers. All of it is documented once in [docs/Composing and threading.md](docs/Composing%20and%20threading.md), which the README, `--help` preambles and MCP instructions now point at rather than restate. Every `exe/` command answers `--version`, so consumers can check the installed version instead of probing for a flag (the CLIs pass unknown flags through to `emate`, which makes flag-probing unsafe). The gemspec finally carries `homepage` and `metadata`, so the rubygems page links back to the source.
+
+**Search:** `is:unread`, `is:read`, `is:flagged`, `is:replied`, `is:draft`, and `has:attachment` are first-class quicksearch (the MailMate app has no state vocabulary in its toolbar search — its `A` modifier searches attachment *filenames* — so the familiar Gmail spellings were adopted, including the `starred`/`answered` synonyms and `-is:unread` negation). Flag states read the `#flags` index; attachment presence reads the indexed root `content-type` (`multipart/mixed`). An unknown state value (`is:snoozed`) is a usage error naming the known states, not a silent empty result.
+
+1.7.0 — Search-language release, driven by a study of how LLM agents actually misuse `mmsearch`. The quicksearch syntax reference is now single-sourced (`Mailmate::SearchSyntax`) into both `mmsearch --help` and the MCP `search` description, so the two can no longer drift. Foreign `key:value` dialects (Gmail/Outlook/Spotlight — `from:bob`, `date:today`, `after:2026-08-01`, `older_than:2w`) auto-translate to their exact quicksearch equivalent, loudly: each rewrite is announced on stderr, and untranslatable keys are flagged when a search returns nothing. The language itself grew: boolean `or` (AND binds tighter, no parens; a bare term after `or` inherits the modifier in force), date comparisons (`d >2026-08`, `d <2026-08`, `>=`/`<=`), rolling hour windows (`d 24h`), and American slash dates (`d 8/9/2026`; `--european` for day-first). Two semantic fixes: `d 1d` now means *today* (N calendar units ending today, matching the MailMate app; the old today−N made it span two days), and date matching converts to the display zone — the same conversion the `date`/`time` columns use — so the day a search matches is always the day shown (sender-local index days previously leaked "tomorrow's" mail into `d 1d`). Impossible date terms and combinations (`d 0d`, `d 2026-02-31`, `d >2026 d <2025`) are usage errors instead of silent empty results.
+
 1.6.0 — Distribution release. The repo is now a Claude Code plugin marketplace (`/plugin marketplace add brianmd/mailmate`), and a one-line `install.sh` provisions the MCP server into an isolated `~/.mailmate-mcp` — including a private relocatable Ruby when no Ruby ≥ 3.0 is present — without touching system Ruby, Homebrew, or shell profiles. Every MCP tool now carries a `title` plus `readOnlyHint`/`destructiveHint` annotations (Claude clients use these for permission behavior; Anthropic's directory review requires them), and the README gains a formal Privacy Policy section. No changes to CLI or library behavior.
 
 1.5.0 — Reliability and batch-verification for `mm-modify`, plus search/read speedups. `mm-modify` gains a no-window retry guard (a `mid:` open that spawns no viewer would otherwise act on the wrong message) and opt-in effect verification: `--check` confirms a flag/tag/read action landed on the target eml-id by re-reading `#flags` (the only way to catch a duplicate-Message-ID misland). Because MailMate flushes `#flags` to disk ~5 s after acting, a new **`mm-verify`** command plus `mm-modify --emit-check` decouple acting from confirming — collect JSON check-tickets across a batch and verify them all in one flush-wait instead of paying the latency per message. `mmsearch` is substantially faster (compiled date ranges, cheapest-spec-first ordering, bulk-unpack index reader, inverted body search) with bit-identical output; the persistent MCP server now invalidates index caches on disk change. `mmmessage` shows user tags and lazy-loads the `mail` gem (`--raw`/`--mailmate` skip it). MCP: `message` gains `markdown`, `modify` gains a `check` mode (`none｜inline｜defer`), and a new `verify` tool batch-confirms deferred tickets.

data/docs/Composing and threading.md

@@ -0,0 +1,69 @@
+# Composing and threading
+
+**This is the canonical description of how mailmate sends mail.** `mm-send`, `mm-draft`, the MCP `send` / `draft` tools, and every downstream consumer behave as described here. Other surfaces (the README, `--help` preambles, MCP tool descriptions) carry deliberately-minimal summaries and point here — they should never restate a rule in their own words, because a second independent statement of the same fact is what drifts.
+
+## The two commands, and why there are exactly two
+
+`mm-send` and `mm-draft` are thin wrappers around MailMate's bundled `emate mailto`, with `--markup markdown` enforced. The body is read from stdin; every other flag passes through to `emate`.
+
+They differ on exactly one axis: **send-ability.** `mm-send` can send (with `--send-now`); `mm-draft` refuses `--send-now` with a nonzero exit and therefore *cannot*, no matter what flags it is handed. That refusal is the entire point — a "compose this but don't send it" instruction can't be silently defeated by a caller (human or model) adding a flag.
+
+That axis, and only that axis, earns a command name. It has to be a name because a name is a guarantee you can reason about before running anything; a flag can be forgotten, mis-copied, or argued away. Every *other* variation — replying, replying-all, forwarding — is a flag, because none of them is safety-critical and because command names multiply where flags add. Cross-producting "threading mode" with "send-ability" would mean `mm-reply`, `mm-reply-all`, `mm-reply-draft`, `mm-reply-all-draft`, and then double again the day forwarding lands. The flag form covers the same matrix with two commands, permanently.
+
+## Threading
+
+**MailMate generates the outgoing `Message-ID` itself.** Never construct or pass one.
+
+`In-Reply-To` and `References` are **pure pass-through**: whatever you set ships verbatim, and *what you don't set is absent*. This is the rule that surprises people, so state it plainly: **a `Re:` subject does not thread.** Modern mail clients thread on headers. A reply with a perfect `Re: …` subject and no threading headers appears in the recipient's client as a brand-new conversation, and nothing about the sender's own view reveals this — the failure is invisible from where you're standing.
+
+The chain is built one way:
+
+> `References` = the parent's own `References` header (if any) + the parent's `Message-ID` appended.
+> If the parent is itself a thread root with no `References`, use its `Message-ID` alone.
+> `In-Reply-To` = the parent's `Message-ID`.
+
+Message-IDs may be written with or without angle brackets on input; they are normalized to the bracketed RFC 5322 form on the wire.
+
+### Deriving it, rather than assembling it
+
+Getting the chain wrong produces a message that looks correct everywhere you can see it and silently fails to thread. So prefer having it derived from the parent rather than assembling it by hand:
+
+- **CLI:** `--reply-to <id>` / `--reply-all-to <id>` / `--forward <id>` on either command take the parent's eml-id or RFC Message-ID and derive the threading headers, recipients, and subject from it. `--no-quote` drops the quoted original.
+- **MCP:** the `send` / `draft` tools take `reply_to` / `reply_all_to` / `forward` (plus `quote: false`), which hand the id to the same CLI. They also still accept `in_reply_to` / `references` directly — if you use those, set **both**.
+- **Library:** `Mailmate::ReplyPrefill.build(id, mode:)` returns the derived fields without sending anything, and `mm-send --reply-to <id> --print-prefill` is the same thing as JSON for non-Ruby callers. That's the hook for a tool filling its own compose form.
+
+Because `forward` derives no recipient, it is the one mode that still requires `to`.
+
+Hand-assembly via `--header` remains available and is the escape hatch when the parent isn't in MailMate's index:
+
+```sh
+mm-send -f you@x -t them@y -s "Re: foo" \
+  --header "In-Reply-To: <parent-message-id@domain>" \
+  --header "References: <root-mid> <parent-mid>" \
+  --send-now <<<"body"
+```
+
+### The merge rule
+
+When a parent is supplied, **explicitly-passed fields always win; omitted fields follow normal reply rules** (parent's sender becomes the recipient, subject becomes `Re: <original>`, the quoted original seeds the body, reply-all additionally carries the other recipients minus your own identities).
+
+This rule is uniform across every surface that composes from a parent — the CLI flags above and markdownr's compose popup — so a caller who learns it once can predict all of them. Overriding a visible field never drops the threading headers.
+
+## Header safety
+
+`--header` values ship verbatim into the message. Any value derived from *another message* is therefore untrusted input: a `Message-ID` or `References` carrying `\r\n` could otherwise smuggle additional RFC 5322 headers into the outgoing message. All header values are collapsed to a single line before injection. If you add a new path that pushes a `--header`, route it through the same sanitization rather than formatting the flag yourself.
+
+## Identity
+
+`-f <address>` picks which configured MailMate identity sends. Without it, MailMate uses its default identity — which, when the recipient is one of your own addresses, may not be the one you expect. Set it explicitly. `mmdiscover` lists the available addresses and writes them to `~/.config/mailmate/config.yml`, where `Mailmate::Identity` reads them.
+
+## Prerequisites for markdown bodies
+
+Bodies are markdown; MailMate renders them to HTML on the way out. For that to reach recipients, MailMate → Preferences → Composer must have **Preview: Display = Always** and **Replying/Forwarding HTML = Always embed**. These are global, one-time settings; without them recipients get plain text.
+
+## Who points here
+
+- `README.md` § `mm-send` / `mm-draft` — short usage orientation.
+- `mm-send --help` / `mm-draft --help` preambles — the minimal operational recipe.
+- The MCP server's `initialize` instructions and `send` / `draft` tool descriptions.
+- markdownr's `.claude/instructions/nested/email.md` (compose popup + routes) and the private `email` skill (sender/signature doctrine). Those own their own layers — markdownr's UI surface and personal doctrine respectively — and defer to this file for anything below them.

data/exe/mailmate-mcp

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/mcp"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mailmate-mcp")
+
 exit Mailmate::MCP.run

data/exe/mm-draft

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/draft"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-draft")
+
 exit Mailmate::CLI::Draft.run(ARGV)

data/exe/mm-mailboxes

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/mailboxes"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-mailboxes")
+
 exit Mailmate::CLI::Mailboxes.run(ARGV)

data/exe/mm-modify

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/modify"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-modify")
+
 exit Mailmate::CLI::Modify.run(ARGV)

data/exe/mm-send

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/send"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-send")
+
 exit Mailmate::CLI::Send.run(ARGV)

data/exe/mm-verify

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/verify"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mm-verify")
+
 exit Mailmate::CLI::Verify.run(ARGV)

data/exe/mmdiscover

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/discover"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmdiscover")
+
 exit Mailmate::CLI::Discover.run(ARGV)

data/exe/mmmessage

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/message"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmmessage")
+
 exit Mailmate::CLI::Message.run(ARGV)

data/exe/mmopen

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/open"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmopen")
+
 exit Mailmate::CLI::Open.run(ARGV)

data/exe/mmsearch

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/search"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmsearch")
+
 exit Mailmate::CLI::Search.run(ARGV)

data/exe/mmtags

@@ -5,4 +5,8 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "mailmate"
 require "mailmate/cli/tags"
 
+require "mailmate/cli/version_flag"
+
+Mailmate::CLI::VersionFlag.handle!(ARGV, "mmtags")
+
 exit Mailmate::CLI::Tags.run(ARGV)