mailmate 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 284cbe7b6bd7c22400073332c186ec005a8c7bd7f60953084d7067ebf4ec9b6a
-  data.tar.gz: 5e5fa97e0c3eb222bc081c5d29ce611c65de9c159476075a844c91bf00cfcafa
+  metadata.gz: 34b3eb13fdd2c2a9ec690ec623a543c074014dc1e6b3f82aa3abe6e6cb8de2c7
+  data.tar.gz: 11417aa45bfa1980f946b6838ca4451c79e6fb2244976c5879253c37b96cbb72
 SHA512:
-  metadata.gz: 573429618b13cba013fcb7b4c07db6284335887f577fe0b8d4d2b3c91d2961815d6a32005254d7b848b5c71716a2ee7a0d011caa4a33ab7d35ac1c74c1448700
-  data.tar.gz: 7e3ef0a93e0462a60f97028a84e9d360e0c8560552100349bd0f348a962e5b76ccf4b5d5febfdefa1b522e8c73aa4934c1d5a17b1bc3c5cc84a185e49709c022
+  metadata.gz: d724662f4b0084dbbe7bb712f4678976b30654d26fa67479d038d203034c951a95d90b08c5e7266c7461103299ddb9c6dab03cd8ff3c83d09c7d2a6a9e0c7321
+  data.tar.gz: 1a56382a2a6792e0a0df2fc5e83ad26c51158238720c21bc9f7d222b3047dc013eb473dbee623ad0b23f6c53075489603b37d41f789f3019551bda0532443213

data/README.md

@@ -106,7 +106,7 @@ mmdiscover
 
 **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:
+`mmmessage --markdown` renders HTML-only message bodies as readable markdown, and (since 2.2.0) the quoted original of a reply or forward is the parent's HTML part rendered the same way, so it reads as the author laid it out. Both need the `reverse_markdown` gem, which has `nokogiri` as a transitive dependency:
 
 ```bash
 gem install reverse_markdown
@@ -114,7 +114,7 @@ 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 installed, `mmmessage` warns with a clear install hint and falls back to the raw HTML body (it does not abort — so the in-process MCP server survives a missing optional dependency). The plugin launcher and one-line installer attempt this gem automatically and degrade the same way if it fails to build.
+If you never use `--markdown` or compose from a parent, you never pay any of this. Without the gem, a reply/forward quotes the plain-text part instead (or an honest placeholder for an HTML-only parent); if you invoke `--markdown` without it, `mmmessage` warns with a clear install hint and falls back to the raw HTML body (it does not abort — so the in-process MCP server survives a missing optional dependency). The plugin launcher and one-line installer attempt this gem automatically and degrade the same way if it fails to build.
 
 ### From source (development)
 
@@ -201,7 +201,7 @@ The `--mailbox` argument accepts an account, an `account/path`, a bare mailbox n
 
 **Output fields.** Default columns are `flags date time direction party subject`. Prefix a field list with `+` to add to the defaults; a bare list replaces them (include `id` yourself if you want it).
 
-**Limiting and ordering.** `--limit N` returns the N *newest* matches, chosen after the full scan; `--limit-by KEY[:asc|desc]` changes which rows survive (`date:asc` = the N oldest). `--sort KEY[:asc|desc]` orders the emitted rows independently, so `--limit 10 --sort from` is the ten newest shown by sender. Bare `--sort asc|desc|none` still means date; a bare key reads the way the key does (date/time newest-first, text A→Z); ties break newest-first. A truncated result says so on stderr (`[limit] showing 200 of 319 matches …`) so stdout stays clean CSV. `--scan-limit N` is a different thing: it stops the *scan* after N matches in undefined order — a speed bound for slow `--all` body scans, never a way to pick rows. (Before 2.0, `--limit` had those scan-cap semantics: N arbitrary matches, however sorted.)
+**Limiting and ordering.** `--limit N` returns the N *newest* matches, chosen after the full scan; `--limit-by KEY[:asc|desc]` changes which rows survive (`date:asc` = the N oldest). `--sort KEY[:asc|desc]` orders the emitted rows independently, so `--limit 10 --sort from` is the ten newest shown by sender. Bare `--sort asc|desc|none` still means date; a bare key reads the way the key does (date/time newest-first, text A→Z); ties break newest-first. A truncated result says so on stderr (`[limit] showing 200 of 319 matches …`) so stdout stays clean CSV. `--scan-limit N` is a different thing: it stops the *scan* after N matches in undefined order — a speed bound for slow `--all` body scans, never a way to pick rows. (Before 2.0, `--limit` had those scan-cap semantics: N arbitrary matches, however sorted.) `--offset N` skips the first N rows of that ordering before taking `--limit` — rows 1001–1200 newest-first is `--offset 1000 --limit 200`; offsets drift as mail arrives, so a date term (`d <2026-08-25`) is the stable way to page a live mailbox. `--stats` replaces the prose notices with one machine-readable line, first on stderr — `stats: {"schema":1,"matches":321,"returned":3,"scan_capped":false,…}` — whose keys are additive-only; scripts and the MCP server read that instead of parsing prose.
 
 | Field | What it shows |
 |---|---|
@@ -385,7 +385,7 @@ mm-send -f you@x --reply-all-to 12345 --send-now <<<"body"
 mm-send -f you@x --forward 12345 -t someone@example.com <<<"FYI"
 ```
 
