browserctl 0.2.0 → 0.3.0

data/lib/browserctl/commands/pause_resume.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    module PauseResume
+      extend CliOutput
+
+      def self.pause(client, args)
+        name = args.shift or abort "usage: browserctl pause <page>"
+        res = client.pause(name)
+        if res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        puts "Page '#{name}' paused. Browser is live — interact freely."
+        puts "When done: browserctl resume #{name}"
+      end
+
+      def self.resume(client, args)
+        name = args.shift or abort "usage: browserctl resume <page>"
+        res = client.resume(name)
+        if res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        puts "Page '#{name}' resumed."
+      end
+    end
+  end
+end

data/lib/browserctl/commands/record.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "optimist"
 require "browserctl/recording"
 
 module Browserctl
   module Commands
     class Record
-      USAGE = "usage: browserctl record start <name> | stop [--out path] | status"
+      USAGE = "Usage: browserctl record start <name> | stop [--out PATH] | status"
 
       def self.run(args)
         subcmd = args.shift
@@ -14,7 +15,8 @@ module Browserctl
         when "start"  then run_start(args)
         when "stop"   then run_stop(args)
         when "status" then run_status
-        else               abort USAGE
+        else
+          abort "#{USAGE}\nRun 'browserctl record <subcommand> --help' for details."
         end
       end
 
@@ -22,6 +24,7 @@ module Browserctl
         private
 
         def run_start(args)
+          Optimist.options(args) { banner "Usage: browserctl record start <name>" }
           name = args.shift or abort "usage: browserctl record start <name>"
           Recording.start(name)
           puts "Recording started: #{name}"
@@ -29,23 +32,15 @@ module Browserctl
         end
 
         def run_stop(args)
-          idx = args.index("--out")
-          out = if idx
-                  args.delete_at(idx)
-                  args.delete_at(idx)
-                end
-          name = Recording.stop
-          if out
-            FileUtils.mkdir_p(File.dirname(out))
-            Recording.generate_workflow(name, output_path: out)
-            puts "Workflow saved: #{out}"
-          else
-            dest_dir  = ".browserctl/workflows"
-            dest_file = File.join(dest_dir, "#{name}.rb")
-            FileUtils.mkdir_p(dest_dir)
-            Recording.generate_workflow(name, output_path: dest_file)
-            puts "Workflow saved: #{dest_file}"
+          opts = Optimist.options(args) do
+            banner "Usage: browserctl record stop [--out PATH]"
+            opt :out, "Output path for workflow file", type: :string, short: "-o"
           end
+          name = Recording.stop
+          out  = opts[:out] || File.join(".browserctl/workflows", "#{name}.rb")
+          FileUtils.mkdir_p(File.dirname(out))
+          Recording.generate_workflow(name, output_path: out)
+          puts "Workflow saved: #{out}"
           puts "Run with: browserctl run #{name}"
         end
 

data/lib/browserctl/commands/screenshot.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class Screenshot
+      extend CliOutput
+
       def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl shot <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]"
-        path = FlagExtractor.extract_opt(args, "--out")
-        full = args.delete("--full") ? true : false
-        puts client.screenshot(name, path: path, full: full).to_json
+        print_result(client.screenshot(name, path: opts[:out], full: opts[:full]))
       end
     end
   end

data/lib/browserctl/commands/snapshot.rb

@@ -1,25 +1,36 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "flag_extractor"
+require "optimist"
 
 module Browserctl
   module Commands
     class Snapshot
+      VALID_FORMATS = %w[ai html].freeze
+
       def self.run(client, args)
-        name   = args.shift or abort "usage: browserctl snap <page> [--format ai|html] [--diff]"
-        format = FlagExtractor.extract_opt(args, "--format") || "ai"
-        diff   = FlagExtractor.extract_flag?(args, "--diff")
-        res    = client.snapshot(name, format: format, diff: diff)
-        output_snapshot(res, format)
+        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"
+          opt :diff,   "Return only changed elements", default: false, short: "-d"
+        end
+        name = args.shift or abort "usage: browserctl snap <page> [--format ai|html] [--diff]"
+        unless VALID_FORMATS.include?(opts[:format])
+          warn "Error: --format must be one of: #{VALID_FORMATS.join(', ')}"
+          exit 1
+        end
+        res = client.snapshot(name, format: opts[:format], diff: opts[:diff])
+        output_snapshot(res, opts[:format])
       end
 
       class << self
         private
 
         def output_snapshot(res, format)
