mailmate 1.4.0 → 1.6.0

data/lib/mailmate/cli/modify.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "json"
+require_relative "../flag_check"
 
 module Mailmate
   module CLI
@@ -59,12 +61,45 @@ module Mailmate
 
         warn_on_duplicates(message_id, eml_id)
 
-        drive(eml_id, message_id, actions, opts)
-        0
+        ok = drive(eml_id, message_id, actions, opts)
+
+        # --emit-check: the action is sent; defer confirmation to a later
+        # batched `mm-verify` pass. Emit the ticket as the sole stdout line
+        # (operational notes went to stderr via `say`) and exit 0 — there's
+        # nothing to fail on yet.
+        if opts[:emit_check]
+          $stdout.puts JSON.generate(build_check_ticket(eml_id, message_id, actions))
+          return 0
+        end
+
+        # Exit 3 when an effect check fails — distinct from "couldn't resolve"
+        # (1) and "bad usage" (2). The MCP surfaces this as isError, and a
+        # caller scripting mm-modify can branch on it.
+        ok ? 0 : 3
+      end
+
+      # A deferred-verification ticket: the target eml-id plus the #flags
+      # expectations its action chain should satisfy once MailMate flushes.
+      # Non-flag-verifiable chains (move/archive/delete) carry an empty list,
+      # so mm-verify auto-passes them. Symbol kinds are stringified for JSON;
+      # mm-verify / FlagCheck.met? resolve either form.
+      def build_check_ticket(eml_id, message_id, actions)
+        exps = verifiable_expectations(actions) || []
+        {
+          "eml_id"       => eml_id.to_i,
+          "message_id"   => message_id,
+          "expectations" => exps.map { |kind, arg| [kind.to_s, arg] },
+        }
+      end
+
+      # Operational notes go to stderr in --emit-check mode (stdout must be
+      # pure JSON for the ticket); otherwise to stdout as before.
+      def say(opts, msg)
+        (opts[:emit_check] ? $stderr : $stdout).puts(msg)
       end
 
       def parse_options(argv)
-        opts = { verify: false, dry_run: false, settle: 3.5, keep_window: false }
+        opts = { verify: false, dry_run: false, settle: 3.5, keep_window: false, check: false, check_timeout: 8.0, emit_check: false }
         parser = OptionParser.new do |o|
           o.banner = <<~BANNER
             Usage: mm-modify <id> <action> [args...] [<action> [args...]]...
@@ -102,6 +137,9 @@ module Mailmate
           o.on("--dry-run", "Print the actions; don't run") { opts[:dry_run] = true }
           o.on("--settle SECONDS", Float, "Timeout for waiting for MailMate's viewer window to spawn after open_url (default 3.5)") { |s| opts[:settle] = s }
           o.on("--keep-window", "Don't close the spawned message-viewer window") { opts[:keep_window] = true }
+          o.on("--check", "Verify flag/tag/read actions actually landed on the TARGET eml-id by polling its #flags index after acting (mismatch → exit 3). This is the only way to detect a `mid:` open that resolved to a different duplicate copy. Opt-in, NOT default: MailMate flushes #flags to disk several seconds after an AppleScript action, so this waits up to --check-timeout (default 8s) for the index to catch up before deciding. Chains containing move/archive/delete/junk aren't flag-verifiable and are skipped.") { opts[:check] = true }
+          o.on("--check-timeout SECONDS", Float, "Max seconds to wait for the #flags index to reflect the action when --check is set (default 8.0; the index typically lags ~5s).") { |s| opts[:check_timeout] = s }
+          o.on("--emit-check", "Don't verify inline; instead print a one-line JSON check-ticket to stdout ({eml_id, message_id, expectations}) and exit 0 once the action is sent. Collect tickets across a batch of modifies and feed them to `mm-verify` to confirm them all with a SINGLE index-flush wait, instead of paying ~5s per message. Operational notes go to stderr so stdout stays pure JSON.") { opts[:emit_check] = true }
         end
         parser.parse!(argv)
         [opts, parser]
@@ -156,6 +194,7 @@ module Mailmate
         fast_moves, other = actions.partition { |name, _, _| name == "move" }
 
         if other.empty? && !fast_moves.empty?
+          ok = true
           current_path = Mailmate::EmlLookup.path_for(eml_id)
           fast_moves.each do |_name, selector, args|
             new_path = try_fast_move(eml_id, current_path, args.first, opts)
@@ -164,9 +203,10 @@ module Mailmate
             else
               # Fast-path declined for this one move (cross-account, target
               # not found, perm error, …) — single UI-driven move as fallback.
