browserctl 0.11.0 → 0.13.0

data/lib/browserctl/migrations.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+require_relative "error/codes"
+
+module Browserctl
+  # Migration registry for browserctl persisted formats. Operators run
+  # `browserctl migrate <path>` to upgrade an artifact written by an older
+  # browserctl to the current build's format version.
+  #
+  # Distinct from `verify_format_version!` (in bundle/recording/workflow):
+  # those gates stay strict — a reader that encounters an unknown version
+  # raises {Browserctl::ProtocolMismatch}. This module is the only blessed
+  # path to mutate an old artifact in place.
+  #
+  # The registry ships **empty** in v0.12. The first real migration arrives
+  # only when a format actually changes post-1.0. See
+  # `docs/reference/format-versions.md` ("Migration registry").
+  module Migrations
+    # Single registered upgrader. `upgrade` is a Proc invoked with the
+    # absolute path of the file being migrated; it is responsible for
+    # rewriting that file in place, advancing it from `from_version` to
+    # `to_version`.
+    Migration = Struct.new(:format, :from_version, :to_version, :upgrade, keyword_init: true)
+
+    # Result of {.run}. `applied` is the ordered list of {Migration} steps
+    # that ran. When the artifact was already at target, `applied` is empty.
+    Result = Struct.new(:format, :from, :to, :applied, keyword_init: true)
+
+    FORMAT_EXTENSIONS = {
+      ".bctl" => :bundle,
+      ".jsonl" => :recording,
+      ".rb" => :workflow
+    }.freeze
+
+    @registry = []
+    @mutex = Mutex.new
+
+    class << self
+      # Registers an upgrader for one hop in `format`'s version chain. The
+      # block receives the file path as a keyword argument and must rewrite
+      # the file in place to the new version.
+      def register(format:, from_version:, to_version:, &upgrade)
+        raise ArgumentError, "upgrade block required" unless upgrade
+
+        @mutex.synchronize do
+          @registry << Migration.new(format: format, from_version: from_version,
+                                     to_version: to_version, upgrade: upgrade)
+        end
+      end
+
+      # All registered migrations, in registration order.
+      def all
+        @mutex.synchronize { @registry.dup }
+      end
+
+      # Test-only hook — clears the registry. Not part of the public API.
+      def reset!
+        @mutex.synchronize { @registry.clear }
+      end
+
+      # Breadth-first search through registered migrations to chain a path
+      # for `format` from `from` to `to`. Returns the ordered list of
+      # {Migration} hops, or `nil` if no path is reachable. When `from == to`
+      # returns an empty array (already at target — no work to do).
+      def find_path(format:, from:, to:)
+        return [] if from == to
+
+        all_for_format = all.select { |m| m.format == format }
+        queue = [[from, []]]
+        seen  = { from => true }
+
+        until queue.empty?
+          current, path = queue.shift
+          all_for_format.each do |m|
+            next unless m.from_version == current
+            next if seen[m.to_version]
+
+            new_path = path + [m]
+            return new_path if m.to_version == to
+
+            seen[m.to_version] = true
+            queue << [m.to_version, new_path]
+          end
+        end
+        nil
+      end
+
+      # Inspects an artifact path and returns a format symbol — `:bundle`,
+      # `:recording`, or `:workflow` — or `nil` when the format cannot be
+      # identified. Detection is extension-driven: keep new formats listed
+      # in {FORMAT_EXTENSIONS} so this stays a one-line lookup.
+      def detect_format(path)
+        FORMAT_EXTENSIONS[File.extname(path.to_s).downcase]
+      end
+
+      # Reads `path` and returns the integer format_version it declares, or
+      # `nil` when no version header is present. Format-specific because
+      # each format stores the header differently — the bundle in its
+      # binary manifest, the recording in a `_meta` JSONL line, the
+      # workflow in a Ruby comment.
+      def detect_version(path, format)
+        case format
+        when :bundle    then peek_bundle_version(path)
+        when :recording then peek_recording_version(path)
+        when :workflow  then peek_workflow_version(path)
+        end
+      end
+
+      # End-to-end migration. Detects format and current version, finds a
+      # chain of registered upgraders to `target_version` (or the latest
+      # `to_version` seen for this format if `target_version` is nil), and
+      # invokes each in order. Each upgrader rewrites the file in place.
+      #
+      # Returns a {Result}. When no migrations are needed (or the registry
+      # has no entries for this format), `applied` is empty.
+      #
+      # Raises {Browserctl::ProtocolMismatch} when format detection fails,
+      # the version cannot be read, or no chain reaches the target.
+      def run(path, target_version: nil)
+        format  = detect_format(path) or raise_protocol("could not detect format for #{path}")
+        current = detect_version(path, format) or raise_protocol("could not read format_version from #{path}")
+        target  = target_version || latest_known_target(format, current)
+
+        if current == target
+          # If we'd be a no-op but the artifact's declared version is one this
+          # build's reader does not support, surface that as PROTOCOL_MISMATCH —
+          # there is no migration registered to bring it into range.
+          unless format_version_supported?(format, current)
+            raise_protocol("#{format} at #{path} declares unsupported format_version=#{current}; " \
+                           "no migration registered")
+          end
+          return Result.new(format: format, from: current, to: current, applied: [])
+        end
+
+        chain = find_path(format: format, from: current, to: target)
+        raise_protocol("no migration path from #{format} v#{current} to v#{target}") if chain.nil?
+
+        chain.each { |m| m.upgrade.call(path: path, from_version: m.from_version, to_version: m.to_version) }
+        Result.new(format: format, from: current, to: target, applied: chain)
+      end
+
+      private
+
+      # Reflects whether each format's reader currently accepts a given
+      # version. Mirrors the SUPPORTED_FORMAT_VERSIONS constant on the
+      # corresponding class — kept here so adding a new format is one
+      # branch, not a new public API.
+      def format_version_supported?(format, version)
+        case format
+        when :bundle
+          require_relative "state/bundle"
+          Browserctl::State::Bundle::SUPPORTED_FORMAT_VERSIONS.include?(version)
+        when :recording
+          require_relative "recording"
+          Browserctl::Recording::SUPPORTED_FORMAT_VERSIONS.include?(version)
+        when :workflow
+          require_relative "workflow"
+          Browserctl::SUPPORTED_WORKFLOW_FORMAT_VERSIONS.include?(version)
+        else
+          false
+        end
+      end
+
+      def latest_known_target(format, current)
+        targets = all.select { |m| m.format == format }.map(&:to_version)
+        targets.empty? ? current : targets.max
+      end
+
+      def peek_bundle_version(path)
+        require_relative "state/bundle"
+        manifest = Browserctl::State::Bundle.peek_manifest(File.binread(path))
+        manifest[:format_version] || manifest["format_version"]
+      rescue Browserctl::ProtocolMismatch
+        # `peek_manifest` raises on unknown versions, but we want to *return*
+        # the version so a migration can target it. Re-parse the manifest
+        # bytes directly when the strict gate refuses.
+        peek_bundle_version_loosely(path)
+      end
+
+      def peek_bundle_version_loosely(path)
+        blob = File.binread(path)
+        # Manifest length is at byte offset 8 (5 magic + 3 header). Parse
+        # the JSON without invoking Bundle's strict version check.
+        manifest_len = blob.byteslice(8, 4).unpack1("N")
+        manifest_bytes = blob.byteslice(12, manifest_len)
+        manifest = JSON.parse(manifest_bytes)
+        manifest["format_version"]
+      rescue StandardError
+        nil
+      end
+
+      def peek_recording_version(path)
+        first_line = File.foreach(path).first
+        return nil unless first_line
+
+        meta = JSON.parse(first_line, symbolize_names: true)
+        return nil unless meta[:cmd] == "_meta"
+
+        meta[:format_version]
+      rescue JSON::ParserError
+        nil
+      end
+
+      def peek_workflow_version(path)
+        require_relative "workflow"
+        Browserctl.parse_workflow_format_version(File.read(path))
+      end
+
+      def raise_protocol(msg)
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
+      end
+    end
+  end
+end