-The parent is an eml-id or an RFC Message-ID. **Fields you pass explicitly win; fields you omit follow normal reply rules**, and overriding a visible field never drops the threading headers. `--no-quote` suppresses the quoted original. `--print-prefill` prints the derived fields as JSON and sends nothing — the hook for other tools that fill their own compose form.
+The parent is an eml-id or an RFC Message-ID. **Fields you pass explicitly win; fields you omit follow normal reply rules**, and overriding a visible field never drops the threading headers. `--no-quote` suppresses the quoted original (the parent's HTML part rendered to markdown when it has one, else its plain text — see `docs/Composing and threading.md`). `--print-prefill` prints the derived fields as JSON and sends nothing — the hook for other tools that fill their own compose form.
 
 Hand-assembly via `--header` still works and is the escape hatch when the parent isn't in MailMate's index. The `mailmate-mcp` `send` / `draft` tools take `in_reply_to` and `references` directly.
 

data/docs/Composing and threading.md

@@ -47,6 +47,8 @@ mm-send -f you@x -t them@y -s "Re: foo" \
 
 When a parent is supplied, **explicitly-passed fields always win; omitted fields follow normal reply rules** (parent's sender becomes the recipient, subject becomes `Re: <original>`, the quoted original seeds the body, reply-all additionally carries the other recipients minus your own identities).
 
+**What "the quoted original" is** (2.2.0): the parent's HTML part rendered to markdown when it has one — so the quote reads as the author laid it out (headings, links, emphasis) rather than as the text/plain alternative many senders neglect — else the plain part, else an honest placeholder saying there is no readable text. Raw HTML is never quoted, and a quote is never silently empty. The rendering needs the optional `reverse_markdown` gem (the same one `mmmessage --markdown` uses); without it the plain part is used. Same in every mode; a forward wraps it in the `---------- Forwarded message ----------` header block, a reply prefixes it with `> `.
+
 This rule is uniform across every surface that composes from a parent — the CLI flags above and markdownr's compose popup — so a caller who learns it once can predict all of them. Overriding a visible field never drops the threading headers.
 
 ## Header safety

data/lib/mailmate/cli/message.rb

@@ -146,42 +146,21 @@ module Mailmate
         ct.include?("text/html") || body =~ /\A\s*<(?:!doctype html|html|body|head)\b/i
       end
 
-      # HTML → clean markdown for terminal reading. Three preprocessing /
-      # postprocessing passes beyond plain reverse_markdown:
-      #   1. Drop <style> and <script> blocks before conversion — pure clutter
-      #      that reverse_markdown otherwise dumps as inline text.
-      #   2. Strip zero-width spacers that newsletters use to control inbox
-      #      preview text (U+034F, U+200B/C/D, U+FEFF). Without this, you get
-      #      long runs of `͏ ` in the output.
-      #   3. Collapse 3+ consecutive blank lines into a single blank line.
+      # HTML → clean markdown for terminal reading, via the shared converter
+      # (Mailmate::HtmlMarkdown — ReplyPrefill quotes HTML-only parents with
+      # the same passes). Degrades to the raw HTML with a hint rather than
+      # `exit`: a library method must not kill its host, and the in-process
+      # MCP server would otherwise die on the SystemExit (its dispatch rescues
+      # StandardError only).
       def html_to_markdown(html)
-        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}) — falling back to raw HTML."
-          # Degrade to the raw HTML rather than `exit`: a library method must
-          # not kill its host, and the in-process MCP server would otherwise
-          # die on the SystemExit (its dispatch rescues StandardError only).
-          return html
-        end
-        doc = Nokogiri::HTML(html)
-        doc.css("style, script").remove
-        md = ReverseMarkdown.convert(doc.to_html)
-        # U+034F combining grapheme joiner, U+200B ZWSP, U+200C ZWNJ,
-        # U+200D ZWJ, U+FEFF BOM/ZWNBSP — newsletter preview-text padding.
-        md.gsub!(/[\u034F\u200B\u200C\u200D\uFEFF]/, "")
-        # Convert non-breaking spaces to regular spaces so rstrip can collapse
-        # them. Newsletter preview-text padding often uses runs of &nbsp; which
-        # Ruby's .rstrip leaves alone otherwise.
-        md.gsub!(/[\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]/, " ")
-        # Strip trailing whitespace per line - the spaces between the
-        # now-removed zero-width chars otherwise leave long whitespace runs.
-        md = md.lines.map(&:rstrip).join("\n")
-        md.gsub!(/\n{3,}/, "\n\n")
-        md.strip
+        require_relative "../html_markdown"
+        md = Mailmate::HtmlMarkdown.convert(html)
+        return md if md
+
+        warn "mmmessage --markdown needs the reverse_markdown gem (which pulls nokogiri)."
+        warn "Install it with:  gem install reverse_markdown"
+        warn "Falling back to raw HTML."
+        html
       end
     end
   end

