imsg-grep 0.1.2-darwin

data/bin/imsg-grep

@@ -0,0 +1,749 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# Search and filter iMessage database entries with regex patterns, date ranges, and participant filters
+
+require "bundler/setup"
+
+require "date"
+require "json"
+require "sqlite3"
+require "rainbow"
+require "io/console"
+require "strop"
+
+require_relative "../lib/imsg-grep/utils/date"
+require_relative "../lib/imsg-grep/utils/strop_utils"
+require_relative "../lib/imsg-grep/messages"
+
+
+include Strop::Exports
+
+### initial values and defaults
+PROG = File.basename($0)
+@utc = false
+@case = :smart
+@mode = :regexp
+@exact = false
+@negate = false
+@next_bool = nil
+@conditions = []
+
+class Cond < Array # basically a tuple with named accessors for positions
+  %i[ key term bin_op not_op opt ].zip(0..).each do |m, i|
+    define_method(m){ self[i] }
+    define_method("#{m}="){|v| self[i] = v }
+  end
+end
+
+class << @conditions
+  def on(key)       = filter{|k,| k == key }
+  def atomics(key)  = filter{|k,_,b,n,| k == key && b.nil? && !n } # conds without a connective operator
+  def positive(key) = filter{|k,_,_,n,| k == key && !n } # conds without negation
+end
+
+### tiny helpers
+
+def consume(ivarname) = instance_variable_get(ivarname).tap{ instance_variable_set(ivarname, nil) }
+
+# wrap and indent text, respecting SGR sequences; only if tty
+def wrap(s, indent=0, maxw = IO.console.winsize[1] - 2, disable: (!$stdout.tty?||@no_wrap), wrap_all: false)
+  return s if disable
+  sgr = /\e\[[\d;]*m/
+  pad = "\e[#{indent}C"
+
+  s.lines.map(&:chomp).each_with_object([]) do |line, acc|
+    next acc << pad+line if line =~ %r[^#{sgr}*https?://\S+\z] unless wrap_all # don't wrap link lines
+    w = maxw - indent
+    line.scan(sgr) { $~.begin(0) > w ? break : w += it.bytesize } # increase w to account for SGR
+    ix = (line.rindex(" ", w) || w-1 if line.size > w)            # find last space before w, or use w, or nil when short enough
+    acc << pad + line.slice!(..ix).chomp(" ")
+    redo unless line.empty?
+  end*?\n
+end
+
+def info!(s) = $stderr.puts("#{PROG}: #{s}")
+def err!(s)  = info!("error: #{s}")
+def warn!(s) = (info!("warning: #{s}") unless @no_warn)
+
+################################################################################
+### parse helpers ##############################################################
+################################################################################
+
+def parse_date(str, utc = @utc)
+  DateArg.parse(str, utc)
+rescue DateArg::Error
+  raise OptionError, "invalid date #{str} (format: yyyy-mm-dd or 1y4m2d; see --help-dates)"
+end
+
+def parse_p_int(str)
+  Integer(str).tap{ raise ArgumentError unless it > 0 }
+rescue ArgumentError
+  raise OptionError, "not a positive integer: #{str}"
+end
+
+def parse_capture(str)
+  case str
+  when nil                  then '\0'
+  when /\A\d(,\d)*\z/       then str.gsub(/(?=\d)/, ?\\).gsub(",", " ") # 1 or 1,2; "1,2" => "\1 \2"; 0 == $&
+  when /(?<!\\)\\[&\d`'&+]/ then str
+  else raise OptionError, "invalid capture expression: #{str} (format: '1,2' or '\\1 \\2')"
+  end
+end
+
+def rx_abbr(pat) = /^#{pat.chars.map{ Regexp.escape it }.join(".{,8}?")}/i
+
+def parse_service(str)
+  srvs = %w[ any imessage rcs sms ]
+  str.split(?,).map do |s|
+    m = srvs.grep(rx_abbr s).first # safe to assume .first as /^./ all distinct
+    # warn but let through, if \W, assume regexp and dont warn
+    warn! "unknown service: #{s} (will try to match anyway)" if m.nil? && s !~ /\W/
+    m += ?$ if srvs.include? m  # full match for known services
+    m ||= s                     # fallback to str if unknown
+    m = "" if m == "any"        # empty str will match anything
+    m
+  end.join(?|).then{ /^(?:#{it})/i }
+end
+
+# LIKE is too much of a mess. ASCII-insensitive, only sensitive option is GLOB.
+# We'll be regexing everything, even literals, at maybe some perf cost.
+def mk_regexp(src)
+  pattern = src
+  case_ = @case
+  case_ = /\p{Upper}/ =~ pattern ? :sensitive : :ignore if case_ == :smart
+  pattern = Regexp.escape(pattern) if @mode == :literal
+  pattern = "\\A#{pattern}\\z" if consume :@exact
+  flags = [Regexp::IGNORECASE] if case_ == :ignore
+  Regexp.new(pattern, *flags)
+rescue RegexpError => e
+  raise OptionError, "invalid regular expression: #{src} (#{e.message})"
+end
+
+def add_cond(key, term, negate: false, via:)
+  bin_op = consume(:@next_bool)
+  if bin_op
+    raise OptionError, "no previous condition to apply --#{bin_op} to" unless @conditions.last
+    @conditions.last.bin_op ||= "" # generates no sql but evals true
+  end
+  @conditions << Cond[key, term, bin_op, (:not if negate), via]
+end
+
+def repeat_cond(term, negate: false, via:)
+  last = @conditions.last
+  raise OptionError, "no previous condition to apply --#{@next_bool} to" unless last
+  raise OptionError, "--#{@next_bool} attemped with non-pattern condition #{last.opt._name}" unless Regexp === last.term
+  add_cond last.key, term, negate:, via:
+end
+
+def next_bool op
+  raise OptionError, "--#{@next_bool} with no argument followed by --#{op}" if @next_bool
+  @next_bool = op
+end
+
+################################################################################
+### begin option parsing #######################################################
+################################################################################
+begin
+  def read_doc(f) = IO.read(__dir__ + "/../doc/#{f}")
+  HELP = read_doc("HELP").gsub("PROG", PROG)
+  HELP_OPTS = HELP[/.*?(?=~~)/m].strip
+  optlist = Strop.parse_help HELP_OPTS
+  optlist << Optdecl[:D, :debug] # hidden opt
+  optlist << Optdecl[:opts?] if File.directory? __dir__ + "/../.git" # only available during development
+
+  # custom opt shorthands for max and relative dates: -1 == -n1, -1d == -d1d
+  # strop can't handle this (yet?) so we transform ahead
+  argvl, argvr = [ARGV, ARGV.index("--")].then{|a, i| [a[...i], i ? a[i..] : []] }
+  argvl.map! do |x|
+    x =~ /\A-((\d+)|(#{DateArg::RX_REL_DATE_PART}|#{DateArg::RX_REL_TIME_PART}))\z/
+    case [$2, $3]
+    in String, nil then "-n#{$1}"
+    in nil, String then "-d#{$1}"
+    in nil, nil    then x
+    end
+  end
+
+  result = Strop.parse optlist, argvl + argvr
+
+  (puts HELP_OPTS; exit 1) if result.empty?
+
+  capture_opts = %w[ capture ]
+  text_opts    = %w[ no-meta no-wrap count preview img tiny short-names urls color count ]
+  json_opts    = %w[ json payload ]
+  result.incompatible json_opts, text_opts
+  result.incompatible json_opts, capture_opts
+  result.incompatible :no_wrap, :preview
+  result.incompatible %w[ one-line tiny no-meta ], %w[ list-files ]
+
+  result.compact_singles! %w[ max capture ]
+
+  result.disallow_empty # for all
+
+  for opt in result
+    case opt
+    in Sep # ignore; `arg:` will handle .rest just fine
+    in label: "since", value:    then add_cond :since, parse_date(value), via: opt
+    in label: "until", value:    then add_cond :until, parse_date(value), via: opt
+    in label: "to",    value:    then add_cond :to,    mk_regexp(value), negate: consume(:@negate), via: opt
+    in label: "from",  value:    then add_cond :from,  mk_regexp(value), negate: consume(:@negate), via: opt
+    in label: "with",  value:    then add_cond :with,  mk_regexp(value), negate: consume(:@negate), via: opt
+    in label: "chat",  value:nil then add_cond :chat,  true,             negate: consume(:@negate), via: opt
+    in label: "chat",  value:    then add_cond :chat,  mk_regexp(value), negate: consume(:@negate), via: opt
+    in label: "sent"             then add_cond :from_me, true,  via: opt
+    in label: "received"         then add_cond :from_me, false, via: opt
+    in label: "links", value:nil then add_cond :links, true, via: opt
+    in label: "links", value:    then add_cond :links, mk_regexp(value), negate: consume(:@negate), via: opt
+    in label: "youtube"          then add_cond :links, :youtube,    via: opt
+    in label: "soundcloud"       then add_cond :links, :soundcloud, via: opt
+    in label: "twitter"          then add_cond :links, :twitter,    via: opt
+    in label: "service", value:  then srv = parse_service(value) and add_cond :service, srv, via: opt
+    in label: "and", value:nil   then next_bool :and
+    in label: "or",  value:nil   then next_bool :or
+    in label: "and", value:      then next_bool :and; repeat_cond mk_regexp(value), negate: consume(:@negate), via: opt
+    in label: "or",  value:      then next_bool :or;  repeat_cond mk_regexp(value), negate: consume(:@negate), via: opt
+    in label: "smart-case"       then @case = :smart
+    in label: "ignore-case"      then @case = :ignore
+    in label: "no-ignore-case"   then @case = :sensitive
+    in label: "literal"          then @mode = :literal
+    in label: "regexp"           then @mode = :regexp
+    in label: "capture", value:  then @capture   = parse_capture(value)
+    in label: "exact"            then @exact     = opt
+    in label: "invert-match"     then @negate    = true
+    in label: "max", value:      then @allow_all = true; @max = parse_p_int(value)
+    in label: "all"              then @allow_all = true
+    in label: "urls"             then @urls      = true
+    in label: "no-wrap"          then @no_wrap   = true
+    in label: "one-line"         then @one_line  = true
+    in label: "count"            then @count     = true
+    in label: "reverse"          then @reverse   = true
+    in label: "utc"              then @utc       = true
+    in label: "json"             then @json      = true
+    in label: "no-meta"          then @no_meta = true; @list_files = false
+    in label: "short-names"      then @short_names = true
+    in label: "payload"          then @json = @payload = true
+    in label: "tiny"             then @short_names = @urls = @one_line = true
+    in label: "list-files"       then @list_files = true
+    in label: "no-list-files"    then @list_files = false
+    in label: "color"            then Rainbow.enabled = opt.yes?
+    in label: "img"              then @preview ||= []; @preview|= ["images"]; add_cond :files, :images, via: opt
+    in label: "silence-warnings" then @no_warn = true
+    in label: "version"          then puts "imsg-grep v#{ IO.read("#{__dir__}/../lib/imsg-grep/VERSION").chomp }"; exit
+    in label: "debug"            then @debug = true
+    in label: "opts", value:     then optlist.report_usage(value); exit # dev stuff: Used to see what options are still available
+
+    in label: "help-dates"       then puts read_doc("HELP_DATES"); exit
+    in label: "help"             then
+      long = opt.name != ?h || result[[:help]].size > 1 # ! -h || -hh
+      if long
+        puts HELP.sub(/^~~.*\n/, '')
+        puts "\nFor a shorter help summary, use -h"
+      else
+        puts HELP_OPTS
+        puts "\nSee --help for more"
+      end
+      exit
+
+    in label: "preview", value:
+      previewables = %w[ images links ]
+      next @preview = previewables if value.nil?
+      @preview = value.split(?,).map do |v|
+        previewables.grep(rx_abbr v).first or raise OptionError, "invalid preview target: #{v}"
+      end
+
+    in label: "files", value:
+      value = "any" if value.nil?
+      value.split(/(?!<\\),/).map{ it.split(?:, 2) }.each do |spec|
+        _add_cond = ->cond{ add_cond :files, cond, negate: consume(:@negate), via: opt }
+        case spec
+        in [/^a(ny)?$/]         then _add_cond.call :any
+        in [/^i(mg?|mages?)?$/] then _add_cond.call :images
+        in [/^n(ame)?$/, v]     then _add_cond.call [:name, mk_regexp(v)]
+        in [/^m(ime)?$/, v]     then _add_cond.call [:mime, mk_regexp(v)]
+        in [/^e(xt)?$/, v]      then _add_cond.call [:ext,  mk_regexp(v)]
+        else raise OptionError, "invalid file specifier: #{[*spec]*?:} (in #{value})"
+        end
+      end
+
+    in Arg(arg: _) | Opt(label: "message", value: _)
+      add_cond :message, mk_regexp(opt.value), negate: consume(:@negate), via: opt
+
+    in label: "reset"
+      Messages.reset_cache
+      exit if (result.opts.map(&:label) - ["reset"]).empty? && result.args.empty? # exit if opt used alone
+
+    end
+  end
+
+  @list_files = !@one_line && !@json if @list_files.nil?
+
+  def preview?(kind=nil) = kind ? @preview&.include?(kind.to_s) : @preview&.any?
+
+
+################################################################################
+### checking conflicting options ###############################################
+################################################################################
+
+  if @conditions.empty? && !@allow_all
+    raise OptionError, "no filter conditions given (use --all or --max to allow)" # too much stuff
+  end
+
+  if @conditions.atomics(:from_me).map(&:term).uniq.size > 1
+    raise OptionError, "cannot use --sent and --received together" # empty result
+  end
+
+  # warn multiple dates
+  d0, d1 = ds = [@conditions.atomics(:since), @conditions.atomics(:until)]
+  warn! "multiple since dates given (most recent date wins)"  if d0.size > 1
+  warn! "multiple until dates given (least recent date wins)" if d1.size > 1
+
+  # try to warn date conflicts: since > until
+  begin # if a mix of Time & Date, sorting/comparison will fail, so we just bail
+    d0, d1 = ds.map{ it.map(&:term).sort }
+    d0, d1 = d0.last, d1.first
+    bad_dates = d0 && d1 && d0 > d1
+  rescue ArgumentError
+    bad_dates = nil
+  end
+  raise OptionError, "since date must be before until date" if bad_dates
+
+  # ignore request for all links when already getting more specific site links
+  # -L(noarg) + -[YSX]|Larg, kinda useless
+  any_links, site_links = @conditions.atomics(:links).partition{ it.term == true }
+  if any_links.any? && site_links.any?
+    any_links.each{ @conditions.delete it }
+    overrides = site_links.map{ [it.opt._name, it.opt.value].compact*' ' }
+    warn! "ignoring #{any_links[0].opt._name} (overriden by #{overrides.join(', ')})"
+  end
+
+  # require mag pattern for -o
+  # warn -o with multiple msg patterns
+  # ignore -v patterns
+  if @capture
+    aconds = @conditions.atomics(:message)
+    *pats, @capture_pat = aconds.map(&:term) # take last pattern for capture refs, rest for warn
+    bool_note = (@conditions.on(:message) - aconds).any?
+    raise OptionError, "#{result[:capture]._name} requires a message pattern#{' outside boolean expressions' if bool_note}" unless @capture_pat
+    warn! "#{result[:capture]._name} used with multiple message patterns (will capture from last)" unless pats.empty?
+  end
+
+  @negate    and warn! "last #{result[[:invert_match]].last._name} disregarded (not followed by pattern)"
+  @exact     and warn! "last #{result[[:exact]].last._name} disregarded (not followed by pattern)"
+  @next_bool and warn! "last #{result.opts.reverse_each.find{ %w[ and or ].include? it.label }._name} disregarded (not followed by pattern)"
+
+  require_relative "../lib/imsg-grep/images/imaginator" if preview?
+  if preview? && !Imaginator.image_tooling?
+    @preview = nil
+    e = "previews disabled: "
+    case
+    when !Imaginator::EXTENSION_AVAILABLE then warn! e + "img2png extension not compiled"
+    when !Imaginator.term_image_protocol  then warn! e + "no terminal support for images"
+    when !Imaginator.cell_size            then warn! e + "cannot determine cell dimensions"
+    end
+  end
+
+################################################################################
+### build sql query ############################################################
+################################################################################
+
+  def date_cmp(op, dt)
+    case [dt, @utc]
+    in Date, true  then "utc_date   #{op} '#{dt.strftime('%Y-%m-%d')}'"
+    in Date, false then "local_date #{op} '#{dt.strftime('%Y-%m-%d')}'"
+    in Time, _     then "unix_time  #{op} #{dt.to_i}"
+    end
+  end
+
+  def match(x, r) = "#{x} REGEXP '#{SQLite3::Database.quote r.to_s}'"
+  def match_searchable(x, r) = "EXISTS (SELECT 1 FROM json_each(#{x}) WHERE #{match(:value, r)})"
+
+  groups = @conditions.slice_before{ !(Symbol === it.bin_op) }
+
+  default_or = %i[ links service from chat files ] # these conds do OR by default (unless negated)
+  singles, grouped = groups.partition{|group| group in [[_, _, nil, *]] } # singles = a group with single elem, no bin op
+  keyed_singles = singles.flatten(1).group_by(&:first)
+  keyed_singles.each do |k, group|
+    op = default_or.include?(k) ? :or : :and
+    group[1..]&.each{ it.bin_op = it.not_op ? :and : op } # first member doest get op; negated exprs on base expr always AND
+  end
+
+  # put the easy filters first for performance
+  filter_order = %i[ from_me since until service files links ]
+  sorted_singles = keyed_singles.sort_by{|k,| filter_order.index(k) || Float::INFINITY }.map(&:last)
+  groups = sorted_singles + grouped  # put it back together
+
+  Messages.init
+
+  @file_filters = []
+  if @conditions.on(:files).any?{ it.term in [_, Regexp] }
+    Messages.db.ƒ(:filename){ it[(it.rindex(?/) || -1)+1..] }
+    Messages.db.ƒ(:fileext) { i = it.rindex(?.) and it[i+1..] or "" }
+    def add_file_filter(sel) = "file_filter_#{@file_filters.size}".tap{|as| @file_filters << [sel, as].join(" as ") }
+  end
+
+  sql_cond = groups.map do |group|
+    group.map do |key, term, bin_op, not_op|
+      sql = case [key, term]
+      in :since,   _           then date_cmp(:>=, term)
+      in :until,   _           then date_cmp(:<=, term)
+      in :from_me, _           then "is_from_me IS #{term}"
+      in :links,   true        then "link IS NOT NULL"
+      in :links,   :youtube    then match(:link, %r["https?://((www\.)?youtube\.com|youtu\.be)/]i) # matching inside json, " acts as \A sort of
+      in :links,   :soundcloud then match(:link, %r["https?://(on\.)?soundcloud\.com/]i)
+      in :links,   :twitter    then match(:link, %r["https?://(pic\.)?(twitter|x)\.com/]i)
+      in :links,   Regexp      then match(:link, term)
+      in :from,    Regexp      then match_searchable(:sender_searchable, term)
+      in :to,      Regexp      then match_searchable(:recipients_searchable, term)
+      in :with,    Regexp      then match_searchable(:members_searchable, term)
+      in :chat,    Regexp      then match(:chat_name, term)
+      in :chat, (true | false) then "(is_group_chat IS #{'NOT' unless term} TRUE)" # so nulls also match -vc
+      in :message, Regexp      then match(:text, term)
+      in :service, Regexp      then match(:service, term)
+      in :files, :any          then "(has_attachments AND has_files IS TRUE)"  # has_attachments first should be a faster check
+      in :files, :images       then "(has_attachments AND has_images IS TRUE)"
+      in :files, [:mime, Regexp => r] then add_file_filter(match("a.mime_type",          r)).then{ "#{it} IS TRUE" }
+      in :files, [:name, Regexp => r] then add_file_filter(match("filename(a.filename)", r)).then{ "#{it} IS TRUE" }
+      in :files, [:ext,  Regexp => r] then add_file_filter(match("fileext(a.filename)",  r)).then{ "#{it} IS TRUE" }
+
+      end
+      ops = [bin_op, not_op].compact.join(" ").upcase
+      sql = "#{ops} #{sql}".lstrip
+    end.join("\n  ").then{ "(#{it})" }
+  end.join("\nAND ")
+
+  limit = "LIMIT #{@max}" if @max
+  time_col = @utc ? :utc_time : :local_time
+
+  sql = <<~SQL
+    WITH attachment_flags AS (
+      SELECT
+        m.ROWID as message_id,
+        #{[*@file_filters, ""].join(",\n")}
+        MAX(CASE WHEN a.mime_type LIKE 'image/%' THEN 1 ELSE 0 END) as has_images,
+        MAX(a.mime_type IS NOT NULL) as has_files -- this excludes the uti like 'dyn.%'  files
+      FROM _imsg.message m
+      JOIN _imsg.message_attachment_join maj ON m.ROWID = maj.message_id
+      JOIN _imsg.attachment a ON maj.attachment_id = a.ROWID
+      WHERE m.cache_has_attachments
+      GROUP BY m.ROWID
+    )
+    SELECT
+      #{'payload_json,' if @payload}
+      m.message_id,
+      guid,
+      has_attachments,
+      af.has_images IS TRUE as has_images,
+      af.has_files  IS TRUE as has_files,
+      sender_name as "from",
+      recipient_names as "to",
+      is_group_chat,
+      chat_name,
+      text,
+      link,
+      service,
+      utc_time,
+      #{time_col} as time
+    FROM message_view m
+    LEFT JOIN attachment_flags af ON m.message_id = af.message_id
+    #{"WHERE\n" + sql_cond unless sql_cond.empty?}
+    ORDER BY unix_time #{@reverse ? 'ASC' : 'DESC'}
+    #{limit}
+  SQL
+
+  if @debug
+    bat = `command -v bat >/dev/null 2>&1` && $?.success? ? %w[bat -l sql] : "cat"
+    IO.popen(bat, 'w', out: :err) { it << sql }
+  end
+
+  slow = unless @no_warn || result[:since] || Messages.db.execute("SELECT 1 FROM _cache.texts LIMIT 1").empty? # no cache is meant to be slow
+    Thread.new do
+      sleep 1
+      info! "hint: taking too long? try --since with a short time distance"
+    end
+  end
+
+  messages = Messages.db.select_hashes(sql)
+
+  if @list_files || preview?(:links)
+    ids = messages.select{ it[:has_attachments] == 1 }.map{ it[:message_id] }.join(", ")
+    all_files = Messages.db.select_hashes(<<~SQL).group_by{ it[:message_id] }
+      SELECT a.ROWID, a.filename, a.mime_type, a.uti, m.ROWID as message_id
+      FROM _imsg.attachment a
+      JOIN _imsg.message_attachment_join maj ON a.ROWID = maj.attachment_id
+      JOIN _imsg.message m ON maj.message_id = m.ROWID
+      WHERE m.ROWID IN (#{ids})
+      ORDER BY m.ROWID, a.ROWID
+    SQL
+    messages.each{ it[:files] = all_files[it[:message_id]] || [] }
+  end
+
+
+################################################################################
+### Massage results ############################################################
+################################################################################
+
+  messages.each do |msg|
+    msg[:from]        ||= "me"
+    msg[:to]            = JSON.parse(msg[:to] || '["me"]')
+    msg[:link]          = JSON.parse(msg[:link] || "null")&.transform_keys(&:to_sym)
+    msg[:payload]       = JSON.parse(msg.delete(:payload_json) || "null") if msg.key? :payload_json
+    msg[:is_group_chat] = msg[:is_group_chat] == 1
+  end
+
+  slow&.kill
+
+  if @json
+    puts JSON.send(@one_line ? :generate : :pretty_generate, messages)
+    exit
+  end
+
+  class String
+    # 'xxx'.cleave(nil) # => %w[ xxx ]
+    # 'a1b2c3d'.cleave(/\d/) # => %w[ a 1 b 2 c 3 d ]
+    # (cant use split(/(...)/) bc inner regexen may have captures)
+    def cleave(rx, &)
+      return [self] unless rx
+      r, i = [], 0
+      scan(rx) { r << self[i...$~.begin(0)] << $&; i = $~.end(0) }
+      r << self[i..]
+    end
+  end
+
+  # stylesheets :P
+  @c = c = Object.new
+  def c.pass(s)         = s
+  def c.link(s)         = Rainbow(s).green
+  def c.link!(s)        = Rainbow(s).green.bright
+  def c.match!(s)       = Rainbow(s).magenta.bright
+  def c.capture!(s)     = Rainbow(s).red.bright
+  def c.l_time(s)       = Rainbow(s).bright.blue
+  def c.l_from(s)       = Rainbow(s).yellow
+  def c.l_to(s)         = Rainbow(s).yellow.bright
+  def c.label(s)        = Rainbow(s).yellow
+  def c.value(s)        = Rainbow(s).yellow.bright
+  def c.link_title(s)   = Rainbow(s).cyan.bright
+  def c.link_summary(s) = Rainbow(s).cyan
+  def c.count(s)        = Rainbow(s).cyan
+  def c.files(s)        = Rainbow(s).cyan
+  def c.file_path_bad(s)= Rainbow(s).red
+  def c.file_path(s)    = Rainbow(s).cyan.faint
+  def c.file_name(s)    = Rainbow(s).cyan.bright
+
+  # to highlight all matches in text, inside links
+  m_conds = @conditions.positive(:message).map(&:term)
+  l_conds = @conditions.positive(:links).map(&:term).select{ Regexp===it } + m_conds
+  rx_highlight      = /#{m_conds*?|}/ if m_conds.any?
+  rx_link_highlight = /#{l_conds*?|}/ if l_conds.any?
+
+  def highlight(s, r, a, b)
+    return unless s
+    s.cleave(r).each_slice(2).flat_map do |sa, sb|
+      [ (@c.send(a, sa) if sa && !sa.empty?),
+        (@c.send(b, sb) if sb && !sb.empty?)]
+    end.join
+  end
+
+
+  ################################################################################
+  ## link/image preview setup ####################################################
+  ################################################################################
+  if preview?
+    # suppress CFPropertyList warnings on stderr. They're harmless but affect image rendering
+    ENV["OS_ACTIVITY_MODE"] = ENV["OS_ACTIVITY_DT_MODE"] = "disable"
+
+    POOL = Concurrent::FixedThreadPool.new(Concurrent.processor_count - 1)
+    cols = IO.console.winsize[1]
+    @link_preview_cols = [(cols - 2) / 2, 20].min
+    @link_preview_min_rows = 6
+    @img_rows = 8
+    @link_images = {}
+    @images = {}
+
+    # because we need to retain the imgs for resizing, too many links will use too much memory
+    # so instead we release and reload them if need to resize again
+    release_links = preview?(:links) && messages.count{it[:link]} > 1000
+
+    messages.each do |msg|
+      preview?(:links) and
+      link = msg[:link] and
+      @link_images[link] = Concurrent::Promises.future_on(POOL, msg) do |msg|
+        ix   = link[:image_idx] or next
+        file = msg.dig(:files, ix) or next
+        path = File.expand_path file[:filename]
+        img  = Imaginator::Image.new(path).load or next
+        fit, fits = img.fit @link_preview_cols, @link_preview_min_rows
+        png = img.png_transform w:fit.w, h:fit.h, pad_w:fits[:cfit].pad_w
+        if release_links
+          img.release
+          img = path
+        end
+        # if safe enough to not release: don't release img yet, might reuse. released after png use
+        [fit, png, img]
+      end
+      msg[:images] = msg[:files].select{ it[:mime_type]&.start_with?('image/') }
+      preview?(:images) and msg[:images].each do |im|
+        @images[im] = Concurrent::Promises.future_on(POOL, im) do |im|
+          path = File.expand_path im[:filename]
+          img  = Imaginator::Image.new(path).load or next
+          fit, = img.fit 25, @img_rows
+          png  = img.png_transform w:fit.w, h:fit.h
+          img.release
+          [fit, png]
+        end # promise
+      end # images
+    end # messages
+  end # preview
+
+  ################################################################################
+  ### Print messages #############################################################
+  ################################################################################
+
+  for msg in messages
+    msg => guid:, from:, to:, chat_name:, text:, link:, time:, is_group_chat:, has_attachments:
+    files = msg[:files]
+
+    if @short_names
+      rename = ->s{ s.sub(/^(\p{Alpha}\S*)(?:.*\s+(\p{Alpha})\S*)?(?: \(.+\))?$/){ [$1, $2].compact.join(" ") } }
+      from = rename.(from)
+      to.map!(&rename)
+      chat_name = chat_name&.sub(/^.{8}\K(.+)/m, "…") if @one_line
+    end
+
+    # highlight matches inside urls
+    url,  ourl  = link&.values_at(:url, :original_url)
+    curl, courl = [url, ourl].map { highlight(it, rx_link_highlight, :link, :link!) }
+
+    text = text.to_s.dup
+    if @urls && url  # -U captured links replace text
+      text = curl
+    elsif @capture   # replace text with eval'd capture output string
+      m1   = @capture_pat.match text
+      m2   = { ?` => $`, ?' => $', ?& => $&, ?+ => $+ }
+      refs = /\\(?:(\d)|([&`'+]))|\\(\\)/ # 3 = \, 2 = `'&+ refs, 1 = digits
+      text = @capture.gsub(refs){ $3 || c.capture!(m2[$2] || m1[$1.to_i]) }
+    else
+      rx_links = (/#{[ourl, url].compact.map{Regexp.escape it}*?|}/ if link)
+      has_link = link && text =~ rx_links
+      # hightlight matches in text, first replacing links with colored versions from above
+      text = text.cleave(rx_links).each_slice(2).flat_map do |s, u|
+        msg_text = highlight(s, rx_highlight, :pass, :match!) # hilight the message part that is not link
+        msg_url  = { ourl => courl, url => curl}[u]           # urls highlighted earlier, use that
+        [msg_text, msg_url]
+      end.join
+      # append whole url if not fully present in text (missing protocol etc)
+      text << "\n\n" << curl if link && !has_link
+    end
+
+    oneline = ->s { s.gsub(/\p{Space}*\R\p{Space}*/, " ").strip }
+    text = oneline[text] if @one_line
+
+    if has_attachments && text =~ /\A\uFFFC*\z/ # if text is empty or only object marker
+      text = @list_files && !@one_line ? "" : c.files("[files]")
+    end
+
+    text = text.gsub(/\uFFFC/, c.files(?░)) if @list_files && has_attachments
+
+    unless @no_meta
+      nn      = "\n\n"
+      title   = (link[:title]   if link)
+      summary = (link[:summary] if link)
+      link_image_result = (@link_images.delete(link)&.value! if link && preview?(:links))
+    end
+
+    if @no_meta # oneline included, already onelined above
+      puts text
+    elsif @one_line
+      text << " #{c.link_summary(oneline[title])}" if title
+      to = chat_name.to_s.empty? ? to*', ' : chat_name
+      buf = "#{c.l_time time} [#{c.l_from from} -> #{c.l_to to}]: #{text}"
+      buf.prepend "#{guid} " if @debug
+      puts buf
+    else
+      buf = {
+        GUID: (guid if @debug),
+        From: from,
+        "To..": (to*', ' unless is_group_chat),
+        With:   (to*', ' if is_group_chat),
+        Chat: chat_name,
+        Date: time
+      }.reject{|k,v| v.to_s.empty? }.map{|k,v| "#{c.label k}: #{c.value v}" }*?\n << nn
+
+      puts buf
+
+      pad = 2
+      pad += 1 + @link_preview_cols if link_image_result
+
+      buf = +""
+      buf << wrap(text, pad, wrap_all: !!link_image_result) << nn unless text.empty?
+      buf << c.link_title(wrap(title, pad, wrap_all: !!link_image_result)) << nn if title
+      buf << c.link_summary(wrap(summary, pad, wrap_all: !!link_image_result)) << nn if summary
+
+      if link_image_result
+        buf_rows = buf.strip.count(?\n) + 1
+        img_rows = [buf_rows, @link_preview_min_rows].max
+        fit, png, img = link_image_result
+        if img_rows != @link_preview_min_rows
+          img = Imaginator::Image.new(img).load if img.is_a? String # it's a path, original img released
+          fit1, fits = img.fit @link_preview_cols, img_rows
+          # if the backround render image is different from what we need now that we know the text size, do it again
+          if fit1 != fit
+            fit = fit1
+            png = img.png_transform w:fit.w, h:fit.h, pad_w:fits[:cfit].pad_w
+          end
+        end
+        img.release unless img.is_a? String
+        print " "
+        Imaginator.print_image(data: png, c: @link_preview_cols)
+        puts
+        print "\e[#{fit.r}A" # go up by image rows
+      end
+
+      print buf
+      (fit.r - buf_rows).times{ puts } if link_image_result # fill newlines past img
+
+      if @list_files
+        for file in files.reject{ it[:mime_type].nil? }
+          path, _, name = file[:filename].rpartition %r_(?<=/)_
+          p, q, r = path.rpartition %r_/\KTemporaryItems(?=/)_
+          path = c.file_path(p) + c.file_path_bad(q) + c.file_path(r)
+          puts "  " + path + c.file_name(name) + ?\n
+        end
+        puts
+
+        # gotta load them all upfront cause gotta know if the last exists for cursor move
+        # deleting helps GC
+        images = msg[:images] && msg[:images].map{ @images.delete(it)&.value! }.compact
+        if preview?(:images) && images.any?
+          maxcols  = IO.console.winsize[1] - 2
+          (print "  "; cols = 2)
+          for img_result, ix in images.zip(1..)
+            fit, png, img = img_result
+            cols += fit.c
+            if cols > maxcols
+              print "\n" * (fit.r+1)
+              (print "  "; cols = 2 + fit.c)
+            end
+            Imaginator.print_image(data: png, r: fit.r)
+            (print "\e[#{fit.r - 1}A "; cols += 1) unless ix == images.size # move back up for next image unless last
+          end
+          puts nn
+        end
+      end
+
+    end
+  end # for msgs
+
+  if @count
+    n = messages.size
+    s = "#{n} message#{?s unless n == 1} found"
+    s << " (#{result[:max]._name} used)" if @max && n == @max
+    info! c.count s
+  end
+
+  # exiting with code seems to prevent at_exit from running, which will not populate cache, but well, it is what it is. will cache on next match
+  exit 1 unless messages.any?
+
+rescue OptionError => e
+  err! e.message.sub(/^./){ $&.downcase } # strop using upcases but we aren't; not ready to change this on strop yet
+  info! "see --help for usage information"
+  exit 64 # cf. man 3 sysexits
+end