mailmate 0.2.0 → 1.0.0

data/lib/mailmate/cli/open.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Mailmate
+  module CLI
+    # `mmopen` — open one MailMate message in the MailMate UI by handing the
+    # `mid:` URL to macOS's `open`. Read-side (doesn't change message state),
+    # but activates MailMate's window and brings it forward.
+    #
+    # Accepts any of the six id forms `EmlLookup.resolve_id` understands —
+    # eml-id, RFC Message-ID with or without angle brackets, message://… URL,
+    # or mid:… URL.
+    # @api private
+    module Open
+      extend self
+
+      def run(argv)
+        opts = parse_options(argv)
+        input = argv.first
+        return usage_error("missing <id>") if input.nil? || input.empty?
+
+        eml_id = Mailmate::EmlLookup.resolve_id(input)
+        if eml_id.nil? || eml_id.zero?
+          warn "mmopen: not found: #{input.inspect} (couldn't resolve as eml-id or Message-ID)"
+          return 1
+        end
+
+        path = Mailmate::EmlLookup.path_for(eml_id)
+        unless path
+          warn "mmopen: not found: #{eml_id}.eml"
+          return 1
+        end
+
+        message_id = Mailmate::HeaderReader.message_id(path)
+        unless message_id
+          warn "mmopen: could not find Message-ID in #{path}"
+          return 1
+        end
+
+        url = Mailmate::MidUrl.for(message_id)
+        if opts[:print_only]
+          $stdout.puts url
+          return 0
+        end
+
+        system("/usr/bin/open", url)
+        $?.exitstatus
+      end
+
+      def parse_options(argv)
+        opts = { print_only: false }
+        OptionParser.new do |o|
+          o.banner = "Usage: mmopen <id> [--print]"
+          o.separator ""
+          o.separator "Open a MailMate message in MailMate's UI. <id> can be a local"
+          o.separator "eml-id, an RFC Message-ID (with or without angle brackets), or"
+          o.separator "a message://… or mid:… URL."
+          o.on("--print", "Print the mid: URL instead of opening it (for piping)") { opts[:print_only] = true }
+        end.parse!(argv)
+        opts
+      end
+
+      def usage_error(msg)
+        warn "mmopen: #{msg}"
+        warn "Usage: mmopen <id> [--print]"
+        2
+      end
+    end
+  end
+end

data/lib/mailmate/cli/search.rb

@@ -22,10 +22,14 @@ module Mailmate
         "d" => :date, "T" => :tag, "K" => :keyword
       }.freeze
 
-      HEADER_FIELDS = %i[from recipients cc subject address_any any].freeze
+      # Filter modifiers that read from MailMate's per-header indexes —
+      # zero .eml reads when matching. `field_value` consults them via
+      # `header_index_value_lc`. Kept as a constant for documentation;
+      # the prefilter no longer uses it (indexes are the prefilter now).
+      INDEXED_FILTER_FIELDS = %i[from recipients cc subject address_any any].freeze
 
       VALID_FIELDS = %w[id path mailbox from to cc bcc reply-to subject date time
-                        message-id references in-reply-to
+                        message-id message-url references in-reply-to
                         direction party flags read archive tags keywords].freeze
 
       HEADER_LABELS = {
@@ -34,6 +38,11 @@ module Mailmate
         "archive"   => "a",
       }.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
+      # (the `f`/`t`/`s` modifiers in the search string) still parses the
+      # .eml header block — migrating that side is a separate change.
       FIELD_TIERS = {
         "id" => :index, "path" => :index, "mailbox" => :index,
         "date" => :index, "time" => :index,
@@ -42,18 +51,20 @@ module Mailmate
         "flags" => :index,
         "tags" => :index,
         "keywords" => :index,
-        "from" => :header, "to" => :header, "cc" => :header, "bcc" => :header,
-        "reply-to" => :header, "subject" => :header, "message-id" => :header,
-        "references" => :header, "in-reply-to" => :header,
-        "direction" => :header, "party" => :header,
+        "from" => :index, "to" => :index, "cc" => :index, "bcc" => :index,
+        "reply-to" => :index, "subject" => :index, "message-id" => :index,
+        "message-url" => :index,
+        "references" => :index, "in-reply-to" => :index,
+        "direction" => :index, "party" => :index,
       }.freeze
 
       DEFAULT_SEARCH = "d 1d"
