browserctl 0.11.0 → 0.13.0

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

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../logger"
+require_relative "../redactor"
+require_relative "../secret_resolver_registry"
+require_relative "output_format"
+
+module Browserctl
+  module Commands
+    # `browserctl trace [<session>] [--no-redact]` — pretty timeline of
+    # structured log events across cli.log + daemon.log. Defaults to most
+    # recent session.
+    #
+    # Loose categorisation by inspecting common keys (event/snapshot/request/
+    # error). No schema is enforced — this command is tolerant of any JSONL
+    # produced by Browserctl::JsonlFormatter.
+    #
+    # Redaction: ON by default. Secret values are sourced from current ENV
+    # patterns (`*_TOKEN`, `*_KEY`, `*_SECRET`, `*_PASSWORD`) and any values
+    # captured by `SecretResolverRegistry` during this process. Pass
+    # `--no-redact` to disable (local debugging only). Note: when replaying
+    # historical traces from a previous process, registry-captured values are
+    # gone — only current ENV patterns apply.
+    module Trace
+      USAGE = "Usage: browserctl trace [<session>] [--no-redact]"
+      NO_REDACT_WARNING = "[browserctl] traces include unredacted secret values; " \
+                          "do not paste this output publicly."
+
+      LEVEL_COLORS = {
+        "DEBUG" => "\e[2;37m", # dim grey
+        "INFO" => "\e[36m",    # cyan
+        "WARN" => "\e[33m",    # yellow
+        "ERROR" => "\e[31m" # red
+      }.freeze
+      RESET = "\e[0m"
+
+      CATEGORY_ICONS = {
+        error: "!",
+        snapshot: "S",
+        network: "N",
+        event: "."
+      }.freeze
+
+      OMIT_KEYS = %w[ts level component event msg].freeze
+
+      def self.run(args, log_dir: Browserctl.log_dir, out: $stdout, err: $stderr)
+        abort USAGE if args.include?("-h") || args.include?("--help")
+        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
+
+      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?
+          emit_empty("No log entries found in #{log_dir}", out)
+          return nil
+        end
+
+        records = filter_session(records, session_filter)
+        if records.empty?
+          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
+
+        line = JSON.generate(record)
+        JSON.parse(redactor.redact(line))
+      rescue JSON::ParserError
+        record
+      end
+
+      def self.build_redactor
+        extra = if defined?(Browserctl::SecretResolverRegistry)
+                  Browserctl::SecretResolverRegistry.resolved_values
+                else
+                  []
+                end
+        Browserctl::Redactor.from_env(extra: extra)
+      rescue StandardError
+        Browserctl::Redactor.new(secrets: [])
+      end
+
+      def self.warn_no_redact(err)
+        err&.puts NO_REDACT_WARNING
+      end
+
+      def self.load_records(log_dir)
+        paths = Dir.glob(File.join(log_dir, "{cli,daemon}.log"))
+        records = paths.flat_map do |path|
+          File.foreach(path).filter_map { |line| parse_line(line) }
+        end
+        records.sort_by { |r| r["ts"].to_s }
+      end
+
+      def self.parse_line(line)
+        line = line.strip
+        return nil if line.empty?
+
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Session resolution. When session_id is stamped on records (future PR),
+      # filter/select by it. Otherwise, treat the entire merged stream as one
+      # session — caller can scope by tailing/rotating logs.
+      # TODO: stamp session_id on every log line so this scopes correctly.
+      def self.filter_session(records, session_filter)
+        if session_filter
+          records.select { |r| r["session_id"].to_s == session_filter }
+        else
+          ids = records.map { |r| r["session_id"] }.compact.uniq
+          if ids.empty?
+            records
+          else
+            recent = ids.last
+            records.select { |r| r["session_id"] == recent }
+          end
+        end
+      end
+
+      def self.render(records, out:, redactor: nil)
+        tty = out.respond_to?(:tty?) && out.tty?
+        records.each { |r| out.puts(format_line(r, tty: tty, redactor: redactor)) }
+      end
+
+      def self.format_line(record, tty:, redactor: nil)
+        level = (record["level"] || "INFO").to_s
+        line  = format("%-12<ts>s %<icon>s %-5<level>s %-7<comp>s %-22<label>s %<ctx>s",
+                       ts: format_ts(record["ts"]),
+                       icon: CATEGORY_ICONS.fetch(categorise(record), "."),
+                       level: level,
+                       comp: (record["component"] || "?").to_s,
+                       label: event_label(record),
+                       ctx: context_snippet(record)).rstrip
+
+        line = redactor.redact(line) if redactor
+        tty ? colourise(line, level) : line
+      end
+
+      def self.format_ts(timestamp)
+        Time.iso8601(timestamp.to_s).strftime("%H:%M:%S.%L")
+      rescue ArgumentError, TypeError
+        "??:??:??.???"
+      end
+
+      def self.categorise(record)
+        return :error    if record["level"] == "ERROR" || record["error"]
+        return :snapshot if record["snapshot"]
+        return :network  if record["request"] || record["response"] || record["url"]
+
+        :event
+      end
+
+      def self.event_label(record)
+        (record["event"] || record["snapshot"] || record["request"] ||
+          record["msg"] || "-").to_s.slice(0, 22)
+      end
+
+      # Compact "k=v k=v" snippet of remaining structured keys, capped to keep
+      # the timeline scannable. Skips fields already shown in fixed columns.
+      def self.context_snippet(record)
+        pairs = record.except(*OMIT_KEYS)
+        return "" if pairs.empty?
+
+        pairs.map { |k, v| "#{k}=#{format_value(v)}" }.join(" ").slice(0, 120)
+      end
+
+      def self.format_value(value)
+        case value
+        when String  then value.length > 40 ? "#{value[0, 37]}..." : value
+        when Array   then "[#{value.length}]"
+        when Hash    then "{#{value.keys.length}}"
+        else value.to_s
+        end
+      end
+
+      def self.colourise(line, level)
+        colour = LEVEL_COLORS[level] || ""
+        "#{colour}#{line}#{RESET}"
+      end
+    end
+  end
+end

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/constants.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "errors"
+
 module Browserctl
   BROWSERCTL_DIR   = File.expand_path("~/.browserctl")
   IDLE_TTL         = 30 * 60
