mailmate 0.1.0

data/lib/mailmate/index_reader.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# IndexReader — decodes MailMate's binary header indexes at
+# `~/Library/Application Support/MailMate/Database.noindex/Headers/`.
+#
+# Index format (verified against `#flags.offsets` and `#forwarding.offsets`):
+#
+#   .cache    Newline-separated string table.
+#   .offsets  Concatenated 12-byte records, three little-endian uint32 each:
+#               [0..4)   message body-part ID
+#               [4..8)   start byte offset into .cache
+#               [8..12)  end byte offset into .cache (exclusive)
+#             value = cache[start...end]   (start == end → empty / "no value")
+#   .plist    Old-style plist with offsetsFileSize / stringsFileSize sentinels.
+#
+# Specific accessors:
+#   `flags.flag(eml_id)`  → Array<String> of IMAP keywords (`\Seen`,
+#                            `\Flagged`, `$Forwarded`, `$Muted`, custom tags…)
+#                            or [] if the message has no flags / isn't indexed.
+#
+# IndexReader instances cache both files in memory and build a hash from
+# msg_id → (start,end) for O(1) lookup. Construction cost ≈ 5–20 ms for
+# 50–200k records; memory ≈ a few MB. For a CLI invocation that's fine; the
+# evaluator instantiates one lazily when first needed.
+
+module Mailmate
+  # @api public
+  class IndexReader
+    RECORD_SIZE = 12
+
+    class << self
+      # Per-process cache of readers keyed by [name, db_headers]. Including
+      # db_headers means a Mailmate.config swap (e.g. a test pointing at a
+      # different tmpdir) doesn't return stale readers built from the old
+      # path.
+      def for(name)
+        @cache ||= {}
+        @cache[cache_key(name)] ||= new(name)
+      end
+
+      # Invalidate cached readers. With no argument, drops the entire cache
+      # (useful for tests or when MailMate's database swaps out). With a name,
+      # invalidates only entries for that name across all db_headers — the
+      # common case (cache-bust after a write) doesn't need to thread config
+      # through.
+      def reset!(name = nil)
+        if name.nil?
+          @cache = nil
+        elsif @cache
+          @cache.delete_if { |(n, _dir), _reader| n == name }
+        end
+      end
+
+      private
+
+      def cache_key(name)
+        [name, Mailmate.config.db_headers]
+      end
+    end
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+      base = "#{Mailmate.config.db_headers}/#{name}"
+      raise ArgumentError, "Index not found: #{name} (looked at #{base}.{cache,offsets})" \
+        unless File.exist?("#{base}.cache") && File.exist?("#{base}.offsets")
+
+      @cache_bytes   = File.binread("#{base}.cache")
+      @offsets_bytes = File.binread("#{base}.offsets")
+      build_index!
+    end
+
+    # Returns the raw cached value for a given .eml body-part ID, or nil if
+    # the message isn't in this index.
+    def value_for(eml_id)
+      pair = @index[eml_id.to_i]
+      return nil unless pair
+      @cache_bytes[pair[0]...pair[1]]
+    end
+
+    # `#flags.flag` semantics: the cache stores a space-separated list of IMAP
+    # keywords. Split into individual flag tokens.
+    def flags_for(eml_id)
+      v = value_for(eml_id)
+      return [] if v.nil? || v.empty?
+      v.split(/\s+/).reject(&:empty?)
+    end
+
+    # Number of records (mostly for diagnostics).
+    def size
+      @index.size
+    end
+
+    # Iterate every recorded eml-id. Yields just the id; callers that also
+    # want the value should pair this with `value_for`. Exists so other gem
+    # modules don't have to reach into `@index` directly.
+    def each_eml_id(&block)
+      return enum_for(:each_eml_id) unless block
+      @index.each_key(&block)
+    end
+
+    # Iterate every (eml_id, raw_value) pair. The value comes back as the
+    # bare cache substring; callers that need parsed form (e.g. flag tokens)
+    # should massage it themselves.
+    def each_record
+      return enum_for(:each_record) unless block_given?
+      @index.each_key do |eml_id|
+        yield eml_id, value_for(eml_id)
+      end
+    end
+
+    private
+
+    def build_index!
+      @index = {}
+      n = @offsets_bytes.bytesize / RECORD_SIZE
+      i = 0
+      while i < n
+        rec = @offsets_bytes[i * RECORD_SIZE, RECORD_SIZE].unpack("V3")
+        @index[rec[0]] = [rec[1], rec[2]]
+        i += 1
+      end
+    end
+  end
+end