-          return abort res[:error] if res[:error]
-
+          if res[:error]
+            warn "Error: #{res[:error]}"
+            exit 1
+          end
           puts(format == "ai" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
         end
       end

data/lib/browserctl/commands/watch.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class Watch
+      extend CliOutput
+
       def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl watch <page> <selector> [--timeout N]"
+          opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
+        end
         name     = args.shift
         selector = args.shift
-        timeout  = (FlagExtractor.extract_opt(args, "--timeout") || 30).to_f
         abort "usage: browserctl watch <page> <selector> [--timeout N]" unless name && selector
-        puts client.watch(name, selector, timeout: timeout).to_json
+        unless opts[:timeout].positive?
+          warn "Error: --timeout must be a positive number"
+          exit 1
+        end
+        print_result(client.watch(name, selector, timeout: opts[:timeout]))
       end
     end
   end

data/lib/browserctl/recording.rb

@@ -39,6 +39,8 @@ module Browserctl
       # ref-based interactions have no replayable selector — skip them
       return if %w[click fill].include?(cmd.to_s) && attrs[:selector].nil?
 
+      attrs = attrs.except(:value) if cmd.to_s == "fill"
+
       File.open(log_path(name), "a") do |f|
         f.puts JSON.generate({ cmd: cmd.to_s }.merge(attrs.transform_keys(&:to_s)))
       end
@@ -90,7 +92,7 @@ module Browserctl
           ["goto #{page}", "page(:#{page}).goto(#{cmd[:url].inspect})"]
         when "fill"
           ["fill #{cmd[:selector]} on #{page}",
-           "page(:#{page}).fill(#{cmd[:selector].inspect}, #{cmd[:value].inspect})"]
+           "page(:#{page}).fill(#{cmd[:selector].inspect}, params[:fill_value])"]
         when "click"
           ["click #{cmd[:selector]} on #{page}",
            "page(:#{page}).click(#{cmd[:selector].inspect})"]

data/lib/browserctl/runner.rb

@@ -10,6 +10,11 @@ module Browserctl
       File.expand_path("~/.browserctl/workflows")
     ].freeze
 
+    # Runs a named workflow with the given parameters.
+    # @param name [String] workflow name (must match /\A[a-zA-Z0-9_-]+\z/)
+    # @param params [Hash] keyword arguments passed to the workflow
+    # @return [Boolean] true if all steps succeeded
+    # @raise [WorkflowError] if the name is invalid or a step fails
     def run_workflow(name, **params)
       defn    = fetch_workflow(name)
       results = defn.call(params, Client.new)
@@ -17,19 +22,33 @@ module Browserctl
       results.all?(&:ok)
     end
 
+    # Lists all registered workflows from the standard search paths.
+    # @return [Array<Hash>] array of `{ name:, desc: }` hashes
     def list_workflows
       load_all_workflows
       REGISTRY.map { |name, defn| { name: name, desc: defn.description } }
     end
 
+    # Returns detailed information about a workflow.
+    # @param name [String] workflow name
+    # @return [Hash] `{ name:, desc:, params:, steps: }`
     def describe_workflow(name)
       defn = fetch_workflow(name)
       { name: defn.name, desc: defn.description, params: format_params(defn), steps: defn.steps.map(&:label) }
     end
 
+    SAFE_WORKFLOW_NAME = /\A[a-zA-Z0-9_-]+\z/
+
     private
 
+    def validate_name!(name)
+      return if SAFE_WORKFLOW_NAME.match?(name.to_s)
+
+      raise Browserctl::WorkflowError, "invalid workflow name: #{name.inspect} — use letters, digits, _ and - only"
+    end
+
     def fetch_workflow(name)
+      validate_name!(name)
       load_workflow_file(name)
       REGISTRY[name.to_s] || raise("workflow '#{name}' not found")
     end

data/lib/browserctl/server/command_dispatcher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "snapshot_builder"
+require_relative "page_session"
 
 module Browserctl
   class CommandDispatcher
@@ -18,68 +19,92 @@ module Browserctl
       "watch" => :cmd_watch,
       "url" => :cmd_url,
       "ping" => :cmd_ping,
