mailmate 1.8.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2563290d07b7e90281a78c4161337f8fe94a21d4cd1f42501946a6c8107be5da
-  data.tar.gz: 04600cc5e50d4a4518ddcd27cc210d357decfeefb32e8adc1e3bb1624af17781
+  metadata.gz: 284cbe7b6bd7c22400073332c186ec005a8c7bd7f60953084d7067ebf4ec9b6a
+  data.tar.gz: 5e5fa97e0c3eb222bc081c5d29ce611c65de9c159476075a844c91bf00cfcafa
 SHA512:
-  metadata.gz: d4619d78ed6224df84378ad42cff61865653e32e463b8c8b3ad1349549f32c8bf74c6635e64f377653231d3a93afc087fba18cf6da9ad2897fe97c68e096d58a
-  data.tar.gz: a1437ae600957dedc21446c151cbc6061d1def590693f83359fcd79f5d1dd36e57bcbad4ab9ecb85a7621910119a14d30b21f97eb4b90aebc826b3dc9a0f873e
+  metadata.gz: 573429618b13cba013fcb7b4c07db6284335887f577fe0b8d4d2b3c91d2961815d6a32005254d7b848b5c71716a2ee7a0d011caa4a33ab7d35ac1c74c1448700
+  data.tar.gz: 7e3ef0a93e0462a60f97028a84e9d360e0c8560552100349bd0f348a962e5b76ccf4b5d5febfdefa1b522e8c73aa4934c1d5a17b1bc3c5cc84a185e49709c022

data/README.md

@@ -169,8 +169,11 @@ mmsearch 's "invoice due" !draft'
 # Received in May 2026
 mmsearch 'd 2026-05'
 
-# Custom columns + cap results + raw CSV (no padding)
+# Custom columns + the 20 newest + raw CSV (no padding)
 mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
