browserctl 0.1.0

data/lib/browserctl/commands/click.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class Click
+      def self.run(client, args)
+        name, selector = args
+        abort "usage: browserctl click <page> <selector>" unless name && selector
+        puts client.click(name, selector).to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/fill.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    class Fill
+      def self.run(client, args)
+        name, selector, value = args
+        abort "usage: browserctl fill <page> <selector> <value>" unless name && selector && value
+        puts client.fill(name, selector, value).to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/flag_extractor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    module FlagExtractor
+      def self.extract_opt(args, flag)
+        i = args.index(flag)
+        return unless i
+
+        args.delete_at(i)
+        args.delete_at(i)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/open_page.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "flag_extractor"
+
+module Browserctl
+  module Commands
+    class OpenPage
+      def self.run(client, args)
+        name = args.shift or abort "usage: browserctl open <name> [--url URL]"
+        url  = FlagExtractor.extract_opt(args, "--url")
+        res  = client.open_page(name, url: url)
+        puts res.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/screenshot.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "flag_extractor"
+
+module Browserctl
+  module Commands
+    class Screenshot
+      def self.run(client, args)
+        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
+      end
+    end
+  end
+end

data/lib/browserctl/commands/snapshot.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "flag_extractor"
+
+module Browserctl
+  module Commands
+    class Snapshot
+      def self.run(client, args)
+        name   = args.shift or abort "usage: browserctl snapshot <page> [--format ai|html]"
+        format = FlagExtractor.extract_opt(args, "--format") || "ai"
+        res    = client.snapshot(name, format: format)
+        output_snapshot(res, format)
+      end
+
+      class << self
+        private
+
+        def output_snapshot(res, format)
+          return abort res[:error] if res[:error]
+
+          puts(format == "ai" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/constants.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Browserctl
+  SOCKET_PATH = File.expand_path("~/.browserctl/browserd.sock")
+  PID_PATH    = File.expand_path("~/.browserctl/browserd.pid")
+  IDLE_TTL    = 30 * 60
+end

data/lib/browserctl/runner.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "workflow"
+require_relative "client"
+
+module Browserctl
+  class Runner
+    SEARCH_PATHS = [
+      "./.browserctl/workflows",
+      File.expand_path("~/.browserctl/workflows")
+    ].freeze
+
+    def run_workflow(name, **params)
+      defn    = fetch_workflow(name)
+      results = defn.call(params, Client.new)
+      print_results(results)
+      results.all?(&:ok)
+    end
+
+    def list_workflows
+      load_all_workflows
+      REGISTRY.map { |name, defn| { name: name, desc: defn.description } }
+    end
+
+    def describe_workflow(name)
+      defn = fetch_workflow(name)
+      { name: defn.name, desc: defn.description, params: format_params(defn), steps: defn.steps.map(&:first) }
+    end
+
+    private
+
+    def fetch_workflow(name)
+      load_workflow_file(name)
+      REGISTRY[name.to_s] || raise("workflow '#{name}' not found")
+    end
+
+    def load_workflow_file(name)
+      return if REGISTRY.key?(name.to_s)
+
+      path = workflow_path(name)
+      load path if path
+    end
+
+    def workflow_path(name)
+      SEARCH_PATHS.find do |dir|
+        candidate = File.join(dir, "#{name}.rb")
+        candidate if File.exist?(candidate)
+      end
+    end
+
+    def load_all_workflows
+      SEARCH_PATHS.select { |d| Dir.exist?(d) }.each { |d| load_from_dir(d) }
+    end
+
+    def load_from_dir(dir)
+      Dir.glob("#{dir}/*.rb").each do |f|
+        load f unless $LOADED_FEATURES.include?(f)
+      end
+    end
+
+    def print_results(results)
+      results.each { |r| print_result(r) }
+    end
+
+    def print_result(result)
+      label = result.ok ? "[ok]  " : "[fail]"
+      msg   = result.ok ? result.name : "#{result.name}: #{result.error}"
+      $stdout.puts "  #{label} #{msg}"
+    end
+
+    def format_params(defn)
+      defn.param_defs.transform_values { |p| { required: p.required, secret: p.secret, default: p.default } }
+    end
+  end
+end

data/lib/browserctl/server/command_dispatcher.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "snapshot_builder"
+
+module Browserctl
+  class CommandDispatcher
+    COMMAND_MAP = {
+      "open_page" => :cmd_open_page,
+      "close_page" => :cmd_close_page,
+      "list_pages" => :cmd_list_pages,
+      "goto" => :cmd_goto,
+      "snapshot" => :cmd_snapshot,
+      "evaluate" => :cmd_evaluate,
+      "fill" => :cmd_fill,
+      "click" => :cmd_click,
+      "screenshot" => :cmd_screenshot,
+      "wait_for" => :cmd_wait_for,
+      "url" => :cmd_url,
+      "ping" => :cmd_ping,
+      "shutdown" => :cmd_shutdown
+    }.freeze
+
+    def initialize(pages, browser, snapshot_builder = SnapshotBuilder.new)
+      @pages    = pages
+      @browser  = browser
+      @snapshot = snapshot_builder
+    end
+
+    def dispatch(req)
+      handler = COMMAND_MAP[req[:cmd]]
+      return { error: "unknown command: #{req[:cmd]}" } unless handler
+
+      send(handler, req)
+    end
+
+    private
+
+    def cmd_open_page(req)
+      page = @pages[req[:name]] ||= @browser.create_page
+      page.go_to(req[:url]) if req[:url]
+      { ok: true, name: req[:name] }
+    end
+
+    def cmd_close_page(req)
+      @pages.delete(req[:name])&.close
+      { ok: true }
+    end
+
+    def cmd_list_pages(_req)
+      { pages: @pages.keys }
+    end
+
+    def cmd_goto(req)
+      with_page(req[:name]) do |p|
+        p.go_to(req[:url])
+        { ok: true, url: p.current_url }
+      end
+    end
+
+    def cmd_snapshot(req)
+      with_page(req[:name]) { |p| build_snapshot(p, req[:format]) }
+    end
+
+    def build_snapshot(page, format)
+      format == "ai" ? { ok: true, snapshot: @snapshot.call(page) } : { ok: true, html: page.body }
+    end
+
+    def cmd_evaluate(req)
+      with_page(req[:name]) { |p| { ok: true, result: p.evaluate(req[:expression]) } }
+    end
+
+    def cmd_fill(req)
+      with_page(req[:name]) { |p| type_into(p, req[:selector], req[:value]) }
+    end
+
+    def type_into(page, selector, value)
+      el = page.at_css(selector)
+      return { error: "selector not found: #{selector}" } unless el
+
+      el.focus
+      el.type(value)
+      { ok: true }
+    end
+
+    def cmd_click(req)
+      with_page(req[:name]) { |p| click_element(p, req[:selector]) }
+    end
+
+    def click_element(page, selector)
+      el = page.at_css(selector)
+      return { error: "selector not found: #{selector}" } unless el
+
+      el.click
+      { ok: true }
+    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))
+        { ok: true, path: path }
+      end
+    end
+
+    def cmd_wait_for(req)
+      with_page(req[:name]) { |p| wait_for_selector(p, req[:selector], req.fetch(:timeout, 10).to_f) }
+    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" }
+    end
+
+    def cmd_url(req)
+      with_page(req[:name]) { |p| { ok: true, url: p.current_url } }
+    end
+
+    def cmd_ping(_req)
+      { ok: true, pid: Process.pid }
+    end
+
+    def cmd_shutdown(_req)
+      Process.kill("INT", Process.pid)
+      { ok: true }
+    end
+
+    def with_page(name)
+      page = @pages[name]
+      return { error: "no page named '#{name}'" } unless page
+
+      yield page
+    end
+  end
+end