-      "shutdown" => :cmd_shutdown
+      "shutdown" => :cmd_shutdown,
+      "pause" => :cmd_pause,
+      "resume" => :cmd_resume,
+      "inspect" => :cmd_inspect,
+      "cookies" => :cmd_cookies,
+      "set_cookie" => :cmd_set_cookie,
+      "clear_cookies" => :cmd_clear_cookies
     }.freeze
 
-    def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new, mutex: Mutex.new)
-      @pages          = pages
-      @browser        = browser
-      @snapshot       = snapshot_builder
-      @mutex          = mutex
-      @ref_registries = {}
-      @prev_snapshots = {}
+    SCREENSHOT_DIR  = File.expand_path("~/.browserctl/screenshots").freeze
+    SCREENSHOT_EXTS = %w[.png .jpg .jpeg].freeze
+    CLOUDFLARE_SIGNALS = [
+      "cf-challenge-running",
+      "cf_chl_opt",
+      "__cf_chl_f_tk",
+      "Just a moment..."
+    ].freeze
+
+    def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new, global_mutex: Mutex.new)
+      @pages            = pages
+      @browser          = browser
+      @snapshot_builder = snapshot_builder
+      @global_mutex     = global_mutex
     end
 
     def dispatch(req)
       handler = COMMAND_MAP[req[:cmd]]
-      return { error: "unknown command: #{req[:cmd]}" } unless handler
+      if handler
+        Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
+        return send(handler, req)
+      end
+
+      if (plugin = Browserctl::PLUGIN_COMMANDS[req[:cmd]])
+        Browserctl.logger.debug("plugin:#{req[:cmd]} #{req[:name]}")
+        session = req[:name] ? @global_mutex.synchronize { @pages[req[:name]] } : nil
+        return plugin.call(session, req)
+      end
 
-      Browserctl.logger.debug("#{req[:cmd]} #{req[:name]}")
-      send(handler, req)
+      { error: "unknown command: #{req[:cmd]}" }
     end
 
     private
 
     def cmd_open_page(req)
-      page = @mutex.synchronize { @pages[req[:name]] ||= @browser.create_page }
-      page.go_to(req[:url]) if req[:url]
+      session = @global_mutex.synchronize do
+        @pages[req[:name]] ||= PageSession.new(@browser.create_page)
+      end
+      session.page.go_to(req[:url]) if req[:url]
       { ok: true, name: req[:name] }
     end
 
     def cmd_close_page(req)
-      @mutex.synchronize { @pages.delete(req[:name]) }&.close
+      session = @global_mutex.synchronize { @pages.delete(req[:name]) }
+      session&.page&.close
       { ok: true }
     end
 
     def cmd_list_pages(_req)
-      { pages: @mutex.synchronize { @pages.keys } }
+      { pages: @global_mutex.synchronize { @pages.keys } }
     end
 
     def cmd_goto(req)
-      with_page(req[:name]) do |p|
-        p.go_to(req[:url])
-        { ok: true, url: p.current_url }
+      with_page(req[:name]) do |session|
+        session.page.go_to(req[:url])
+        { ok: true, url: session.page.current_url, challenge: cloudflare_challenge?(session.page) }
       end
     end
 
     def cmd_snapshot(req)
-      with_page(req[:name]) { |p| take_snapshot(req[:name], p, req[:format], req[:diff]) }
+      with_page(req[:name]) { |session| take_snapshot(session, req[:format], req[:diff]) }
     end
 
-    def take_snapshot(name, page, format, diff)
-      return { ok: true, html: page.body } unless format == "ai"
+    def take_snapshot(session, format, diff)
+      challenge = cloudflare_challenge?(session.page)
+
+      return { ok: true, html: session.page.body, challenge: challenge } unless format == "ai"
 
-      snapshot = @snapshot.call(page)
+      snapshot = @snapshot_builder.call(session.page)
       registry = snapshot.to_h { |el| [el[:ref], el[:selector]] }
 
-      result = @mutex.synchronize do
-        prev = @prev_snapshots[name]
-        @ref_registries[name] = registry
-        @prev_snapshots[name] = snapshot
-        diff && prev ? compute_diff(prev, snapshot) : snapshot
-      end
+      prev = session.prev_snapshot
+      session.ref_registry  = registry
+      session.prev_snapshot = snapshot
+      result = diff && prev ? compute_diff(prev, snapshot) : snapshot
 
