browserctl 0.9.0 → 0.11.0

data/lib/browserctl/flows/stdlib/oauth_github.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../../flow"
+
+# Clicks the "Authorize <app>" button on a GitHub OAuth consent screen.
+#
+# Assumes the user is already signed in to GitHub and the page is parked
+# on the consent URL — this flow does not handle the credential entry
+# step. Use a separate workflow or flow to land on the consent page first.
+Browserctl.flow("oauth_github") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Click the Authorize button on a GitHub OAuth consent screen."
+
+  # The default selector targets the green Authorize submit button on
+  # github.com/login/oauth/authorize. GitHub keeps name="authorize" stable
+  # across UI revisions; override only if you're testing against a forked
+  # GitHub Enterprise instance with a customised template.
+  param :authorize_selector, default: 'button[name="authorize"][value="1"]'
+
+  precondition("on a github oauth consent page") do
+    page.url.include?("/login/oauth/authorize")
+  end
+
+  step("click authorize") do
+    page.click(authorize_selector)
+  end
+end

data/lib/browserctl/flows/stdlib/oauth_google.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../../flow"
+
+# Clicks the Continue / Allow button on a Google OAuth consent screen.
+#
+# Assumes the user is already signed in to Google and the page is parked
+# on accounts.google.com showing the consent prompt. This flow does not
+# pick an account from the chooser, enter a password, or solve 2FA —
+# compose those before calling this flow.
+#
+# Google rotates consent UI more often than GitHub, so the default
+# selector is a best-effort match against the modern Material 3 button.
+# Override if your account or app version sees a different layout.
+Browserctl.flow("oauth_google") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Click the Continue/Allow button on a Google OAuth consent screen."
+
+  param :continue_selector, default: 'button[jsname="LgbsSe"]'
+
+  precondition("on a google oauth consent page") do
+    url = page.url
+    url.include?("accounts.google.com") && (url.include?("/oauth") || url.include?("/signin/oauth"))
+  end
+
+  step("click continue") do
+    page.click(continue_selector)
+  end
+end

data/lib/browserctl/flows/stdlib/totp_2fa.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "../../flow"
+
+module Browserctl
+  module Flows
+    # RFC 6238 TOTP code generation from a base32 secret.
+    # Pure Ruby; no network and no external gem.
+    module TOTP
+      module_function
+
+      def generate(secret, at: Time.now, digits: 6, period: 30, digest: "SHA1")
+        counter   = (at.to_i / period).to_i
+        key       = decode_base32(secret)
+        counter_b = [counter].pack("Q>") # 64-bit big-endian
+        hmac      = OpenSSL::HMAC.digest(digest, key, counter_b)
+        offset    = hmac[-1].ord & 0x0f
+        truncated = hmac[offset, 4].unpack1("N") & 0x7fffffff
+        truncated.to_s.rjust(digits, "0")[-digits..]
+      end
+
+      BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+
+      def decode_base32(secret)
+        cleaned = secret.to_s.upcase.gsub(/[^A-Z2-7]/, "")
+        bits = cleaned.each_char.map { |c| char_to_bits(c) }.join
+        whole_bytes = bits[0, (bits.length / 8) * 8]
+        whole_bytes.scan(/.{8}/).map { |b| b.to_i(2).chr }.join
+      end
+
+      def char_to_bits(char)
+        idx = BASE32_ALPHABET.index(char) or
+          raise ArgumentError, "invalid base32 char #{char.inspect}"
+        idx.to_s(2).rjust(5, "0")
+      end
+    end
+  end
+end
+
+Browserctl.flow("totp_2fa") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Generate an RFC 6238 TOTP code from a base32 secret and type it into the page."
+
+  param :secret,   required: true, secret: true
+  param :selector, required: true
+  param :digits,   default: 6
+  param :period,   default: 30
+
+  precondition("page proxy is present") { !page.nil? }
+
+  step("compute and fill code") do
+    code = Browserctl::Flows::TOTP.generate(
+      secret,
+      digits: digits.to_i,
+      period: period.to_i
+    )
+    page.fill(selector, code)
+  end
+end

data/lib/browserctl/recording.rb

@@ -2,12 +2,13 @@
 
 require "json"
 require "date"
+require "time"
 require "fileutils"
 require "tmpdir"
 require "uri"
 
 module Browserctl
-  class Recording
+  class Recording # rubocop:disable Metrics/ClassLength
     RECORDINGS_DIR = File.join(Dir.tmpdir, "browserctl-recordings")
     STATE_FILE     = File.expand_path("~/.browserctl/active_recording")
 
