browserctl 0.11.0 → 0.12.0

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

@@ -21,7 +21,11 @@ module Browserctl
         def cmd_fetch(req)
           key = req[:key].to_s
           found = @kv_mutex.synchronize { @kv_store.key?(key) ? { ok: true, value: @kv_store[key] } : nil }
-          found || { error: "key '#{key}' not found", code: "key_not_found" }
+          found || error_payload(
+            code: Browserctl::Error::Codes::KEY_NOT_FOUND,
+            message: "key '#{key}' not found",
+            context: { key: key }
+          )
         end
       end
     end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+
+module Browserctl
+  class CommandDispatcher
+    module Handlers
+      # Centralised structured-error builder for daemon JSON-RPC responses.
+      # Each handler returns `{ error:, code:, context:, suggested_action: }`
+      # for any failure carrying a stable {Browserctl::Error::Codes} code.
+      module ErrorPayload
+        # @param code [String] a SCREAMING_SNAKE code from {Codes}
+        # @param message [String] human-readable error
+        # @param context [Hash] free-form structured fields (selector, path, ...)
+        # @return [Hash{Symbol => Object}]
+        def error_payload(code:, message:, context: {})
+          {
+            error: message,
+            code: code,
+            context: context,
+            suggested_action: Browserctl::Error::SuggestedActions.for(code)
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -27,7 +27,13 @@ module Browserctl
               "return { x: r.left + r.width / 2, y: r.top + r.height / 2 }; " \
               "})(#{sel.to_json})"
             )
-            return { error: "selector not found: #{sel}", code: "selector_not_found" } unless coords
+            unless coords
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             session.page.mouse.move(x: coords["x"], y: coords["y"])
             { ok: true }
@@ -43,7 +49,13 @@ module Browserctl
             return sel if sel.is_a?(Hash)
 
             el = session.page.at_css(sel)
-            return { error: "selector not found: #{sel}", code: "selector_not_found" } unless el
+            unless el
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             el.select_file(path)
             { ok: true }
@@ -56,7 +68,13 @@ module Browserctl
             return sel if sel.is_a?(Hash)
 
             el = session.page.at_css(sel)
