mailmate 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d762c124b353823c34d4b87eb5748727ed2901a507f8bc67a0d74f22b1ab1350
-  data.tar.gz: c02381fd0d81be1e8793d85d3d838d40378bf2e99bc4d96f82405144171a73ed
+  metadata.gz: b986acdac48e1c98c6cc80ae0cc1686af00161a5de3cc17b0946ea09c43b17e1
+  data.tar.gz: 6867d4736f7c4118ea775c60b108a36dc76a5234312b20a36cb5c60070233712
 SHA512:
-  metadata.gz: cf2901c2df5341834cdcabeed160b33ea4d797c36cdaf24ee14ce1f48020f3a34ac8ff37f5c06a29f659ff486246838b575f73e5cf34e2fae0e986a64949650e
-  data.tar.gz: bf8f8e7fc3944a32b279a7ac8448def35020a430c38bad95f8f08d63e4e67d9eeef08ddb98f6775b0ba1b428fc6c20e93f27379833e73de28dd6425788158e07
+  metadata.gz: 45d6fc1c66f4549fdf14a899bdba83d1b7d0510b5a20e9469e75f44d92e8b5285bd4cba548a2524d9561831cd34ee64cf3fe3239829afe8b4dc19aa27e4cdbda
+  data.tar.gz: 7b88d5bb8668614368c969d0e6ba10f14a444594b4fe55fdf6dc14bf536e35b29c8845818bff44b65f880c4c5a724d551b245c23c4f3ee56d78247043da1af9c

data/README.md

@@ -60,6 +60,10 @@ mmopen 'message://%3Cabc%40example.com%3E'
 
 # Print the mid: URL instead of opening it (useful in pipelines)
 mmopen 183715 --print
+
+# Spawn the viewer in the background — MailMate stays where it is and
+# your keyboard focus is not stolen. Useful when scripting / cross-app.
+mmopen 183715 --background    # also: -g
 ```
 
 ### `mm-mailboxes` — list accounts and mailboxes
@@ -113,6 +117,11 @@ mm-modify 183715 archive --dry-run
 
 # Verify the new flags after acting
 mm-modify 183715 read --verify
+
+# As of 1.2.0, `--verify` works in `--dry-run` mode too — pair them as a
+# post-hoc state probe (run the action first, then re-run with --dry-run
+# --verify to confirm the change took effect).
+mm-modify 183715 read --dry-run --verify
 ```
 
 **Tip — batch your actions.** Doing all related changes in **one** `mm-modify` invocation is still worthwhile: one open/close cycle instead of two, and the chain runs deterministically without you having to think about ordering. Splitting is safe — `path_for` falls back to a filesystem glob if MailMate's `#source` index is briefly stale after a fast-move — just slower than batching.
@@ -148,54 +157,116 @@ The `mm` prefix is for tab completion: typing `mm<tab>` in a shell lists every c
 
 A few rough edges to be aware of:
 
-1. **Body search speed depends on MailMate's body-index coverage; everything else is fully index-driven.** Header-based filters (`f`/`t`/`c`/`s`/`a`/`T`/`K`/`d`) and every output column (subject, from, to, cc, date, tags, flags, …) read directly from MailMate's binary header indexes under `Database.noindex/Headers/`. No `.eml` is opened for those queries — performance is in the same ballpark as MailMate's own UI search (sub-second across large stores).
+1. **Non-move `mm-modify` actions briefly spawn a MailMate viewer window.** Same-account `move` actions use a fast path — a direct `.eml` rename on disk — so they're entirely silent. Everything else (`read`, `flag`, `tag`, `archive`, `junk`, `delete`, etc.) drives MailMate's URL handler: each invocation opens a message-viewer window via the `mid:` URL in the background, runs AppleScript key-binding selectors against it, then closes the window.
 
-   Body queries (`b <term>`, a bare term that falls through to `:message_or_body`, or explicit `m <term>` without `--headers-only`) check MailMate's `#unquoted` and `#quoted` body indexes. **Default behavior matches MailMate's UI body search** — only messages MailMate has body-indexed are searched. Sub-second on any archive size; the catch is that MailMate populates those indexes lazily (typically when you view or search messages in its UI), so a search may miss content in messages MailMate hasn't yet indexed. Coverage varies by user: a fresh install has a handful indexed; a heavy MailMate-search user has most.
+   **As of 1.2.0 this runs in the background.** MailMate is not brought to the foreground, your keyboard focus stays in whatever app you were using, and you can keep working — even during bulk loops. The viewer windows still appear briefly in MailMate's own window list before closing, but they don't take over your screen. The previous behavior (full-screen takeover, close-keystroke landing on the wrong window) is gone.
 