@@ -15,6 +16,22 @@ module Browserctl
 
     SENSITIVE_PARAM_PATTERN = /\A(token|key|secret|auth|code|access_token|api_key|client_secret|state)\z/ix
 
+    # Selector tokens that signal a fill is targeting a secret-shaped field.
+    # The captured group (or matched substring) is used as the inferred field
+    # name; that name later drives the generated `secret_ref:` placeholder.
+    SECRET_FIELD_PATTERN = /\b(password|passwd|api[_-]?key|token|secret|otp|pin|client[_-]?secret|access[_-]?token)\b/i
+
+    # Conservative thresholds for inferring an explicit wait between recorded
+    # steps. Gaps shorter than the threshold come from natural input cadence;
+    # gaps above it usually mean the page actually had work to do.
+    WAIT_THRESHOLD_SECONDS = 1.5
+    WAIT_PADDING_SECONDS   = 5
+    WAIT_FLOOR_SECONDS     = 5
+
+    # Bumped when the recording log shape changes in a way that older
+    # tooling (workflow generate, replay) cannot read.
+    LOG_FORMAT = "v0.11"
+
     def self.start(name)
       FileUtils.mkdir_p(RECORDINGS_DIR, mode: 0o700)
       FileUtils.mkdir_p(File.dirname(STATE_FILE))
@@ -22,6 +39,14 @@ module Browserctl
       FileUtils.rm_f(log_path(name))
       FileUtils.touch(log_path(name))
       File.chmod(0o600, log_path(name))
+      File.open(log_path(name), "a") do |f|
+        f.puts JSON.generate(
+          cmd: "_meta",
+          log_format: LOG_FORMAT,
+          recording: name,
+          started_at: Time.now.utc.iso8601
+        )
+      end
       name
     end
 
@@ -37,40 +62,45 @@ module Browserctl
       File.exist?(STATE_FILE) ? File.read(STATE_FILE).strip : nil
     end
 
-    def self.append(cmd, **attrs)
+    def self.append(cmd, response: nil, **attrs)
       name = active
       return unless name
       return unless RECORDABLE.include?(cmd.to_s)
 
       if %w[click fill].include?(cmd.to_s) && attrs[:selector].nil?
-        record_ref_interaction(name, cmd.to_s, attrs)
+        record_ref_interaction(name, cmd.to_s, attrs, response)
         return
       end
 
       attrs = prepare_attrs(cmd.to_s, attrs)
+      entry = { cmd: cmd.to_s, ts: now }.merge(attrs.transform_keys(&:to_s))
+      entry.merge!(replay_metadata(response)) if response
 
       File.open(log_path(name), "a") do |f|
-        f.puts JSON.generate({ cmd: cmd.to_s }.merge(attrs.transform_keys(&:to_s)))
+        f.puts JSON.generate(entry)
       end
     end
 
-    def self.generate_workflow(name, output_path: nil)
+    def self.generate_workflow(name, output_path: nil, keep_log: false)
       log = log_path(name)
       raise "no recording found for '#{name}'" unless File.exist?(log)
 
-      lines = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
+      raw   = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
+      lines = raw.reject { |l| l[:cmd] == "_meta" }
       ruby  = build_workflow_ruby(name, lines)
       File.write(output_path, ruby) if output_path
+      warn_about_ref_interactions(lines)
+      ruby
+    ensure
+      FileUtils.rm_f(log) if log && !keep_log
+    end
 
+    def self.warn_about_ref_interactions(lines)
       ref_count = lines.count { |l| l[:cmd] == "_ref_interaction" }
-      if ref_count.positive?
-        warn "Warning: #{ref_count} ref-based interaction(s) were captured but cannot be replayed by ref."
-        warn "Search the generated workflow for 'TODO: ref-based' and replace with stable CSS selectors."
-      end
+      return unless ref_count.positive?
 
-      ruby
-    ensure
-      FileUtils.rm_f(log) if log
+      warn "Warning: #{ref_count} ref-based interaction(s) were captured but cannot be replayed by ref."
+      warn "Search the generated workflow for 'TODO: ref-based' and replace with stable CSS selectors."
     end
 
     class << self
@@ -80,26 +110,163 @@ module Browserctl
         File.join(RECORDINGS_DIR, "#{name}.jsonl")
       end
 
