browserctl 0.3.1 → 0.5.0

data/examples/smoke/params_file.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#
+# Smoke test for --params file loading (Task 7.5).
+#
+# Run with:
+#   browserctl run examples/smoke/params_file.rb --params examples/smoke/params_file.yml
+#
+# The workflow logs in using credentials from the params file and asserts
+# the secure area is reached — proving the params were loaded and available.
+
+Browserctl.workflow "smoke/params_file" do
+  desc "Smoke: load credentials from a --params file and use them in a workflow"
+
+  param :username, required: true
+  param :password, required: true, secret: true
+  param :base_url, default: "https://the-internet.herokuapp.com"
+
+  step "open login page" do
+    client.open_page("main", url: "#{base_url}/login")
+  end
+
+  step "fill credentials from params file" do
+    puts "  [params] username = #{username.inspect}"
+    puts "  [params] password = (#{password.length} chars, secret)"
+    page(:main).fill("input#username", username)
+    page(:main).fill("input#password", password)
+    page(:main).click("button[type=submit]")
+  end
+
+  step "assert login succeeded" do
+    assert page(:main).url.include?("/secure"), "expected redirect to /secure — params may not have loaded"
+    puts "  [ok] reached secure area — params file loaded correctly"
+  end
+end

data/examples/smoke/store_fetch.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+#
+# Smoke test for WorkflowContext#store / #fetch (Task 7.3).
+#
+# Uses the-internet's dynamic loading example: click Start, wait for "Hello World!",
+# capture the text in step 1, assert it is still accessible in step 2 via fetch.
+
+Browserctl.workflow "smoke/store_fetch" do
+  desc "Smoke: store a value in one step and retrieve it in a later step"
+
+  param :base_url, default: "https://the-internet.herokuapp.com"
+
+  step "open dynamic loading page" do
+    client.open_page("main", url: "#{base_url}/dynamic_loading/1")
+  end
+
+  step "click start and capture loaded text" do
+    page(:main).click("div#start button")
+    page(:main).wait_for("div#finish", timeout: 10)
+    text = client.evaluate("main", "document.querySelector('div#finish h4')?.innerText?.trim()")[:result]
+    assert text && !text.empty?, "expected loaded text, got: #{text.inspect}"
+    store(:loaded_text, text)
+    puts "  [store] loaded_text = #{text.inspect}"
+  end
+
+  step "fetch value from previous step and assert" do
+    text = fetch(:loaded_text)
+    puts "  [fetch] loaded_text = #{text.inspect}"
+    assert text == "Hello World!", "expected 'Hello World!', got: #{text.inspect}"
+  end
+
+  step "confirm fetch raises for unknown key" do
+    fetch(:nonexistent_key)
+    assert false, "expected KeyError was not raised"
+  rescue KeyError => e
+    puts "  [ok] KeyError raised as expected: #{e.message}"
+  end
+end

data/examples/the_internet/add_remove_elements.rb

@@ -3,7 +3,8 @@
 Browserctl.workflow "the_internet/add_remove_elements" do
   desc "Add/Remove Elements: add several elements, remove some, assert final count"
 
-  param :base_url, default: "https://the-internet.herokuapp.com"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_add_remove_elements.png")
 
   step "open add/remove elements page" do
     client.open_page("main", url: "#{base_url}/add_remove_elements/")
@@ -13,8 +14,7 @@ Browserctl.workflow "the_internet/add_remove_elements" do
     3.times { page(:main).click("button[onclick]") }
     count = client.evaluate("main", "document.querySelectorAll('#elements button').length")[:result]
     assert count == 3, "expected 3 elements, got: #{count}"
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_add_remove_elements.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 
   step "remove one element" do

data/examples/the_internet/checkboxes.rb

@@ -3,7 +3,8 @@
 Browserctl.workflow "the_internet/checkboxes" do
   desc "Checkboxes: read state, toggle each, verify both checked"
 
-  param :base_url, default: "https://the-internet.herokuapp.com"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_checkboxes.png")
 
   step "open checkboxes page" do
     client.open_page("main", url: "#{base_url}/checkboxes")
@@ -29,7 +30,6 @@ Browserctl.workflow "the_internet/checkboxes" do
   end
 
   step "capture screenshot" do
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_checkboxes.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 end

data/examples/the_internet/dropdown.rb

