browserctl 0.10.0 → 0.11.0

data/lib/browserctl/workflow/flow_wrapper.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../constants"
+
+module Browserctl
+  module Workflow
+    # Renders a `Browserctl.flow` definition that wraps a promoted workflow.
+    # The flow becomes a globally-registered, parameterised handle that runs
+    # the underlying workflow via `Runner#run_workflow`. Params are inferred
+    # from the workflow's `param_defs` so callers see the same surface area
+    # they would on the workflow itself.
+    #
+    # Wrapping (rather than translating step-by-step) keeps the workflow as
+    # the single source of truth: edits to the workflow file flow through
+    # to the wrapper without regeneration.
+    module FlowWrapper
+      module_function
+
+      def target_dir
+        File.join(Browserctl::BROWSERCTL_DIR, "flows")
+      end
+
+      def target_path(name)
+        File.join(target_dir, "#{name}.rb")
+      end
+
+      # @param defn [Browserctl::WorkflowDefinition]
+      # @return [String] Ruby source for a flow file
+      def render(defn)
+        params = defn.param_defs.values.map { |p| render_param(p) }.join("\n")
+        desc   = defn.description || "Promoted from workflow '#{defn.name}'"
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require "browserctl/flow"
+          require "browserctl/runner"
+
+          # Auto-generated flow wrapper for workflow '#{defn.name}'.
+          # Edit the underlying workflow file rather than this wrapper.
+          Browserctl.flow(#{defn.name.inspect}) do
+            version "1.0.0"
+            requires_browserctl "0.11.0"
+            desc #{desc.inspect}
+
+          #{params.gsub(/^/, '  ') unless params.empty?}
+
+            step("run workflow #{defn.name}") do
+              Browserctl::Runner.new.run_workflow(#{defn.name.inspect}, **params)
+            end
+          end
+        RUBY
+      end
+
+      # @param defn [Browserctl::WorkflowDefinition]
+      # @param overwrite [Boolean]
+      # @param dir [String, nil] override target dir (testing)
+      # @return [String] path written
+      def write(defn, overwrite: true, dir: nil)
+        path = dir ? File.join(dir, "#{defn.name}.rb") : target_path(defn.name)
+        if File.exist?(path) && !overwrite
+          raise "flow wrapper already exists at #{path} (pass overwrite: true to replace)"
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, render(defn))
+        path
+      end
+
+      def render_param(param)
+        opts = []
+        opts << "required: true" if param.required
+        opts << "secret: true"   if param.secret && !param.secret_ref
+        opts << "secret_ref: #{param.secret_ref.inspect}" if param.secret_ref
+        opts << "default: #{param.default.inspect}" unless param.default.nil?
+        suffix = opts.empty? ? "" : ", #{opts.join(', ')}"
+        "param :#{param.name}#{suffix}"
+      end
+    end
+  end
+end

data/lib/browserctl/workflow/promoter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../constants"
+require_relative "promotion_ledger"
+require_relative "flow_wrapper"
+
+module Browserctl
+  module Workflow
+    # Promotes a workflow file from the project-local `.browserctl/workflows/`
+    # directory to the user-global `~/.browserctl/workflows/` directory, where
+    # it is invocable from any project.
+    #
+    # Promotion is gated by `PromotionLedger.clean_streak`: a workflow must
+    # have at least `threshold` consecutive clean `--check` runs before it
+    # can be promoted. `--force` overrides the gate.
+    module Promoter
+      class IneligibleError < StandardError
+        attr_reader :streak, :threshold
+
+        def initialize(workflow:, streak:, threshold:)
+          @streak = streak
+          @threshold = threshold
+          super(
+            "workflow '#{workflow}' has #{streak} clean --check run(s); " \
+            "needs #{threshold}. Run `browserctl workflow run #{workflow} --check` " \
+            "until clean, or pass --force to override."
+          )
+        end
+      end
+
+      class NotFoundError < StandardError; end
+
+      module_function
+
+      DEFAULT_SOURCE_DIR = ".browserctl/workflows"
+
+      def target_dir
+        File.join(Browserctl::BROWSERCTL_DIR, "workflows")
+      end
+
+      def source_path(workflow, source_dir: DEFAULT_SOURCE_DIR)
+        File.join(source_dir, "#{workflow}.rb")
+      end
+
+      def target_path(workflow)
+        File.join(target_dir, "#{workflow}.rb")
+      end
+
+      # @param workflow [String]
+      # @param force [Boolean]
+      # @param threshold [Integer]
+      # @param source_dir [String] override the source directory (testing)
+      # @param ledger_path [String] override the ledger path (testing)
+      # @return [Hash] `{ workflow:, source:, target:, streak:, threshold:, forced: }`
+      def promote(workflow:, force: false, threshold: PromotionLedger::DEFAULT_THRESHOLD, # rubocop:disable Metrics/ParameterLists
+                  as_flow: false, source_dir: DEFAULT_SOURCE_DIR,
+                  ledger_path: PromotionLedger.ledger_path, flow_dir: nil)
+        src = source_path(workflow, source_dir: source_dir)
+        raise NotFoundError, "workflow file not found: #{src}" unless File.exist?(src)
+
+        streak = PromotionLedger.clean_streak(workflow: workflow, path: ledger_path)
+        unless force || streak >= threshold
+          raise IneligibleError.new(workflow: workflow, streak: streak, threshold: threshold)
+        end
+
+        dst = target_path(workflow)
+        FileUtils.mkdir_p(File.dirname(dst))
+        FileUtils.cp(src, dst)
+
+        result = {
+          workflow: workflow,
+          source: src,
+          target: dst,
+          streak: streak,
+          threshold: threshold,
+          forced: force && streak < threshold
+        }
+
+        result[:flow] = wrap_as_flow(workflow, dst, flow_dir) if as_flow
+        result
+      end
+
+      # Loads the just-promoted workflow file, infers params from its
+      # WorkflowDefinition, and writes a flow wrapper at `flow_dir`
+      # (defaults to `~/.browserctl/flows/<name>.rb`).
+      def wrap_as_flow(workflow, workflow_path, flow_dir)
+        load workflow_path
+        defn = Browserctl.lookup_workflow(workflow.to_s) or
+          raise NotFoundError, "workflow '#{workflow}' did not register after load"
+
+        FlowWrapper.write(defn, overwrite: true, dir: flow_dir)
+      end
+    end
+  end
+end

data/lib/browserctl/workflow/promotion_ledger.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+require_relative "../constants"
+
+module Browserctl
+  module Workflow
+    # Append-only JSONL ledger of `workflow run --check` outcomes per workflow.
+    # Used as the gate for `workflow promote`: only workflows with a sufficient
+    # streak of clean runs are eligible for promotion to `~/.browserctl/workflows/`.
+    #
+    # Record schema (one JSONL line):
+    #   { "ts": "2026-05-10T12:00:00Z", "workflow": "name", "verdict": "clean" }
+    module PromotionLedger
+      LEDGER_BASENAME = "check_ledger.jsonl"
+      DEFAULT_THRESHOLD = 3
+      VALID_VERDICTS = %i[clean drift fail].freeze
+
+      module_function
+
+      def ledger_path
+        File.join(Browserctl::BROWSERCTL_DIR, LEDGER_BASENAME)
+      end
+
+      # Append a verdict for a workflow run.
+      # @param workflow [String]
+      # @param verdict [Symbol] :clean, :drift, or :fail
+      # @param path [String] override (testing)
+      def record(workflow:, verdict:, path: ledger_path, at: Time.now.utc)
+        return unless VALID_VERDICTS.include?(verdict)
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.open(path, "a") do |f|
+          f.puts JSON.generate(
+            ts: at.iso8601,
+            workflow: workflow.to_s,
+            verdict: verdict.to_s
+          )
+        end
+      end
+
+      # Count the trailing streak of :clean verdicts for a workflow.
+      # A non-clean verdict resets the streak. Drift and fail both break it
+      # — the gate is intentionally strict; users can override with --force.
+      # @return [Integer]
+      def clean_streak(workflow:, path: ledger_path)
+        return 0 unless File.exist?(path)
+
+        streak = 0
+        File.foreach(path) do |line|
+          entry = parse(line) or next
+          next unless entry["workflow"] == workflow.to_s
+
+          if entry["verdict"] == "clean"
+            streak += 1
+          else
+            streak = 0
+          end
+        end
+        streak
+      end
+
+      def parse(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/browserctl/workflow.rb

@@ -3,6 +3,10 @@
 require "timeout"
 require_relative "client"
 require_relative "errors"
+require_relative "flow_registry"
+require_relative "replay/context"
+require_relative "replay/fingerprint_matcher"
+require_relative "replay/snapshot_diff"
 require_relative "secret_resolvers"
 require_relative "session"
 
@@ -12,11 +16,12 @@ module Browserctl
   StepDef = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
 
   class WorkflowContext
-    attr_reader :client
+    attr_reader :client, :replay_context, :params
 
-    def initialize(params, client)
+    def initialize(params, client, replay_context: nil)
       @params = params
       @client = client
+      @replay_context = replay_context
     end
 
     def store(key, value)
@@ -44,7 +49,7 @@ module Browserctl
     end
 
     def page(name)
-      PageProxy.new(name.to_s, @client)
+      PageProxy.new(name.to_s, @client, replay_context: @replay_context)
     end
 
     def open_page(page_name, url: nil)
@@ -68,7 +73,39 @@ module Browserctl
       res
     end
 
+    # Persists the daemon's current cookies + storage as a .bctl bundle.
+    # Optional flow binding lets `load_state` auto-rotate when the bundle
+    # is detected as needing authentication.
+    def save_state(name, flow: nil, origins: nil, encrypt: false)
+      passphrase = encrypt ? ENV.fetch("BROWSERCTL_STATE_PASSPHRASE", nil) : nil
+      res = @client.state_save(name.to_s,
+                               flow: flow&.to_s, origins: origins, passphrase: passphrase)
+      raise WorkflowError, res[:error] if res[:error]
+
+      res
+    end
+
+    # Restores a .bctl bundle. When the daemon detects AUTH_REQUIRED before
+    # applying (e.g. expired cookies in the payload), this rotates the bound
+    # flow and retries — no caller code change required.
+    #
+    # @param on_auth_required [Proc, nil] override the auto-rotate path. The
+    #   block runs in the workflow context, in lieu of invoking the manifest's
+    #   bound flow. Use this when the recovery procedure is bespoke.
+    def load_state(name, on_auth_required: nil)
+      res = @client.state_load(name.to_s)
+      return res unless auth_required_response?(res)
+
+      recover_auth_required_state(name.to_s, res, on_auth_required)
+    end
+    DEPRECATED_LOAD_SESSION_FALLBACK = <<~MSG
+      [browserctl] DEPRECATION: `load_session(name, fallback:, expired_if:)` is superseded by
+      `load_state(name)` with a flow-bound bundle (`save_state(name, flow: :name)`).
+      `load_session` will be removed in v0.12. See docs/concepts/state.md.
+    MSG
+
     def load_session(session_name, fallback: nil, expired_if: nil)
+      warn DEPRECATED_LOAD_SESSION_FALLBACK if fallback || expired_if
       validate_expired_if!(expired_if)
       fallback_name = fallback&.to_s
       res = @client.session_load(session_name)
@@ -94,16 +131,41 @@ module Browserctl
       $stdin.gets.chomp
     end
 
-    def invoke(workflow_name, **override_params)
-      name = workflow_name.to_s
+    def invoke(target_name, page: nil, **override_params)
+      name = target_name.to_s
       guard_circular!(name)
-      track_invoke(name) { run_nested(workflow_name, **override_params) }
+
+      flow = lookup_flow_target(name)
+      if flow
+        track_invoke(name) { run_invoked_flow(flow, page_name: page, **override_params) }
+      else
+        track_invoke(name) { run_nested(target_name, **override_params) }
+      end
     end
 
     def assert(condition, msg = "assertion failed")
       raise WorkflowError, msg unless condition
     end
 
+    # Snapshots the named page and compares its digest against `expected_digest`.
+    # Under `workflow run --check` (a replay context is attached), a mismatch is
+    # recorded as a drift event with reason "post-snapshot mismatch" and the
+    # step still passes. Outside --check, mismatch raises WorkflowError so the
+    # workflow fails fast.
+    def assert_snapshot_stable(page_name, expected_digest:)
+      res = @client.snapshot(page_name.to_s, format: "elements")
+      snapshot = res[:snapshot]
+      actual = Replay::SnapshotDiff.digest(snapshot)
+      return if actual == expected_digest
+
+      msg = "post-snapshot mismatch on :#{page_name} — expected #{expected_digest}, got #{actual}"
+      raise WorkflowError, msg unless @replay_context
+
+      @replay_context.record(command: :assert_snapshot_stable, selector: page_name.to_s,
+                             matched_ref: nil, score: nil, reason: "post-snapshot mismatch")
+      warn "[browserctl replay] #{msg}"
+    end
+
     def compose(*)
       raise WorkflowError,
             "`compose` must be called at the workflow definition level, not inside a step block. " \
@@ -112,6 +174,45 @@ module Browserctl
 
     private
 
+    def auth_required_response?(res)
+      (res[:code] || res["code"]) == "AUTH_REQUIRED"
+    end
+
+    def recover_auth_required_state(name, initial_res, on_auth_required)
+      if on_auth_required
+        on_auth_required.call
+      else
+        flow_name = initial_res[:suggested_flow] || initial_res["suggested_flow"]
+        unless flow_name && !flow_name.to_s.empty?
+          raise WorkflowError,
+                "state '#{name}' needs auth but bundle has no bound flow — " \
+                "save with `save_state('#{name}', flow: :NAME)` or pass on_auth_required:"
+        end
+
+        # Match the daemon's `state load` preflight: it auth-checks the first
+        # open page (insertion order). Passing that same name to the flow
+        # gives stdlib flows a `page` proxy to drive (oauth_github reads
+        # `page.url`, totp_2fa calls `page.fill`, etc.). Falls back to no
+        # page only when nothing is open — `state_save` would have errored
+        # earlier in that case, so this is a defence-in-depth nil.
+        invoke(flow_name, page: first_open_page)
+      end
+
+      after_save = @client.state_save(name)
+      raise WorkflowError, after_save[:error] if after_save[:error]
+
+      retry_res = @client.state_load(name, skip_auth_check: true)
+      raise WorkflowError, retry_res[:error] if retry_res[:error]
+
+      retry_res.merge(rotated: true)
+    end
+
+    def first_open_page
+      res = @client.page_list
+      pages = res[:pages] || res["pages"] || []
+      pages.first
+    end
+
     def validate_expired_if!(expired_if)
       return unless expired_if
 
@@ -182,22 +283,43 @@ module Browserctl
     def run_nested(workflow_name, **override_params)
       Runner.new.run_workflow(workflow_name, **@params, **override_params)
     end
+
+    def lookup_flow_target(name)
+      Browserctl.lookup_flow(name) || begin
+        FlowRegistry.resolve(name)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def run_invoked_flow(flow, page_name:, **params)
+      proxy = page_name ? page(page_name) : nil
+      flow.run(page: proxy, client: @client, **params)
+    end
   end
 
   class PageProxy
-    def initialize(name, client)
-      @name   = name
-      @client = client
+    attr_accessor :replay_context
+
+    def initialize(name, client, replay_context: nil, matcher: nil)
+      @name           = name
+      @client         = client
+      @replay_context = replay_context
+      @matcher        = matcher || Replay::FingerprintMatcher.new
     end
 
     def navigate(url) = unwrap @client.navigate(@name, url)
 
     def fill(selector = nil, value = nil, ref: nil)
-      unwrap @client.fill(@name, selector, value, ref: ref)
+      with_selector_fallback(:fill, selector, ref) do |sel, r|
+        @client.fill(@name, sel, value, ref: r)
+      end
     end
 
     def click(selector = nil, ref: nil)
-      unwrap @client.click(@name, selector, ref: ref)
+      with_selector_fallback(:click, selector, ref) do |sel, r|
+        @client.click(@name, sel, ref: r)
+      end
     end
 
     def snapshot(**)              = unwrap @client.snapshot(@name, **)
@@ -219,15 +341,21 @@ module Browserctl
     def press(key) = unwrap @client.press(@name, key)
 
     def hover(selector = nil, ref: nil)
-      unwrap @client.hover(@name, selector, ref: ref)
+      with_selector_fallback(:hover, selector, ref) do |sel, r|
+        @client.hover(@name, sel, ref: r)
+      end
     end
 
     def upload(selector = nil, path = nil, ref: nil)
-      unwrap @client.upload(@name, selector, path, ref: ref)
+      with_selector_fallback(:upload, selector, ref) do |sel, r|
+        @client.upload(@name, sel, path, ref: r)
+      end
     end
 
     def select(selector = nil, value = nil, ref: nil)
-      unwrap @client.select(@name, selector, value, ref: ref)
+      with_selector_fallback(:select, selector, ref) do |sel, r|
+        @client.select(@name, sel, value, ref: r)
+      end
     end
 
     def dialog_accept(text: nil) = unwrap @client.dialog_accept(@name, text: text)
@@ -235,6 +363,42 @@ module Browserctl
 
     private
 
+    # Issues the wrapped command. If the daemon returns selector_not_found
+    # and a replay context has a fingerprint for this selector, takes a
+    # fresh snapshot, asks the matcher for a candidate, and retries by ref.
+    def with_selector_fallback(cmd, selector, ref)
+      res = yield(selector, ref)
+      return unwrap(res) if !selector_not_found?(res) || ref || !@replay_context || !selector
+
+      fp = @replay_context.fingerprint_for(selector)
+      return unwrap(res) unless fp
+
+      match = @matcher.best(fp, snapshot_entries)
+      unless match
+        @replay_context.record(command: cmd, selector: selector, reason: "no candidate above threshold")
+        return unwrap(res)
+      end
+
+      log_rematch(cmd, selector, match)
+      @replay_context.record(command: cmd, selector: selector,
+                             matched_ref: match.candidate[:ref], score: match.score, reason: "rematch")
+      unwrap(yield(nil, match.candidate[:ref]))
+    end
+
+    def snapshot_entries
+      res = @client.snapshot(@name, format: "elements")
+      Array(res[:snapshot])
+    end
+
+    def selector_not_found?(res)
+      res.is_a?(Hash) && res[:code] == "selector_not_found"
+    end
+
+    def log_rematch(cmd, selector, match)
+      warn "[browserctl replay] #{cmd} selector #{selector.inspect} not found — " \
+           "rematched to ref=#{match.candidate[:ref]} (score=#{format('%.2f', match.score)})"
+    end
+
     def unwrap(res)
       raise WorkflowError, res[:error] if res[:error]
 
@@ -273,8 +437,8 @@ module Browserctl
       @steps.concat(source.steps)
     end
 
-    def call(params, client)
-      ctx = WorkflowContext.new(resolve_params(params), client)
+    def call(params, client, replay_context: nil)
+      ctx = WorkflowContext.new(resolve_params(params), client, replay_context: replay_context)
       execute_steps(ctx)
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-09 00:00:00.000000000 Z
+date: 2026-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -174,6 +174,7 @@ files:
 - lib/browserctl/commands/daemon.rb
 - lib/browserctl/commands/dialog.rb
 - lib/browserctl/commands/fill.rb
+- lib/browserctl/commands/flow.rb
 - lib/browserctl/commands/init.rb
 - lib/browserctl/commands/page.rb
 - lib/browserctl/commands/record.rb
@@ -181,19 +182,32 @@ files:
 - lib/browserctl/commands/screenshot.rb
 - lib/browserctl/commands/session.rb
 - lib/browserctl/commands/snapshot.rb
+- lib/browserctl/commands/state.rb
 - lib/browserctl/commands/storage.rb
 - lib/browserctl/commands/workflow.rb
 - lib/browserctl/constants.rb
 - lib/browserctl/detectors.rb
+- lib/browserctl/detectors/auth_required.rb
 - lib/browserctl/driver.rb
 - lib/browserctl/driver/base.rb
 - lib/browserctl/driver/cdp.rb
 - lib/browserctl/driver/cdp_page.rb
 - lib/browserctl/errors.rb
 - lib/browserctl/flow.rb
+- lib/browserctl/flow_registry.rb
+- lib/browserctl/flows/stdlib/basic_auth.rb
+- lib/browserctl/flows/stdlib/cloudflare_solve.rb
+- lib/browserctl/flows/stdlib/magic_link_email.rb
+- lib/browserctl/flows/stdlib/oauth_github.rb
+- lib/browserctl/flows/stdlib/oauth_google.rb
+- lib/browserctl/flows/stdlib/totp_2fa.rb
 - lib/browserctl/logger.rb
 - lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
+- lib/browserctl/replay/context.rb
+- lib/browserctl/replay/fingerprint_matcher.rb
+- lib/browserctl/replay/snapshot_diff.rb
+- lib/browserctl/replay/telemetry.rb
 - lib/browserctl/runner.rb
 - lib/browserctl/secret_resolver_registry.rb
 - lib/browserctl/secret_resolvers.rb
@@ -212,13 +226,28 @@ files:
 - lib/browserctl/server/handlers/observation.rb
 - lib/browserctl/server/handlers/page_lifecycle.rb
 - lib/browserctl/server/handlers/session.rb
+- lib/browserctl/server/handlers/state.rb
 - lib/browserctl/server/handlers/storage.rb
 - lib/browserctl/server/idle_watcher.rb
 - lib/browserctl/server/page_session.rb
 - lib/browserctl/server/snapshot_builder.rb
 - lib/browserctl/session.rb
+- lib/browserctl/snapshot/annotator.rb
+- lib/browserctl/snapshot/extractor.rb
+- lib/browserctl/snapshot/fingerprint.rb
+- lib/browserctl/snapshot/ref.rb
+- lib/browserctl/snapshot/serializer.rb
+- lib/browserctl/state.rb
+- lib/browserctl/state/bundle.rb
+- lib/browserctl/state/transport.rb
+- lib/browserctl/state/transports/file.rb
+- lib/browserctl/state/transports/one_password.rb
+- lib/browserctl/state/transports/s3.rb
 - lib/browserctl/version.rb
 - lib/browserctl/workflow.rb
+- lib/browserctl/workflow/flow_wrapper.rb
+- lib/browserctl/workflow/promoter.rb
+- lib/browserctl/workflow/promotion_ledger.rb
 homepage: https://github.com/patrick204nqh/browserctl
 licenses:
 - MIT