browserctl 0.3.1 → 0.5.0

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Navigation
+        private
+
+        def cmd_goto(req)
+          unless Policy.allowed_navigation?(req[:url].to_s)
+            return { error: "navigation to '#{req[:url]}' blocked by domain policy", code: "domain_not_allowed" }
+          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) }
+          end
+        end
+
+        def cmd_evaluate(req)
+          with_page(req[:name]) { |session| { ok: true, result: session.page.evaluate(req[:expression]) } }
+        end
+
+        def cmd_fill(req)
+          with_page(req[:name]) do |session|
+            sel = resolve_selector_from(session, req)
+            return sel if sel.is_a?(Hash)
+
+            type_into(session.page, sel, req[:value])
+          end
+        end
+
+        def cmd_click(req)
+          with_page(req[:name]) do |session|
+            sel = resolve_selector_from(session, req)
+            return sel if sel.is_a?(Hash)
+
+            click_element(session.page, sel)
+          end
+        end
+
+        def cmd_url(req)
+          with_page(req[:name]) { |session| { ok: true, url: session.page.current_url } }
+        end
+
+        def type_into(page, selector, value)
+          el = page.at_css(selector)
+          return { error: "selector not found: #{selector}" } unless el
+
+          el.focus
+          el.type(value)
+          { ok: true }
+        end
+
+        def click_element(page, selector)
+          el = page.at_css(selector)
+          return { error: "selector not found: #{selector}" } unless el
+
+          el.click
+          { ok: true }
+        end
+
+        def resolve_selector_from(session, req)
+          return req[:selector] if req[:selector]
+          return { error: "selector or ref required" } unless req[:ref]
+
+          session.ref_registry[req[:ref]] || { error: "ref '#{req[:ref]}' not found — run snap first" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Observation
+        private
+
+        def cmd_snapshot(req)
+          with_page(req[:name]) { |session| take_snapshot(session, req[:format], req[:diff]) }
+        end
+
+        def take_snapshot(session, format, diff)
+          nonce     = SecureRandom.hex(8)
+          challenge = Detectors.cloudflare?(session.page)
+
+          return { ok: true, html: session.page.body, challenge: challenge, nonce: nonce } unless format == "elements"
+
+          snapshot = @snapshot_builder.call(session.page)
+          registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
+
+          prev = session.prev_snapshot
+          session.ref_registry  = registry
+          session.prev_snapshot = snapshot
+          result = diff && prev ? compute_diff(prev, snapshot) : snapshot
+
+          { ok: true, snapshot: result, challenge: challenge, nonce: nonce }
+        end
+
+        def compute_diff(prev, current)
+          prev_by_sel = prev.to_h { |el| [el[:selector], el] }
+          current.reject do |el|
+            old = prev_by_sel[el[:selector]]
+            old && old.slice(:text, :attrs) == el.slice(:text, :attrs)
+          end
+        end
+
+        def cmd_screenshot(req)
+          with_page(req[:name]) do |session|
+            path = safe_screenshot_path(req[:path], req[:name])
+            return path if path.is_a?(Hash)
+
+            FileUtils.mkdir_p(File.dirname(path))
+            session.page.screenshot(path: path, full: req.fetch(:full, false))
+            { ok: true, path: path }
+          end
+        end
+
+        def safe_screenshot_path(requested, page_name)
+          return default_screenshot_path(page_name) unless requested
+
+          expanded = File.expand_path(requested)
+          return { error: "invalid extension — use .png, .jpg, or .jpeg" } unless valid_screenshot_ext?(expanded)
+          return { error: "path outside allowed directory (#{SCREENSHOT_DIR} or project directory)" } \
+            unless within_screenshot_roots?(expanded)
+
+          File.join(resolve_dir(File.dirname(expanded)), File.basename(expanded))
+        end
+
+        def valid_screenshot_ext?(path)
+          SCREENSHOT_EXTS.include?(File.extname(path).downcase)
+        end
+
+        def within_screenshot_roots?(path)
+          dir = resolve_dir(File.dirname(path))
+          SCREENSHOT_ROOTS.any? do |root|
+            real_root = resolve_dir(root)
+            dir.start_with?("#{real_root}/") || dir == real_root
+          end
+        end
+
+        def resolve_dir(dir)
+          File.realpath(dir)
+        rescue Errno::ENOENT
+          dir
+        end
+
+        def default_screenshot_path(page_name)
+          name_safe = page_name.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
+          File.join(SCREENSHOT_DIR, "browserctl_shot_#{name_safe}_#{Time.now.to_i}.png")
+        end
+
+        def cmd_wait_for(req)
+          with_page(req[:name]) do |session|
+            wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 10).to_f)
+          end
+        end
+
+        def cmd_watch(req)
+          with_page(req[:name]) do |session|
+            result = wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 30).to_f)
+            result[:error] ? result : { ok: true, selector: req[:selector] }
+          end
+        end
+
+        def wait_for_selector(page, selector, timeout)
+          deadline = Time.now + timeout
+          loop do
+            found = page.at_css(selector)
+            break { ok: true } if found
+            if Time.now >= deadline
+              break { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" }
+            end
+
+            sleep 0.2
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module PageLifecycle
+        private
+
+        def cmd_open_page(req)
+          session = @global_mutex.synchronize do
+            @pages[req[:name]] ||= PageSession.new(@browser.create_page)
+          end
+          session.page.go_to(req[:url]) if req[:url]
+          { ok: true, name: req[:name] }
+        end
+
+        def cmd_close_page(req)
+          session = @global_mutex.synchronize { @pages.delete(req[:name]) }
+          session&.page&.close
+          { ok: true }
+        end
+
+        def cmd_list_pages(_req)
+          { pages: @global_mutex.synchronize { @pages.keys } }
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server.rb

@@ -21,6 +21,7 @@ module Browserctl
     end
 
     def run
+      guard_already_running!
       write_pid
       server, idle = setup_server
       serve(server)
@@ -61,12 +62,27 @@ module Browserctl
 
     def setup_socket
       FileUtils.rm_f(@socket_path)
+      old_umask = File.umask(0o177)
       server = UNIXServer.new(@socket_path)
-      File.chmod(0o600, @socket_path)
-      Browserctl.logger.info "listening on #{@socket_path}"
+      File.umask(old_umask)
+      Browserctl.logger.info "daemon ready — listening on #{@socket_path}"
       server
     end
 
+    def guard_already_running!
+      return unless File.exist?(@pid_path)
+
+      pid = File.read(@pid_path).strip.to_i
+      return unless pid.positive?
+
+      Process.kill(0, pid)
+      abort "browserd already running (PID #{pid}). Use 'browserctl shutdown' first."
+    rescue Errno::ESRCH
+      # Dead process — stale PID file, safe to continue
+    rescue Errno::EPERM
+      abort "browserd (PID #{pid}) is running as a different user. Remove #{@pid_path} manually if stale."
+    end
+
     def serve(server)
       loop do
         client = server.accept

data/lib/browserctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Browserctl
-  VERSION = "0.3.1"
+  VERSION = "0.5.0"
 end

data/lib/browserctl/workflow.rb

@@ -18,6 +18,20 @@ module Browserctl
       @client = client
     end
 
+    def store(key, value)
+      res = @client.store(key.to_s, value)
+      raise WorkflowError, res[:error] if res[:error]
+
+      value
+    end
+
+    def fetch(key)
+      res = @client.fetch(key.to_s)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res[:value]
+    end
+
     def method_missing(name, *args)
       return @params[name] if @params.key?(name)
 
@@ -32,6 +46,20 @@ module Browserctl
       PageProxy.new(name.to_s, @client)
     end
 
+    def open_page(page_name, url: nil)
+      res = @client.open_page(page_name.to_s, url: url)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
+    def close_page(page_name)
+      res = @client.close_page(page_name.to_s)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
     def invoke(workflow_name, **override_params)
       name = workflow_name.to_s
       guard_circular!(name)
@@ -77,6 +105,7 @@ module Browserctl
     def click(sel)       = unwrap @client.click(@name, sel)
     def snapshot(**) = unwrap @client.snapshot(@name, **)
     def screenshot(**) = unwrap @client.screenshot(@name, **)
+    def watch(sel, timeout: 30)    = unwrap @client.watch(@name, sel, timeout: timeout)
     def wait_for(sel, timeout: 10) = unwrap @client.wait_for(@name, sel, timeout: timeout)
     def url              = @client.url(@name)[:url]
     def evaluate(expr)   = @client.evaluate(@name, expr)[:result]
@@ -113,7 +142,7 @@ module Browserctl
     end
 
     def compose(workflow_name)
-      source = REGISTRY[workflow_name.to_s]
+      source = Browserctl.lookup_workflow(workflow_name.to_s)
       raise WorkflowError, "workflow '#{workflow_name}' not found for composition" unless source
 
       @steps.concat(source.steps)
@@ -163,11 +192,20 @@ module Browserctl
     end
   end
 
-  REGISTRY = {} # rubocop:disable Style/MutableConstant
+  @registry_mutex = Mutex.new
+  @registry = {}
 
   def self.workflow(name, &)
     defn = WorkflowDefinition.new(name.to_s)
     defn.instance_exec(&)
-    REGISTRY[name.to_s] = defn
+    @registry_mutex.synchronize { @registry[name.to_s] = defn }
+  end
+
+  def self.lookup_workflow(name)
+    @registry_mutex.synchronize { @registry[name.to_s] }
+  end
+
+  def self.registry_snapshot
+    @registry_mutex.synchronize { @registry.dup }
   end
 end

data/lib/browserctl.rb

@@ -2,14 +2,24 @@
 
 require_relative "browserctl/version"
 require_relative "browserctl/constants"
+require_relative "browserctl/errors"
 require_relative "browserctl/workflow"
 require_relative "browserctl/runner"
 require_relative "browserctl/client"
 
 module Browserctl
-  PLUGIN_COMMANDS = {} # rubocop:disable Style/MutableConstant
+  @plugin_commands_mutex = Mutex.new
+  @plugin_commands = {}
 
   def self.register_command(name, &block)
-    PLUGIN_COMMANDS[name.to_s] = block
+    @plugin_commands_mutex.synchronize { @plugin_commands[name.to_s] = block }
+  end
+
+  def self.lookup_plugin_command(name)
+    @plugin_commands_mutex.synchronize { @plugin_commands[name.to_s] }
+  end
+
+  def self.plugin_commands_snapshot
+    @plugin_commands_mutex.synchronize { @plugin_commands.dup }
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -52,6 +52,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: lefthook
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -111,6 +139,8 @@ files:
 - bin/browserd
 - bin/setup
 - examples/cloudflare_hitl.rb
+- examples/smoke/params_file.rb
+- examples/smoke/store_fetch.rb
 - examples/the_internet/add_remove_elements.rb
 - examples/the_internet/checkboxes.rb
 - examples/the_internet/dropdown.rb
@@ -120,21 +150,35 @@ files:
 - lib/browserctl/client.rb
 - lib/browserctl/commands/cli_output.rb
 - lib/browserctl/commands/click.rb
+- lib/browserctl/commands/export_cookies.rb
 - lib/browserctl/commands/fill.rb
+- lib/browserctl/commands/import_cookies.rb
 - lib/browserctl/commands/init.rb
 - lib/browserctl/commands/inspect.rb
 - lib/browserctl/commands/open_page.rb
-- lib/browserctl/commands/pause_resume.rb
+- lib/browserctl/commands/pause.rb
 - lib/browserctl/commands/record.rb
+- lib/browserctl/commands/resume.rb
 - lib/browserctl/commands/screenshot.rb
 - lib/browserctl/commands/snapshot.rb
+- lib/browserctl/commands/status.rb
 - lib/browserctl/commands/watch.rb
 - lib/browserctl/constants.rb
+- lib/browserctl/detectors.rb
+- lib/browserctl/errors.rb
 - lib/browserctl/logger.rb
+- lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
 - lib/browserctl/runner.rb
 - lib/browserctl/server.rb
 - lib/browserctl/server/command_dispatcher.rb
+- lib/browserctl/server/handlers/cookies.rb
+- lib/browserctl/server/handlers/daemon_control.rb
+- lib/browserctl/server/handlers/devtools.rb
+- lib/browserctl/server/handlers/hitl.rb
+- lib/browserctl/server/handlers/navigation.rb
+- lib/browserctl/server/handlers/observation.rb
+- lib/browserctl/server/handlers/page_lifecycle.rb
 - lib/browserctl/server/idle_watcher.rb
 - lib/browserctl/server/page_session.rb
 - lib/browserctl/server/snapshot_builder.rb
@@ -157,7 +201,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="