browserctl 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2662c63f1ab585b29689e8e09ac2c8f7c3214539c440c51da82efc954fc0493
-  data.tar.gz: 3e8f6790cdb3a3a79382f68c3a1fb6235805e6acc96658270d06c4d91ee1098b
+  metadata.gz: e63d2425e4bbd57beefebf31e3f616a3183823f467b08c89ba6a1e2bb32cca0b
+  data.tar.gz: 8f12b646d805237a46b2bba2c194fb91c21834dc78648db97a4f74b0cc672de6
 SHA512:
-  metadata.gz: d729193bb86f061227588d46981d7fc5aaf98ef45956a4f4c5e59ca30c95f02f2a06d0d2e9227e671e0f6fb8a3ffcdd2ec4347cc20bd30bb40b2bef54f8b25c4
-  data.tar.gz: 48170f604f692e980da8956c41f74255e0f16c6a43a13f3ae090377550bc14967a632a8ac01ebe85c7cabde1ff4226638e92fd40329cde0bcb2539c0c4a5c69a
+  metadata.gz: 50521d3c938c009818d85c93b793c55f5ec2b6d7ae64ec0daae5bf337d793f795189f870d1451d5dca18b285c428a2dd48ec1c0b6af210e6e7c3b41a49c14989
+  data.tar.gz: fe973906dbfe35134aaa32c2e3080196febaa99dc4c8858683ceb9a9e41579f9a40b7ca7865af67ba946a6b2acc68dd7bafa31036daafeebe96e23edbd3f53c6

data/CHANGELOG.md

