browserctl 0.9.0 → 0.11.0

data/lib/browserctl/commands/workflow.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "json"
 require_relative "cli_output"
+require_relative "../recording"
+require_relative "../workflow/promoter"
 
 module Browserctl
   module Commands
     module Workflow
       extend CliOutput
 
-      USAGE = "Usage: browserctl workflow <run|list|describe> [args]"
+      USAGE = "Usage: browserctl workflow <run|list|describe|generate|promote> [args]"
 
       def self.run(runner, args)
         sub = args.shift or abort USAGE
@@ -16,18 +19,73 @@ module Browserctl
         when "run"      then run_workflow(runner, args)
         when "list"     then run_list(runner)
         when "describe" then run_describe(runner, args)
+        when "generate" then run_generate(args)
+        when "promote"  then run_promote(args)
         else abort "unknown workflow subcommand '#{sub}'\n#{USAGE}"
         end
       end
 
+      def self.run_promote(args)
+        name = args.shift or abort \
+          "usage: browserctl workflow promote <name> [--force] [--threshold N] [--as-flow]"
+
+        force   = !args.delete("--force").nil?
+        as_flow = !args.delete("--as-flow").nil?
+
+        threshold_idx = args.index("--threshold")
+        threshold = if threshold_idx
+                      val = args.delete_at(threshold_idx + 1)
+                      args.delete_at(threshold_idx)
+                      Integer(val)
+                    else
+                      Browserctl::Workflow::PromotionLedger::DEFAULT_THRESHOLD
+                    end
+
+        result = Browserctl::Workflow::Promoter.promote(
+          workflow: name, force: force, threshold: threshold, as_flow: as_flow
+        )
+        puts JSON.generate(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
+        )
+        exit 1
+      rescue Browserctl::Workflow::Promoter::NotFoundError => e
+        abort "Error: #{e.message}"
+      rescue ArgumentError => e
+        abort "Error: invalid --threshold value: #{e.message}"
+      end
+
+      def self.run_generate(args)
+        name = args.shift or abort \
+          "usage: browserctl workflow generate <recording> [--out PATH]"
+        out_idx = args.index("--out")
+        out = if out_idx
+                args.delete_at(out_idx + 1).tap { args.delete_at(out_idx) }
+              else
+                File.join(".browserctl/workflows", "#{name}.rb")
+              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 })
+      rescue StandardError => e
+        abort "Error generating workflow: #{e.message}"
+      end
+
+      EXIT_CODE = { clean: 0, drift: 2, fail: 1 }.freeze
+
       def self.run_workflow(runner, args)
-        name = args.shift or abort "usage: browserctl workflow run <name|file> [--params file] [--key value ...]"
+        name = args.shift or abort \
+          "usage: browserctl workflow run <name|file> [--check] [--params file] [--key value ...]"
         if File.exist?(name)
           before = Browserctl.registry_snapshot.keys
           load File.expand_path(name)
           name = (Browserctl.registry_snapshot.keys - before).first || File.basename(name, ".rb")
         end
 
+        check = !args.delete("--check").nil?
+
         params_file_idx = args.index("--params")
         file_params = {}
         if params_file_idx
@@ -47,8 +105,8 @@ module Browserctl
         end
 
         params = file_params.merge(cli_params)
-        success = runner.run_workflow(name, **params)
-        exit(success ? 0 : 1)
+        verdict = runner.run_workflow(name, check: check, **params)
+        exit(EXIT_CODE.fetch(verdict, 1))
       end
 
       def self.run_list(runner)

data/lib/browserctl/constants.rb

@@ -5,7 +5,7 @@ module Browserctl
   IDLE_TTL         = 30 * 60
   # Increment when a breaking wire protocol change ships (new field names, removed commands, changed response shapes).
   # Clients read this from `ping` to verify compatibility before sending commands.
-  PROTOCOL_VERSION = "2"
+  PROTOCOL_VERSION = "3"
 
   def self.socket_path(name = nil)
     File.join(BROWSERCTL_DIR, name ? "#{name}.sock" : "browserd.sock")

