mailmate 0.1.0

data/lib/mailmate/config.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Mailmate
+  # @api private
+  #
+  # The Config class is the storage and loader; consumers should reach it
+  # through `Mailmate.config` rather than constructing instances directly.
+  #
+  # Mailmate.config — process-wide configuration with three-layer loading:
+  #
+  #   1. Built-in defaults (macOS-standard paths, no identities)
+  #   2. YAML at ~/.config/mailmate/config.yml (silently ignored if missing)
+  #   3. Environment variables (override YAML)
+  #
+  # Personal data — identity addresses, custom paths — lives in the YAML or
+  # env vars, never in the gem source. `mmdiscover` populates the YAML on
+  # first run from MailMate's own Sources.plist + Identities.plist.
+  class Config
+    DEFAULT_APP_SUPPORT_DIR = File.expand_path("~/Library/Application Support/MailMate")
+    DEFAULT_CONFIG_PATH     = File.expand_path("~/.config/mailmate/config.yml")
+
+    attr_reader :app_support_dir, :identities, :display_timezone
+
+    def self.instance
+      @instance ||= new
+    end
+
+    # Replace the singleton with a freshly-loaded config. Accepts the same
+    # kwargs as `.new`, so tests can scope a config block without poking
+    # ivars. Passing no args reloads from defaults (YAML at the default path,
+    # real ENV).
+    def self.reload!(yaml_path: DEFAULT_CONFIG_PATH, env: ENV)
+      @instance = new(yaml_path: yaml_path, env: env)
+    end
+
+    def initialize(yaml_path: DEFAULT_CONFIG_PATH, env: ENV)
+      @app_support_dir  = DEFAULT_APP_SUPPORT_DIR
+      @identities       = []
+      @display_timezone = nil
+
+      load_yaml!(yaml_path)
+      apply_env!(env)
+    end
+
+    # Derived paths. Each follows from app_support_dir; if a user has a
+    # non-default MailMate install, overriding app_support_dir flows through.
+    def imap_root
+      File.join(app_support_dir, "Messages.noindex", "IMAP")
+    end
+
+    def db_headers
+      File.join(app_support_dir, "Database.noindex", "Headers")
+    end
+
+    def mailboxes_plist
+      File.join(app_support_dir, "Mailboxes.plist")
+    end
+
+    def sources_plist
+      File.join(app_support_dir, "Sources.plist")
+    end
+
+    def identities_plist
+      File.join(app_support_dir, "Identities.plist")
+    end
+
+    KNOWN_KEYS = %w[app_support_dir identities display_timezone].freeze
+
+    private
+
+    def load_yaml!(path)
+      return unless File.exist?(path)
+      data = YAML.safe_load_file(path) || {}
+      unless data.is_a?(Hash)
+        warn "Mailmate.config: #{path} did not parse as a YAML mapping; ignoring."
+        return
+      end
+
+      unknown = data.keys - KNOWN_KEYS
+      unless unknown.empty?
+        warn "Mailmate.config: unknown key(s) in #{path}: #{unknown.join(", ")} (valid: #{KNOWN_KEYS.join(", ")})"
+      end
+
+      if data.key?("app_support_dir")
+        val = data["app_support_dir"]
+        if val.is_a?(String) && !val.empty?
+          @app_support_dir = File.expand_path(val)
+        else
+          warn "Mailmate.config: app_support_dir in #{path} must be a non-empty string; ignoring (#{val.inspect})"
+        end
+      end
+
+      if data.key?("identities")
+        val = data["identities"]
+        if val.is_a?(Array)
+          @identities = val.map(&:to_s)
+        else
+          warn "Mailmate.config: identities in #{path} must be a list; ignoring (#{val.inspect})"
+        end
+      end
+
+      if data.key?("display_timezone")
+        val = data["display_timezone"]
+        if val.nil? || (val.is_a?(String) && val.empty?)
+          @display_timezone = nil
+        elsif val.is_a?(String)
+          @display_timezone = val
+        else
+          warn "Mailmate.config: display_timezone in #{path} must be a string (e.g. '-07:00'); ignoring (#{val.inspect})"
+        end
+      end
+    end
+
+    def apply_env!(env)
+      if (v = env["MAILMATE_APP_SUPPORT_DIR"]) && !v.empty?
+        @app_support_dir = File.expand_path(v)
+      end
+      if (v = env["MAILMATE_IDENTITIES"]) && !v.empty?
+        @identities = v.split(",").map(&:strip).reject(&:empty?)
+      end
+      if (v = env["MAILMATE_DISPLAY_TIMEZONE"]) && !v.empty?
+        @display_timezone = v
+      end
+    end
+  end
+
+  # Convenience: `Mailmate.config.imap_root` etc.
+  def self.config
+    Config.instance
+  end
+end