-      DEFAULT_FIELDS = "flags date time direction party subject"
+      DEFAULT_FIELDS = "id flags date time direction party subject"
 
       def run(argv)
         opts = {
-          mailbox: "all", limit: nil, headers_only: false,
+          mailbox: "all", limit: nil, headers_only: false, all: false,
+          exclude_quoted: false,
           header: true, align: true, sort: :asc,
         }
 
@@ -62,10 +73,15 @@ module Mailmate
 
         search_string = argv[0] || DEFAULT_SEARCH
         fields_arg    = (opts[:fields] || argv[1] || DEFAULT_FIELDS).to_s.strip
-        # `+...` means "defaults plus these"; bare list replaces defaults.
+        # `+...` means "defaults plus these"; bare list = exactly those columns.
+        # Defaults already include `id` as the first column, so `+x` keeps id
+        # automatic while a bare list lets callers omit it (useful for
+        # `mmsearch foo 'message-id' | sort | uniq` where leading per-row ids
+        # would defeat the dedup).
         fields_arg    = "#{DEFAULT_FIELDS} #{fields_arg[1..]}" if fields_arg.start_with?("+")
-        extra_fields  = fields_arg.split(/\s+/).reject(&:empty?)
-        fields = (["id"] + extra_fields).uniq
+        # Split on whitespace OR commas (or both) so callers can pass
+        # 'subject message-id', 'subject,message-id', or any mix.
+        fields = fields_arg.split(/[\s,]+/).reject(&:empty?).uniq
 
         imap_root = Mailmate.config.imap_root
         unless File.directory?(imap_root)
@@ -106,16 +122,11 @@ module Mailmate
           end
 
         filter_tier      = composed_ast ? Mailmate::FilterClassifier.tier(composed_ast) : :index
-        specs_tier =
-          if specs.empty?
-            :index
-          elsif specs.any? { |field, _, _| (field == :body || field == :message_or_body) && !opts[:headers_only] }
-            :full
-          elsif specs.all? { |field, _, _| %i[date tag keyword].include?(field) }
-            :index
-          else
-            :header
-          end
+        # Every spec is now index-tier. Body matching reads MailMate's
+        # `#unquoted#lc`/`#quoted#lc` indexes (zero .eml read for indexed
+        # messages); `body_value` lazily Mail.reads the .eml for the rare
+        # misses. Header/tag/date specs all hit per-header indexes too.
+        specs_tier = :index
         fields_tier_     = fields_tier(fields)
         filter_only_tier = Mailmate::FilterClassifier.combine_tiers(filter_tier, specs_tier)
         load_tier        = Mailmate::FilterClassifier.combine_tiers(filter_only_tier, fields_tier_)
@@ -162,15 +173,18 @@ module Mailmate
           o.separator ""
           o.separator "POSITIONAL ARGS"
           o.separator "  search-string  Quicksearch expression. Default: 'd 1d'. Pass '' to disable."
-          o.separator "  fields         Space-separated columns to show (id is always first)."
-          o.separator "                 Default: 'flags date time direction party subject'."
-          o.separator "                 Prefix with '+' to add to the defaults: '+tags' = defaults + tags."
+          o.separator "  fields         Columns to show. Space- or comma-separated."
+          o.separator "                 Default: 'id flags date time direction party subject'."
+          o.separator "                 Bare list = exactly those columns (omit 'id' to drop it)."
+          o.separator "                 Prefix with '+' to extend the defaults: '+tags' = defaults + tags."
           o.separator ""
           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("--headers-only", "Skip body matching") { opts[:headers_only] = true }