data/lib/browserctl/detectors/auth_required.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Detectors
+    # Detects "you need to log in again" — the signal that flips a workflow's
+    # `load_state` into `state rotate` territory. Lives alongside the older
+    # `Detectors.cloudflare?` and follows the same `(page) -> Result` shape.
+    #
+    # Three independent checks, evaluated in order. The first to fire wins:
+    #
+    #   1. URL → login path. The page is currently sitting on /login,
+    #      /signin, /auth/login, or a similar canonical login route. This
+    #      catches redirect-based auth ("we noticed you're not logged in").
+    #   2. Recent HTTP 401 / 403. The most recent network response on this
+    #      page was an auth challenge from the backend.
+    #   3. Cookie ledger. A caller-supplied list of cookies contains entries
+    #      that have already expired. Useful when the daemon is preflighting
+    #      a bundle before navigating.
+    #
+    # Each check is pure — no daemon dependencies — so the same detector
+    # runs server-side (handlers/observation.rb) and client-side (workflow
+    # `load_state` hook).
+    module AuthRequired
+      Result = Struct.new(:triggered, :code, :reason, :suggested_flow, keyword_init: true) do
+        def to_h
+          { triggered: triggered, code: code, reason: reason, suggested_flow: suggested_flow }.compact
+        end
+      end
+
+      LOGIN_PATH_RE = %r{(?:^|/)(login|signin|sign[-_]in|auth/(?:login|signin)|account/login)(?:/|$|\?)}i
+
+      AUTH_HTTP_STATUSES = [401, 403].freeze
+
+      class << self
+        # Run every check; return the first triggered Result, or a non-
+        # triggered Result if all pass.
+        #
+        # @param page  [#current_url] anything quacking like a Page
+        # @param recent_responses [Array<Hash>] each `{ status:, url: }`; the
+        #   caller is responsible for collecting these (e.g. via Ferrum's
+        #   network.traffic). Empty by default so callers without traffic
+        #   instrumentation still get the URL/cookie checks.
+        # @param cookies [Array<Hash>, nil] each `{ name:, expires: }`;
+        #   `expires` is a unix timestamp. nil to skip the cookie check.
+        # @param suggested_flow [String, nil] flow name to surface when the
+        #   detector fires — populated by callers from the bundle manifest.
+        # @return [Result]
+        def detect(page, recent_responses: [], cookies: nil, suggested_flow: nil)
+          [
+            check_url(page, suggested_flow),
+            check_responses(recent_responses, suggested_flow),
+            check_cookies(cookies, suggested_flow)
+          ].find(&:triggered) || negative
+        end
+
+        # Convenience predicate matching the existing `Detectors.cloudflare?`
+        # style. Callers that just need a boolean can use this.
+        def triggered?(page, **)
+          detect(page, **).triggered
+        end
+
+        private
+
+        def check_url(page, suggested_flow)
+          url = safe_call(page, :current_url).to_s
+          match = LOGIN_PATH_RE.match(url)
+          return negative unless match
+
+          Result.new(triggered: true, code: "redirect_login",
+                     reason: "url '#{url}' matches login path", suggested_flow: suggested_flow)
+        end
+
+        def check_responses(recent_responses, suggested_flow)
+          response = Array(recent_responses).reverse_each.find do |r|
+            AUTH_HTTP_STATUSES.include?(r[:status] || r["status"])
+          end
+          return negative unless response
+
+          status = response[:status] || response["status"]
+          url    = response[:url] || response["url"]
+          Result.new(triggered: true, code: "http_#{status}",
+                     reason: "recent #{status} from #{url}", suggested_flow: suggested_flow)
+        end
+
+        def check_cookies(cookies, suggested_flow)
+          return negative if cookies.nil?
+
+          expired = expired_cookies(cookies)
+          return negative if expired.empty?
+
+          names = expired.map { |c| c[:name] || c["name"] }.compact.join(", ")
+          Result.new(triggered: true, code: "cookie_expired",
+                     reason: "expired cookies: #{names}", suggested_flow: suggested_flow)
+        end
+
+        def expired_cookies(cookies)
+          now = Time.now.to_f
+          Array(cookies).select { |c| cookie_expired?(c, now) }
+        end
+
+        def cookie_expired?(cookie, now)
+          exp = cookie[:expires] || cookie["expires"]
+          return false unless exp
+
+          float = exp.to_f
+          float.positive? && float < now
+        end
+
+        def negative
+          Result.new(triggered: false, code: nil, reason: nil, suggested_flow: nil)
+        end
+
+        def safe_call(obj, method)
+          obj.respond_to?(method) ? obj.public_send(method) : nil
+        end
+      end
+    end
+
+    # Module-level shorthand so callers match the existing `Detectors.cloudflare?` style.
+    def self.auth_required?(page, **)
+      AuthRequired.triggered?(page, **)
+    end
+
+    def self.auth_required(page, **)
+      AuthRequired.detect(page, **)
+    end
+  end
+end

