browserctl 0.12.0 → 0.13.0

data/lib/browserctl/commands/migrate.rb

@@ -4,6 +4,7 @@ require_relative "../migrations"
 require_relative "../errors"
 require_relative "../error/codes"
 require_relative "../error/exit_codes"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -43,21 +44,42 @@ module Browserctl
       end
 
       def self.execute(path, target_version:, dry_run:, out:, err:)
+        format = detect_format!(path, err: err)
+        current = Browserctl::Migrations.detect_version(path, format)
+        emit_detected(format, current, path, out)
+
+        return plan_dry_run(format, current, target_version, out) if dry_run
+
+        result = Browserctl::Migrations.run(path, target_version: target_version)
+        emit_applied(format, current, result, out)
+      end
+
+      def self.detect_format!(path, err:)
         format = Browserctl::Migrations.detect_format(path)
-        unless format
-          err.puts "Error: could not detect format for #{path} (expected .bctl, .jsonl, or .rb)"
-          exit Browserctl::Error::ExitCodes::PROTOCOL_MISMATCH
-        end
+        return format if format
+
+        err.puts "Error: could not detect format for #{path} (expected .bctl, .jsonl, or .rb)"
+        exit Browserctl::Error::ExitCodes::PROTOCOL_MISMATCH
+      end
+      private_class_method :detect_format!
+
+      def self.emit_detected(format, current, path, out)
+        return unless OutputFormat.current.text?
 
-        current = Browserctl::Migrations.detect_version(path, format)
         out.puts "Detected: format=#{format} version=#{current.inspect} path=#{path}"
+      end
+      private_class_method :emit_detected
 
-        if dry_run
-          plan_dry_run(format, current, target_version, out)
+      def self.emit_applied(format, current, result, out)
+        fmt = OutputFormat.current
+        if fmt.json?
+          fmt.emit({ ok: true, format: format, from: result.from, to: result.to,
+                     applied: result.applied.map { |m| { from: m.from_version, to: m.to_version } } },
+                   io: out)
           return
         end
+        return if fmt.silent?
 
-        result = Browserctl::Migrations.run(path, target_version: target_version)
         if result.applied.empty?
           out.puts "No migrations registered for #{format} v#{current}; nothing to do."
         else
@@ -65,11 +87,36 @@ module Browserctl
           result.applied.each { |m| out.puts "  - #{format} v#{m.from_version} -> v#{m.to_version}" }
         end
       end
+      private_class_method :emit_applied
 
       def self.plan_dry_run(format, current, target_version, out)
         target = target_version || latest_target(format, current)
         chain  = Browserctl::Migrations.find_path(format: format, from: current, to: target)
+        emit_plan(format, current, target, chain, out)
+      end
+
+      def self.emit_plan(format, current, target, chain, out)
+        fmt = OutputFormat.current
+        if fmt.json?
+          fmt.emit(plan_payload(format, current, target, chain), io: out)
+          return
+        end
+        return if fmt.silent?
+
+        emit_plan_text(format, current, target, chain, out)
+      end
+      private_class_method :emit_plan
+
+      def self.plan_payload(format, current, target, chain)
+        {
+          format: format, from: current, to: target, dry_run: true,
+          plan: chain&.map { |m| { from: m.from_version, to: m.to_version } },
+          registered: registered_for(format)
+        }
+      end
+      private_class_method :plan_payload
 
+      def self.emit_plan_text(format, current, target, chain, out)
         if chain.nil?
           out.puts "No migration path #{format} v#{current} -> v#{target} (registered: " \
                    "#{registered_for(format).inspect})"
@@ -80,6 +127,7 @@ module Browserctl
           chain.each { |m| out.puts "  - #{format} v#{m.from_version} -> v#{m.to_version}" }
         end
       end
+      private_class_method :emit_plan_text
 
       def self.latest_target(format, current)
         targets = registered_for(format)