-      { ok: true, snapshot: result }
+      { ok: true, snapshot: result, challenge: challenge }
     end
 
     def compute_diff(prev, current)
@@ -91,14 +116,16 @@ module Browserctl
     end
 
     def cmd_evaluate(req)
-      with_page(req[:name]) { |p| { ok: true, result: p.evaluate(req[:expression]) } }
+      with_page(req[:name]) { |session| { ok: true, result: session.page.evaluate(req[:expression]) } }
     end
 
     def cmd_fill(req)
-      sel = resolve_selector(req[:name], req)
-      return sel if sel.is_a?(Hash)
+      with_page(req[:name]) do |session|
+        sel = resolve_selector_from(session, req)
+        return sel if sel.is_a?(Hash)
 
-      with_page(req[:name]) { |p| type_into(p, sel, req[:value]) }
+        type_into(session.page, sel, req[:value])
+      end
     end
 
     def type_into(page, selector, value)
@@ -111,10 +138,12 @@ module Browserctl
     end
 
     def cmd_click(req)
-      sel = resolve_selector(req[:name], req)
-      return sel if sel.is_a?(Hash)
+      with_page(req[:name]) do |session|
+        sel = resolve_selector_from(session, req)
+        return sel if sel.is_a?(Hash)
 
-      with_page(req[:name]) { |p| click_element(p, sel) }
+        click_element(session.page, sel)
+      end
     end
 
     def click_element(page, selector)
@@ -126,56 +155,145 @@ module Browserctl
     end
 
     def cmd_screenshot(req)
-      with_page(req[:name]) do |p|
-        path = req[:path] || "/tmp/browserctl_shot_#{req[:name]}_#{Time.now.to_i}.png"
-        p.screenshot(path: path, full: req.fetch(:full, false))
+      with_page(req[:name]) do |session|
+        path = safe_screenshot_path(req[:path], req[:name])
+        return path if path.is_a?(Hash)
+
+        FileUtils.mkdir_p(File.dirname(path))
+        session.page.screenshot(path: path, full: req.fetch(:full, false))
         { ok: true, path: path }
       end
     end
 
+    def safe_screenshot_path(requested, page_name)
+      if requested
+        expanded = File.expand_path(requested)
+        return { error: "path outside allowed directory (#{SCREENSHOT_DIR})" } \
+          unless expanded.start_with?(SCREENSHOT_DIR)
+        return { error: "invalid extension — use .png, .jpg, or .jpeg" } \
+          unless SCREENSHOT_EXTS.include?(File.extname(expanded).downcase)
+
+        expanded
+      else
+        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
+    end
+
     def cmd_wait_for(req)
-      with_page(req[:name]) { |p| wait_for_selector(p, req[:selector], req.fetch(:timeout, 10).to_f) }
+      with_page(req[:name]) { |session| wait_for_selector(session.page, req[:selector], req.fetch(:timeout, 10).to_f) }
     end
 
     def cmd_watch(req)
