mailmate 0.1.0

data/lib/mailmate/attributes.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+# Attribute resolver: maps a path like ["from", "name"] or ["#any-address"]
+# to one or more values on a parsed Mail::Message. Implements the subset of
+# /Applications/MailMate.app/Contents/Resources/specifiers.plist that Brian's
+# smart-mailbox filters actually reference.
+#
+# Returns:
+#   - String  for single-valued paths
+#   - Array<String> for multi-valued paths (e.g. recipient lists, all-addresses)
+#   - Time    for date paths
+#   - nil     when the value is missing/empty
+#
+# Stage A subset (no #flags / #date-last-viewed access; those need IndexReader).
+
+require "time"
+require_relative "index_reader"
+
+# @api private
+module Mailmate
+  module Attributes
+    SHORTHANDS = {
+      "#recipient"   => %w[to cc bcc],
+      "#any-address" => %w[from to cc bcc],
+      "#mailer"      => %w[x-mailer user-agent x-newsreader],
+      "#date"        => :date,
+      "#date-received" => :date_received,
+      "#date-sent"   => :date,
+    }.freeze
+
+    # Resolve a path to value(s). Returns nil/[] when nothing.
+    # `mail_or_message` may be a Mail::Message OR a Mailmate::Message (which
+    # carries the `eml_id` needed for index-based attributes like `#flags`).
+    def self.resolve(mail_or_message, path)
+      mail   = mail_or_message.respond_to?(:mail) ? mail_or_message.mail : mail_or_message
+      eml_id = mail_or_message.respond_to?(:eml_id) ? mail_or_message.eml_id : nil
+
+      head, *rest = path
+      values = head_values(mail, head, eml_id)
+      values = Array(values).flatten.compact
+      return nil if values.empty?
+
+      rest.each do |seg|
+        values = values.flat_map { |v| step(v, seg) }.compact
+        return nil if values.empty?
+      end
+
+      values.size == 1 ? values.first : values
+    end
+
+    # ---- head resolution ----
+
+    INDEX_DATE_HEADS = %w[#date #date-sent #date-received #date-last-viewed].freeze
+
+    def self.head_values(mail, head, eml_id = nil)
+      # Index-backed paths: never need the Mail object.
+      if INDEX_DATE_HEADS.include?(head) && eml_id
+        s = (IndexReader.for(head).value_for(eml_id) rescue nil)
+        return nil if s.nil? || s.empty?
+        begin
+          return Time.parse(s)
+        rescue ArgumentError
+          return nil
+        end
+      end
+
+      case head
+      when "##thread-id"
+        # Heuristic thread-id: root Message-ID of the References chain (or
+        # In-Reply-To, or the message's own Message-ID). Requires the headers
+        # — return nil cleanly if we're in index-only mode without a Mail.
+        return nil if mail.nil?
+        thread_id_for(mail)
+      when "#flags"
+        # Returns the raw flag tokens as strings (e.g. ["\\Seen", "$Forwarded"]).
+        # Empty array if the message has no flags / isn't indexed.
+        # Resolved via the binary `Database.noindex/Headers/#flags` index.
+        return [] if eml_id.nil?
+        IndexReader.for("#flags").flags_for(eml_id)
+      when "##tags"
+        return [] if eml_id.nil?
+        # ##tags is a related index (multiValue) for user-facing tag names.
+        # Best-effort: fall back to #flags if ##tags isn't present.
+        begin
+          IndexReader.for("##tags").flags_for(eml_id)
+        rescue ArgumentError
+          IndexReader.for("#flags").flags_for(eml_id)
+        end
+      else
+        # All other heads need the Mail object. In index-only mode, mail is
+        # nil — return nil so comparisons fail cleanly rather than crashing.
+        return nil if mail.nil?
+        head_values_from_mail(mail, head)
+      end
+    end
+
+    def self.head_values_from_mail(mail, head)
+      case head
+      when "from"
+        addrs(mail, :from)
+      when "to"
+        addrs(mail, :to)
+      when "cc"
+        addrs(mail, :cc)
+      when "bcc"
+        addrs(mail, :bcc)
+      when "reply-to"
+        addrs(mail, :reply_to)
+      when "subject"
+        mail.subject.to_s
+      when "list-id"
+        v = header_value(mail, "list-id")
+        v && [v]
+      when "in-reply-to"
+        v = header_value(mail, "in-reply-to")
+        v && [v]
+      when "message-id"
+        mail.message_id
+      when "x-mailer", "user-agent", "x-newsreader"
+        v = header_value(mail, head)
+        v && [v]
+      when "#recipient", "#any-address"
+        SHORTHANDS[head].flat_map { |h| addrs(mail, h.to_sym) || [] }
+      when "#mailer"
+        SHORTHANDS[head].map { |h| header_value(mail, h) }.compact
+      when "#date", "#date-sent"
+        mail.date
+      when "#date-received"
+        # Best available proxy without IMAP: prefer the latest Received: timestamp,
+        # falling back to the Date header. Receiving servers stamp Received headers
+        # in reverse-chrono order; the topmost is the most recent.
+        recv = mail.received
+        recv = [recv].flatten.compact.first
+        recv&.date_time && Time.parse(recv.date_time.to_s) rescue mail.date
+      else
+        # Unknown header — try as a raw header lookup.
+        v = header_value(mail, head)
+        v && [v]
+      end
+    end
+
+    # Address fields can carry either an email or a display name. We return
+    # *one Address-shaped string* per recipient, plus separately accessible
+    # display names — `step` decomposes further on `.name` / `.address`.
+    def self.addrs(mail, sym)
+      field = mail[sym]
+      return nil unless field
+      list = Array(field.respond_to?(:addrs) ? field.addrs : nil)
+      return [field.value.to_s] if list.empty?
+      # Each Mail::Address has #display_name, #address, #name
+      list.map { |a| AddressValue.new(a) }
+    end
+
+    # AddressValue wraps Mail::Address so `.step` knows what to extract.
+    AddressValue = Struct.new(:addr) do
+      def to_s
+        if addr.display_name && !addr.display_name.empty?
+          "#{addr.display_name} <#{addr.address}>"
+        else
+          addr.address.to_s
+        end
+      end
+
+      def name
+        addr.display_name
+      end
+
+      def address
+        addr.address
+      end
+    end
+
+    def self.header_value(mail, name)
+      h = mail[name]
+      return nil unless h
+      h.value.to_s
+    end
+
+    # ---- decomposition step ----
+
+    def self.step(value, seg)
+      case value
+      when AddressValue
+        case seg
+        when "name"    then value.name
+        when "address" then value.address
+        when "domain"
+          a = value.address.to_s
+          a.include?("@") ? a.split("@", 2).last : nil
+        when "user"
+          a = value.address.to_s
+          a.include?("@") ? a.split("@", 2).first : a
+        when "top-level", "second-level", "third-level", "final-level"
+          a = value.address.to_s
+          dom = a.include?("@") ? a.split("@", 2).last : nil
+          dom && domain_level(dom, seg)
+        else nil
+        end
+      when String
+        case seg
+        when "flag", "tag"
+          # `#flags.flag` / `##tags.tag` — each value of the multi-value head
+          # is already an individual flag/tag string. Passthrough.
+          value
+        when "body" # e.g. subject.body — strip Re:/Fwd: prefixes and [bracketed] blobs
+          strip_subject_prefixes(value)
+        when "blob"
+          subject_blob(value)
+        when "prefix"
+          subject_prefix(value)
+        when "identifier" # list-id <foo@bar>
+          value =~ /<([^>]+)>/ ? Regexp.last_match(1) : value.strip
+        when "description" # list-id "Description" <foo@bar>
+          value =~ /^\s*"([^"]+)"|^([^<]+?)\s*</ ? (Regexp.last_match(1) || Regexp.last_match(2)).strip : nil
+        when "user"
+          value.include?("@") ? value.split("@", 2).first : value
+        when "domain"
+          value.include?("@") ? value.split("@", 2).last : nil
+        when "top-level", "second-level", "third-level", "final-level"
+          dom = value.include?("@") ? value.split("@", 2).last : value
+          domain_level(dom, seg)
+        else nil
+        end
+      when Time, DateTime
+        t = value.respond_to?(:to_time) ? value.to_time : value
+        case seg
+        when "year"   then t.year.to_s
+        when "month"  then t.month.to_s
+        when "day"    then t.day.to_s
+        when "hour"   then t.hour.to_s
+        else nil
+        end
+      end
+    end
+
+    def self.strip_subject_prefixes(s)
+      v = s.to_s.dup
+      # Remove leading "Re:", "Fwd:", "[Tag]" sequences
+      loop do
+        if v.sub!(/\A\s*(?i:re|fw|fwd|sv|aw|antw|wg|tr)(?:\[\d+\])?\s*[:：]\s*/, "")
+          next
+        end
+        if v.sub!(/\A\s*\[[^\[\]]+\]\s*/, "")
+          next
+        end
+        break
+      end
+      v
+    end
+
+    def self.subject_blob(s)
+      m = s.to_s.match(/\A(?:\s*(?i:re|fw|fwd|sv|aw|antw|wg|tr)(?:\[\d+\])?\s*[:：]\s*)*\s*\[([^\[\]]+)\]/)
+      m && m[1]
+    end
+
+    def self.subject_prefix(s)
+      m = s.to_s.match(/\A((?:\s*(?i:re|fw|fwd|sv|aw|antw|wg|tr)(?:\[\d+\])?\s*[:：]\s*)+)/)
+      m && m[1].strip
+    end
+
+    # Thread-id heuristic: use the FIRST Message-ID in the References header
+    # as the thread root, falling back to In-Reply-To, falling back to the
+    # message's own Message-ID. Matches what most threading algorithms do.
+    def self.thread_id_for(mail)
+      refs = header_value(mail, "references").to_s
+      if (m = refs.match(/<([^>]+)>/))
+        return m[1]
+      end
+      irt = header_value(mail, "in-reply-to").to_s
+      if (m = irt.match(/<([^>]+)>/))
+        return m[1]
+      end
+      mid = mail.message_id.to_s
+      mid = mid.tr("<>", "") if mid && !mid.empty?
+      mid.empty? ? nil : mid
+    end
+
+    def self.domain_level(domain, level)
+      parts = domain.to_s.split(".")
+      return nil if parts.empty?
+      case level
+      when "top-level"    then parts[-1]
+      when "second-level" then parts[-2]
+      when "third-level"  then parts[-3]
+      when "final-level"  then parts[0]
+      end
+    end
+  end
+end