data/lib/browserctl/commands/output_format.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Browserctl
+  module Commands
+    # Resolves and applies the unified `--output {json,text,silent}` flag.
+    #
+    # Resolution order: explicit flag value -> `BROWSERCTL_OUTPUT` env var ->
+    # `text` (default).
+    #
+    # Usage from a command:
+    #
+    #   fmt = OutputFormat.from(flag, ENV)
+    #   fmt.emit(payload_hash) { "human readable text" }
+    #
+    # Per the v0.13 contract:
+    #
+    #   text   - prints the human-readable block; this is byte-identical to
+    #            today's output. For most commands the human block already IS
+    #            the JSON payload (legacy CLI shape) so the two collapse.
+    #   json   - prints the JSON payload via `to_json` (no pretty printing).
+    #   silent - prints nothing on stdout. Exit codes still carry the result.
+    #
+    # The current format is also exposed as a process-wide default
+    # (`OutputFormat.current`) so that `CliOutput#print_result` and other
+    # legacy helpers can consult it without every callsite threading the
+    # value through.
+    module OutputFormat
+      VALID = %w[json text silent].freeze
+      DEFAULT = "text"
+      ENV_VAR = "BROWSERCTL_OUTPUT"
+      FLAG = "--output"
+
+      class InvalidFormat < ArgumentError; end
+
+      class Formatter
+        attr_reader :mode
+
+        def initialize(mode)
+          @mode = mode
+        end
+
+        # Print success output for a command.
+        # `payload` is a JSON-serialisable Hash (or Array). `text_block` is
+        # either a String or a block that returns a String — only evaluated
+        # when needed.
+        def emit(payload, text_block = nil, io: $stdout)
+          case @mode
+          when "silent"
+            nil
+          when "json"
+            io.puts payload.to_json
+          else # "text"
+            text = if block_given?
+                     yield
+                   elsif text_block.respond_to?(:call)
+                     text_block.call
+                   elsif text_block.nil?
+                     payload.to_json
+                   else
+                     text_block
+                   end
+            io.puts text
+          end
+        end
+
+        def silent?
+          @mode == "silent"
+        end
+
+        def json?
+          @mode == "json"
+        end
+
+        def text?
+          @mode == "text"
+        end
+      end
+
+      module_function
+
+      # Build a Formatter from an explicit flag value (or nil) and an env hash.
+      def from(flag, env = ENV)
+        raw = flag || env[ENV_VAR] || DEFAULT
+        mode = raw.to_s.strip.downcase
+        mode = DEFAULT if mode.empty?
+        unless VALID.include?(mode)
+          raise InvalidFormat,
+                "invalid --output value '#{raw}' (expected one of: #{VALID.join(', ')})"
+        end
+        Formatter.new(mode)
+      end
+
+      # Strip `--output VALUE` (or `--output=VALUE`) from `args` in place and
+      # return the extracted value (or nil). Recognises the long form only —
+      # there is intentionally no short alias.
+      def extract!(args)
+        i = 0
+        while i < args.length
+          arg = args[i]
+          if arg == FLAG
+            args.delete_at(i)
+            value = args.delete_at(i) or
+              raise InvalidFormat, "missing value for #{FLAG}"
+            return value
+          elsif arg.is_a?(String) && arg.start_with?("#{FLAG}=")
+            value = arg.split("=", 2)[1]
+            args.delete_at(i)
+            return value
+          else
+            i += 1
+          end
+        end
+        nil
+      end
+
+      # Process-wide current format. Set once by the CLI entry point after
+      # parsing the global flag; consulted by helpers that don't otherwise
+      # have a reference to a Formatter (notably `CliOutput#print_result`).
+      def current
+        @current ||= Formatter.new(DEFAULT)
+      end
+
+      def current=(formatter)
+        @current = formatter
+      end
+
+      # Convenience: parse the flag out of `args`, build a Formatter, set it
+      # as current, and return it.
+      def install!(args, env = ENV)
+        flag = extract!(args)
+        fmt  = from(flag, env)
+        self.current = fmt
+        fmt
+      end
+
+      # Reset to default — for tests.
+      def reset!
+        @current = Formatter.new(DEFAULT)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/page.rb

@@ -2,21 +2,25 @@
 
 require "optimist"
 require_relative "cli_output"