-      with_page(req[:name]) do |p|
-        result = wait_for_selector(p, req[:selector], req.fetch(:timeout, 30).to_f)
+      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
-      sleep 0.2 until (found = page.at_css(selector)) || Time.now > deadline
-      found ? { ok: true } : { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" }
+      loop do
+        found = page.at_css(selector)
+        break { ok: true } if found
+        break { error: "wait_for timeout: selector '#{selector}' not found after #{timeout}s" } if Time.now >= deadline
+
+        sleep 0.2
+      end
     end
 
     def cmd_url(req)
-      with_page(req[:name]) { |p| { ok: true, url: p.current_url } }
+      with_page(req[:name]) { |session| { ok: true, url: session.page.current_url } }
     end
 
-    def cmd_ping(_req)
-      { ok: true, pid: Process.pid }
+    def cmd_cookies(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      all = session.page.cookies.all
+      { ok: true, cookies: all.values.map(&:to_h) }
+    end
+
+    def cmd_set_cookie(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.page.cookies.set(
+        name: req[:cookie_name],
+        value: req[:value],
+        domain: req[:domain],
+        path: req.fetch(:path, "/")
+      )
+      { ok: true }
     end
 
+    def cmd_clear_cookies(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.page.cookies.clear
+      { ok: true }
+    end
+
+    def cmd_inspect(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      port      = @browser.process.port
+      target_id = session.page.target_id
+      devtools_url = "http://127.0.0.1:#{port}/devtools/inspector.html" \
+                     "?ws=127.0.0.1:#{port}/devtools/page/#{target_id}"
+      { ok: true, devtools_url: devtools_url }
+    end
+
+    def cmd_pause(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.mutex.synchronize { session.pause! }
+      { ok: true, paused: true }
+    end
+
+    def cmd_resume(req)
+      session = @global_mutex.synchronize { @pages[req[:name]] }
+      return { error: "no page named '#{req[:name]}'" } unless session
+
+      session.mutex.synchronize do
+        session.resume!
+        session.pause_cv.signal
+      end
+      { ok: true, paused: false }
+    end
+
+    def cmd_ping(_req) = { ok: true, pid: Process.pid }
+
     def cmd_shutdown(_req)
       Process.kill("INT", Process.pid)
       { ok: true }
     end
 
     def with_page(name)
-      page = @mutex.synchronize { @pages[name] }
-      return { error: "no page named '#{name}'" } unless page
+      session = @global_mutex.synchronize { @pages[name] }
+      return { error: "no page named '#{name}'" } unless session
+
+      session.mutex.synchronize do
+        session.pause_cv.wait(session.mutex) while session.paused?
+        yield session
+      end
+    end
 
-      yield page
+    def cloudflare_challenge?(page)
+      url  = page.current_url.to_s
+      body = page.body.to_s
+      url.include?("challenge-platform") ||
+        CLOUDFLARE_SIGNALS.any? { |sig| body.include?(sig) }
     end
 
-    def resolve_selector(name, req)
+    def resolve_selector_from(session, req)
       return req[:selector] if req[:selector]
       return { error: "selector or ref required" } unless req[:ref]
 
-      sel = @mutex.synchronize { @ref_registries.dig(name, req[:ref]) }
-      sel || { error: "ref '#{req[:ref]}' not found — run snap first" }
+      session.ref_registry[req[:ref]] || { error: "ref '#{req[:ref]}' not found — run snap first" }
     end
   end
 end

data/lib/browserctl/server/page_session.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class PageSession
+    attr_reader :page, :mutex, :pause_cv
+    attr_accessor :ref_registry, :prev_snapshot
+
+    def initialize(page)
+      @page          = page
+      @mutex         = Mutex.new
+      @pause_cv      = ConditionVariable.new
+      @ref_registry  = {}
+      @prev_snapshot = nil
+      @paused        = false
+    end
+
+    def paused? = @paused
+    def pause!  = (@paused = true)
+    def resume! = (@paused = false)
+  end
+end

data/lib/browserctl/server.rb

@@ -9,6 +9,7 @@ require_relative "constants"
 require_relative "logger"
 require_relative "server/command_dispatcher"
 require_relative "server/idle_watcher"
+require_relative "server/page_session"
 
 module Browserctl
   class Server
@@ -16,7 +17,7 @@ module Browserctl
       @socket_path = socket_path
       @pid_path    = pid_path
       prepare_runtime(headless)
-      @dispatcher = CommandDispatcher.new(@pages, @browser, mutex: @mutex)
+      @dispatcher = CommandDispatcher.new(@pages, @browser, global_mutex: @mutex)
     end
 
     def run
@@ -85,7 +86,6 @@ module Browserctl
     def dispatch(socket, line)
       return unless line
 
-      @mutex.synchronize { @last_used = Time.now }
       socket.puts JSON.generate(process(line))
     end
 
@@ -109,7 +109,7 @@ module Browserctl
 
     def quietly
       yield
-    rescue StandardError
+    rescue Exception # rubocop:disable Lint/RescueException
       nil
     end
   end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -112,6 +112,13 @@ module Browserctl
       @steps << StepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
     end
 
+    def compose(workflow_name)
+      source = REGISTRY[workflow_name.to_s]
+      raise WorkflowError, "workflow '#{workflow_name}' not found for composition" unless source
+
+      @steps.concat(source.steps)
+    end
+
     def call(params, client)
       ctx = WorkflowContext.new(resolve_params(params), client)
       execute_steps(ctx)