data/lib/browserctl/detectors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "detectors/auth_required"
+
 module Browserctl
   module Detectors
     CLOUDFLARE_SIGNALS = [

data/lib/browserctl/errors.rb

@@ -25,6 +25,42 @@ module Browserctl
   class DaemonUnavailableError < Error; def self.default_code = "daemon_unavailable" end
   class BrowserNotFound < Error; def self.default_code = "browser_not_found" end
 
+  # Raised when the daemon detects that the current page needs authentication —
+  # the canonical signal that a workflow's `load_state` should rotate the bound
+  # flow. Carries the bundle name (when a state load was in progress) and a
+  # 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"
+
+    AUTH_REQUIRED_EXIT_CODE = 7
+
+    attr_reader :state, :suggested_flow, :reason
+
+    def initialize(msg = "authentication required", state: nil, suggested_flow: nil, reason: nil)
+      super(msg)
+      @state          = state
+      @suggested_flow = suggested_flow
+      @reason         = reason
+    end
+
+    def to_response
+      {
+        error: message,
+        code: self.class.default_code,
+        state: state,
+        suggested_flow: suggested_flow,
+        reason: reason
+      }.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 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
 end

data/lib/browserctl/flow.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "timeout"
+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)
+
+  class FlowContext
+    attr_reader :page, :client, :params
+
+    def initialize(page:, params:, client: nil)
+      @page   = page
+      @client = client
+      @params = params
+    end
+
+    def method_missing(name, *args)
+      return @params[name] if args.empty? && @params.key?(name)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @params.key?(name) || super
+    end
+  end
+
+  class Flow
+    SEMVER_RE = /\A\d+\.\d+\.\d+\z/
+
+    attr_reader :name,
+                :version_string,
+                :description,
+                :param_defs,
+                :steps,
+                :preconditions,
+                :postconditions,
+                :produces_state_block,
+                :min_browserctl_version
+
+    def initialize(name)
+      @name                   = name.to_s
+      @version_string         = "0.0.0"
+      @description            = nil
+      @param_defs             = {}
+      @steps                  = []
+      @preconditions          = []
+      @postconditions         = []
+      @produces_state_block   = nil
+      @min_browserctl_version = nil
+    end
+
+    def version(value)
+      validate_semver!(value, label: "version")
+      @version_string = value.to_s
+    end
+
+    def requires_browserctl(value)
+      validate_semver!(value, label: "requires_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
+
+      @preconditions << FlowConditionDef.new(kind: :precondition, label: label, block: block)
+    end
+
+    def postcondition(label = "postcondition", &block)
+      raise ArgumentError, "postcondition '#{label}' requires a block" unless block
+
+      @postconditions << FlowConditionDef.new(kind: :postcondition, label: label, block: block)
+    end
+
+    def produces_state(&block)
+      raise ArgumentError, "produces_state requires a block" unless block
+
+      @produces_state_block = block
+    end
+
+    def run(page: nil, client: nil, **params)
+      ctx = FlowContext.new(page: page, client: client, params: resolve_params(params))
+
+      run_conditions(ctx, @preconditions, error_class: FlowPreconditionError)
+      run_steps(ctx)
+      run_conditions(ctx, @postconditions, error_class: FlowPostconditionError)
+
+      produce_state(ctx)
+    end
+
+    private
+
+    def validate_semver!(value, label:)
+      return if value.to_s.match?(SEMVER_RE)
+
+      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?
+
+        out[name] = val
+      end
+    end
+
+    def run_conditions(ctx, conditions, error_class:)
+      conditions.each do |cond|
+        result = ctx.instance_exec(&cond.block)
+        next if result
+
+        raise error_class,
+              "flow '#{@name}' #{cond.kind} '#{cond.label}' returned #{result.inspect}"
+      rescue FlowError
+        raise
+      rescue StandardError => e
+        raise error_class,
+              "flow '#{@name}' #{cond.kind} '#{cond.label}' raised: #{e.message}"
+      end
+    end
+
+    def run_steps(ctx)
+      @steps.each { |defn| run_step(ctx, defn) }
+    end
+
+    def run_step(ctx, defn)
+      last_error = nil
+      (defn.retry_count + 1).times do
+        execute_step_block(ctx, defn)
+        return
+      rescue StandardError => e
+        last_error = e
+      end
+      raise FlowStepError,
+            "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
+
+      ctx.instance_exec(&@produces_state_block)
+    end
+  end
+
+  @flow_registry_mutex = Mutex.new
+  @flow_registry       = {}
+
+  def self.flow(name, &block)
+    raise ArgumentError, "Browserctl.flow requires a block" unless block
+
+    flow = Flow.new(name).tap { |f| f.instance_exec(&block) }
+    register_flow(flow)
+    flow
+  end
+
+  def self.register_flow(flow)
+    @flow_registry_mutex.synchronize { @flow_registry[flow.name] = flow }
+  end
+
+  def self.lookup_flow(name)
+    @flow_registry_mutex.synchronize { @flow_registry[name.to_s] }
+  end
+
+  def self.flow_registry_snapshot
+    @flow_registry_mutex.synchronize { @flow_registry.dup }
+  end
+
+  def self.flow_registry_reset!
+    @flow_registry_mutex.synchronize { @flow_registry.clear }
+  end
+end

data/lib/browserctl/flow_registry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "flow"
+
+module Browserctl
+  # Discovers and loads flow files from project, user, and bundled stdlib
+  # locations. Project flows shadow user flows, which shadow stdlib flows.
+  #
+  # Files are plain Ruby; loading them is expected to invoke
+  # `Browserctl.flow(name) { ... }`, which registers the flow in the global
+  # registry. Filename should match the registered name (validated lazily —
+  # mismatches are allowed but discouraged).
+  class FlowRegistry
+    SAFE_NAME = /\A[a-zA-Z0-9_-]+\z/
+
+    # Search order: highest-precedence last so later registrations
+    # overwrite earlier ones in the global registry.
+    def self.bundled_dir = File.expand_path("flows/stdlib", __dir__)
+    def self.user_dir    = File.expand_path("~/.browserctl/flows")
+    def self.project_dir = "./.browserctl/flows"
+
+    def self.search_paths
+      [bundled_dir, user_dir, project_dir]
+    end
+
+    # Loads every flow file from every search path. Lower-precedence dirs
+    # run first; project files load last and win on name collisions.
+    def self.load_all
+      search_paths.each do |dir|
+        next unless Dir.exist?(dir)
+
+        Dir.glob(File.join(dir, "*.rb")).each { |f| load f }
+      end
+      Browserctl.flow_registry_snapshot
+    end
+
+    # Resolves a name to a registered flow, loading from disk on demand.
+    # Searches in precedence order: project → user → stdlib. The first
+    # matching file is loaded and the flow returned via the global registry.
+    def self.resolve(name)
+      validate_name!(name)
+      existing = Browserctl.lookup_flow(name)
+      return existing if existing
+
+      search_paths.reverse_each do |dir|
+        candidate = File.join(dir, "#{name}.rb")
+        next unless File.exist?(candidate)
+
+        load candidate
+        flow = Browserctl.lookup_flow(name)
+        return flow if flow
+      end
+      nil
+    end
+
+    def self.list
+      load_all.map { |n, f| { name: n, desc: f.description, version: f.version_string } }
+    end
+
+    def self.validate_name!(name)
+      return if SAFE_NAME.match?(name.to_s)
+
+      raise ArgumentError, "invalid flow name: #{name.inspect} — use letters, digits, _ and - only"
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "../../flow"
+
+# Authenticates with an HTTP Basic Auth-protected URL by navigating to it
+# with credentials embedded in the URL. This avoids the native auth
+# dialog entirely; Chromium ingests the userinfo and supplies it on the
+# request without prompting.
+#
+# Use for sites where the auth challenge is real HTTP Basic. For form-
+# based "username + password" logins, use a workflow with `page.fill`.
+Browserctl.flow("basic_auth") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Navigate to an HTTP Basic Auth URL using credentials embedded in the URL."
+
+  param :url,      required: true
+  param :username, required: true
+  param :password, required: true, secret: true
+
+  precondition("page proxy is present") { !page.nil? }
+
+  step("navigate with embedded credentials") do
+    parsed = URI.parse(url)
+    parsed.user     = URI.encode_www_form_component(username)
+    parsed.password = URI.encode_www_form_component(password)
+    page.navigate(parsed.to_s)
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../../detectors"
+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`.
+#
+# Reuses Browserctl::Detectors.cloudflare? — the server-side detector
+# already shipped in v0.8 — by adapting the client-facing PageProxy to
+# the duck-typed (current_url, body) interface the detector expects.
+module Browserctl
+  module Flows
+    PageDetectorAdapter = Struct.new(:current_url, :body)
+
+    module CloudflareSolve
+      module_function
+
+      def detect?(page_proxy)
+        body = page_proxy.evaluate("document.body && document.body.innerText || ''").to_s
+        adapter = PageDetectorAdapter.new(page_proxy.url, body)
+        Browserctl::Detectors.cloudflare?(adapter)
+      end
+    end
+  end
+end
+
+Browserctl.flow("cloudflare_solve") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Pause for a human to solve a Cloudflare challenge; verify it cleared; optionally capture state."
+
+  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
+
+  precondition("page proxy is present") { !page.nil? }
+  precondition("cloudflare challenge is present") do
+    Browserctl::Flows::CloudflareSolve.detect?(page)
+  end
+
+  step("wait for human signal") do
+    warn "[browserctl] #{prompt}"
+    line = $stdin.gets
+    raise "stdin closed before user signaled" if line.nil?
+  end
+
+  step("verify challenge cleared") do
+    raise "cloudflare challenge still detected after human signal" if Browserctl::Flows::CloudflareSolve.detect?(page)
+  end
+
+  produces_state do
+    next nil unless state_name && client
+
+    client.session_save(state_name)
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../../flow"
+
+# HITL flow for magic-link login: pauses, asks the human to paste the
+# link they received via email, then navigates the page to it.
+#
+# Does NOT read the email mailbox; that would require provider-specific
+# IMAP/Gmail integration which belongs in a vendor flow, not stdlib.
+Browserctl.flow("magic_link_email") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Wait for the human to paste a magic link from their email, then navigate to it."
+
+  param :prompt, default: "Paste the magic link from your email:"
+
+  precondition("page proxy is present") { !page.nil? }
+
+  step("prompt and navigate") do
+    $stderr.print("[browserctl] #{prompt} ")
+    link = $stdin.gets&.strip
+    raise "no magic link provided" if link.nil? || link.empty?
+
+    raise "magic link must start with http:// or https:// (got #{link.inspect})" unless link.match?(%r{\Ahttps?://}i)
+
+    page.navigate(link)
+  end
+end