browserctl 0.8.1 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e85e284d37a585d84857db9f02a93bc7d9aacbf5c026da8ab06559fdff121f16
-  data.tar.gz: 76dbe3a44dee51d1c520dc0bd4d282790309efab1ecc5567fcee585b064660f1
+  metadata.gz: cd4d66743b0fba81220c113a7c99a09a94b216acee4d734a6e69ff76d27378b7
+  data.tar.gz: 60a8eb9469960e376c0d71a51bf801863e60d7a52e935578920ce227d8397e2b
 SHA512:
-  metadata.gz: e66d36468423be0212176d8d40df94c5e10ba3d5f23663041b502c0d481580f94f12f308deaffac18b25fef1cc0bd644dac110e4d98ce365574ef6aa53dc4784
-  data.tar.gz: b147ca301c15e728b9bf6e3682bcf975f7f105adadd77d62db9a6a68fa8a05cd73533562f198b0825abc99f45ee73c04cf50aa2205d840d0181f3b599e9f7093
+  metadata.gz: ceed28ff7dd8603bbaaee3ddaa5f6e65669a623aca423633a3ce08f64584064d37a400e461f8828260f245c34bba509452431c4af8ce2c672764778337a51075
+  data.tar.gz: 932c20041989b25fc3fc7d20aa23909edd1651a00500071fbe1ceb4b38edb7c0d64c033cd267f5a4ad240fb3d3f60020320f94f5c45ad9912f79a1960549d7e0

data/CHANGELOG.md