@@ -26,7 +28,7 @@ module Browserctl
     1.upto(99) do |i|
       return "d#{i}" unless File.exist?(socket_path("d#{i}"))
     end
-    raise "too many running daemons (limit: 99)"
+    raise Browserctl::Error, "too many running daemons (limit: 99)"
   end
 
   def self.all_daemon_sockets

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/crash_report.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+require "etc"
+
+require_relative "version"
+require_relative "logger"
+
+module Browserctl
+  # Writes a local crash report JSON file when the daemon panics. No telemetry,
+  # no upload — purely a local artifact users can attach to bug reports.
+  #
+  # The writer is intentionally defensive: it must never raise. If anything
+  # goes wrong while writing the file, it falls back to a single
+  # `[crash-report-failed]` line on stderr and returns nil.
+  module CrashReport
+    SCHEMA_VERSION = 1
+    LAST_EVENTS_LIMIT = 50
+
+    # @param error [Exception] the unhandled exception that took the daemon down
+    # @param log_path [String, nil] path to the daemon's JSONL log; the last
+    #   {LAST_EVENTS_LIMIT} valid records are tailed in
+    # @return [String, nil] the path of the written crash file, or nil on failure
+    def self.write(error:, log_path: nil)
+      ts = Time.now.utc
+      filename = "crash-#{ts.iso8601(3).gsub(':', '-')}.json"
+      dir = Browserctl.log_dir
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      path = File.join(dir, filename)
+
+      payload = {
+        schema_version: SCHEMA_VERSION,
+        ts: ts.iso8601(3),
+        daemon_version: Browserctl::VERSION,
+        ruby_version: RUBY_VERSION,
+        os: os_info,
+        error: error_info(error),
+        backtrace: Array(error.backtrace),
+        last_events: tail_events(log_path)
+      }
+
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |f|
+        f.write(JSON.pretty_generate(payload))
+      end
+      path
+    rescue StandardError => e
+      warn "[crash-report-failed] #{e.class}: #{e.message}"
+      nil
+    end
+
+    def self.os_info
+      info = { platform: RUBY_PLATFORM }
+      uname = Etc.uname
+      info[:version] = uname[:version] if uname.is_a?(Hash) && uname[:version]
+      info[:sysname] = uname[:sysname] if uname.is_a?(Hash) && uname[:sysname]
+      info
+    rescue StandardError
+      { platform: RUBY_PLATFORM }
+    end
+    private_class_method :os_info
+
+    def self.error_info(error)
+      info = {
+        class: error.class.name,
+        message: error.message.to_s
+      }
+      info[:code] = error.code if error.respond_to?(:code) && error.code
+      info
+    end
+    private_class_method :error_info
+
+    def self.tail_events(log_path)
+      return [] unless log_path && File.exist?(log_path)
+
+      lines = File.readlines(log_path).last(LAST_EVENTS_LIMIT * 2)
+      events = []
+      lines.reverse_each do |line|
+        line = line.strip
+        next if line.empty?
+
+        begin
+          events.unshift(JSON.parse(line))
+        rescue JSON::ParserError
+          next
+        end
+        break if events.length >= LAST_EVENTS_LIMIT
+      end
+      events
+    rescue StandardError
+      []
+    end
+    private_class_method :tail_events
+  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)

