browserctl 0.14.0 → 0.15.0

data/lib/browserctl/replay/context.rb

@@ -16,7 +16,7 @@ module Browserctl
     # context so the surrounding workflow runner can render them into a
     # drift report at end-of-run.
     class Context
-      DriftEvent = Struct.new(:command, :selector, :matched_ref, :score, :reason, keyword_init: true)
+      DriftEvent = Data.define(:command, :selector, :matched_ref, :score, :reason)
 
       attr_reader :drift_events
 

data/lib/browserctl/replay/fingerprint_matcher.rb

@@ -21,7 +21,7 @@ module Browserctl
       DEFAULT_THRESHOLD = 0.6
       WEIGHTS = { text: 0.40, role: 0.20, neighbors: 0.25, position: 0.15 }.freeze
 
-      Match = Struct.new(:candidate, :score, keyword_init: true)
+      Match = Data.define(:candidate, :score)
 
       def initialize(threshold: DEFAULT_THRESHOLD, weights: WEIGHTS)
         @threshold = threshold

data/lib/browserctl/server/command_dispatcher.rb

@@ -3,6 +3,7 @@
 require_relative "snapshot_builder"
 require_relative "page_session"
 require_relative "handlers/error_payload"
+require_relative "plugin_dispatcher"
 require_relative "handlers/page_lifecycle"
 require_relative "handlers/navigation"
 require_relative "handlers/observation"
@@ -11,11 +12,13 @@ require_relative "handlers/hitl"
 require_relative "handlers/devtools"
 require_relative "handlers/daemon_control"
 require_relative "handlers/storage"
+require_relative "handlers/data"
 require_relative "handlers/state"
 require_relative "handlers/interaction"
 require_relative "../detectors"
 require_relative "../policy"
 require_relative "../errors"
+require_relative "../tracing"
 require_relative "../replay/snapshot_diff"
 
 module Browserctl
@@ -29,6 +32,7 @@ module Browserctl
     include Handlers::DevTools
     include Handlers::DaemonControl
     include Handlers::Storage
+    include Handlers::Data
     include Handlers::StateRpc
     include Handlers::Interaction
 
@@ -62,6 +66,10 @@ module Browserctl
       "storage_export" => :cmd_storage_export,
       "storage_import" => :cmd_storage_import,
       "storage_delete" => :cmd_storage_delete,
+      "data_get" => :cmd_data_get,
+      "data_set" => :cmd_data_set,
+      "data_delete" => :cmd_data_delete,
+      "data_list" => :cmd_data_list,
       "press" => :cmd_press,
       "hover" => :cmd_hover,
       "upload" => :cmd_upload,
@@ -80,12 +88,13 @@ module Browserctl
     SCREENSHOT_EXTS  = %w[.png .jpg .jpeg].freeze
 
     def initialize(pages, driver, snapshot_builder = SnapshotBuilder.new, global_mutex: Mutex.new)
-      @pages            = pages
-      @driver           = driver
-      @snapshot_builder = snapshot_builder
-      @global_mutex     = global_mutex
-      @kv_store         = {}
-      @kv_mutex         = Mutex.new
+      @pages             = pages
+      @driver            = driver
+      @snapshot_builder  = snapshot_builder
+      @global_mutex      = global_mutex
+      @kv_store          = {}
+      @kv_mutex          = Mutex.new
+      @plugin_dispatcher = PluginDispatcher.new(@pages, global_mutex: @global_mutex)
     end
 
     # Dispatches a parsed request to the appropriate handler.
@@ -93,13 +102,15 @@ module Browserctl
     # @param req [Hash{Symbol => Object}] parsed request; must include `:cmd`
     # @return [Hash{Symbol => Object}] response; always includes `:ok` or `:error`
     def dispatch(req)
-      builtin = dispatch_builtin(req)
-      return builtin if builtin
+      Tracing.in_span("command.#{req[:cmd]}", attributes: { command: req[:cmd], page: req[:name] }) do
+        builtin = dispatch_builtin(req)
+        next builtin if builtin
 
-      plugin = dispatch_plugin(req)
-      return plugin if plugin
+        plugin = dispatch_plugin(req)
+        next plugin if plugin
 