+          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],
@@ -207,6 +221,7 @@ module Mailmate
           o.separator "  reply-to    Reply-To header"
           o.separator "  subject       Subject header"
           o.separator "  message-id    RFC Message-ID header"
+          o.separator "  message-url   message://%3C<MID>%3E — portable, paste-ready cross-machine ref"
           o.separator "  references    RFC References header (space-joined when multiple)"
           o.separator "  in-reply-to   RFC In-Reply-To header"
           o.separator "  date        received date, YYYY-MM-DD (local time)"
@@ -375,20 +390,41 @@ module Mailmate
 
       # ---- field-value matching -----------------------------------------------
 
-      def field_value(mail, field)
+      # Lowercased index value for a header — tries `<name>#lc` (MailMate's
+      # pre-downcased index) first, falls back to `<name>` + downcase. Returns
+      # nil if neither index has a record for this eml-id.
+      def header_index_value_lc(eml_id, name)
+        v = header_index_value(eml_id, "#{name}#lc")
+        return v unless v.nil?
+        raw = header_index_value(eml_id, name)
+        raw&.downcase
+      end
+
+      # Substring-match haystack for a filter modifier. Index-first; mail
+      # fallback only kicks in for the no-index case (tests, fresh installs,
+      # messages MailMate hasn't indexed yet).
+      def field_value(eml_id, mail, field)
         case field
         when :from
-          [Array(mail.from), mail[:from]&.value.to_s].flatten.join(" ").downcase
+          idx = header_index_value_lc(eml_id, "from")
+          return idx if idx && !idx.empty?
+          mail ? [Array(mail.from), mail[:from]&.value.to_s].flatten.join(" ").downcase : ""
         when :recipients
-          [Array(mail.to), Array(mail.cc), mail[:to]&.value.to_s, mail[:cc]&.value.to_s]
-            .flatten.join(" ").downcase
+          parts = %w[to cc].map { |n| header_index_value_lc(eml_id, n) }.compact.reject(&:empty?)
+          return parts.join(" ") unless parts.empty?
+          mail ? [Array(mail.to), Array(mail.cc), mail[:to]&.value.to_s, mail[:cc]&.value.to_s].flatten.join(" ").downcase : ""
         when :cc
-          [Array(mail.cc), mail[:cc]&.value.to_s].flatten.join(" ").downcase
+          idx = header_index_value_lc(eml_id, "cc")
+          return idx if idx && !idx.empty?
+          mail ? [Array(mail.cc), mail[:cc]&.value.to_s].flatten.join(" ").downcase : ""
         when :subject
-          mail.subject.to_s.downcase
+          idx = header_index_value_lc(eml_id, "subject")
+          return idx if idx && !idx.empty?
+          mail ? mail.subject.to_s.downcase : ""
         when :address_any
-          [mail[:from], mail[:to], mail[:cc], mail[:reply_to], mail[:sender]]
-            .compact.map { |h| h.value.to_s }.join(" ").downcase
+          parts = %w[from to cc reply-to sender].map { |n| header_index_value_lc(eml_id, n) }.compact.reject(&:empty?)
+          return parts.join(" ") unless parts.empty?
+          mail ? [mail[:from], mail[:to], mail[:cc], mail[:reply_to], mail[:sender]].compact.map { |h| h.value.to_s }.join(" ").downcase : ""
         end
       end
 
@@ -408,35 +444,105 @@ module Mailmate
         ""
       end
 
