mailmate 0.2.0 → 1.0.0

data/lib/mailmate/eml_lookup.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module Mailmate
   # @api public
   #
@@ -42,19 +44,37 @@ module Mailmate
       nil
     end
 
-    # Resolve an identifier that may be either an eml-id (all digits) or an
-    # RFC Message-ID (anything else) to a local eml-id.
+    # Resolve an identifier to a local eml-id. Accepts:
+    #   - eml-id (all digits)              e.g. "183715"
+    #   - RFC Message-ID, brackets optional e.g. "<abc@example.com>"
+    #   - message://… URL                  e.g. "message://%3Cabc%40example.com%3E"
+    #                                           or "message://183715"
+    #   - mid:… URL                        e.g. "mid:%3Cabc%40example.com%3E"
+    #                                           or "mid:183715"
+    # Strips the URL wrapper first (message:// or mid:) so the digit check
+    # below catches the local-eml-id payload too — same leniency MailMate's
+    # own URL handler offers. The %3C…%3E payload form is portable across
+    # machines; the bare-integer form is local-only.
     def self.resolve_id(input)
       s = input.to_s.strip
+      s = URI.decode_www_form_component(s.sub(%r{\A(?:message://|mid:)}, "")) if s.match?(%r{\A(?:message://|mid:)})
       return s.to_i if s =~ /\A\d+\z/
       eml_id_for_message_id(s)
     end
 
     # Force the index path (useful for tests and benchmarking).
+    #
+    # Returns nil — not just on missing-index — when the indexed path no
+    # longer points at an existing file. That happens whenever MailMate's
+    # `#source` index lags the filesystem; the common case is right after
+    # `mm-modify`'s fast-path move renames the .eml on disk and MailMate
+    # hasn't rescanned yet. Treating stale entries as misses lets `path_for`
+    # fall through to the glob walker and recover the file at its new home.
     def self.via_index(eml_id)
       url = source_url_for(eml_id)
       return nil if url.nil?
-      url_to_path(url, eml_id)
+      path = url_to_path(url, eml_id)
+      path if path && File.exist?(path)
     end
 
     # Force the glob fallback.

data/lib/mailmate/index_reader.rb

@@ -13,13 +13,29 @@
 #             value = cache[start...end]   (start == end → empty / "no value")
 #   .plist    Old-style plist with offsetsFileSize / stringsFileSize sentinels.
 #
+# Most indexes have multiple records per id even when they're conceptually
+# 1:1 (header indexes accumulate stale records as messages change; e.g.
+# `#flags` for a single id can have dozens of records, one per flag change,
+# with the latest at the end). Body indexes (`#unquoted#lc`, `#quoted#lc`)
+# are intentionally multi-record: one record per text segment of each body
+# part. The accessor pair handles both cases:
+#
+#   value_for(id)   → LAST record for the id (matches the on-disk
+#                     "latest-version" semantics for accumulator-style
+#                     indexes; for genuinely multi-record indexes like body
+#                     content, the last record alone is meaningless — use
+#                     values_for there).
+#   values_for(id)  → all records for the id, in offsets-file order.
+#   each_record     → yields (id, value) once per on-disk record. Multi-record
+#                     ids yield multiple times; 1:1 ids yield once.
+#
 # Specific accessors:
 #   `flags.flag(eml_id)`  → Array<String> of IMAP keywords (`\Seen`,
 #                            `\Flagged`, `$Forwarded`, `$Muted`, custom tags…)
 #                            or [] if the message has no flags / isn't indexed.
 #
 # IndexReader instances cache both files in memory and build a hash from
-# msg_id → (start,end) for O(1) lookup. Construction cost ≈ 5–20 ms for
+# id → [[start,end], …] for O(1) lookup. Construction cost ≈ 5–20 ms for
 # 50–200k records; memory ≈ a few MB. For a CLI invocation that's fine; the
 # evaluator instantiates one lazily when first needed.
 
@@ -72,11 +88,25 @@ module Mailmate
     end
 
     # Returns the raw cached value for a given .eml body-part ID, or nil if
-    # the message isn't in this index.
+    # the id isn't in this index. Returns the LAST record for the id — for
+    # accumulator-style header indexes (`#flags`, `#source`, `subject`, etc.)
+    # that's the latest state; the older records are stale versions. For
+    # body indexes (`#unquoted#lc`, `#quoted#lc`) last-alone is meaningless
+    # — use values_for to read every segment.
     def value_for(eml_id)
-      pair = @index[eml_id.to_i]
-      return nil unless pair
-      @cache_bytes[pair[0]...pair[1]]
+      pairs = @index[eml_id.to_i]
+      return nil if pairs.nil? || pairs.empty?
+      s, e = pairs[-1]
+      @cache_bytes[s...e]
+    end
+
+    # Returns every recorded value for an id, in offsets-file order. Returns
+    # [] if the id isn't in the index. Use this for body indexes
+    # (#unquoted#lc, #quoted#lc), which store one record per text segment.
+    def values_for(eml_id)
+      pairs = @index[eml_id.to_i]
+      return [] if pairs.nil?
+      pairs.map { |(s, e)| @cache_bytes[s...e] }
     end
 
     # `#flags.flag` semantics: the cache stores a space-separated list of IMAP
@@ -87,11 +117,17 @@ module Mailmate
       v.split(/\s+/).reject(&:empty?)
     end
 
-    # Number of records (mostly for diagnostics).
+    # Number of distinct ids in the index. For multi-record indexes this is
+    # smaller than the on-disk record count (use record_count for that).
     def size
       @index.size
     end
 
+    # Total number of on-disk records (sum across all ids). Diagnostics.
+    def record_count
+      @index.values.sum(&:size)
+    end
+
     # Iterate every recorded eml-id. Yields just the id; callers that also
     # want the value should pair this with `value_for`. Exists so other gem
     # modules don't have to reach into `@index` directly.
@@ -100,25 +136,26 @@ module Mailmate
       @index.each_key(&block)
     end
 
-    # Iterate every (eml_id, raw_value) pair. The value comes back as the
-    # bare cache substring; callers that need parsed form (e.g. flag tokens)
+    # Iterate every (eml_id, raw_value) pair, once per on-disk record.
+    # Multi-record ids yield multiple times. The value comes back as the bare
+    # cache substring; callers that need parsed form (e.g. flag tokens)
     # should massage it themselves.
     def each_record
       return enum_for(:each_record) unless block_given?
-      @index.each_key do |eml_id|
-        yield eml_id, value_for(eml_id)
+      @index.each do |eml_id, pairs|
+        pairs.each { |(s, e)| yield eml_id, @cache_bytes[s...e] }
       end
     end
 
     private
 
     def build_index!
-      @index = {}
+      @index = Hash.new { |h, k| h[k] = [] }
       n = @offsets_bytes.bytesize / RECORD_SIZE
       i = 0
       while i < n
         rec = @offsets_bytes[i * RECORD_SIZE, RECORD_SIZE].unpack("V3")
-        @index[rec[0]] = [rec[1], rec[2]]
+        @index[rec[0]] << [rec[1], rec[2]]
         i += 1
       end
     end

data/lib/mailmate/mcp.rb

@@ -0,0 +1,394 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+
+require "mailmate"
+require "mailmate/cli/search"
+require "mailmate/cli/message"
+require "mailmate/cli/modify"
+require "mailmate/cli/send"
+require "mailmate/cli/open"
+require "mailmate/cli/mailboxes"
+require "mailmate/cli/tags"
+require "mailmate/eml_lookup"
+require "mailmate/header_reader"
+require "mailmate/mid_url"
+
+module Mailmate
+  # Stdio MCP server (JSON-RPC 2.0, line-delimited). Exposes the gem's CLIs —
+  # search, message, modify, send — plus a resolve_id helper that round-trips
+  # between local eml-id, RFC Message-ID, and the cross-machine message:// URL.
+  #
+  # In-process: each tool call runs the corresponding `Mailmate::CLI::*.run`
+  # method with a synthesized argv, capturing stdout/stderr from the existing
+  # CLI rather than re-implementing each command.
+  module MCP
+    extend self
+
+    PROTOCOL_VERSION = "2024-11-05"
+    SERVER_NAME      = "mailmate"
+
+    TOOLS = [
+      {
+        name: "search",
+        description: <<~DESC.strip,
+          Search MailMate's .eml files using MailMate's quicksearch syntax.
+          Returns column-aligned CSV. Same engine as the `mmsearch` CLI.
+
+          Common patterns:
+            query="f medium d 7d"        from Medium in the last 7 days
+            query="T robot"              tagged "robot" (reads MailMate's #flags index)
+            query="s 'rent due' !draft"  subject has 'rent due', not 'draft'
+            query="d 2026-05"            received in May 2026
+
+          Fields default to: flags date time direction party subject
+          Prefix fields with "+" to add to defaults (e.g. "+tags +mailbox").
+          Bare fields list replaces defaults (id is always first).
+        DESC
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Quicksearch expression. Empty string disables filtering. Default: 'd 1d' (today).",
+            },
+            fields: {
+              type: "string",
+              description: "Space-separated columns. Prefix with '+' to add to defaults. Available: id path mailbox from to cc bcc reply-to subject date time message-id references in-reply-to direction party flags read archive tags keywords.",
+            },
+            mailbox: {
+              type: "string",
+              description: "Account, mailbox path, or smart-mailbox name. Default: all.",
+            },
+            limit: { type: "integer", description: "Stop after N matches." },
+            headers_only: { type: "boolean", description: "Skip body matching (much faster on text searches)." },
+            sort: { type: "string", enum: %w[asc desc none], description: "Sort by date+time. Default: asc." },
+          },
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "message",
+        description: "Read one MailMate message. Accepts either local eml-id (digits) or RFC Message-ID (with or without angle brackets). Default output: headers block + plain-text body.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "eml-id (e.g. '183715') or RFC Message-ID (e.g. '<abc@example.com>')." },
+            raw: { type: "boolean", description: "Return raw .eml bytes." },
+            text_only: { type: "boolean", description: "Body only, no headers block." },
+          },
+          required: ["id"],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "modify",
+        description: <<~DESC.strip,
+          Apply state-change actions to a message via MailMate.
+          NOTE: drives MailMate's UI via AppleScript — it briefly takes focus,
+          and calls are serial per app.
+
+          actions is a flat array; arg-taking actions consume the next item:
+            ["read"]                       mark read
+            ["read", "flag", "archive"]    three actions, one open/wait cycle
+            ["tag", "urgent"]              add tag
+            ["untag", "todo"]              remove tag
+            ["move", "Archive.mailbox"]    move
+
+          Valid actions: read unread flag unflag tag untag clear-tags archive
+          junk not-junk mute delete move
+        DESC
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "eml-id or RFC Message-ID." },
+            actions: {
+              type: "array",
+              items: { type: "string" },
+              description: "Flat list of action tokens; arg-taking actions consume the following item.",
+            },
+            dry_run: { type: "boolean", description: "Print plan, don't execute." },
+            verify: { type: "boolean", description: "Re-read flags after acting to confirm." },
+            keep_window: { type: "boolean", description: "Skip the close-window keystroke at the end." },
+          },
+          required: %w[id actions],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "send",
+        description: "Send mail via MailMate's `emate` (markdown body). Recipients and subject via fields; body is the markdown source.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            to: { type: "string", description: "Recipient(s), comma-separated." },
+            cc: { type: "string", description: "CC recipient(s), comma-separated." },
+            bcc: { type: "string", description: "BCC recipient(s), comma-separated." },
+            subject: { type: "string", description: "Subject line." },
+            body: { type: "string", description: "Markdown body." },
+            attachments: { type: "array", items: { type: "string" }, description: "Absolute paths to files to attach." },
+            send_now: { type: "boolean", description: "Send immediately (skip the Drafts pause)." },
+          },
+          required: %w[to subject body],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "open",
+        description: "Open one MailMate message in MailMate's UI (activates the window). Accepts any of the id forms `resolve_id` takes. Read-side semantically, but does shift focus to MailMate.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "eml-id, RFC Message-ID, message://… URL, or mid:… URL." },
+            print_only: { type: "boolean", description: "Return the mid: URL without invoking `open`." },
+          },
+          required: ["id"],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "list_mailboxes",
+        description: "Enumerate accounts, IMAP mailboxes (with optional message counts), and smart mailboxes MailMate has defined. Account names are decoded for display (`%40` → `@`).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            count: { type: "boolean", description: "Include .eml counts per IMAP mailbox (default true; pass false to skip for speed)." },
+            csv:   { type: "boolean", description: "Flat CSV output (one row per mailbox); default is grouped by account." },
+          },
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "list_tags",
+        description: "List user tags. Default: tags actually applied to messages, with usage counts (from MailMate's #flags index; system flags excluded). `defined: true`: tags MailMate has registered in Preferences → Tags (from Tags.plist).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            defined: { type: "boolean", description: "Read from Tags.plist (defined tags) instead of scanning #flags (used tags)." },
+          },
+          additionalProperties: false,
+        },
+      },
+      {
+        name: "resolve_id",
+        description: <<~DESC.strip,
+          Look up a message and return all its identifiers:
+            - eml_id        local body-part id (changes per machine)
+            - message_id    RFC Message-ID header (portable across machines)
+            - message_url   message://%3C<MID>%3E   — cross-machine reference
+            - mid_url       mid:%3C<MID>%3E         — drives MailMate locally
+
+          Accepts: eml-id, Message-ID (with/without angle brackets), or message:// URL.
+          Use to mint a portable reference from a local eml-id, or to find the
+          local eml-id given a Message-ID copied from another machine.
+        DESC
+        inputSchema: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "eml-id, Message-ID, or message:// URL." },
+          },
+          required: ["id"],
+          additionalProperties: false,
+        },
+      },
+    ].freeze
+
+    def run(stdin: $stdin, stdout: $stdout)
+      stdin.binmode
+      stdout.binmode
+      stdout.sync = true
+      loop do
+        line = stdin.gets
+        break if line.nil?
+        line = line.strip
+        next if line.empty?
+        begin
+          msg = JSON.parse(line)
+        rescue JSON::ParserError => e
+          write(stdout, jsonrpc_error(nil, -32700, "Parse error: #{e.message}"))
+          next
+        end
+        handle(msg, stdout)
+      end
+      0
+    end
+
+    def handle(msg, stdout)
+      method = msg["method"]
+      id     = msg["id"]
+      case method
+      when "initialize"
+        write(stdout, jsonrpc_result(id, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities:    { tools: {} },
+          serverInfo:      { name: SERVER_NAME, version: Mailmate::VERSION },
+        }))
+      when "notifications/initialized", "notifications/cancelled"
+        # notifications — no response
+      when "tools/list"
+        write(stdout, jsonrpc_result(id, { tools: TOOLS }))
+      when "tools/call"
+        params = msg["params"] || {}
+        result = dispatch(params["name"], params["arguments"] || {})
+        write(stdout, jsonrpc_result(id, result))
+      when "ping"
+        write(stdout, jsonrpc_result(id, {}))
+      else
+        # Unknown method — error if it has an id (request), drop if not.
+        write(stdout, jsonrpc_error(id, -32601, "Method not found: #{method}")) unless id.nil?
+      end
+    end
+
+    def dispatch(name, args)
+      case name
+      when "search"         then call_search(args)
+      when "message"        then call_message(args)
+      when "modify"         then call_modify(args)
+      when "send"           then call_send(args)
+      when "open"           then call_open(args)
+      when "list_mailboxes" then call_list_mailboxes(args)
+      when "list_tags"      then call_list_tags(args)
+      when "resolve_id"     then call_resolve(args)
+      else                       text_error("Unknown tool: #{name}")
+      end
+    rescue StandardError => e
+      text_error("#{e.class}: #{e.message}\n#{e.backtrace.first(8).join("\n")}")
+    end
+
+    # ---- tool handlers ----------------------------------------------------
+
+    def call_search(args)
+      argv = []
+      argv.push("--mailbox", args["mailbox"].to_s)   if args["mailbox"]
+      argv.push("--limit",   args["limit"].to_i.to_s) if args["limit"]
+      argv.push("--headers-only")                    if args["headers_only"]
+      argv.push("--sort",    args["sort"].to_s)      if args["sort"]
+      # Positionals: search-string then fields. Only include if the caller
+      # gave us either — otherwise let the CLI apply its defaults.
+      if args.key?("query") || args["fields"]
+        argv << (args["query"] || "")
+        argv << args["fields"].to_s if args["fields"]
+      end
+      run_cli(Mailmate::CLI::Search, argv)
+    end
+
+    def call_message(args)
+      argv = [args["id"].to_s]
+      argv << "--raw"       if args["raw"]
+      argv << "--text-only" if args["text_only"]
+      run_cli(Mailmate::CLI::Message, argv)
+    end
+
+    def call_modify(args)
+      argv = [args["id"].to_s] + Array(args["actions"]).map(&:to_s)
+      argv << "--dry-run"     if args["dry_run"]
+      argv << "--verify"      if args["verify"]
+      argv << "--keep-window" if args["keep_window"]
+      run_cli(Mailmate::CLI::Modify, argv)
+    end
+
+    def call_send(args)
+      argv = []
+      argv.push("-t", args["to"].to_s)      if args["to"]
+      argv.push("-c", args["cc"].to_s)      if args["cc"]
+      argv.push("-b", args["bcc"].to_s)     if args["bcc"]
+      argv.push("-s", args["subject"].to_s) if args["subject"]
+      argv << "--send-now"                  if args["send_now"]
+      Array(args["attachments"]).each { |p| argv << p.to_s }
+      with_stdin(args["body"].to_s) { run_cli(Mailmate::CLI::Send, argv) }
+    end
+
+    def call_open(args)
+      argv = [args["id"].to_s]
+      argv << "--print" if args["print_only"]
+      run_cli(Mailmate::CLI::Open, argv)
+    end
+
+    def call_list_mailboxes(args)
+      argv = []
+      argv << "--no-count" if args.key?("count") && !args["count"]
+      argv << "--csv"      if args["csv"]
+      run_cli(Mailmate::CLI::Mailboxes, argv)
+    end
+
+    def call_list_tags(args)
+      argv = []
+      argv << "--defined" if args["defined"]
+      run_cli(Mailmate::CLI::Tags, argv)
+    end
+
+    def call_resolve(args)
+      eml_id = Mailmate::EmlLookup.resolve_id(args["id"].to_s)
+      return text_error("Not found: #{args["id"].inspect}") if eml_id.nil? || eml_id.zero?
+
+      path = Mailmate::EmlLookup.path_for(eml_id)
+      return text_error("Not found: #{eml_id}.eml") unless path
+
+      message_id = Mailmate::HeaderReader.message_id(path)
+      mailbox    = path.sub("#{Mailmate.config.imap_root}/", "")
+                       .sub(%r{/Messages/[^/]+\.eml\z}, "")
+
+      payload = {
+        eml_id:      eml_id,
+        message_id:  message_id,
+        message_url: message_id ? Mailmate::MidUrl.message_url_for(message_id) : nil,
+        mid_url:     message_id ? Mailmate::MidUrl.for(message_id) : nil,
+        path:        path,
+        mailbox:     mailbox,
+      }
+      { content: [{ type: "text", text: JSON.pretty_generate(payload) }] }
+    end
+
+    # ---- protocol helpers -------------------------------------------------
+
+    def run_cli(mod, argv)
+      out, err, code = with_captured_io { mod.run(argv) }
+      text = +""
+      text << out unless out.empty?
+      unless err.empty?
+        text << "\n" unless text.empty?
+        text << "[stderr]\n" << err
+      end
+      text = "(no output)" if text.empty?
+      { content: [{ type: "text", text: text }], isError: code != 0 }
+    end
+
+    def with_captured_io
+      old_out, old_err = $stdout, $stderr
+      $stdout = StringIO.new
+      $stderr = StringIO.new
+      code = yield
+      [$stdout.string, $stderr.string, code.is_a?(Integer) ? code : 0]
+    ensure
+      $stdout = old_out
+      $stderr = old_err
+    end
+
+    def with_stdin(text)
+      old = $stdin
+      $stdin = StringIO.new(text)
+      yield
+    ensure
+      $stdin = old
+    end
+
+    def text_error(msg)
+      { content: [{ type: "text", text: msg }], isError: true }
+    end
+
+    def jsonrpc_result(id, result)
+      { jsonrpc: "2.0", id: id, result: result }
+    end
+
+    def jsonrpc_error(id, code, message)
+      { jsonrpc: "2.0", id: id, error: { code: code, message: message } }
+    end
+
+    def write(stdout, obj)
+      stdout.write(JSON.generate(obj) + "\n")
+      stdout.flush
+    end
+
+  end
+end

