browserctl 0.11.0 → 0.13.0

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

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
-require "timeout"
+require_relative "callable_definition"
 require_relative "errors"
-require_relative "secret_resolvers"
 
 module Browserctl
-  FlowParamDef    = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
-  FlowStepDef     = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
   FlowConditionDef = Struct.new(:kind, :label, :block, keyword_init: true)
 
+  # Back-compat aliases — flow_wrapper specs reference these directly.
+  FlowParamDef = CallableDefinition::ParamDef
+  FlowStepDef  = CallableDefinition::StepDef
+
   class FlowContext
     attr_reader :page, :client, :params
 
@@ -29,31 +30,28 @@ module Browserctl
     end
   end
 
-  class Flow
+  class Flow < CallableDefinition
     SEMVER_RE = /\A\d+\.\d+\.\d+\z/
 
-    attr_reader :name,
-                :version_string,
-                :description,
-                :param_defs,
-                :steps,
+    attr_reader :version_string,
                 :preconditions,
                 :postconditions,
                 :produces_state_block,
                 :min_browserctl_version
 
     def initialize(name)
-      @name                   = name.to_s
+      super
       @version_string         = "0.0.0"
-      @description            = nil
-      @param_defs             = {}
-      @steps                  = []
       @preconditions          = []
       @postconditions         = []
       @produces_state_block   = nil
       @min_browserctl_version = nil
     end
 
+    def callable_kind
+      :flow
+    end
+
     def version(value)
       validate_semver!(value, label: "version")
       @version_string = value.to_s
@@ -64,27 +62,6 @@ module Browserctl
       @min_browserctl_version = value.to_s
     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] = FlowParamDef.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, "flow step '#{label}' requires a block" unless block
-
-      @steps << FlowStepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
-    end
-
     def precondition(label = "precondition", &block)
       raise ArgumentError, "precondition '#{label}' requires a block" unless block
 
@@ -103,6 +80,24 @@ module Browserctl
       @produces_state_block = block
     end
 
+    # Definition-time guard against cross-type composition. A flow may only
+    # compose other flows; pulling steps from a workflow would smuggle
+    # `store`/`fetch` into a flow context that has no daemon-backed
+    # persistence.
+    def compose(target_name)
+      name = target_name.to_s
+      if Browserctl.respond_to?(:lookup_workflow) && Browserctl.lookup_workflow(name)
+        raise ArgumentError,
+              "flow '#{@name}' cannot compose workflow '#{name}': flows return state, " \
+              "workflows share state — composition across kinds is not supported"
+      end
+
+      source = Browserctl.lookup_flow(name)
+      raise ArgumentError, "flow '#{name}' not found for composition" unless source
+
+      @steps.concat(source.steps)
+    end
+
     def run(page: nil, client: nil, **params)
       ctx = FlowContext.new(page: page, client: client, params: resolve_params(params))
 
@@ -121,20 +116,12 @@ module Browserctl
       raise ArgumentError, "#{label} must be MAJOR.MINOR.PATCH (got #{value.inspect})"
     end
 
-    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 FlowParamError, "flow '#{@name}' requires param '#{name}'" if defn.required && val.nil?
+    def missing_param_error(name)
+      FlowParamError.new("flow '#{@name}' requires param '#{name}'")
+    end
 
-        out[name] = val
-      end
+    def step_timeout_error(defn)
+      FlowStepError.new("flow '#{@name}' step '#{defn.label}' timed out after #{defn.timeout}s")
     end
 
     def run_conditions(ctx, conditions, error_class:)
@@ -168,17 +155,6 @@ module Browserctl
             "flow '#{@name}' step '#{defn.label}' failed: #{last_error.message}"
     end
 
-    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 FlowStepError,
-            "flow '#{@name}' step '#{defn.label}' timed out after #{defn.timeout}s"
-    end
-
     def produce_state(ctx)
       return nil unless @produces_state_block
 

data/lib/browserctl/flows/stdlib/cloudflare_solve.rb

@@ -5,8 +5,8 @@ require_relative "../../flow"
 
 # Pauses for a human to solve a Cloudflare challenge (Turnstile, "Just a
 # moment...", interactive checkbox), then verifies the challenge cleared
-# before returning. Optionally saves the post-solve session under a name
-# you can reload later with `state load` or `session_load`.
+# before returning. Optionally saves the post-solve state under a name
+# you can reload later with `state load`.
 #
 # Reuses Browserctl::Detectors.cloudflare? — the server-side detector
 # already shipped in v0.8 — by adapting the client-facing PageProxy to
@@ -34,7 +34,7 @@ Browserctl.flow("cloudflare_solve") do
 
   param :prompt,
         default: "Cloudflare challenge detected. Solve it in the browser, then press Enter to continue."
-  param :state_name # optional — if set, session_save is called after the challenge clears
+  param :state_name # optional — if set, state_save is called after the challenge clears
 
   precondition("page proxy is present") { !page.nil? }
   precondition("cloudflare challenge is present") do
@@ -54,6 +54,6 @@ Browserctl.flow("cloudflare_solve") do
   produces_state do
     next nil unless state_name && client
 
-    client.session_save(state_name)
+    client.state_save(state_name)
   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

data/lib/browserctl/logger.rb

@@ -2,6 +2,8 @@
 
 require "logger"
 require "fileutils"