-      def matches?(mail, eml_id, specs, headers_only)
+      # Lowercased body substring-match haystack. Three-layer fallback:
+      #
+      #   1. MailMate's #unquoted#lc + #quoted#lc indexes — pre-decoded,
+      #      pre-downcased body text. Zero .eml read. The fast path; covers
+      #      the overwhelming majority of indexed mail. Body indexes are
+      #      keyed by body-part-id (not envelope-id), so we resolve the
+      #      envelope to its child parts via PartLookup, then aggregate every
+      #      segment record across both indexes.
+      #   2. If no index record AND the caller already has a parsed Mail
+      #      object, use text_body(mail) (same as before the migration).
+      #   3. If no index record AND no preloaded Mail, lazily Mail.read the
+      #      .eml on demand. Slow, but only happens for the rare message
+      #      MailMate hasn't body-indexed yet — far cheaper than the old
+      #      always-load behavior.
+      #
+      # `index_only: true` short-circuits after step 1 (no fallback to mail or
+      # to disk). Same coverage and speed as MailMate's own UI body search:
+      # instant, but limited to messages MailMate has body-indexed.
+      def body_value(eml_id, mail, path, index_only: false, exclude_quoted: false)
+        texts = body_index_records(eml_id, exclude_quoted: exclude_quoted)
+        return texts.join(" ") unless texts.empty?
+        return "" if index_only
+        return text_body(mail) if mail
+        return "" if path.nil?
+        begin
+          text_body(Mail.read(path))
+        rescue StandardError
+          ""
+        end
+      end
+
+      # Lowercased body-text segments from MailMate's #unquoted#lc and
+      # #quoted#lc indexes, aggregated across every body-part of the envelope.
+      # Returns [] if MailMate hasn't body-indexed the message.
+      #
+      # Body indexes are keyed by body-part-id and are multi-record (one
+      # record per text segment — paragraph/line/table row). For multipart
+      # messages we ask PartLookup for the child part-ids. For single-part
+      # messages PartLookup returns [] (envelope-id == body-part-id is not
+      # recorded in #root-body-part); we fall back to looking up the envelope
+      # eml-id directly so those messages still match.
+      #
+      # `exclude_quoted: true` drops #quoted#lc (forwarded / replied-to text),
+      # tightening recall toward MailMate UI's body-search semantics.
+      def body_index_records(eml_id, exclude_quoted: false)
+        return [] if eml_id.nil?
+        envelope = eml_id.to_i
+        part_ids = Mailmate::PartLookup.body_parts_of(envelope)
+        part_ids = [envelope] if part_ids.empty?
+
+        index_names = exclude_quoted ? %w[#unquoted#lc] : %w[#unquoted#lc #quoted#lc]
+        texts = []
+        index_names.each do |name|
+          reader =
+            begin
+              Mailmate::IndexReader.for(name)
+            rescue ArgumentError
+              next
+            end
+          part_ids.each do |pid|
+            reader.values_for(pid).each do |v|
+              next if v.nil? || v.empty?
+              texts << v.dup.force_encoding("UTF-8").scrub
+            end
+          end
+        end
+        texts
+      end
+
+      def matches?(mail, eml_id, specs, headers_only, path = nil, index_only: false, exclude_quoted: false)
         specs.all? do |field, term, negate|
           hit =
             case field
             when :from, :recipients, :cc, :subject, :address_any
-              field_value(mail, field).include?(term)
+              field_value(eml_id, mail, field).include?(term)
             when :tag, :keyword
               tag_value(eml_id).include?(term)
             when :body
-              headers_only ? false : text_body(mail).include?(term)
+              headers_only ? false : body_value(eml_id, mail, path, index_only: index_only, exclude_quoted: exclude_quoted).include?(term)
             when :message_or_body
-              common = %i[from recipients subject].any? { |f| field_value(mail, f).include?(term) }
-              common || (!headers_only && text_body(mail).include?(term))
+              common = %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term) }
+              common || (!headers_only && body_value(eml_id, mail, path, index_only: index_only, exclude_quoted: exclude_quoted).include?(term))
             when :date
               date_matches?(mail, eml_id, term)
             when :any
