browserctl 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a7eb052c2bbfc4e1f5afc24ba08c5b2b0d471a85d2acf6ea61a7f160cbe201b
-  data.tar.gz: 2d4259da9b4a13a50ad80e68d404f11eda89b6249e5315c58247c8d80514d21f
+  metadata.gz: 41aa6c550f8a9a6403781639ebbd381c653aedb03cfa95f732b74de3ee0a931d
+  data.tar.gz: 3feea758e797eca81e1ab269ca5d9011f82778510dab1ee45e31b80b9aa38048
 SHA512:
-  metadata.gz: ca34ca3125de0686417b06919a8cb0eaf3311eaedd7ebe6538c1f159941d737ca549f3d0c3d8a10da73146bd23602cb145ed010539a48de97c3d8552d4f317c9
-  data.tar.gz: 61c89f8a4b2e61076ddd5fa603710e226ebfe1e176914ffb37f47a79ee35a2161b3700406a35c878d6fdc6cb129f051f00943d080b636076f6d1452b6ee290b3
+  metadata.gz: e100a2bce4a66b7ccd1cfaebfd5e5acb3b0f9c32aafec8427efe0f8d2b613ae954d9043a8d4da536284b7739508d4b318dab5e2abe16a83113938a23fb000796
+  data.tar.gz: b2171d7d6043c5c89084a21f50a5c53bbaa0ce1e891babeb30b4beb66ede7e41e8f87e7382980bb9f9229e453121cc99bd252aa4d54c48598d01bdbc7fbdadab

data/CHANGELOG.md

