browserctl 0.4.0 → 0.6.0

data/lib/browserctl/commands/daemon.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+require "optimist"
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module Daemon
+      extend CliOutput
+
+      USAGE = "Usage: browserctl daemon <ping|status|start|stop|list> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "ping"   then print_result(client.ping)
+        when "status" then run_status(client)
+        when "start"  then run_start(args)
+        when "stop"   then print_result(client.shutdown)
+        when "list"   then run_list
+        else abort "unknown daemon subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_status(client)
+        ping = client.ping
+        pages = client.page_list[:pages] || []
+        page_info = pages.map do |name|
+          url_res = client.url(name)
+          { name: name, url: url_res[:url] || url_res[:error] }
+        end
+        puts JSON.pretty_generate(
+          daemon: "online",
+          pid: ping[:pid],
+          protocol_version: ping[:protocol_version],
+          pages: page_info
+        )
+      rescue RuntimeError => e
+        raise unless e.message.include?("browserd is not running")
+
+        puts JSON.pretty_generate(daemon: "offline", error: e.message)
+        exit 1
+      end
+
+      def self.run_start(args)
+        opts = Optimist.options(args) do
+          opt :headed, "Run with visible browser", default: false
+          opt :name,   "Daemon name", type: :string
+        end
+        flags = []
+        flags << "--headed" if opts[:headed]
+        flags += ["--name", opts[:name]] if opts[:name]
+        pid = Process.spawn("browserd", *flags, out: File::NULL, err: File::NULL)
+        Process.detach(pid)
+        puts "browserd started (pid #{pid})"
+      end
+
+      def self.run_list
+        sockets = Dir[File.join(Browserctl::BROWSERCTL_DIR, "*.sock")]
+        rows = sockets.map do |sock_path|
+          daemon_name = File.basename(sock_path, ".sock")
+          display_name = daemon_name == "browserd" ? "default" : daemon_name
+          socket_name = daemon_name == "browserd" ? nil : daemon_name
+          client = Browserctl::Client.new(Browserctl.socket_path(socket_name))
+          status = client.ping
+          next unless status&.dig(:ok)
+
+          { name: display_name, pid: status[:pid], pages: (client.page_list[:pages] || []).length }
+        rescue RuntimeError
+          nil
+        end.compact
+        puts({ daemons: rows }.to_json)
+      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.call("page_focus", name: 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

@@ -6,15 +6,15 @@ require "optimist"
 module Browserctl
   module Commands
     class Snapshot
-      VALID_FORMATS = %w[ai html].freeze
+      VALID_FORMATS = %w[elements html].freeze
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl snap <page> [--format ai|html] [--diff]"
-          opt :format, "Output format: ai or html", default: "ai", short: "-f"
+          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 ai|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
@@ -31,7 +31,7 @@ module Browserctl
             warn "Error: #{res[:error]}"
             exit 1
           end
-          puts(format == "ai" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
+          puts(format == "elements" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
         end
       end
     end

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/detectors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Detectors
+    CLOUDFLARE_SIGNALS = [
+      "cf-challenge-running",
+      "cf_chl_opt",
+      "__cf_chl_f_tk",
+      "Just a moment..."
+    ].freeze
+
+    # Returns true if the page appears to be showing a Cloudflare challenge.
+    # Checks both the current URL and the page body for known Cloudflare signals.
+    # @param page [Ferrum::Page] the browser page to inspect
+    # @return [Boolean]
+    def self.cloudflare?(page)
+      url  = page.current_url.to_s
+      body = page.body.to_s
+      url.include?("challenge-platform") ||
+        CLOUDFLARE_SIGNALS.any? { |sig| body.include?(sig) }
+    end
+  end
+end

data/lib/browserctl/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Browserctl
+  # Base error class for all browserctl daemon errors.
+  # Subclasses carry a machine-readable `code` that appears in wire responses.
+  # @attr_reader code [String] machine-readable error code
+  class Error < StandardError
+    def self.default_code = "error"
+
+    attr_reader :code
+
+    def initialize(msg = nil, code: self.class.default_code)
+      @code = code
+      super(msg)
+    end
+  end
+
+  class PageNotFound     < Error; def self.default_code = "page_not_found"     end
+  class SelectorNotFound < Error; def self.default_code = "selector_not_found" end
+  class RefNotFound      < Error; def self.default_code = "ref_not_found"      end
+  class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"   end
+  class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
+  class TimeoutError     < Error; def self.default_code = "timeout"            end
+  class KeyNotFound      < Error; def self.default_code = "key_not_found"      end
+end

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/policy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Browserctl
+  module Policy
+    # Returns true if the URL is permitted by the domain policy.
+    # When BROWSERCTL_ALLOWED_DOMAINS is unset, all URLs are allowed.
+    # @param url [String] the URL to check
+    # @return [Boolean]
+    def self.allowed_navigation?(url)
+      domains = allowed_domains
+      return true if domains.empty?
+
+      host_matches?(URI.parse(url).host, domains)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def self.allowed_domains
+      raw = ENV.fetch("BROWSERCTL_ALLOWED_DOMAINS", nil)
+      return [] unless raw&.match?(/\S/)
+
+      raw.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    def self.host_matches?(host, domains)
+      return false unless host
+
+      normalised = host.downcase
+      domains.any? { |d| normalised == d.downcase || normalised.end_with?(".#{d.downcase}") }
+    end
+
+    private_class_method :allowed_domains, :host_matches?
+  end
+end

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/runner.rb

@@ -27,7 +27,7 @@ module Browserctl
     # @return [Array<Hash>] array of `{ name:, desc: }` hashes
     def list_workflows
       load_all_workflows
-      REGISTRY.map { |name, defn| { name: name, desc: defn.description } }
+      Browserctl.registry_snapshot.map { |name, defn| { name: name, desc: defn.description } }
     end
 
     # Returns detailed information about a workflow.
@@ -67,15 +67,15 @@ module Browserctl
     end
 
     def fetch_workflow(name)
-      return REGISTRY[name.to_s] if REGISTRY.key?(name.to_s)
+      return Browserctl.lookup_workflow(name.to_s) if Browserctl.lookup_workflow(name.to_s)
 
       validate_name!(name)
       load_workflow_file(name)
-      REGISTRY[name.to_s] || raise("workflow '#{name}' not found")
+      Browserctl.lookup_workflow(name.to_s) || raise("workflow '#{name}' not found")
     end
 
     def load_workflow_file(name)
-      return if REGISTRY.key?(name.to_s)
+      return if Browserctl.lookup_workflow(name.to_s)
 
       path = workflow_path(name)
       load path if path