-              %i[from recipients subject].any? { |f| field_value(mail, f).include?(term) }
+              %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term) }
             end
           negate ? !hit : hit
         end
       end
 
       # ---- pre-filter ---------------------------------------------------------
-
-      def can_prefilter?(specs)
-        specs.any? do |field, term, negate|
-          !negate && HEADER_FIELDS.include?(field) && term.bytesize >= 3 && term.ascii_only?
-        end
-      end
+      #
+      # Filter modifiers (f/t/s/c/a) now match through MailMate's per-header
+      # indexes — index lookup IS the prefilter, no .eml read needed. The
+      # only remaining use of the .eml header-block grep is smart-mailbox
+      # filters that reference literal strings in arbitrary headers; those
+      # still benefit from a quick header-block scan to skip non-matching
+      # messages before any full evaluation.
 
       def header_block(path)
         bytes = +""
@@ -451,19 +557,10 @@ module Mailmate
         bytes.downcase
       end
 
-      def prefilter_pass?(path, specs, smart_literals = [])
-        return true if !can_prefilter?(specs) && smart_literals.empty?
+      def prefilter_pass?(path, _specs, smart_literals = [])
+        return true if smart_literals.empty?
         hdr = header_block(path)
-        specs.each do |field, term, negate|
-          next if negate
-          next unless HEADER_FIELDS.include?(field)
-          next unless term.bytesize >= 3 && term.ascii_only?
-          return false unless hdr.include?(term)
-        end
-        smart_literals.each do |lit|
-          return false unless hdr.include?(lit)
-        end
-        true
+        smart_literals.all? { |lit| hdr.include?(lit) }
       rescue StandardError
         true
       end
@@ -487,21 +584,65 @@ module Mailmate
 
       # ---- field extraction ---------------------------------------------------
 
-      def outbound?(path, mail)
+      # MailMate keeps a per-header binary index under Database.noindex/Headers/
+      # — one cache/offsets file per RFC header name. Reading from there is
+      # O(1) and skips the .eml entirely. Returns nil if the index is missing
+      # (e.g. tests against a synthetic config) or if the eml-id isn't in it,
+      # so callers can fall back to a parsed `Mail` object.
+      #
+      # IndexReader returns the cache substring as ASCII-8BIT (raw bytes from
+      # File.binread). Force UTF-8 + scrub here so values from the index can
+      # 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 && v.dup.force_encoding("UTF-8").scrub
+      rescue ArgumentError
+        nil
+      end
+
+      def index_or_mail(eml_id, name, fallback)
+        v = header_index_value(eml_id, name)
+        return v if v && !v.empty?
+        fallback.to_s
+      end
+
+      # First bare email address from a header value, lower-cased. Accepts
+      # either "Name <addr>" or "addr"; for comma-separated lists, returns
+      # the first one.
+      def first_address(value)
+        return nil if value.nil? || value.empty?
+        first = value.split(",").first.to_s.strip
+        addr = first =~ /<([^>]+)>/ ? Regexp.last_match(1) : first
+        addr.to_s.downcase
+      end
+
+      # Split a comma-separated address-list header value into individual
+      # tokens, each kept in its original "Name <addr>" form.
+      def split_addresses(value)
+        return [] if value.nil? || value.empty?
+        value.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def outbound?(path, mail, eml_id = nil)
         return true if path.include?("/Sent Mail.mailbox/") ||
                        path.include?("/Sent Messages.mailbox/") ||
                        path.include?("/Drafts.mailbox/")
-        from = Array(mail.from).first.to_s.downcase
+        from = first_address(header_index_value(eml_id, "from")) ||
+               Array(mail&.from).first.to_s.downcase
         Mailmate::Identity.mine?(from)
       end
 
-      def party_for(mail, outbound)
+      def party_for(eml_id, mail, outbound)
         if outbound