@@ -3,7 +3,8 @@
 Browserctl.workflow "the_internet/dropdown" do
   desc "Dropdown: select each option via JS, assert selected value"
 
-  param :base_url, default: "https://the-internet.herokuapp.com"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_dropdown.png")
 
   step "open dropdown page" do
     client.open_page("main", url: "#{base_url}/dropdown")
@@ -27,7 +28,6 @@ Browserctl.workflow "the_internet/dropdown" do
   end
 
   step "capture screenshot" do
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_dropdown.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 end

data/examples/the_internet/dynamic_loading.rb

@@ -3,7 +3,8 @@
 Browserctl.workflow "the_internet/dynamic_loading" do
   desc "Dynamic loading: click Start, wait for hidden element to appear"
 
-  param :base_url, default: "https://the-internet.herokuapp.com"
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_dynamic_loading.png")
 
   step "open dynamic loading page" do
     client.open_page("main", url: "#{base_url}/dynamic_loading/1")
@@ -27,7 +28,6 @@ Browserctl.workflow "the_internet/dynamic_loading" do
     sleep 0.2 until client.evaluate("main",
                                     "document.querySelector('#loading')?.style?.display")[:result] == "none" ||
                     Time.now > deadline
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_dynamic_loading.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 end

data/examples/the_internet/login.rb

@@ -3,9 +3,10 @@
 Browserctl.workflow "the_internet/login" do
   desc "Form authentication: fill credentials, submit, assert secure area"
 
-  param :username, default: "tomsmith"
-  param :password, default: "SuperSecretPassword!", secret: true
-  param :base_url, default: "https://the-internet.herokuapp.com"
+  param :username,        default: "tomsmith"
+  param :password,        default: "SuperSecretPassword!", secret: true
+  param :base_url,        default: "https://the-internet.herokuapp.com"
+  param :screenshot_path, default: File.expand_path(".browserctl/screenshots/the_internet_login.png")
 
   step "open login page" do
     client.open_page("main", url: "#{base_url}/login")
@@ -21,8 +22,7 @@ Browserctl.workflow "the_internet/login" do
     assert page(:main).url.include?("/secure"), "expected redirect to /secure"
     flash = client.evaluate("main", "document.querySelector('.flash.success')?.innerText?.trim()")[:result]
     assert flash&.include?("You logged into a secure area!"), "expected success flash, got: #{flash.inspect}"
-    screenshots_dir = File.expand_path("../../docs/screenshots", __dir__)
-    page(:main).screenshot(path: "#{screenshots_dir}/the_internet_login.png")
+    page(:main).screenshot(path: screenshot_path)
   end
 
   step "logout and verify" do

data/lib/browserctl/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "socket"
 require "json"
 require_relative "constants"
@@ -73,10 +74,10 @@ module Browserctl
 
     # Takes a DOM snapshot. Returns `challenge: true` when Cloudflare is detected.
     # @param name [String] logical page name
-    # @param format [String] "ai" (token-efficient JSON) or "html" (raw HTML)
+    # @param format [String] "elements" (interactable elements JSON) or "html" (raw HTML)
     # @param diff [Boolean] return only elements changed since last snapshot
     # @return [Hash] `{ ok: true, snapshot:, challenge: }` or `{ ok: true, html:, challenge: }` or `{ error: }`
-    def snapshot(name, format: "ai", diff: false)
+    def snapshot(name, format: "elements", diff: false)
       call("snapshot", name: name, format: format, diff: diff)
     end
 
@@ -130,6 +131,17 @@ module Browserctl
     # @return [Hash] `{ ok: true, devtools_url: }` or `{ error: }`
     def inspect_page(name)         = call("inspect", name: name)
 
+    # Stores a value in the daemon-scoped key-value store.
+    # @param key [String] storage key
+    # @param value [Object] value to store (must be JSON-serialisable)
+    # @return [Hash] `{ ok: true }` or `{ error: }`
+    def store(key, value) = call("store", key: key, value: value)
+
+    # Retrieves a value from the daemon-scoped key-value store.
+    # @param key [String] storage key
+    # @return [Hash] `{ ok: true, value: }` or `{ error:, code: "key_not_found" }`
+    def fetch(key) = call("fetch", key: key)
+
     # Returns all cookies for a named page.
     # @param name [String] logical page name
     # @return [Hash] `{ ok: true, cookies: [Hash] }` or `{ error: }`
