browserctl 0.10.0 → 0.12.0

data/lib/browserctl/replay/context.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Replay
+    # Per-page replay context carried by PageProxy during a workflow run
+    # generated from a recording.
+    #
+    # Holds the recorded fingerprint for each selector that the workflow
+    # interacts with. When a selector-driven command fails with
+    # selector_not_found at replay time, the proxy looks up the fingerprint
+    # here and asks FingerprintMatcher to find a candidate in the live
+    # snapshot. The matched element's stable ref is then re-used to retry
+    # the original command.
+    #
+    # Drift events (rematches, threshold misses) are accumulated on the
+    # context so the surrounding workflow runner can render them into a
+    # drift report at end-of-run.
+    class Context
+      DriftEvent = Struct.new(:command, :selector, :matched_ref, :score, :reason, keyword_init: true)
+
+      attr_reader :drift_events
+
+      def initialize(fingerprints: {})
+        @fingerprints = fingerprints
+        @drift_events = []
+      end
+
+      def fingerprint_for(selector)
+        @fingerprints[selector]
+      end
+
+      def record(command:, selector:, matched_ref: nil, score: nil, reason: nil)
+        @drift_events << DriftEvent.new(
+          command: command, selector: selector,
+          matched_ref: matched_ref, score: score, reason: reason
+        )
+      end
+    end
+  end
+end

data/lib/browserctl/replay/fingerprint_matcher.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Replay
+    # Scores candidate snapshot entries against a recorded fingerprint and
+    # returns the best match above a configurable threshold.
+    #
+    # Inputs are the wire-shape fingerprints emitted by Snapshot::Fingerprint:
+    #   { text:, role:, neighbors: [...], position: { index:, depth: } }
+    #
+    # Score is a weighted sum in [0.0, 1.0]:
+    #   text      0.40   (exact match; case-insensitive)
+    #   role      0.20   (exact match)
+    #   neighbors 0.25   (Jaccard over the neighbor sets)
+    #   position  0.15   (proximity in (index, depth) space)
+    #
+    # Defaults reflect the v0.11 acceptance bar: text + role together (0.60)
+    # are enough to clear the default threshold, so a renamed neighbor or a
+    # shifted index doesn't break replay.
+    class FingerprintMatcher
+      DEFAULT_THRESHOLD = 0.6
+      WEIGHTS = { text: 0.40, role: 0.20, neighbors: 0.25, position: 0.15 }.freeze
+
+      Match = Struct.new(:candidate, :score, keyword_init: true)
+
+      def initialize(threshold: DEFAULT_THRESHOLD, weights: WEIGHTS)
+        @threshold = threshold
+        @weights = weights
+      end
+
+      # Returns the highest-scoring candidate entry above the threshold, or
+      # nil if no candidate qualifies. `candidates` must be an array of
+      # snapshot entries (hashes with a :fingerprint key). The returned
+      # Match wraps the candidate hash and the numeric score.
+      def best(target_fp, candidates)
+        scored = candidates
+                 .map { |c| Match.new(candidate: c, score: score(target_fp, c[:fingerprint])) }
+                 .sort_by { |m| -m.score }
+
+        winner = scored.first
+        return nil unless winner && winner.score >= @threshold
+
+        winner
+      end
+
+      def score(target, candidate)
+        return 0.0 unless target && candidate
+
+        (@weights[:text] * text_score(target[:text], candidate[:text])) +
+          (@weights[:role]      * bool_score(target[:role] == candidate[:role])) +
+          (@weights[:neighbors] * jaccard(target[:neighbors], candidate[:neighbors])) +
+          (@weights[:position] * position_score(target[:position], candidate[:position]))
+      end
+
+      private
+
+      def text_score(target, candidate)
+        return 0.0 if target.nil? || candidate.nil? || target.empty? || candidate.empty?
+
+        target.downcase.strip == candidate.downcase.strip ? 1.0 : 0.0
+      end
+
+      def bool_score(flag) = flag ? 1.0 : 0.0
+
+      def jaccard(target, candidate)
+        target = Array(target)
+        candidate = Array(candidate)
+        return 1.0 if target.empty? && candidate.empty?
+        return 0.0 if target.empty? || candidate.empty?
+
+        inter = (target & candidate).size
+        union = (target | candidate).size
+        union.zero? ? 0.0 : inter.to_f / union
+      end
+
+      def position_score(target, candidate)
+        return 0.0 unless target && candidate
+
+        idx_d = (target[:index].to_i - candidate[:index].to_i).abs
+        depth_d = (target[:depth].to_i - candidate[:depth].to_i).abs
+        # Soft falloff: 1.0 when identical, ~0 once they're 4+ apart in either axis.
+        [1.0 - ((idx_d + depth_d) / 8.0), 0.0].max
+      end
+    end
+  end
+end