data/lib/browserctl/encryption_service.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module Browserctl
+  # Cryptographic primitives for browserctl-managed payloads.
+  #
+  # Raised when decryption fails (tampered ciphertext or wrong key). Callers
+  # should catch this rather than `OpenSSL::Cipher::CipherError` so they
+  # don't have to take a direct dependency on the underlying cipher library.
+  #
+  # Owns AES-256-GCM cipher setup and PBKDF2 key derivation so callers like
+  # `State::Bundle` don't reach into `OpenSSL::Cipher` directly. The contract
+  # is intentionally narrow:
+  #
+  #   * `derive_keys(passphrase, salt)` returns a `[enc_key, hmac_key]` pair
+  #     derived via PBKDF2-HMAC-SHA256 with `PBKDF2_ITERS` iterations and a
+  #     64-byte output split in half. The first half is the AES-256-GCM key,
+  #     the second is the HMAC-SHA-256 key for the bundle footer.
+  #   * `encrypt(plaintext, key)` returns `nonce || ciphertext || tag`.
+  #   * `decrypt(blob, key)` reverses it; raises `OpenSSL::Cipher::CipherError`
+  #     on tampered blobs / wrong key.
+  #   * `random_salt` / `random_nonce` are exposed so callers can keep bundle
+  #     wire-format assembly in one place without re-deriving sizes.
+  #
+  # The constants here are duplicated in `State::Bundle` only as named
+  # references to the wire format positions; the source of truth lives here.
+  module EncryptionService
+    class DecryptionError < StandardError; end
+
+    SALT_SIZE    = 16
+    NONCE_SIZE   = 12
+    TAG_SIZE     = 16
+    KEY_SIZE     = 32
+    PBKDF2_ITERS = 200_000
+    DIGEST       = "SHA256"
+    CIPHER       = "aes-256-gcm"
+
+    module_function
+
+    # Returns `[enc_key, hmac_key]`, each `KEY_SIZE` bytes.
+    def derive_keys(passphrase, salt)
+      material = OpenSSL::PKCS5.pbkdf2_hmac(passphrase.to_s, salt, PBKDF2_ITERS, KEY_SIZE * 2, DIGEST)
+      [material.byteslice(0, KEY_SIZE), material.byteslice(KEY_SIZE, KEY_SIZE)]
+    end
+
+    # AES-256-GCM. Returns `nonce || ciphertext || tag`.
+    def encrypt(plaintext, key)
+      cipher = OpenSSL::Cipher.new(CIPHER)
+      cipher.encrypt
+      cipher.key = key
+      nonce = SecureRandom.bytes(NONCE_SIZE)
+      cipher.iv = nonce
+      ct = cipher.update(plaintext) + cipher.final
+      nonce + ct + cipher.auth_tag
+    end
+
+    # Inverse of `encrypt`. Raises `DecryptionError` on tampered ciphertext
+    # or wrong key so callers don't need to reach into `OpenSSL::Cipher`.
+    def decrypt(blob, key)
+      nonce      = blob.byteslice(0, NONCE_SIZE)
+      tag        = blob.byteslice(-TAG_SIZE, TAG_SIZE)
+      ciphertext = blob.byteslice(NONCE_SIZE, blob.bytesize - NONCE_SIZE - TAG_SIZE)
+
+      cipher = OpenSSL::Cipher.new(CIPHER)
+      cipher.decrypt
+      cipher.key      = key
+      cipher.iv       = nonce
+      cipher.auth_tag = tag
+      cipher.update(ciphertext) + cipher.final
+    rescue OpenSSL::Cipher::CipherError => e
+      raise DecryptionError, e.message
+    end
+
+    def random_salt
+      SecureRandom.bytes(SALT_SIZE)
+    end
+
+    def random_nonce
+      SecureRandom.bytes(NONCE_SIZE)
+    end
+  end
+end

data/lib/browserctl/error/codes.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Browserctl
+  class Error < StandardError
+    # Canonical enum of stable error code strings emitted on the wire and in
+    # CLI stderr payloads. Codes are SCREAMING_SNAKE_CASE and must remain
+    # stable across releases — agents branch on these deterministically.
+    #
+    # The full sweep that wires every raise site to one of these codes lands
+    # in PR #8 of the v0.12 "Solid" milestone. This module is the single
+    # source of truth those raises will reference.
+    module Codes
+      AUTH_REQUIRED            = "AUTH_REQUIRED"
+      SELECTOR_NOT_FOUND       = "SELECTOR_NOT_FOUND"
+      STATE_EXPIRED            = "STATE_EXPIRED"
+      SECRET_RESOLUTION_FAILED = "SECRET_RESOLUTION_FAILED"
+      DAEMON_UNREACHABLE       = "DAEMON_UNREACHABLE"
+      PROTOCOL_MISMATCH        = "PROTOCOL_MISMATCH"
+      DOMAIN_NOT_ALLOWED       = "DOMAIN_NOT_ALLOWED"
+      KEY_NOT_FOUND            = "KEY_NOT_FOUND"
+      GENERIC                  = "GENERIC"
+
+      ALL = [
+        AUTH_REQUIRED,
+        SELECTOR_NOT_FOUND,
+        STATE_EXPIRED,
+        SECRET_RESOLUTION_FAILED,
+        DAEMON_UNREACHABLE,
+        PROTOCOL_MISMATCH,
+        DOMAIN_NOT_ALLOWED,
+        KEY_NOT_FOUND,
+        GENERIC
+      ].freeze
+
+      def self.all
+        ALL
+      end
+
+      def self.valid?(code)
+        ALL.include?(code)
+      end
+    end
+  end
+end