data/lib/mailmate/cli/search.rb

@@ -4,6 +4,8 @@ require "mail"
 require "optparse"
 require "date"
 require "csv"
+require "json"
+require "stringio"
 
 module Mailmate
   module CLI
@@ -84,10 +86,10 @@ module Mailmate
 
       def run(argv)
         opts = {
-          mailbox: "all", limit: nil, scan_limit: nil, limit_by: DEFAULT_LIMIT_BY,
+          mailbox: "all", limit: nil, offset: 0, scan_limit: nil, limit_by: DEFAULT_LIMIT_BY,
           headers_only: false, all: false,
           exclude_quoted: false,
-          header: true, align: true, sort: DEFAULT_SORT,
+          header: true, align: true, sort: DEFAULT_SORT, stats: false,
         }
 
         parser = build_parser(opts)
@@ -98,14 +100,43 @@ module Mailmate
           return 2
         end
 
+        return search(argv, opts) unless opts[:stats]
+
+        # --stats promises one machine-readable line FIRST on stderr, but
+        # the run says other things there before the total is known (the
+        # translation notice, dead-branch warnings, [skip]s). Hold all of it
+        # back and release it, in order, after the stats line. A run that
+        # never reached the scan (usage error) produces no stats line — the
+        # held output is still released, so nothing is swallowed.
+        held = StringIO.new
+        real_err = $stderr
+        $stderr = held
+        begin
+          search(argv, opts)
+        ensure
+          $stderr = real_err
+          $stderr.puts "#{STATS_PREFIX}#{JSON.generate(opts[:stats_result])}" if opts[:stats_result]
+          $stderr.print held.string
+        end
+      end
+
+      # The `--stats` contract: this prefix, then one JSON object, on the
+      # first stderr line. `matches`, `returned` and `scan_capped` are always
+      # present; keys are additive-only, and `schema` increments only on a
+      # change that breaks that promise. Consumers (markdownr's search_mail,
+      # mailmate-mcp) parse this instead of the prose notices.
+      STATS_PREFIX = "stats: "
+      STATS_SCHEMA = 1
+
+      def search(argv, opts)
         self.date_order = opts[:european] ? :dmy : :mdy
 
-        search_string = argv[0] || DEFAULT_SEARCH
+        query = argv[0] || DEFAULT_SEARCH
         # Rewrite Gmail/Outlook-style key:value tokens to their exact
         # quicksearch equivalent — loudly, never silently: every rewrite is
         # announced on stderr so the transcript shows what actually ran (and
         # the caller learns the syntax). stdout stays clean CSV.