data/lib/browserctl/replay/snapshot_diff.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Browserctl
+  module Replay
+    # Stable digest + element-set comparison for post-step snapshots.
+    #
+    # The digest is intentionally cheap and stable across cosmetic DOM noise:
+    # only the (selector, role, tag) triples drive the hash, sorted to remove
+    # ordering effects. That's enough to flag structural drift (a step that
+    # used to land on /dashboard now lands on /login) without flapping on
+    # every reflow or class rename.
+    module SnapshotDiff
+      module_function
+
+      def digest(snapshot)
+        return nil if snapshot.nil?
+
+        keys = Array(snapshot).map { |el| identity_tuple(el) }.compact.sort
+        Digest::SHA1.hexdigest(keys.join("\n"))[0, 16]
+      end
+
+      # Returns { added: [...], removed: [...] } of element selectors that
+      # differ between two snapshots. Empty arrays mean structurally identical.
+      def compare(prev, current)
+        prev_set    = element_set(prev)
+        current_set = element_set(current)
+        {
+          added: (current_set - prev_set).sort,
+          removed: (prev_set - current_set).sort
+        }
+      end
+
+      def identity_tuple(entry)
+        return nil unless entry.is_a?(Hash)
+
+        sel = entry[:selector] || entry["selector"]
+        role = entry[:role] || entry["role"]
+        tag = entry[:tag] || entry["tag"]
+        return nil unless sel
+
+        "#{sel}|#{role}|#{tag}"
+      end
+
+      def element_set(snapshot)
+        Array(snapshot).map { |entry| entry[:selector] || entry["selector"] }.compact
+      end
+    end
+  end
+end

data/lib/browserctl/replay/telemetry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../constants"
+
+module Browserctl
+  module Replay
+    # Append-only JSONL log of replay drift events for offline analysis.
+    # Local-only; nothing is uploaded. One line per event.
+    module Telemetry
+      LOG_BASENAME = "replay_drift.jsonl"
+
+      module_function
+
+      def log_path
+        File.join(Browserctl::BROWSERCTL_DIR, LOG_BASENAME)
+      end
+
+      # Write each drift event from a Replay::Context as its own JSONL line.
+      # @param ctx [Browserctl::Replay::Context, nil]
+      # @param workflow [String] workflow name for cross-reference
+      # @param path [String] override the destination (testing)
+      # @return [Integer] number of events written
+      def emit(ctx, workflow:, path: log_path)
+        events = ctx&.drift_events
+        return 0 if events.nil? || events.empty?
+
+        ensure_log_file(path)
+        ts = Time.now.utc.iso8601
+        File.open(path, "a") do |f|
+          events.each do |e|
+            f.puts JSON.generate(
+              event: "replay_drift",
+              ts: ts,
+              workflow: workflow,
+              command: e.command.to_s,
+              selector: e.selector,
+              matched_ref: e.matched_ref,
+              score: e.score,
+              reason: e.reason
+            )
+          end
+        end
+        events.size
+      rescue SystemCallError, IOError
+        # Telemetry must never break a run.
+        0
+      end
+
+      def ensure_log_file(path)
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        return if File.exist?(path)
+
+        FileUtils.touch(path)
+        File.chmod(0o600, path)
+      end
+    end
+  end
+end