data/lib/mailmate/duplicate_scanner.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # Detect duplicate Message-ID copies across MailMate's tree. The same RFC
+  # Message-ID can appear in multiple `.eml` files — Gmail's label-creates-a-copy
+  # semantics produce this for any message that hits a labeled mailbox, and
+  # self-to-self messages can end up in both Sent and INBOX folders.
+  #
+  # Why this matters: MailMate's `mid:` URL resolves to a single message
+  # non-deterministically, so an action keyed by Message-ID can land on a
+  # different `.eml` file than the one the user typed. `mailmate-modify` warns
+  # when this is the case.
+  #
+  # Implementation uses MailMate's own `message-id` index — O(n) over the
+  # decoded index instead of a recursive `grep -rli` over the whole IMAP tree.
+  # [[Mailmate scripts speed]] §1.
+  module DuplicateScanner
+    # Returns Array<Integer> of eml-ids that share `message_id`. The array is
+    # ordered as `#message-id` records them; callers don't depend on the order.
+    def self.eml_ids_for(message_id)
+      return [] if message_id.nil? || message_id.empty?
+
+      reader = Mailmate::IndexReader.for("message-id")
+      target = strip_brackets(message_id).downcase
+
+      ids = []
+      iterate(reader) do |eml_id, cached|
+        next if cached.nil?
+        ids << eml_id if strip_brackets(cached).downcase == target
+      end
+      ids
+    end
+
+    # Convenience: is there more than one copy of this Message-ID in the tree?
+    def self.duplicate?(message_id)
+      eml_ids_for(message_id).size > 1
+    end
+
+    # Build a Hash{Message-ID => Array<eml_id>} for every duplicated Message-ID
+    # in the index. One full pass; useful as a session-cached lookup when many
+    # messages will be processed in a batch.
+    def self.duplicates
+      reader = Mailmate::IndexReader.for("message-id")
+
+      groups = Hash.new { |h, k| h[k] = [] }
+      iterate(reader) do |eml_id, cached|
+        next if cached.nil? || cached.empty?
+        groups[strip_brackets(cached).downcase] << eml_id
+      end
+      groups.select { |_, ids| ids.size > 1 }
+    end
+
+    # Internal — iterate the IndexReader's records. Delegates to the
+    # reader's public `each_record` API.
+    def self.iterate(reader, &block)
+      reader.each_record(&block)
+    end
+
+    def self.strip_brackets(s)
+      s.to_s.sub(/\A</, "").sub(/>\z/, "").strip
+    end
+  end
+end