-        search_string, translations = Mailmate::SearchSyntax.translate(search_string, european: !!opts[:european])
+        search_string, translations = Mailmate::SearchSyntax.translate(query, european: !!opts[:european])
         if (notice = Mailmate::SearchSyntax.translation_notice(translations))
           warn notice
         end
@@ -193,19 +224,29 @@ module Mailmate
         # The scan stops exactly at --scan-limit, so hitting it is inferable.
         scan_capped = opts[:scan_limit] && rows.size >= opts[:scan_limit]
         total = rows.size
-        rows = apply_limit(rows, opts[:limit], opts[:limit_by], fields)
+        rows = apply_limit(rows, opts[:limit], opts[:offset], opts[:limit_by], fields)
         sort_rows!(rows, opts[:sort], fields)
         emit_output(rows.map(&:cells), fields, opts)
         # Truncation announces itself on stderr — same idiom as the
         # zero-result hint below: stdout stays clean CSV, exit status stays
-        # 0. When the scan cap fired, the match total is itself a sample, so
-        # the [limit] notice's "of M" would be false precision; the scan
-        # notice speaks alone.
-        if scan_capped
+        # 0. With --stats the JSON line carries it and the prose is
+        # suppressed. When the scan cap fired, the match total is itself a
+        # sample, so the [limit] notice's "of M" would be false precision;
+        # the scan notice speaks alone.
+        if opts[:stats]
+          opts[:stats_result] = {
+            schema: STATS_SCHEMA, matches: total, returned: rows.size,
+            limit: opts[:limit], offset: opts[:offset],
+            limit_by: order_to_s(opts[:limit_by]), sort: order_to_s(opts[:sort]),
+            scan_limit: opts[:scan_limit], scan_capped: !!scan_capped,
+            query: query, effective_query: search_string,
+          }
+        elsif scan_capped
           warn "[scan-limit] stopped scanning after #{total} matches in undefined order — " \
                "this is a sample, not the newest #{total}"
-        elsif opts[:limit] && total > opts[:limit]
-          warn "[limit] showing #{opts[:limit]} of #{total} matches (#{describe_order(opts[:limit_by])}); " \
+        elsif rows.size < total
+          from = opts[:offset].positive? ? ", from #{opts[:offset] + 1}" : ""
+          warn "[limit] showing #{rows.size} of #{total} matches#{from} (#{describe_order(opts[:limit_by])}); " \
                "add a date term such as `d 3d` to narrow, or raise --limit"
         end
         # A query written in another mail system's dialect is not a syntax
@@ -213,8 +254,10 @@ module Mailmate
         # nothing. Callers (people and agents alike) read that empty result
         # as "no such mail" and stop. Say so on stderr, so stdout stays
         # clean CSV and the exit status stays 0: the search DID run, it just
-        # cannot have found what the caller meant.
-        if rows.empty? && (hint = Mailmate::SearchSyntax.zero_result_hint(search_string))
+        # cannot have found what the caller meant. (Keyed on the match
+        # total, not the emitted rows: an --offset past the end is not a
+        # miss.)
+        if total.zero? && (hint = Mailmate::SearchSyntax.zero_result_hint(search_string))
           warn hint
         end
         0
@@ -250,6 +293,10 @@ module Mailmate
         { key: key, dir: dir.to_sym }
       end
 
+      def order_to_s(order)
+        order == :none ? "none" : "#{order[:key]}:#{order[:dir]}"
+      end
+
       def describe_order(order)
         return "scan order" if order == :none
         what = order[:key] == "date" ? (order[:dir] == :desc ? "newest first" : "oldest first")
@@ -268,32 +315,37 @@ module Mailmate
         end
       end
 
