browserctl 0.4.0 → 0.6.0

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module PageLifecycle
+        private
+
+        def cmd_page_open(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_page_close(req)
+          session = @global_mutex.synchronize { @pages.delete(req[:name]) }
+          session&.page&.close
+          { ok: true }
+        end
+
+        def cmd_page_list(_req)
+          { pages: @global_mutex.synchronize { @pages.keys } }
+        end
+
+        def cmd_page_focus(req)
+          with_page(req[:name]) do |session|
+            session.page.activate
+            { ok: true }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../session"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Session
+        private
+
+        def cmd_session_save(req)
+          first_session = @global_mutex.synchronize { @pages.values.first }
+          return { error: "no open pages — open a page before saving a session" } unless first_session
+
+          cookies = first_session.page.cookies.all.values.map(&:to_h)
+
+          pages_meta    = {}
+          local_storage = {}
+          @global_mutex.synchronize { @pages.dup }.each do |page_name, session|
+            session.mutex.synchronize do
+              origin    = session.page.evaluate("location.origin")
+              local_str = session.page.evaluate("JSON.stringify({...localStorage})")
+              pages_meta[page_name] = { url: session.page.current_url, title: session.page.title }
+              local_storage[origin] = JSON.parse(local_str)
+            end
+          end
+
+          now = Time.now.iso8601
+          Browserctl::Session.save(
+            req[:session_name],
+            metadata: { version: 1, name: req[:session_name],
+                        created_at: now, updated_at: now, pages: pages_meta },
+            cookies: cookies,
+            local_storage: local_storage,
+            session_storage: {}
+          )
+          { ok: true, path: Browserctl::Session.path(req[:session_name]),
+            pages: pages_meta.length, cookies: cookies.length }
+        end
+
+        def cmd_session_load(req)
+          data = Browserctl::Session.load(req[:session_name])
+
+          data[:metadata][:pages].each do |page_name, page_data|
+            existing = @global_mutex.synchronize { @pages[page_name.to_s] }
+            if existing
+              existing.page.go_to(page_data[:url])
+            else
+              new_page = @browser.create_page
+              new_page.go_to(page_data[:url])
+              @global_mutex.synchronize { @pages[page_name.to_s] = PageSession.new(new_page) }
+            end
+          end
+
+          seed_session = @global_mutex.synchronize { @pages.values.first }
+          cookie_count = data[:cookies].length
+          data[:cookies].each { |c| seed_session.page.cookies.set(**c.slice(:name, :value, :domain, :path)) }
+
+          ls_key_count = 0
+          data[:local_storage].each do |origin, keys|
+            next if keys.empty?
+
+            tmp_page = @browser.create_page
+            begin
+              tmp_page.go_to(origin)
+              keys.each do |k, v|
+                tmp_page.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
+                ls_key_count += 1
+              end
+            ensure
+              tmp_page.close
+            end
+          end
+
+          { ok: true, cookies: cookie_count, pages: data[:metadata][:pages].length,
+            local_storage_keys: ls_key_count }
+        rescue RuntimeError => e
+          { error: e.message }
+        end
+
+        def cmd_session_list(_req)
+          sessions = Browserctl::Session.all
+          { ok: true, sessions: sessions }
+        end
+
+        def cmd_session_delete(req)
+          Browserctl::Session.delete(req[:session_name])
+          { ok: true }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Storage
+        private
+
+        # Returns { ok: true, value: } or { error: }
+        def cmd_storage_get(req)
+          with_page(req[:name]) do |session|
+            store = req.fetch(:store, "local")
+            js    = storage_js_get(store, req[:key])
+            return { error: "unknown store '#{store}' — use 'local' or 'session'" } unless js
+
+            value = session.page.evaluate(js)
+            { ok: true, value: value }
+          end
+        end
+
+        # Returns { ok: true } or { error: }
+        def cmd_storage_set(req)
+          with_page(req[:name]) do |session|
+            store = req.fetch(:store, "local")
+            js    = storage_js_set(store, req[:key], req[:value])
+            return { error: "unknown store '#{store}' — use 'local' or 'session'" } unless js
+
+            session.page.evaluate(js)
+            { ok: true }
+          end
+        end
+
+        # Exports localStorage and/or sessionStorage to a JSON file.
+        # Returns { ok: true, path:, key_count: } or { error: }
+        def cmd_storage_export(req)
+          with_page(req[:name]) do |session|
+            stores  = req.fetch(:stores, "all")
+            data    = {}
+
+            origin = session.page.evaluate("location.origin")
+            data[origin] = {}
+
+            if %w[local all].include?(stores)
+              local = JSON.parse(session.page.evaluate("JSON.stringify({...localStorage})") || "{}")
+              data[origin].merge!(local)
+            end
+
+            if %w[session all].include?(stores)
+              sess = JSON.parse(session.page.evaluate("JSON.stringify({...sessionStorage})") || "{}")
+              data[origin].merge!(sess)
+            end
+
+            path = File.expand_path(req[:path])
+            FileUtils.mkdir_p(File.dirname(path))
+            File.write(path, JSON.generate(data))
+            { ok: true, path: path, key_count: data[origin].length }
+          end
+        end
+
+        # Imports keys from a JSON file into the page's localStorage only.
+        # sessionStorage keys in the file are ignored (sessionStorage is tab-scoped and not restorable).
+        # Returns { ok: true, origins: N, key_count: M } or { error: }
+        def cmd_storage_import(req)
+          path = File.expand_path(req[:path])
+          return { error: "file not found: #{path}" } unless File.exist?(path)
+
+          data = JSON.parse(File.read(path))
+          return { error: "invalid storage file format" } unless data.is_a?(Hash)
+
+          with_page(req[:name]) do |session|
+            key_count = 0
+            data.each_value do |keys|
+              keys.each do |k, v|
+                session.page.evaluate("localStorage.setItem(#{k.to_json}, #{v.to_json})")
+                key_count += 1
+              end
+            end
+            { ok: true, origins: data.length, key_count: key_count }
+          end
+        end
+
+        # Clears localStorage and/or sessionStorage for the page.
+        # Returns { ok: true } or { error: }
+        def cmd_storage_delete(req)
+          with_page(req[:name]) do |session|
+            stores = req.fetch(:stores, "all")
+            session.page.evaluate("localStorage.clear()")   if %w[local all].include?(stores)
+            session.page.evaluate("sessionStorage.clear()") if %w[session all].include?(stores)
+            { ok: true }
+          end
+        end
+
+        def storage_js_get(store, key)
+          case store
+          when "local"   then "localStorage.getItem(#{key.to_json})"
+          when "session" then "sessionStorage.getItem(#{key.to_json})"
+          end
+        end
+
+        def storage_js_set(store, key, value)
+          case store
+          when "local"   then "localStorage.setItem(#{key.to_json}, #{value.to_json})"
+          when "session" then "sessionStorage.setItem(#{key.to_json}, #{value.to_json})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/server.rb

@@ -62,8 +62,9 @@ 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)
+      File.umask(old_umask)
       Browserctl.logger.info "daemon ready — listening on #{@socket_path}"
       server
     end