data/lib/mailmate/eml_lookup.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # Map an `.eml` body-part ID to its absolute on-disk path.
+  #
+  # Two implementations:
+  #   - The fast path uses MailMate's `#source` index
+  #     (`Database.noindex/Headers/#source.{cache,offsets}`), which carries the
+  #     `imap://account@host/path` URL for every indexed message. O(1) lookup.
+  #   - The fallback walks the IMAP tree with `Dir.glob`, the same shape as the
+  #     `find -name <id>.eml` shell-out the original scripts used. Slower
+  #     (seconds on a cold cache) but always works.
+  #
+  # The fast path wins ~99% of the time. The fallback exists for messages
+  # MailMate hasn't yet indexed (e.g. immediately after a fresh IMAP push) and
+  # for edge cases where `#source` is unreadable.
+  module EmlLookup
+    # Returns an absolute path string, or nil if not found.
+    def self.path_for(eml_id)
+      via_index(eml_id) || via_glob(eml_id)
+    end
+
+    # Reverse-lookup: given an RFC Message-ID (with or without angle brackets),
+    # return the local eml-id (integer) or nil. O(n) scan of the message-id
+    # index — fine for one-shot CLI lookups; cache the result if you need it
+    # repeatedly.
+    def self.eml_id_for_message_id(message_id)
+      needle = message_id.to_s.strip
+      return nil if needle.empty?
+
+      candidates = needle.start_with?("<") && needle.end_with?(">") ?
+                     [needle, needle[1..-2]] :
+                     [needle, "<#{needle}>"]
+
+      Mailmate::IndexReader.for("message-id").each_record do |eml_id, value|
+        return eml_id if candidates.include?(value)
+      end
+      nil
+    rescue ArgumentError
+      nil
+    end
+
+    # Resolve an identifier that may be either an eml-id (all digits) or an
+    # RFC Message-ID (anything else) to a local eml-id.
+    def self.resolve_id(input)
+      s = input.to_s.strip
+      return s.to_i if s =~ /\A\d+\z/
+      eml_id_for_message_id(s)
+    end
+
+    # Force the index path (useful for tests and benchmarking).
+    def self.via_index(eml_id)
+      url = source_url_for(eml_id)
+      return nil if url.nil?
+      url_to_path(url, eml_id)
+    end
+
+    # Force the glob fallback.
+    def self.via_glob(eml_id)
+      matches = Dir.glob("#{Mailmate.config.imap_root}/*/**/Messages/#{eml_id}.eml")
+      matches.first
+    end
+
+    # Lookup the `imap://...` URL recorded in `#source` for this eml_id.
+    # Returns nil if the index doesn't have a record for it.
+    def self.source_url_for(eml_id)
+      Mailmate::IndexReader.for("#source").value_for(eml_id)
+    rescue ArgumentError
+      # #source index missing (non-default MailMate install? fresh sync?).
+      nil
+    end
+
+    # Convert an `imap://account@host/mailbox/path` URL to the on-disk
+    # absolute path of the .eml file. Internal but exposed for tests.
+    def self.url_to_path(url, eml_id)
+      stripped = url.sub(%r{\Aimap://}, "")
+      account, mailbox_path = stripped.split("/", 2)
+      return nil if account.nil? || mailbox_path.nil? || mailbox_path.empty?
+
+      mailbox_dirs = mailbox_path.split("/").map { |seg| "#{seg}.mailbox" }.join("/")
+      File.join(Mailmate.config.imap_root, account, mailbox_dirs, "Messages", "#{eml_id}.eml")
+    end
+  end
+end

data/lib/mailmate/evaluator.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+require_relative "attributes"
+require_relative "operators"
+
+# Evaluator: walks a parsed AST and tests it against a Mail::Message or
+# Mailmate::Message. `var_resolver` is required if the AST contains
+# VarRefNode (i.e. `$SENT.foo`, `$PERSONAL_INBOX.foo` etc.).
+
+module Mailmate
+  # @api public
+  class Evaluator
+    def initialize(filter_ast, var_resolver: nil)
+      @ast = filter_ast
+      @var_resolver = var_resolver
+    end
+
+    def matches?(message)
+      eval_node(@ast, message)
+    end
+
+    private
+
+    def eval_node(node, message)
+      case node
+      when AST::AndNode then node.children.all? { |c| eval_node(c, message) }
+      when AST::OrNode  then node.children.any? { |c| eval_node(c, message) }
+      when AST::NotNode then !eval_node(node.child, message)
+      when AST::ExistsNode
+        v = Attributes.resolve(message, node.path)
+        !(v.nil? || (v.respond_to?(:empty?) && v.empty?))
+      when AST::CompareNode
+        eval_compare(node, message)
+      else
+        raise "unhandled node: #{node.class}"
+      end
+    end
+
+    # Multi-value path semantics:
+    #   `path = X`     → ANY value equals X
+    #   `path ~ X`     → ANY value contains X
+    #   `path != X`    → NO value equals X
+    #   `path !~ X`    → NO value contains X
+    #   `path < X` etc → ANY value compares
+    #
+    # When the RHS is a `$VAR.attr` reference, RHS becomes a *set* of values;
+    # the operator then asks whether any LHS × any RHS satisfies. Negation
+    # still inverts the positive form.
+    def eval_compare(node, message)
+      lhs_values = Array(Attributes.resolve(message, node.path)).compact
+      rhs_values = resolve_value_set(node.value, node.flags, message)
+
+      pos_op = positive_op(node.op)
+      positive_match = lhs_values.any? do |l|
+        rhs_values.any? { |r| Operators.compare(l, pos_op, node.flags, r) }
+      end
+
+      negated_op?(node.op) ? !positive_match : positive_match
+    end
+
+    def positive_op(op)
+      case op
+      when "!=" then "="
+      when "!~" then "~"
+      else op
+      end
+    end
+
+    def negated_op?(op)
+      op == "!=" || op == "!~"
+    end
+
+    # Resolve the AST's RHS value to an array of comparable values.
+    # Bare values become a one-element array; VarRefNode delegates to the
+    # var_resolver, which returns the full set.
+    def resolve_value_set(value_node, op_flags, _message)
+      case value_node
+      when AST::LiteralStringNode then [value_node.value]
+      when AST::NumberNode        then [value_node.value]
+      when AST::AbsoluteDateNode  then [value_node.time]
+      when AST::RelativeDateNode  then [Operators.relative_date(value_node.n, value_node.unit, op_flags)]
+      when AST::VarRefNode
+        unless @var_resolver
+          raise "Filter contains $#{value_node.var} but no var_resolver was provided"
+        end
+        @var_resolver.resolve(value_node.var, value_node.path)
+      else
+        raise "unhandled value: #{value_node.class}"
+      end
+    end
+  end
+end

data/lib/mailmate/filter_classifier.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+
+# @api private
+#
+# FilterClassifier — walks an AST and answers questions about what's
+# required to evaluate it. Used by `mailmate-search` to pick the cheapest
+# `.eml` loading tier per query:
+#
+#   :index   — every path is index-backed; never open the .eml at all.
+#   :header  — every path resolves from headers (or index); read header block only.
+#   :full    — at least one path needs body content; full Mail.read.
+#
+# Also extracts ASCII string literals from top-level AND-chained
+# header-path comparisons so the raw-bytes pre-filter can short-circuit
+# without parsing.
+
+module Mailmate
+  module FilterClassifier
+    # Heads served by an on-disk index in Database.noindex/Headers/<name>.
+    INDEX_BACKED_HEADS = %w[
+      #flags ##tags
+      #date #date-received #date-sent #date-last-viewed
+    ].freeze
+
+    # Heads that resolve from .eml header bytes (vs. body).
+    HEADER_HEADS = %w[
+      from to cc bcc reply-to sender resent-from resent-to resent-cc resent-bcc
+      subject list-id message-id in-reply-to references
+      x-mailer user-agent x-newsreader received delivered-to
+      #recipient #any-address #mailer ##thread-id
+    ].freeze
+
+    # Heads that require the body to resolve.
+    BODY_HEADS = %w[#unquoted #quoted #common #commonplus].freeze
+
+    # Heads whose literals appear textually in the .eml header bytes
+    # (so they're safe pre-filter candidates).
+    PREFILTER_HEADS = %w[
+      from to cc bcc reply-to sender
+      subject list-id message-id in-reply-to references
+      x-mailer user-agent x-newsreader
+      #recipient #any-address #mailer
+    ].freeze
+
+    # Returns one of :index, :header, :full.
+    def self.tier(ast)
+      heads = collect_path_heads(ast)
+      return :full   if heads.any? { |h| BODY_HEADS.include?(h) }
+      return :index  if heads.all? { |h| INDEX_BACKED_HEADS.include?(h) }
+      :header
+    end
+
+    # Same idea but for a list of attribute paths (e.g. fields the user wants
+    # output, or paths the user-search specs reference).
+    def self.tier_for_paths(paths)
+      heads = paths.map { |p| Array(p).first }.compact
+      return :full   if heads.any? { |h| BODY_HEADS.include?(h) }
+      return :index  if !heads.empty? && heads.all? { |h| INDEX_BACKED_HEADS.include?(h) }
+      :header
+    end
+
+    # Combine multiple tiers; the strictest wins. (full > header > index)
+    def self.combine_tiers(*tiers)
+      return :full   if tiers.include?(:full)
+      return :header if tiers.include?(:header)
+      :index
+    end
+
+    # ASCII literals from top-level AND-chained header-path comparisons,
+    # which are guaranteed to appear (substring-wise) in any matching message's
+    # raw header bytes. Skips OR branches (literals there are alternatives,
+    # not requirements) and skips negated comparisons.
+    def self.header_literals(ast)
+      walk_top_and(ast).flat_map { |node| literal_from(node) }.compact.uniq
+    end
+
+    # ---- internals ----
+
+    def self.collect_path_heads(ast)
+      heads = []
+      walk(ast) do |n|
+        case n
+        when AST::CompareNode, AST::ExistsNode
+          heads << n.path[0]
+        when AST::VarRefNode
+          # var refs are evaluated by walking the referenced mailbox,
+          # which is its own search. The OUTER caller doesn't need to load
+          # body for a var ref — only headers/index, depending on the
+          # path's head on the LHS side. The inner mailbox walk classifies
+          # itself when it runs (via VarResolver's own header-only scan).
+        end
+      end
+      heads
+    end
+
+    def self.walk(ast, &blk)
+      yield ast
+      case ast
+      when AST::AndNode, AST::OrNode then ast.children.each { |c| walk(c, &blk) }
+      when AST::NotNode then walk(ast.child, &blk)
+      end
+    end
+
+    def self.walk_top_and(ast)
+      case ast
+      when AST::AndNode then ast.children.flat_map { |c| walk_top_and(c) }
+      else [ast]
+      end
+    end
+
+    def self.literal_from(node)
+      return [] unless node.is_a?(AST::CompareNode)
+      return [] if %w[!= !~].include?(node.op)
+      return [] unless PREFILTER_HEADS.include?(node.path[0])
+      return [] unless node.value.is_a?(AST::LiteralStringNode)
+      s = node.value.value
+      return [] unless s.bytesize >= 3 && s.ascii_only?
+      [s.downcase]
+    end
+  end
+end

data/lib/mailmate/header_reader.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # Read just the header block of an `.eml` file. Pulls in a small amount of
+  # the file from disk (up to ~64 KB), stops at the first blank line that
+  # separates headers from body, and extracts named header values.
+  #
+  # Cheap relative to `Mail.read` — no MIME parsing, no body decode — when all
+  # the caller wants is `Message-ID` or `From` from a known `.eml` path.
+  #
+  # Stateless utility surface, so it's a module (cf. AppleScriptDriver, which
+  # is a class because it carries per-invocation state).
+  module HeaderReader
+    extend self
+
+    DEFAULT_MAX_BYTES = 65_536
+    CHUNK_SIZE        = 4_096
+
+    # Returns the raw bytes of the header block, capped at `max_bytes`.
+    # Truncates at the first blank line (the header/body separator) so callers
+    # looking for "To:" or similar don't accidentally match a `To:` line that
+    # appears in the body.
+    def read_block(path, max_bytes: DEFAULT_MAX_BYTES)
+      header_bytes = +""
+      File.open(path, "rb") do |f|
+        while (chunk = f.read(CHUNK_SIZE))
+          header_bytes << chunk
+          break if header_bytes.index("\r\n\r\n") || header_bytes.index("\n\n")
+          break if header_bytes.bytesize > max_bytes
+        end
+      end
+
+      if (i = header_bytes.index("\r\n\r\n"))
+        header_bytes[0, i]
+      elsif (i = header_bytes.index("\n\n"))
+        header_bytes[0, i]
+      else
+        header_bytes
+      end
+    end
+
+    # Extract a named header's value from a path. Case-insensitive. Handles
+    # RFC 5322 §2.2.3 header folding — a value continued on subsequent lines
+    # with leading whitespace is unfolded into a single line (CRLF + WSP
+    # collapsed to a single space). Returns nil if the header isn't present
+    # in the first `max_bytes` of the file.
+    def header(path, name, max_bytes: DEFAULT_MAX_BYTES)
+      block = read_block(path, max_bytes: max_bytes)
+      # Match the header name at start of line, then the rest of that line and
+      # any subsequent continuation lines (lines beginning with WSP).
+      pattern = /^#{Regexp.escape(name)}:[\t ]*(.*(?:\r?\n[\t ].*)*)/i
+      match = block.match(pattern)
+      return nil unless match
+      unfold(match[1])
+    end
+
+    # Collapse CRLF + WSP runs into a single space (RFC 5322 §2.2.3
+    # "unfolding"). Trailing whitespace is stripped.
+    def unfold(raw)
+      raw.gsub(/\r?\n[\t ]+/, " ").strip
+    end
+
+    # Convenience for the Message-ID specifically. Strips the surrounding angle
+    # brackets if present, returning the bare ID suitable for building a
+    # `mid:` URL via Mailmate::MidUrl.for.
+    def message_id(path)
+      val = header(path, "Message-ID")
+      return nil if val.nil?
+      val.match(/<([^>]+)>/)&.captures&.first || val
+    end
+  end
+end

data/lib/mailmate/identity.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # @api public
+  #
+  # "Is this address one of mine?" — answered against the identity list
+  # configured at `Mailmate.config.identities`. Personal data lives in user
+  # config (YAML or env vars), never in the gem source. This is the
+  # canonical public surface; `Mailmate::Config` is data-only.
+  module Identity
+    extend self
+
+    # Returns true if `address` matches any configured identity
+    # (case-insensitive, whitespace-trimmed). Returns false for nil / empty
+    # input, and false when no identities are configured — the "I don't know
+    # who you are yet" state, deliberately safe rather than surprising.
+    def mine?(address)
+      return false if address.nil? || address.to_s.empty?
+      addr = address.to_s.downcase.strip
+      list.include?(addr)
+    end
+
+    # The configured identity list, as an array of lowercase strings.
+    def list
+      Mailmate.config.identities.map { |a| a.to_s.downcase.strip }
+    end
+
+    # Reject "my" addresses from an array. Useful for "who's the other party
+    # in this conversation?" — pass the To/Cc/Bcc list, get back just the
+    # external addresses.
+    def reject_mine(addresses)
+      Array(addresses).reject { |a| mine?(a.to_s) }
+    end
+  end
+end