mailmate 1.6.0 → 1.8.0

data/lib/mailmate/cli/send.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "open3"
+require_relative "../reply_prefill"
+
 module Mailmate
   module CLI
     # `mm-send` — send mail through MailMate's `emate` CLI with a markdown body.
@@ -17,42 +20,177 @@ module Mailmate
         Body is read from stdin. All other flags pass through to emate (its help follows).
 
         Replies and threading
-          MailMate auto-generates the outgoing Message-ID — never your job.
-          In-Reply-To and References are PURE PASS-THROUGH: whatever you set via
-          `--header` ships verbatim; what you don't set is absent (and recipients'
-          clients will see the message as a fresh thread, no matter how `Re:` the
-          subject looks). To make a reply land in-thread, pass both:
+          A `Re:` subject alone does NOT thread — modern clients thread on headers.
+          MailMate generates the outgoing Message-ID; never your job.
 
-            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"
+            mm-send -f you@x --reply-to "<parent-mid@domain>" --send-now <<<"body"
 
-          References is constructed as the source message's References header (if
-          any) with the source's Message-ID appended. If the source is a thread
-          root with no References, just use its Message-ID alone.
+          derives In-Reply-To, References, recipients and subject from the parent.
+          --reply-all-to replies to all; --forward forwards. Fields you pass
+          explicitly win; fields you omit follow normal reply rules. --header
+          stays available as the escape hatch when the parent isn't indexed.
 
         Identity selection
           `-f <address>` picks which of MailMate's configured identities sends.
           Without `-f`, MailMate uses its default identity. See `mmdiscover` to
           list available addresses.
 
+        Full rules — threading chain, merge rule, header safety:
+          docs/Composing and threading.md (shipped with the gem), or
+          https://github.com/brianmd/mailmate/blob/main/docs/
+
         ──────────────────────────── emate help follows ────────────────────────────
 
       PREAMBLE
 
-      # Returns the exit status of the spawned `emate` invocation. Uses
-      # `system` (not `exec`) so the caller — and the test suite — can
-      # actually observe the result.
+      # Returns the exit status of the spawned `emate` invocation.
+      #
+      # emate must NEVER inherit the caller's real stdin/stdout. Inside the
+      # MCP server, fd 0/1 are the JSON-RPC transport, and the previous
+      # `system(...)` handed both to emate: it blocked reading the protocol
+      # pipe for a body and consumed the next frame as one (a cancelled turn
+      # produced a MailMate draft whose entire body was a
+      # `notifications/cancelled` frame — the composed body, swapped in via
+      # the Ruby-level `$stdin` global, was silently discarded). So: read the
+      # body through `$stdin` (honors the MCP's StringIO swap AND a shell
+      # pipe), hand it to emate on a private pipe that capture3 EOFs (no
+      # more hanging until the server dies), and re-emit emate's output
+      # through the `$stdout`/`$stderr` globals so the MCP's capture sees it
+      # instead of the protocol stream getting corrupted.
       def run(argv)
+        help = argv.include?("--help") || argv.include?("-h")
+
+        # Our own flags are peeled off BEFORE the platform/emate checks so
+        # `--print-prefill` works as a pure query — markdownr calls it to fill
+        # a form and has no business requiring a launchable MailMate.
+        begin
+          argv, derived = apply_parent!(argv, help: help)
+        rescue Mailmate::ReplyPrefill::NotFound, ArgumentError => e
+          warn "mm-send: #{e.message}"
+          return 1
+        end
+        return print_prefill(derived) if derived && derived[:print_only]
+
         Mailmate::PlatformError.check_darwin!(component: "mm-send")
         unless File.executable?(EMATE_PATH)
           warn "mm-send: emate not found at #{EMATE_PATH}. Is MailMate installed?"
           return 1
         end