data/lib/mailmate/mid_url.rb

@@ -3,21 +3,41 @@
 module Mailmate
   # @api public
   #
-  # Build a MailMate `mid:` URL from a Message-ID. MailMate registers the
-  # `mid:` scheme (RFC 2392) and resolves it to a specific message. The angle
-  # brackets that bracket the Message-ID in headers must be percent-encoded.
+  # Build URLs that point to a single MailMate message:
+  #
+  #   - `mid:%3C<id>%3E`       — local MailMate driver URL (RFC 2392). Selects
+  #                              the message in the local store; what
+  #                              `mm-modify` uses to drive the UI.
+  #   - `message://%3C<id>%3E` — portable, cross-machine reference. Same
+  #                              encoding, different scheme. Resolves to the
+  #                              same physical email on any MailMate install
+  #                              because the RFC `Message-ID` header is
+  #                              globally unique.
+  #
+  # Both schemes need the angle brackets that wrap a Message-ID to be
+  # percent-encoded; characters that would break URL parsers (`[`, `]`,
+  # whitespace) are also encoded. Other URL-reserved characters (`@`, `.`,
+  # `-`, `_`) are preserved — MailMate's parser accepts them as-is.
   module MidUrl
-    # Returns `mid:%3C<message-id>%3E`. Accepts the Message-ID with or without
-    # surrounding angle brackets — strips them either way before encoding.
-    # URL-encodes characters that would break the URL parser, notably `[` and
-    # `]` (which appear in Message-IDs containing IPv4 literals, e.g.
-    # `<id@[169.254.16.253]>`). Other URL-reserved characters (`@`, `.`, `-`,
-    # `_`, etc.) are preserved — MailMate's parser accepts them as-is.
+    # `mid:%3C<message-id>%3E` — used by MailMate to select a message locally.
     def self.for(message_id)