-              drive_via_applescript(eml_id, message_id, [["move", selector, args]], opts)
+              ok &&= drive_via_applescript(eml_id, message_id, [["move", selector, args]], opts)
             end
           end
+          ok
         else
           # Mixed chain (or pure non-move chain): everything goes through the
           # AppleScript driver in the user-supplied order.
@@ -188,14 +228,14 @@ module Mailmate
 
         dest_path = File.join(dest_messages, "#{eml_id}.eml")
         if dest_path == current_path
-          $stdout.puts "move (fast): #{eml_id}.eml is already in #{target_spec} — no-op"
+          say(opts, "move (fast): #{eml_id}.eml is already in #{target_spec} — no-op")
           return dest_path
         end
 
         if opts[:dry_run]
-          $stdout.puts "move (fast, dry-run): would rename"
-          $stdout.puts "  from: #{current_path}"
-          $stdout.puts "  to:   #{dest_path}"
+          say(opts, "move (fast, dry-run): would rename")
+          say(opts, "  from: #{current_path}")
+          say(opts, "  to:   #{dest_path}")
           return dest_path
         end
 
@@ -204,7 +244,7 @@ module Mailmate
         # rescans; bust it so any subsequent path_for in this process re-reads
         # (and eventually picks up MailMate's refreshed value).
         Mailmate::IndexReader.reset!("#source") if defined?(Mailmate::IndexReader)
-        $stdout.puts "move (fast): renamed #{eml_id}.eml → #{relative_to_imap_root(dest_messages)}"
+        say(opts, "move (fast): renamed #{eml_id}.eml → #{relative_to_imap_root(dest_messages)}")
         dest_path
       rescue Errno::EACCES, Errno::EXDEV, Errno::ENOENT, Errno::EEXIST => e
         warn "move (fast): rename failed (#{e.class}: #{e.message}); falling back to AppleScript"
@@ -271,12 +311,27 @@ module Mailmate
         # the timeout for this wait rather than the sleep duration.
         new_windows = opts[:dry_run] ? [] : wait_for_new_window(driver, windows_before, timeout: opts[:settle])
 
+        # No viewer window means the `mid:` open didn't take (MailMate busy,
+        # mid-launch, or the URL didn't resolve) — performing actions now
+        # would act on whatever is currently selected, i.e. the wrong message.
+        # Retry the open once before proceeding; if it still doesn't spawn,
+        # warn loudly. Effect verification below is the backstop for flag
+        # actions; for move/archive/delete this warning is the only signal.
+        if !opts[:dry_run] && new_windows.empty?
+          driver.open_url(mid_url)
+          new_windows = wait_for_new_window(driver, windows_before, timeout: opts[:settle])
+          if new_windows.empty?
+            warn "WARNING: no MailMate viewer window appeared for #{mid_url} (retried once)."
+            warn "         The action target is UNCONFIRMED — it may hit the wrong message or no-op."
+          end
+        end
+
         # Restore unread BEFORE user actions: a subsequent move / archive /
         # delete moves the message out of the viewer's selection, after
         # which a `markAsUnread:` would land on whatever MailMate selected
         # next (or be a silent no-op).
         if preserve_unread
-          $stdout.puts "preserve-read-state: re-marking #{eml_id}.eml unread (opening the mid: URL marks it read)"
+          say(opts, "preserve-read-state: re-marking #{eml_id}.eml unread (opening the mid: URL marks it read)")
           driver.perform("markAsUnread:")
         end
 
@@ -290,7 +345,7 @@ module Mailmate
             flags = opts[:dry_run] ? [] : current_flags(eml_id)
             has   = flags.include?("\\Flagged")
             if has == want
-              $stdout.puts "#{name}: already #{want ? "flagged" : "not flagged"} — no-op"
+              say(opts, "#{name}: already #{want ? "flagged" : "not flagged"} — no-op")
             else
               driver.perform("toggleFlag:")
             end
@@ -299,6 +354,32 @@ module Mailmate
           end
         end
 