-          others = Mailmate::Identity.reject_mine(Array(mail.to) + Array(mail.cc))
-          others = Array(mail.to) if others.empty?
+          to_str = index_or_mail(eml_id, "to", mail ? Array(mail.to).join(", ") : "")
+          cc_str = index_or_mail(eml_id, "cc", mail ? Array(mail.cc).join(", ") : "")
+          tokens = split_addresses(to_str) + split_addresses(cc_str)
+          others = Mailmate::Identity.reject_mine(tokens.map { |t| first_address(t) || t })
+          others = split_addresses(to_str) if others.empty?
           others.join("; ")
         else
-          Array(mail.from).join("; ")
+          index_or_mail(eml_id, "from", mail ? Array(mail.from).join("; ") : "")
         end
       end
 
@@ -530,17 +671,20 @@ module Mailmate
           flags.reject { |f| f.start_with?("\\", "$") }.join(",")
         when "keywords"
           (Mailmate::IndexReader.for("#flags").flags_for(eml_id.to_i) rescue []).join(",")
-        when "from"       then mail ? Array(mail.from).join("; ") : nil
-        when "to"         then mail ? Array(mail.to).join("; ") : nil
-        when "cc"         then mail ? Array(mail.cc).join("; ") : nil
-        when "bcc"        then mail ? Array(mail.bcc).join("; ") : nil
-        when "reply-to"   then mail ? Array(mail.reply_to).join("; ") : nil
-        when "subject"     then mail&.subject.to_s
-        when "message-id"  then mail&.message_id.to_s
-        when "references"  then mail ? Array(mail.references).join(" ") : nil
-        when "in-reply-to" then mail ? Array(mail.in_reply_to).join(" ") : nil
-        when "direction"   then mail ? (outbound?(path, mail) ? "→" : "←") : nil
-        when "party"      then mail ? party_for(mail, outbound?(path, mail)) : nil
+        when "from"        then index_or_mail(eml_id, "from",        mail ? Array(mail.from).join("; ")     : nil)
+        when "to"          then index_or_mail(eml_id, "to",          mail ? Array(mail.to).join("; ")       : nil)
+        when "cc"          then index_or_mail(eml_id, "cc",          mail ? Array(mail.cc).join("; ")       : nil)
+        when "bcc"         then index_or_mail(eml_id, "bcc",         mail ? Array(mail.bcc).join("; ")      : nil)
+        when "reply-to"    then index_or_mail(eml_id, "reply-to",    mail ? Array(mail.reply_to).join("; ") : nil)
+        when "subject"     then index_or_mail(eml_id, "subject",     mail&.subject)
+        when "message-id"  then index_or_mail(eml_id, "message-id",  mail&.message_id)
+        when "message-url"
+          mid = index_or_mail(eml_id, "message-id", mail&.message_id)
+          mid.empty? ? "" : Mailmate::MidUrl.message_url_for(mid)
+        when "references"  then index_or_mail(eml_id, "references",  mail ? Array(mail.references).join(" ")  : nil)
+        when "in-reply-to" then index_or_mail(eml_id, "in-reply-to", mail ? Array(mail.in_reply_to).join(" ") : nil)
+        when "direction"   then outbound?(path, mail, eml_id) ? "→" : "←"
+        when "party"       then party_for(eml_id, mail, outbound?(path, mail, eml_id))
         end.to_s
       end
 
@@ -588,7 +732,8 @@ module Mailmate
                   next unless smart_evaluator.matches?(Mailmate::Message.new(nil, eml_id, path))
                 end
                 if !specs.empty?
-                  next unless matches?(nil, eml_id, specs, opts[:headers_only])
+                  next unless matches?(nil, eml_id, specs, opts[:headers_only], path,
+                                       index_only: !opts[:all], exclude_quoted: opts[:exclude_quoted])
                 end
               end
 
@@ -604,7 +749,8 @@ module Mailmate
 
               if filter_only_tier != :index
                 if !specs.empty?