+
+# The 10 newest from acme, listed by sender (not the 10 alphabetically-first senders)
+mmsearch 'f acme' --limit 10 --sort from
 ```
 
 **Quicksearch syntax.** The search-string is a list of specs combined with **AND**; a bare `or` separates alternatives, and AND binds tighter (no parens — write `(f bob or f ann) s invoice` out as `f bob s invoice or f ann s invoice`). After `or`, a bare first term inherits the modifier in force: `d 2024 or 2025 or 2y`. Wrap multi-word terms in `"double quotes"` (also how to search for the literal word "or"). `mmsearch --help` is the canonical, always-current rendering of this table.
@@ -185,17 +188,20 @@ mmsearch 'f acme' 'id flags subject from' --limit 20 --no-align
 | `a <term>` | Any address header contains. |
 | `b <term>` | Body (plain text) contains. |
 | `m <term>` | Common headers OR body. |
-| `d <date>` | Received: `Nh` (rolling clock hours, `24h` = last 24 hours), `Nd`/`Nw`/`Nm`/`Ny` (N calendar units ending today — `1d` = today, `2d` = yesterday + today), or absolute `Y`, `Y-M`, `Y-M-D`. Slash dates are month-first American (`8/9/2026` = Aug 9); `--european` flips to day-first. Comparisons on absolute dates: `d >2026-08` (after), `d <2026-08` (before), also `>=`/`<=`. |
+| `d <date>` | Received: `Nh` (rolling clock hours, `24h` = last 24 hours), `Nd`/`Nw`/`Nm`/`Ny` (calendar units floored to the unit start, app parity — `1d` = today, `1w` = this week, `1y` = this year), absolute `Y`, `Y-M`, `Y-M-D`, or day-of-month `D` / `M-D` (`d 7` = the most recent 7th). Slash dates are month-first American (`8/9/2026` = Aug 9); `--european` flips to day-first. Comparisons on absolute dates: `d >2026-08` (after), `d <2026-08` (before), also `>=`/`<=`. |
 | `T <tag>` | Tags / IMAP keywords (`K` is a synonym). |
-| `is:<state>` | Message state: `is:unread`, `is:read`, `is:flagged`, `is:replied`, `is:draft` (Gmail synonyms `starred`/`answered` work; `-is:unread` negates). |
-| `has:attachment` | Root MIME type is `multipart/mixed` — the standard attachment layout. |
+| `is:<state>` | Message state: `is:unread`, `is:read`, `is:flagged`, `is:replied`, `is:draft`, `is:archived` (Gmail synonyms `starred`/`answered` work; `-is:unread` negates; `in:inbox`/`in:archive` translate onto `is:archived`). |
+| `has:attachment` | Root MIME type is `multipart/mixed`; wrapper types (`signed`/`encrypted`/`related`) are opened and checked for real attachments. |
+| `<header>:<term>` | Any indexed header contains (`delivered-to:joe`). A header this store has never seen is a usage error, not an empty result. |
 | `!<value>` | Negate, e.g. `f !smith` = From does NOT contain smith; works on dates too (`d !3d` = more than 3 days ago). |
 
 Dates match on the **display-zone day** — the same day the `date`/`time` output columns show. An impossible date term or combination (`d 2026-02-31`, `d >2026 d <2025`) is a usage error, not a silent empty result. Familiar foreign `key:value` tokens (`from:bob`, `date:today`, `after:2026-08-01`, `older_than:2w`) are auto-translated to quicksearch with each rewrite announced on stderr; unrecognized keys (`is:unread`) are searched as literal text, and an empty result says so.
 
 The `--mailbox` argument accepts an account, an `account/path`, a bare mailbox name matched across accounts, or a **smart-mailbox name** (e.g. `Newsletters`, `Receipts`, `Priority`) whose filter is ANDed into the search.
 
-**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 (`id` is always the first column).
+**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.)
 
 | Field | What it shows |
 |---|---|
@@ -433,6 +439,8 @@ A few rough edges to be aware of:
 
 ## Status
 
+1.9.0 — App-parity search release. Arbitrary header specs are native (`delivered-to:joe`, `x-mailer.name:mailmate` — subpaths search the whole header value); index-only by design: a header the store has never seen is a usage error suggesting quotes, never a `Mail.read` per candidate. Relative calendar units now floor to the unit start, matching the app's documented semantics (`1w` = this week, `1y` = this year; `Nh` stays a rolling clock window on purpose). Day-of-month terms (`d 7` = the most recent 7th, `d 12-25` = last Christmas) close the last known silent-empty. `is:archived` joins the state specs (path-derived, same source as the flags column), with `in:inbox`/`in:archive` translating onto it; `has:attachment` now opens `multipart/signed`/`encrypted`/`related` wrappers and checks for real attachments. New `rake release` runs the whole mechanical release — clean-tree + green-tests + unreleased-version guards, then build, tag, sync, `gem push`.
+
 1.8.0 — Reply derivation, and message-state specs.
 
 **Composing:** replies and forwards are now derived from the parent instead of hand-assembled. `mm-send` / `mm-draft` gain `--reply-to <id>`, `--reply-all-to <id>`, `--forward <id>` (eml-id or Message-ID), which compute `In-Reply-To`, the full `References` chain, recipients and the `Re:`/`Fwd:` subject, plus `--no-quote` and `--print-prefill` (derived fields as JSON, sends nothing). The MCP `send`/`draft` tools take the same `reply_to` / `reply_all_to` / `forward` arguments. Explicitly-passed fields win over derived ones, and overriding a visible field never drops the threading headers. A forward deliberately does *not* thread into the original conversation. The chain is built in exactly one place (`Mailmate::ReplyPrefill`), and `--header` values now route through one sanitizer (`Mailmate::HeaderValue`) — previously the MCP's own argv builder lacked the CR/LF defense that stops a parent `Message-ID` smuggling extra headers. All of it is documented once in [docs/Composing and threading.md](docs/Composing%20and%20threading.md), which the README, `--help` preambles and MCP instructions now point at rather than restate. Every `exe/` command answers `--version`, so consumers can check the installed version instead of probing for a flag (the CLIs pass unknown flags through to `emate`, which makes flag-probing unsafe). The gemspec finally carries `homepage` and `metadata`, so the rubygems page links back to the source.

data/lib/mailmate/cli/search.rb

@@ -38,6 +38,27 @@ module Mailmate
         "archive"   => "a",
       }.freeze
 
+      # One matched message on its way to the output. `cells` are the
+      # extracted output columns in `fields` order; `keys` holds the values
+      # of any sort/limit key that is NOT an output column (extracted while
+      # the message was live, so ordering never re-reads a .eml); `instant`
+      # is the absolute send time (nil when unknown); `index` is scan order,
+      # the last-resort tie-break. Ordering keys off these, never off the
+      # cells — a bare fields list may omit `id`, and the old
+      # `rows[0].to_i` shortcut silently sorted such runs by readdir order.
+      Row = Struct.new(:eml_id, :index, :instant, :cells, :keys) do
+        def instant_or_epoch = instant || Time.at(0)
+      end
+
+      # `--sort` / `--limit-by` values: `{ key: <field>, dir: :asc|:desc }`,
+      # or :none (sort only). Omitted `--sort` keeps the historical
+      # date-ascending output; omitted `--limit-by` keeps the N newest.
+      DEFAULT_SORT     = { key: "date", dir: :asc }.freeze
+      DEFAULT_LIMIT_BY = { key: "date", dir: :desc }.freeze
+      # A bare KEY (no :DIR) reads the way the key does: dates newest-first,
+      # text A→Z.
+      DESC_BY_DEFAULT = %w[date time].freeze
+
       # All output fields are now index-tier: MailMate maintains a per-header
       # binary index under Database.noindex/Headers/, so extracting from/to/
       # subject/etc. doesn't require opening the .eml. Spec/filter matching
@@ -63,13 +84,19 @@ module Mailmate
 
       def run(argv)
         opts = {
-          mailbox: "all", limit: nil, headers_only: false, all: false,
+          mailbox: "all", limit: nil, scan_limit: nil, limit_by: DEFAULT_LIMIT_BY,
+          headers_only: false, all: false,
           exclude_quoted: false,
-          header: true, align: true, sort: :asc,
+          header: true, align: true, sort: DEFAULT_SORT,
         }
 
         parser = build_parser(opts)
-        parser.parse!(argv)
+        begin
+          parser.parse!(argv)
+        rescue OptionParser::ParseError => e
+          warn e.message
+          return 2
+        end
 
         self.date_order = opts[:european] ? :dmy : :mdy
 
@@ -163,8 +190,24 @@ module Mailmate
           opts: opts,
         )
 
-        sort_rows!(rows, opts[:sort])
-        emit_output(rows, fields, opts)
+        # 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)
+        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
+          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])}); " \
+               "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
         # error here — it parses as a literal term and quietly matches
         # nothing. Callers (people and agents alike) read that empty result
@@ -177,22 +220,84 @@ module Mailmate
         0
       end
 
-      # ---- sort ---------------------------------------------------------------
+      # ---- ordering -----------------------------------------------------------
+      #
+      # Two orderings, two questions. `--limit-by` answers WHICH rows survive
+      # the cap (the N newest, by default); `--sort` answers the ORDER they
+      # are emitted in. They coincide when both are date — the default — and
+      # diverge exactly when MailMate's UI would: "sort by sender, limit 10"
+      # is the 10 newest shown by sender, not the 10 alphabetically-first
+      # senders. Both are applied AFTER the full scan; the only pre-scan
+      # bound is --scan-limit, which picks nothing (see build_parser).
+
+      # Parses a `--sort`/`--limit-by` value: bare `asc`/`desc` (date, kept
+      # for existing invocations), `none` (sort only), `KEY`, or `KEY:DIR`.
+      def parse_order(value, allow_none: false)
+        v = value.to_s.strip
+        return :none if v == "none" && allow_none
+        return { key: "date", dir: v.to_sym } if %w[asc desc].include?(v)
+        key, dir = v.split(":", 2)
+        key = "date" if key.nil? || key.empty?
+        unless VALID_FIELDS.include?(key)
+          raise OptionParser::InvalidArgument,
+                "#{value}: unknown field '#{key}' (valid: #{VALID_FIELDS.join(' ')})"
+        end
+        dir = (DESC_BY_DEFAULT.include?(key) ? "desc" : "asc") if dir.nil? || dir.empty?
+        unless %w[asc desc].include?(dir)
+          raise OptionParser::InvalidArgument,
+                "#{value}: direction must be asc or desc#{allow_none ? ' (or bare none)' : ''}"
+        end
+        { key: key, dir: dir.to_sym }
+      end
+
+      def describe_order(order)
+        return "scan order" if order == :none
+        what = order[:key] == "date" ? (order[:dir] == :desc ? "newest first" : "oldest first")
+                                     : "#{order[:key]} #{order[:dir] == :desc ? 'descending' : 'ascending'}"
+        "#{what} by #{order[:key]}"
+      end
 
-      # Sorts `rows` in place by the message's absolute send instant (UTC), so
-      # senders in different timezones still order correctly. The first column
-      # is always `id` (forced in `run`), which lets us hit the `#date` index
-      # without re-reading any .eml.
-      def sort_rows!(rows, mode)
-        return rows if mode == :none || rows.size < 2
-        reader = Mailmate::IndexReader.for("#date") rescue nil
-        epoch = Time.at(0)
-        rows.sort_by! do |r|
-          s = reader && (reader.value_for(r[0].to_i) rescue nil)
-          (s && !s.empty? && (fast_time(s) || (Time.parse(s) rescue nil))) || epoch
+      # The sort key value for one row. `date` is the absolute send instant
+      # (so senders in different timezones still order correctly), `id` is
+      # numeric, everything else is the column text, case-folded.
+      def order_value(row, key, column)
+        case key
+        when "date" then row.instant_or_epoch
+        when "id"   then row.eml_id.to_i
+        else (column ? row.cells[column] : row.keys[key]).to_s.downcase
+        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.
+      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)
+        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
         end