-      def record_ref_interaction(recording_name, cmd, attrs)
-        entry = { cmd: "_ref_interaction", action: cmd, ref: attrs[:ref], name: attrs[:name] }
+      def record_ref_interaction(recording_name, cmd, attrs, response)
+        entry = { cmd: "_ref_interaction", ts: now, action: cmd, ref: attrs[:ref], name: attrs[:name] }
+        entry.merge!(replay_metadata(response)) if response
         File.open(log_path(recording_name), "a") do |f|
           f.puts JSON.generate(entry)
         end
       end
 
+      # Pulls the replay-relevant fields out of a daemon response. Each
+      # is optional — older daemons or non-resolving commands may omit
+      # any of them.
+      def now
+        Time.now.utc.to_f
+      end
+
+      def replay_metadata(response)
+        meta = {}
+        meta[:ref]                  = response[:ref]                  if response[:ref]
+        meta[:fingerprint]          = response[:fingerprint]          if response[:fingerprint]
+        meta[:snapshot_id]          = response[:snapshot_id]          if response[:snapshot_id]
+        meta[:postcondition_hint]   = response[:postcondition_hint]   if response[:postcondition_hint]
+        meta[:post_snapshot_digest] = response[:post_snapshot_digest] if response[:post_snapshot_digest]
+        meta.transform_keys(&:to_s)
+      end
+
       def build_workflow_ruby(name, commands)
-        steps = commands.map { |c| build_step(c) }.join("\n\n")
+        steps   = annotated_steps(commands).join("\n\n")
+        secrets = commands.map { |c| c[:secret_field] }.compact.uniq
+        header  = secret_header(secrets)
         <<~RUBY
           # frozen_string_literal: true
-
+          #{header}
           Browserctl.workflow #{name.inspect} do
             desc "Recorded on #{Date.today}"
-
+          #{secrets.map { |f| "  param :secret_#{f}, secret: true" }.join("\n")}
           #{steps.gsub(/^/, '  ')}
           end
         RUBY
       end
 