data/lib/mailmate/lexer.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# Lexer for MailMate filter expressions. Emits a flat array of [kind, value]
+# tokens. Whitespace is skipped. Keywords (`and`, `or`, `not`, `exists`) are
+# recognized at lex time; `ago`, `days`, `months`, etc. stay as :ident and are
+# disambiguated by the parser.
+
+module Mailmate
+  # @api private
+  module Lexer
+    KEYWORDS = %w[and or not exists].freeze
+    OP_FLAG_CHARS = "cafx" # operator-modifier flags, e.g. =[c], >[f], !=[x]
+
+    class Error < StandardError; end
+
+    def self.lex(input)
+      tokens = []
+      i = 0
+      while i < input.length
+        c = input[i]
+
+        # Whitespace
+        if c =~ /\s/
+          i += 1
+          next
+        end
+
+        # Punctuation
+        if c == "("
+          tokens << [:lparen]; i += 1; next
+        elsif c == ")"
+          tokens << [:rparen]; i += 1; next
+        elsif c == "."
+          tokens << [:dot]; i += 1; next
+        end
+
+        # Variable reference: $SENT, $PERSONAL_INBOX
+        if c == "$"
+          j = i + 1
+          j += 1 while j < input.length && input[j] =~ /[A-Z_]/
+          raise Error, "empty variable name at #{i}" if j == i + 1
+          tokens << [:var, input[(i + 1)...j]]
+          i = j
+          next
+        end
+
+        # String: '...'  Only `\\` and `\'` are recognized escapes; other
+        # backslashes are preserved literally so IMAP keywords like
+        # `\Seen` / `\Flagged` survive intact.
+        if c == "'"
+          j = i + 1
+          buf = +""
+          while j < input.length && input[j] != "'"
+            if input[j] == "\\" && j + 1 < input.length && (input[j + 1] == "\\" || input[j + 1] == "'")
+              buf << input[j + 1]
+              j += 2
+            else
+              buf << input[j]
+              j += 1
+            end
+          end
+          raise Error, "unterminated string starting at #{i}" if j >= input.length
+          tokens << [:string, buf]
+          i = j + 1
+          next
+        end
+
+        # Operator: !=, =, ~, !~, <, <=, >, >=, with optional [flags]
+        if "!=~<>".include?(c)
+          op = c
+          j = i + 1
+          if c == "!" && j < input.length && (input[j] == "=" || input[j] == "~")
+            op = "!" + input[j]
+            j += 1
+          elsif (c == "<" || c == ">") && j < input.length && input[j] == "="
+            op = c + "="
+            j += 1
+          end
+          # Optional [flags]
+          flags = []
+          if j < input.length && input[j] == "["
+            k = j + 1
+            while k < input.length && OP_FLAG_CHARS.include?(input[k])
+              flags << input[k]
+              k += 1
+            end
+            raise Error, "expected ] after operator flags at #{j}" if k >= input.length || input[k] != "]"
+            j = k + 1
+          end
+          tokens << [:op, op, flags]
+          i = j
+          next
+        end
+
+        # Number: 0-9+
+        if c =~ /\d/
+          j = i
+          j += 1 while j < input.length && input[j] =~ /\d/
+          tokens << [:number, input[i...j].to_i]
+          i = j
+          next
+        end
+
+        # Shorthand: # or ## followed by ident
+        if c == "#"
+          j = i
+          j += 1 while j < input.length && input[j] == "#"
+          start = j
+          j += 1 while j < input.length && input[j] =~ /[a-zA-Z0-9_-]/
+          raise Error, "empty shorthand at #{i}" if start == j
+          tokens << [:shorthand, input[i...j]]
+          i = j
+          next
+        end
+
+        # Identifier: [a-zA-Z_][a-zA-Z0-9_-]*
+        if c =~ /[a-zA-Z_]/
+          j = i
+          j += 1 while j < input.length && input[j] =~ /[a-zA-Z0-9_-]/
+          word = input[i...j]
+          if KEYWORDS.include?(word)
+            tokens << [:keyword, word]
+          else
+            tokens << [:ident, word]
+          end
+          i = j
+          next
+        end
+
+        raise Error, "unexpected char #{c.inspect} at position #{i}"
+      end
+      tokens << [:eof]
+      tokens
+    end
+  end
+end