-        warn PREAMBLE if argv.include?("--help") || argv.include?("-h")
-        system(EMATE_PATH, "mailto", "--markup", "markdown", *argv)
-        $?.exitstatus
+        warn PREAMBLE if help
+        # --help never reads a body; consuming stdin here would hang an
+        # interactive `mm-send --help` waiting for Ctrl-D.
+        body = help ? "" : $stdin.read.to_s
+        body = append_quote(body, derived) if derived
+        out, err, status = Open3.capture3(EMATE_PATH, "mailto", "--markup", "markdown", *argv, stdin_data: body)
+        $stdout.write(out)
+        $stderr.write(err)
+        # exitstatus is nil for a signal-killed child; the exe shims do
+        # `exit run(ARGV)`, which needs an Integer.
+        status.exitstatus || 1
+      end
+
+      # Flags this wrapper consumes itself. Everything else in argv is emate's
+      # and passes through untouched — that pass-through is the design, so the
+      # scan below is deliberately literal rather than an OptionParser (which
+      # would have to be taught every emate flag in order to ignore them).
+      PARENT_FLAGS = { "--reply-to" => "reply", "--reply-all-to" => "reply-all", "--forward" => "forward" }.freeze
+
+      # Returns [argv_for_emate, derived_or_nil]. When a parent flag is
+      # present, derives the reply fields and splices them in as emate flags —
+      # but only for fields the caller did NOT pass. Explicit always wins; see
+      # the merge rule in docs/Composing and threading.md.
+      def apply_parent!(argv, help: false)
+        rest, parent, mode, print_only, quote = extract_flags(argv)
+        return [rest, nil] if parent.nil?
+
+        # --print-prefill is a query, so it answers even under --help; the
+        # send path would otherwise be unreachable for a caller inspecting it.
+        prefill = Mailmate::ReplyPrefill.build(parent, mode: mode)
+        derived = { prefill: prefill, print_only: print_only, quote: quote }
+        return [rest, derived] if print_only || help
+
+        [splice(rest, prefill), derived]
+      end
+
+      def extract_flags(argv)
+        rest = []
+        parent = mode = nil
+        print_only = false
+        quote = true
+        i = 0
+        while i < argv.length
+          arg = argv[i]
+          if PARENT_FLAGS.key?(arg)
+            raise ArgumentError, "#{arg} needs a message id" if argv[i + 1].nil?
+            raise ArgumentError, "pass only one of #{PARENT_FLAGS.keys.join(', ')}" if parent
+
+            mode = PARENT_FLAGS[arg]
+            parent = argv[i + 1]
+            i += 2
+          elsif arg == "--print-prefill"
+            print_only = true
+            i += 1
+          elsif arg == "--no-quote"
+            quote = false
+            i += 1
+          else
+            rest << arg
+            i += 1
+          end
+        end
+        raise ArgumentError, "--print-prefill needs one of #{PARENT_FLAGS.keys.join(', ')}" if print_only && parent.nil?
+
+        [rest, parent, mode, print_only, quote]
+      end
+
+      # Add derived values ONLY where the caller was silent. `passed?` looks
+      # for the flag itself, so `-t a@x --reply-to <id>` keeps a@x and still
+      # threads — overriding a visible field must never drop the headers.
+      def splice(argv, prefill)
+        out = argv.dup
+        out.push("-f", prefill.from) if prefill.from && !passed?(argv, %w[-f --from])
+        unless passed?(argv, %w[-t --to])
+          prefill.to.each { |a| out.push("-t", a) }
+        end
+        unless passed?(argv, %w[-c --cc])
+          prefill.cc.each { |a| out.push("-c", a) }
+        end
+        out.push("-s", prefill.subject) if prefill.subject && !passed?(argv, %w[-s --subject])
+        # Threading headers are NOT subject to the merge rule's "explicit
+        # wins" in the usual sense — a caller who passes their own
+        # --header "In-Reply-To: …" alongside --reply-to gets both, which is
+        # a duplicate header. Skip ours when they've hand-set either one.
+        out.push("--header", "In-Reply-To: #{prefill.in_reply_to}") if prefill.in_reply_to && !header_passed?(argv, "in-reply-to")
+        out.push("--header", "References: #{prefill.references}")   if prefill.references && !header_passed?(argv, "references")
+        out
+      end
+
+      def passed?(argv, flags)
+        argv.any? { |a| flags.include?(a) || flags.any? { |f| f.start_with?("--") && a.start_with?("#{f}=") } }
+      end
+
+      def header_passed?(argv, name)
+        argv.each_with_index.any? do |a, i|
+          (a == "--header" && argv[i + 1].to_s.downcase.start_with?("#{name}:")) ||
+            (a.start_with?("--header=") && a.split("=", 2).last.to_s.downcase.start_with?("#{name}:"))
+        end
+      end
+
+      # Reply rules seed the body with the quoted original BELOW whatever the
+      # caller wrote, matching what a mail client's Reply button produces.
+      def append_quote(body, derived)
+        return body unless derived[:quote]
+
+        quote = derived[:prefill].quoted_body.to_s
+        return body if quote.strip.empty?
+
+        "#{body.to_s.sub(/\n+\z/, '')}\n\n#{quote}"
+      end
+
+      def print_prefill(derived)
+        require "json"
+        $stdout.puts JSON.pretty_generate(derived[:prefill].to_h)
+        0
       end
     end
   end