-      { error: "unknown command: #{req[:cmd]}" }
+        { error: "unknown command: #{req[:cmd]}" }
+      end
     end
 
     private
@@ -116,13 +127,10 @@ module Browserctl
 
     # Routes the request to a registered plugin command if one matches.
     # Returns the plugin response, or `nil` if no plugin handles `req[:cmd]`.
+    # Plugin invocation, timeout, and rescue boundary all live in
+    # {PluginDispatcher} — see v0.15 WS-2 PR 5.
     def dispatch_plugin(req)
-      plugin = Browserctl.lookup_plugin_command(req[:cmd])
-      return nil unless plugin
-
-      Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
-      session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
-      plugin.call(session, req)
+      @plugin_dispatcher.dispatch(req)
     end
 
     def with_page(name)

data/lib/browserctl/server/handlers/cookies.rb

@@ -7,38 +7,35 @@ module Browserctl
         private
 
         def cmd_cookies(req)
-          session = @global_mutex.synchronize { @pages[req[:name]] }
-          return { error: "no page named '#{req[:name]}'" } unless session
-
-          all = session.page.cookies.all
-          { ok: true, cookies: all.values.map(&:to_h) }
+          with_page(req[:name]) do |session|
+            all = session.driver.cookies_all
+            { ok: true, cookies: all.values.map(&:to_h) }
+          end
         end
 
         def cmd_set_cookie(req)
-          session = @global_mutex.synchronize { @pages[req[:name]] }
-          return { error: "no page named '#{req[:name]}'" } unless session
-
-          session.page.cookies.set(
-            name: req[:cookie_name],
-            value: req[:value],
-            domain: req[:domain],
-            path: req.fetch(:path, "/")
-          )
-          { ok: true }
+          with_page(req[:name]) do |session|
+            session.driver.cookies_set(
+              name: req[:cookie_name],
+              value: req[:value],
+              domain: req[:domain],
+              path: req.fetch(:path, "/")
+            )
+            { ok: true }
+          end
         end
 
         def cmd_delete_cookies(req)
-          session = @global_mutex.synchronize { @pages[req[:name]] }
-          return { error: "no page named '#{req[:name]}'" } unless session
-
-          session.page.cookies.clear
-          { ok: true }
+          with_page(req[:name]) do |session|
+            session.driver.cookies_clear
+            { ok: true }
+          end
         end
 
         def cmd_import_cookies(req)
           with_page(req[:name]) do |session|
             req[:cookies].each do |c|