-            return { error: "selector not found: #{sel}", code: "selector_not_found" } unless el
+            unless el
+              return error_payload(
+                code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+                message: "selector not found: #{sel}",
+                context: { selector: sel }
+              )
+            end
 
             el.evaluate(
               "this.value = #{req[:value].to_json}; " \

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

@@ -8,7 +8,11 @@ module Browserctl
 
         def cmd_navigate(req)
           unless Policy.allowed_navigation?(req[:url].to_s)
-            return { error: "navigation to '#{req[:url]}' blocked by domain policy", code: "domain_not_allowed" }
+            return error_payload(
+              code: Browserctl::Error::Codes::DOMAIN_NOT_ALLOWED,
+              message: "navigation to '#{req[:url]}' blocked by domain policy",
+              context: { url: req[:url].to_s }
+            )
           end
 
           with_page(req[:name]) do |session|
@@ -81,7 +85,13 @@ module Browserctl
 
         def type_into(page, selector, value)
           el = page.at_css(selector)
-          return { error: "selector not found: #{selector}", code: "selector_not_found" } unless el
+          unless el
+            return error_payload(
+              code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+              message: "selector not found: #{selector}",
+              context: { selector: selector }
+            )
+          end
 
           el.focus
           el.evaluate("this.select()")
@@ -91,7 +101,13 @@ module Browserctl
 
         def click_element(page, selector)
           el = page.at_css(selector)
-          return { error: "selector not found: #{selector}", code: "selector_not_found" } unless el
+          unless el
+            return error_payload(
+              code: Browserctl::Error::Codes::SELECTOR_NOT_FOUND,
+              message: "selector not found: #{selector}",
+              context: { selector: selector }
+            )
+          end
 
           # Use the DOM native click() so JS-only event listeners fire.
           # CDP mouse simulation (el.click) dispatches events at screen coordinates

data/lib/browserctl/session.rb

@@ -71,7 +71,7 @@ module Browserctl
     def self.load(session_name)
       validate_name!(session_name)
       dir = path(session_name)
-      raise "session '#{session_name}' not found" unless Dir.exist?(dir)
+      raise Browserctl::Error, "session '#{session_name}' not found" unless Dir.exist?(dir)
 
       meta = JSON.parse(File.read(File.join(dir, "metadata.json")), symbolize_names: true)
 

data/lib/browserctl/state/bundle.rb

@@ -4,6 +4,7 @@ require "json"
 require "openssl"
 require "securerandom"
 require_relative "../errors"
+require_relative "../error/codes"
 
 module Browserctl
   module State
@@ -42,6 +43,12 @@ module Browserctl
     class Bundle
       MAGIC          = "BCTL\x00".b.freeze
       VERSION        = 1
+      # Manifest-level format version, written as `format_version` and
+      # validated on decode. Distinct from the wire-format byte `VERSION`
+      # above (which gates the binary envelope shape) — this gates the
+      # manifest schema. See docs/reference/format-versions.md.
+      BUNDLE_FORMAT_VERSION = 1
+      SUPPORTED_FORMAT_VERSIONS = [BUNDLE_FORMAT_VERSION].freeze
       FLAG_ENCRYPTED = 0x01
       HEADER_SIZE    = MAGIC.bytesize + 3 # version + flags + reserved
       LEN_SIZE       = 4
@@ -63,6 +70,7 @@ module Browserctl
       #   the footer is an HMAC. When nil, payload is plaintext and the
       #   footer is a SHA-256 digest.
       def self.encode(manifest:, payload:, passphrase: nil)
+        manifest = stamp_format_version(manifest)
         manifest_bytes = JSON.generate(manifest).b
         payload_json   = JSON.generate(payload).b
         flags          = 0
@@ -96,7 +104,8 @@ module Browserctl
         verify_footer!(body, footer, encrypted: encrypted, passphrase: passphrase)
 
         manifest = JSON.parse(manifest_bytes, symbolize_names: true)
-        payload  = decode_payload(payload_bytes, encrypted: encrypted, passphrase: passphrase)
+        verify_format_version!(manifest)
+        payload = decode_payload(payload_bytes, encrypted: encrypted, passphrase: passphrase)
 
         { manifest: manifest, payload: payload, magic: magic, version: version, encrypted: encrypted }
       end
@@ -108,8 +117,40 @@ module Browserctl
         raise BundleError, "unsupported bundle version #{version}" unless version == VERSION
 
         manifest_bytes, = read_sections!(blob)
-        JSON.parse(manifest_bytes, symbolize_names: true)
+        manifest = JSON.parse(manifest_bytes, symbolize_names: true)
+        verify_format_version!(manifest)
+        manifest
+      end
+
+      # Returns the manifest with `format_version` set as the first key. When
+      # the caller already provided a value we keep it (so encoders can stamp
+      # a future version explicitly); otherwise we stamp the current one.
+      def self.stamp_format_version(manifest)
+        existing = manifest[:format_version] || manifest["format_version"]
+        version = existing || BUNDLE_FORMAT_VERSION
+        rest = manifest.except(:format_version, "format_version")
+        { format_version: version }.merge(rest)
+      end
+      private_class_method :stamp_format_version
+
+      # Raises Browserctl::ProtocolMismatch when the manifest declares no
+      # format_version or one this build does not support. The error carries
+      # the canonical PROTOCOL_MISMATCH code from the v0.12 error taxonomy.
+      def self.verify_format_version!(manifest, path: nil)
+        version = manifest[:format_version] || manifest["format_version"]
+        return if version && SUPPORTED_FORMAT_VERSIONS.include?(version)
+
+        where = path ? " at #{path}" : ""
+        msg = if version.nil?
+                "bundle manifest#{where} is missing format_version " \
+                  "(supported: #{SUPPORTED_FORMAT_VERSIONS.inspect})"
+              else
+                "bundle manifest#{where} declares format_version=#{version.inspect}, " \
+                  "this build supports #{SUPPORTED_FORMAT_VERSIONS.inspect}"
+              end
+        raise Browserctl::ProtocolMismatch.new(msg, code: Browserctl::Error::Codes::PROTOCOL_MISMATCH)
       end
+      private_class_method :verify_format_version!
 
       def self.build_body(flags, manifest_bytes, payload_bytes)
         header = MAGIC + [VERSION, flags, 0].pack("CCC")

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow/flow_wrapper.rb

@@ -59,7 +59,7 @@ module Browserctl
       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)"
+          raise Browserctl::WorkflowError, "flow wrapper already exists at #{path} (pass overwrite: true to replace)"
         end
 
         FileUtils.mkdir_p(File.dirname(path))

data/lib/browserctl/workflow.rb

@@ -11,6 +11,61 @@ 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)
@@ -391,7 +446,7 @@ module Browserctl
     end
 
     def selector_not_found?(res)
-      res.is_a?(Hash) && res[:code] == "selector_not_found"
+      res.is_a?(Hash) && res[:code] == Browserctl::Error::Codes::SELECTOR_NOT_FOUND
     end
 
     def log_rematch(cmd, selector, match)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: browserctl
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Patrick
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-10 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:
@@ -176,6 +175,7 @@ files:
 - 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
@@ -184,14 +184,19 @@ files:
 - 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
@@ -201,13 +206,17 @@ files:
 - 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
@@ -220,6 +229,7 @@ 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
@@ -258,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
@@ -273,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