-      # Orders `rows` in place by `order` (`{key:, dir:}`), breaking ties
-      # newest-first and then by scan order — so "sorted by sender" lists each
-      # sender's mail newest-first, deterministically. Ruby's sort is not
-      # stable, and stable-over-readdir would only preserve the undefined
-      # order this exists to get rid of.
+      # Orders `rows` in place by `order` (`{key:, dir:}`). The order is
+      # TOTAL: ties break newest-first, then by eml-id (in the date's
+      # direction when date is the key, else newest-first) — so "sorted by
+      # sender" lists each sender's mail newest-first, and two runs of the
+      # same query page identically (`--offset` depends on that). Ruby's
+      # sort is not stable, and stable-over-readdir would only preserve the
+      # undefined order this exists to get rid of.
       def order_rows!(rows, order, fields)
         return rows.sort_by!(&:index) if order == :none
         return rows if rows.size < 2
         key, sign = order[:key], (order[:dir] == :desc ? -1 : 1)
+        id_sign = key == "date" ? sign : -1
         column = fields.index(key)
         rows.sort! do |a, b|
           c = (order_value(a, key, column) <=> order_value(b, key, column)) || 0
           c *= sign
           c = b.instant_or_epoch <=> a.instant_or_epoch if c.zero? && key != "date"
-          c = a.index <=> b.index if c.zero?
+          c = (a.eml_id.to_i <=> b.eml_id.to_i) * id_sign if c.zero?
           c
         end
       end
 
-      # Keeps the top `limit` rows by `limit_by`, taken over the FULL match
-      # set. Returns the same array when no cap applies. Rows come back in
-      # limit-by order; `sort_rows!` re-orders them for output.
-      def apply_limit(rows, limit, limit_by, fields)
-        return rows if limit.nil? || rows.size <= limit
+      # Keeps rows `offset` through `offset + limit` of the `limit_by`
+      # ordering, taken over the FULL match set. Returns the same array when
+      # no cap applies. Rows come back in limit-by order; `sort_rows!`
+      # re-orders them for output.
+      def apply_limit(rows, limit, offset, limit_by, fields)
+        return rows if offset.zero? && (limit.nil? || rows.size <= limit)
         order_rows!(rows, limit_by, fields)
-        rows.first(limit)
+        window = rows.drop(offset)
+        limit ? window.first(limit) : window
       end
 
       def sort_rows!(rows, order, fields)
@@ -322,6 +374,11 @@ module Mailmate
                "Return at most N rows: the top N by --limit-by (default: the N newest), taken after the full scan. Announces truncation on stderr.") { |n| opts[:limit] = n }
           o.on("--limit-by KEY[:DIR]",
                "Which rows --limit keeps. KEY is any output field; DIR is asc|desc (bare date/time = desc, text keys = asc). Default: date:desc") { |v| opts[:limit_by] = parse_order(v) }
+          o.on("--offset N", Integer,
+               "Skip the first N rows of the --limit-by ordering before taking --limit: rows 1001-1200 newest-first is --offset 1000 --limit 200. Pages of a live mailbox drift as mail arrives; a date term (d <2026-08-25) is the stable way to page.") { |n|
+            raise OptionParser::InvalidArgument, "#{n}: offset cannot be negative" if n.negative?
+            opts[:offset] = n
+          }
           o.on("--scan-limit N", Integer,
                "Stop SCANNING after N matches, in undefined order — a speed bound for slow --all body scans, never a way to pick rows. Announces on stderr.") { |n| opts[:scan_limit] = n }
           o.on("--headers-only", "Skip body matching entirely") { opts[:headers_only] = true }
@@ -331,6 +388,8 @@ module Mailmate
           o.on("--no-align", "Plain CSV (no column padding)") { opts[:align] = false }
           o.on("--sort KEY[:DIR]",
                "Order of the emitted rows. asc|desc|none alone mean date; or any output field, e.g. from, subject:desc (bare date/time = desc, text keys = asc). Ties break newest-first. Default: date:asc") { |v| opts[:sort] = parse_order(v, allow_none: true) }
+          o.on("--stats",
+               "Write one machine-readable line FIRST on stderr — stats: {\"schema\":1,\"matches\":M,\"returned\":N,\"scan_capped\":false,...} — in place of the [limit]/[scan-limit] prose. Keys are additive-only; other stderr follows it.") { opts[:stats] = true }
           o.on("--european",
                "Slash dates are day-first: d 9/8/2026 = Aug 9 (default: month-first American)") { opts[:european] = true }
           o.separator ""
