browserctl 0.10.0 → 0.12.0

data/lib/browserctl/workflow.rb

@@ -3,20 +3,80 @@
 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"
 
 module Browserctl
+  # Workflow-file format version. Workflows are Ruby files; the schema gate
+  # is a top-of-file comment header:
+  #
+  #   # format_version: 1
+  #
+  # Unlike bundles and recordings, an unsupported or missing version on a
+  # workflow file is a *warning*, not a hard failure. Workflows are
+  # human-authored Ruby — the loader prefers to surface drift via stderr
+  # and let the file run, rather than block execution. See
+  # docs/reference/format-versions.md.
+  WORKFLOW_FORMAT_VERSION = 1
+  SUPPORTED_WORKFLOW_FORMAT_VERSIONS = [WORKFLOW_FORMAT_VERSION].freeze
+
+  # Matches a leading-line comment of the form `# format_version: <int>`.
+  # Tolerates leading whitespace inside the comment body and ignores the
+  # `# frozen_string_literal: true` magic comment that conventionally
+  # precedes it.
+  WORKFLOW_FORMAT_VERSION_HEADER = /^\s*#\s*format_version:\s*(\d+)\s*$/
+
+  # Parses the `# format_version: N` header from a workflow file's source.
+  # Scans only the contiguous leading comment block (and blank lines) so
+  # the header cannot be smuggled in mid-file. Returns the integer if
+  # present, or nil if the file has no version header.
+  def self.parse_workflow_format_version(source)
+    source.each_line do |line|
+      stripped = line.strip
+      next if stripped.empty?
+      break unless stripped.start_with?("#")
+
+      if (m = line.match(WORKFLOW_FORMAT_VERSION_HEADER))
+        return Integer(m[1])
+      end
+    end
+    nil
+  end
+
+  # Reads a workflow file and warns to stderr when the `format_version:`
+  # header is missing or declares an unsupported version. Always returns
+  # the parsed integer (or nil) — never raises. Callers should still
+  # `load` the file regardless.
+  def self.verify_workflow_format_version!(path)
+    source = File.read(path)
+    version = parse_workflow_format_version(source)
+
+    if version.nil?
+      warn "[browserctl] workflow #{path} is missing a `# format_version: N` header " \
+           "(expected #{WORKFLOW_FORMAT_VERSION}); proceeding anyway"
+    elsif !SUPPORTED_WORKFLOW_FORMAT_VERSIONS.include?(version)
+      warn "[browserctl] workflow #{path} format_version=#{version} is not supported " \
+           "(expected #{WORKFLOW_FORMAT_VERSION}); proceeding anyway"
+    end
+
+    version
+  end
+
   ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
   StepResult = Struct.new(:name, :ok, :error, keyword_init: true)
   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 +104,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 +128,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 +186,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 +229,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 +338,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 +396,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 +418,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] == Browserctl::Error::Codes::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 +492,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,13 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Patrick
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -127,8 +126,8 @@ description: Named browser sessions, Ruby workflow DSL, and a token-efficient DO
 email:
 - patrick204nqh@gmail.com
 executables:
-- browserd
 - browserctl
+- browserd
 extensions: []
 extra_rdoc_files: []
 files:
@@ -174,26 +173,50 @@ 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/migrate.rb
 - lib/browserctl/commands/page.rb
 - lib/browserctl/commands/record.rb
 - lib/browserctl/commands/resume.rb
 - 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/trace.rb
 - lib/browserctl/commands/workflow.rb
 - lib/browserctl/constants.rb
+- lib/browserctl/crash_report.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/error/codes.rb
+- lib/browserctl/error/exit_codes.rb
+- lib/browserctl/error/suggested_actions.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/format_version.rb
 - lib/browserctl/logger.rb
+- lib/browserctl/migrations.rb
 - lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
+- lib/browserctl/redactor.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/rubocop/cops/typed_error.rb
 - lib/browserctl/runner.rb
 - lib/browserctl/secret_resolver_registry.rb
 - lib/browserctl/secret_resolvers.rb
@@ -206,19 +229,35 @@ files:
 - lib/browserctl/server/handlers/cookies.rb
 - lib/browserctl/server/handlers/daemon_control.rb
 - lib/browserctl/server/handlers/devtools.rb
+- lib/browserctl/server/handlers/error_payload.rb
 - lib/browserctl/server/handlers/hitl.rb
 - lib/browserctl/server/handlers/interaction.rb
 - lib/browserctl/server/handlers/navigation.rb
 - 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
@@ -229,7 +268,6 @@ metadata:
   bug_tracker_uri: https://github.com/patrick204nqh/browserctl/issues
   documentation_uri: https://github.com/patrick204nqh/browserctl/tree/main/docs
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -244,8 +282,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Persistent browser automation daemon and CLI for AI agents and developer
   workflows