data/lib/browserctl/server/idle_watcher.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+
+module Browserctl
+  class IdleWatcher
+    def initialize(last_used_fn)
+      @last_used_fn = last_used_fn
+    end
+
+    def watch(server)
+      loop do
+        sleep 60
+        if idle?
+          shutdown(server)
+          break
+        end
+      end
+    end
+
+    private
+
+    def idle?
+      Time.now - @last_used_fn.call > IDLE_TTL
+    end
+
+    def shutdown(server)
+      $stdout.puts "browserd idle timeout, shutting down"
+      quietly { server.close }
+      Process.kill("INT", Process.pid)
+    end
+
+    def quietly
+      yield
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/browserctl/server/snapshot_builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Browserctl
+  class SnapshotBuilder
+    INTERACTABLE = %w[a button input select textarea
+                      [role=button] [role=link] [role=menuitem]].freeze
+    ATTRS        = %w[type name placeholder href aria-label role].freeze
+
+    def call(page)
+      doc = Nokogiri::HTML(page.body)
+      ref = 0
+      doc.css(INTERACTABLE.join(",")).map { |el| element_entry(el, ref += 1) }
+    end
+
+    private
+
+    def element_entry(elem, ref)
+      { ref: "e#{ref}", tag: elem.name, text: elem.text.strip.slice(0, 80),
+        selector: css_path(elem), attrs: element_attrs(elem) }
+    end
+
+    def element_attrs(elem)
+      elem.attributes.transform_values(&:value).slice(*ATTRS)
+    end
+
+    def css_path(node)
+      ancestors_until_html(node).map { |n| path_segment(n) }.join(" > ")
+    end
+
+    def ancestors_until_html(node)
+      [].tap do |acc|
+        while node && node.name != "html"
+          acc.unshift(node)
+          node = node.parent
+        end
+      end
+    end
+
+    def path_segment(node)
+      node.name + id_fragment(node) + class_fragment(node)
+    end
+
+    def id_fragment(node)
+      (id = node["id"]) && !id.empty? ? "##{id}" : ""
+    end
+
+    def class_fragment(node)
+      return "" if node["id"] && !node["id"].empty?
+
+      (klass = node["class"]&.split&.first) ? ".#{klass}" : ""
+    end
+  end
+end