data/lib/mailmate/cli/version_flag.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../version"
+
+module Mailmate
+  module CLI
+    # `--version` / `-V`, handled uniformly by every exe shim.
+    #
+    # This exists so a CONSUMER can tell how old an installed mailmate is
+    # without parsing help text or probing for a flag's side effects. That
+    # matters because the CLIs are deliberately pass-through: an older
+    # `mm-send` handed a flag it doesn't know forwards it to `emate` rather
+    # than rejecting it, so "did this flag work?" is not a safe capability
+    # probe — it can open a composer window instead of erroring. A version
+    # string is the honest check.
+    #
+    # Every shim calls this before dispatching, so the answer is available
+    # even from commands whose real work needs macOS or a running MailMate.
+    # test_exe_shims.rb asserts the coverage is total; a new shim that skips
+    # the call fails that test rather than silently becoming the one command
+    # that can't be version-probed.
+    module VersionFlag
+      extend self
+
+      FLAGS = %w[--version -V].freeze
+
+      # Prints "<name> (mailmate X.Y.Z)" and exits 0 when the flag is present.
+      # Returns nil otherwise, so shims can call it unconditionally.
+      def handle!(argv, name)
+        return unless argv.any? { |a| FLAGS.include?(a) }
+
+        $stdout.puts "#{name} (mailmate #{Mailmate::VERSION})"
+        exit 0
+      end
+    end
+  end
+end

data/lib/mailmate/header_value.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # Sanitize a value destined for an `emate --header "Name: value"` flag.
+  #
+  # Header values ship VERBATIM into the outgoing message, and the values we
+  # inject most often (`In-Reply-To`, `References`) are derived from ANOTHER
+  # message — i.e. from input nobody in this process authored. A value
+  # carrying CR/LF would end the header and begin a new one, smuggling
+  # arbitrary RFC 5322 headers (a `Bcc:`, say) into mail the caller believes
+  # they fully specified.
+  #
+  # Every path that builds a `--header` flag must run its value through here.
+  # There is deliberately ONE implementation: this logic previously existed in
+  # two places (the MCP server's argv builder and markdownr's), and only one of
+  # them had the defense — which is exactly the failure mode a shared helper
+  # exists to prevent.
+  module HeaderValue
+    extend self
+
+    # Collapse any CR/LF (and the whitespace that follows it, so an unfolded
+    # continuation doesn't leave a ragged double space) to a single space,
+    # then trim. Returns a String; nil/empty in → "" out.
+    def sanitize(value)
+      value.to_s.gsub(/[\r\n]+\s*/, " ").strip
+    end
+
+    # Wrap a Message-ID in angle brackets unless it already has them. Both
+    # forms are valid input; the on-wire form is bracketed per RFC 5322.
+    # Sanitizes first, so a smuggled newline can't survive by hiding inside
+    # what looks like an already-bracketed id.
+    def bracket_message_id(id)
+      s = sanitize(id)
+      return s if s.empty?
+      return s if s.start_with?("<") && s.end_with?(">")
+
+      "<#{s}>"
+    end
+  end
+end

data/lib/mailmate/mcp.rb

@@ -51,9 +51,18 @@ module Mailmate
       - Prefer `draft` over `send` whenever the user said "don't send" / "just
         draft it" — `draft` physically cannot send, so it's the safe choice.
         `send` also opens a draft and waits unless you pass `send_now: true`.