@@ -75,7 +76,7 @@ module Browserctl
       return unless pid.positive?
 
       Process.kill(0, pid)
-      abort "browserd already running (PID #{pid}). Use 'browserctl shutdown' first."
+      abort "browserd already running (PID #{pid}). Use 'browserctl daemon stop' first."
     rescue Errno::ESRCH
       # Dead process — stale PID file, safe to continue
     rescue Errno::EPERM
@@ -124,7 +125,7 @@ module Browserctl
 
     def quietly
       yield
-    rescue Exception # rubocop:disable Lint/RescueException
+    rescue Exception
       nil
     end
   end

data/lib/browserctl/session.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require_relative "constants"
+
+module Browserctl
+  class Session
+    BASE_DIR = File.join(BROWSERCTL_DIR, "sessions")
+
+    SAFE_NAME = /\A[a-zA-Z0-9_-]{1,64}\z/
+
+    def self.path(name)    = File.join(BASE_DIR, name)
+    def self.exist?(name)  = Dir.exist?(path(name))
+
+    def self.delete(name)
+      validate_name!(name)
+      FileUtils.rm_rf(path(name))
+    end
+
+    def self.all
+      Dir[File.join(BASE_DIR, "*/metadata.json")].filter_map { |f| load_meta(f) }
+    end
+
+    def self.save(session_name, metadata:, cookies:, local_storage:, session_storage:)
+      validate_name!(session_name)
+      dir = path(session_name)
+      FileUtils.mkdir_p(dir)
+      write_json(File.join(dir, "metadata.json"),     metadata)
+      write_secret(File.join(dir, "cookies.json"),    cookies)
+      write_secret(File.join(dir, "local_storage.json"), local_storage)
+      return if session_storage.empty?
+
+      write_secret(File.join(dir, "session_storage.json"), session_storage)
+    end
+
+    def self.load(session_name)
+      validate_name!(session_name)
+      dir = path(session_name)
+      raise "session '#{session_name}' not found" unless Dir.exist?(dir)
+
+      {
+        metadata: JSON.parse(File.read(File.join(dir, "metadata.json")), symbolize_names: true),
+        cookies: JSON.parse(File.read(File.join(dir, "cookies.json")), symbolize_names: true),
+        local_storage: JSON.parse(File.read(File.join(dir, "local_storage.json")), symbolize_names: false),
+        session_storage: load_session_storage(dir)
+      }
+    end
+
+    def self.load_meta(path)
+      JSON.parse(File.read(path), symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def self.validate_name!(name)
+      return if SAFE_NAME.match?(name.to_s)
+
+      raise ArgumentError, "invalid session name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
+    end
+
+    def self.load_session_storage(dir)
+      ss_path = File.join(dir, "session_storage.json")
+      File.exist?(ss_path) ? JSON.parse(File.read(ss_path), symbolize_names: false) : {}
+    end
+    private_class_method :load_session_storage
+
+    def self.write_json(path, data)
+      File.write(path, JSON.generate(data))
+    end
+    private_class_method :write_json
+
+    # Cookies and storage contain secrets — restrict to owner read/write only.
+    def self.write_secret(path, data)
+      File.open(path, "w", 0o600) { |f| f.write(JSON.generate(data)) }
+    end
+    private_class_method :write_secret
+  end
+end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -16,15 +16,20 @@ module Browserctl
     def initialize(params, client)
       @params = params
       @client = client
-      @_store = {}
     end
 
     def store(key, value)
-      @_store[key] = value
+      res = @client.store(key.to_s, value)
+      raise WorkflowError, res[:error] if res[:error]
+
+      value
     end
 
     def fetch(key)
-      @_store.fetch(key) { raise KeyError, "no value stored for key #{key.inspect}" }
+      res = @client.fetch(key.to_s)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res[:value]
     end
 
     def method_missing(name, *args)
@@ -42,19 +47,37 @@ module Browserctl
     end
 
     def open_page(page_name, url: nil)
-      res = @client.open_page(page_name.to_s, url: url)
+      res = @client.page_open(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)
+      res = @client.page_close(page_name.to_s)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
+    def save_session(session_name)
+      res = @client.session_save(session_name)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
+    def load_session(session_name)
+      res = @client.session_load(session_name)
       raise WorkflowError, res[:error] if res[:error]
 
       res
     end
 
+    def list_sessions
+      @client.session_list[:sessions]
+    end
+
     def invoke(workflow_name, **override_params)
       name = workflow_name.to_s
       guard_circular!(name)
@@ -95,15 +118,24 @@ module Browserctl
       @client = client
     end
 
-    def goto(url)        = unwrap @client.goto(@name, url)
-    def fill(sel, val)   = unwrap @client.fill(@name, sel, val)
-    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]
+    def navigate(url)             = unwrap @client.navigate(@name, url)
+    def fill(sel, val)            = unwrap @client.fill(@name, sel, val)
+    def click(sel)                = unwrap @client.click(@name, sel)
+    def snapshot(**)              = unwrap @client.snapshot(@name, **)
+    def screenshot(**)            = unwrap @client.screenshot(@name, **)
+    def wait(sel, timeout: 30)    = unwrap @client.wait(@name, sel, timeout: timeout)
+    def delete_cookies             = unwrap @client.delete_cookies(@name)
+    def devtools                   = @client.devtools(@name)[:devtools_url]
+    def url                        = @client.url(@name)[:url]
+    def evaluate(expr)             = @client.evaluate(@name, expr)[:result]
+
+    def storage_get(key, store: "local")
+      @client.storage_get(@name, key, store: store)[:value]
+    end
+
+    def storage_set(key, value, store: "local")
+      unwrap @client.storage_set(@name, key, value, store: store)
+    end
 
     private
 
