browserctl 0.13.1 → 0.14.0

data/lib/browserctl/error/codes.rb

@@ -18,6 +18,18 @@ module Browserctl
       PROTOCOL_MISMATCH        = "PROTOCOL_MISMATCH"
       DOMAIN_NOT_ALLOWED       = "DOMAIN_NOT_ALLOWED"
       KEY_NOT_FOUND            = "KEY_NOT_FOUND"
+
+      # Validation family — introduced in v0.14 WS-1 to retire the remaining
+      # bare ArgumentError raises on public APIs and DSL guards.
+      # VALIDATION_FAILED is the parent code; the four INVALID_* members are
+      # specialisations that all share exit code 8. See docs/reference/errors.md
+      # for the per-code triggers.
+      VALIDATION_FAILED        = "VALIDATION_FAILED"
+      INVALID_SELECTOR_REF     = "INVALID_SELECTOR_REF"
+      INVALID_STATE_NAME       = "INVALID_STATE_NAME"
+      INVALID_DSL_USAGE        = "INVALID_DSL_USAGE"
+      INVALID_FORMAT_VERSION   = "INVALID_FORMAT_VERSION"
+
       GENERIC                  = "GENERIC"
 
       ALL = [
@@ -29,6 +41,11 @@ module Browserctl
         PROTOCOL_MISMATCH,
         DOMAIN_NOT_ALLOWED,
         KEY_NOT_FOUND,
+        VALIDATION_FAILED,
+        INVALID_SELECTOR_REF,
+        INVALID_STATE_NAME,
+        INVALID_DSL_USAGE,
+        INVALID_FORMAT_VERSION,
         GENERIC
       ].freeze
 

data/lib/browserctl/error/exit_codes.rb

@@ -25,6 +25,7 @@ module Browserctl
       PROTOCOL_MISMATCH  = 5
       SELECTOR_NOT_FOUND = 6
       STATE_EXPIRED      = 7
+      VALIDATION_FAILED  = 8
 
       # Canonical Codes string → exit status integer. Codes without an entry
       # (e.g. DOMAIN_NOT_ALLOWED, KEY_NOT_FOUND, SECRET_RESOLUTION_FAILED,
@@ -34,12 +35,22 @@ module Browserctl
       # DRIFT (2) is reserved for a future Codes::DRIFT and currently has no
       # entry in this table — drift-related raises fall through to GENERIC
       # until that code is introduced.
+      #
+      # The validation family (VALIDATION_FAILED parent plus INVALID_*
+      # specialisations) all map to exit code 8 — agents and scripts can
+      # branch on `$? == 8` for any caller-side validation failure without
+      # caring which specific guard tripped.
       TABLE = {
         Codes::AUTH_REQUIRED => AUTH_REQUIRED,
         Codes::DAEMON_UNREACHABLE => DAEMON_UNREACHABLE,
         Codes::PROTOCOL_MISMATCH => PROTOCOL_MISMATCH,
         Codes::SELECTOR_NOT_FOUND => SELECTOR_NOT_FOUND,
-        Codes::STATE_EXPIRED => STATE_EXPIRED
+        Codes::STATE_EXPIRED => STATE_EXPIRED,
+        Codes::VALIDATION_FAILED => VALIDATION_FAILED,
+        Codes::INVALID_SELECTOR_REF => VALIDATION_FAILED,
+        Codes::INVALID_STATE_NAME => VALIDATION_FAILED,
+        Codes::INVALID_DSL_USAGE => VALIDATION_FAILED,
+        Codes::INVALID_FORMAT_VERSION => VALIDATION_FAILED
       }.freeze
 
       # @param code [String, nil] a canonical code from {Browserctl::Error::Codes}

data/lib/browserctl/error/suggested_actions.rb

@@ -28,6 +28,17 @@ module Browserctl
           "Add the domain to your policy allowlist or use an allowed URL.",
         Codes::KEY_NOT_FOUND =>
           "Verify the key was stored in this daemon session before fetching.",