-      - Threading: set BOTH `in_reply_to` and `references`. A "Re:" subject
-        alone does not thread in modern clients. MailMate generates the
-        outgoing Message-ID itself.
+      - Replying: pass `reply_to` (the parent's eml-id or Message-ID) and the
+        threading headers, recipient and "Re:" subject are derived for you.
+        `reply_all_to` replies to all; `forward` forwards (supply `to`).
+        Fields you also pass explicitly win; ones you omit follow normal
+        reply rules. Prefer this over hand-setting in_reply_to/references —
+        a mis-built References chain sends fine and simply doesn't thread,
+        and nothing in your own view reveals it. A "Re:" subject alone never
+        threads. MailMate generates the outgoing Message-ID itself.
+        Full rules — the References chain, the merge rule, header safety —
+        are in the gem's docs/Composing and threading.md
+        (github.com/brianmd/mailmate), which is canonical; this summary
+        exists only so you need not follow a link mid-call.
 
       Modifying (modify)
       - Drives MailMate's UI via AppleScript: it briefly takes focus, calls are
@@ -80,22 +89,19 @@ module Mailmate
           Search MailMate's .eml files using MailMate's quicksearch syntax.
           Returns column-aligned CSV. Same engine as the `mmsearch` CLI.
 
-          Query = space-separated specs combined with AND (no or/parens yet).
-          Quote multi-word terms ("invoice due"). Modifiers:
-            (bare term)  From/To/Cc/Subject OR body contains
-            f <t> From    t <t> To/Cc    c <t> Cc    s <t> Subject
-            a <t> any address header    b <t> body    m <t> headers OR body
-            d <date>  received: Y, Y-M, Y-M-D, or relative 1d/2w/3m/1y
-            T <tag>   tag / IMAP keyword (K is a synonym)
-            !<value>  negate, e.g. f !smith  (From does NOT contain smith)
+          The only native key:value specs are the state forms below
+          (is:unread, has:attachment). Other familiar foreign tokens
+          (`from:bob`, `date:today`, `after:2026-08-01`, `older_than:2w`) are
+          auto-translated to quicksearch, and the rewrite is announced in the
+          result — that announcement means your query was translated, not
+          that it failed. Unrecognized keys (`in:inbox`, `filename:pdf`) are
+          searched as literal text and match nothing, silently.
+
+          #{Mailmate::SearchSyntax.reference(indent: "  ")}
+
           The `mailbox` arg also accepts a smart-mailbox name (e.g. Newsletters,
           Receipts, Priority) whose filter is ANDed into the search.
 
-          Examples:
-            query="f substack d 7d"        from Substack in the last 7 days
-            query="T urgent"               tagged "urgent"
-            query="s 'invoice due' !draft" subject has 'invoice due', not 'draft'
-
           Fields default to: flags date time direction party subject.
           Prefix with "+" to add to the defaults ("+tags +mailbox"); a bare
           list replaces them (id is always the first column). Meanings:
@@ -124,6 +130,7 @@ module Mailmate
             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." },
+            european: { type: "boolean", description: "Slash dates in the query are day-first (d 9/8/2026 = Aug 9). Default: month-first American." },
           },
           additionalProperties: false,
         },
@@ -239,11 +246,15 @@ module Mailmate
             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." },
+            reply_to: { type: "string", description: "Parent message to reply to — eml-id or RFC Message-ID. PREFER THIS over setting in_reply_to/references by hand: it derives In-Reply-To, the full References chain, the recipient and a \"Re:\" subject from the parent. Fields you also pass explicitly win; ones you omit follow normal reply rules." },
+            reply_all_to: { type: "string", description: "Same as reply_to but replies to all — adds the other recipients, minus the user own identities." },
+            forward: { type: "string", description: "Parent message to forward — eml-id or RFC Message-ID. Derives a \"Fwd:\" subject and the forwarded block; you supply `to`. A forward deliberately does NOT thread into the original conversation." },
+            quote: { type: "boolean", description: "Include the quoted original when replying/forwarding (default true). Set false to send only your own text." },
             in_reply_to: { type: "string", description: "Message-ID of the parent message (with or without angle brackets). Sets the In-Reply-To header on the outgoing message so recipients' clients thread it correctly." },
             references: { type: "string", description: "Space-separated chain of Message-IDs (with angle brackets). Conventionally: parent's References header + parent's Message-ID. Required alongside in_reply_to for clean threading in deep chains." },
             send_now: { type: "boolean", description: "Send immediately (skip the Drafts pause)." },
           },
-          required: %w[to subject body],
+          required: %w[body],
           additionalProperties: false,
         },
       },