@@ -10,6 +10,23 @@ 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.13.0](https://github.com/patrick204nqh/browserctl/compare/v0.12.0...v0.13.0) (2026-05-10)
+
+
+### ⚠ BREAKING CHANGES
+
+* `--output` is now a reserved global flag on every browserctl command. Existing invocations are unaffected (default mode `text` preserves prior byte-for-byte output), but commands that previously consumed `--output` as a positional or sub-flag would now collide. None ship in this gem.
+* The CLI subcommands `snapshot`, `screenshot`, and `record` are removed with no aliases. Use `page snapshot`, `page screenshot`, and `recording start|stop|status` respectively.
+* The `session` CLI commands and the `session_*` JSON-RPC wire commands are removed. Users on v0.12 sessions must regenerate state via `state save` before upgrading. The workflow DSL methods `save_session`, `load_session`, and `list_sessions` are also removed; use `save_state` / `load_state` instead.
+* `store` and `fetch` wire commands are no longer part of the Fixed zone. They move to Extension and may change between minor releases with a changelog entry. The wire shape is unchanged in v0.13; the change is to the stability promise.
+
+### Features
+
+* narrow Fixed zone — store/fetch and known overlaps ([#158](https://github.com/patrick204nqh/browserctl/issues/158)) ([067cb42](https://github.com/patrick204nqh/browserctl/commit/067cb423b5966784abc8be2395808b5e4fa92ac0))
+* noun-verb CLI consistency ([#162](https://github.com/patrick204nqh/browserctl/issues/162)) ([8ceb729](https://github.com/patrick204nqh/browserctl/commit/8ceb72998008a8e6983cb4bad13ac5f286ad9ee8))
+* remove session commands and code path ([#161](https://github.com/patrick204nqh/browserctl/issues/161)) ([12d58d9](https://github.com/patrick204nqh/browserctl/commit/12d58d9aa26b2609c98e4b34ce072a6dbb8baafe))
+* unified --output {json,text,silent} on every CLI command ([#164](https://github.com/patrick204nqh/browserctl/issues/164)) ([f8947c6](https://github.com/patrick204nqh/browserctl/commit/f8947c655bc0b1f21bbf6067a059d6ab0b7d8b9e))
+
 ## [0.12.0](https://github.com/patrick204nqh/browserctl/compare/v0.11.0...v0.12.0) (2026-05-10)
 
 

data/README.md

@@ -21,7 +21,7 @@ Every browser automation tool restarts the browser when your script ends. That m
 ```bash
 browserd &                                               # start the daemon (headless)
 browserctl page open main --url https://example.com/login
-browserctl snapshot main                                 # AI-friendly JSON snapshot with ref IDs
+browserctl page snapshot main                                 # AI-friendly JSON snapshot with ref IDs
 browserctl fill main --ref e1 --value me@example.com    # interact by ref, no selectors needed
 browserctl click main --ref e2
 browserctl daemon stop
@@ -42,7 +42,7 @@ browserd &
 browserctl page open main --url https://moatazeldebsy.github.io/test-automation-practices/#/auth
 
 # 4. Snapshot — returns JSON with a ref ID per interactable element
-browserctl snapshot main
+browserctl page snapshot main
 # → [{"ref":"e1","tag":"input","attrs":{"data-test":"username-input"}}, {"ref":"e2",...}, {"ref":"e3","tag":"button","text":"Login",...}]
 
 # 5. Interact using the ref IDs from the snapshot
@@ -52,7 +52,7 @@ browserctl click main --ref e3
 
 # 6. Observe
 browserctl url main
-browserctl snapshot main --diff   # only what changed
+browserctl page snapshot main --diff       # only what changed
 
 # Session persistence: save now, pick up later
 browserctl session save my-session

data/bin/browserctl

@@ -14,17 +14,17 @@ require "json"
 require "optimist"
 require "browserctl"
 require "browserctl/commands/cli_output"
+require "browserctl/commands/output_format"
 require "browserctl/commands/fill"
 require "browserctl/commands/click"
 require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
-require "browserctl/commands/record"
+require "browserctl/commands/recording"
 require "browserctl/commands/resume"
 require "browserctl/commands/init"
 require "browserctl/commands/page"
 require "browserctl/commands/cookie"
 require "browserctl/commands/storage"
-require "browserctl/commands/session"
 require "browserctl/commands/state"
 require "browserctl/commands/daemon"
 require "browserctl/commands/workflow"
@@ -42,9 +42,11 @@ def structured_stderr_payload(res, message)
   [code, JSON.generate(code: code, message: message, context: context, suggested_action: action)]
 end
 
-def print_result(res)
+def print_result(res, text_block = nil)
+  fmt = Browserctl::Commands::OutputFormat.current
+
   unless res.is_a?(Hash) && (res[:error] || res["error"])
-    puts res.to_json
+    fmt.emit(res, text_block)
     return
   end
 
@@ -52,7 +54,7 @@ def print_result(res)
   code, payload = structured_stderr_payload(res, message)
   warn "Error: #{message}"
   warn payload
-  puts res.to_json
+  puts res.to_json unless fmt.silent?
   exit Browserctl::Error::ExitCodes.for(code)
 end
 
@@ -64,10 +66,12 @@ def usage
       init
 
     Page:
-      page open <name> [--url URL]
-      page close <name>
+      page open       <name> [--url URL]
+      page close      <name>
       page list
-      page focus <name>
+      page focus      <name>
+      page snapshot   <name> [--format elements|html] [--diff]
+      page screenshot <name> [--out PATH] [--full]
 
     Interaction (page is always first arg after verb):
       navigate <page> <url>
@@ -75,8 +79,6 @@ def usage
                <page> --ref <ref> --value <value>
       click    <page> <selector>
                <page> --ref <ref>
-      snapshot <page> [--format elements|html] [--diff]
-      screenshot <page> [--out PATH] [--full]
       evaluate <page> <expression>
       url      <page>
       wait     <page> <selector> [--timeout N]
@@ -105,14 +107,6 @@ def usage
       storage import <page> <path>
       storage delete <page> [--store local|session|all]
 
-    Session:
-      session save   <name>
-      session load   <name>
-      session list
-      session delete <name>
-      session export <name> <path>
-      session import <path>
-
     Auth detection:
       auth-check <page> [--cookies] [--state NAME] [--flow NAME]
         # Exits 7 with code: AUTH_REQUIRED when the page needs login.
@@ -128,9 +122,9 @@ def usage
       state import <source> [--name NAME]
 
     Recording:
-      record start <name>
-      record stop  [--out PATH]
-      record status
+      recording start <name>
+      recording stop  [--out PATH]
+      recording status
 
     Workflow:
       workflow run      <name|file> [--check] [--params file] [--key value ...]
@@ -162,11 +156,23 @@ def usage
 
     Global options:
       --daemon <name>    Connect to named or auto-indexed daemon (d1, d2, work, ...)
+      --output <fmt>     Output format: json | text | silent (default: text;
+                         override with BROWSERCTL_OUTPUT)
       --version, -v
   USAGE
   exit 0
 end
 
+# Resolve --output {json,text,silent} (or BROWSERCTL_OUTPUT) once, globally,
+# before per-command parsers run. Strips the flag from ARGV in place so
+# downstream Optimist/positional parsers don't see it.
+begin
+  Browserctl::Commands::OutputFormat.install!(ARGV)
+rescue Browserctl::Commands::OutputFormat::InvalidFormat => e
+  warn "Error: #{e.message}"
+  exit 2
+end
+
 daemon_idx  = ARGV.index("--daemon")
 daemon_name = if daemon_idx
                 ARGV.delete_at(daemon_idx)
@@ -193,9 +199,9 @@ runner = Browserctl::Runner.new
 
 begin
   case cmd
-  when "workflow" then Browserctl::Commands::Workflow.run(runner, args)
-  when "record"   then Browserctl::Commands::Record.run(args)
-  when "init"     then Browserctl::Commands::Init.run(args)
+  when "workflow"  then Browserctl::Commands::Workflow.run(runner, args)
+  when "recording" then Browserctl::Commands::Recording.run(args)
+  when "init"      then Browserctl::Commands::Init.run(args)
   when "ask"      then Browserctl::Commands::Ask.run(args)
   when "trace"    then Browserctl::Commands::Trace.run(args)
   when "migrate"  then Browserctl::Commands::Migrate.run(args)
@@ -208,7 +214,6 @@ begin
     when "page"     then Browserctl::Commands::Page.run(client, args)
     when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
     when "storage"  then Browserctl::Commands::Storage.run(client, args)
-    when "session"  then Browserctl::Commands::Session.run(client, args)
     when "state"    then Browserctl::Commands::State.run(client, args)
     when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
     when "auth-check"
@@ -229,8 +234,6 @@ begin
     when "navigate" then print_result(client.navigate(args[0], args[1]))
     when "fill"     then Browserctl::Commands::Fill.run(client, args)
     when "click"    then Browserctl::Commands::Click.run(client, args)
-    when "snapshot" then Browserctl::Commands::Snapshot.run(client, args)
-    when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
     when "evaluate" then print_result(client.evaluate(args[0], args[1]))
     when "url"      then print_result(client.url(args[0]))
     when "wait"
@@ -251,9 +254,12 @@ begin
         warn "Error: #{res[:error]}"
         exit 1
       end
-      puts "Page '#{name}' paused. Browser is live — interact freely."
-      puts "(#{opts[:message]})" if opts[:message]
-      puts "When done: browserctl resume #{name}"
+      print_result(res.merge(paused: name, message: opts[:message])) do
+        lines = ["Page '#{name}' paused. Browser is live — interact freely."]
+        lines << "(#{opts[:message]})" if opts[:message]
+        lines << "When done: browserctl resume #{name}"
+        lines.join("\n")
+      end
     when "resume" then Browserctl::Commands::Resume.run(client, args)
     when "press"
       name = args.shift or abort "usage: browserctl press <page> <key>"
@@ -282,8 +288,9 @@ begin
         exit 1
       end
       url = res[:devtools_url]
-      puts "Opening DevTools for '#{name}':"
-      puts "  #{url}"
+      print_result(res) do
+        "Opening DevTools for '#{name}':\n  #{url}"
+      end
       opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
       system(opener, url)
     else

data/lib/browserctl/callable_definition.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "errors"
+require_relative "secret_resolvers"
+
+module Browserctl
+  # Shared base for {Flow} and {WorkflowDefinition}. Holds the duplicated
+  # DSL surface (`desc`, `param`, `step`) and the shared execution helpers
+  # for resolving params and running step blocks with retry + timeout.
+  #
+  # Subclasses provide:
+  # - their own `call`/`run` entry point and context object;
+  # - {#callable_kind} so cross-type composition can be rejected at
+  #   definition time (e.g. a flow trying to `compose` a workflow);
+  # - {#step_failure_message} for the typed error wording.
+  #
+  # The persistence DSL (`store`/`fetch`/`save_state`/`load_state`) is
+  # mixed into `WorkflowContext` via {ContextualPersistence} and is
+  # deliberately absent from `FlowContext` — flows return state, workflows
+  # share state.
+  class CallableDefinition
+    ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
+    StepDef  = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
+
+    attr_reader :name, :description, :param_defs, :steps
+
+    def initialize(name)
+      @name        = name.to_s
+      @description = nil
+      @param_defs  = {}
+      @steps       = []
+    end
+
+    def desc(text)
+      @description = text.to_s
+    end
+
+    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
+      secret = true if secret_ref
+      @param_defs[name] = ParamDef.new(
+        name: name,
+        required: required,
+        secret: secret,
+        default: default,
+        secret_ref: secret_ref
+      )
+    end
+
+    def step(label, retry_count: 0, timeout: nil, &block)
+      raise ArgumentError, "#{callable_kind} step '#{label}' requires a block" unless block
+
+      @steps << StepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
+    end
+
+    # Subclasses override these to specialise the base behaviour.
+
+    # @return [Symbol] :flow or :workflow — used for cross-type composition checks.
+    def callable_kind
+      raise NotImplementedError
+    end
+
+    private
+
+    def resolve_params(provided)
+      @param_defs.each_with_object({}) do |(name, defn), out|
+        val = if defn.secret_ref
+                SecretResolverRegistry.resolve(defn.secret_ref)
+              elsif provided.key?(name)
+                provided[name]
+              else
+                defn.default
+              end
+
+        raise missing_param_error(name) if defn.required && val.nil?
+
+        out[name] = val
+      end
+    end
+
+    # Override for typed error wording.
+    def missing_param_error(_name)
+      raise NotImplementedError
+    end
+
+    # Runs a step block with retry + timeout. Yields the recoverable error
+    # to the caller (via the returned exception in `:error`) so subclasses
+    # can decide how to surface a failure (raise vs StepResult).
+    def execute_step_block(ctx, defn)
+      if defn.timeout
+        ::Timeout.timeout(defn.timeout) { ctx.instance_exec(&defn.block) }
+      else
+        ctx.instance_exec(&defn.block)
+      end
+    rescue ::Timeout::Error
+      raise step_timeout_error(defn)
+    end
+
+    def with_retries(defn)
+      last_error = nil
+      (defn.retry_count + 1).times do
+        return yield
+      rescue StandardError => e
+        last_error = e
+      end
+      [:error, last_error]
+    end
+
+    # Subclasses override to raise their typed timeout error.
+    def step_timeout_error(_defn)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/browserctl/client.rb

@@ -283,33 +283,6 @@ module Browserctl
     # @return [Hash] `{ ok: true }` or `{ error: }`
     def dialog_dismiss(name)           = call("dialog_dismiss", name: name)
 
-    # Saves the current browser state (cookies, localStorage, open pages) to a named session.
-    # @param session_name [String] name for the saved session
-    # @return [Hash] `{ ok: true, path:, pages: N, cookies: N }` or `{ error: }`
-    def session_save(session_name, encrypt: false)
-      call("session_save", session_name: session_name, encrypt: encrypt)
-    end
-
-    # Restores a previously saved session into the running daemon.
-    # @param session_name [String] name of the session to load
-    # @return [Hash] `{ ok: true, cookies: N, pages: N, local_storage_keys: N }` or `{ error: }`
-    def session_load(session_name)
-      call("session_load", session_name: session_name)
-    end
-
-    # Lists all saved sessions.
-    # @return [Hash] `{ ok: true, sessions: [Hash] }` or `{ error: }`
-    def session_list
-      call("session_list")
-    end
-
-    # Permanently deletes a named session.
-    # @param session_name [String] name of the session to delete
-    # @return [Hash] `{ ok: true }` or `{ error: }`
-    def session_delete(session_name)
-      call("session_delete", session_name: session_name)
-    end
-
     # Saves browser state (cookies + storage) into a single .bctl bundle.
     # @return [Hash] `{ ok:, path:, origins:, cookies:, encrypted: }` or `{ error: }`
     def state_save(name, origins: nil, flow: nil, flow_version: nil, passphrase: nil)

data/lib/browserctl/commands/cli_output.rb

@@ -3,21 +3,35 @@
 require "json"
 require_relative "../errors"
 require_relative "../error/suggested_actions"
+require_relative "output_format"
 
 module Browserctl
   module Commands
     module CliOutput
       AUTH_REQUIRED_EXIT_CODE = Browserctl::AuthRequiredError::AUTH_REQUIRED_EXIT_CODE
 
-      def print_result(res)
+      # Print the JSON-RPC daemon response, routed through the active
+      # `OutputFormat`. The historical default behaviour was `puts res.to_json`
+      # — keeping that as the `text` branch preserves byte-identical output
+      # for existing callers and golden files. `json` mode emits the same
+      # JSON explicitly. `silent` suppresses stdout entirely; errors still
+      # write the structured payload to stderr because errors are the
+      # result, not cosmetic output.
+      #
+      # `text_block` (optional) overrides the JSON dump in `text` mode for
+      # commands that have a distinct human-readable form (e.g. `init`).
+      def print_result(res, text_block = nil)
+        fmt = OutputFormat.current
+
         if res.is_a?(Hash) && (res[:error] || res["error"])
           message = res[:error] || res["error"]
           warn "Error: #{message}"
           warn structured_error_line(res, message)
-          puts res.to_json
+          puts res.to_json unless fmt.silent?
           exit exit_code_for(res)
         end
-        puts res.to_json
+
+        fmt.emit(res, text_block)
       end
 
       # Maps a daemon error response onto a process exit code. Defaults to 1;

data/lib/browserctl/commands/daemon.rb

@@ -3,6 +3,7 @@
 require "json"
 require "optimist"
 require_relative "cli_output"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -18,7 +19,8 @@ module Browserctl
           begin
             print_result(client.ping)
           rescue Browserctl::DaemonUnavailableError => e
-            puts JSON.generate({ ok: false, daemon: "offline", error: e.message })
+            payload = { ok: false, daemon: "offline", error: e.message }
+            OutputFormat.current.emit(payload)
             exit 1
           end
         when "status" then run_status(client)
@@ -36,14 +38,16 @@ module Browserctl
           url_res = client.url(name)
           { name: name, url: url_res[:url] || url_res[:error] }
         end
-        puts JSON.pretty_generate(
+        payload = {
           daemon: "online",
           pid: ping[:pid],
           protocol_version: ping[:protocol_version],
           pages: page_info
-        )
+        }
+        OutputFormat.current.emit(payload, JSON.pretty_generate(payload))
       rescue Browserctl::DaemonUnavailableError => e
-        puts JSON.pretty_generate(daemon: "offline", error: e.message)
+        payload = { daemon: "offline", error: e.message }
+        OutputFormat.current.emit(payload, JSON.pretty_generate(payload))
         exit 1
       end
 
@@ -57,7 +61,7 @@ module Browserctl
         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})"
+        OutputFormat.current.emit({ ok: true, pid: pid }) { "browserd started (pid #{pid})" }
       end
 
       def self.run_list
@@ -74,7 +78,7 @@ module Browserctl
         rescue Browserctl::DaemonUnavailableError, RuntimeError
           nil
         end.compact
-        puts({ daemons: rows }.to_json)
+        OutputFormat.current.emit({ daemons: rows })
       end
     end
   end

data/lib/browserctl/commands/flow.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require_relative "cli_output"
+require_relative "output_format"
 require_relative "../flow_registry"
 require_relative "../runner"
 
@@ -31,22 +32,22 @@ module Browserctl
         page_proxy = page_name ? Browserctl::PageProxy.new(page_name, client) : nil
 
         result = flow.run(page: page_proxy, client: client, **params)
-        puts JSON.generate(ok: true, flow: flow.name, result: serialisable(result))
+        OutputFormat.current.emit({ ok: true, flow: flow.name, result: serialisable(result) })
       rescue Browserctl::FlowError => e
         warn "Error: #{e.message}"
-        puts JSON.generate(ok: false, code: e.code, error: e.message)
+        OutputFormat.current.emit({ ok: false, code: e.code, error: e.message }) unless OutputFormat.current.silent?
         exit 1
       end
 
       def self.run_list
         entries = Browserctl::FlowRegistry.list
-        puts JSON.generate(flows: entries)
+        OutputFormat.current.emit({ flows: entries })
       end
 
       def self.run_describe(args)
         name = args.shift or abort "usage: browserctl flow describe <name>"
         flow = resolve(name)
-        puts JSON.pretty_generate(
+        payload = {
           name: flow.name,
           desc: flow.description,
           version: flow.version_string,
@@ -56,7 +57,8 @@ module Browserctl
           steps: flow.steps.map(&:label),
           postconditions: flow.postconditions.map(&:label),
           produces_state: !flow.produces_state_block.nil?
-        )
+        }
+        OutputFormat.current.emit(payload, JSON.pretty_generate(payload))
       end
 
       def self.resolve(name_or_path)

data/lib/browserctl/commands/init.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -14,15 +15,15 @@ module Browserctl
       YAML
 
       GITIGNORE_CONTENT = <<~GITIGNORE
-        # Cookie session exports — contain credentials, never commit
-        sessions/
+        # State bundles — contain credentials, never commit
+        state/
       GITIGNORE
 
       def self.run(_args)
         FileUtils.mkdir_p(".browserctl/workflows")
         FileUtils.touch(".browserctl/workflows/.keep")
 
-        FileUtils.mkdir_p(".browserctl/sessions")
+        FileUtils.mkdir_p(".browserctl/state")
 
         gitignore_path = ".browserctl/.gitignore"
         File.write(gitignore_path, GITIGNORE_CONTENT) unless File.exist?(gitignore_path)
@@ -30,10 +31,22 @@ module Browserctl
         config_path = ".browserctl/config.yml"
         File.write(config_path, CONFIG_TEMPLATE) unless File.exist?(config_path)
 
-        puts "Initialised browserctl project:"
-        puts "  .browserctl/workflows/   (place workflow .rb files here)"
-        puts "  .browserctl/sessions/    (cookie exports — git-ignored)"
-        puts "  .browserctl/config.yml   (project settings)"
+        payload = {
+          ok: true,
+          paths: {
+            workflows: ".browserctl/workflows",
+            state: ".browserctl/state",
+            config: ".browserctl/config.yml"
+          }
+        }
+        OutputFormat.current.emit(payload) do
+          <<~TEXT.chomp
+            Initialised browserctl project:
+              .browserctl/workflows/   (place workflow .rb files here)
+              .browserctl/state/       (state bundles — git-ignored)
+              .browserctl/config.yml   (project settings)
+          TEXT
+        end
       end
     end
   end