@@ -152,6 +164,30 @@ module Browserctl
     # @return [Hash] `{ ok: true }` or `{ error: }`
     def clear_cookies(name) = call("clear_cookies", name: name)
 
+    # Exports all cookies for a named page to a JSON file.
+    # @param name [String] logical page name
+    # @param path [String] file path to write cookies to
+    # @return [Hash] `{ ok: true, path:, count: }` or `{ error: }`
+    def export_cookies(name, path)
+      result = call("cookies", name: name)
+      return result unless result[:ok]
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "w", 0o600) { |f| f.write(JSON.generate(result[:cookies])) }
+      { ok: true, path: path, count: result[:cookies].length }
+    end
+
+    # Imports cookies from a JSON file into a named page.
+    # @param name [String] logical page name
+    # @param path [String] file path to read cookies from
+    # @return [Hash] `{ ok: true, count: }` or `{ error: }`
+    def import_cookies(name, path)
+      raise "cookie file not found: #{path}" unless File.exist?(path)
+
+      cookies = JSON.parse(File.read(path), symbolize_names: true)
+      call("import_cookies", name: name, cookies: cookies)
+    end
+
     private
 
     def communicate(payload)

data/lib/browserctl/commands/export_cookies.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class ExportCookies
+      def self.run(client, args)
+        page = args.shift or abort "usage: browserctl export-cookies <page> <path>"
+        path = args.shift or abort "usage: browserctl export-cookies <page> <path>"
+        result = client.export_cookies(page, path)
+        if result[:error]
+          warn "Error: #{result[:error]}"
+          exit 1
+        end
+        puts result.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/import_cookies.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class ImportCookies
+      def self.run(client, args)
+        page = args.shift or abort "usage: browserctl import-cookies <page> <path>"
+        path = args.shift or abort "usage: browserctl import-cookies <page> <path>"
+        begin
+          result = client.import_cookies(page, path)
+        rescue StandardError => e
+          warn "Error: #{e.message}"
+          exit 1
+        end
+        if result[:error]
+          warn "Error: #{result[:error]}"
+          exit 1
+        end
+        puts result.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/init.rb

@@ -13,15 +13,26 @@ module Browserctl
         # workflows_dir: .browserctl/workflows
       YAML
 
+      GITIGNORE_CONTENT = <<~GITIGNORE
+        # Cookie session exports — contain credentials, never commit
+        sessions/
+      GITIGNORE
+
       def self.run(_args)
         FileUtils.mkdir_p(".browserctl/workflows")
         FileUtils.touch(".browserctl/workflows/.keep")
 
+        FileUtils.mkdir_p(".browserctl/sessions")
+
+        gitignore_path = ".browserctl/.gitignore"
+        File.write(gitignore_path, GITIGNORE_CONTENT) unless File.exist?(gitignore_path)
+
         config_path = ".browserctl/config.yml"
         File.write(config_path, CONFIG_TEMPLATE) unless File.exist?(config_path)
 
         puts "Initialised browserctl project:"
         puts "  .browserctl/workflows/   (place workflow .rb files here)"
+        puts "  .browserctl/sessions/    (cookie exports — git-ignored)"
         puts "  .browserctl/config.yml   (project settings)"
       end
     end

data/lib/browserctl/commands/{pause_resume.rb → pause.rb}

@@ -4,10 +4,10 @@ require_relative "cli_output"
 
 module Browserctl
   module Commands
-    module PauseResume
+    module Pause
       extend CliOutput
 
-      def self.pause(client, args)
+      def self.run(client, args)
         name = args.shift or abort "usage: browserctl pause <page>"
         res = client.pause(name)
         if res[:error]
@@ -17,16 +17,6 @@ module Browserctl
         puts "Page '#{name}' paused. Browser is live — interact freely."
         puts "When done: browserctl resume #{name}"
       end
-
-      def self.resume(client, args)
-        name = args.shift or abort "usage: browserctl resume <page>"
-        res = client.resume(name)
-        if res[:error]
-          warn "Error: #{res[:error]}"
-          exit 1
-        end
-        puts "Page '#{name}' resumed."
-      end
     end
   end
 end

data/lib/browserctl/commands/record.rb

@@ -26,6 +26,8 @@ module Browserctl
         def run_start(args)
           Optimist.options(args) { banner "Usage: browserctl record start <name>" }
           name = args.shift or abort "usage: browserctl record start <name>"