-              session.page.cookies.set(
+              session.driver.cookies_set(
                 name: c[:name],
                 value: c[:value],
                 domain: c[:domain],

data/lib/browserctl/server/handlers/data.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      # `data` is the unified verb family that subsumes `cookie *` and
+      # `storage *` (introduced in v0.15 via ADR-0021). Every operation takes
+      # a required `scope` ∈ {cookies, localStorage, sessionStorage} and
+      # returns a unified envelope shape — see docs/reference/commands.md
+      # for the full table.
+      #
+      # The legacy `cookies`, `set_cookie`, `delete_cookies`, `import_cookies`,
+      # `storage_*` handlers remain as aliases that delegate here so the old
+      # wire verbs keep working for the v0.15 deprecation window.
+      module Data
+        VALID_SCOPES = %w[cookies localStorage sessionStorage].freeze
+
+        private
+
+        # @return [Hash] unified response with `ok`, `scope`, plus per-op fields
+        def cmd_data_get(req)
+          scope = validate_scope(req[:scope])
+          return scope if scope.is_a?(Hash) # error envelope
+
+          case scope
+          when "cookies"
+            { error: "data get is not supported for scope 'cookies' — use 'data list'",
+              code: Browserctl::Error::Codes::INVALID_ARGUMENT }
+          when "localStorage", "sessionStorage"
+            with_page(req[:name]) do |session|
+              js = storage_get_js(scope, req[:key])
+              value = session.driver.evaluate(js)
+              { ok: true, scope: scope, key: req[:key], value: value }
+            end
+          end
+        end
+
+        def cmd_data_set(req)
+          scope = validate_scope(req[:scope])
+          return scope if scope.is_a?(Hash)
+
+          case scope
+          when "cookies"
+            with_page(req[:name]) do |session|
+              unless req[:domain]
+                next({ error: "data set --scope cookies requires --domain",
+                       code: Browserctl::Error::Codes::INVALID_ARGUMENT })
+              end
+
+              session.driver.cookies_set(
+                name: req[:key],
+                value: req[:value],
+                domain: req[:domain],
+                path: req.fetch(:path, "/")
+              )
+              { ok: true, scope: scope, key: req[:key] }
+            end
+          when "localStorage", "sessionStorage"
+            with_page(req[:name]) do |session|
+              js = storage_set_js(scope, req[:key], req[:value])
+              session.driver.evaluate(js)
+              { ok: true, scope: scope, key: req[:key] }
+            end
+          end
+        end
+
+        def cmd_data_delete(req)
+          scope = validate_scope(req[:scope])
+          return scope if scope.is_a?(Hash)
+
+          case scope
+          when "cookies"
+            with_page(req[:name]) do |session|
+              count = session.driver.cookies_all.length
+              session.driver.cookies_clear
+              { ok: true, scope: scope, deleted: count }
+            end
+          when "localStorage"
+            with_page(req[:name]) do |session|
+              count = JSON.parse(session.driver.evaluate("JSON.stringify({...localStorage})") || "{}").length
+              session.driver.evaluate("localStorage.clear()")
+              { ok: true, scope: scope, deleted: count }
+            end
+          when "sessionStorage"
+            with_page(req[:name]) do |session|
+              count = JSON.parse(session.driver.evaluate("JSON.stringify({...sessionStorage})") || "{}").length
+              session.driver.evaluate("sessionStorage.clear()")
+              { ok: true, scope: scope, deleted: count }
+            end
+          end
+        end
+
+        def cmd_data_list(req)
+          scope = validate_scope(req[:scope])
+          return scope if scope.is_a?(Hash)
+
+          case scope
+          when "cookies"
+            with_page(req[:name]) do |session|
+              entries = session.driver.cookies_all.values.map(&:to_h)
+              { ok: true, scope: scope, entries: entries, count: entries.length }
+            end
+          when "localStorage", "sessionStorage"
+            with_page(req[:name]) do |session|
+              raw     = session.driver.evaluate("JSON.stringify({...#{scope}})") || "{}"
+              parsed  = JSON.parse(raw)
+              entries = parsed.map { |k, v| { key: k, value: v } }
+              { ok: true, scope: scope, entries: entries, count: entries.length }
+            end
+          end
+        end
+
+        # Returns the canonical scope string, or an error envelope on bad input.
+        def validate_scope(raw)
+          return invalid_scope_error(raw) if raw.nil?
+
+          scope = raw.to_s
+          # Accept short forms as v0.15-only wire aliases (per ADR-0021).
+          scope = "localStorage"   if scope == "local"
+          scope = "sessionStorage" if scope == "session"
+          return invalid_scope_error(raw) unless VALID_SCOPES.include?(scope)
+
+          scope
+        end
+
+        def invalid_scope_error(raw)
+          {
+            error: "invalid --scope '#{raw}' — expected one of: #{VALID_SCOPES.join(', ')}",
+            code: Browserctl::Error::Codes::INVALID_ARGUMENT
+          }
+        end
+
+        def storage_get_js(scope, key)
+          target = scope == "localStorage" ? "localStorage" : "sessionStorage"
+          "#{target}.getItem(#{key.to_json})"
+        end
+
+        def storage_set_js(scope, key, value)
+          target = scope == "localStorage" ? "localStorage" : "sessionStorage"
+          "#{target}.setItem(#{key.to_json}, #{value.to_json})"
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server/handlers/devtools.rb

@@ -9,15 +9,14 @@ module Browserctl
         def cmd_devtools(req)
           return { error: "devtools is not supported by this driver" } unless @driver.supports?(:devtools)
 
-          session = @global_mutex.synchronize { @pages[req[:name]] }
-          return { error: "no page named '#{req[:name]}'" } unless session
-
-          info      = @driver.devtools_info(session.page)
-          port      = info[:port]
-          target_id = info[:target_id]
-          devtools_url = "http://127.0.0.1:#{port}/devtools/inspector.html" \
-                         "?ws=127.0.0.1:#{port}/devtools/page/#{target_id}"
-          { ok: true, devtools_url: devtools_url }
+          with_page(req[:name]) do |session|
+            info      = @driver.devtools_info(session.driver)
+            port      = info[:port]
+            target_id = info[:target_id]
+            devtools_url = "http://127.0.0.1:#{port}/devtools/inspector.html" \
+                           "?ws=127.0.0.1:#{port}/devtools/page/#{target_id}"
+            { ok: true, devtools_url: devtools_url }
+          end
         end
       end
     end

data/lib/browserctl/server/handlers/hitl.rb

@@ -3,10 +3,18 @@
 module Browserctl
   class CommandDispatcher
     module Handlers
+      # HITL pause/resume cannot route through `with_page` because `with_page`
+      # acquires `session.mutex` and waits on `session.pause_cv` while paused.
+      # Pause sets that flag; resume signals the CV. Reentering `with_page`
+      # would deadlock — resume would never get the lock to clear the flag.
+      # So these handlers look up the session under `@global_mutex` directly,
+      # then manage `session.mutex` / `pause_cv` themselves.
       module Hitl
         private
 
         def cmd_pause(req)
+          # registry lookup: HITL manages session.mutex/pause_cv directly,
+          # cannot reenter with_page (would deadlock against pause_cv wait).
           session = @global_mutex.synchronize { @pages[req[:name]] }
           return { error: "no page named '#{req[:name]}'" } unless session
 
@@ -16,6 +24,8 @@ module Browserctl
         end
 
         def cmd_resume(req)
+          # registry lookup: HITL manages session.mutex/pause_cv directly,
+          # cannot reenter with_page (would deadlock against pause_cv wait).
           session = @global_mutex.synchronize { @pages[req[:name]] }
           return { error: "no page named '#{req[:name]}'" } unless session
 

data/lib/browserctl/server/handlers/interaction.rb

@@ -8,8 +8,8 @@ module Browserctl
 
         def cmd_press(req)
           with_page(req[:name]) do |session|
-            session.page.keyboard.down(req[:key])
-            session.page.keyboard.up(req[:key])
+            session.driver.keyboard_down(req[:key])
+            session.driver.keyboard_up(req[:key])
             { ok: true }
           end
         end
@@ -19,7 +19,7 @@ module Browserctl
             sel = resolve_selector_from(session, req)
             return sel if sel.is_a?(Hash)
 
-            coords = session.page.evaluate(
+            coords = session.driver.evaluate(
               "(function(sel) {   " \
               "var el = document.querySelector(sel);   " \
               "if (!el) return null;   " \
@@ -35,7 +35,7 @@ module Browserctl
               )
             end
 
-            session.page.mouse.move(x: coords["x"], y: coords["y"])
+            session.driver.mouse_move(x: coords["x"], y: coords["y"])
             { ok: true }
           end
         end
@@ -48,7 +48,7 @@ module Browserctl
             sel = resolve_selector_from(session, req)
             return sel if sel.is_a?(Hash)
 
-            el = session.page.at_css(sel)
+            el = session.driver.at_css(sel)
             unless el
               return error_payload(
                 code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
@@ -67,7 +67,7 @@ module Browserctl
             sel = resolve_selector_from(session, req)
             return sel if sel.is_a?(Hash)
 
-            el = session.page.at_css(sel)
+            el = session.driver.at_css(sel)
             unless el
               return error_payload(
                 code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
@@ -85,28 +85,26 @@ module Browserctl
         end
 
         def cmd_dialog_accept(req)
-          session = @global_mutex.synchronize { @pages[req[:name]] }
-          return { error: "no page named '#{req[:name]}'" } unless session
-
-          text = req[:text]
-          id   = nil
-          id = session.page.on(:dialog) do |dialog|
-            session.page.off(:dialog, id)
-            dialog.accept(text)
+          with_page(req[:name]) do |session|
+            text = req[:text]
+            id   = nil
+            id = session.driver.on(:dialog) do |dialog|
+              session.driver.off(:dialog, id)
+              dialog.accept(text)
+            end
+            { ok: true }
           end
-          { ok: true }
         end
 
         def cmd_dialog_dismiss(req)
-          session = @global_mutex.synchronize { @pages[req[:name]] }
-          return { error: "no page named '#{req[:name]}'" } unless session
-
-          id = nil
-          id = session.page.on(:dialog) do |dialog|
-            session.page.off(:dialog, id)
-            dialog.dismiss
+          with_page(req[:name]) do |session|
+            id = nil
+            id = session.driver.on(:dialog) do |dialog|
+              session.driver.off(:dialog, id)
+              dialog.dismiss
+            end
+            { ok: true }
           end
-          { ok: true }
         end
       end
     end

data/lib/browserctl/server/handlers/navigation.rb

@@ -19,20 +19,20 @@ module Browserctl
           end
 
           with_page(req[:name]) do |session|
-            session.page.go_to(req[:url])
-            { ok: true, url: session.page.current_url, challenge: Detectors.cloudflare?(session.page) }
+            session.driver.go_to(req[:url])
+            { ok: true, url: session.driver.current_url, challenge: Detectors.cloudflare?(session.driver) }
           end
         end
 
         def cmd_wait(req)
           with_page(req[:name]) do |session|
-            result = wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 30).to_f)
+            result = wait_for_selector(session.driver, req[:selector], req.fetch(:timeout, 30).to_f)
             result[:error] ? result : { ok: true, selector: req[:selector] }
           end
         end
 
         def cmd_evaluate(req)
-          with_page(req[:name]) { |session| { ok: true, result: session.page.evaluate(req[:expression]) } }
+          with_page(req[:name]) { |session| { ok: true, result: session.driver.evaluate(req[:expression]) } }
         end
 
         def cmd_fill(req)
@@ -40,7 +40,7 @@ module Browserctl
             sel = resolve_selector_from(session, req)
             return sel if sel.is_a?(Hash)
 
-            result = type_into(session.page, sel, req[:value])
+            result = type_into(session.driver, sel, req[:value])
             enrich_with_recording_metadata(result, session, sel, req)
           end
         end
@@ -50,7 +50,7 @@ module Browserctl
             sel = resolve_selector_from(session, req)
             return sel if sel.is_a?(Hash)
 
-            result = click_element(session.page, sel)
+            result = click_element(session.driver, sel)
             enrich_with_recording_metadata(result, session, sel, req)
           end
         end
@@ -69,14 +69,14 @@ module Browserctl
             ref: ref,
             fingerprint: fp,
             snapshot_id: session.snapshot_id,
-            postcondition_hint: { url: session.page.current_url }
+            postcondition_hint: { url: session.driver.current_url }
           )
           enriched[:post_snapshot_digest] = capture_post_snapshot_digest(session) if req[:capture_post_snapshot]
           enriched.compact
         end
 
         def capture_post_snapshot_digest(session)
-          snapshot = @snapshot_builder.call(session.page)
+          snapshot = @snapshot_builder.call(session.driver)
           Browserctl::Replay::SnapshotDiff.digest(snapshot)
         rescue JSON::ParserError, Timeout::Error, Browserctl::Error => e
           Browserctl.logger.debug("post-snapshot digest skipped: #{e.class}: #{e.message}")
@@ -84,11 +84,11 @@ module Browserctl
         end
 
         def cmd_url(req)
-          with_page(req[:name]) { |session| { ok: true, url: session.page.current_url } }
+          with_page(req[:name]) { |session| { ok: true, url: session.driver.current_url } }
         end
 
-        def type_into(page, selector, value)
-          el = page.at_css(selector)
+        def type_into(driver, selector, value)
+          el = driver.at_css(selector)
           unless el
             return error_payload(
               code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
@@ -103,8 +103,8 @@ module Browserctl
           { ok: true }
         end
 
-        def click_element(page, selector)
-          el = page.at_css(selector)
+        def click_element(driver, selector)
+          el = driver.at_css(selector)
           unless el
             return error_payload(
               code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
@@ -127,10 +127,10 @@ module Browserctl
           session.ref_registry[req[:ref]] || { error: "ref '#{req[:ref]}' not found — run snap first" }
         end
 
-        def wait_for_selector(page, selector, timeout)
+        def wait_for_selector(driver, selector, timeout)
           deadline = Time.now + timeout
           loop do
-            found = page.at_css(selector)
+            found = driver.at_css(selector)
             break { ok: true } if found
             break { error: "wait timeout: selector '#{selector}' not found after #{timeout}s" } if Time.now >= deadline
 

data/lib/browserctl/server/handlers/observation.rb

@@ -19,9 +19,9 @@ module Browserctl
         # bundle in hand (see PR 18); without them, only the URL signal fires.
         def cmd_auth_check(req)
           with_page(req[:name]) do |session|
-            cookies = session.page.cookies.all.values.map(&:to_h) if req[:include_cookies]
+            cookies = session.driver.cookies_all.values.map(&:to_h) if req[:include_cookies]
             result = Browserctl::Detectors.auth_required(
-              session.page,
+              session.driver,
               cookies: cookies,
               suggested_flow: req[:suggested_flow]
             )
@@ -38,11 +38,11 @@ module Browserctl
 
         def take_snapshot(session, format, diff)
           nonce     = SecureRandom.hex(8)
-          challenge = Detectors.cloudflare?(session.page)
+          challenge = Detectors.cloudflare?(session.driver)
 
-          return { ok: true, html: session.page.body, challenge: challenge, nonce: nonce } unless format == "elements"
+          return { ok: true, html: session.driver.body, challenge: challenge, nonce: nonce } unless format == "elements"
 
-          snapshot = @snapshot_builder.call(session.page)
+          snapshot = @snapshot_builder.call(session.driver)
           registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
           fp_index = build_fingerprint_index(snapshot)
 
@@ -84,7 +84,7 @@ module Browserctl
             return path if path.is_a?(Hash)
 
             FileUtils.mkdir_p(File.dirname(path))
-            session.page.screenshot(path: path, full: req.fetch(:full, false))
+            session.driver.screenshot(path: path, full: req.fetch(:full, false))
             { ok: true, path: path }
           end
         end

data/lib/browserctl/server/handlers/page_lifecycle.rb

@@ -1,26 +1,34 @@
 # frozen_string_literal: true
 
+require_relative "../../driver/ferrum_page_driver"
+
 module Browserctl
   class CommandDispatcher
     module Handlers
+      # Page-lifecycle handlers are intrinsically registry-wide: they
+      # add to, remove from, or enumerate the `@pages` registry. They
+      # legitimately bypass `with_page` and hold `@global_mutex` directly.
       module PageLifecycle
         private
 
         def cmd_page_open(req)
+          # registry-wide: adds an entry to @pages, needs @global_mutex.
           session = @global_mutex.synchronize do
-            @pages[req[:name]] ||= PageSession.new(@driver.create_page)
+            @pages[req[:name]] ||= PageSession.new(Browserctl::Driver::FerrumPageDriver.new(@driver.create_page))
           end
-          session.page.go_to(req[:url]) if req[:url]
+          session.driver.go_to(req[:url]) if req[:url]
           { ok: true, name: req[:name] }
         end
 
         def cmd_page_close(req)
+          # registry-wide: removes an entry from @pages, needs @global_mutex.
           session = @global_mutex.synchronize { @pages.delete(req[:name]) }
-          session&.page&.close
+          session&.driver&.close
           { ok: true }
         end
 
         def cmd_page_list(_req)
+          # registry-wide read: enumerates @pages keys (no per-page state).
           { pages: @global_mutex.synchronize { @pages.keys } }
         end
 
@@ -28,7 +36,7 @@ module Browserctl
           return { error: "page focus requires headed mode — start browserd with --headed" } unless @driver.headed?
 
           with_page(req[:name]) do |session|
-            session.page.activate
+            session.driver.activate
             { ok: true }
           end
         end