browserctl 0.10.0 → 0.12.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.rb

@@ -2,19 +2,46 @@
 
 require "json"
 require "date"
+require "time"
 require "fileutils"
 require "tmpdir"
 require "uri"
+require_relative "errors"
+require_relative "error/codes"
 
 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")
 
+    # Recording-log format version, written into the `_meta` header and
+    # validated when generate_workflow loads a recording. Distinct from
+    # LOG_FORMAT below — that string ("v0.11") tracks the human-readable
+    # log shape; this integer is the machine-readable schema gate per the
+    # WS-1 format-version convention. See docs/reference/format-versions.md.
+    RECORDING_FORMAT_VERSION = 1
+    SUPPORTED_FORMAT_VERSIONS = [RECORDING_FORMAT_VERSION].freeze
+
     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
+
+    # 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,12 +49,21 @@ 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",
+          format_version: RECORDING_FORMAT_VERSION,
+          log_format: LOG_FORMAT,
+          recording: name,
+          started_at: Time.now.utc.iso8601
+        )
+      end
       name
     end
 
     def self.stop
       name = active
-      raise "no active recording — run: browserctl record start <name>" unless name
+      raise Browserctl::Error, "no active recording — run: browserctl record start <name>" unless name
 
       File.unlink(STATE_FILE)
       name
@@ -37,69 +73,232 @@ 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)
+      raise Browserctl::Error, "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) }
+      verify_format_version!(raw, path: log)
+      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
       private
 
+      # Raises Browserctl::ProtocolMismatch when the recording log's _meta
+      # header is missing or declares a format_version this build does not
+      # support. Mirrors Browserctl::State::Bundle.verify_format_version!.
+      def verify_format_version!(raw_lines, path: nil)
+        meta = raw_lines.first
+        version = meta && meta[:cmd] == "_meta" ? meta[:format_version] : nil
+        return if version && SUPPORTED_FORMAT_VERSIONS.include?(version)
+
+        where = path ? " at #{path}" : ""
+        msg = if version.nil?
+                "recording log#{where} is missing format_version " \
+                  "(supported: #{SUPPORTED_FORMAT_VERSIONS.inspect})"
+              else
+                "recording log#{where} declares format_version=#{version.inspect}, " \
+                  "this build supports #{SUPPORTED_FORMAT_VERSIONS.inspect}"
+              end
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
+      end
+
       def log_path(name)
         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
-
+          # 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)
 
@@ -113,12 +312,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 +343,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 +353,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/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