data/lib/browserctl/recording/log_writer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "../errors"
+require_relative "../error/codes"
+
+module Browserctl
+  class Recording
+    # Owns recording-log file I/O: path resolution, header initialisation,
+    # JSONL append, raw read, deletion, and format-version validation.
+    #
+    # All paths are resolved against the parent `Recording::RECORDINGS_DIR`
+    # constant on each call so RSpec `stub_const` calls remain effective.
+    module LogWriter
+      module_function
+
+      # Returns the on-disk JSONL path for a named recording.
+      def log_path(name)
+        File.join(Browserctl::Recording::RECORDINGS_DIR, "#{name}.jsonl")
+      end
+
+      # Truncates (or creates) the log for `name`, locks it down to user
+      # permissions, and writes the `_meta` header line. Returns the path.
+      def init_log(name)
+        FileUtils.mkdir_p(Browserctl::Recording::RECORDINGS_DIR, mode: 0o700)
+        path = log_path(name)
+        FileUtils.rm_f(path)
+        FileUtils.touch(path)
+        File.chmod(0o600, path)
+        File.open(path, "a") do |f|
+          f.puts JSON.generate(
+            cmd: "_meta",
+            format_version: Browserctl::Recording::RECORDING_FORMAT_VERSION,
+            log_format: Browserctl::Recording::LOG_FORMAT,
+            recording: name,
+            started_at: Time.now.utc.iso8601
+          )
+        end
+        path
+      end
+
+      # Appends a single JSONL entry to the log for `name`.
+      def append_entry(name, entry)
+        File.open(log_path(name), "a") do |f|
+          f.puts JSON.generate(entry)
+        end
+      end
+
+      # Returns the parsed lines for `name`, with symbolised keys.
+      def read_entries(name)
+        File.readlines(log_path(name)).map { |l| JSON.parse(l, symbolize_names: true) }
+      end
+
+      # Removes the log file for `name` if present.
+      def delete_log(name)
+        FileUtils.rm_f(log_path(name))
+      end
+
+      # Raises Browserctl::ProtocolMismatch when the recording log's
+      # `_meta` header is missing or declares a `format_version` that this
+      # build does not support. Mirrors `Browserctl::State::Bundle`.
+      def verify_format_version!(raw_lines, path: nil)
+        meta = raw_lines.first
+        version = meta && meta[:cmd] == "_meta" ? meta[:format_version] : nil
+        supported = Browserctl::Recording::SUPPORTED_FORMAT_VERSIONS
+        return if version && supported.include?(version)
+
+        where = path ? " at #{path}" : ""
+        msg = if version.nil?
+                "recording log#{where} is missing format_version " \
+                  "(supported: #{supported.inspect})"
+              else
+                "recording log#{where} declares format_version=#{version.inspect}, " \
+                  "this build supports #{supported.inspect}"
+              end
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
+      end
+    end
+  end
+end

