browserctl 0.11.0 → 0.12.0

data/lib/browserctl/commands/trace.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../logger"
+require_relative "../redactor"
+require_relative "../secret_resolver_registry"
+
+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
+
+        if redact
+          redactor = build_redactor
+        else
+          redactor = nil
+          warn_no_redact(err)
+        end
+
+        records = load_records(log_dir)
+        if records.empty?
+          out.puts "No log entries found in #{log_dir}"
+          return
+        end
+
+        records = filter_session(records, session_filter)
+        if records.empty?
+          out.puts "No entries match session=#{session_filter}"
+          return
+        end
+
+        render(records, out: out, redactor: redactor)
+      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/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/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/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

data/lib/browserctl/error/exit_codes.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "codes"
+
+module Browserctl
+  class Error < StandardError
+    # Stable mapping from a canonical {Browserctl::Error::Codes} string to a
+    # process exit status. The CLI's top-level rescue uses this so AI agents
+    # and shell scripts can branch on `$?` deterministically without parsing
+    # stderr.
+    #
+    # Stability contract:
+    # - Exit code integers are part of the v0.12 stable surface and will not
+    #   be renumbered without a major version bump.
+    # - Unknown / unmapped codes intentionally fall through to {GENERIC} (1)
+    #   so an unfamiliar code never silently surfaces as a non-error (0).
+    #
+    # See docs/reference/exit-codes.md for the operator-facing table.
+    module ExitCodes
+      OK                 = 0
+      GENERIC            = 1
+      DRIFT              = 2
+      AUTH_REQUIRED      = 3
+      DAEMON_UNREACHABLE = 4
+      PROTOCOL_MISMATCH  = 5
+      SELECTOR_NOT_FOUND = 6
+      STATE_EXPIRED      = 7
+
+      # Canonical Codes string → exit status integer. Codes without an entry
+      # (e.g. DOMAIN_NOT_ALLOWED, KEY_NOT_FOUND, SECRET_RESOLUTION_FAILED,
+      # GENERIC) collapse to {GENERIC} for now; they may earn dedicated exit
+      # codes in a future milestone.
+      #
+      # DRIFT (2) is reserved for a future Codes::DRIFT and currently has no
+      # entry in this table — drift-related raises fall through to GENERIC
+      # until that code is introduced.
+      TABLE = {
+        Codes::AUTH_REQUIRED => AUTH_REQUIRED,
+        Codes::DAEMON_UNREACHABLE => DAEMON_UNREACHABLE,
+        Codes::PROTOCOL_MISMATCH => PROTOCOL_MISMATCH,
+        Codes::SELECTOR_NOT_FOUND => SELECTOR_NOT_FOUND,
+        Codes::STATE_EXPIRED => STATE_EXPIRED
+      }.freeze
+
+      # @param code [String, nil] a canonical code from {Browserctl::Error::Codes}
+      # @return [Integer] mapped exit status; {GENERIC} for nil or unknown codes
+      def self.for(code)
+        return GENERIC if code.nil?
+
+        TABLE.fetch(code, GENERIC)
+      end
+    end
+  end
+end

data/lib/browserctl/error/suggested_actions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "codes"
+
+module Browserctl
+  class Error < StandardError
+    # Maps a stable error code (see {Browserctl::Error::Codes}) to a short
+    # imperative sentence telling the operator (or AI agent) what to try
+    # next. Codes without an explicit entry fall back to a generic pointer
+    # to the error reference doc (added in PR #11 of v0.12).
+    module SuggestedActions
+      DEFAULT = "See docs/reference/errors.md for guidance."
+
+      TABLE = {
+        Codes::AUTH_REQUIRED =>
+          "Run the suggested flow to refresh credentials, then retry.",
+        Codes::SELECTOR_NOT_FOUND =>
+          "Re-run snapshot to get fresh refs, then retry with a stable ref or selector.",
+        Codes::STATE_EXPIRED =>
+          "Re-save the state bundle (state save) or rotate it (state rotate).",
+        Codes::SECRET_RESOLUTION_FAILED =>
+          "Verify the secret resolver config and that the underlying secret exists.",
+        Codes::DAEMON_UNREACHABLE =>
+          "Start the daemon with 'browserctl daemon start', then retry.",
+        Codes::PROTOCOL_MISMATCH =>
+          "Upgrade browserctl to a version that supports this artifact's format version.",
+        Codes::DOMAIN_NOT_ALLOWED =>
+          "Add the domain to your policy allowlist or use an allowed URL.",
+        Codes::KEY_NOT_FOUND =>
+          "Verify the key was stored in this daemon session before fetching.",
+        Codes::GENERIC => DEFAULT
+      }.freeze
+
+      # @param code [String, nil] a SCREAMING_SNAKE code from {Codes}
+      # @return [String] suggested action sentence; never nil
+      def self.for(code)
+        TABLE.fetch(code, DEFAULT)
+      end
+    end
+  end
+end

data/lib/browserctl/errors.rb

@@ -1,28 +1,50 @@
 # frozen_string_literal: true
 
+require_relative "error/codes"
+require_relative "error/exit_codes"
+require_relative "error/suggested_actions"
+
 module Browserctl
   # Base error class for all browserctl daemon errors.
   # Subclasses carry a machine-readable `code` that appears in wire responses.
+  # The canonical enum of stable codes lives in {Browserctl::Error::Codes};
+  # the sweep that retrofits every raise to use those codes lands in a later
+  # v0.12 PR.
   # @attr_reader code [String] machine-readable error code
