browserctl 0.10.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,36 @@ 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
 

data/lib/browserctl/flow.rb

@@ -186,9 +186,30 @@ module Browserctl
     end
   end
 
+  @flow_registry_mutex = Mutex.new
+  @flow_registry       = {}
+
   def self.flow(name, &block)
     raise ArgumentError, "Browserctl.flow requires a block" unless block
 
-    Flow.new(name).tap { |f| f.instance_exec(&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

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../../flow"
+
+# Clicks the "Authorize <app>" button on a GitHub OAuth consent screen.
+#
+# Assumes the user is already signed in to GitHub and the page is parked
+# on the consent URL — this flow does not handle the credential entry
+# step. Use a separate workflow or flow to land on the consent page first.
+Browserctl.flow("oauth_github") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Click the Authorize button on a GitHub OAuth consent screen."
+
+  # The default selector targets the green Authorize submit button on
+  # github.com/login/oauth/authorize. GitHub keeps name="authorize" stable
+  # across UI revisions; override only if you're testing against a forked
+  # GitHub Enterprise instance with a customised template.
+  param :authorize_selector, default: 'button[name="authorize"][value="1"]'
+
+  precondition("on a github oauth consent page") do
+    page.url.include?("/login/oauth/authorize")
+  end
+
+  step("click authorize") do
+    page.click(authorize_selector)
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../../flow"
+
+# Clicks the Continue / Allow button on a Google OAuth consent screen.
+#
+# Assumes the user is already signed in to Google and the page is parked
+# on accounts.google.com showing the consent prompt. This flow does not
+# pick an account from the chooser, enter a password, or solve 2FA —
+# compose those before calling this flow.
+#
+# Google rotates consent UI more often than GitHub, so the default
+# selector is a best-effort match against the modern Material 3 button.
+# Override if your account or app version sees a different layout.
+Browserctl.flow("oauth_google") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Click the Continue/Allow button on a Google OAuth consent screen."
+
+  param :continue_selector, default: 'button[jsname="LgbsSe"]'
+
+  precondition("on a google oauth consent page") do
+    url = page.url
+    url.include?("accounts.google.com") && (url.include?("/oauth") || url.include?("/signin/oauth"))
+  end
+
+  step("click continue") do
+    page.click(continue_selector)
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "../../flow"
+
+module Browserctl
+  module Flows
+    # RFC 6238 TOTP code generation from a base32 secret.
+    # Pure Ruby; no network and no external gem.
+    module TOTP
+      module_function
+
+      def generate(secret, at: Time.now, digits: 6, period: 30, digest: "SHA1")
+        counter   = (at.to_i / period).to_i
+        key       = decode_base32(secret)
+        counter_b = [counter].pack("Q>") # 64-bit big-endian
+        hmac      = OpenSSL::HMAC.digest(digest, key, counter_b)
+        offset    = hmac[-1].ord & 0x0f
+        truncated = hmac[offset, 4].unpack1("N") & 0x7fffffff
+        truncated.to_s.rjust(digits, "0")[-digits..]
+      end
+
+      BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+
+      def decode_base32(secret)
+        cleaned = secret.to_s.upcase.gsub(/[^A-Z2-7]/, "")
+        bits = cleaned.each_char.map { |c| char_to_bits(c) }.join
+        whole_bytes = bits[0, (bits.length / 8) * 8]
+        whole_bytes.scan(/.{8}/).map { |b| b.to_i(2).chr }.join
+      end
+
+      def char_to_bits(char)
+        idx = BASE32_ALPHABET.index(char) or
+          raise ArgumentError, "invalid base32 char #{char.inspect}"
+        idx.to_s(2).rjust(5, "0")
+      end
+    end
+  end
+end
+
+Browserctl.flow("totp_2fa") do
+  version "1.0.0"
+  requires_browserctl "0.11.0"
+  desc "Generate an RFC 6238 TOTP code from a base32 secret and type it into the page."
+
+  param :secret,   required: true, secret: true
+  param :selector, required: true
+  param :digits,   default: 6
+  param :period,   default: 30
+
+  precondition("page proxy is present") { !page.nil? }
+
+  step("compute and fill code") do
+    code = Browserctl::Flows::TOTP.generate(
+      secret,
+      digits: digits.to_i,
+      period: period.to_i
+    )
+    page.fill(selector, code)
+  end
+end