+        Codes::VALIDATION_FAILED =>
+          "Check the argument or DSL usage against the documented contract, then retry.",
+        Codes::INVALID_SELECTOR_REF =>
+          "Pass either a CSS selector or a stable ref — one is required.",
+        Codes::INVALID_STATE_NAME =>
+          "Use only letters, digits, '_' or '-' (max 64 chars) for state names.",
+        Codes::INVALID_DSL_USAGE =>
+          "Check the workflow/flow DSL call against docs/reference/style-guide.md; " \
+          "required blocks or arguments are missing.",
+        Codes::INVALID_FORMAT_VERSION =>
+          "Use a non-negative Integer for the format version header; see docs/reference/format-versions.md.",
         Codes::GENERIC => DEFAULT
       }.freeze
 

data/lib/browserctl/flow.rb

@@ -63,19 +63,37 @@ module Browserctl
     end
 
     def precondition(label = "precondition", &block)
-      raise ArgumentError, "precondition '#{label}' requires a block" unless block
+      unless block
+        raise Browserctl::Error.new(
+          "precondition '#{label}' requires a block",
+          code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+          context: { dsl: :flow, action: :precondition, label: label }
+        )
+      end
 
       @preconditions << FlowConditionDef.new(kind: :precondition, label: label, block: block)
     end
 
     def postcondition(label = "postcondition", &block)
-      raise ArgumentError, "postcondition '#{label}' requires a block" unless block
+      unless block
+        raise Browserctl::Error.new(
+          "postcondition '#{label}' requires a block",
+          code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+          context: { dsl: :flow, action: :postcondition, label: label }
+        )
+      end
 
       @postconditions << FlowConditionDef.new(kind: :postcondition, label: label, block: block)
     end
 
     def produces_state(&block)
-      raise ArgumentError, "produces_state requires a block" unless block
+      unless block
+        raise Browserctl::Error.new(
+          "produces_state requires a block",
+          code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+          context: { dsl: :flow, action: :produces_state }
+        )
+      end
 
       @produces_state_block = block
     end
@@ -87,13 +105,22 @@ module Browserctl
     def compose(target_name)
       name = target_name.to_s
       if Browserctl.respond_to?(:lookup_workflow) && Browserctl.lookup_workflow(name)
-        raise ArgumentError,
-              "flow '#{@name}' cannot compose workflow '#{name}': flows return state, " \
-              "workflows share state — composition across kinds is not supported"
+        raise Browserctl::Error.new(
+          "flow '#{@name}' cannot compose workflow '#{name}': flows return state, " \
+          "workflows share state — composition across kinds is not supported",
+          code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+          context: { dsl: :flow, action: :compose, source: @name, target: name, reason: :cross_kind }
+        )
       end
 
       source = Browserctl.lookup_flow(name)
-      raise ArgumentError, "flow '#{name}' not found for composition" unless source
+      unless source
+        raise Browserctl::Error.new(
+          "flow '#{name}' not found for composition",
+          code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+          context: { dsl: :flow, action: :compose, source: @name, target: name, reason: :not_found }
+        )
+      end
 
       @steps.concat(source.steps)
     end
@@ -113,7 +140,11 @@ module Browserctl
     def validate_semver!(value, label:)
       return if value.to_s.match?(SEMVER_RE)
 
-      raise ArgumentError, "#{label} must be MAJOR.MINOR.PATCH (got #{value.inspect})"
+      raise Browserctl::Error.new(
+        "#{label} must be MAJOR.MINOR.PATCH (got #{value.inspect})",
+        code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+        context: { dsl: :flow, action: :validate_semver, label: label, value: value.to_s }
+      )
     end
 
     def missing_param_error(name)
@@ -166,7 +197,13 @@ module Browserctl
   @flow_registry       = {}
 
   def self.flow(name, &block)
-    raise ArgumentError, "Browserctl.flow requires a block" unless block
+    unless block
+      raise Browserctl::Error.new(
+        "Browserctl.flow requires a block",
+        code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+        context: { dsl: :flow, action: :define, name: name.to_s }
+      )
+    end
 
     flow = Flow.new(name).tap { |f| f.instance_exec(&block) }
     register_flow(flow)

data/lib/browserctl/flow_registry.rb

@@ -60,7 +60,11 @@ module Browserctl
     def self.validate_name!(name)
       return if SAFE_NAME.match?(name.to_s)
 