data/lib/browserctl/rubocop/cops/typed_error.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module Browserctl
+      # Enforces that any explicit `code:` keyword passed to a `raise` of a
+      # `Browserctl::*` error refers to a constant from
+      # `Browserctl::Error::Codes` rather than a free-form string literal.
+      #
+      # Subclasses with their own `default_code` are trusted (the cop does not
+      # try to statically resolve `default_code` across files); the contract
+      # is enforced by the unit test suite. This cop's job is to catch the
+      # specific failure mode of inlining a stale snake_case code at the
+      # raise site and bypassing the canonical enum.
+      #
+      # @example
+      #   # bad — string literal that isn't a Codes constant
+      #   raise Browserctl::Error, "state expired", code: "state_expired"
+      #
+      #   # good — Codes constant reference
+      #   raise Browserctl::Error, "state expired",
+      #         code: Browserctl::Error::Codes::STATE_EXPIRED
+      #
+      #   # good — typed subclass relies on its own default_code
+      #   raise Browserctl::SelectorNotFound, "no such selector"
+      #
+      # The pattern is intentionally narrow. The full default_code-vs-Codes
+      # reconciliation lives in `lib/browserctl/errors.rb` and is covered by
+      # `spec/unit/errors_spec.rb`.
+      class TypedError < RuboCop::Cop::Base
+        MSG = "Browserctl raise: `code:` must reference Browserctl::Error::Codes::* — " \
+              "got string literal %<value>p. See lib/browserctl/error/codes.rb."
+
+        VALID_CODES = %w[
+          AUTH_REQUIRED
+          SELECTOR_NOT_FOUND
+          STATE_EXPIRED
+          SECRET_RESOLUTION_FAILED
+          DAEMON_UNREACHABLE
+          PROTOCOL_MISMATCH
+        ].freeze
+
+        # Matches `raise Browserctl::Foo, ..., code: <value>` and yields the
+        # `code:` value node.
+        def_node_matcher :browserctl_raise_with_code, <<~PATTERN
+          (send nil? :raise
+            (const (const nil? :Browserctl) _)
+            ...
+            (hash <(pair (sym :code) $_) ...>))
+        PATTERN
+
+        def on_send(node)
+          return unless node.method?(:raise)
+
+          browserctl_raise_with_code(node) do |code_value|
+            next unless code_value.str_type?
+
+            value = code_value.value
+            next if VALID_CODES.include?(value)
+
+            add_offense(code_value, message: format(MSG, value: value))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/runner.rb

@@ -2,7 +2,9 @@
 
 require "json"
 require_relative "workflow"
+require_relative "workflow/promotion_ledger"
 require_relative "client"
+require_relative "replay/telemetry"
 
 module Browserctl
   class Runner
@@ -14,13 +16,27 @@ module Browserctl
     # Runs a named workflow with the given parameters.
     # @param name [String] workflow name (must match /\A[a-zA-Z0-9_-]+\z/)
     # @param params [Hash] keyword arguments passed to the workflow
-    # @return [Boolean] true if all steps succeeded
+    # @param check [Boolean] when true, attaches a Replay::Context, renders
+    #   a drift report after the run, and signals drift via exit code 2.
+    # @return [Symbol] :clean (all ok, no drift), :drift (all ok, drift seen), :fail (any step failed)
     # @raise [WorkflowError] if the name is invalid or a step fails
-    def run_workflow(name, **params)
+    def run_workflow(name, check: false, **params)
       defn    = fetch_workflow(name)
-      results = defn.call(params, Client.new)
+      ctx     = check ? Browserctl::Replay::Context.new : nil
+      begin
+        results = defn.call(params, Client.new, replay_context: ctx)
+      rescue StandardError
+        Browserctl::Workflow::PromotionLedger.record(workflow: name.to_s, verdict: :fail) if check
+        raise
+      end
       print_results(results)
-      results.all?(&:ok)
+      v = verdict(results, ctx)
+      if check
+        print_drift_report(ctx)
+        Browserctl::Replay::Telemetry.emit(ctx, workflow: name.to_s)
+        Browserctl::Workflow::PromotionLedger.record(workflow: name.to_s, verdict: v)
+      end
+      v
     end
 
     # Lists all registered workflows from the standard search paths.
@@ -41,7 +57,7 @@ module Browserctl
     SAFE_WORKFLOW_NAME = /\A[a-zA-Z0-9_-]+\z/
 
     def self.load_params_file(path)