-        rows.reverse! if mode == :desc
-        rows
+      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
+        order_rows!(rows, limit_by, fields)
+        rows.first(limit)
+      end
+
+      def sort_rows!(rows, order, fields)
+        order_rows!(rows, order, fields)
       end
 
       # ---- option parsing -----------------------------------------------------
@@ -213,14 +318,19 @@ module Mailmate
           o.separator "OPTIONS"
           o.on("--mailbox X", "Mailbox to search (default: all)") { |v| opts[:mailbox] = v }
           o.on("--fields F", "Fields list (alt to 2nd positional)") { |v| opts[:fields] = v }
-          o.on("--limit N", Integer, "Stop after N matches") { |n| opts[:limit] = n }
+          o.on("--limit N", Integer,
+               "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("--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 }
           o.on("--all", "Include un-indexed messages in body matching by lazily reading and parsing each .eml. Slow (tens of seconds to minutes on large archives). Default behavior matches MailMate's UI: only check messages MailMate has body-indexed — fast, but bounded.") { opts[:all] = true }
           o.on("--exclude-quoted", "Match body only against #unquoted text — skip MailMate's #quoted index (forwarded/replied-to text). Tightens search to fresh content; gets you closer to MailMate UI's body-search result set, at the cost of missing hits in quoted sections.") { opts[:exclude_quoted] = true }
           o.on("--no-header", "Suppress column header row") { opts[:header] = false }
           o.on("--no-align", "Plain CSV (no column padding)") { opts[:align] = false }