+require_relative "snapshot"
+require_relative "screenshot"
 
 module Browserctl
   module Commands
     module Page
       extend CliOutput
 
-      USAGE = "Usage: browserctl page <open|close|list|focus> [args]"
+      USAGE = "Usage: browserctl page <open|close|list|focus|snapshot|screenshot> [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)
+        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)
+        when "snapshot"   then Browserctl::Commands::Snapshot.run(client, args)
+        when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
         else abort "unknown page subcommand '#{sub}'\n#{USAGE}"
         end
       end

data/lib/browserctl/commands/{record.rb → recording.rb}

@@ -4,11 +4,12 @@ require "fileutils"
 require "json"
 require "optimist"
 require "browserctl/recording"
+require_relative "output_format"
 
 module Browserctl
   module Commands
-    class Record
-      USAGE = "Usage: browserctl record start <name> | stop [--out PATH] | status"
+    class Recording
+      USAGE = "Usage: browserctl recording start <name> | stop [--out PATH] | status"
 
       def self.run(args)
         subcmd = args.shift
@@ -17,7 +18,7 @@ module Browserctl
         when "stop"   then run_stop(args)
         when "status" then run_status
         else
-          abort "#{USAGE}\nRun 'browserctl record <subcommand> --help' for details."
+          abort "#{USAGE}\nRun 'browserctl recording <subcommand> --help' for details."
         end
       end
 
@@ -25,29 +26,29 @@ 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>"
+          Optimist.options(args) { banner "Usage: browserctl recording start <name>" }
+          name = args.shift or abort "usage: browserctl recording start <name>"
           abort "Invalid recording name #{name.inspect} — use only letters, digits, _ or -" \
             unless name =~ /\A[a-zA-Z0-9_-]{1,64}\z/
-          Recording.start(name)
-          puts JSON.generate({ ok: true, name: name })
+          Browserctl::Recording.start(name)
+          OutputFormat.current.emit({ ok: true, name: name })
         end
 
         def run_stop(args)
           opts = Optimist.options(args) do
-            banner "Usage: browserctl record stop [--out PATH]"
+            banner "Usage: browserctl recording stop [--out PATH]"
             opt :out, "Output path for workflow file", type: :string, short: "-o"
           end
-          name = Recording.stop
+          name = Browserctl::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 JSON.generate({ ok: true, name: name, path: out })
+          Browserctl::Recording.generate_workflow(name, output_path: out)
+          OutputFormat.current.emit({ ok: true, name: name, path: out })
         end
 
         def run_status
-          active = Recording.active
-          puts JSON.generate({ active: active })
+          active = Browserctl::Recording.active
+          OutputFormat.current.emit({ active: active })
         end
       end
     end

data/lib/browserctl/commands/resume.rb

@@ -14,7 +14,7 @@ module Browserctl
           warn "Error: #{res[:error]}"
           exit 1
         end
-        puts "Page '#{name}' resumed."
+        print_result(res.merge(resumed: name)) { "Page '#{name}' resumed." }
       end
     end
   end

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 screenshot <page> [--out PATH] [--full]"
+          banner "Usage: browserctl page screenshot <name> [--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 screenshot <page> [--out PATH] [--full]"
+        name = args.shift or abort "usage: browserctl page screenshot <name> [--out PATH] [--full]"
         print_result(client.screenshot(name, path: opts[:out], full: opts[:full]))
       end
     end

data/lib/browserctl/commands/snapshot.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "optimist"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -10,11 +11,11 @@ module Browserctl
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl snapshot <page> [--format elements|html] [--diff]"
+          banner "Usage: browserctl page snapshot <name> [--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 snapshot <page> [--format elements|html] [--diff]"
+        name = args.shift or abort "usage: browserctl page snapshot <name> [--format elements|html] [--diff]"
         unless VALID_FORMATS.include?(opts[:format])
           warn "Error: --format must be one of: #{VALID_FORMATS.join(', ')}"
           exit 1
@@ -31,7 +32,11 @@ module Browserctl
             warn "Error: #{res[:error]}"
             exit 1
           end
