browserctl 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b5b21accfeb82afa82dc2c12d51ef7da31ed8ab9db073d2b576df0385e5adb6
-  data.tar.gz: d9cd601ce2d63b5c3f2c8d539d14dc684dcf3753a7f95002b9c165791ff2f584
+  metadata.gz: c12ad0cc3d34e7163bab1d678d65b320e946e0fa16fe7bd3e9f5881855d4801f
+  data.tar.gz: 84d80f56270dfc7d252d7e63279f7c7c54123067837af457f5e92e82b2f0384e
 SHA512:
-  metadata.gz: 5bc9c337336ac4fb23da1966a9b51e3dffcef8b23ea00a2990310a0aae5978ccf423416118ebe61b83c92ca84f38846ca16ca909a376e2e3e8f13eb97e82b045
-  data.tar.gz: 13b8b5fcbc17e328210488ce8e50ead2ea8576419dc5d493c06285d8e191a4be7599a04a58b651f501febb351704609be6dc06c0c8c00c827a7c796667072943
+  metadata.gz: c95dbbbe2a573635421fe90cd65d2ccc41baf968c32bb65edcea52030e1b0080fd2af0f50ea9d85bc827ff4f537e2c5b4f3a7631c8242380a007df432e820906
+  data.tar.gz: 1da50ab443d365e4a4b9ce145671e266fdfb0d83432b7b2313d87233b58b425252d2d9a365b0f8b3c31040961b90f684fe9299867c4cccfcd9600ea88cb93cc1