-          o.on("--sort MODE", %w[asc desc none],
-               "Sort rows by date+time: asc (default), desc, none") { |v| opts[:sort] = v.to_sym }
+          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("--european",
                "Slash dates are day-first: d 9/8/2026 = Aug 9 (default: month-first American)") { opts[:european] = true }
           o.separator ""
@@ -405,6 +515,14 @@ module Mailmate
               # Gmail callers actually write.
               negate ||= operand.start_with?("-")
               specs << [:state, operand.delete_prefix("-").downcase, negate]
+            elsif !quoted && (hdr = header_spec_token(operand))
+              # Arbitrary header specs (delivered-to:joe) — native app
+              # syntax per the manual. Foreign keys (date:, from:, ...) never
+              # reach here: translate() rewrote the translatable ones before
+              # parsing, and the rest stay literal so zero_result_hint can
+              # suggest their quicksearch equivalent.
+              negate ||= operand.start_with?("-")
+              specs << [:header, hdr, negate]
             else
               # A bare term opening an or-group inherits the modifier in
               # force (`d 2024 or 2025`). Elsewhere it is MailMate's
@@ -420,13 +538,29 @@ module Mailmate
         [specs, in_force]
       end
 
+      # The downcased "name:value" for a bare token that should parse as an
+      # arbitrary-header spec, nil otherwise. Excluded: keys the translator
+      # owns (FOREIGN_KEYS — their untranslatable forms stay literal for the
+      # zero-result hint), state keys (is/has, handled first), and
+      # URL-shaped tokens (http://... is a term, not a search of the
+      # nonexistent "http" header).
+      def header_spec_token(operand)
+        m = operand.match(/\A-?([A-Za-z][\w-]*(?:\.[\w.-]+)?):(\S+)\z/)
+        return nil unless m
+        return nil if m[2].start_with?("/")
+        key = Mailmate::SearchSyntax.normalize_key(m[1].sub(/\..*/, ""))
+        return nil if Mailmate::SearchSyntax::FOREIGN_KEYS.include?(key)
+        return nil if %w[is has].include?(key)
+        "#{m[1]}:#{m[2]}".downcase
+      end
+
       # Static cost rank per spec field for AND evaluation order: compiled
       # date compare < header/tag index lookup < body matching (resolves
       # part-ids and walks every body segment). Used by order_specs.
       SPEC_COST = {
         date: 0,
         from: 1, recipients: 1, cc: 1, subject: 1, address_any: 1, any: 1,
-        tag: 1, keyword: 1, state: 1,
+        tag: 1, keyword: 1, state: 1, header: 1,
         body: 2, message_or_body: 2,
       }.freeze
 