-      raise ArgumentError, "invalid flow name: #{name.inspect} — use letters, digits, _ and - only"
+      raise Browserctl::Error.new(
+        "invalid flow name: #{name.inspect} — use letters, digits, _ and - only",
+        code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+        context: { name: name.to_s }
+      )
     end
   end
 end

data/lib/browserctl/flows/stdlib/totp_2fa.rb

@@ -31,7 +31,11 @@ module Browserctl
 
       def char_to_bits(char)
         idx = BASE32_ALPHABET.index(char) or
-          raise ArgumentError, "invalid base32 char #{char.inspect}"
+          raise Browserctl::Error.new(
+            "invalid base32 char #{char.inspect}",
+            code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+            context: { char: char }
+          )
         idx.to_s(2).rjust(5, "0")
       end
     end

data/lib/browserctl/format_version.rb

@@ -29,7 +29,13 @@ module Browserctl
 
     # Returns the canonical header string for a given integer version.
     def stamp(version:)
-      raise ArgumentError, "version must be a non-negative Integer" unless version.is_a?(Integer) && version >= 0
+      unless version.is_a?(Integer) && version >= 0
+        raise Browserctl::Error.new(
+          "version must be a non-negative Integer",
+          code: Browserctl::Error::Codes::INVALID_FORMAT_VERSION,
+          context: { value: version }
+        )
+      end
 
       "version: #{version}\n"
     end

data/lib/browserctl/logger.rb

@@ -132,7 +132,8 @@ module Browserctl
     log.progname  = component
     log.formatter = JsonlFormatter.new(component: component)
     log
-  rescue StandardError
+  rescue Errno::EACCES, Errno::ENOENT, Errno::EISDIR, Errno::ENOSPC, Errno::EROFS, IOError => e
+    warn "browserctl: failed to build jsonl logger (#{e.class}: #{e.message})"
     nil
   end
 

data/lib/browserctl/migrations.rb

@@ -42,7 +42,14 @@ module Browserctl
       # block receives the file path as a keyword argument and must rewrite
       # the file in place to the new version.
       def register(format:, from_version:, to_version:, &upgrade)
-        raise ArgumentError, "upgrade block required" unless upgrade
+        unless upgrade
+          raise Browserctl::Error.new(
+            "upgrade block required",
+            code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+            context: { dsl: :migrations, action: :register, format: format,
+                       from_version: from_version, to_version: to_version }
+          )
+        end
 
         @mutex.synchronize do
           @registry << Migration.new(format: format, from_version: from_version,

data/lib/browserctl/rubocop/cops/typed_error.rb

@@ -12,12 +12,13 @@ module RuboCop
       # Subclasses with their own `default_code` are trusted (the cop does not
       # try to statically resolve `default_code` across files); the contract
       # is enforced by the unit test suite. This cop's job is to catch the
-      # specific failure mode of inlining a stale snake_case code at the
-      # raise site and bypassing the canonical enum.
+      # specific failure mode of inlining a stale code string at the raise
+      # site and bypassing the canonical enum.
       #
       # @example
-      #   # bad — string literal that isn't a Codes constant
-      #   raise Browserctl::Error, "state expired", code: "state_expired"
+      #   # bad — any string literal, even one that happens to match a
+      #   # canonical code today, drifts when the enum is renamed
+      #   raise Browserctl::Error, "state expired", code: "STATE_EXPIRED"
       #
       #   # good — Codes constant reference
       #   raise Browserctl::Error, "state expired",
@@ -29,19 +30,16 @@ module RuboCop
       # The pattern is intentionally narrow. The full default_code-vs-Codes
       # reconciliation lives in `lib/browserctl/errors.rb` and is covered by
       # `spec/unit/errors_spec.rb`.
+      #
+      # The cop was tightened in v0.14 WS-1 PR 5 to remove the previous
+      # "canonical SCREAMING_SNAKE string literals are also fine" escape
+      # hatch — every `code:` must now be a constant reference so renames in
+      # `Codes` propagate through the codebase via the constant, not via a
+      # stale whitelist baked into this cop.
       class TypedError < RuboCop::Cop::Base
         MSG = "Browserctl raise: `code:` must reference Browserctl::Error::Codes::* — " \
               "got string literal %<value>p. See lib/browserctl/error/codes.rb."
 
-        VALID_CODES = %w[
-          AUTH_REQUIRED
-          SELECTOR_NOT_FOUND
-          STATE_EXPIRED
-          SECRET_RESOLUTION_FAILED
-          DAEMON_UNREACHABLE
-          PROTOCOL_MISMATCH
-        ].freeze
-
         # Matches `raise Browserctl::Foo, ..., code: <value>` and yields the
         # `code:` value node.
         def_node_matcher :browserctl_raise_with_code, <<~PATTERN
@@ -51,16 +49,27 @@ module RuboCop
             (hash <(pair (sym :code) $_) ...>))
         PATTERN
 
