browserctl 0.5.0 → 0.6.0

data/lib/browserctl/commands/session.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Session
+      extend CliOutput
+
+      USAGE = "Usage: browserctl session <save|load|list|delete|export|import> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "save"   then run_save(client, args)
+        when "load"   then run_load(client, args)
+        when "list"   then run_list(client)
+        when "delete" then run_delete(client, args)
+        when "export" then run_export(args)
+        when "import" then run_import(args)
+        else abort "unknown session subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_save(client, args)
+        name = args.shift or abort "usage: browserctl session save <name>"
+        print_result(client.session_save(name))
+      end
+
+      def self.run_load(client, args)
+        name = args.shift or abort "usage: browserctl session load <name>"
+        print_result(client.session_load(name))
+      end
+
+      def self.run_list(client)
+        print_result(client.session_list)
+      end
+
+      def self.run_delete(client, args)
+        name = args.shift or abort "usage: browserctl session delete <name>"
+        print_result(client.session_delete(name))
+      end
+
+      def self.run_export(args)
+        name = args.shift or abort "usage: browserctl session export <name> <path>"
+        dest = args.shift or abort "usage: browserctl session export <name> <path>"
+        session_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions", name)
+        abort "session '#{name}' not found" unless Dir.exist?(session_dir)
+
+        dest = File.expand_path(dest)
+        pid = Process.spawn("zip", "-r", dest, name, chdir: File.join(Browserctl::BROWSERCTL_DIR, "sessions"))
+        Process.wait(pid)
+        puts({ ok: true, path: dest }.to_json)
+      end
+
+      def self.run_import(args)
+        zip_path = args.shift or abort "usage: browserctl session import <path>"
+        zip_path = File.expand_path(zip_path)
+        abort "zip file not found: #{zip_path}" unless File.exist?(zip_path)
+
+        sessions_dir = File.join(Browserctl::BROWSERCTL_DIR, "sessions")
+        FileUtils.mkdir_p(sessions_dir)
+        pid = Process.spawn("unzip", "-o", zip_path, "-d", sessions_dir)
+        Process.wait(pid)
+        puts({ ok: true }.to_json)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/snapshot.rb

@@ -10,11 +10,11 @@ module Browserctl
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl snap <page> [--format elements|html] [--diff]"
+          banner "Usage: browserctl snapshot <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 elements|html] [--diff]"
+        name = args.shift or abort "usage: browserctl snapshot <page> [--format elements|html] [--diff]"
         unless VALID_FORMATS.include?(opts[:format])
           warn "Error: --format must be one of: #{VALID_FORMATS.join(', ')}"
           exit 1