data/lib/browserctl/server.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "ferrum"
+require "socket"
+require "json"
+require "fileutils"
+require "timeout"
+require_relative "constants"
+require_relative "server/command_dispatcher"
+require_relative "server/idle_watcher"
+
+module Browserctl
+  class Server
+    def initialize(headless: true)
+      prepare_runtime(headless)
+      @dispatcher = CommandDispatcher.new(@pages, @browser)
+    end
+
+    def run
+      write_pid
+      server, idle = setup_server
+      serve(server)
+    rescue SignalException
+      # clean shutdown
+    ensure
+      teardown(idle, server)
+    end
+
+    private
+
+    def prepare_runtime(headless)
+      FileUtils.mkdir_p(File.dirname(SOCKET_PATH))
+      @browser = init_browser(headless)
+      init_state
+    end
+
+    def init_browser(headless)
+      Ferrum::Browser.new(
+        headless: headless,
+        timeout: 30,
+        process_timeout: 30,
+        browser_options: { "no-sandbox" => nil, "disable-dev-shm-usage" => nil, "disable-gpu" => nil }
+      )
+    end
+
+    def init_state
+      @pages     = {}
+      @last_used = Time.now
+      @mutex     = Mutex.new
+    end
+
+    def setup_server
+      server = setup_socket
+      idle   = Thread.new { IdleWatcher.new(-> { @mutex.synchronize { @last_used } }).watch(server) }
+      [server, idle]
+    end
+
+    def setup_socket
+      FileUtils.rm_f(SOCKET_PATH)
+      server = UNIXServer.new(SOCKET_PATH)
+      File.chmod(0o600, SOCKET_PATH)
+      announce_socket
+      server
+    end
+
+    def announce_socket
+      $stdout.puts "browserd listening on #{SOCKET_PATH}"
+      $stdout.flush
+    end
+
+    def serve(server)
+      loop do
+        client = server.accept
+        Thread.new(client) { |c| handle(c) }
+      end
+    end
+
+    def handle(socket)
+      if (line = socket.gets)
+        @mutex.synchronize { @last_used = Time.now }
+        socket.puts JSON.generate(process(line))
+      end
+    rescue StandardError => e
+      quietly { socket.puts JSON.generate({ error: e.message }) }
+    ensure
+      quietly { socket.close }
+    end
+
+    def process(line)
+      req = JSON.parse(line.chomp, symbolize_names: true)
+      @mutex.synchronize { @dispatcher.dispatch(req) }
+    end
+
+    def teardown(idle, server)
+      idle&.kill
+      quietly { server&.close }
+      quietly { Timeout.timeout(5) { @browser.quit } }
+      quietly { File.unlink(SOCKET_PATH) }
+      quietly { File.unlink(PID_PATH) }
+    end
+
+    def write_pid
+      File.write(PID_PATH, Process.pid.to_s)
+    end
+
+    def quietly
+      yield
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module Browserctl
+  class WorkflowError < StandardError; end
+
+  ParamDef = Struct.new(:name, :required, :secret, :default, keyword_init: true)
+  StepResult = Struct.new(:name, :ok, :error, keyword_init: true)
+
+  class WorkflowContext
+    attr_reader :client
+
+    def initialize(params, client)
+      @params = params
+      @client = client
+    end
+
+    def method_missing(name, *args)
+      return @params[name] if @params.key?(name)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @params.key?(name) || super
+    end
+
+    def page(name)
+      PageProxy.new(name.to_s, @client)
+    end
+
+    def invoke(workflow_name, **override_params)
+      name = workflow_name.to_s
+      guard_circular!(name)
+      track_invoke(name) { run_nested(workflow_name, **override_params) }
+    end
+
+    def assert(condition, msg = "assertion failed")
+      raise WorkflowError, msg unless condition
+    end
+
+    private
+
+    def invoke_stack
+      @invoke_stack ||= []
+    end
+
+    def guard_circular!(name)
+      return unless invoke_stack.include?(name)
+
+      raise WorkflowError, "circular workflow invocation: #{(invoke_stack + [name]).join(' → ')}"
+    end
+
+    def track_invoke(name)
+      invoke_stack << name
+      yield
+    ensure
+      invoke_stack.pop
+    end
+
+    def run_nested(workflow_name, **override_params)
+      Runner.new.run_workflow(workflow_name, **@params, **override_params)
+    end
+  end
+
+  class PageProxy
+    def initialize(name, client)
+      @name   = name
+      @client = client
+    end
+
+    def goto(url)        = unwrap @client.goto(@name, url)
+    def fill(sel, val)   = unwrap @client.fill(@name, sel, val)
+    def click(sel)       = unwrap @client.click(@name, sel)
+    def snapshot(**) = unwrap @client.snapshot(@name, **)
+    def screenshot(**) = unwrap @client.screenshot(@name, **)
+    def wait_for(sel, timeout: 10) = unwrap @client.wait_for(@name, sel, timeout: timeout)
+    def url              = @client.url(@name)[:url]
+    def evaluate(expr)   = @client.evaluate(@name, expr)[:result]
+
+    private
+
+    def unwrap(res)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+  end
+
+  class WorkflowDefinition
+    attr_reader :name, :description, :param_defs, :steps
+
+    def initialize(name)
+      @name = name
+      @description = nil
+      @param_defs  = {}
+      @steps       = []
+    end
+
+    def desc(text)
+      @description = text
+    end
+
+    def param(name, required: false, secret: false, default: nil)
+      @param_defs[name] = ParamDef.new(name: name, required: required, secret: secret, default: default)
+    end
+
+    def step(label, &block)
+      @steps << [label, block]
+    end
+
+    def call(params, client)
+      ctx = WorkflowContext.new(resolve_params(params), client)
+      execute_steps(ctx)
+    end
+
+    private
+
+    def execute_steps(ctx)
+      @steps.map { |label, block| run_step(ctx, label, block) }.each do |r|
+        raise WorkflowError, "step '#{r.name}' failed: #{r.error}" unless r.ok
+      end
+    end
+
+    def run_step(ctx, label, block)
+      ctx.instance_exec(&block)
+      StepResult.new(name: label, ok: true)
+    rescue WorkflowError, StandardError => e
+      StepResult.new(name: label, ok: false, error: e.message)
+    end
+
+    def resolve_params(provided)
+      @param_defs.each_with_object({}) do |(name, defn), out|
+        val = provided[name] || defn.default
+        raise WorkflowError, "required param '#{name}' missing" if defn.required && val.nil?
+
+        out[name] = val
+      end
+    end
+  end
+
+  REGISTRY = {} # rubocop:disable Style/MutableConstant
+
+  def self.workflow(name, &)
+    defn = WorkflowDefinition.new(name.to_s)
+    defn.instance_exec(&)
+    REGISTRY[name.to_s] = defn
+  end
+end

data/lib/browserctl.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "browserctl/version"
+require_relative "browserctl/constants"
+require_relative "browserctl/workflow"
+require_relative "browserctl/runner"
+require_relative "browserctl/client"