+        # Matches `raise Browserctl::Foo.new(..., code: <value>, ...)` and
+        # yields the `code:` value node. The base error initializer is
+        # routinely called via `.new` (see `Browserctl::Error#initialize`),
+        # so the cop needs to inspect both shapes.
+        def_node_matcher :browserctl_raise_new_with_code, <<~PATTERN
+          (send nil? :raise
+            (send (const (const nil? :Browserctl) _) :new
+              ...
+              (hash <(pair (sym :code) $_) ...>)))
+        PATTERN
+
         def on_send(node)
           return unless node.method?(:raise)
 
-          browserctl_raise_with_code(node) do |code_value|
+          [
+            browserctl_raise_with_code(node),
+            browserctl_raise_new_with_code(node)
+          ].compact.each do |code_value|
             next unless code_value.str_type?
 
-            value = code_value.value
-            next if VALID_CODES.include?(value)
-
-            add_offense(code_value, message: format(MSG, value: value))
+            add_offense(code_value, message: format(MSG, value: code_value.value))
           end
         end
       end

data/lib/browserctl/server/command_dispatcher.rb

@@ -29,7 +29,7 @@ module Browserctl
     include Handlers::DevTools
     include Handlers::DaemonControl
     include Handlers::Storage
-    include Handlers::State
+    include Handlers::StateRpc
     include Handlers::Interaction
 
     COMMAND_MAP = {

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "json"
+require "timeout"
+
 module Browserctl
   class CommandDispatcher
     module Handlers
@@ -75,7 +78,8 @@ module Browserctl
         def capture_post_snapshot_digest(session)
           snapshot = @snapshot_builder.call(session.page)
           Browserctl::Replay::SnapshotDiff.digest(snapshot)
-        rescue StandardError
+        rescue JSON::ParserError, Timeout::Error, Browserctl::Error => e
+          Browserctl.logger.debug("post-snapshot digest skipped: #{e.class}: #{e.message}")
           nil
         end
 

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

@@ -8,7 +8,7 @@ module Browserctl
     module Handlers
       # Top-level state management — collapses cookies + localStorage +
       # sessionStorage into a single `.bctl` bundle. See lib/browserctl/state.rb.
-      module State
+      module StateRpc
         private
 
         def cmd_state_save(req)

data/lib/browserctl/state/mutator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "../flow_registry"
+require_relative "../errors"
+
+module Browserctl
+  module State
+    # Drives the "rotate this bundle's bound flow and re-save" operation
+    # without dragging in CLI input concerns. Extracted from
+    # `Browserctl::Commands::State.run_rotate` so the rotation flow is:
+    #   - testable without spawning a CLI subprocess
+    #   - reusable from Workflow if a workflow ever needs to drive rotation
+    #     programmatically.
+    #
+    # Errors are surfaced by raising typed `Browserctl::FlowError` so the
+    # caller (CLI or Workflow) can decide how to render them. The CLI maps
+    # to a non-zero exit; a Workflow caller may catch and continue.
+    class Mutator
+      Result = Struct.new(:save_result, :flow_name, :flow_version, keyword_init: true) do
+        def to_h
+          (save_result || {}).merge(rotated_flow: flow_name)
+        end
+      end
+
+      def initialize(client:, registry: Browserctl::FlowRegistry)
+        @client   = client
+        @registry = registry
+      end
+
+      # Re-runs the flow bound to the bundle <name> and re-saves it under the
+      # same origins. `params` is the merged param set (file + caller-provided);
+      # the CLI does the file/k=v parsing before handing values in.
+      #
+      # @return [Result]
+      # @raise  [Browserctl::FlowError]
+      def rotate(name:, params: {}, page: nil)
+        manifest = read_manifest!(name)
+        flow     = resolve_bound_flow!(manifest)
+
+        flow.run(page: page, client: @client, **params)
+
+        save_result = @client.state_save(name,
+                                         flow: flow.name,
+                                         flow_version: flow.version_string,
+                                         origins: manifest[:origins] || manifest["origins"])
+        Result.new(save_result: save_result, flow_name: flow.name, flow_version: flow.version_string)
+      end
+
+      private
+
+      def read_manifest!(name)
+        info = @client.state_info(name)
+        err  = info[:error] || info["error"]
+        raise Browserctl::FlowError, err.to_s if err
+
+        info[:info] || info["info"] || {}
+      end
+
+      def resolve_bound_flow!(manifest)
+        flow_name = manifest[:flow] || manifest["flow"]
+        if flow_name.nil? || flow_name.to_s.empty?
+          raise Browserctl::FlowError,
+                "state has no bound flow — re-save with `state save --flow NAME` first"
+        end
+
+        flow = @registry.resolve(flow_name)
+        raise Browserctl::FlowError, "flow '#{flow_name}' not found in registry" unless flow
+
+        flow
+      end
+    end
+  end
+end

data/lib/browserctl/state.rb

@@ -83,7 +83,11 @@ module Browserctl
     def self.validate_name!(name)
       return if SAFE_NAME.match?(name.to_s)
 
-      raise ArgumentError, "invalid state name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
+      raise Browserctl::Error.new(
+        "invalid state name #{name.inspect} — use letters, digits, _ or - (max 64 chars)",
+        code: Browserctl::Error::Codes::INVALID_STATE_NAME,
+        context: { name: name }
+      )
     end
 
     # Persist a bundle. `payload` is a `State::Payload` value object carrying

data/lib/browserctl/trace/event_stream.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Browserctl
+  module Trace
+    # Reads `cli.log` + `daemon.log` JSONL files from a log directory and yields
+    # records sorted by timestamp. Malformed lines are skipped silently — this
+    # matches the tolerant behaviour expected of `browserctl trace`.
+    #
+    # Session filtering: when `session_filter` is provided, only records whose
+    # `session_id` matches are emitted. When nil, records are scoped to the most
+    # recent `session_id` observed in the merged stream (or all records if none
+    # carry a session id yet — backwards compatible with older logs).
+    class EventStream
+      include Enumerable
+
+      LOG_GLOB = "{cli,daemon}.log"
+
+      def initialize(log_dir, session_filter: nil)
+        @log_dir = log_dir
+        @session_filter = session_filter
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        records.each(&block)
+      end
+
+      def empty?
+        records.empty?
+      end
+
+      def records
+        @records ||= filter_session(load_records)
+      end
+
+      private
+
+      def load_records
+        paths = Dir.glob(File.join(@log_dir, LOG_GLOB))
+        rows = paths.flat_map do |path|
+          File.foreach(path).filter_map { |line| parse_line(line) }
+        end
+        rows.sort_by { |r| r["ts"].to_s }
+      end
+
+      def parse_line(line)
+        stripped = line.strip
+        return nil if stripped.empty?
+
+        JSON.parse(stripped)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Session resolution. When session_id is stamped on records (future PR),
+      # filter/select by it. Otherwise, treat the entire merged stream as one
+      # session — caller can scope by tailing/rotating logs.
+      # TODO: stamp session_id on every log line so this scopes correctly.
+      def filter_session(rows)
+        if @session_filter
+          rows.select { |r| r["session_id"].to_s == @session_filter }
+        else
+          ids = rows.map { |r| r["session_id"] }.compact.uniq
+          return rows if ids.empty?
+
+          recent = ids.last
+          rows.select { |r| r["session_id"] == recent }
+        end
+      end
+    end
+  end
+end

data/lib/browserctl/trace/renderer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Browserctl
+  module Trace
+    # Renders structured log records as a human-scannable timeline. Output
+    # format is intentionally compact:
+    #
+    #   HH:MM:SS.mmm I LEVEL COMPONENT LABEL                  k=v k=v
+    #
+    # Colour is enabled when the target IO is a TTY (or when `color: true` is
+    # forced). Redaction is optional and injected as a dependency so callers
+    # can substitute a stricter `Browserctl::Redactor` or pass `nil` to
+    # disable.
+    class Renderer
+      LEVEL_COLORS = {
+        "DEBUG" => "\e[2;37m", # dim grey
+        "INFO" => "\e[36m",    # cyan
+        "WARN" => "\e[33m",    # yellow
+        "ERROR" => "\e[31m" # red
+      }.freeze
+      RESET = "\e[0m"
+
+      CATEGORY_ICONS = {
+        error: "!",
+        snapshot: "S",
+        network: "N",
+        event: "."
+      }.freeze
+
+      OMIT_KEYS = %w[ts level component event msg].freeze
+
+      def initialize(io:, color: nil, redactor: nil)
+        @io = io
+        @color = color.nil? ? tty?(io) : color
+        @redactor = redactor
+      end
+
+      def render(stream)
+        stream.each { |record| @io.puts(format_line(record)) }
+      end
+
+      private
+
+      def tty?(io)
+        io.respond_to?(:tty?) && io.tty?
+      end
+
+      def format_line(record)
+        level = (record["level"] || "INFO").to_s
+        line  = format("%-12<ts>s %<icon>s %-5<level>s %-7<comp>s %-22<label>s %<ctx>s",
+                       ts: format_ts(record["ts"]),
+                       icon: CATEGORY_ICONS.fetch(categorise(record), "."),
+                       level: level,
+                       comp: (record["component"] || "?").to_s,
+                       label: event_label(record),
+                       ctx: context_snippet(record)).rstrip
+
+        line = @redactor.redact(line) if @redactor
+        @color ? colourise(line, level) : line
+      end
+
+      def format_ts(timestamp)
+        Time.iso8601(timestamp.to_s).strftime("%H:%M:%S.%L")
+      rescue ArgumentError, TypeError
+        "??:??:??.???"
+      end
+
+      def categorise(record)
+        return :error    if record["level"] == "ERROR" || record["error"]
+        return :snapshot if record["snapshot"]
+        return :network  if record["request"] || record["response"] || record["url"]
+
+        :event
+      end
+
+      def event_label(record)
+        (record["event"] || record["snapshot"] || record["request"] ||
+          record["msg"] || "-").to_s.slice(0, 22)
+      end
+
+      # Compact "k=v k=v" snippet of remaining structured keys, capped to keep
+      # the timeline scannable. Skips fields already shown in fixed columns.
+      def context_snippet(record)
+        pairs = record.except(*OMIT_KEYS)
+        return "" if pairs.empty?
+
+        pairs.map { |k, v| "#{k}=#{format_value(v)}" }.join(" ").slice(0, 120)
+      end
+
+      def format_value(value)
+        case value
+        when String  then value.length > 40 ? "#{value[0, 37]}..." : value
+        when Array   then "[#{value.length}]"
+        when Hash    then "{#{value.keys.length}}"
+        else value.to_s
+        end
+      end
+
+      def colourise(line, level)
+        colour = LEVEL_COLORS[level] || ""
+        "#{colour}#{line}#{RESET}"
+      end
+    end
+  end
+end

data/lib/browserctl/version.rb

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

data/lib/browserctl/workflow.rb

@@ -320,9 +320,12 @@ module Browserctl
     def compose(workflow_name)
       name = workflow_name.to_s
       if Browserctl.lookup_flow(name)
-        raise ArgumentError,
-              "workflow '#{@name}' cannot compose flow '#{name}': flows return state, " \
-              "workflows share state — composition across kinds is not supported"
+        raise Browserctl::Error.new(
+          "workflow '#{@name}' cannot compose flow '#{name}': flows return state, " \
+          "workflows share state — composition across kinds is not supported",
+          code: Browserctl::Error::Codes::INVALID_DSL_USAGE,
+          context: { workflow: @name, flow: name, kind: :cross_kind_compose }
+        )
       end
 
       source = Browserctl.lookup_workflow(name)