data/lib/browserctl/commands/storage.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Storage
+      extend CliOutput
+
+      USAGE = "Usage: browserctl storage <get|set|export|import|delete> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "get"    then run_get(client, args)
+        when "set"    then run_set(client, args)
+        when "export" then run_export(client, args)
+        when "import" then run_import(client, args)
+        when "delete" then run_delete(client, args)
+        else abort "unknown storage subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_get(client, args)
+        page  = args.shift or abort "usage: browserctl storage get <page> <key> [--store local|session]"
+        key   = args.shift or abort "usage: browserctl storage get <page> <key> [--store local|session]"
+        store = extract_opt(args, "--store") || "local"
+        print_result(client.storage_get(page, key, store: store))
+      end
+
+      def self.run_set(client, args)
+        page  = args.shift or abort "usage: browserctl storage set <page> <key> <value> [--store local|session]"
+        key   = args.shift or abort "usage: browserctl storage set <page> <key> <value> [--store local|session]"
+        value = args.shift or abort "usage: browserctl storage set <page> <key> <value> [--store local|session]"
+        store = extract_opt(args, "--store") || "local"
+        print_result(client.storage_set(page, key, value, store: store))
+      end
+
+      def self.run_export(client, args)
+        page  = args.shift or abort "usage: browserctl storage export <page> <path> [--store local|session|all]"
+        path  = args.shift or abort "usage: browserctl storage export <page> <path> [--store local|session|all]"
+        store = extract_opt(args, "--store") || "all"
+        print_result(client.storage_export(page, path, stores: store))
+      end
+
+      def self.run_import(client, args)
+        page = args.shift or abort "usage: browserctl storage import <page> <path>"
+        path = args.shift or abort "usage: browserctl storage import <page> <path>"
+        print_result(client.storage_import(page, path))
+      end
+
+      def self.run_delete(client, args)
+        page  = args.shift or abort "usage: browserctl storage delete <page> [--store local|session|all]"
+        store = extract_opt(args, "--store") || "all"
+        print_result(client.storage_delete(page, stores: store))
+      end
+
+      def self.extract_opt(args, flag)
+        idx = args.index(flag)
+        return nil unless idx
+
+        args.delete_at(idx)
+        args.delete_at(idx)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/workflow.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Workflow
+      extend CliOutput
+
+      USAGE = "Usage: browserctl workflow <run|list|describe> [args]"
+
+      def self.run(runner, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "run"      then run_workflow(runner, args)
+        when "list"     then run_list(runner)
+        when "describe" then run_describe(runner, args)
+        else abort "unknown workflow subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_workflow(runner, args)
+        name = args.shift or abort "usage: browserctl workflow run <name|file> [--params file] [--key value ...]"
+        if File.exist?(name)
+          before = Browserctl.registry_snapshot.keys
+          load File.expand_path(name)
+          name = (Browserctl.registry_snapshot.keys - before).first || File.basename(name, ".rb")
+        end
+
+        params_file_idx = args.index("--params")
+        file_params = {}
+        if params_file_idx
+          params_path = args.delete_at(params_file_idx + 1)
+          args.delete_at(params_file_idx)
+          begin
+            file_params = Browserctl::Runner.load_params_file(params_path)
+          rescue StandardError => e
+            abort "Error loading params file: #{e.message}"
+          end
+        end
+
+        cli_params = {}
+        args.each_slice(2) do |flag, val|
+          key = flag.sub(/\A--/, "").to_sym
+          cli_params[key] = val
+        end
+
+        params = file_params.merge(cli_params)
+        success = runner.run_workflow(name, **params)
+        exit(success ? 0 : 1)
+      end
+
+      def self.run_list(runner)
+        list = runner.list_workflows
+        list.each { |w| puts "#{w[:name].ljust(24)} #{w[:desc]}" }
+      end
+
+      def self.run_describe(runner, args)
+        name = args.shift or abort "usage: browserctl workflow describe <name>"
+        puts JSON.pretty_generate(runner.describe_workflow(name))
+      end
+    end
+  end
+end

data/lib/browserctl/constants.rb

@@ -5,7 +5,7 @@ module 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"
+  PROTOCOL_VERSION = "2"
 
   def self.socket_path(name = nil)
     File.join(BROWSERCTL_DIR, name ? "#{name}.sock" : "browserd.sock")
@@ -19,6 +19,25 @@ module Browserctl
     File.join(BROWSERCTL_DIR, name ? "#{name}.log" : "browserd.log")
   end
 
+  # Returns nil when the default (unnamed) slot is free; otherwise returns "d1", "d2", etc.
+  def self.next_daemon_name
+    return nil unless File.exist?(socket_path)
+
+    1.upto(99) do |i|
+      return "d#{i}" unless File.exist?(socket_path("d#{i}"))
+    end
+    raise "too many running daemons (limit: 99)"
+  end
+
+  def self.all_daemon_sockets
+    Dir[File.join(BROWSERCTL_DIR, "*.sock")]
+  end
+
+  def self.all_daemon_names
+    all_daemon_sockets.map { |f| File.basename(f, ".sock") }
+                      .map { |n| n == "browserd" ? nil : n }
+  end
+
   # Backward-compatible constants
   SOCKET_PATH = socket_path
   PID_PATH    = pid_path

data/lib/browserctl/logger.rb

@@ -18,10 +18,10 @@ module Browserctl
 
     # 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 debug(msg = nil, &) = @loggers.each { |l| l.debug(msg, &) rescue nil }
+    def info(msg = nil, &)  = @loggers.each { |l| l.info(msg, &)  rescue nil }
+    def warn(msg = nil, &)  = @loggers.each { |l| l.warn(msg, &)  rescue nil }
+    def error(msg = nil, &) = @loggers.each { |l| l.error(msg, &) rescue nil }
 
     def level = @loggers.first&.level
 

data/lib/browserctl/recording.rb

@@ -11,7 +11,7 @@ module Browserctl
     RECORDINGS_DIR = File.join(Dir.tmpdir, "browserctl-recordings")
     STATE_FILE     = File.expand_path("~/.browserctl/active_recording")
 
-    RECORDABLE = %w[open_page goto fill click screenshot evaluate].freeze
+    RECORDABLE = %w[page_open navigate fill click screenshot evaluate].freeze
 
     SENSITIVE_PARAM_PATTERN = /\A(token|key|secret|auth|code|access_token|api_key|client_secret|state)\z/ix
 
@@ -127,8 +127,8 @@ module Browserctl
 
         page = cmd[:name]
         case cmd[:cmd]
-        when "open_page"  then ["open #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
-        when "goto"       then ["goto #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
+        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}"]
@@ -153,7 +153,7 @@ module Browserctl
 
       def prepare_attrs(cmd, attrs)
         attrs = attrs.except(:value) if cmd == "fill"
-        attrs[:url] = redact_url(attrs[:url]) if %w[goto open_page].include?(cmd) && attrs[:url]
+        attrs[:url] = redact_url(attrs[:url]) if %w[navigate page_open].include?(cmd) && attrs[:url]
         attrs
       end
 

data/lib/browserctl/server/command_dispatcher.rb

@@ -9,6 +9,8 @@ require_relative "handlers/cookies"
 require_relative "handlers/hitl"
 require_relative "handlers/devtools"
 require_relative "handlers/daemon_control"
+require_relative "handlers/storage"
+require_relative "handlers/session"
 require_relative "../detectors"
 require_relative "../policy"
 
@@ -21,31 +23,42 @@ module Browserctl
     include Handlers::Hitl
     include Handlers::DevTools
     include Handlers::DaemonControl
+    include Handlers::Storage
+    include Handlers::Session
 
     COMMAND_MAP = {
-      "open_page" => :cmd_open_page,
-      "close_page" => :cmd_close_page,
-      "list_pages" => :cmd_list_pages,
-      "goto" => :cmd_goto,
+      "page_open" => :cmd_page_open,
+      "page_close" => :cmd_page_close,
+      "page_list" => :cmd_page_list,
+      "page_focus" => :cmd_page_focus,
+      "navigate" => :cmd_navigate,
+      "wait" => :cmd_wait,
       "snapshot" => :cmd_snapshot,
       "evaluate" => :cmd_evaluate,
       "fill" => :cmd_fill,
       "click" => :cmd_click,
       "screenshot" => :cmd_screenshot,
-      "wait_for" => :cmd_wait_for,
-      "watch" => :cmd_watch,
       "url" => :cmd_url,
       "ping" => :cmd_ping,
       "shutdown" => :cmd_shutdown,
       "pause" => :cmd_pause,
       "resume" => :cmd_resume,
-      "inspect" => :cmd_inspect,
+      "devtools" => :cmd_devtools,
       "cookies" => :cmd_cookies,
       "set_cookie" => :cmd_set_cookie,
-      "clear_cookies" => :cmd_clear_cookies,
+      "delete_cookies" => :cmd_delete_cookies,
       "import_cookies" => :cmd_import_cookies,
       "store" => :cmd_store,
-      "fetch" => :cmd_fetch
+      "fetch" => :cmd_fetch,
+      "storage_get" => :cmd_storage_get,
+      "storage_set" => :cmd_storage_set,
+      "storage_export" => :cmd_storage_export,
+      "storage_import" => :cmd_storage_import,
+      "storage_delete" => :cmd_storage_delete,
+      "session_save" => :cmd_session_save,
+      "session_load" => :cmd_session_load,
+      "session_list" => :cmd_session_list,
+      "session_delete" => :cmd_session_delete
     }.freeze
 
     SCREENSHOT_DIR   = File.expand_path("~/.browserctl/screenshots").freeze

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

@@ -27,7 +27,7 @@ module Browserctl
           { ok: true }
         end
 
-        def cmd_clear_cookies(req)
+        def cmd_delete_cookies(req)
           session = @global_mutex.synchronize { @pages[req[:name]] }
           return { error: "no page named '#{req[:name]}'" } unless session
 

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

@@ -6,7 +6,7 @@ module Browserctl
       module DevTools
         private
 
-        def cmd_inspect(req)
+        def cmd_devtools(req)
           session = @global_mutex.synchronize { @pages[req[:name]] }
           return { error: "no page named '#{req[:name]}'" } unless session
 

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

@@ -11,7 +11,8 @@ module Browserctl
           return { error: "no page named '#{req[:name]}'" } unless session
 
           session.mutex.synchronize { session.pause! }
-          { ok: true, paused: true }
+          Browserctl.logger.info("HITL pause: #{req[:message]}") if req[:message]
+          { ok: true, paused: true, message: req[:message] }
         end
 
         def cmd_resume(req)

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

@@ -6,7 +6,7 @@ module Browserctl
       module Navigation
         private
 
-        def cmd_goto(req)
+        def cmd_navigate(req)
           unless Policy.allowed_navigation?(req[:url].to_s)
             return { error: "navigation to '#{req[:url]}' blocked by domain policy", code: "domain_not_allowed" }
           end
@@ -17,6 +17,13 @@ module Browserctl
           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[: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]) } }
         end