+        # Opt-in effect verification (--check): re-read the TARGET eml-id's
+        # flags and confirm the actions actually landed there. This is the
+        # only check that catches a `mid:` open resolving to a different
+        # duplicate copy — AppleScript can't tell us which message it acted
+        # on, but the index can tell us whether OUR eml-id changed.
+        #
+        # NOT default: MailMate flushes #flags to disk ~5s after an
+        # AppleScript write (measured), so verify_effects polls up to
+        # check_timeout for the index to catch up. A default-on check would
+        # either false-fail (timeout too short) or slow every modify by
+        # several seconds (timeout long enough) — neither is acceptable for
+        # the common path, so the latency is paid only when asked for.
+        # Skipped for location-changing chains (the .eml leaves the viewer).
+        verified = true
+        if opts[:check] && !opts[:emit_check] && !opts[:dry_run] && (exps = verifiable_expectations(actions))
+          verified, flags = verify_effects(eml_id, exps, timeout: opts[:check_timeout])
+          if verified
+            $stdout.puts "verify: ✓ #{exps.size} effect(s) confirmed on #{eml_id}.eml — flags: #{flags.inspect}"
+          else
+            warn "verify: ✗ effect check FAILED on #{eml_id}.eml after #{opts[:check_timeout]}s — flags: #{flags.inspect}"
+            warn "        Expected: #{exps.map { |k, a| Mailmate::FlagCheck.label(k, a) }.join(", ")}"
+            warn "        The action may have landed on a different duplicate copy, or the index"
+            warn "        still hasn't flushed. Re-run, or raise --check-timeout."
+          end
+        end
+
         # --verify is now permitted in --dry-run mode so callers can use
         # `mm-modify <id> <any-action> --dry-run --verify` as a post-hoc
         # "what's the current flag state?" probe after a separate action run.
@@ -306,12 +387,70 @@ module Mailmate
         # flush #flags before we read it back; in dry-run no wait is needed.
         if opts[:verify]
           sleep(1) unless opts[:dry_run]
-          $stdout.puts "Flags now: #{current_flags(eml_id).inspect}"
+          say(opts, "Flags now: #{current_flags(eml_id).inspect}")
         end
 
         unless opts[:keep_window] || opts[:dry_run] || new_windows.empty?
           driver.close_windows(new_windows)
         end
+
+        verified
+      end
+
+      # Actions that relocate or destroy the .eml — its #flags record moves
+      # or disappears, so post-action flag verification isn't meaningful.
+      LOCATION_ACTIONS = %w[move archive delete junk not-junk].freeze
+
+      # Build the set of #flags expectations a chain should satisfy after it
+      # runs, or nil when the chain isn't effect-verifiable. Returns nil if:
+      #   - any action changes location (move/archive/delete/junk),
+      #   - clear-tags is mixed with tag/untag (order-dependent net state we
+      #     don't model — bail rather than risk a false failure),
+      #   - nothing in the chain is flag-observable.
+      # Later actions on the same flag win (last-write); `mute` is ignored
+      # (no clean #flags signal) without blocking the rest.
+      def verifiable_expectations(actions)
+        return nil if actions.any? { |name, _, _| LOCATION_ACTIONS.include?(name) }
+
+        exp = {}
+        has_clear = false
+        has_tagop = false
+        actions.each do |name, _, args|
+          case name
+          when "read"       then exp[:seen]    = [:seen, true]
+          when "unread"     then exp[:seen]    = [:seen, false]
+          when "flag"       then exp[:flagged] = [:flagged, true]
+          when "unflag"     then exp[:flagged] = [:flagged, false]
+          when "tag"        then has_tagop = true; exp["tag:#{args.first}"] = [:tag_present, args.first]
+          when "untag"      then has_tagop = true; exp["tag:#{args.first}"] = [:tag_absent, args.first]
+          when "clear-tags" then has_clear = true
+          end
+        end
+        return nil if has_clear && has_tagop
+        exp[:clear] = [:no_user_tags, nil] if has_clear
+        exp.empty? ? nil : exp.values
+      end
+
+      # Poll the target eml-id's flags until every expectation holds or the
+      # timeout elapses (success returns on the first satisfying read, so the
+      # common case is fast; only genuine failures wait out the timeout).
+      # Returns [met?, last_flags_seen].
+      def verify_effects(eml_id, expectations, timeout:, poll: 0.1)
+        deadline = Time.now + timeout
+        flags = nil
+        loop do
+          flags = current_flags(eml_id)
+          return [true, flags] if Mailmate::FlagCheck.all_met?(flags, expectations)
+          break if Time.now >= deadline
+          sleep(poll)
+        end
+        [false, flags]
+      end
+
+      # Thin delegator kept for the unit tests that target the predicate
+      # directly; the canonical logic lives in Mailmate::FlagCheck.
+      def flag_expectation_met?(flags, kind, arg)
+        Mailmate::FlagCheck.met?(flags, kind, arg)
       end
 
       # Poll for a new MailMate window appearing in `driver.window_ids` that