-          puts(format == "elements" ? JSON.pretty_generate(res[:snapshot]) : res[:html])
+          if format == "elements"
+            OutputFormat.current.emit(res[:snapshot], JSON.pretty_generate(res[:snapshot]))
+          else
+            OutputFormat.current.emit({ html: res[:html] }, res[:html])
+          end
         end
       end
     end

data/lib/browserctl/commands/state.rb

@@ -3,6 +3,7 @@
 require "io/console"
 require "json"
 require_relative "cli_output"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -131,7 +132,7 @@ module Browserctl
         destination = args.shift or abort "usage: browserctl state export <name> <destination>"
         require "browserctl/state"
         result = Browserctl::State.export(name, destination)
-        puts result.to_json
+        OutputFormat.current.emit(result)
       rescue Browserctl::State::Transport::TransportError, Browserctl::Error, ArgumentError => e
         warn "Error: #{e.message}"
         exit 1
@@ -142,7 +143,7 @@ module Browserctl
         source        = args.shift or abort "usage: browserctl state import <source> [--name NAME]"
         require "browserctl/state"
         result = Browserctl::State.import(source, name: name_override)
-        puts result.to_json
+        OutputFormat.current.emit(result)
       rescue Browserctl::State::Transport::TransportError,
              Browserctl::State::Bundle::BundleError,
              Browserctl::Error, ArgumentError => e

data/lib/browserctl/commands/trace.rb

@@ -5,6 +5,7 @@ require "time"
 require_relative "../logger"
 require_relative "../redactor"
 require_relative "../secret_resolver_registry"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -49,27 +50,55 @@ module Browserctl
         args = args.dup
         redact = !args.delete("--no-redact")
         session_filter = args.shift
+        redactor = resolve_redactor(redact, err)
+        records = collect_records(log_dir, session_filter, out)
+        emit_records(records, redactor, out) if records
+      end
 
-        if redact
-          redactor = build_redactor
-        else
-          redactor = nil
-          warn_no_redact(err)
-        end
+      def self.resolve_redactor(redact, err)
+        return nil unless redact
 
+        build_redactor
+      ensure
+        warn_no_redact(err) unless redact
+      end
+
+      def self.collect_records(log_dir, session_filter, out)
         records = load_records(log_dir)
         if records.empty?
-          out.puts "No log entries found in #{log_dir}"
-          return
+          emit_empty("No log entries found in #{log_dir}", out)
+          return nil
         end
 
         records = filter_session(records, session_filter)
         if records.empty?
-          out.puts "No entries match session=#{session_filter}"
-          return
+          emit_empty("No entries match session=#{session_filter}", out)
+          return nil
+        end
+
+        records
+      end
+
+      def self.emit_empty(message, out)
+        OutputFormat.current.emit({ records: [], message: message }, message, io: out)
+      end
+
+      def self.emit_records(records, redactor, out)
+        fmt = OutputFormat.current
+        if fmt.json?
+          fmt.emit({ records: records.map { |r| redact_record(r, redactor) } }, io: out)
+        elsif !fmt.silent?
+          render(records, out: out, redactor: redactor)
         end
+      end
+
+      def self.redact_record(record, redactor)
+        return record unless redactor
 
-        render(records, out: out, redactor: redactor)
+        line = JSON.generate(record)
+        JSON.parse(redactor.redact(line))
+      rescue JSON::ParserError
+        record
       end
 
       def self.build_redactor

data/lib/browserctl/commands/workflow.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "json"
 require_relative "cli_output"
+require_relative "output_format"
 require_relative "../recording"
 require_relative "../workflow/promoter"
 
@@ -44,11 +45,11 @@ module Browserctl
         result = Browserctl::Workflow::Promoter.promote(
           workflow: name, force: force, threshold: threshold, as_flow: as_flow
         )
-        puts JSON.generate(ok: true, **result)
+        OutputFormat.current.emit({ ok: true, **result })
       rescue Browserctl::Workflow::Promoter::IneligibleError => e