data/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1](https://github.com/patrick204nqh/browserctl/compare/v0.2.0...v0.2.1) (2026-04-20)
+
+
+### Bug Fixes
+
+* align CLI with standard conventions ([215c2af](https://github.com/patrick204nqh/browserctl/commit/215c2af3a4c4d27397476932147f3fda39e4039c))
+* remove flag_extractor spec after deleting the module ([cd80045](https://github.com/patrick204nqh/browserctl/commit/cd8004515fcbae68248d7133e10d5c0223be10e1))
+* use GH_PAT for release-please to trigger release workflow ([da83358](https://github.com/patrick204nqh/browserctl/commit/da83358e8ff19e8a30c23b9f5d744cb11ffbc7c6))
+* use PAT for release-please to trigger release workflow ([4a9ea99](https://github.com/patrick204nqh/browserctl/commit/4a9ea99f418cbf719a16e2a971672175e0292221))
+
 ## [0.2.0](https://github.com/patrick204nqh/browserctl/compare/v0.1.1...v0.2.0) (2026-04-20)
 
 

data/bin/browserctl

@@ -3,8 +3,17 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
+require "browserctl/version"
+
+if ARGV.intersect?(%w[--version -v])
+  puts "browserctl #{Browserctl::VERSION}"
+  exit 0
+end
+
 require "json"
+require "optimist"
 require "browserctl"
+require "browserctl/commands/cli_output"
 require "browserctl/commands/open_page"
 require "browserctl/commands/fill"
 require "browserctl/commands/click"
@@ -13,42 +22,55 @@ require "browserctl/commands/screenshot"
 require "browserctl/commands/watch"
 require "browserctl/commands/record"
 
+def print_result(res)
+  if res.is_a?(Hash) && res[:error]
+    warn "Error: #{res[:error]}"
+    exit 1
+  end
+  puts res.to_json
+end
+
+# rubocop:disable Metrics/MethodLength
 def usage
   puts <<~USAGE
     Usage: browserctl <command> [args]
 
     Browser commands (require browserd running):
-      open   <page> [--url URL]           Open or focus a named page
-      close  <page>                        Close a named page
-      pages                                List open pages
-      goto   <page> <url>                  Navigate a page
-      fill   <page> <selector> <value>     Fill an input
-      click  <page> <selector>             Click an element
-      shot   <page> [--out PATH] [--full]  Take a screenshot
-      snap   <page> [--format ai|html]     Snapshot DOM (default: ai)
-      url    <page>                        Print current URL
-      eval   <page> <expression>           Evaluate JS expression
-      watch  <page> <selector> [--timeout N]  Wait for a selector to appear
+      open   <page> [--url URL]                   Open or focus a named page
+      close  <page>                                Close a named page
+      pages                                        List open pages
+      goto   <page> <url>                          Navigate a page
+      fill   <page> <selector> <value>             Fill an input
+             <page> --ref <ref> --value <value>    Fill via snapshot ref
+      click  <page> <selector>                     Click an element
+             <page> --ref <ref>                    Click via snapshot ref
+      shot   <page> [--out PATH] [--full]          Take a screenshot
+      snap   <page> [--format ai|html] [--diff]    Snapshot DOM (default: ai)
+      url    <page>                                Print current URL
+      eval   <page> <expression>                   Evaluate JS expression
+      watch  <page> <selector> [--timeout N]       Wait for a selector to appear
 
     Recording commands:
-      record start <name>    Start recording browser commands
-      record stop [--out path]  Stop recording and save workflow
-      record status          Show active recording name
+      record start <name>            Start recording browser commands
+      record stop  [--out PATH]      Stop recording and save workflow
+      record status                  Show active recording name
 
     Workflow commands:
-      run      <name|file> [--key value]   Run a workflow
-      workflows                            List available workflows
-      describe <name>                      Describe a workflow
+      run      <name|file> [--key value ...]   Run a workflow
+      workflows                                List available workflows
+      describe <name>                          Describe a workflow
 
     Daemon commands:
-      ping                                 Check if browserd is alive
-      shutdown                             Stop browserd
+      ping                   Check if browserd is alive
+      shutdown               Stop browserd
 
     Options:
       --daemon <name>    Connect to a named daemon instance
+      --version, -v      Print version and exit
   USAGE
   exit 0
 end
+# rubocop:enable Metrics/MethodLength
 
 daemon_idx  = ARGV.index("--daemon")
 daemon_name = if daemon_idx
@@ -93,19 +115,19 @@ else
   client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
   case cmd
-  when "open"   then Browserctl::Commands::OpenPage.run(client, args)
-  when "close"  then puts client.close_page(args[0]).to_json
-  when "pages"  then puts client.list_pages.to_json
-  when "goto"   then puts client.goto(args[0], args[1]).to_json
-  when "fill"   then Browserctl::Commands::Fill.run(client, args)
-  when "click"  then Browserctl::Commands::Click.run(client, args)
-  when "shot"   then Browserctl::Commands::Screenshot.run(client, args)
-  when "snap"   then Browserctl::Commands::Snapshot.run(client, args)
-  when "url"    then puts client.url(args[0]).to_json
-  when "eval"   then puts client.evaluate(args[0], args[1]).to_json
-  when "watch"  then Browserctl::Commands::Watch.run(client, args)
-  when "ping"   then puts client.ping.to_json
-  when "shutdown" then puts client.shutdown.to_json
+  when "open"     then Browserctl::Commands::OpenPage.run(client, args)
+  when "close"    then print_result(client.close_page(args[0]))
+  when "pages"    then print_result(client.list_pages)
+  when "goto"     then print_result(client.goto(args[0], args[1]))
+  when "fill"     then Browserctl::Commands::Fill.run(client, args)
+  when "click"    then Browserctl::Commands::Click.run(client, args)
+  when "shot"     then Browserctl::Commands::Screenshot.run(client, args)
+  when "snap"     then Browserctl::Commands::Snapshot.run(client, args)
+  when "url"      then print_result(client.url(args[0]))
+  when "eval"     then print_result(client.evaluate(args[0], args[1]))
+  when "watch"    then Browserctl::Commands::Watch.run(client, args)
+  when "ping"     then print_result(client.ping)
+  when "shutdown" then print_result(client.shutdown)
   else
     abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
   end

data/bin/browserd

@@ -7,11 +7,13 @@ require "optimist"
 require "nokogiri"
 require "browserctl/logger"
 require "browserctl/server"
+require "browserctl/version"
 
 opts = Optimist.options do
-  opt :headed,    "Run with a visible browser window",        default: false
-  opt :log_level, "Log verbosity: debug, info, warn, error",  default: "info", type: :string
-  opt :name,      "Daemon instance name for multi-agent use", default: nil, type: :string
+  version "browserd #{Browserctl::VERSION}"
+  opt :headed,    "Run with a visible browser window",        default: false,  short: "-H"
+  opt :log_level, "Log verbosity: debug, info, warn, error",  default: "info", short: "-l", type: :string
+  opt :name,      "Daemon instance name for multi-agent use", default: nil,    short: "-n", type: :string
 end
 
 Browserctl.logger = Browserctl.build_logger(opts[:log_level])

data/lib/browserctl/commands/cli_output.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Commands
+    module CliOutput
+      def print_result(res)
+        if res.is_a?(Hash) && res[:error]
+          warn "Error: #{res[:error]}"
+          exit 1
+        end
+        puts res.to_json
+      end
+    end
+  end
+end

data/lib/browserctl/commands/click.rb

@@ -1,21 +1,27 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class Click
+      extend CliOutput
+
       def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl click <page> <selector>\n       " \
+                 "browserctl click <page> --ref <ref>"
+          opt :ref, "Snapshot ref to click", type: :string, short: "-r"
+        end
         name = args.shift
-        ref  = FlagExtractor.extract_opt(args, "--ref")
-        selector = args.shift unless ref
-
-        if ref
+        if opts[:ref]
           abort "usage: browserctl click <page> --ref <ref>" unless name
-          puts client.click(name, ref: ref).to_json
+          print_result(client.click(name, ref: opts[:ref]))
         else
+          selector = args.shift
           abort "usage: browserctl click <page> <selector>" unless name && selector
-          puts client.click(name, selector).to_json
+          print_result(client.click(name, selector))
         end
       end
     end

data/lib/browserctl/commands/fill.rb

@@ -1,23 +1,37 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class Fill
+      extend CliOutput
+
       def self.run(client, args)
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl fill <page> <selector> <value>\n       " \
+                 "browserctl fill <page> --ref <ref> --value <value>"
+          opt :ref,   "Snapshot ref to fill", type: :string, short: "-r"
+          opt :value, "Value to fill",        type: :string, short: "-V"
+        end
         name = args.shift
-        ref  = FlagExtractor.extract_opt(args, "--ref")
+        opts[:ref] ? fill_by_ref(client, name, opts) : fill_by_selector(client, name, args, opts[:value])
+      end
+
+      class << self
+        private
+
+        def fill_by_ref(client, name, opts)
+          abort "usage: browserctl fill <page> --ref <ref> --value <value>" unless name && opts[:value]
+          print_result(client.fill(name, nil, opts[:value], ref: opts[:ref]))
+        end
 
-        if ref
-          value = FlagExtractor.extract_opt(args, "--value")
-          abort "usage: browserctl fill <page> --ref <ref> --value <value>" unless name && value
-          puts client.fill(name, nil, value, ref: ref).to_json
-        else
+        def fill_by_selector(client, name, args, value_opt)
           selector = args.shift
-          value = args.shift
+          value    = value_opt || args.shift
           abort "usage: browserctl fill <page> <selector> <value>" unless name && selector && value
-          puts client.fill(name, selector, value).to_json
+          print_result(client.fill(name, selector, value))
         end
       end
     end

data/lib/browserctl/commands/open_page.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
-require_relative "flag_extractor"
+require "optimist"
+require_relative "cli_output"
 
 module Browserctl
   module Commands
     class OpenPage
+      extend CliOutput
+
       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
+        opts = Optimist.options(args) do
+          banner "Usage: browserctl open <page> [--url URL]"
+          opt :url, "URL to navigate to", type: :string, short: "-u"
+        end
+        name = args.shift or abort "usage: browserctl open <page> [--url URL]"
+        print_result(client.open_page(name, url: opts[:url]))
       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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Patrick
@@ -103,9 +103,9 @@ files:
 - examples/the_internet/login.rb
 - lib/browserctl.rb
 - lib/browserctl/client.rb
+- lib/browserctl/commands/cli_output.rb
 - lib/browserctl/commands/click.rb
 - lib/browserctl/commands/fill.rb
-- lib/browserctl/commands/flag_extractor.rb
 - lib/browserctl/commands/open_page.rb
 - lib/browserctl/commands/record.rb
 - lib/browserctl/commands/screenshot.rb

data/lib/browserctl/commands/flag_extractor.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Browserctl
-  module Commands
-    module FlagExtractor
-      def self.extract_opt(args, flag)
-        i = args.index(flag)
-        return unless i
-
-        sliced = args.slice!(i, 2)
-        sliced.length == 2 ? sliced.last : nil
-      end
-
-      def self.extract_flag?(args, flag)
-        i = args.index(flag)
-        return false unless i
-
-        args.delete_at(i)
-        true
-      end
-    end
-  end
-end