-   Pass `--all` to fall back to reading and parsing the `.eml` on disk for messages without an index record. This finds everything but takes tens of seconds to minutes on large archives. Use `--all` when you need an exhaustive answer; stick with the default when you want a predictable-fast one.
+   Two residual caveats:
+   - **Don't bring MailMate to the foreground during a run.** If you click into MailMate or Cmd-Tab to it while `mm-modify` is mid-flight, MailMate's responder chain shifts and subsequent perform-selectors may misbehave. Wait for the run to finish.
+   - **MailMate must be running.** See #3.
 
-2. **Non-move `mm-modify` actions still take over the UI.** Same-account `move` actions use a fast path — a direct `.eml` rename on disk — so they're silent and don't activate MailMate. Everything else (`read`, `flag`, `tag`, `archive`, `junk`, `delete`, etc.) still drives MailMate's UI: each invocation opens a message-viewer window via the `mid:` URL, runs AppleScript key-binding selectors against it, then closes the window. Two consequences:
-   - **Focus is stolen.** When the `mid:` URL fires, macOS brings MailMate forward and the spawned message-viewer window takes keyboard focus. Anything you were typing into another app goes to MailMate instead.
-   - **The close at the end can close the wrong window.** `mm-modify` ends by sending the standard "close window" keystroke. If focus has drifted (or another app's window has come forward in the meantime), that keystroke lands on **your** window — your editor, your browser tab — not MailMate's viewer.
+   The `--keep-window` flag leaves the spawned viewers open if you want to inspect them. Batch multiple actions into one `mm-modify` invocation when you can — they share a single open/close cycle (or skip it entirely for pure-move).
 
-   For one-off changes this is just annoying; for a loop of hundreds of messages it makes the machine unusable while it runs. Batch multiple actions into one `mm-modify` invocation when you can — they share a single open/close cycle (or skip it entirely for pure-move). The `--keep-window` flag avoids the close-keystroke entirely if you don't mind cleaning up viewers manually.
+2. **`eml-id` is machine-local; prefer `Message-ID:`.** The integer eml-id (also shown as MailMate's "Msg ID" column) is just the filename of the `.eml` on disk and differs on every install — copy/pasting an eml-id from your desktop to your laptop will refer to a different message (or none at all). For anything you want to keep, store the RFC `Message-ID:` header (which `mmmessage` prints) and pass that to the CLIs. The `mid:%3C<message-id>%3E` URL scheme works portably for the same reason.
 
-3. **`eml-id` is machine-local; prefer `Message-ID:`.** The integer eml-id (also shown as MailMate's "Msg ID" column) is just the filename of the `.eml` on disk and differs on every install — copy/pasting an eml-id from your desktop to your laptop will refer to a different message (or none at all). For anything you want to keep, store the RFC `Message-ID:` header (which `mmmessage` prints) and pass that to the CLIs. The `mid:%3C<message-id>%3E` URL scheme works portably for the same reason.
+3. **MailMate must be running.** Anything that goes through `mm-modify` requires MailMate open and unblocked by modal dialogs. `mm-send` likewise needs MailMate running — `emate mailto` opens a draft window in the running MailMate process, so without MailMate up there's nowhere for the draft to land (this is true with or without `--send-now`). Headless / unattended use isn't supported.
 
-4. **MailMate must be running.** Anything that goes through `mm-modify` requires MailMate open and unblocked by modal dialogs. `mm-send` likewise needs MailMate running — `emate mailto` opens a draft window in the running MailMate process, so without MailMate up there's nowhere for the draft to land (this is true with or without `--send-now`). Headless / unattended use isn't supported.
-
-5. **Single-account `mm-send` defaults.** `mm-send` passes flags straight through to `emate mailto`. If you have multiple identities configured in MailMate and don't pass `-f`, MailMate picks the default identity — there's no opinionated multi-account routing in the wrapper.
+4. **Single-account `mm-send` defaults.** `mm-send` passes flags straight through to `emate mailto`. If you have multiple identities configured in MailMate and don't pass `-f`, MailMate picks the default identity — there's no opinionated multi-account routing in the wrapper.
 
 ## Status
 
-Pre-1.0 (0.x). Breaking changes allowed without version bumps. See [`docs/roadmap/Mailmate gem.md`](../claude/people/docs/roadmap/Mailmate%20gem.md) in the sibling `people` repo for the design history and remaining work.
+1.2.0 — `mm-modify` no longer brings MailMate to the foreground and is roughly 8× faster on single-action invocations. Internally: the open call uses `open -g -a MailMate <url>` to keep MailMate in the background, and the fixed `--settle` sleeps are replaced by active waits (polling for the spawned viewer window to appear). `mmopen` gains a `--background` / `-g` flag for ad-hoc use. `mm-modify --verify` now works in `--dry-run` mode as a post-hoc state probe. `--settle` is preserved for backward compat; it now caps the active-wait timeout rather than fixing sleep duration.
+
+1.1.0 — `reverse_markdown` (and its transitive `nokogiri` dep) is now opt-in rather than auto-installed. Run `gem install reverse_markdown` if you want `mmmessage --markdown`; everything else is unchanged.
+
+1.0.0 — initial public release; API stable from this point. Breaking changes bump the major version going forward.
 
 ## Install
 
+### Requirements
+
+- **macOS** with **MailMate** installed (and running, for any command that drives the UI or sends mail).
+- **Ruby ≥ 3.0**.
+- No third-party CLI tools — the gem only shells out to macOS-bundled `plutil`, `osascript`, and `open`, plus MailMate's bundled `emate`.
+
 ```bash
 gem install mailmate
 ```
 
-Then bootstrap your config:
+Then optionally bootstrap your config (will happen automatically on first invocation of any command from an interactive shell if it hasn't been run before):
 
 ```bash
 mmdiscover
 ```
 
-`mmdiscover` reads MailMate's `Sources.plist` and `Identities.plist`, shows you the accounts and addresses it found, and offers to write `~/.config/mailmate/config.yml` from them. It also writes `~/.config/mailmate/bundle_loader.rb` for MailMate bundles.
+`mmdiscover` reads MailMate's `Sources.plist` and `Identities.plist`, shows you the accounts and addresses it found, and offers to write `~/.config/mailmate/config.yml` from them. It also writes `~/.config/mailmate/bundle_loader.rb` for MailMate bundles. Running it explicitly is only needed in non-TTY contexts (cron jobs, MCP servers) — there, the gem falls back to built-in defaults and warns once.
+
+### Optional: `mmmessage --markdown`
+
+**On the vast majority of Ruby setups (stock `arm64-darwin` or `x86_64-darwin` Ruby) this step is a no-op — nokogiri ships a precompiled binary, you can skip the rest of this section and move on.** Keep reading only if your `gem install` actually fails.
+
+`mmmessage --markdown` renders HTML-only message bodies as readable markdown. It needs the `reverse_markdown` gem, which has `nokogiri` as a transitive dependency:
+
+```bash
+gem install reverse_markdown
+```
+
+That single command pulls `nokogiri` in automatically — no separate `gem install nokogiri` step. This is kept out of the base install because nokogiri ships a native extension. On Ruby/platform combinations without a precompiled match nokogiri falls back to compiling from source — it vendors its own libxml2/libxslt, but it does need a C compiler, which on macOS means Xcode Command Line Tools (`xcode-select --install`). If `gem install reverse_markdown` fails, that's almost certainly the cause.
+
+If you never use `--markdown`, you never pay any of this. If you do invoke `--markdown` without the gem already being installed (default on most Ruby versions), `mmmessage` exits with a clear install hint.
 
 ### From source (development)
 
-If you're hacking on the gem itself, skip `gem install` and put the repo's `exe/` on your `PATH`:
+If you're hacking on the gem itself, skip `gem install` and put the repo's `exe/` on your `PATH`. Clone wherever you keep source repos, then prepend its `exe/` to `PATH` from your shell's rc file (`~/.zshrc`, `~/.bashrc`, etc.):
 
 ```bash
-git clone <this repo> ~/code/claude/mailmate
-echo 'export PATH="$HOME/code/claude/mailmate/exe:$PATH"' >> ~/.zshrc
-source ~/.zshrc
+git clone https://github.com/brianmd/mailmate.git
+cd mailmate
+
+# In your shell rc file, add (adjust the path to wherever you cloned):
+#   export PATH="/absolute/path/to/mailmate/exe:$PATH"
+# Then reload the shell (open a new tab, or `source` the rc file).
 ```
 
 Then `mmdiscover` as above.
 
+### MCP server
+
+The gem also ships an MCP server (`exe/mailmate-mcp`) that exposes the same surface to AI assistants as JSON-RPC tools: `search`, `message`, `modify`, `send`, `open`, `list_mailboxes`, `list_tags`, `resolve_id`. After `gem install mailmate`, `mailmate-mcp` is on your `PATH`.
+
+#### Claude Code (global, all projects)
+
+```bash
+claude mcp add --scope user mailmate "$(which mailmate-mcp)"
+```
+
+Or add manually to `~/.claude.json` under `"mcpServers"`:
+
+```json
+"mailmate": {
+  "type": "stdio",
+  "command": "/absolute/path/to/mailmate-mcp",
+  "args": [],
+  "env": {}
+}
+```
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mailmate": {
+      "command": "/absolute/path/to/mailmate-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after any change to server code or config.
+
 ## Commands
 
 | Command | What it does |

data/lib/mailmate/applescript_driver.rb

@@ -32,13 +32,20 @@ module Mailmate
     end
 
     # Open a URL in MailMate (used for `mid:` URLs to select a message).
+    # Uses `open -g -a MailMate` so the URL is dispatched to MailMate's URL
+    # handler without bringing MailMate to the foreground — keeping the
+    # user's keyboard focus where it was. The viewer window is still spawned
+    # for `mid:` URLs. The AppleScript-native alternative
+    # (`tell application "MailMate" to open location`) was tried but is
+    # synchronous and can hang on `mid:` URLs while MailMate processes the
+    # spawn — `open -g` is asynchronous and avoids the wait.
     def open_url(url)
       Mailmate::PlatformError.check_darwin!(component: "AppleScriptDriver") unless dry_run
       if dry_run
-        @output.puts "DRY: open -a MailMate #{url.inspect}"
+        @output.puts "DRY: open -g -a MailMate #{url.inspect}"
         return
       end
-      success = system("open", "-a", "MailMate", url)
+      success = system("/usr/bin/open", "-g", "-a", "MailMate", url)
       raise Error, "open command failed for #{url}" unless success
     end
 

data/lib/mailmate/cli/message.rb

@@ -137,8 +137,15 @@ module Mailmate
       #      long runs of `͏ ` in the output.
       #   3. Collapse 3+ consecutive blank lines into a single blank line.
       def html_to_markdown(html)
-        require "nokogiri"
-        require "reverse_markdown"
+        begin
+          require "nokogiri"
+          require "reverse_markdown"
+        rescue LoadError => e
+          warn "mmmessage --markdown needs the reverse_markdown gem (which pulls nokogiri)."
+          warn "Install it with:  gem install reverse_markdown"
+          warn "(underlying: #{e.message})"
+          exit 3
+        end
         doc = Nokogiri::HTML(html)
         doc.css("style, script").remove
         md = ReverseMarkdown.convert(doc.to_html)

data/lib/mailmate/cli/modify.rb

@@ -98,9 +98,9 @@ module Mailmate
               mute                          Toggle mute state
               delete                        Delete (move to trash)
           BANNER
-          o.on("--verify", "After running, print the message's current flags") { opts[:verify] = true }
+          o.on("--verify", "Print the message's current flags. Works with --dry-run as a post-hoc 'check state' probe (run the action first, then re-run with --dry-run --verify).") { opts[:verify] = true }
           o.on("--dry-run", "Print the actions; don't run") { opts[:dry_run] = true }
-          o.on("--settle SECONDS", Float, "Sleep between operations (default 3.5)") { |s| opts[:settle] = s }
+          o.on("--settle SECONDS", Float, "Timeout for waiting for MailMate's viewer window to spawn after open_url (default 3.5)") { |s| opts[:settle] = s }
           o.on("--keep-window", "Don't close the spawned message-viewer window") { opts[:keep_window] = true }
         end
         parser.parse!(argv)
@@ -258,9 +258,15 @@ module Mailmate
 
         windows_before = driver.window_ids
         driver.open_url(mid_url)
-        sleep(opts[:settle]) unless opts[:dry_run]
-        new_windows = driver.window_ids - windows_before
-
+        # Active wait: poll for the new viewer window instead of sleeping a
+        # fixed `settle`. Windows typically spawn in 200-500ms; the previous
+        # fixed 3.5s sleep was wildly conservative. `--settle` now controls
+        # the timeout for this wait rather than the sleep duration.
+        new_windows = opts[:dry_run] ? [] : wait_for_new_window(driver, windows_before, timeout: opts[:settle])
+
+        # Send each action's selector without sleeping between them.
+        # AppleEvents queue per-app and process in order, so a subsequent
+        # `close window id N` will execute only after `perform` is committed.
         actions.each do |name, selector, args|
           case selector
           when :ensure_flagged, :ensure_not_flagged
@@ -271,16 +277,19 @@ module Mailmate
               $stdout.puts "#{name}: already #{want ? "flagged" : "not flagged"} — no-op"
             else
               driver.perform("toggleFlag:")
-              sleep(opts[:settle]) unless opts[:dry_run]
             end
           else
             driver.perform(selector, *args)
-            sleep(opts[:settle]) unless opts[:dry_run]
           end
         end
 
-        if opts[:verify] && !opts[:dry_run]
-          sleep(opts[:settle])
+        # --verify is now permitted in --dry-run mode so callers can use
+        # `mm-modify <id> <any-action> --dry-run --verify` as a post-hoc
+        # "what's the current flag state?" probe after a separate action run.
+        # In non-dry-run mode, a short fixed wait gives MailMate time to
+        # flush #flags before we read it back; in dry-run no wait is needed.
+        if opts[:verify]
+          sleep(1) unless opts[:dry_run]
           $stdout.puts "Flags now: #{current_flags(eml_id).inspect}"
         end
 
@@ -289,6 +298,20 @@ module Mailmate
         end
       end
 
+      # Poll for a new MailMate window appearing in `driver.window_ids` that
+      # isn't in `windows_before`. Returns the set of new window IDs, or an
+      # empty array if `timeout` elapses without a new window appearing.
+      def wait_for_new_window(driver, windows_before, timeout:, poll: 0.05)
+        deadline = Time.now + timeout
+        loop do
+          diff = driver.window_ids - windows_before
+          return diff unless diff.empty?
+          break if Time.now >= deadline
+          sleep(poll)
+        end
+        []
+      end
+
       def current_flags(eml_id)
         # AppleScript actions write the index asynchronously — bust just the
         # #flags cache to pick up the latest values without throwing away

data/lib/mailmate/cli/open.rb

@@ -44,26 +44,30 @@ module Mailmate
           return 0
         end
 
-        system("/usr/bin/open", url)
+        cmd = ["/usr/bin/open"]
+        cmd << "-g" if opts[:background]
+        cmd << url
+        system(*cmd)
         $?.exitstatus
       end
 
       def parse_options(argv)
-        opts = { print_only: false }
+        opts = { print_only: false, background: false }
         OptionParser.new do |o|
-          o.banner = "Usage: mmopen <id> [--print]"
+          o.banner = "Usage: mmopen <id> [--print] [--background|-g]"
           o.separator ""
           o.separator "Open a MailMate message in MailMate's UI. <id> can be a local"
           o.separator "eml-id, an RFC Message-ID (with or without angle brackets), or"
           o.separator "a message://… or mid:… URL."
           o.on("--print", "Print the mid: URL instead of opening it (for piping)") { opts[:print_only] = true }
+          o.on("-g", "--background", "Open without bringing MailMate to the foreground") { opts[:background] = true }
         end.parse!(argv)
         opts
       end
 
       def usage_error(msg)
         warn "mmopen: #{msg}"
-        warn "Usage: mmopen <id> [--print]"
+        warn "Usage: mmopen <id> [--print] [--background|-g]"
         2
       end
     end

data/lib/mailmate/cli/search.rb

@@ -200,7 +200,7 @@ module Mailmate
           o.separator "    c <term>  cc contains"
           o.separator "    s <term>  subject contains"
           o.separator "    a <term>  any address header contains"
-          o.separator "    b <term>  body contains (slow — disables prefilter)"
+          o.separator "    b <term>  body contains (reads MailMate's body indexes; --all for un-indexed too)"
           o.separator "    m <term>  common headers OR body (same as bare term)"
           o.separator "    d <date>  received date: Nd|Nw|Nm|Ny (relative), or Y, Y-M, Y-M-D"
           o.separator "    T <tag>   tag / IMAP keyword contains  (K is a synonym)"

data/lib/mailmate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailmate
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailmate
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Brian Murphy-Dye
@@ -38,47 +38,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: reverse_markdown
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :runtime
+        version: '5.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: reverse_markdown
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '3.0'
 description: |
   mailmate is a Ruby library and CLI for working with MailMate's on-disk
   storage and AppleScript surface. It includes a smart-mailbox filter
@@ -166,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby toolkit for MailMate on macOS — search, read, modify, send, and smart-mailbox
   evaluation