+require "json"
+require "time"
 
 module Browserctl
   LEVEL_MAP = {
@@ -11,6 +13,16 @@ module Browserctl
     "error" => ::Logger::ERROR
   }.freeze
 
+  # JSONL rotation policy. Stdlib `Logger` rotates by size when given an
+  # integer `shift_age` and `shift_size`.
+  LOG_SHIFT_AGE  = 10                # keep last 10 rotated files
+  LOG_SHIFT_SIZE = 10 * 1024 * 1024  # rotate at 10MB
+
+  # Resolved at call time so tests can override BROWSERCTL_DIR via stub_const.
+  def self.log_dir
+    File.join(BROWSERCTL_DIR, "logs")
+  end
+
   class MultiLogger
     def initialize(*loggers)
       @loggers = loggers
@@ -30,6 +42,37 @@ module Browserctl
     end
   end
 
+  # Formats every log line as a single JSON object: {ts, level, component, msg, ...}.
+  # If the message is a Hash, its keys are merged so callers can attach
+  # structured context, e.g. `logger.info(event: "x", session: id)`.
+  class JsonlFormatter
+    def initialize(component:)
+      @component = component
+    end
+
+    def call(severity, time, _progname, msg)
+      record = {
+        ts: time.utc.iso8601(3),
+        level: severity,
+        component: @component
+      }
+
+      case msg
+      when Hash
+        explicit = msg[:msg] || msg["msg"]
+        record[:msg] = explicit if explicit
+        record.merge!(msg.reject { |k, _| k.to_s == "msg" })
+      when Exception
+        record[:msg] = "#{msg.class}: #{msg.message}"
+        record[:backtrace] = Array(msg.backtrace).first(10)
+      else
+        record[:msg] = msg.to_s
+      end
+
+      "#{JSON.generate(record)}\n"
+    end
+  end
+
   def self.logger
     @logger ||= build_logger("info")
   end
@@ -38,19 +81,69 @@ module Browserctl
     @logger = instance
   end
 
-  def self.build_logger(level_name, log_path: nil)
+  # Build a logger that writes:
+  #   - human-readable lines to stderr (unchanged behaviour)
+  #   - human-readable lines to log_path: when given (the daemon tail file)
+  #   - structured JSONL lines to ~/.browserctl/logs/<component>.log (rotating
+  #     10 files x 10MB) when jsonl: is true
+  #
+  # JSONL output is purely additive — existing stderr/stdout behaviour is
+  # preserved so scripted callers see no change.
+  def self.build_logger(level_name, log_path: nil, component: "daemon", jsonl: true)
     level = LEVEL_MAP.fetch(level_name.to_s.downcase, ::Logger::INFO)
-    formatter = proc { |sev, t, prog, msg| "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{msg}\n" }
+    text_formatter = proc do |sev, t, prog, msg|
+      "#{t.strftime('%Y-%m-%dT%H:%M:%S')} #{sev[0]} [#{prog}] #{format_text_msg(msg)}\n"
+    end
+
+    loggers = [make_logger($stderr, level, text_formatter)]
 
-    stderr_log = make_logger($stderr, level, formatter)
-    return stderr_log unless log_path
+    if log_path
+      FileUtils.mkdir_p(File.dirname(log_path), mode: 0o700)
+      FileUtils.touch(log_path)
+      File.chmod(0o600, log_path)
+      loggers << make_logger(log_path, level, text_formatter)
+    end
 
-    FileUtils.mkdir_p(File.dirname(log_path), mode: 0o700)
-    FileUtils.touch(log_path)
-    File.chmod(0o600, log_path)
-    file_log = make_logger(log_path, level, formatter)
-    MultiLogger.new(stderr_log, file_log)
+    if jsonl
+      jsonl_logger = build_jsonl_logger(level, component)
+      loggers << jsonl_logger if jsonl_logger
+    end
+
+    loggers.length == 1 ? loggers.first : MultiLogger.new(*loggers)
+  end
+
+  # Returns a stdlib Logger writing JSON-Lines records to
+  # ~/.browserctl/logs/<component>.log with size-based rotation. Returns nil
+  # (and stays silent) if the directory cannot be created so logging never
+  # crashes the daemon.
+  # LogDevice that suppresses stdlib's "# Logfile created on ..." header so
+  # the resulting file is pure JSON Lines.
+  class HeaderlessLogDevice < ::Logger::LogDevice
+    def add_log_header(_file); end
+  end
+
+  def self.build_jsonl_logger(level, component)
+    dir = log_dir
+    FileUtils.mkdir_p(dir, mode: 0o700)
+    path = File.join(dir, "#{component}.log")
+    device = HeaderlessLogDevice.new(path, shift_age: LOG_SHIFT_AGE, shift_size: LOG_SHIFT_SIZE)
+    log = ::Logger.new(device)
+    log.level     = level
+    log.progname  = component
+    log.formatter = JsonlFormatter.new(component: component)
+    log
+  rescue StandardError
+    nil
+  end
+
+  def self.format_text_msg(msg)
+    case msg
+    when Hash      then (msg[:msg] || msg["msg"] || msg.inspect).to_s
+    when Exception then "#{msg.class}: #{msg.message}"
+    else                msg.to_s
+    end
   end
+  private_class_method :format_text_msg
 
   def self.make_logger(device, level, formatter)
     log = ::Logger.new(device)