@@ -10,6 +10,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0](https://github.com/patrick204nqh/browserctl/compare/v0.7.0...v0.8.0) (2026-04-29)
+
+
+### Features
+
+* **v0.8:** secret resolver plugin system + load_session fallback ([#54](https://github.com/patrick204nqh/browserctl/issues/54)) ([69737bf](https://github.com/patrick204nqh/browserctl/commit/69737bf10528ad691a31abf916953325637af597))
+
 ## [0.7.0](https://github.com/patrick204nqh/browserctl/compare/v0.6.0...v0.7.0) (2026-04-28)
 
 

data/lib/browserctl/errors.rb

@@ -22,4 +22,7 @@ module Browserctl
   class DomainNotAllowed < Error; def self.default_code = "domain_not_allowed" end
   class TimeoutError     < Error; def self.default_code = "timeout"            end
   class KeyNotFound      < Error; def self.default_code = "key_not_found"      end
+
+  class WorkflowError < StandardError; end
+  class SecretResolverError < WorkflowError; end
 end

data/lib/browserctl/secret_resolver_registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Browserctl
+  class SecretResolverRegistry
+    @mutex    = Mutex.new
+    @registry = {}
+
+    def self.register(resolver_class)
+      instance = resolver_class.new
+      @mutex.synchronize { @registry[resolver_class.scheme] = instance }
+    end
+
+    def self.resolve(secret_ref)
+      scheme, reference = secret_ref.split("://", 2)
+      resolver = @mutex.synchronize { @registry[scheme] }
+      raise SecretResolverError, "unknown secret resolver scheme '#{scheme}'" unless resolver
+      unless resolver.available?
+        raise SecretResolverError,
+              "'#{scheme}://' resolver is not available in this environment"
+      end
+
+      resolver.resolve(reference)
+    rescue SecretResolverError
+      raise
+    rescue StandardError => e
+      raise SecretResolverError, "secret resolution failed for #{secret_ref.inspect}: #{e.message}"
+    end
+
+    def self.registered?(scheme)
+      @mutex.synchronize { @registry.key?(scheme) }
+    end
+
+    def self.reset!
+      @mutex.synchronize { @registry.clear }
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module SecretResolvers
+    class Base
+      def self.scheme
+        raise NotImplementedError, "#{name}.scheme not implemented"
+      end
+
+      def available? = true
+
+      def resolve(_reference)
+        raise NotImplementedError, "#{self.class.name}#resolve not implemented"
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/env.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module SecretResolvers
+    class Env < Base
+      def self.scheme = "env"
+
+      def resolve(reference)
+        ENV.fetch(reference) { raise SecretResolverError, "env var '#{reference}' is not set" }
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/macos_keychain.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Browserctl
+  module SecretResolvers
+    class MacOSKeychain < Base
+      def self.scheme = "keychain"
+
+      def available?
+        RUBY_PLATFORM.include?("darwin") && system("which security > /dev/null 2>&1")
+      end
+
+      def resolve(reference)
+        service, account = reference.split("/", 2)
+        if account.nil?
+          raise SecretResolverError,
+                "keychain reference must be 'service/account', got: #{reference.inspect}"
+        end
+
+        result, status = Open3.capture2("security", "find-generic-password",
+                                        "-a", account, "-s", service, "-w")
+        raise SecretResolverError, "keychain item not found: #{reference}" unless status.success?
+
+        result.chomp
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers/one_password.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Browserctl
+  module SecretResolvers
+    class OnePassword < Base
+      def self.scheme = "op"
+
+      def available?
+        system("which op > /dev/null 2>&1")
+      end
+
+      def resolve(reference)
+        result, status = Open3.capture2("op", "read", "op://#{reference}")
+        raise SecretResolverError, "1Password item not found: op://#{reference}" unless status.success?
+
+        result.chomp
+      end
+    end
+  end
+end

data/lib/browserctl/secret_resolvers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "secret_resolver_registry"
+require_relative "secret_resolvers/base"
+require_relative "secret_resolvers/env"
+require_relative "secret_resolvers/macos_keychain"
+require_relative "secret_resolvers/one_password"
+
+Browserctl::SecretResolverRegistry.register(Browserctl::SecretResolvers::Env)
+Browserctl::SecretResolverRegistry.register(Browserctl::SecretResolvers::MacOSKeychain)
+Browserctl::SecretResolverRegistry.register(Browserctl::SecretResolvers::OnePassword)
+
+user_resolvers = File.expand_path("~/.browserctl/resolvers.rb")
+load user_resolvers if File.exist?(user_resolvers)

data/lib/browserctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Browserctl
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/browserctl/workflow.rb

@@ -2,11 +2,11 @@
 
 require "timeout"
 require_relative "client"
+require_relative "errors"
+require_relative "secret_resolvers"
 
 module Browserctl
-  class WorkflowError < StandardError; end
-
-  ParamDef = Struct.new(:name, :required, :secret, :default, keyword_init: true)
+  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)
 
@@ -67,11 +67,20 @@ module Browserctl
       res
     end
 
-    def load_session(session_name)
+    def load_session(session_name, fallback: nil)
       res = @client.session_load(session_name)
-      raise WorkflowError, res[:error] if res[:error]
+      return res unless res[:error]
 
-      res
+      raise WorkflowError, res[:error] unless fallback
+
+      invoke(fallback.to_s)
+      res2 = @client.session_load(session_name)
+      if res2[:error]
+        raise WorkflowError,
+              "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+      end
+
+      res2
     end
 
     def list_sessions
@@ -172,8 +181,10 @@ module Browserctl
       @description = text
     end
 
-    def param(name, required: false, secret: false, default: nil)
-      @param_defs[name] = ParamDef.new(name: name, required: required, secret: secret, default: default)
+    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
+      secret = true if secret_ref
+      @param_defs[name] =
+        ParamDef.new(name: name, required: required, secret: secret, default: default, secret_ref: secret_ref)
     end
 
     def step(label, retry_count: 0, timeout: nil, &block)
@@ -223,7 +234,11 @@ module Browserctl
 
     def resolve_params(provided)
       @param_defs.each_with_object({}) do |(name, defn), out|
-        val = provided[name] || defn.default
+        val = if defn.secret_ref
+                SecretResolverRegistry.resolve(defn.secret_ref)
+              else
+                provided[name] || defn.default
+              end
         raise WorkflowError, "required param '#{name}' missing" if defn.required && val.nil?
 
         out[name] = val

data/lib/browserctl.rb

@@ -3,6 +3,7 @@
 require_relative "browserctl/version"
 require_relative "browserctl/constants"
 require_relative "browserctl/errors"
+require_relative "browserctl/secret_resolvers"
 require_relative "browserctl/workflow"
 require_relative "browserctl/runner"
 require_relative "browserctl/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Patrick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ferrum
@@ -139,8 +139,6 @@ files:
 - bin/browserd
 - bin/setup
 - examples/cloudflare_hitl.rb
-- examples/smoke/params_file.rb
-- examples/smoke/store_fetch.rb
 - examples/test_automation_practices/advanced/ab_testing.rb
 - examples/test_automation_practices/advanced/broken_images.rb
 - examples/test_automation_practices/advanced/file_download.rb
@@ -191,6 +189,12 @@ files:
 - lib/browserctl/policy.rb
 - lib/browserctl/recording.rb
 - lib/browserctl/runner.rb
+- lib/browserctl/secret_resolver_registry.rb
+- lib/browserctl/secret_resolvers.rb
+- lib/browserctl/secret_resolvers/base.rb
+- lib/browserctl/secret_resolvers/env.rb
+- lib/browserctl/secret_resolvers/macos_keychain.rb
+- lib/browserctl/secret_resolvers/one_password.rb
 - lib/browserctl/server.rb
 - lib/browserctl/server/command_dispatcher.rb
 - lib/browserctl/server/handlers/cookies.rb

data/examples/smoke/params_file.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Smoke test for --params file loading (Task 7.5).
-#
-# Run with:
-#   browserctl workflow run examples/smoke/params_file.rb --params examples/smoke/params_file.yml
-#
-# The workflow logs in using credentials from the params file and asserts
-# the secure area is reached — proving the params were loaded and available.
-
-Browserctl.workflow "smoke/params_file" do
-  desc "Smoke: load credentials from a --params file and use them in a workflow"
-
-  param :username, required: true
-  param :password, required: true, secret: true
-  param :base_url, default: "https://the-internet.herokuapp.com"
-
-  step "open login page" do
-    open_page(:main, url: "#{base_url}/login")
-  end
-
-  step "fill credentials from params file" do
-    puts "  [params] username = #{username.inspect}"
-    puts "  [params] password = (#{password.length} chars, secret)"
-    page(:main).fill("input#username", username)
-    page(:main).fill("input#password", password)
-    page(:main).click("button[type=submit]")
-  end
-
-  step "assert login succeeded" do
-    page(:main).wait(".flash.success", timeout: 10)
-    assert page(:main).url.include?("/secure"), "expected redirect to /secure — params may not have loaded"
-    puts "  [ok] reached secure area — params file loaded correctly"
-  end
-end

data/examples/smoke/store_fetch.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Smoke test for WorkflowContext#store / #fetch (Task 7.3).
-#
-# Uses the-internet's dynamic loading example: click Start, wait for "Hello World!",
-# capture the text in step 1, assert it is still accessible in step 2 via fetch.
-
-Browserctl.workflow "smoke/store_fetch" do
-  desc "Smoke: store a value in one step and retrieve it in a later step"
-
-  param :base_url, default: "https://the-internet.herokuapp.com"
-
-  step "open dynamic loading page" do
-    open_page(:main, url: "#{base_url}/dynamic_loading/1")
-  end
-
-  step "click start and capture loaded text" do
-    page(:main).click("div#start button")
-    page(:main).wait("div#finish", timeout: 10)
-    text = client.evaluate("main", "document.querySelector('div#finish h4')?.innerText?.trim()")[:result]
-    assert text && !text.empty?, "expected loaded text, got: #{text.inspect}"
-    store(:loaded_text, text)
-    puts "  [store] loaded_text = #{text.inspect}"
-  end
-
-  step "fetch value from previous step and assert" do
-    text = fetch(:loaded_text)
-    puts "  [fetch] loaded_text = #{text.inspect}"
-    assert text == "Hello World!", "expected 'Hello World!', got: #{text.inspect}"
-  end
-
-  step "confirm fetch raises for unknown key" do
-    fetch(:nonexistent_key)
-    assert false, "expected WorkflowError was not raised"
-  rescue Browserctl::WorkflowError => e
-    puts "  [ok] WorkflowError raised as expected: #{e.message}"
-  end
-end