@@ -1428,7 +1487,7 @@ module Mailmate
         # while the message is live, and ride along in Row#keys. `date` and
         # `id` never need extracting: every row carries instant + eml_id.
         extra_keys = [opts[:sort], opts[:limit_by]].grep(Hash).map { |o| o[:key] } - fields - %w[date id]
-        need_instant = opts[:sort] != :none || !opts[:limit].nil?
+        need_instant = opts[:sort] != :none || !opts[:limit].nil? || opts[:offset].positive?
         rows = []
         catch(:done) do
           dirs.each do |dir|

data/lib/mailmate/html_markdown.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # HTML → clean markdown, shared by `mmmessage --markdown` (terminal reading)
+  # and ReplyPrefill (quoting an HTML-only parent in a forward or reply).
+  #
+  # Depends on reverse_markdown (which pulls nokogiri), an OPTIONAL dependency
+  # so the base install stays free of native extensions. `available?` says
+  # whether the converter can run; `convert` returns nil when it can't, and
+  # each caller decides what an honest fallback looks like for its surface —
+  # mmmessage prints the raw HTML with a hint, a prefill uses a placeholder.
+  #
+  # Three passes beyond plain reverse_markdown, all learned from newsletters:
+  #   1. Drop <style> / <script> blocks and HTML comments before conversion —
+  #      pure clutter that reverse_markdown otherwise dumps as inline text.
+  #   2. Strip zero-width spacers used to control inbox preview text (U+034F,
+  #      U+200B/C/D, U+FEFF) and turn non-breaking spaces into plain ones, or
+  #      the output carries long runs of `͏ `.
+  #   3. Trim trailing whitespace per line and collapse 3+ blank lines to one.
+  module HtmlMarkdown
+    extend self
+
+    def available?
+      require "nokogiri"
+      require "reverse_markdown"
+      true
+    rescue LoadError
+      false
+    end
+
+    # Markdown String, or nil when the optional gems are missing.
+    def convert(html)
+      return nil unless available?
+
+      doc = Nokogiri::HTML(html.to_s)
+      doc.css("style, script").remove
+      # Comments too: newsletter templates leave `<!-- tdMobZ1BottomNew-->`
+      # markers that reverse_markdown would otherwise print verbatim.
+      doc.xpath("//comment()").remove
+      md = ReverseMarkdown.convert(doc.to_html)
+      # U+034F combining grapheme joiner, U+200B ZWSP, U+200C ZWNJ,
+      # U+200D ZWJ, U+FEFF BOM/ZWNBSP — newsletter preview-text padding.
+      md.gsub!(/[\u034F\u200B\u200C\u200D\uFEFF]/, "")
+      # Non-breaking spaces (and their Unicode cousins) → plain spaces so the
+      # per-line rstrip below can collapse the padding they hold open.
+      md.gsub!(/[\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]/, " ")
+      md = md.lines.map(&:rstrip).join("\n")
+      md.gsub!(/\n{3,}/, "\n\n")
+      md.strip
+    end
+  end
+end

data/lib/mailmate/mcp.rb

@@ -129,6 +129,7 @@ module Mailmate
             },
             limit: { type: "integer", description: "Return at most N rows — the top N by limit_by (default: the N newest), taken after the full scan. Truncation is announced on stderr, which is included in the result." },
             limit_by: { type: "string", description: "Which rows limit keeps: KEY[:asc|desc], KEY any output field (bare date/time = desc, text keys = asc). Default: date:desc (the N newest)." },
+            offset: { type: "integer", description: "Skip the first N rows of the limit_by ordering before taking limit (rows 1001-1200 = offset 1000, limit 200). Offsets drift as mail arrives; a date term in the query (d <2026-08-25) is the stable way to page." },
             scan_limit: { type: "integer", description: "Stop SCANNING after N matches, in undefined order — a speed bound for slow body scans, never a way to pick rows. Prefer limit." },
             headers_only: { type: "boolean", description: "Skip body matching (much faster on text searches)." },
             sort: { type: "string", description: "Order of the emitted rows: asc|desc|none (by date), or KEY[:asc|desc] for any output field, e.g. from, subject:desc. Ties break newest-first. Default: asc (date)." },
