browserctl 0.10.0 → 0.12.0

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

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)