@@ -10,6 +10,25 @@ 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.3](https://github.com/patrick204nqh/browserctl/compare/v0.8.2...v0.8.3) (2026-04-29)
+
+
+### Features
+
+* expired_if: on load_session — detect stale sessions and auto-recover ([#67](https://github.com/patrick204nqh/browserctl/issues/67)) ([c6a4674](https://github.com/patrick204nqh/browserctl/commit/c6a467439835373165b1323c4aad6144388533be))
+
+
+### Miscellaneous Chores
+
+* pin next release to 0.8.3 ([#69](https://github.com/patrick204nqh/browserctl/issues/69)) ([a017e3c](https://github.com/patrick204nqh/browserctl/commit/a017e3c3b464060ced2ecd4d76fa04049f40e46a))
+
+## [0.8.2](https://github.com/patrick204nqh/browserctl/compare/v0.8.1...v0.8.2) (2026-04-29)
+
+
+### Bug Fixes
+
+* v0.8.2 UX polish — describe secret_ref, fallback hint, cross-platform encrypt guidance ([#65](https://github.com/patrick204nqh/browserctl/issues/65)) ([2fe5ea4](https://github.com/patrick204nqh/browserctl/commit/2fe5ea4da0997dc2ab2c3a0696fc819e3fffca40))
+
 ## [0.8.1](https://github.com/patrick204nqh/browserctl/compare/v0.8.0...v0.8.1) (2026-04-29)
 
 

data/lib/browserctl/client.rb

@@ -270,8 +270,8 @@ module Browserctl
     # Saves the current browser state (cookies, localStorage, open pages) to a named session.
     # @param session_name [String] name for the saved session
     # @return [Hash] `{ ok: true, path:, pages: N, cookies: N }` or `{ error: }`
-    def session_save(session_name)
-      call("session_save", session_name: session_name)
+    def session_save(session_name, encrypt: false)
+      call("session_save", session_name: session_name, encrypt: encrypt)
     end
 
     # Restores a previously saved session into the running daemon.

data/lib/browserctl/runner.rb

@@ -109,7 +109,11 @@ module Browserctl
     end
 
     def format_params(defn)
-      defn.param_defs.transform_values { |p| { required: p.required, secret: p.secret, default: p.default } }
+      defn.param_defs.transform_values do |p|
+        entry = { required: p.required, secret: p.secret, default: p.default }
+        entry[:secret_ref] = p.secret_ref if p.secret_ref
+        entry
+      end
     end
   end
 end

data/lib/browserctl/secret_resolver_registry.rb

@@ -16,9 +16,13 @@ module Browserctl
       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"
+        msg = "'#{scheme}://' resolver is not available in this environment"
+        if scheme == "keychain"
+          msg += "\n  Use env://YOUR_VAR_NAME to source secrets from environment variables instead."
+        end
+        raise SecretResolverError, msg
       end
 
       resolver.resolve(reference)

data/lib/browserctl/server/handlers/session.rb

@@ -32,7 +32,8 @@ module Browserctl
                         created_at: now, updated_at: now, pages: pages_meta },
             cookies: cookies,
             local_storage: local_storage,
-            session_storage: {}
+            session_storage: {},
+            encrypt: req[:encrypt] || false
           )
           { ok: true, path: Browserctl::Session.path(req[:session_name]),
             pages: pages_meta.length, cookies: cookies.length }

data/lib/browserctl/session.rb

@@ -39,7 +39,12 @@ module Browserctl
     def self.prepare_encryption(session_name, metadata, encrypt)
       return [nil, metadata] unless encrypt
 
-      raise Browserctl::Error, "session encryption requires macOS Keychain (darwin only)" unless keychain_available?
+      unless keychain_available?
+        raise Browserctl::Error,
+              "session encryption requires macOS Keychain (darwin only)\n  " \
+              "For Linux/CI, omit --encrypt and rely on 0o600 file permissions,\n  " \
+              "or use BROWSERCTL_EXPORT_PASSPHRASE with session export --encrypt for portable archives."
+      end
 
       key = SecureRandom.bytes(32)
       keychain_store(session_name, key)

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -4,6 +4,7 @@ require "timeout"
 require_relative "client"
 require_relative "errors"
 require_relative "secret_resolvers"
+require_relative "session"
 
 module Browserctl
   ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
@@ -67,20 +68,21 @@ module Browserctl
       res
     end
 
-    def load_session(session_name, fallback: nil)
+    def load_session(session_name, fallback: nil, expired_if: nil)
+      validate_expired_if!(expired_if)
+      fallback_name = fallback&.to_s
       res = @client.session_load(session_name)
-      return res unless res[:error]
 
-      raise WorkflowError, res[:error] unless fallback
+      if res[:error]
+        raise WorkflowError, res[:error] unless fallback_name
 
-      invoke(fallback.to_s)
-      res2 = @client.session_load(session_name)
-      if res2[:error]
-        raise WorkflowError,
-              "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+        invoke(fallback_name)
+        return load_after_fallback(session_name, fallback_name)
       end
 
-      res2
+      return res if expired_if.nil? || !call_expired_if(expired_if, session_name)
+
+      recover_expired_session(session_name, fallback_name, expired_if)
     end
 
     def list_sessions
@@ -104,6 +106,48 @@ module Browserctl
 
     private
 
+    def validate_expired_if!(expired_if)
+      return unless expired_if && !expired_if.lambda?
+
+      raise ArgumentError,
+            "expired_if: must be a lambda (-> { }), not a Proc — " \
+            "bare return inside a Proc unwinds the caller"
+    end
+
+    def call_expired_if(expired_if, session_name)
+      expired_if.call
+    rescue WorkflowError, StandardError => e
+      raise WorkflowError, "expired_if check failed for session '#{session_name}': #{e.message}"
+    end
+
+    def recover_expired_session(session_name, fallback_name, expired_if)
+      unless fallback_name
+        raise WorkflowError,
+              "session '#{session_name}' is expired; provide fallback: to auto-recover"
+      end
+
+      invoke(fallback_name)
+      res = load_after_fallback(session_name, fallback_name)
+
+      if call_expired_if(expired_if, session_name)
+        raise WorkflowError,
+              "session '#{session_name}' still expired after running fallback '#{fallback_name}'"
+      end
+
+      res
+    end
+
+    def load_after_fallback(session_name, fallback)
+      res = @client.session_load(session_name)
+      return res unless res[:error]
+
+      msg = "session '#{session_name}' still unavailable after running fallback '#{fallback}'"
+      unless Session.exist?(session_name)
+        msg += "\n  Hint: '#{fallback}' did not call save_session(\"#{session_name}\") — add it as the last step."
+      end
+      raise WorkflowError, msg
+    end
+
     def invoke_stack
       @invoke_stack ||= []
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.3
 platform: ruby
 authors:
 - Patrick