@@ -262,10 +273,14 @@ module Mailmate
             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." },
+            reply_to: { type: "string", description: "Parent message to reply to — eml-id or RFC Message-ID. PREFER THIS over setting in_reply_to/references by hand: it derives In-Reply-To, the full References chain, the recipient and a \"Re:\" subject from the parent. Fields you also pass explicitly win; ones you omit follow normal reply rules." },
+            reply_all_to: { type: "string", description: "Same as reply_to but replies to all — adds the other recipients, minus the user own identities." },
+            forward: { type: "string", description: "Parent message to forward — eml-id or RFC Message-ID. Derives a \"Fwd:\" subject and the forwarded block; you supply `to`. A forward deliberately does NOT thread into the original conversation." },
+            quote: { type: "boolean", description: "Include the quoted original when replying/forwarding (default true). Set false to send only your own text." },
             in_reply_to: { type: "string", description: "Message-ID of the parent message (with or without angle brackets). Sets the In-Reply-To header so recipients' clients thread it correctly." },
             references: { type: "string", description: "Space-separated chain of Message-IDs (with angle brackets). Conventionally: parent's References header + parent's Message-ID. Required alongside in_reply_to for clean threading in deep chains." },
           },
-          required: %w[to subject body],
+          required: %w[body],
           additionalProperties: false,
         },
       },
@@ -416,6 +431,7 @@ module Mailmate
       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"]
+      argv.push("--european")                        if args["european"]
       # 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"]
@@ -455,7 +471,21 @@ module Mailmate
       with_stdin(payload) { run_cli(Mailmate::CLI::Verify, argv) }
     end
 
+    # `to` and `subject` used to be schema-required, which stopped working the
+    # moment a parent could supply them. JSON Schema can't say "required
+    # unless another field is present", so the check moved here — dropping it
+    # entirely would let a `to`-less call through to open an empty composer.
+    def recipient_check(args)
+      return nil if args["to"] || args["reply_to"] || args["reply_all_to"]
+      return nil if args["forward"] && args["to"]
+
+      text_error("no recipient: pass `to`, or `reply_to`/`reply_all_to` to derive it from the parent. " \
+                 "(`forward` derives the subject and body but not the recipient — pass `to` with it.)")
+    end
+
     def call_send(args)
+      (err = recipient_check(args)) and return err
+
       argv = compose_argv(args)
       argv << "--send-now" if args["send_now"]
       with_stdin(args["body"].to_s) { run_cli(Mailmate::CLI::Send, argv) }
@@ -464,6 +494,8 @@ module Mailmate
     # `draft` mirrors `send` but never sends — it has no send_now option and
     # routes through CLI::Draft, which refuses `--send-now` outright.
     def call_draft(args)
+      (err = recipient_check(args)) and return err
+
       argv = compose_argv(args)
       with_stdin(args["body"].to_s) { run_cli(Mailmate::CLI::Draft, argv) }
     end
@@ -477,21 +509,28 @@ module Mailmate
       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.push("--header", "In-Reply-To: #{bracket_mid(args["in_reply_to"])}") if args["in_reply_to"]
-      argv.push("--header", "References: #{args["references"]}")                if args["references"]
+      # Both values come from ANOTHER message, so both go through the shared
+      # sanitizer — see Mailmate::HeaderValue for why this is not open-coded.
+      argv.push("--header", "In-Reply-To: #{Mailmate::HeaderValue.bracket_message_id(args["in_reply_to"])}") if args["in_reply_to"]
+      argv.push("--header", "References: #{Mailmate::HeaderValue.sanitize(args["references"])}")             if args["references"]
+      # Parent-derived compose: hand the id to the CLI rather than deriving
+      # here. `reply_to` is what a caller should reach for over hand-setting
+      # in_reply_to/references — it builds the References chain from the
+      # parent, the step that is easy to get subtly wrong and impossible to
+      # notice afterwards (a mis-built chain sends fine and simply doesn't
+      # thread).
+      if (parent = args["reply_to"] || args["reply_all_to"] || args["forward"])
+        flag = if args["forward"] then "--forward"
+               elsif args["reply_all_to"] then "--reply-all-to"
+               else "--reply-to"
+               end
+        argv.push(flag, parent.to_s)
+        argv << "--no-quote" if args["quote"] == false
+      end
       Array(args["attachments"]).each { |p| argv << p.to_s }
       argv
     end
 