+          abort "Invalid recording name #{name.inspect} — use only letters, digits, _ or -" \
+            unless name =~ /\A[a-zA-Z0-9_-]{1,64}\z/
           Recording.start(name)
           puts "Recording started: #{name}"
           puts "Run browser commands, then: browserctl record stop"

data/lib/browserctl/commands/resume.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Resume
+      extend CliOutput
+
+      def self.run(client, args)
+        name = args.shift or abort "usage: browserctl resume <page>"
+        res = client.resume(name)
+        if res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        puts "Page '#{name}' resumed."
+      end
+    end
+  end
+end

data/lib/browserctl/commands/snapshot.rb

@@ -6,15 +6,15 @@ require "optimist"
 module Browserctl
   module Commands
     class Snapshot
-      VALID_FORMATS = %w[ai html].freeze
+      VALID_FORMATS = %w[elements html].freeze
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl snap <page> [--format ai|html] [--diff]"
-          opt :format, "Output format: ai or html", default: "ai", short: "-f"
+          banner "Usage: browserctl snap <page> [--format elements|html] [--diff]"
+          opt :format, "Output format: elements (default) or html", default: "elements", short: "-f"
           opt :diff,   "Return only changed elements", default: false, short: "-d"
         end
-        name = args.shift or abort "usage: browserctl snap <page> [--format ai|html] [--diff]"
+        name = args.shift or abort "usage: browserctl snap <page> [--format elements|html] [--diff]"
         unless VALID_FORMATS.include?(opts[:format])
           warn "Error: --format must be one of: #{VALID_FORMATS.join(', ')}"
           exit 1
@@ -31,7 +31,7 @@ module Browserctl
             warn "Error: #{res[:error]}"
             exit 1
           end
