browserctl 0.11.0 → 0.13.0

data/lib/browserctl/recording.rb

@@ -1,65 +1,46 @@
 # frozen_string_literal: true
 
-require "json"
-require "date"
-require "time"
-require "fileutils"
 require "tmpdir"
-require "uri"
+require_relative "errors"
+require_relative "error/codes"
 
 module Browserctl
-  class Recording # rubocop:disable Metrics/ClassLength
+  # Captures a sequence of daemon commands as a JSONL log and renders it
+  # back out as a Ruby workflow file. This class is the public facade;
+  # the focused responsibilities live under `Browserctl::Recording::*`:
+  #
+  # - `Recording::State`            — singleton over the on-disk marker.
+  # - `Recording::Redactor`         — secret-aware redaction.
+  # - `Recording::LogWriter`        — log file I/O and JSONL formatting.
+  # - `Recording::WorkflowRenderer` — log-to-Ruby workflow translation.
+  class Recording
     RECORDINGS_DIR = File.join(Dir.tmpdir, "browserctl-recordings")
     STATE_FILE     = File.expand_path("~/.browserctl/active_recording")
 
-    RECORDABLE = %w[page_open navigate fill click screenshot evaluate].freeze
-
-    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
+    # Recording-log format version, written into the `_meta` header and
+    # validated when generate_workflow loads a recording. See
+    # docs/reference/format-versions.md.
+    RECORDING_FORMAT_VERSION = 1
+    SUPPORTED_FORMAT_VERSIONS = [RECORDING_FORMAT_VERSION].freeze
 
     # Bumped when the recording log shape changes in a way that older
     # tooling (workflow generate, replay) cannot read.
     LOG_FORMAT = "v0.11"
 
+    RECORDABLE = %w[page_open navigate fill click screenshot evaluate].freeze
+
     def self.start(name)
-      FileUtils.mkdir_p(RECORDINGS_DIR, mode: 0o700)
-      FileUtils.mkdir_p(File.dirname(STATE_FILE))
-      File.write(STATE_FILE, name)
-      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
+      LogWriter.init_log(name)
+      State.write(name)
       name
     end
 
     def self.stop
-      name = active
-      raise "no active recording — run: browserctl record start <name>" unless name
-
-      File.unlink(STATE_FILE)
-      name
+      State.clear!
     end
 
     def self.active
-      File.exist?(STATE_FILE) ? File.read(STATE_FILE).strip : nil
+      State.active
     end
 
     def self.append(cmd, response: nil, **attrs)
@@ -76,23 +57,22 @@ module Browserctl
       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(entry)
-      end
+      LogWriter.append_entry(name, entry)
     end
 
     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)
+      log = LogWriter.log_path(name)
+      raise Browserctl::Error, "no recording found for '#{name}'" unless File.exist?(log)
 
-      raw   = File.readlines(log).map { |l| JSON.parse(l, symbolize_names: true) }
+      raw   = LogWriter.read_entries(name)
+      LogWriter.verify_format_version!(raw, path: log)
       lines = raw.reject { |l| l[:cmd] == "_meta" }
-      ruby  = build_workflow_ruby(name, lines)
+      ruby  = WorkflowRenderer.render(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
+      LogWriter.delete_log(name) unless keep_log
     end
 
     def self.warn_about_ref_interactions(lines)
@@ -106,25 +86,19 @@ module Browserctl
     class << self
       private
 
-      def log_path(name)
-        File.join(RECORDINGS_DIR, "#{name}.jsonl")
+      def now
+        Time.now.utc.to_f
       end
 
       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
+        LogWriter.append_entry(recording_name, entry)
       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]
@@ -135,227 +109,24 @@ module Browserctl
         meta.transform_keys(&:to_s)
       end
 