data/lib/mailmate/cli/discover.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "fileutils"
+
+module Mailmate
+  module CLI
+    # `mmdiscover` — bootstrap ~/.config/mailmate/{config.yml,bundle_loader.rb}
+    # from MailMate's own Sources.plist and Identities.plist.
+    #
+    # First-run UX: a user installs the gem, runs `mmdiscover`, sees their
+    # accounts and identity addresses laid out, confirms, and the gem now
+    # knows who they are without any hand-editing of YAML or `plutil`
+    # archaeology.
+    # @api private
+    module Discover
+      extend self
+
+      CONFIG_DIR    = File.expand_path("~/.config/mailmate")
+      CONFIG_FILE   = File.join(CONFIG_DIR, "config.yml")
+      LOADER_FILE   = File.join(CONFIG_DIR, "bundle_loader.rb")
+
+      def run(argv)
+        opts = parse_options(argv)
+        app_support_dir = opts[:app_support_dir] || File.expand_path("~/Library/Application Support/MailMate")
+
+        unless File.directory?(app_support_dir)
+          warn "mmdiscover: MailMate app-support directory not found at #{app_support_dir}"
+          warn "  Pass --app-support-dir if your install is elsewhere, or check that MailMate is installed."
+          return 1
+        end
+
+        sources_plist    = File.join(app_support_dir, "Sources.plist")
+        identities_plist = File.join(app_support_dir, "Identities.plist")
+
+        accounts   = read_accounts(sources_plist)
+        identities = read_identities(identities_plist)
+
+        $stdout.puts "Found #{accounts.size} account#{"s" if accounts.size != 1} in Sources.plist:"
+        accounts.each { |a| $stdout.puts "  #{a[:name].ljust(35)}(#{a[:host]})" }
+        $stdout.puts
+        $stdout.puts "Found #{identities.size} identity address#{"es" if identities.size != 1} in Identities.plist:"
+        identities.each { |addr| $stdout.puts "  #{addr}" }
+        $stdout.puts
+
+        # Compare against existing config, if any, and surface differences.
+        # Without --force we won't silently overwrite manual additions
+        # (e.g. aliases that aren't outgoing identities in MailMate).
+        existing_identities = read_existing_identities(CONFIG_FILE)
+        if existing_identities && !opts[:force] && !opts[:dry_run]
+          only_in_existing = existing_identities - identities
+          only_in_new      = identities - existing_identities
+
+          if !only_in_existing.empty? || !only_in_new.empty?
+            $stdout.puts "Existing #{CONFIG_FILE} has a different identity set:"
+            only_in_existing.each { |a| $stdout.puts "  - #{a}  (in current config, NOT in Identities.plist)" }
+            only_in_new.each      { |a| $stdout.puts "  + #{a}  (in Identities.plist, NOT in current config)" }
+            $stdout.puts
+            $stdout.puts "Re-run with --force to overwrite, or hand-merge if you have manual additions to preserve."
+            return 0
+          end
+        end
+
+        if opts[:dry_run]
+          $stdout.puts "(--dry-run) Would write #{CONFIG_FILE} and #{LOADER_FILE}; skipping."
+          return 0
+        end
+
+        unless opts[:yes]
+          $stdout.print "Write these to #{CONFIG_FILE}? [y/N] "
+          response = $stdin.gets&.strip&.downcase
+          unless %w[y yes].include?(response)
+            $stdout.puts "Aborted."
+            return 0
+          end
+        end
+
+        FileUtils.mkdir_p(CONFIG_DIR)
+        write_config(identities, app_support_dir, opts[:app_support_dir])
+        write_bundle_loader
+
+        $stdout.puts "Wrote #{CONFIG_FILE}"
+        $stdout.puts "Wrote #{LOADER_FILE}"
+        0
+      end
+
+      def parse_options(argv)
+        opts = { dry_run: false, yes: false, force: false, app_support_dir: nil }
+        OptionParser.new do |o|
+          o.banner = "Usage: mmdiscover [--app-support-dir PATH] [--dry-run] [--yes] [--force]"
+          o.on("--app-support-dir PATH", "Override the MailMate app-support location") { |p| opts[:app_support_dir] = File.expand_path(p) }
+          o.on("--dry-run", "Print what would be written; don't write") { opts[:dry_run] = true }
+          o.on("-y", "--yes", "Skip the y/N prompt") { opts[:yes] = true }
+          o.on("--force", "Overwrite existing config even if it has identities not in Identities.plist") { opts[:force] = true }
+        end.parse!(argv)
+        opts
+      end
+
+      # Read the existing config.yml's `identities:` list, if the file exists.
+      # Returns Array<String> (possibly empty) or nil if the file is missing.
+      def read_existing_identities(path)
+        return nil unless File.exist?(path)
+        require "yaml"
+        data = YAML.safe_load_file(path) rescue nil
+        return [] unless data.is_a?(Hash)
+        Array(data["identities"]).map { |a| a.to_s.downcase.strip }.reject(&:empty?)
+      end
+
+      # Read Sources.plist via plutil. Returns Array<{name:, host:}>.
+      def read_accounts(path)
+        return [] unless File.exist?(path)
+        json = `plutil -convert json -o - #{shellesc(path)}`
+        data = JSON.parse(json) rescue {}
+        sources = data["sources"] || data["Sources"] || []
+        sources.map do |s|
+          name = s["name"] || s["Name"] || "(unnamed)"
+          server_url = s["serverURL"] || s["ServerURL"] || ""
+          host = server_url.split("@").last || "(no host)"
+          { name: name, host: host }
+        end
+      end
+
+      # Read Identities.plist via plutil. Returns Array<String> of email
+      # addresses, lowercased and deduplicated. Each identity entry has an
+      # `emailAddresses` field that may be a single string or a newline-
+      # delimited list.
+      def read_identities(path)
+        return [] unless File.exist?(path)
+        json = `plutil -convert json -o - #{shellesc(path)}`
+        data = JSON.parse(json) rescue {}
+        ids = data["identities"] || data["Identities"] || []
+
+        all = ids.flat_map do |i|
+          raw = i["emailAddresses"] || i["EmailAddresses"] || i["emailAddress"] || ""
+          raw.to_s.split(/[\s,]+/)
+        end
+        all.map { |a| a.strip.downcase }.reject(&:empty?).uniq
+      end
+
+      def write_config(identities, _app_support_dir, app_support_override)
+        File.open(CONFIG_FILE, "w") do |f|
+          f.puts "# Mailmate gem configuration — written by mmdiscover on #{Time.now.strftime("%Y-%m-%d %H:%M")}"
+          f.puts
+          if app_support_override
+            f.puts "app_support_dir: #{app_support_override}"
+            f.puts
+          end
+          f.puts "identities:"
+          identities.each { |addr| f.puts "  - #{addr}" }
+        end
+      end
+
+      def write_bundle_loader
+        gem_lib = File.expand_path("../..", __dir__) # → ~/code/claude/mailmate/lib
+        File.open(LOADER_FILE, "w") do |f|
+          f.puts "# Mailmate gem bundle-loader — written by mmdiscover."
+          f.puts "# MailMate bundle handlers `load` this file then `require \"mailmate\"`."
+          f.puts "# Re-run mmdiscover to refresh if the gem's location changes."
+          f.puts
+          f.puts "$LOAD_PATH.unshift #{gem_lib.inspect} unless $LOAD_PATH.include?(#{gem_lib.inspect})"
+        end
+      end
+
+      def shellesc(s)
+        "'#{s.gsub("'", "'\\\\''")}'"
+      end
+    end
+  end
+end