data/lib/mailmate/mailbox_graph.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Reads MailMate's mailbox configuration: the user's `Mailboxes.plist` plus
+# the bundled `standardMailboxes.plist`/`defaultMailboxes.plist`. Builds an
+# in-memory graph keyed by UUID with name → uuid lookup.
+
+module Mailmate
+  # @api public
+  class MailboxGraph
+    APP_RESOURCES = "/Applications/MailMate.app/Contents/Resources"
+
+    SPECIAL_UUIDS = %w[ALL_MESSAGES INBOX SENT DRAFTS ARCHIVE JUNK TRASH FLAGGED MAILBOXES PERSONAL_INBOX].freeze
+
+    # Mailbox = a Hash with keys: :uuid, :name, :parent, :set, :filter
+    attr_reader :by_uuid, :by_name
+
+    def self.load
+      new.tap(&:load!)
+    end
+
+    def initialize
+      @by_uuid = {}
+      @by_name = {}
+    end
+
+    def load!
+      load_plist!("#{APP_RESOURCES}/standardMailboxes.plist")
+      load_plist!("#{APP_RESOURCES}/defaultMailboxes.plist")
+      load_plist!(Mailmate.config.mailboxes_plist)
+      build_name_index!
+      self
+    end
+
+    def lookup(name_or_uuid)
+      @by_uuid[name_or_uuid] || @by_name[name_or_uuid]
+    end
+
+    private
+
+    def load_plist!(path)
+      return unless File.exist?(path)
+      data = JSON.parse(`plutil -convert json -o - #{shellesc(path)}`)
+      boxes = (data["mailboxes"] || []) + (data["deltaMailboxes"] || [])
+      boxes.each do |m|
+        next unless m["uuid"]
+        existing = @by_uuid[m["uuid"]] || {}
+        @by_uuid[m["uuid"]] = existing.merge(
+          uuid:   m["uuid"],
+          name:   m["name"]    || existing[:name],
+          parent: m["parentUUID"] || existing[:parent],
+          set:    m["set"]     || existing[:set],
+          filter: m["filter"]  || existing[:filter],
+          symbol: m["symbol"]  || existing[:symbol],
+        )
+      end
+    end
+
+    def build_name_index!
+      @by_uuid.each do |uuid, m|
+        next unless m[:name]
+        # Prefer user-defined entries (later loads) over defaults; later loads
+        # already overwrite earlier ones in @by_uuid via merge, but the name
+        # index can still get clobbered when two mailboxes share a name.
+        # We keep the most-recently-loaded — and for tied cases, prefer the
+        # one that has a filter (smart mailboxes are what users address by name).
+        existing = @by_name[m[:name]]
+        @by_name[m[:name]] = uuid if existing.nil? || @by_uuid[existing][:filter].nil? || m[:filter]
+      end
+    end
+
+    def shellesc(s)
+      "'#{s.gsub("'", "'\\\\''")}'"
+    end
+  end
+end

data/lib/mailmate/message.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Message — thin wrapper that pairs a parsed Mail::Message with its `.eml`
+# body-part ID and on-disk path. Stage B+ attribute paths (`#flags.flag`,
+# `#date-last-viewed`, …) need the body-part ID to look up MailMate's binary
+# Database.noindex/Headers indexes; carrying it alongside the Mail object lets
+# the resolver fetch indexed values without re-deriving the ID.
+#
+# Delegates the headers-and-body interface back to Mail so existing code that
+# expects a `Mail::Message` keeps working unchanged.
+
+module Mailmate
+  # @api public
+  class Message
+    attr_reader :mail, :eml_id, :path
+
+    def initialize(mail, eml_id, path)
+      @mail = mail
+      @eml_id = eml_id.to_i
+      @path = path
+    end
+
+    # Delegate the headers/body methods Attributes uses.
+    %i[from to cc bcc reply_to sender subject date message_id received body
+       text_part html_part attachments].each do |m|
+      define_method(m) { mail.public_send(m) }
+    end
+
+    def [](key); mail[key]; end
+  end
+end

