browserctl 0.5.0 → 0.7.0

data/lib/browserctl/commands/dialog.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Dialog
+      extend CliOutput
+
+      USAGE = "Usage: browserctl dialog <accept|dismiss> <page> [text]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "accept"  then run_accept(client, args)
+        when "dismiss" then run_dismiss(client, args)
+        else abort "unknown dialog subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_accept(client, args)
+        name = args.shift or abort "usage: browserctl dialog accept <page> [text]"
+        text = args.shift
+        print_result(client.dialog_accept(name, text: text))
+      end
+
+      def self.run_dismiss(client, args)
+        name = args.shift or abort "usage: browserctl dialog dismiss <page>"
+        print_result(client.dialog_dismiss(name))
+      end
+    end
+  end
+end

data/lib/browserctl/commands/page.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "optimist"
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Page
+      extend CliOutput
+
+      USAGE = "Usage: browserctl page <open|close|list|focus> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "open"  then run_open(client, args)
+        when "close" then run_close(client, args)
+        when "list"  then run_list(client)
+        when "focus" then run_focus(client, args)
+        else abort "unknown page subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_open(client, args)
+        opts = Optimist.options(args) do
+          opt :url, "URL to navigate to", type: :string, short: "-u"
+        end
+        name = args.shift or abort "usage: browserctl page open <name> [--url URL]"
+        print_result(client.page_open(name, url: opts[:url]))
+      end
+
+      def self.run_close(client, args)
+        name = args.shift or abort "usage: browserctl page close <name>"
+        print_result(client.page_close(name))
+      end
+
+      def self.run_list(client)
+        print_result(client.page_list)
+      end
+
+      def self.run_focus(client, args)
+        name = args.shift or abort "usage: browserctl page focus <name>"
+        print_result(client.page_focus(name))
+      end
+    end
+  end
+end

data/lib/browserctl/commands/record.rb

@@ -43,7 +43,7 @@ module Browserctl
           FileUtils.mkdir_p(File.dirname(out))
           Recording.generate_workflow(name, output_path: out)
           puts "Workflow saved: #{out}"
-          puts "Run with: browserctl run #{name}"
+          puts "Run with: browserctl workflow run #{name}"
         end
 
         def run_status

data/lib/browserctl/commands/screenshot.rb

@@ -10,11 +10,11 @@ module Browserctl
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl shot <page> [--out PATH] [--full]"
+          banner "Usage: browserctl screenshot <page> [--out PATH] [--full]"
           opt :out,  "Output file path",   type: :string, short: "-o"
           opt :full, "Capture full page",  default: false, short: "-f"
         end
-        name = args.shift or abort "usage: browserctl shot <page> [--out PATH] [--full]"
+        name = args.shift or abort "usage: browserctl screenshot <page> [--out PATH] [--full]"
         print_result(client.screenshot(name, path: opts[:out], full: opts[:full]))
       end
     end

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,9 @@ 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 "handlers/interaction"
 require_relative "../detectors"
 require_relative "../policy"
 
@@ -21,31 +24,49 @@ module Browserctl
     include Handlers::Hitl
     include Handlers::DevTools
     include Handlers::DaemonControl
+    include Handlers::Storage
+    include Handlers::Session
+    include Handlers::Interaction
 
     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,
+      "press" => :cmd_press,
+      "hover" => :cmd_hover,
+      "upload" => :cmd_upload,
+      "select" => :cmd_select,
+      "dialog_accept" => :cmd_dialog_accept,
+      "dialog_dismiss" => :cmd_dialog_dismiss,
+      "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/interaction.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      module Interaction
+        private
+
+        def cmd_press(req)
+          with_page(req[:name]) do |session|
+            session.page.keyboard.down(req[:key])
+            session.page.keyboard.up(req[:key])
+            { ok: true }
+          end
+        end
+
+        def cmd_hover(req)
+          with_page(req[:name]) do |session|
+            coords = session.page.evaluate(
+              "(function(sel) {   " \
+              "var el = document.querySelector(sel);   " \
+              "if (!el) return null;   " \
+              "var r = el.getBoundingClientRect();   " \
+              "return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; " \
+              "})(#{req[:selector].to_json})"
+            )
+            return { error: "selector not found: #{req[:selector]}" } unless coords
+
+            session.page.mouse.move(x: coords["x"], y: coords["y"])
+            { ok: true }
+          end
+        end
+
+        def cmd_upload(req)
+          path = File.expand_path(req[:path])
+          return { error: "file not found: #{path}" } unless File.exist?(path)
+
+          with_page(req[:name]) do |session|
+            el = session.page.at_css(req[:selector])
+            return { error: "selector not found: #{req[:selector]}" } unless el
+
+            el.select_file(path)
+            { ok: true }
+          end
+        end
+
+        def cmd_select(req)
+          with_page(req[:name]) do |session|
+            el = session.page.at_css(req[:selector])
+            return { error: "selector not found: #{req[:selector]}" } unless el
+
+            el.evaluate(
+              "this.value = #{req[:value].to_json}; " \
+              "this.dispatchEvent(new Event('change', {bubbles: true}))"
+            )
+            { ok: true }
+          end
+        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)
+          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
+          end
+          { ok: true }
+        end
+      end
+    end
+  end
+end

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