-      raise "params file not found: #{path}" unless File.exist?(path)
+      raise Browserctl::WorkflowError, "params file not found: #{path}" unless File.exist?(path)
 
       case File.extname(path).downcase
       when ".yml", ".yaml"
@@ -50,12 +66,12 @@ module Browserctl
       when ".json"
         JSON.parse(File.read(path), symbolize_names: true)
       else
-        raise "unsupported params file format: #{path} (use .yml, .yaml, or .json)"
+        raise Browserctl::WorkflowError, "unsupported params file format: #{path} (use .yml, .yaml, or .json)"
       end
     rescue Psych::SyntaxError => e
-      raise "invalid YAML in #{path}: #{e.message}"
+      raise Browserctl::WorkflowError, "invalid YAML in #{path}: #{e.message}"
     rescue JSON::ParserError => e
-      raise "invalid JSON in #{path}: #{e.message}"
+      raise Browserctl::WorkflowError, "invalid JSON in #{path}: #{e.message}"
     end
 
     private
@@ -79,7 +95,10 @@ module Browserctl
       return if Browserctl.lookup_workflow(name.to_s)
 
       path = workflow_path(name)
-      load path if path
+      return unless path
+
+      Browserctl.verify_workflow_format_version!(path)
+      load path
     end
 
     def workflow_path(name)
@@ -95,7 +114,10 @@ module Browserctl
 
     def load_from_dir(dir)
       Dir.glob("#{dir}/*.rb").each do |f|
-        load f unless $LOADED_FEATURES.include?(f)
+        next if $LOADED_FEATURES.include?(f)
+
+        Browserctl.verify_workflow_format_version!(f)
+        load f
       end
     end
 
@@ -109,6 +131,24 @@ module Browserctl
       $stdout.puts "  #{label} #{msg}"
     end
 
+    def print_drift_report(ctx)
+      events = ctx&.drift_events || []
+      report = {
+        drift: events.any?,
+        rematches: events.count { |e| e.reason == "rematch" },
+        unresolved: events.count { |e| e.reason == "no candidate above threshold" },
+        events: events.map(&:to_h)
+      }
+      $stdout.puts JSON.pretty_generate(report)
+    end
+
+    def verdict(results, ctx)
+      return :fail unless results.all?(&:ok)
+      return :drift if ctx&.drift_events&.any?
+
+      :clean
+    end
+
     def format_params(defn)
       defn.param_defs.transform_values do |p|
         entry = { required: p.required, secret: p.secret, default: p.default }

data/lib/browserctl/secret_resolver_registry.rb

@@ -4,8 +4,9 @@ require_relative "errors"
 
 module Browserctl
   class SecretResolverRegistry
-    @mutex    = Mutex.new
-    @registry = {}
+    @mutex          = Mutex.new
+    @registry       = {}
+    @resolved_values = []
 
     def self.register(resolver_class)
       instance = resolver_class.new
@@ -25,7 +26,9 @@ module Browserctl
         raise SecretResolverError, msg
       end
 
-      resolver.resolve(reference)
+      value = resolver.resolve(reference)
+      record_resolved_value(value)
+      value
     rescue SecretResolverError
       raise
     rescue StandardError => e
@@ -36,8 +39,24 @@ module Browserctl
       @mutex.synchronize { @registry.key?(scheme) }
     end
 
+    # In-memory record of values resolved during this process. Used by the
+    # Redactor so trace output never leaks values that flowed through the
+    # registry. Never persisted.
+    def self.resolved_values
+      @mutex.synchronize { @resolved_values.dup }
+    end
+
+    def self.record_resolved_value(value)
+      return unless value.is_a?(String) && !value.empty?
+
+      @mutex.synchronize { @resolved_values << value unless @resolved_values.include?(value) }
+    end
+
     def self.reset!
-      @mutex.synchronize { @registry.clear }
+      @mutex.synchronize do
+        @registry.clear
+        @resolved_values.clear
+      end
     end
   end
 end

data/lib/browserctl/server/command_dispatcher.rb

@@ -2,6 +2,7 @@
 
 require_relative "snapshot_builder"
 require_relative "page_session"