data/lib/mailmate/mid_url.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # Build a MailMate `mid:` URL from a Message-ID. MailMate registers the
+  # `mid:` scheme (RFC 2392) and resolves it to a specific message. The angle
+  # brackets that bracket the Message-ID in headers must be percent-encoded.
+  module MidUrl
+    # Returns `mid:%3C<message-id>%3E`. Accepts the Message-ID with or without
+    # surrounding angle brackets — strips them either way before encoding.
+    # URL-encodes characters that would break the URL parser, notably `[` and
+    # `]` (which appear in Message-IDs containing IPv4 literals, e.g.
+    # `<id@[169.254.16.253]>`). Other URL-reserved characters (`@`, `.`, `-`,
+    # `_`, etc.) are preserved — MailMate's parser accepts them as-is.
+    def self.for(message_id)
+      raise ArgumentError, "Message-ID required" if message_id.nil? || message_id.to_s.empty?
+      id = message_id.to_s.sub(/\A</, "").sub(/>\z/, "")
+      encoded = id.gsub(/[\[\]<>\s]/) { |c| "%%%02X" % c.ord }
+      "mid:%3C#{encoded}%3E"
+    end
+  end
+end

data/lib/mailmate/operators.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+# Operator evaluator + date arithmetic for MailMate filter expressions.
+
+module Mailmate
+  # @api private
+  module Operators
+    # Compare a single LHS value against a single RHS, applying modifier flags.
+    # Returns true/false. lhs may be String, Time/DateTime, Numeric, or
+    # Mailmate::Attributes::AddressValue (which to_s renders as "Name <addr>").
+    def self.compare(lhs, op, flags, rhs)
+      lhs_norm = normalize(lhs, flags)
+      rhs_norm = normalize(rhs, flags)
+
+      case op
+      when "="  then lhs_norm == rhs_norm
+      when "!=" then lhs_norm != rhs_norm
+      when "~"  then lhs_norm.to_s.include?(rhs_norm.to_s)
+      when "!~" then !lhs_norm.to_s.include?(rhs_norm.to_s)
+      when "<", "<=", ">", ">="
+        compare_ordered(lhs_norm, op, rhs_norm)
+      else
+        raise ArgumentError, "unknown operator: #{op.inspect}"
+      end
+    end
+
+    def self.normalize(v, flags)
+      return v if v.is_a?(Time) || v.is_a?(DateTime) || v.is_a?(Numeric)
+      s = v.to_s
+      s = s.unicode_normalize(:nfd).gsub(/\p{Mn}/, "") if flags.include?("a")
+      s = s.downcase if flags.include?("c")
+      s
+    end
+
+    def self.compare_ordered(lhs, op, rhs)
+      lhs_v = coerce_for_ordering(lhs)
+      rhs_v = coerce_for_ordering(rhs)
+      return false if lhs_v.nil? || rhs_v.nil?
+      case op
+      when "<"  then lhs_v <  rhs_v
+      when "<=" then lhs_v <= rhs_v
+      when ">"  then lhs_v >  rhs_v
+      when ">=" then lhs_v >= rhs_v
+      end
+    rescue StandardError
+      false
+    end
+
+    def self.coerce_for_ordering(v)
+      return v.to_time if v.is_a?(DateTime)
+      return v if v.is_a?(Time) || v.is_a?(Numeric)
+      s = v.to_s
+      # Try Time, fall back to Integer
+      begin
+        return Time.parse(s)
+      rescue ArgumentError
+      end
+      Integer(s) rescue Float(s) rescue nil
+    end
+
+    # ---- Date arithmetic ----
+
+    # Resolve a relative date (n units ago) to a Time.
+    # `flags` may include "f", which floors to the start of the unit
+    # (matches MailMate's >[f] / <[f] semantics).
+    def self.relative_date(n, unit, flags = [])
+      now = Time.now
+      base =
+        case unit
+        when :day  then now - n * 86_400
+        when :week then now - n * 7 * 86_400
+        when :month
+          y = now.year
+          m = now.month - n
+          while m <= 0
+            m += 12
+            y -= 1
+          end
+          Time.new(y, m, [now.day, last_day_of_month(y, m)].min, now.hour, now.min, now.sec)
+        when :year
+          Time.new(now.year - n, now.month, now.day, now.hour, now.min, now.sec)
+        end
+
+      return base unless flags.include?("f")
+
+      case unit
+      when :day
+        Time.new(base.year, base.month, base.day)
+      when :week
+        # Snap to start of ISO week (Monday)
+        d = base.to_date
+        d -= (d.cwday - 1) # Mon = 1
+        Time.new(d.year, d.month, d.day)
+      when :month
+        Time.new(base.year, base.month, 1)
+      when :year
+        Time.new(base.year, 1, 1)
+      else
+        base
+      end
+    end
+
+    def self.last_day_of_month(y, m)
+      Date.new(y, m, -1).day
+    end
+  end
+end