@@ -438,6 +572,7 @@ module Mailmate
         "flagged" => :flagged, "starred" => :flagged,
         "replied" => :replied, "answered" => :replied,
         "draft" => :draft,
+        "archived" => :archived, "archive" => :archived,
         "attachment" => :attachment, "attachments" => :attachment,
       }.freeze
 
@@ -528,16 +663,23 @@ module Mailmate
         if term =~ /\A(\d+)([dwmy])\z/
           n, u = Regexp.last_match(1).to_i, Regexp.last_match(2)
           return nil if n.zero? # a zero-length window matches nothing
-          # N units ENDING today: `1d` = today only, `7d` = the last 7
-          # calendar days including today. (Off-by-one fixed 2026-08-11 to
-          # match the MailMate app, where `d 1d` is today's mail — the old
-          # cutoff of today-N made `d 1d` span two calendar days. For a
-          # rolling 24-hour clock window, that's `d 24h` now.)
+          # Calendar units floored to the unit start, matching the app's
+          # documented semantics ("1y means this year and not 365 days"):
+          # 1d = today, 1w = this ISO week (from Monday), 1m = this month,
+          # 1y = this year; N reaches back N-1 further units. Only `Nh` is a
+          # rolling clock window — that split is deliberate (2026-08-18):
+          # calendar words mean calendar spans, and "the last 24 hours" is
+          # spelled d 24h.
           cutoff = case u
                    when "d" then today - (n - 1)
-                   when "w" then today - (n * 7 - 1)
-                   when "m" then (today << n) + 1
-                   when "y" then (today << (n * 12)) + 1
+                   when "w"
+                     start = today - (7 * (n - 1))
+                     start - (start.cwday - 1)
+                   when "m"
+                     start = today << (n - 1)
+                     Date.new(start.year, start.month, 1)
+                   when "y"
+                     Date.new(today.year - (n - 1), 1, 1)
                    end
           return [ymd_int(cutoff), 9999_12_31]
         end
@@ -547,15 +689,34 @@ module Mailmate
 
         case parts.size
         when 1
-          y = parts[0].to_i
-          return nil if y.zero?
-          [y * 10_000 + 101, y * 10_000 + 1231]
+          if parts[0].length == 4
+            y = parts[0].to_i
+            return nil if y.zero?
+            [y * 10_000 + 101, y * 10_000 + 1231]
+          else
+            # App semantics: a bare small number is a day of the current
+            # month — or the most recent month containing that day when it
+            # hasn't happened yet (`d 7` on the 5th = last month's 7th).
+            most_recent_day_range(parts[0].to_i, today)
+          end
         when 2