@@ -433,16 +434,27 @@ module Mailmate
       argv.push("--limit",      args["limit"].to_i.to_s)      if args["limit"]
       argv.push("--limit-by",   args["limit_by"].to_s)        if args["limit_by"]
       argv.push("--scan-limit", args["scan_limit"].to_i.to_s) if args["scan_limit"]
+      argv.push("--offset",     args["offset"].to_i.to_s)     if args["offset"]
       argv.push("--headers-only")                    if args["headers_only"]
       argv.push("--sort",    args["sort"].to_s)      if args["sort"]
       argv.push("--european")                        if args["european"]
+      # Always ask for the stats line: it carries the true match total and
+      # the truncation facts as one JSON object, first on stderr, in place
+      # of the prose notices. It stays in the text (readable as-is) and is
+      # ALSO surfaced as structuredContent for clients that render it.
+      argv.push("--stats")
       # 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)
+      res = run_cli(Mailmate::CLI::Search, argv)
+      if (m = res[:content].first[:text].match(/^#{Regexp.escape(Mailmate::CLI::Search::STATS_PREFIX)}(\{.*\})$/))
+        stats = (JSON.parse(m[1]) rescue nil)
+        res[:structuredContent] = { stats: stats } if stats
+      end
+      res
     end
 
     def call_message(args)

data/lib/mailmate/reply_prefill.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "header_value"
+require_relative "html_markdown"
 
 module Mailmate
   # @api public
@@ -138,30 +139,47 @@ module Mailmate
     # 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.
+    #
+    # Which body gets quoted, in both modes: the HTML part rendered to
+    # markdown first — so the quote reads as the author laid it out
+    # (headings, links, emphasis) rather than as the text/plain alternative
+    # senders often neglect — then the plain part, then an honest placeholder
+    # when neither yields text (an HTML-only source with reverse_markdown not
+    # installed). A quote is never silently empty, and raw HTML is never
+    # quoted. (Until 2026-09-04 a reply preferred the plain part and a forward
+    # of an HTML-only message quoted nothing at all — the bug that prompted
+    # this: a bank alert forwarded as a bare header block.)
     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"
+        body = quotable_body(mail) || FORWARD_PLACEHOLDER
         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}"
+        return "#{header}\n\n#{body.sub(/\n+\z/, '')}\n"
       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?
+      body = quotable_body(mail)
+      return "#{attribution}\n> #{REPLY_PLACEHOLDER}\n" if body.nil?
 
       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.
+    REPLY_PLACEHOLDER = "[no plain-text alternative — paste the original manually]"
+    FORWARD_PLACEHOLDER = "[the original has no readable text — it is HTML-only and the reverse_markdown gem is not installed; attach it or paste manually]"
+
+    # HTML-as-markdown, else plain text, else nil.
+    def quotable_body(mail)
+      presence(html_body_markdown(mail)) || presence(plain_body(mail))
+    end
+
+    # The text/plain alternative, or "" when the message is HTML-only.
     def plain_body(mail)
       part = mail.multipart? ? mail.text_part : mail
       return "" if part.nil?
@@ -172,6 +190,19 @@ module Mailmate
       ""
     end
 
+    # The text/html part rendered to markdown (Mailmate::HtmlMarkdown), or ""
+    # when there is no HTML part or the optional converter is missing.
+    # `decoded` (not `body.decoded`) so the part's declared charset — the
+    # iso-8859-1 of a bank alert — is transcoded to UTF-8 before parsing.
+    def html_body_markdown(mail)
+      part = mail.multipart? ? mail.html_part : (mail.content_type.to_s.downcase.include?("text/html") ? mail : nil)
+      return "" if part.nil?
+
+      Mailmate::HtmlMarkdown.convert(part.decoded.to_s).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)

data/lib/mailmate/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailmate
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Brian Murphy-Dye
@@ -145,6 +145,7 @@ files:
 - lib/mailmate/flag_check.rb
 - lib/mailmate/header_reader.rb
 - lib/mailmate/header_value.rb
+- lib/mailmate/html_markdown.rb
 - lib/mailmate/identity.rb
 - lib/mailmate/index_reader.rb
 - lib/mailmate/lexer.rb
@@ -182,7 +183,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Ruby toolkit for MailMate on macOS — search, read, modify, send, and smart-mailbox
   evaluation