browserctl 0.12.0 → 0.13.0

data/lib/browserctl/encryption_service.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module Browserctl
+  # Cryptographic primitives for browserctl-managed payloads.
+  #
+  # Raised when decryption fails (tampered ciphertext or wrong key). Callers
+  # should catch this rather than `OpenSSL::Cipher::CipherError` so they
+  # don't have to take a direct dependency on the underlying cipher library.
+  #
+  # Owns AES-256-GCM cipher setup and PBKDF2 key derivation so callers like
+  # `State::Bundle` don't reach into `OpenSSL::Cipher` directly. The contract
+  # is intentionally narrow:
+  #
+  #   * `derive_keys(passphrase, salt)` returns a `[enc_key, hmac_key]` pair
+  #     derived via PBKDF2-HMAC-SHA256 with `PBKDF2_ITERS` iterations and a
+  #     64-byte output split in half. The first half is the AES-256-GCM key,
+  #     the second is the HMAC-SHA-256 key for the bundle footer.
+  #   * `encrypt(plaintext, key)` returns `nonce || ciphertext || tag`.
+  #   * `decrypt(blob, key)` reverses it; raises `OpenSSL::Cipher::CipherError`
+  #     on tampered blobs / wrong key.
+  #   * `random_salt` / `random_nonce` are exposed so callers can keep bundle
+  #     wire-format assembly in one place without re-deriving sizes.
+  #
+  # The constants here are duplicated in `State::Bundle` only as named
+  # references to the wire format positions; the source of truth lives here.
+  module EncryptionService
+    class DecryptionError < StandardError; end
+
+    SALT_SIZE    = 16
+    NONCE_SIZE   = 12
+    TAG_SIZE     = 16
+    KEY_SIZE     = 32
+    PBKDF2_ITERS = 200_000
+    DIGEST       = "SHA256"
+    CIPHER       = "aes-256-gcm"
+
+    module_function
+
+    # Returns `[enc_key, hmac_key]`, each `KEY_SIZE` bytes.
+    def derive_keys(passphrase, salt)
+      material = OpenSSL::PKCS5.pbkdf2_hmac(passphrase.to_s, salt, PBKDF2_ITERS, KEY_SIZE * 2, DIGEST)
+      [material.byteslice(0, KEY_SIZE), material.byteslice(KEY_SIZE, KEY_SIZE)]
+    end
+
+    # AES-256-GCM. Returns `nonce || ciphertext || tag`.
+    def encrypt(plaintext, key)
+      cipher = OpenSSL::Cipher.new(CIPHER)
+      cipher.encrypt
+      cipher.key = key
+      nonce = SecureRandom.bytes(NONCE_SIZE)
+      cipher.iv = nonce
+      ct = cipher.update(plaintext) + cipher.final
+      nonce + ct + cipher.auth_tag
+    end
+
+    # Inverse of `encrypt`. Raises `DecryptionError` on tampered ciphertext
+    # or wrong key so callers don't need to reach into `OpenSSL::Cipher`.
+    def decrypt(blob, key)
+      nonce      = blob.byteslice(0, NONCE_SIZE)
+      tag        = blob.byteslice(-TAG_SIZE, TAG_SIZE)
+      ciphertext = blob.byteslice(NONCE_SIZE, blob.bytesize - NONCE_SIZE - TAG_SIZE)
+
+      cipher = OpenSSL::Cipher.new(CIPHER)
+      cipher.decrypt
+      cipher.key      = key
+      cipher.iv       = nonce
+      cipher.auth_tag = tag
+      cipher.update(ciphertext) + cipher.final
+    rescue OpenSSL::Cipher::CipherError => e
+      raise DecryptionError, e.message
+    end
+
+    def random_salt
+      SecureRandom.bytes(SALT_SIZE)
+    end
+
+    def random_nonce
+      SecureRandom.bytes(NONCE_SIZE)
+    end
+  end
+end

data/lib/browserctl/flow.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
-require "timeout"
+require_relative "callable_definition"
 require_relative "errors"
-require_relative "secret_resolvers"
 
 module Browserctl
-  FlowParamDef    = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
-  FlowStepDef     = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
   FlowConditionDef = Struct.new(:kind, :label, :block, keyword_init: true)
 
+  # Back-compat aliases — flow_wrapper specs reference these directly.
+  FlowParamDef = CallableDefinition::ParamDef
+  FlowStepDef  = CallableDefinition::StepDef
+
   class FlowContext
     attr_reader :page, :client, :params
 
@@ -29,31 +30,28 @@ module Browserctl
     end
   end
 
-  class Flow
+  class Flow < CallableDefinition
     SEMVER_RE = /\A\d+\.\d+\.\d+\z/
 
-    attr_reader :name,
-                :version_string,
-                :description,
-                :param_defs,
-                :steps,
+    attr_reader :version_string,
                 :preconditions,
                 :postconditions,
                 :produces_state_block,
                 :min_browserctl_version
 
     def initialize(name)