-    # Wrap a bare Message-ID in `<…>` if it doesn't already have them. Both
-    # forms are valid input to the MCP for ergonomics; the header value
-    # going on the wire needs the brackets per RFC 5322.
-    def bracket_mid(id)
-      s = id.to_s.strip
-      return s if s.start_with?("<") && s.end_with?(">")
-      "<#{s}>"
-    end
-
     def call_open(args)
       argv = [args["id"].to_s]
       argv << "--print" if args["print_only"]

data/lib/mailmate/reply_prefill.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "header_value"
+
+module Mailmate
+  # @api public
+  #
+  # Derive the fields of a reply / reply-all / forward from a parent message:
+  # recipients, subject, threading headers, and the quoted original.
+  #
+  # This is the ONE place the References chain is constructed. It is exposed as
+  # a library call (not just a CLI behavior) because consumers need the pieces
+  # WITHOUT sending — markdownr's compose popup fills a form from them, and
+  # `mm-send --reply-to` turns them into emate flags. Two implementations of
+  # "parent's References + parent's Message-ID" is how one of them silently
+  # stops threading; there is only this one.
+  #
+  # Rules it encodes (canonical prose: docs/Composing and threading.md):
+  #   * In-Reply-To = the parent's Message-ID.
+  #   * References  = the parent's References (if any) + the parent's
+  #     Message-ID appended; the bare Message-ID when the parent is a root.
+  #   * A forward does NOT thread. It is a new conversation sent to someone who
+  #     was not party to the original, so injecting the original's chain would
+  #     graft a stranger into a thread they can't see. Forward derives the
+  #     subject and the quoted original only.
+  module ReplyPrefill
+    extend self
+
+    MODES = %w[reply reply-all forward].freeze
+
+    class NotFound < StandardError; end
+
+    Prefill = Struct.new(
+      :mode, :from, :to, :cc, :subject, :in_reply_to, :references, :quoted_body,
+      :parent_message_id, :parent_eml_id,
+      keyword_init: true
+    ) do
+      def to_h
+        super.transform_keys(&:to_s)
+      end
+    end
+
+    # `input` is an eml-id or an RFC Message-ID (bracketed or not) — anything
+    # EmlLookup.resolve_id accepts. `identities` defaults to the configured
+    # list; pass an explicit array to override (markdownr passes what
+    # mmdiscover reported, which may be broader than config.yml).
+    def build(input, mode: "reply", identities: nil)
+      mode = mode.to_s
+      raise ArgumentError, "mode must be one of: #{MODES.join(', ')}" unless MODES.include?(mode)
+
+      mail, eml_id = load_parent(input)
+      idents = normalize_identities(identities)
+
+      message_id = HeaderValue.bracket_message_id(mail.message_id)
+      threading  = mode == "forward" ? { in_reply_to: nil, references: nil } : {
+        in_reply_to: presence(message_id),
+        references: build_references(mail, message_id)
+      }
+
+      Prefill.new(
+        mode: mode,
+        from: pick_from_identity(mail, idents),
+        to: derive_to(mail, mode),
+        cc: derive_cc(mail, mode, idents),
+        subject: derive_subject(mail, mode),
+        quoted_body: derive_quoted_body(mail, mode),
+        parent_message_id: presence(message_id),
+        parent_eml_id: eml_id,
+        **threading
+      )
+    end
+
+    private
+
+    def load_parent(input)
+      eml_id = Mailmate::EmlLookup.resolve_id(input)
+      raise NotFound, "couldn't resolve #{input.inspect} as an eml-id or Message-ID" if eml_id.nil? || eml_id.zero?
+
+      path = Mailmate::EmlLookup.path_for(eml_id)
+      raise NotFound, "no .eml on disk for eml-id #{eml_id}" unless path
+
+      require "mail"
+      [Mail.read(path), eml_id]
+    end
+
+    # References = parent's own chain + parent's Message-ID. A parent that is
+    # itself a thread root has no References, so the chain is just its id.
+    def build_references(mail, message_id)
+      old = HeaderValue.sanitize(mail["references"]&.value)
+      presence(old.empty? ? message_id : "#{old} #{message_id}".strip)
+    end
+
+    # Reply goes to Reply-To when the sender set one, else From. A forward has
+    # no derivable recipient — that's the caller's whole reason for forwarding.
+    def derive_to(mail, mode)
+      return [] if mode == "forward"
+
+      reply_to = addresses(mail.reply_to).first
+      [reply_to || addresses(mail.from).first].compact
+    end
+
+    # Reply-all carries the other recipients, minus every address of ours (so
+    # switching identity can't leave us Cc'ing ourselves) and minus whoever
+    # already landed in To.
+    def derive_cc(mail, mode, idents)
+      return [] unless mode == "reply-all"
+
+      to_lc = derive_to(mail, mode).map(&:downcase)
+      (addresses(mail.to) + addresses(mail.cc))
+        .reject { |a| idents.include?(a.downcase) || to_lc.include?(a.downcase) }
+        .uniq
+    end
+
+    def derive_subject(mail, mode)
+      subject = mail.subject.to_s.strip
+      mode == "forward" ? ensure_prefix(subject, "Fwd", /\Afwd?\s*:/i) : ensure_prefix(subject, "Re", /\Are\s*(?:\[\d+\])?\s*:/i)
+    end
+
+    # Conservative: never double-prefix, and leave an existing prefix in
+    # whatever case/shape the sender used (`RE:`, `Re[2]:`) alone.
+    def ensure_prefix(subject, word, already)
+      return "#{word}: " if subject.empty?
+      return subject if subject.match?(already)
+
+      "#{word}: #{subject}"
+    end
+
+    # Whichever of OUR addresses the parent was addressed to — so a reply goes
+    # out from the identity that received it, not from whatever MailMate
+    # defaults to. nil when we can't tell; the caller decides the fallback.
+    def pick_from_identity(mail, idents)
+      return nil if idents.empty?
+
+      candidates = addresses(mail.to) + addresses(mail.cc) + addresses(mail.bcc)
+      candidates.find { |a| idents.include?(a.downcase) }
+    end
+
+    # Reply: email-classic "On <date>, <sender> wrote:" + a `> `-prefixed body.
+    # Forward: the conventional un-prefixed forwarded-message block with its
+    # own header summary, since the recipient has never seen the original.
+    def derive_quoted_body(mail, mode)
+      body = plain_body(mail)
+      from = presence(mail["from"]&.value.to_s.strip) || "(unknown sender)"
+      date = mail["date"]&.value.to_s.strip
+
+      if mode == "forward"
+        header = ["---------- Forwarded message ----------",
+                  "From: #{from}",
+                  ("Date: #{date}" unless date.empty?),
+                  "Subject: #{mail.subject.to_s.strip}",
+                  ("To: #{mail['to'].value}" if mail["to"])].compact.join("\n")
+        return "#{header}\n\n#{body}"
+      end
+
+      attribution = date.empty? ? "#{from} wrote:" : "On #{date}, #{from} wrote:"
+      return "#{attribution}\n> [no plain-text alternative — paste the original manually]\n" if body.strip.empty?
+
+      quoted = body.sub(/\n+\z/, "").split("\n", -1).map { |l| "> #{l}".rstrip }.join("\n")
+      "#{attribution}\n#{quoted}\n"
+    end
+
+    # The text/plain alternative, or "" when the message is HTML-only. We do
+    # NOT synthesize text from the HTML part here: a lossy auto-conversion
+    # quoted back to the original sender is worse than an honest placeholder.
+    def plain_body(mail)
+      part = mail.multipart? ? mail.text_part : mail
+      return "" if part.nil?
+      return "" if part.respond_to?(:mime_type) && part.mime_type && part.mime_type != "text/plain"
+
+      part.body.decoded.to_s
+    rescue StandardError
+      ""
+    end
+
+    # Mail's address fields raise on malformed input often enough that a reply
+    # to a slightly-broken message shouldn't blow up the whole derivation.
+    def addresses(field)
+      Array(field).map { |a| a.to_s.strip }.reject(&:empty?)
+    rescue StandardError
+      []
+    end
+
+    def normalize_identities(identities)
+      list = identities.nil? ? Mailmate::Identity.list : Array(identities)
+      list.map { |a| a.to_s.downcase.strip }.reject(&:empty?)
+    end
+
+    def presence(str)
+      s = str.to_s.strip
+      s.empty? ? nil : s
+    end
+  end
+end