mailmate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 79154ae28a8d2c2aaf816e6719da7ee549f59db9a9425c19fd14971fa17c2752
+  data.tar.gz: 3ebd8963699820c5a10a777ea1d0013108301f268bd4a59939e5a9cf54649747
+SHA512:
+  metadata.gz: 0f709dfccd86d6abb7e82ec1da45fc7f84745a6967f7e9fdaa90b1b90ae015671271102016f03aea80262ce8ff6ca109d7d8b5365d012c95ab4cc57c102e43ed
+  data.tar.gz: 1da1debaba2cb1260b8b033efb742ec45bca0b37c5b041f87492367bbf0f9efda29cf117723cd1bf027d7b84ccfd4947f8dc84d545759b36ad8f346b0eb4121c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Murphy-Dye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# mailmate
+
+Ruby toolkit for [MailMate](https://freron.com) on macOS — a smart-mailbox filter engine, on-disk index readers, and CLI tools (`mmsearch`, `mmmessage`, `mm-modify`, `mm-send`, `mmdiscover`) for searching, reading, modifying, and sending mail.
+
+**Requires macOS with MailMate installed.** The library code (filter parser, evaluator) works anywhere, but the integration with MailMate itself — AppleScript, on-disk index reads, the `emate` binary — is macOS-only by way of MailMate being macOS-only.
+
+## Example usage
+
+### `mmsearch` — find messages
+
+```bash
+# Default: today's mail, all mailboxes
+mmsearch
+
+# From "Medium" in the last 7 days
+mmsearch 'f medium d 7d'
+
+# Subject contains "rent due", not the word "draft"
+mmsearch 's "rent due" !draft'
+
+# Received in May 2026
+mmsearch 'd 2026-05'
+
+# Custom columns + cap results + raw CSV (no padding)
+mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
+```
+
+### `mmmessage` — read one message
+
+```bash
+# By local eml-id (the integer Msg ID column in MailMate)
+mmmessage 183715
+
+# By portable Message-ID (quote it — the angle brackets are shell metacharacters)
+mmmessage '<CA+abc123@mail.example.com>'
+
+# Raw .eml bytes (e.g. to pipe into `mail` parsers)
+mmmessage 183715 --raw
+
+# Body only, no headers block
+mmmessage 183715 --text-only
+```
+
+### `mm-modify` — change message state
+
+```bash
+# Mark a message read, flag it, and archive it — one open/wait cycle
+mm-modify 183715 read flag archive
+
+# Add a tag
+mm-modify 183715 tag urgent
+
+# Dry-run first
+mm-modify 183715 archive --dry-run
+
+# Verify the new flags after acting
+mm-modify 183715 read --verify
+```
+
+### `mm-send` — send mail
+
+`mm-send` is a thin wrapper around MailMate's bundled `emate mailto`, with `--markup markdown` enforced. The body is read from stdin.
+
+```bash
+# One-liner
+echo "Quick **markdown** body." | mm-send -t friend@example.com -s "Hello"
+
+# Heredoc with cc + send-now
+mm-send -t friend@example.com -c cc@example.com -s "Status update" --send-now <<'EOF'
+## Update
+
+- shipped the thing
+- on to the next
+EOF
+
+# Attach files (positional args after options)
+mm-send -t friend@example.com -s "Photos" /path/to/photo1.jpg /path/to/photo2.jpg <<<"See attached."
+```
+
+### Why the names
+
+The `mm` prefix is for tab completion: typing `mm<tab>` in a shell lists every command in the toolkit. The dash matters:
+
+- **`mm<name>`** (no dash) — **read** operations. `mmsearch`, `mmmessage`, `mmdiscover` only observe MailMate's on-disk state.
+- **`mm-<name>`** (with dash) — **write** operations. `mm-modify`, `mm-send` change state (or send mail). Typing `mm-<tab>` filters to just the write commands so you can see at a glance what mutates.
+
+## Limitations
+
+A few rough edges to be aware of:
+
+1. **Search is slow against this wrapper, even though MailMate itself is fast.** MailMate has a fantastic search engine — its native quicksearch is near-instant even against large stores — but `mmsearch` doesn't yet route through it. The current implementation uses index prefilters plus direct `.eml` walks, which works but is orders of magnitude slower than MailMate's own UI search, and **painfully** slow once a body-text term (`b <term>`, a bare term that falls through to body matching, or a `--no-headers-only` query) disables the prefilter. Prefer narrowing with `f`/`t`/`s`/`d` first, and use `--headers-only` when you don't need the body matched. Finding a way to drive MailMate's native engine from the outside is open work.
+
+2. **Bulk `mm-modify` takes over the whole computer, not just MailMate.** Each invocation opens a message-viewer window via the `mid:` URL, runs AppleScript key-binding selectors against it, then closes the window. Two things follow from that:
+   - **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 the next app's window has come forward in the meantime), that keystroke lands on **your** window — your editor, your browser tab — not MailMate's viewer.
+
+   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. The `--keep-window` flag avoids the close-keystroke entirely if you don't mind cleaning up viewers manually.
+
+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.
+
+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.
+
+## 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.
+
+## Install
+
+For development (no `gem install` needed):
+
+```bash
+git clone <this repo> ~/code/claude/mailmate
+echo 'export PATH="$HOME/code/claude/mailmate/exe:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Then bootstrap your config:
+
+```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.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `mmsearch` | List messages matching a quicksearch expression. Output is aligned CSV. |
+| `mmmessage` | Print one message by `.eml` id (decoded headers + plain-text body). |
+| `mm-modify` | Mark read/flag/tag/archive/move a message via AppleScript. |
+| `mm-send` | Send mail through `emate` with a markdown body on stdin. |
+| `mmdiscover` | First-run bootstrap; (re-)writes the user config from MailMate's plists. |
+
+Each command takes `--help` for usage. Tab-completion: `mm<tab>` lists every command; `mms<tab>` → `mmsearch`; `mmm<tab>` → `mmmessage`; `mm-<tab>` lists the write-side commands.
+
+## eml-id vs Message-ID
+
+The CLI tools take an `eml-id` — the integer filename of MailMate's `.eml` storage (the same value as the **Msg ID** column in MailMate's UI, internally MailMate's `#body-part-id`). It's a counter MailMate maintains locally; **eml-ids are NOT portable across machines.** The same RFC `Message-ID:` will have a different eml-id on every install. If you need a cross-machine reference, use the message's `Message-ID:` header (which `mmmessage <id>` prints). The `mid:%3C<message-id>%3E` URL scheme works portably for the same reason.
+
+## Library
+
+```ruby
+require "mailmate"
+
+# Parse and evaluate a MailMate smart-mailbox filter
+ast = Mailmate.compile_filter("from.name = 'Medium' and #date-received > '1 days ago'")
+# ... feed `ast` to Mailmate::Evaluator ...
+
+# Read the binary `#flags` index
+reader = Mailmate::IndexReader.for("#flags")
+reader.flags_for(180644) # → ["\\Seen", "$Forwarded"]
+
+# Configuration
+Mailmate.config.app_support_dir # → expanded path
+Mailmate::Identity.mine?("brian@example.com") # → true if in identities
+```
+
+## Using from a MailMate bundle
+
+`mmdiscover` writes `~/.config/mailmate/bundle_loader.rb` — a one-line bootstrap that lets MailMate bundle handlers find the gem. Every handler then does:
+
+```ruby
+#!/usr/bin/env ruby
+load File.expand_path("~/.config/mailmate/bundle_loader.rb")
+require "mailmate"
+
+# ... use Mailmate::IndexReader, Mailmate::HeaderReader, Mailmate::Identity, etc.
+```
+
+The bootstrap file is the only place that knows the gem's path on disk, so individual bundles stay portable across machines — copy a `.mmBundle/` to another Mac, run `mmdiscover` there, and the bundle works.
+
+### Sample bundle
+
+The gem ships a working sample at `~/Library/Application Support/MailMate/Bundles/Mailmate.mmBundle/`:
+
+- **`Commands/Inbox Note.mmCommand`** — declares input (canonical body), env vars (from / subject / date / message-id), and output type (actions JSON).
+- **`Support/bin/inbox_note.rb`** — the handler. Reads body from stdin, headers from env, uses `Mailmate::Identity.mine?` to decide inbound/outbound, writes a markdown note to `~/code/claude/people/projects/email/inbox/<YYYY>/<MM>/`, and returns `moveMessage` (archive) + `notify` actions.
+
+To enable: restart MailMate (or use "Reload Bundles" in the Command menu). The "→ Inbox Note" entry will appear in `Command → Mailmate gem bundle`. Override the output directory by setting `MAILMATE_INBOX_DIR` in the `.mmCommand`'s `environment` block.
+
+See `~/code/claude/people/projects/email/mailmate-bundles.md` for the bundle plist mechanics in full.
+
+## Configuration
+
+Loading order: built-in defaults → `~/.config/mailmate/config.yml` → environment variables (override YAML).
+
+Available settings:
+
+| Key (YAML) | Env var | Default |
+|---|---|---|
+| `app_support_dir` | `MAILMATE_APP_SUPPORT_DIR` | `~/Library/Application Support/MailMate` |
+| `identities` (array) | `MAILMATE_IDENTITIES` (comma-separated) | `[]` |
+
+A sample `config.yml.example` ships in the repo with placeholder values.
+
+## Tests
+
+Two suites:
+
+```bash
+rake test         # hermetic — no MailMate required, runs anywhere
+rake test:live    # live — runs against your actual MailMate install
+```
+
+`rake test:live` smoke-tests every smart mailbox in your `Mailboxes.plist`, decodes every `Database.noindex/Headers/*` index, and verifies one message round-trips through `EmlLookup` → `HeaderReader` → `MidUrl`. It's user-runnable so you can verify the gem works on your machine.
+
+## License
+
+MIT. See `LICENSE.txt`.

data/config.yml.example

@@ -0,0 +1,21 @@
+# Mailmate gem configuration. Copy to ~/.config/mailmate/config.yml and edit,
+# or run `mmdiscover` to have it generated for you from MailMate's own
+# Sources.plist and Identities.plist.
+
+# Optional. Override only if MailMate isn't installed at the default location.
+# The loader expands ~ before use.
+# app_support_dir: ~/Library/Application Support/MailMate
+
+# Required for the "is this email mine?" check used by the search CLI's
+# `direction` and `party` output fields. List every address you send mail
+# from across all configured MailMate accounts (Gmail, iCloud, aliases, etc.).
+identities:
+  - me@example.com
+  - me@example.org
+
+# Optional. How to display dates and times in `mmsearch` / `mmmessage`.
+# Unset (default): use the system's local time zone — handles DST automatically.
+# Set to a fixed offset string (e.g. "-07:00" for MST, "-05:00" for EST) to
+# pin a specific zone regardless of the system. IANA names (e.g.
+# "America/Denver") are not supported; use the system zone for DST handling.
+# display_timezone: "-07:00"

data/exe/mm-modify

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "mailmate"
+require "mailmate/cli/modify"
+
+exit Mailmate::CLI::Modify.run(ARGV)

data/exe/mm-send

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "mailmate"
+require "mailmate/cli/send"
+
+exit Mailmate::CLI::Send.run(ARGV)

data/exe/mmdiscover

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "mailmate"
+require "mailmate/cli/discover"
+
+exit Mailmate::CLI::Discover.run(ARGV)

data/exe/mmmessage

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "mailmate"
+require "mailmate/cli/message"
+
+exit Mailmate::CLI::Message.run(ARGV)

data/exe/mmsearch

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "mailmate"
+require "mailmate/cli/search"
+
+exit Mailmate::CLI::Search.run(ARGV)

data/lib/mailmate/applescript_driver.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Mailmate
+  # @api public
+  #
+  # Build and run AppleScript calls against MailMate. macOS-only.
+  #
+  # A class (not a module like the stateless utilities `HeaderReader`,
+  # `MidUrl`, `Identity`, etc.) because each driver carries per-invocation
+  # state — `dry_run`, `output`, `errput`. The rule throughout the gem:
+  # stateless surface → module with `extend self`; state-bearing → class.
+  class AppleScriptDriver
+    class Error < StandardError; end
+
+    attr_reader :dry_run
+
+    def initialize(dry_run: false, output: $stdout, errput: $stderr)
+      @dry_run = dry_run
+      @output  = output
+      @errput  = errput
+    end
+
+    # Drive a MailMate selector against the current selection.
+    # `selector` is the key-binding selector name (`"markAsRead:"`,
+    # `"setTag:"`, etc.). `args` are positional arguments passed alongside.
+    def perform(selector, *args)
+      Mailmate::PlatformError.check_darwin!(component: "AppleScriptDriver") unless dry_run
+      script = build_perform_script(selector, args)
+      run_apple_script(script)
+    end
+
+    # Open a URL in MailMate (used for `mid:` URLs to select a message).
+    def open_url(url)
+      Mailmate::PlatformError.check_darwin!(component: "AppleScriptDriver") unless dry_run
+      if dry_run
+        @output.puts "DRY: open -a MailMate #{url.inspect}"
+        return
+      end
+      success = system("open", "-a", "MailMate", url)
+      raise Error, "open command failed for #{url}" unless success
+    end
+
+    # Return the array of MailMate's current window IDs (integers). Empty
+    # array if MailMate isn't running or `osascript` errors.
+    def window_ids
+      return [] if dry_run
+      out = `osascript -e 'tell application "MailMate" to get id of every window' 2>&1`
+      return [] unless $?.success?
+      out.strip.split(",").map { |s| s.strip.to_i }
+    end
+
+    # Close every window in `ids`. No-op for IDs that no longer exist.
+    def close_windows(ids)
+      return if dry_run
+      Array(ids).each do |id|
+        `osascript -e 'tell application "MailMate" to close window id #{id}' >/dev/null 2>&1`
+      end
+    end
+
+    # Internal — build the `tell application "MailMate" to perform { ... }`
+    # script with proper quoting. AppleScript string literals require:
+    #   \ → \\   (single backslash becomes \\, otherwise it interprets
+    #             \b / \n / \t / etc. as control-character escapes)
+    #   " → \"   (terminates the string otherwise)
+    # Newlines and tabs in args are rejected — they have no defensible meaning
+    # inside an AppleScript single-line script and almost certainly indicate
+    # data the caller doesn't want injected.
+    def build_perform_script(selector, args)
+      escaped_selector = applescript_escape(selector.to_s, allow_controls: false)
+      if args.empty?
+        %(tell application "MailMate" to perform {"#{escaped_selector}"})
+      else
+        list = args.map { |a| %("#{applescript_escape(a.to_s)}") }.join(", ")
+        %(tell application "MailMate" to perform {"#{escaped_selector}", #{list}})
+      end
+    end
+
+    # Escape a Ruby string for inclusion inside an AppleScript double-quoted
+    # string literal. Order matters: backslash first, then quote. Newlines/
+    # tabs are rejected unless `allow_controls: true`.
+    def applescript_escape(s, allow_controls: false)
+      if !allow_controls && s.match?(/[\r\n\t]/)
+        raise Error, "AppleScript arg contains control character (\\r/\\n/\\t): #{s.inspect}"
+      end
+      s.gsub("\\", "\\\\\\\\").gsub('"', '\\"')
+    end
+
+    private
+
+    def run_apple_script(script)
+      if dry_run
+        @output.puts "DRY: osascript -e #{script.inspect}"
+        return
+      end
+      output = `osascript -e #{Shellwords.escape(script)} 2>&1`
+      status = $?.exitstatus
+      @errput.puts "[osascript] #{output.strip}" unless output.strip.empty?
+      raise Error, "osascript exited #{status}: #{script}" unless status.zero?
+    end
+  end
+end

data/lib/mailmate/ast.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# AST nodes for MailMate filter expressions. All nodes implement #inspect for
+# debug output and are evaluated by Mailmate::Evaluator.
+
+module Mailmate
+  # @api private
+  module AST
+    AndNode     = Struct.new(:children) { def inspect; "And(#{children.map(&:inspect).join(", ")})"; end }
+    OrNode      = Struct.new(:children) { def inspect; "Or(#{children.map(&:inspect).join(", ")})"; end }
+    NotNode     = Struct.new(:child)    { def inspect; "Not(#{child.inspect})"; end }
+
+    # path: array of strings, e.g. ["from", "name"] or ["#any-address"]
+    # op: one of "=", "!=", "~", "!~", "<", "<=", ">", ">="
+    # flags: array of single-letter strings, e.g. ["c"], ["c", "a"], or []
+    # value: a *Node (LiteralStringNode, NumberNode, RelativeDateNode, AbsoluteDateNode, VarRefNode)
+    CompareNode = Struct.new(:path, :op, :flags, :value) do
+      def inspect; "Compare(#{path.join(".")} #{op}#{flags.empty? ? "" : "[#{flags.join}]"} #{value.inspect})"; end
+    end
+
+    ExistsNode = Struct.new(:path) { def inspect; "Exists(#{path.join(".")})"; end }
+
+    LiteralStringNode = Struct.new(:value) { def inspect; "Str(#{value.inspect})"; end }
+    NumberNode        = Struct.new(:value) { def inspect; "Num(#{value})"; end }
+
+    # n: integer; unit: :day, :week, :month, :year
+    RelativeDateNode = Struct.new(:n, :unit) { def inspect; "Rel(#{n} #{unit}s ago)"; end }
+    AbsoluteDateNode = Struct.new(:time)     { def inspect; "Abs(#{time.iso8601})"; end }
+
+    # Stage C placeholder: $SENT.from.address style references.
+    VarRefNode = Struct.new(:var, :path) { def inspect; "Var($#{var}.#{path.join(".")})"; end }
+  end
+end