@@ -137,7 +169,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)
@@ -187,11 +219,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.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -58,14 +58,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '2.1'
+- !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
@@ -127,6 +141,12 @@ files:
 - examples/cloudflare_hitl.rb
 - examples/smoke/params_file.rb
 - examples/smoke/store_fetch.rb
+- examples/test_automation_practices/checkboxes.rb
+- examples/test_automation_practices/dynamic_elements.rb
+- examples/test_automation_practices/key_press.rb
+- examples/test_automation_practices/login.rb
+- examples/test_automation_practices/login_negative.rb
+- examples/test_automation_practices/notifications.rb
 - examples/the_internet/add_remove_elements.rb
 - examples/the_internet/checkboxes.rb
 - examples/the_internet/dropdown.rb
@@ -136,28 +156,40 @@ 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/cookie.rb
+- lib/browserctl/commands/daemon.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.rb
+- lib/browserctl/commands/page.rb
 - lib/browserctl/commands/record.rb
 - lib/browserctl/commands/resume.rb
 - lib/browserctl/commands/screenshot.rb
+- lib/browserctl/commands/session.rb
 - lib/browserctl/commands/snapshot.rb
-- lib/browserctl/commands/status.rb
-- lib/browserctl/commands/watch.rb
+- lib/browserctl/commands/storage.rb
+- lib/browserctl/commands/workflow.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/handlers/session.rb
+- lib/browserctl/server/handlers/storage.rb
 - lib/browserctl/server/idle_watcher.rb
 - lib/browserctl/server/page_session.rb
 - lib/browserctl/server/snapshot_builder.rb
+- lib/browserctl/session.rb
 - lib/browserctl/version.rb
 - lib/browserctl/workflow.rb
 homepage: https://github.com/patrick204nqh/browserctl

data/lib/browserctl/commands/export_cookies.rb

@@ -1,18 +0,0 @@
-# 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

@@ -1,23 +0,0 @@
-# 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/inspect.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Browserctl
-  module Commands
-    class Inspect
-      def self.run(client, args)
-        name = args.shift or abort "usage: browserctl inspect <page>"
-        res = client.inspect_page(name)
-        if res[:error]
-          warn "Error: #{res[:error]}"
-          exit 1
-        end
-        url = res[:devtools_url]
-        puts "Opening DevTools for '#{name}':"
-        puts "  #{url}"
-        opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
-        system(opener, url)
-      end
-    end
-  end
-end