-          # Year-first (2026-08) or month-first with a 4-digit year (8/2026).
-          y, m = parts[1].length == 4 ? [parts[1], parts[0]] : [parts[0], parts[1]]
-          y, m = y.to_i, m.to_i
-          return nil if y.zero? || !(1..12).cover?(m)
-          [y * 10_000 + m * 100 + 1, y * 10_000 + m * 100 + 31]
+          if parts[1].length == 4
+            # Month-first with a 4-digit year (8/2026).
+            y, m = parts[1].to_i, parts[0].to_i
+            return nil if y.zero? || !(1..12).cover?(m)
+            [y * 10_000 + m * 100 + 1, y * 10_000 + m * 100 + 31]
+          elsif parts[0].length == 4
+            # Year-first (2026-08).
+            y, m = parts[0].to_i, parts[1].to_i
+            return nil if y.zero? || !(1..12).cover?(m)
+            [y * 10_000 + m * 100 + 1, y * 10_000 + m * 100 + 31]
+          else
+            # No year: month + day, ordered per date_order, most recent
+            # occurrence (`d 12-25` in August = last year's Dec 25).
+            a, b = parts.map(&:to_i)
+            m, d = date_order == :dmy ? [b, a] : [a, b]
+            most_recent_month_day_range(m, d, today)
+          end
         when 3
           # ISO year-first, or slash-date with trailing 4-digit year ordered
           # per date_order. Impossible calendar dates (2026-02-31, month 13)
@@ -590,7 +751,14 @@ module Mailmate
           # would otherwise quietly match no message ever.
           if field == :state && !STATE_CANON.key?(term.split(":", 2).last)
             return "state term cannot match anything: #{term} " \
-                   "(known: is:unread is:read is:flagged is:replied is:draft has:attachment)"
+                   "(known: is:unread is:read is:flagged is:replied is:draft is:archived has:attachment)"
+          end
+          if field == :header
+            name = term.split(":", 2).first.sub(/\..*/, "")
+            if reader_for(name).nil?
+              return "no '#{name}' header index — this MailMate store has never seen that " \
+                     "header. Quote the token (\"#{term}\") to search it as literal text."
+            end
           end
           next unless field == :date
           range = hour_range_for(term) || date_range_for(term)
@@ -615,6 +783,33 @@ module Mailmate
         nil
       end
 
+      # Single day for the most recent occurrence of day-of-month `day`,
+      # stepping back past months that lack it (`d 31` in early March =
+      # Jan 31). nil when no month within a year works (day > 31).
+      def most_recent_day_range(day, today)
+        return nil unless (1..31).cover?(day)
+        0.upto(12) do |back|
+          m = today << back
+          next unless Date.valid_date?(m.year, m.month, day)
+          candidate = Date.new(m.year, m.month, day)
+          return [ymd_int(candidate), ymd_int(candidate)] if candidate <= today
+        end
+        nil
+      end
+
+      # Single day for the most recent occurrence of month+day: this year if
+      # it has happened, else last year. nil for impossible dates.
+      def most_recent_month_day_range(month, day, today)
+        return nil unless (1..12).cover?(month) && (1..31).cover?(day)
+        [0, 1].each do |back|
+          y = today.year - back
+          next unless Date.valid_date?(y, month, day)
+          candidate = Date.new(y, month, day)
+          return [ymd_int(candidate), ymd_int(candidate)] if candidate <= today
+        end
+        nil
+      end
+
       # `13/8/2026` under month-first ordering is month 13 — almost certainly
       # a day-first date (and vice versa). Name the likely fix instead of
       # leaving the generic cannot-match.
@@ -785,27 +980,54 @@ module Mailmate
       end
 
       # term is the full lowercased token ("is:unread", "has:attachment").