@@ -48,6 +55,7 @@ module Browserctl
           return { error: "selector not found: #{selector}" } unless el
 
           el.focus
+          el.evaluate("this.select()")
           el.type(value)
           { ok: true }
         end
@@ -56,7 +64,10 @@ module Browserctl
           el = page.at_css(selector)
           return { error: "selector not found: #{selector}" } unless el
 
-          el.click
+          # Use the DOM native click() so JS-only event listeners fire.
+          # CDP mouse simulation (el.click) dispatches events at screen coordinates
+          # and misses handlers on elements with no form submit chain.
+          el.evaluate("this.click()")
           { ok: true }
         end
 
@@ -66,6 +77,17 @@ module Browserctl
 
           session.ref_registry[req[:ref]] || { error: "ref '#{req[:ref]}' not found — run snap first" }
         end
+
+        def wait_for_selector(page, selector, timeout)
+          deadline = Time.now + timeout
+          loop do
+            found = page.at_css(selector)
+            break { ok: true } if found
+            break { error: "wait timeout: selector '#{selector}' not found after #{timeout}s" } if Time.now >= deadline
+
+            sleep 0.2
+          end
+        end
       end
     end
   end

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

@@ -81,32 +81,6 @@ module Browserctl
           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

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

@@ -6,7 +6,7 @@ module Browserctl
       module PageLifecycle
         private
 
-        def cmd_open_page(req)
+        def cmd_page_open(req)
           session = @global_mutex.synchronize do
             @pages[req[:name]] ||= PageSession.new(@browser.create_page)
           end
@@ -14,15 +14,22 @@ module Browserctl
           { ok: true, name: req[:name] }
         end
 
-        def cmd_close_page(req)
+        def cmd_page_close(req)
           session = @global_mutex.synchronize { @pages.delete(req[:name]) }
           session&.page&.close
           { ok: true }
         end
 
-        def cmd_list_pages(_req)
+        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

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