-      @name                   = name.to_s
+      super
       @version_string         = "0.0.0"
-      @description            = nil
-      @param_defs             = {}
-      @steps                  = []
       @preconditions          = []
       @postconditions         = []
       @produces_state_block   = nil
       @min_browserctl_version = nil
     end
 
+    def callable_kind
+      :flow
+    end
+
     def version(value)
       validate_semver!(value, label: "version")
       @version_string = value.to_s
@@ -64,27 +62,6 @@ module Browserctl
       @min_browserctl_version = value.to_s
     end
 
-    def desc(text)
-      @description = text.to_s
-    end
-
-    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
-      secret = true if secret_ref
-      @param_defs[name] = FlowParamDef.new(
-        name: name,
-        required: required,
-        secret: secret,
-        default: default,
-        secret_ref: secret_ref
-      )
-    end
-
-    def step(label, retry_count: 0, timeout: nil, &block)
-      raise ArgumentError, "flow step '#{label}' requires a block" unless block
-
-      @steps << FlowStepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
-    end
-
     def precondition(label = "precondition", &block)
       raise ArgumentError, "precondition '#{label}' requires a block" unless block
 
@@ -103,6 +80,24 @@ module Browserctl
       @produces_state_block = block
     end
 
+    # Definition-time guard against cross-type composition. A flow may only
+    # compose other flows; pulling steps from a workflow would smuggle
+    # `store`/`fetch` into a flow context that has no daemon-backed
+    # persistence.
+    def compose(target_name)
+      name = target_name.to_s
+      if Browserctl.respond_to?(:lookup_workflow) && Browserctl.lookup_workflow(name)
+        raise ArgumentError,
+              "flow '#{@name}' cannot compose workflow '#{name}': flows return state, " \
+              "workflows share state — composition across kinds is not supported"
+      end
+
+      source = Browserctl.lookup_flow(name)
+      raise ArgumentError, "flow '#{name}' not found for composition" unless source
+
+      @steps.concat(source.steps)
+    end
+
     def run(page: nil, client: nil, **params)
       ctx = FlowContext.new(page: page, client: client, params: resolve_params(params))
 
@@ -121,20 +116,12 @@ module Browserctl
       raise ArgumentError, "#{label} must be MAJOR.MINOR.PATCH (got #{value.inspect})"
     end
 
-    def resolve_params(provided)
-      @param_defs.each_with_object({}) do |(name, defn), out|
-        val = if defn.secret_ref
-                SecretResolverRegistry.resolve(defn.secret_ref)
-              elsif provided.key?(name)
-                provided[name]
-              else
-                defn.default
-              end
-
-        raise FlowParamError, "flow '#{@name}' requires param '#{name}'" if defn.required && val.nil?
+    def missing_param_error(name)
+      FlowParamError.new("flow '#{@name}' requires param '#{name}'")
+    end
 
-        out[name] = val
-      end
+    def step_timeout_error(defn)
+      FlowStepError.new("flow '#{@name}' step '#{defn.label}' timed out after #{defn.timeout}s")
     end
 
     def run_conditions(ctx, conditions, error_class:)
@@ -168,17 +155,6 @@ module Browserctl
             "flow '#{@name}' step '#{defn.label}' failed: #{last_error.message}"
     end
 
-    def execute_step_block(ctx, defn)
-      if defn.timeout
-        ::Timeout.timeout(defn.timeout) { ctx.instance_exec(&defn.block) }
-      else
-        ctx.instance_exec(&defn.block)
-      end
-    rescue ::Timeout::Error
-      raise FlowStepError,
-            "flow '#{@name}' step '#{defn.label}' timed out after #{defn.timeout}s"
-    end
-
     def produce_state(ctx)
       return nil unless @produces_state_block
 

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

@@ -5,8 +5,8 @@ require_relative "../../flow"
 
 # Pauses for a human to solve a Cloudflare challenge (Turnstile, "Just a
 # moment...", interactive checkbox), then verifies the challenge cleared
-# before returning. Optionally saves the post-solve session under a name
-# you can reload later with `state load` or `session_load`.
+# before returning. Optionally saves the post-solve state under a name
+# you can reload later with `state load`.
 #
 # Reuses Browserctl::Detectors.cloudflare? — the server-side detector
 # already shipped in v0.8 — by adapting the client-facing PageProxy to
@@ -34,7 +34,7 @@ Browserctl.flow("cloudflare_solve") do
 
   param :prompt,
         default: "Cloudflare challenge detected. Solve it in the browser, then press Enter to continue."
-  param :state_name # optional — if set, session_save is called after the challenge clears
+  param :state_name # optional — if set, state_save is called after the challenge clears
 
   precondition("page proxy is present") { !page.nil? }
   precondition("cloudflare challenge is present") do
@@ -54,6 +54,6 @@ Browserctl.flow("cloudflare_solve") do
   produces_state do
     next nil unless state_name && client
 
-    client.session_save(state_name)
+    client.state_save(state_name)
   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