-      # Flag states read the #flags index; attachment presence reads the
-      # indexed root content-type — multipart/mixed is the standard
-      # attachment layout (a Mail fallback checks real attachments when the
-      # message is already loaded). Unknown state values never reach here:
+      # Flag states read the #flags index; archive state reads the path
+      # (same source as the flags output column); attachment presence reads
+      # the indexed root content-type — multipart/mixed is the standard
+      # attachment layout. Wrapper types that can HIDE attachments
+      # (signed/encrypted/related) fall back to reading the message and
+      # asking Mail for real attachments; plain and alternative roots are
+      # trusted as attachment-free. Unknown state values never reach here:
       # date_spec_error rejects them up front.
-      def state_matches?(eml_id, mail, term)
+      def state_matches?(eml_id, mail, path, term)
         state = STATE_CANON[term.split(":", 2).last]
         return false unless state
 
         case state
         when :unread
           eml_id ? !message_flags(eml_id).include?("\\Seen") : false
+        when :archived
+          path.to_s.include?("/Archive.mailbox/")
         when :attachment
           ct = eml_id ? (reader_for("content-type")&.value_for(eml_id.to_i) rescue nil).to_s : ""
-          return ct.downcase.include?("multipart/mixed") unless ct.empty?
-          mail ? mail.attachments.any? : false
+          if ct.empty?
+            m = mail || (path && (Mail.read(path) rescue nil))
+            return m ? m.attachments.any? : false
+          end
+          ctl = ct.downcase
+          return true if ctl.include?("multipart/mixed")
+          if ctl.match?(%r{multipart/(signed|encrypted|related)})
+            m = mail || (path && (Mail.read(path) rescue nil))
+            return m ? m.attachments.any? : false
+          end
+          false
         else
           message_flags(eml_id).include?(STATE_FLAGS[state])
         end
       end
 
+      # term is the downcased "name:value" (subpath allowed on the name and
+      # ignored: `x-mailer.name:mailmate` searches the whole x-mailer value,
+      # which substring matching covers anyway). Index-only by design — a
+      # header this store has never seen has no index, and date_spec_error
+      # reports that up front instead of this method quietly missing.
+      def header_matches?(eml_id, mail, term)
+        name, value = term.split(":", 2)
+        name = name.sub(/\..*/, "")
+        v = eml_id ? (reader_for(name)&.value_for(eml_id.to_i) rescue nil) : nil
+        v = (mail[name]&.to_s rescue nil) if v.nil? && mail
+        v.to_s.b.downcase.include?(value.b)
+      end
+
       def message_flags(eml_id)
         return [] unless eml_id
         reader_for("#flags")&.flags_for(eml_id.to_i) || []
@@ -906,7 +1128,9 @@ module Mailmate
               when :date
                 date_matches?(mail, eml_id, term)
               when :state
-                state_matches?(eml_id, mail, term)
+                state_matches?(eml_id, mail, path, term)
+              when :header
+                header_matches?(eml_id, mail, term)
               when :any
                 %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
               end
@@ -1052,7 +1276,7 @@ module Mailmate
       # Absolute send time for an eml_id, preferring the MailMate `#date` index
       # (cheap, no .eml read). Falls back to the parsed mail's Date header.
       def message_time(eml_id, mail)
-        s = (Mailmate::IndexReader.for("#date").value_for(eml_id.to_i) rescue nil)
+        s = (reader_for("#date")&.value_for(eml_id.to_i) rescue nil)
         if s && !s.empty?
           t = fast_time(s) || (Time.parse(s) rescue nil)
           return t if t
@@ -1077,7 +1301,7 @@ module Mailmate
       # safely interleave with UTF-8 strings in joined output rows.
       def header_index_value(eml_id, name)
         return nil if eml_id.nil?
-        v = Mailmate::IndexReader.for(name).value_for(eml_id.to_i)
+        v = reader_for(name)&.value_for(eml_id.to_i)
         v && v.dup.force_encoding("UTF-8").scrub
       rescue ArgumentError
         nil
@@ -1200,6 +1424,11 @@ module Mailmate
 
       def collect_rows(dirs:, specs:, fields:, smart_evaluator:, smart_literals:, filter_only_tier:, load_tier:, opts:)
         reset_run_caches!