+  # @attr_reader context [Hash] free-form structured fields (selector, path, ...)
   class Error < StandardError
     def self.default_code = "error"
 
-    attr_reader :code
+    attr_reader :code, :context
 
-    def initialize(msg = nil, code: self.class.default_code)
-      @code = code
+    def initialize(msg = nil, code: self.class.default_code, context: {})
+      @code    = code
+      @context = context || {}
       super(msg)
     end
+
+    # Returns the canonical structured payload emitted on the daemon wire and
+    # on CLI stderr. Shape is stable across releases — agents branch on `code`
+    # without parsing prose.
+    # @return [Hash{Symbol => Object}]
+    def to_payload
+      {
+        code: code,
+        message: message,
+        context: context,
+        suggested_action: SuggestedActions.for(code)
+      }
+    end
   end
 
-  class PageNotFound     < Error; def self.default_code = "page_not_found"     end
-  class SelectorNotFound < Error; def self.default_code = "selector_not_found" end
-  class RefNotFound      < Error; def self.default_code = "ref_not_found"      end
-  class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"   end
-  class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
-  class TimeoutError     < Error; def self.default_code = "timeout"            end
-  class KeyNotFound < Error; def self.default_code = "key_not_found" end
-  class DaemonUnavailableError < Error; def self.default_code = "daemon_unavailable" end
+  class PageNotFound     < Error; def self.default_code = "page_not_found" end
+  class SelectorNotFound < Error; def self.default_code = Codes::SELECTOR_NOT_FOUND   end
+  class RefNotFound      < Error; def self.default_code = "ref_not_found"             end
+  class PathNotAllowed   < Error; def self.default_code = "path_not_allowed"          end
+  class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed"        end
+  class TimeoutError     < Error; def self.default_code = "timeout"                   end
+  class KeyNotFound      < Error; def self.default_code = "key_not_found"             end
+  class DaemonUnavailableError < Error; def self.default_code = Codes::DAEMON_UNREACHABLE end
   class BrowserNotFound < Error; def self.default_code = "browser_not_found" end
 
   # Raised when the daemon detects that the current page needs authentication —
@@ -31,7 +53,7 @@ module Browserctl
   # suggested flow (from the bundle manifest) so callers can recover without
   # additional lookups. The CLI maps this code to exit status 7.
   class AuthRequiredError < Error
-    def self.default_code = "AUTH_REQUIRED"
+    def self.default_code = Codes::AUTH_REQUIRED
 
     AUTH_REQUIRED_EXIT_CODE = 7
 
@@ -50,17 +72,25 @@ module Browserctl
         code: self.class.default_code,
         state: state,
         suggested_flow: suggested_flow,
-        reason: reason
+        reason: reason,
+        context: { state: state, suggested_flow: suggested_flow, reason: reason }.compact,
+        suggested_action: SuggestedActions.for(self.class.default_code)
       }.compact
     end
   end
 
   class WorkflowError < Error; def self.default_code = "workflow_error" end
-  class SecretResolverError < WorkflowError; def self.default_code = "secret_resolver_error" end
+  class SecretResolverError < WorkflowError; def self.default_code = Codes::SECRET_RESOLUTION_FAILED end
 
   class FlowError < WorkflowError; def self.default_code = "flow_error" end
   class FlowParamError < FlowError; def self.default_code = "flow_param_error" end
   class FlowPreconditionError < FlowError; def self.default_code = "flow_precondition_failed" end
   class FlowStepError < FlowError; def self.default_code = "flow_step_failed" end
   class FlowPostconditionError < FlowError; def self.default_code = "flow_postcondition_failed" end
+
+  # Raised when a persisted artifact (bundle, recording, workflow, etc.) has a
+  # `version:` header that this build does not know how to read. The full error
+  # code taxonomy lands in WS-2 (PR #7); this class is a forward-reference stub
+  # so WS-1 PRs can already raise the canonical code.
+  class ProtocolMismatch < Error; def self.default_code = Codes::PROTOCOL_MISMATCH end
 end

data/lib/browserctl/format_version.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Browserctl
+  # Format-version header convention.
+  #
+  # Every persisted browserctl artifact declares its format version on the very
+  # first line as `version: <int>`. This module is the convention's single
+  # source of truth; per-format adoption (bundle, recording, workflow) lands in
+  # later WS-1 PRs. See `docs/reference/format-versions.md`.
+  module FormatVersion
+    HEADER_RE = /\Aversion:\s*(\d+)\s*\z/
+
+    module_function
+
+    # Parse the version header from an IO or String. Returns the Integer
+    # version. Raises Browserctl::ProtocolMismatch if the header is missing or
+    # malformed.
+    def parse(io_or_string)
+      first_line = io_or_string.respond_to?(:gets) ? io_or_string.gets : io_or_string.to_s.each_line.first
+      raise ProtocolMismatch, "missing version header" if first_line.nil?
+
+      match = HEADER_RE.match(first_line.chomp)
+      raise ProtocolMismatch, "malformed version header: #{first_line.inspect}" unless match
+
+      Integer(match[1])
+    end
+
+    # Returns the canonical header string for a given integer version.
+    def stamp(version:)
+      raise ArgumentError, "version must be a non-negative Integer" unless version.is_a?(Integer) && version >= 0
+
+      "version: #{version}\n"
+    end
+  end
+end