data/lib/browserctl/recording/redactor.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Browserctl
+  class Recording
+    # Secret-aware redaction helpers used while a recording is being
+    # captured. Two responsibilities:
+    #
+    # 1. Inferring whether a `fill` selector is targeting a secret-shaped
+    #    field, so the generated workflow can wire a `secret_ref:` param.
+    # 2. Stripping sensitive query-string values out of recorded URLs so
+    #    they never reach disk.
+    module Redactor
+      # Query-string parameter names whose values are scrubbed when a
+      # navigate/page_open URL is recorded.
+      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 is used as the inferred field name; that
+      # name later drives the generated `secret_ref:` placeholder.
+      SECRET_FIELD_PATTERN = Regexp.new(
+        '\b(password|passwd|api[_-]?key|token|secret|otp|pin|client[_-]?secret|access[_-]?token)\b',
+        Regexp::IGNORECASE
+      )
+
+      module_function
+
+      # Returns a normalised secret-field name (e.g. "api_key") inferred
+      # from the selector, or nil when the selector is missing or does not
+      # match the secret-field pattern.
+      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
+
+      # Returns `url` with any sensitive query parameter values replaced
+      # by `[REDACTED]`. URLs that fail to parse are returned unchanged.
+      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

data/lib/browserctl/recording/state.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../errors"
+require_relative "../error/codes"
+
+module Browserctl
+  class Recording
+    # Singleton over the on-disk marker (`STATE_FILE`) that tracks which
+    # recording, if any, is currently active. Carved out of `Recording` so
+    # the facade stays focused on dispatch.
+    module State
+      module_function
+
+      # Returns the active recording name, or nil when no marker exists.
+      # Reads the constant lazily so RSpec `stub_const` calls on the parent
+      # `Recording::STATE_FILE` continue to take effect.
+      def active
+        path = Browserctl::Recording::STATE_FILE
+        File.exist?(path) ? File.read(path).strip : nil
+      end
+
+      # Writes the marker for `name`. Caller is responsible for any
+      # additional setup (e.g. log initialisation).
+      def write(name)
+        path = Browserctl::Recording::STATE_FILE
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, name)
+        name
+      end
+
+      # Removes the marker. Raises Browserctl::Error when no recording is
+      # active. The message is preserved verbatim from the pre-split
+      # facade so existing specs and CLI surfaces stay stable.
+      def clear!
+        name = active
+        raise Browserctl::Error, "no active recording — run: browserctl recording start <name>" unless name
+
+        File.unlink(Browserctl::Recording::STATE_FILE)
+        name
+      end
+    end
+  end
+end

data/lib/browserctl/recording/workflow_renderer.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "date"
+require "uri"
+
+module Browserctl
+  class Recording
+    # Renders a recording log into the Ruby source of a workflow. Pure
+    # function over the parsed log entries — no I/O, no clock, no globals.
+    #
+    # Carved out of `Recording` so the facade stays focused on dispatch;
+    # the step-rendering rules (selector vs ref, inferred waits, URL and
+    # snapshot postconditions, secret param wiring) all live here.
+    module WorkflowRenderer
+      # 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
+
+      module_function
+
+      # Returns the Ruby source string for the workflow named `name`,
+      # given the parsed (non-meta) command entries.
+      def render(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
+          # format_version: #{Browserctl::WORKFLOW_FORMAT_VERSION}
+          #{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
+    end
+  end
+end