data/lib/mailmate/cli/message.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "mail"
+
+module Mailmate
+  module CLI
+    # `mmmessage` — print a decoded MailMate message by its eml-id.
+    # Ports the standalone mailmate-message script. Headers + plain-text body
+    # by default; `--raw` for the original .eml bytes; `--text-only` for just
+    # the body.
+    # @api private
+    module Message
+      extend self
+
+      def run(argv)
+        opts = parse_options(argv)
+        input = argv.first
+
+        return usage_error("missing <id>") if input.nil? || input.empty?
+
+        # Accept either eml-id (all digits) or RFC Message-ID (with or without
+        # angle brackets). Lets you copy/paste from any machine without caring
+        # whether the local eml-id matches.
+        eml_id = Mailmate::EmlLookup.resolve_id(input)
+        if eml_id.nil? || eml_id.zero?
+          warn "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 "Not found: #{eml_id}.eml"
+          return 1
+        end
+
+        if opts[:raw]
+          $stdout.binmode
+          $stdout.write(File.binread(path))
+          return 0
+        end
+
+        mail = Mail.read(path)
+        print_headers(mail, eml_id, path) unless opts[:text_only]
+        $stdout.puts text_body(mail)
+        0
+      end
+
+      def parse_options(argv)
+        opts = { raw: false, text_only: false }
+        OptionParser.new do |o|
+          o.banner = "Usage: mmmessage <id> [--raw|--text-only]"
+          o.separator ""
+          o.separator "<id> can be either a local eml-id (e.g. 183715) or an RFC"
+          o.separator "Message-ID (with or without angle brackets, e.g."
+          o.separator "<abc@example.com>). Message-IDs are portable across machines"
+          o.separator "and survive copy/paste between desktop/laptop/iPad."
+          o.on("--raw", "Output raw .eml bytes") { opts[:raw] = true }
+          o.on("--text-only", "Output decoded body only (no headers block)") { opts[:text_only] = true }
+        end.parse!(argv)
+        opts
+      end
+
+      def usage_error(msg)
+        warn "mmmessage: #{msg}"
+        warn "Usage: mmmessage <id> [--raw|--text-only]"
+        warn "  <id> is either an eml-id (digits) or an RFC Message-ID."
+        2
+      end
+
+      def print_headers(mail, eml_id, path)
+        imap_root = Mailmate.config.imap_root
+        mailbox = path.sub("#{imap_root}/", "").sub(%r{/Messages/[^/]+\.eml\z}, "")
+        $stdout.puts "eml-id:     #{eml_id}"
+        $stdout.puts "path:       #{path}"
+        $stdout.puts "mailbox:    #{mailbox}"
+        $stdout.puts "from:       #{Array(mail.from).join(", ")}" if mail.from
+        $stdout.puts "to:         #{Array(mail.to).join(", ")}"   if mail.to
+        $stdout.puts "cc:         #{Array(mail.cc).join(", ")}"   if mail.cc
+        $stdout.puts "subject:    #{mail.subject}"
+        $stdout.puts "date:       #{Mailmate.localize(mail.date)&.iso8601}"
+        $stdout.puts "message-id: #{mail.message_id}"
+        if mail.attachments.any?
+          $stdout.puts "attachments:"
+          mail.attachments.each do |a|
+            sz = begin
+              a.body.decoded.bytesize
+            rescue StandardError
+              0
+            end
+            $stdout.puts "  - #{a.filename || "(no name)"}  #{a.mime_type}  #{sz}b"
+          end
+        end
+        $stdout.puts
+      end
+
+      def text_body(mail)
+        if mail.text_part
+          mail.text_part.decoded.force_encoding("UTF-8").scrub
+        elsif mail.html_part
+          "[no text/plain part — HTML rendered below; use --raw for original]\n\n" +
+            mail.html_part.decoded.force_encoding("UTF-8").scrub
+        else
+          mail.body.decoded.to_s.force_encoding("UTF-8").scrub
+        end
+      end
+    end
+  end
+end