+        # Sort/limit keys that are not output columns are extracted here,
+        # 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?
         rows = []
         catch(:done) do
           dirs.each do |dir|
@@ -1240,8 +1469,10 @@ module Mailmate
                 end
               end
 
-              rows << fields.map { |f| extract(f, eml_id, path, mail) }
-              throw :done if opts[:limit] && rows.size >= opts[:limit]
+              cells = fields.map { |f| extract(f, eml_id, path, mail) }
+              keys  = extra_keys.to_h { |k| [k, extract(k, eml_id, path, mail)] }
+              rows << Row.new(eml_id, rows.size, need_instant ? message_time(eml_id, mail) : nil, cells, keys)
+              throw :done if opts[:scan_limit] && rows.size >= opts[:scan_limit]
             end
           end
         end

data/lib/mailmate/mcp.rb

@@ -127,9 +127,11 @@ module Mailmate
               type: "string",
               description: "Account, mailbox path, or smart-mailbox name. Default: all.",
             },
-            limit: { type: "integer", description: "Stop after N matches." },
+            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)." },
+            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", enum: %w[asc desc none], description: "Sort by date+time. Default: asc." },
+            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)." },
             european: { type: "boolean", description: "Slash dates in the query are day-first (d 9/8/2026 = Aug 9). Default: month-first American." },
           },
           additionalProperties: false,
@@ -428,7 +430,9 @@ module Mailmate
     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("--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("--headers-only")                    if args["headers_only"]
       argv.push("--sort",    args["sort"].to_s)      if args["sort"]
       argv.push("--european")                        if args["european"]

data/lib/mailmate/search_syntax.rb

@@ -24,10 +24,11 @@ module Mailmate
       ["a <term>", "any address header contains"],
       ["b <term>", "body contains"],
       ["m <term>", "common headers OR body (same as a bare term)"],
-      ["d <date>", "received: Nh (rolling clock hours), Nd|Nw|Nm|Ny (N calendar units ending today; 1d = today), or Y, Y-M, Y-M-D"],
+      ["d <date>", "received: Nh (rolling clock hours), Nd|Nw|Nm|Ny (calendar, floored: 1d = today, 1w = this week, 1y = this year), Y | Y-M | Y-M-D, or D | M-D (day of month, most recent occurrence)"],
       ["T <tag>",  "tag / IMAP keyword contains (K is a synonym)"],
-      ["is:<state>", "message state: unread, read, flagged, replied, draft"],
-      ["has:attachment", "root MIME is multipart/mixed (the standard attachment layout)"],
+      ["is:<state>", "message state: unread, read, flagged, replied, draft, archived"],
+      ["has:attachment", "root MIME is multipart/mixed (wrappers like signed/related are opened and checked)"],
+      ["<header>:<term>", "any indexed header contains (delivered-to:joe); unknown header = error"],
     ].freeze
 
     EXAMPLES = [
@@ -39,7 +40,8 @@ module Mailmate
       ["d 24h",                   "received in the last 24 hours (rolling, not calendar)"],
       ["d >=2026-05 d <2026-08",  "received May through July 2026"],
       ["d 1h or 2026-08-09",      "last hour, plus everything from Aug 9"],
-      ["is:unread d 7d",          "unread, received in the last 7 days"],
+      ["is:unread d 1w",          "unread, received this week"],
+      ["d 7",                     "day 7 of this month (last month's if the 7th is still ahead)"],
       ["T urgent",                "tagged 'urgent'"],
     ].freeze
 
@@ -260,6 +262,14 @@ module Mailmate
         (rel = parse_relative(value)) && "d #{rel}"
       when "older_than", "older"
         (rel = parse_relative(value)) && "d !#{rel}"
+      when "in"
+        # Archive state is path-derived, so Gmail's location idiom maps onto
+        # the is:archived state spec. Other locations (in:trash, in:spam)
+        # have no equivalent and stay flagged.
+        case value.downcase
+        when "archive", "archived" then "is:archived"
+        when "inbox"               then "!is:archived"
+        end
       end
     end
 

data/lib/mailmate/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailmate
 version: !ruby/object:Gem::Version
-  version: 1.8.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Brian Murphy-Dye