+      # Walks the recorded events and emits the rendered step strings,
+      # interleaving inferred waits before selector-driven actions whose
+      # preceding gap exceeds WAIT_THRESHOLD_SECONDS, and inferred URL
+      # postconditions after click/fill steps that triggered navigation.
+      def annotated_steps(commands)
+        last_url = {}
+        commands.each_with_index.flat_map do |cmd, i|
+          rendered = []
+          if i.positive? && (wait = inferred_wait_step(commands[i - 1], cmd))
+            rendered << wait
+          end
+          rendered << build_step(cmd)
+          if (post = url_postcondition_step(cmd, last_url))
+            rendered << post
+          end
+          if (snap = snapshot_postcondition_step(cmd))
+            rendered << snap
+          end
+          update_last_url!(cmd, last_url)
+          rendered
+        end
+      end
+
+      # Emits a postcondition assertion when a click/fill resulted in a URL
+      # change. Compares the canonical (scheme+host+path) form so query
+      # strings and fragments don't make every replay flaky.
+      def url_postcondition_step(cmd, last_url)
+        return nil unless %w[click fill].include?(cmd[:cmd])
+        return nil unless cmd[:postcondition_hint] && cmd[:postcondition_hint][:url]
+
+        page = cmd[:name]
+        observed = cmd[:postcondition_hint][:url]
+        prior    = last_url[page]
+        return nil if canonical_url(observed) == canonical_url(prior)
+
+        prefix = canonical_url(observed)
+        return nil unless prefix
+
+        <<~RUBY.chomp
+          step "assert url after #{cmd[:cmd]} on #{page}" do
+            current = page(:#{page}).url
+            assert current.start_with?(#{prefix.inspect}), "expected URL to start with #{prefix}, got \#{current}"
+          end
+        RUBY
+      end
+
+      # Emits an assert_snapshot_stable step when the recording captured a
+      # post-step DOM digest. Under workflow run --check the helper records
+      # drift on mismatch instead of raising, so a wiggly page surfaces in
+      # the report rather than failing the run outright.
+      def snapshot_postcondition_step(cmd)
+        return nil unless %w[click fill].include?(cmd[:cmd])
+        return nil unless cmd[:post_snapshot_digest]
+
+        page = cmd[:name]
+        digest = cmd[:post_snapshot_digest]
+        <<~RUBY.chomp
+          step "assert post-snapshot stable on #{page}" do
+            assert_snapshot_stable(:#{page}, expected_digest: #{digest.inspect})
+          end
+        RUBY
+      end
+
+      def update_last_url!(cmd, last_url)
+        case cmd[:cmd]
+        when "navigate", "page_open"
+          last_url[cmd[:name]] = cmd[:url] if cmd[:url]
+        when "click", "fill"
+          observed = cmd[:postcondition_hint] && cmd[:postcondition_hint][:url]
+          last_url[cmd[:name]] = observed if observed
+        end
+      end
+
+      def canonical_url(url)
+        return nil if url.nil? || url.empty?
+
+        uri = URI.parse(url)
+        path = uri.path.to_s
+        path = "/" if path.empty?
+        "#{uri.scheme}://#{uri.host}#{path}"
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def inferred_wait_step(prev, current)
+        return nil unless %w[fill click].include?(current[:cmd])
+        return nil unless current[:selector]
+
+        delta = elapsed(prev, current)
+        return nil unless delta && delta >= WAIT_THRESHOLD_SECONDS
+
+        timeout = [WAIT_FLOOR_SECONDS, delta.ceil + WAIT_PADDING_SECONDS].max
+        page = current[:name]
+        sel  = current[:selector]
+        <<~RUBY.chomp
+          # inferred wait: prior step took ~#{format('%.1f', delta)}s
+          step "wait for #{sel} on #{page}" do
+            page(:#{page}).wait(#{sel.inspect}, timeout: #{timeout})
+          end
+        RUBY
+      end
+
+      def elapsed(prev, current)
+        return nil unless prev && current && prev[:ts] && current[:ts]
+
+        current[:ts] - prev[:ts]
+      end
+
+      def secret_header(secrets)
+        return "" if secrets.empty?
+
+        lines = ["# TODO: review the following secret-shaped fields detected during recording.",
+                 "# Configure a secret_ref: source for each before running:"]
+        secrets.each { |f| lines << "#   - secret_#{f}" }
+        "\n#{lines.join("\n")}\n"
+      end
+
       def build_step(cmd)
         label, body = step_parts(cmd)
 
@@ -113,12 +280,13 @@ module Browserctl
                  "# end"
         end
 
-        url = cmd[:url].to_s
-        if url.include?("[REDACTED]")
-          "# NOTE: sensitive query params were redacted during recording\nstep #{label.inspect} do\n  #{body}\nend"
-        else
-          "step #{label.inspect} do\n  #{body}\nend"
-        end
+        prefix = []
+        prefix << "# NOTE: sensitive query params were redacted during recording" \
+          if cmd[:url].to_s.include?("[REDACTED]")
+        prefix << "# fingerprint fallback: #{cmd[:fingerprint].to_json}" if cmd[:fingerprint]
+
+        head = prefix.empty? ? "" : "#{prefix.join("\n")}\n"
+        "#{head}step #{label.inspect} do\n  #{body}\nend"
       end
 
       def step_parts(cmd)
@@ -143,8 +311,9 @@ module Browserctl
         page = cmd[:name]
         case cmd[:cmd]
         when "fill"
+          value_arg = cmd[:secret_field] ? "params[:secret_#{cmd[:secret_field]}]" : "params[:fill_value]"
           ["fill #{cmd[:selector]} on #{page}",
-           "page(:#{page}).fill(#{cmd[:selector].inspect}, params[:fill_value])"]
+           "page(:#{page}).fill(#{cmd[:selector].inspect}, #{value_arg})"]
         when "click"
           ["click #{cmd[:selector]} on #{page}",
            "page(:#{page}).click(#{cmd[:selector].inspect})"]
@@ -152,11 +321,28 @@ module Browserctl
       end
 
       def prepare_attrs(cmd, attrs)
-        attrs = attrs.except(:value) if cmd == "fill"
+        attrs = attrs.except(:capture_post_snapshot)
+        if cmd == "fill"
+          attrs = attrs.except(:value)
+          field = infer_secret_field(attrs[:selector])
+          if field
+            attrs[:secret_hint]  = true
+            attrs[:secret_field] = field
+          end
+        end
         attrs[:url] = redact_url(attrs[:url]) if %w[navigate page_open].include?(cmd) && attrs[:url]
         attrs
       end
 
+      def infer_secret_field(selector)
+        return nil unless selector
+
+        match = selector.match(SECRET_FIELD_PATTERN)
+        return nil unless match
+
+        match[1].downcase.gsub(/[^a-z0-9]/, "_")
+      end
+
       def redact_url(url)
         uri = URI.parse(url)
         return url if uri.query.nil?

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