+      "mid:#{encoded_with_brackets(message_id)}"
+    end
+
+    # `message://%3C<message-id>%3E` — portable cross-machine reference. Pass
+    # back to `EmlLookup.resolve_id` (or any CLI that takes an id) to look up
+    # the same physical email on another machine.
+    def self.message_url_for(message_id)
+      "message://#{encoded_with_brackets(message_id)}"
+    end
+
+    # Percent-encoded `%3C…%3E` envelope shared by both schemes. Exposed in
+    # case a caller wants the brackets-only form without a scheme prefix.
+    def self.encoded_with_brackets(message_id)
       raise ArgumentError, "Message-ID required" if message_id.nil? || message_id.to_s.empty?
       id = message_id.to_s.sub(/\A</, "").sub(/>\z/, "")
       encoded = id.gsub(/[\[\]<>\s]/) { |c| "%%%02X" % c.ord }
-      "mid:%3C#{encoded}%3E"
+      "%3C#{encoded}%3E"
     end
   end
 end

data/lib/mailmate/part_lookup.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# PartLookup — given a `.eml` envelope id, return the body-part-ids of its
+# child parts.
+#
+# MailMate stores each message as a tree of parts: the envelope (which becomes
+# the on-disk `.eml` filename) is the root, with text/plain, text/html, and
+# attachments as children with their own part-ids. Body content indexes
+# (`#unquoted#lc`, `#quoted#lc`, etc.) are keyed by body-part-id, not
+# envelope-id — so to read a message's body content from those indexes we
+# first have to walk from envelope-id to its children.
+#
+# Data source: `#root-body-part.{cache,offsets}`, which stores the root
+# (envelope) id as a decimal-string value for each non-envelope part-id. We
+# invert that mapping once per process: envelope_id → [part_ids].
+#
+# Memory: ~5 MB for 100k part records. Negligible. Build cost: one IndexReader
+# pass, ≈10–30 ms.
+
+module Mailmate
+  # @api public
+  module PartLookup
+    class << self
+      # Returns the body-part-ids that descend from `envelope_id`. Returns []
+      # for envelopes with no recorded children (single-part messages where
+      # envelope-id == body-part-id, and messages MailMate hasn't yet
+      # indexed). Order matches `#root-body-part`'s id-iteration order, not
+      # MIME-tree order.
+      def body_parts_of(envelope_id)
+        inversion[envelope_id.to_i] || []
+      end
+
+      # Drop the cached inversion. Tests use this with `with_config` swaps;
+      # production callers use it when MailMate's index has been rewritten on
+      # disk. Cheap — next call rebuilds lazily.
+      def reset!
+        @inversions = nil
+      end
+
+      private
+
+      def inversion
+        @inversions ||= {}
+        @inversions[Mailmate.config.db_headers] ||= build_inversion
+      end
+
+      def build_inversion
+        inv = Hash.new { |h, k| h[k] = [] }
+        reader = Mailmate::IndexReader.for("#root-body-part")
+        reader.each_eml_id do |part_id|
+          root_str = reader.value_for(part_id)
+          # Skip deleted parts: MailMate appends an empty trailing record to
+          # `#root-body-part` when a part is removed. value_for returns that
+          # latest record, so empty == "this part is gone."
+          next if root_str.nil? || root_str.empty?
+          inv[root_str.to_i] << part_id
+        end
+        inv
+      end
+    end
+  end
+end

data/lib/mailmate/version.rb

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