-        puts JSON.generate(
-          ok: false, error: "ineligible",
-          message: e.message, streak: e.streak, threshold: e.threshold
+        OutputFormat.current.emit(
+          { ok: false, error: "ineligible",
+            message: e.message, streak: e.streak, threshold: e.threshold }
         )
         exit 1
       rescue Browserctl::Workflow::Promoter::NotFoundError => e
@@ -68,7 +69,7 @@ module Browserctl
               end
         FileUtils.mkdir_p(File.dirname(out))
         Browserctl::Recording.generate_workflow(name, output_path: out, keep_log: true)
-        puts JSON.generate({ ok: true, name: name, path: out })
+        OutputFormat.current.emit({ ok: true, name: name, path: out })
       rescue StandardError => e
         abort "Error generating workflow: #{e.message}"
       end
@@ -111,12 +112,13 @@ module Browserctl
 
       def self.run_list(runner)
         list = runner.list_workflows
-        puts JSON.generate({ workflows: list.map { |w| { name: w[:name], desc: w[:desc] } } })
+        OutputFormat.current.emit({ workflows: list.map { |w| { name: w[:name], desc: 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))
+        payload = runner.describe_workflow(name)
+        OutputFormat.current.emit(payload, JSON.pretty_generate(payload))
       end
     end
   end

data/lib/browserctl/contextual_persistence.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "workflow/recovery_manager"
+
+module Browserctl
+  # Persistence-and-state DSL mixed into {WorkflowContext}. {FlowContext}
+  # does NOT mix this in — that absence is the structural enforcement of
+  # the doctrinal split: flows return state, workflows share state through
+  # the daemon-backed `store`/`fetch` and `.bctl` bundles.
+  #
+  # Hosts must expose `@client` and may expose `@replay_context` (for the
+  # selector-rematch fallback used elsewhere). Auth-required recovery is
+  # delegated to {Workflow::RecoveryManager}, which calls back into the
+  # host's `invoke` so flows bound to a saved bundle can rotate
+  # credentials transparently.
+  module ContextualPersistence
+    def store(key, value)
+      res = @client.store(key.to_s, value)
+      raise WorkflowError, res[:error] if res[:error]
+
+      value
+    end
+
+    def fetch(key)
+      res = @client.fetch(key.to_s)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res[:value]
+    end
+
+    # Persists the daemon's current cookies + storage as a .bctl bundle.
+    # Optional flow binding lets `load_state` auto-rotate when the bundle
+    # is detected as needing authentication.
+    def save_state(name, flow: nil, origins: nil, encrypt: false)
+      passphrase = encrypt ? ENV.fetch("BROWSERCTL_STATE_PASSPHRASE", nil) : nil
+      res = @client.state_save(name.to_s,
+                               flow: flow&.to_s, origins: origins, passphrase: passphrase)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
+    # Restores a .bctl bundle. When the daemon detects AUTH_REQUIRED before
+    # applying (e.g. expired cookies in the payload), this delegates to
+    # {Workflow::RecoveryManager}, which rotates the bound flow and retries
+    # — no caller code change required.
+    #
+    # @param on_auth_required [Proc, nil] override the auto-rotate path. The
+    #   block runs in the workflow context, in lieu of invoking the manifest's
+    #   bound flow. Use this when the recovery procedure is bespoke.
+    def load_state(name, on_auth_required: nil)
+      res = @client.state_load(name.to_s)
+      return res unless Workflow::RecoveryManager.auth_required?(res)
+
+      Workflow::RecoveryManager.new(self).recover(name.to_s, res, on_auth_required: on_auth_required)
+    end
+  end
+end

data/lib/browserctl/driver/cdp.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
 require "ferrum"
-require_relative "base"
 require_relative "cdp_page"
 require_relative "../errors"
 
 module Browserctl
   module Driver
-    class CDP < Base
+    class CDP
       BRAVE_PATHS = {
         darwin: [
           "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
@@ -24,7 +23,7 @@ module Browserctl
         ]
       }.freeze
 
-      def initialize(headless: true, browser: "chrome") # rubocop:disable Lint/MissingSuper
+      def initialize(headless: true, browser: "chrome")
         @headless = headless
         @browser  = browser
         @ferrum   = Ferrum::Browser.new(**ferrum_options)