-          puts(format == "ai" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
+          puts(format == "elements" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
         end
       end
     end

data/lib/browserctl/commands/status.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Browserctl
+  module Commands
+    module Status
+      def self.run(client)
+        ping = client.ping
+        pages = client.list_pages[:pages] || []
+        page_info = pages.map do |name|
+          url_res = client.url(name)
+          { name: name, url: url_res[:url] || url_res[:error] }
+        end
+
+        puts JSON.pretty_generate(
+          daemon: "online",
+          pid: ping[:pid],
+          protocol_version: ping[:protocol_version],
+          pages: page_info
+        )
+      rescue RuntimeError => e
+        raise unless e.message.include?("browserd is not running")
+
+        puts JSON.pretty_generate(daemon: "offline", error: e.message)
+        exit 1
+      end
+    end
+  end
+end

data/lib/browserctl/constants.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 module Browserctl
-  BROWSERCTL_DIR = File.expand_path("~/.browserctl")
-  IDLE_TTL       = 30 * 60
+  BROWSERCTL_DIR   = File.expand_path("~/.browserctl")
+  IDLE_TTL         = 30 * 60
+  # Increment when a breaking wire protocol change ships (new field names, removed commands, changed response shapes).
+  # Clients read this from `ping` to verify compatibility before sending commands.
+  PROTOCOL_VERSION = "1"
 
   def self.socket_path(name = nil)
     File.join(BROWSERCTL_DIR, name ? "#{name}.sock" : "browserd.sock")
@@ -12,6 +15,10 @@ module Browserctl
     File.join(BROWSERCTL_DIR, name ? "#{name}.pid" : "browserd.pid")
   end
 
+  def self.log_path(name = nil)
+    File.join(BROWSERCTL_DIR, name ? "#{name}.log" : "browserd.log")
+  end
+
   # Backward-compatible constants
   SOCKET_PATH = socket_path
   PID_PATH    = pid_path

data/lib/browserctl/detectors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Detectors
+    CLOUDFLARE_SIGNALS = [
+      "cf-challenge-running",
+      "cf_chl_opt",
+      "__cf_chl_f_tk",
+      "Just a moment..."
+    ].freeze
+
+    # Returns true if the page appears to be showing a Cloudflare challenge.
+    # Checks both the current URL and the page body for known Cloudflare signals.
+    # @param page [Ferrum::Page] the browser page to inspect
+    # @return [Boolean]
+    def self.cloudflare?(page)
+      url  = page.current_url.to_s
+      body = page.body.to_s
+      url.include?("challenge-platform") ||
+        CLOUDFLARE_SIGNALS.any? { |sig| body.include?(sig) }
+    end
+  end
+end

data/lib/browserctl/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Browserctl
+  # Base error class for all browserctl daemon errors.
+  # Subclasses carry a machine-readable `code` that appears in wire responses.
+  # @attr_reader code [String] machine-readable error code
+  class Error < StandardError
+    def self.default_code = "error"
+
+    attr_reader :code
+
+    def initialize(msg = nil, code: self.class.default_code)
+      @code = code
+      super(msg)
+    end
+  end
+
+  class PageNotFound     < Error; def self.default_code = "page_not_found"     end
+  class SelectorNotFound < Error; def self.default_code = "selector_not_found" end
+  class RefNotFound      < Error; def self.default_code = "ref_not_found"      end
+  class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"   end
+  class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
+  class TimeoutError     < Error; def self.default_code = "timeout"            end
+  class KeyNotFound      < Error; def self.default_code = "key_not_found"      end
+end

data/lib/browserctl/logger.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+require "fileutils"
 
 module Browserctl
   LEVEL_MAP = {
@@ -10,6 +11,25 @@ module Browserctl
     "error" => ::Logger::ERROR
   }.freeze
 
+  class MultiLogger
+    def initialize(*loggers)
+      @loggers = loggers
+    end
+
+    # Delegate to each logger; swallow individual write failures so a broken file
+    # logger never crashes the daemon or drops a client response.
+    def debug(msg = nil, &) = @loggers.each { |l| l.debug(msg, &) rescue nil } # rubocop:disable Style/RescueModifier
+    def info(msg = nil, &)  = @loggers.each { |l| l.info(msg, &)  rescue nil } # rubocop:disable Style/RescueModifier
+    def warn(msg = nil, &)  = @loggers.each { |l| l.warn(msg, &)  rescue nil } # rubocop:disable Style/RescueModifier
+    def error(msg = nil, &) = @loggers.each { |l| l.error(msg, &) rescue nil } # rubocop:disable Style/RescueModifier
+
+    def level = @loggers.first&.level
+
+    def level=(lvl)
+      @loggers.each { |l| l.level = lvl }
+    end
+  end
+
   def self.logger
     @logger ||= build_logger("info")
   end
@@ -18,11 +38,26 @@ module Browserctl
     @logger = instance
   end
 
-  def self.build_logger(level_name)
-    log = ::Logger.new($stderr)
-    log.level    = LEVEL_MAP.fetch(level_name.to_s.downcase, ::Logger::INFO)
-    log.progname = "browserd"
-    log.formatter = proc { |sev, t, prog, msg| "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{msg}\n" }
+  def self.build_logger(level_name, log_path: nil)
+    level = LEVEL_MAP.fetch(level_name.to_s.downcase, ::Logger::INFO)
+    formatter = proc { |sev, t, prog, msg| "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{msg}\n" }
+
+    stderr_log = make_logger($stderr, level, formatter)
+    return stderr_log unless log_path
+
+    FileUtils.mkdir_p(File.dirname(log_path), mode: 0o700)
+    FileUtils.touch(log_path)
+    File.chmod(0o600, log_path)
+    file_log = make_logger(log_path, level, formatter)
+    MultiLogger.new(stderr_log, file_log)
+  end
+
+  def self.make_logger(device, level, formatter)
+    log = ::Logger.new(device)
+    log.level     = level
+    log.progname  = "browserd"
+    log.formatter = formatter
     log
   end
+  private_class_method :make_logger
 end

data/lib/browserctl/policy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Browserctl
+  module Policy
+    # Returns true if the URL is permitted by the domain policy.
+    # When BROWSERCTL_ALLOWED_DOMAINS is unset, all URLs are allowed.
+    # @param url [String] the URL to check
+    # @return [Boolean]
+    def self.allowed_navigation?(url)
+      domains = allowed_domains
+      return true if domains.empty?
+
+      host_matches?(URI.parse(url).host, domains)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def self.allowed_domains
+      raw = ENV.fetch("BROWSERCTL_ALLOWED_DOMAINS", nil)
+      return [] unless raw&.match?(/\S/)
+
+      raw.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    def self.host_matches?(host, domains)
+      return false unless host
+
+      normalised = host.downcase
+      domains.any? { |d| normalised == d.downcase || normalised.end_with?(".#{d.downcase}") }
+    end
+
+    private_class_method :allowed_domains, :host_matches?
+  end
+end