-                  next unless matches?(mail, eml_id, specs, opts[:headers_only])
+                  next unless matches?(mail, eml_id, specs, opts[:headers_only], path,
+                                       index_only: !opts[:all], exclude_quoted: opts[:exclude_quoted])
                 end
                 if smart_evaluator
                   next unless smart_evaluator.matches?(Mailmate::Message.new(mail, eml_id, path))

data/lib/mailmate/cli/tags.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+
+module Mailmate
+  module CLI
+    # `mmtags` — list user tags MailMate knows about.
+    #
+    # Default: tags actually present on messages, counted from the `#flags`
+    # index (system flags like `\Seen`, `$Forwarded` are excluded — only
+    # user tags). Sorted by count desc.
+    #
+    # `--defined`: tags MailMate has registered in Preferences → Tags
+    # (read from Tags.plist). May include tags that aren't on any message yet.
+    # @api private
+    module Tags
+      extend self
+
+      TAGS_PLIST_FILENAME = "Tags.plist"
+
+      def run(argv)
+        opts = parse_options(argv)
+        if opts[:defined]
+          emit_defined
+        else
+          emit_used
+        end
+        0
+      end
+
+      def parse_options(argv)
+        opts = { defined: false }
+        OptionParser.new do |o|
+          o.banner = "Usage: mmtags [--defined]"
+          o.separator ""
+          o.separator "Default: tags actually applied to messages, with usage counts"
+          o.separator "(read from MailMate's #flags index; system flags excluded)."
+          o.separator ""
+          o.on("--defined", "List tags defined in MailMate Preferences → Tags") { opts[:defined] = true }
+        end.parse!(argv)
+        opts
+      end
+
+      # ---- tags in use (#flags index) ----------------------------------------
+
+      def emit_used
+        counts = used_tag_counts
+        width  = counts.keys.map(&:length).max || 3
+        width  = [width, "tag".length].max
+        $stdout.puts "#{"tag".ljust(width)}  count"
+        counts.sort_by { |tag, n| [-n, tag] }.each do |tag, n|
+          $stdout.puts "#{tag.ljust(width)}  #{n}"
+        end
+      end
+
+      def used_tag_counts
+        counts = Hash.new(0)
+        Mailmate::IndexReader.for("#flags").each_record do |_eml_id, raw|
+          next if raw.nil? || raw.empty?
+          raw.split.each do |token|
+            next if token.start_with?("\\", "$") # IMAP/Thunderbird system flags
+            counts[token] += 1
+          end
+        end
+        counts
+      rescue ArgumentError
+        # #flags index not available — fail gracefully (returns no tags).
+        {}
+      end
+
+      # ---- tags defined in Preferences (Tags.plist) --------------------------
+
+      def emit_defined
+        defined_tag_names.each { |name| $stdout.puts name }
+      end
+
+      def defined_tag_names
+        path = File.join(Mailmate.config.app_support_dir, TAGS_PLIST_FILENAME)
+        return [] unless File.exist?(path)
+        # plutil -convert json is more robust than reading binary plist directly.
+        data = JSON.parse(`plutil -convert json -o - #{shellesc(path)}`)
+        Array(data["tags"]).map { |t| t["displayName"] }.compact
+      rescue StandardError
+        []
+      end
+
+      def shellesc(s)
+        "'#{s.gsub("'", "'\\\\''")}'"
+      end
+    end
+  end
+end

data/lib/mailmate/config.rb

@@ -127,8 +127,11 @@ module Mailmate
     end
   end
 
-  # Convenience: `Mailmate.config.imap_root` etc.
+  # Convenience: `Mailmate.config.imap_root` etc. Triggers first-run
+  # discovery if `~/.config/mailmate/config.yml` doesn't exist yet
+  # (interactive on a TTY, warn-and-continue otherwise).
   def self.config
+    ensure_configured! if respond_to?(:ensure_configured!)
     Config.instance
   end
 end