-      def build_workflow_ruby(name, commands)
-        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)
-
-        if body.nil?
-          page_sym = cmd[:name].to_s.gsub(/[^a-zA-Z0-9_]/, "_")
-          action   = cmd[:action].to_s.gsub(/[^a-z_]/, "")
-          return "# TODO: ref-based #{action} on #{cmd[:name].inspect} (ref: #{cmd[:ref].inspect}) — " \
-                 "replace with a stable CSS selector\n" \
-                 "# step #{label.inspect} do\n" \
-                 "#   page(:#{page_sym}).#{action}(\"YOUR_SELECTOR_HERE\")\n" \
-                 "# end"
-        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)
-        return ref_interaction_parts(cmd) if cmd[:cmd] == "_ref_interaction"
-        return selector_parts(cmd) if %w[fill click].include?(cmd[:cmd])
-
-        page = cmd[:name]
-        case cmd[:cmd]
-        when "page_open"  then ["open #{page}", "page(:#{page}).navigate(#{cmd[:url].inspect})"]
-        when "navigate"   then ["navigate #{page}", "page(:#{page}).navigate(#{cmd[:url].inspect})"]
-        when "screenshot" then ["screenshot #{page}", "page(:#{page}).screenshot"]
-        when "evaluate"   then ["eval on #{page}", "page(:#{page}).evaluate(#{cmd[:expression].inspect})"]
-        else ["#{cmd[:cmd]} on #{page}", "# unrecognised command: #{cmd.inspect}"]
-        end
-      end
-
-      def ref_interaction_parts(cmd)
-        ["TODO: ref-based #{cmd[:action]} on #{cmd[:name]} (ref: #{cmd[:ref]})", nil]
-      end
-
-      def selector_parts(cmd)
-        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}, #{value_arg})"]
-        when "click"
-          ["click #{cmd[:selector]} on #{page}",
-           "page(:#{page}).click(#{cmd[:selector].inspect})"]
-        end
-      end
-
       def prepare_attrs(cmd, attrs)
         attrs = attrs.except(:capture_post_snapshot)
         if cmd == "fill"
           attrs = attrs.except(:value)
-          field = infer_secret_field(attrs[:selector])
+          field = Redactor.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[:url] = Redactor.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?
-
-        uri.query = uri.query.gsub(/([^&=]+)=([^&]*)/) do |full_match|
-          raw_key = ::Regexp.last_match(1)
-          key = URI.decode_www_form_component(raw_key)
-          key =~ SENSITIVE_PARAM_PATTERN ? "#{raw_key}=[REDACTED]" : full_match
-        end
-        uri.to_s
-      rescue URI::InvalidURIError
-        url
-      end
     end
   end
 end
+
+require_relative "recording/state"
+require_relative "recording/redactor"
+require_relative "recording/log_writer"
+require_relative "recording/workflow_renderer"

data/lib/browserctl/redactor.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Browserctl
+  # Redacts known secret values from arbitrary strings.
+  #
+  # Used by `browserctl trace` to ensure traces are safe to attach to issues
+  # by default. Secret values are sourced from two places:
+  #   1. ENV variables whose names match well-known secret patterns
+  #      (`*_TOKEN`, `*_KEY`, `*_SECRET`, `*_PASSWORD`).
+  #   2. Values captured at runtime by `SecretResolverRegistry` (in-memory
+  #      only — never persisted).
+  #
+  # Replacement marker is the literal `[REDACTED]`. We considered including
+  # a sha256 prefix to distinguish values, but that doubles the surface area
+  # for accidental leakage (a determined attacker could brute-force short
+  # secrets from the prefix), and the timeline is more scannable with a
+  # uniform marker.
+  class Redactor
+    MARKER = "[REDACTED]"
+    MIN_LENGTH = 4
+    ENV_PATTERNS = [/_TOKEN\z/, /_KEY\z/, /_SECRET\z/, /_PASSWORD\z/].freeze
+
+    # @param secrets [Array<String>] secret values to redact.
+    def initialize(secrets: [])
+      # Filter empty / too-short values; longest-first to avoid partial
+      # overlaps (e.g. redacting "abcd" before "abcdef" would leave "ef").
+      @secrets = secrets
+                 .compact
+                 .map(&:to_s)
+                 .reject { |s| s.length < MIN_LENGTH }
+                 .uniq
+                 .sort_by { |s| -s.length }
+    end
+
+    # @param string [String, nil]
+    # @return [String, nil]
+    def redact(string)
+      return string if string.nil?
+
+      result = string.to_s
+      @secrets.each { |secret| result = result.gsub(secret, MARKER) }
+      result
+    end
+
+    def empty?
+      @secrets.empty?
+    end
+
+    # Build a Redactor from the current ENV using well-known patterns.
+    # Optionally merges in additional values (e.g. from runtime instrumentation).
+    def self.from_env(env: ENV, extra: [])
+      values = env.each_with_object([]) do |(name, value), acc|
+        acc << value if ENV_PATTERNS.any? { |re| name =~ re }
+      end
+      new(secrets: values + Array(extra))
+    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

@@ -57,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"
@@ -66,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
@@ -95,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)
@@ -111,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
 

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