+require_relative "handlers/error_payload"
 require_relative "handlers/page_lifecycle"
 require_relative "handlers/navigation"
 require_relative "handlers/observation"
@@ -11,12 +12,16 @@ require_relative "handlers/devtools"
 require_relative "handlers/daemon_control"
 require_relative "handlers/storage"
 require_relative "handlers/session"
+require_relative "handlers/state"
 require_relative "handlers/interaction"
 require_relative "../detectors"
 require_relative "../policy"
+require_relative "../errors"
+require_relative "../replay/snapshot_diff"
 
 module Browserctl
   class CommandDispatcher
+    include Handlers::ErrorPayload
     include Handlers::PageLifecycle
     include Handlers::Navigation
     include Handlers::Observation
@@ -26,6 +31,7 @@ module Browserctl
     include Handlers::DaemonControl
     include Handlers::Storage
     include Handlers::Session
+    include Handlers::State
     include Handlers::Interaction
 
     COMMAND_MAP = {
@@ -36,6 +42,7 @@ module Browserctl
       "navigate" => :cmd_navigate,
       "wait" => :cmd_wait,
       "snapshot" => :cmd_snapshot,
+      "auth_check" => :cmd_auth_check,
       "evaluate" => :cmd_evaluate,
       "fill" => :cmd_fill,
       "click" => :cmd_click,
@@ -66,7 +73,12 @@ module Browserctl
       "session_save" => :cmd_session_save,
       "session_load" => :cmd_session_load,
       "session_list" => :cmd_session_list,
-      "session_delete" => :cmd_session_delete
+      "session_delete" => :cmd_session_delete,
+      "state_save" => :cmd_state_save,
+      "state_load" => :cmd_state_load,
+      "state_list" => :cmd_state_list,
+      "state_info" => :cmd_state_info,
+      "state_delete" => :cmd_state_delete
     }.freeze
 
     SCREENSHOT_DIR   = File.expand_path("~/.browserctl/screenshots").freeze

data/lib/browserctl/server/handlers/daemon_control.rb

@@ -21,7 +21,11 @@ module Browserctl
         def cmd_fetch(req)
           key = req[:key].to_s
           found = @kv_mutex.synchronize { @kv_store.key?(key) ? { ok: true, value: @kv_store[key] } : nil }
-          found || { error: "key '#{key}' not found", code: "key_not_found" }
+          found || error_payload(
+            code: Browserctl::Error::Codes::KEY_NOT_FOUND,
+            message: "key '#{key}' not found",
+            context: { key: key }
+          )
         end
       end
     end

data/lib/browserctl/server/handlers/error_payload.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      # Centralised structured-error builder for daemon JSON-RPC responses.
+      # Each handler returns `{ error:, code:, context:, suggested_action: }`
+      # for any failure carrying a stable {Browserctl::Error::Codes} code.
+      module ErrorPayload
+        # @param code [String] a SCREAMING_SNAKE code from {Codes}
+        # @param message [String] human-readable error
+        # @param context [Hash] free-form structured fields (selector, path, ...)
+        # @return [Hash{Symbol => Object}]
+        def error_payload(code:, message:, context: {})
+          {
+            error: message,
+            code: code,
+            context: context,
+            suggested_action: Browserctl::Error::SuggestedActions.for(code)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server/handlers/interaction.rb

@@ -27,7 +27,13 @@ module Browserctl
               "return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; " \
               "})(#{sel.to_json})"
             )
-            return { error: "selector not found: #{sel}" } unless coords
+            unless coords
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             session.page.mouse.move(x: coords["x"], y: coords["y"])
             { ok: true }
@@ -43,7 +49,13 @@ module Browserctl
             return sel if sel.is_a?(Hash)
 
             el = session.page.at_css(sel)
-            return { error: "selector not found: #{sel}" } unless el
+            unless el
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             el.select_file(path)
             { ok: true }
@@ -56,7 +68,13 @@ module Browserctl
             return sel if sel.is_a?(Hash)
 
             el = session.page.at_css(sel)
-            return { error: "selector not found: #{sel}" } unless el
+            unless el
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             el.evaluate(
               "this.value = #{req[:value].to_json}; " \