ace-test-runner-e2e 0.29.0

data/lib/ace/test/end_to_end_runner/molecules/report_writer.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module Ace
+  module Test
+    module EndToEndRunner
+      module Molecules
+        # Writes E2E test reports to disk
+        #
+        # Generates summary, experience, and metadata reports following
+        # the standard report path contract.
+        class ReportWriter
+          # Write all reports for a test result
+          #
+          # @param result [Models::TestResult] The test result
+          # @param scenario [Models::TestScenario] The test scenario
+          # @param report_dir [String] Directory to write reports to
+          # @param test_case [Models::TestCase, nil] Optional single test case for TC-level reports
+          # @return [Hash] Paths to written report files
+          def write(result, scenario, report_dir:, test_case: nil)
+            FileUtils.mkdir_p(report_dir)
+
+            summary_path = write_summary(result, scenario, report_dir, test_case)
+            experience_path = write_experience(result, scenario, report_dir, test_case)
+            metadata_path = write_metadata(result, scenario, report_dir, test_case)
+
+            {
+              summary: summary_path,
+              experience: experience_path,
+              metadata: metadata_path
+            }
+          end
+
+          private
+
+          # Write summary report
+          # @return [String] Path to written file
+          def write_summary(result, scenario, report_dir, test_case = nil)
+            path = File.join(report_dir, "summary.r.md")
+
+            tc_rows = result.test_cases.map do |tc|
+              "| #{tc[:id]} | #{tc[:description]} | #{tc[:status].capitalize} |"
+            end.join("\n")
+
+            goal_criteria_sections = build_goal_criteria_sections(result.test_cases)
+            failed_entries = result.test_cases
+              .select { |tc| tc[:status] == "fail" }
+              .map do |tc|
+                {
+                  "tc" => tc[:id],
+                  "category" => tc[:category] || "runner-error",
+                  "evidence" => tc[:notes].to_s
+                }
+            end
+            verdict = if result.failed_count.zero?
+              (result.status == "error") ? "fail" : "pass"
+            elsif result.passed_count.zero?
+              "fail"
+            else
+              "partial"
+            end
+            score = result.total_count.zero? ? 0.0 : (result.passed_count.to_f / result.total_count).round(3)
+
+            frontmatter_hash = {
+              "test-id" => result.test_id
+            }
+            if test_case
+              frontmatter_hash["tc-id"] = test_case.tc_id
+              frontmatter_hash["scenario-id"] = scenario.test_id
+            end
+            frontmatter_hash.merge!(
+              "package" => scenario.package,
+              "agent" => "ace-test-e2e",
+              "executed" => result.completed_at.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+              "status" => result.status,
+              "tcs-passed" => result.passed_count,
+              "tcs-failed" => result.failed_count,
+              "tcs-total" => result.total_count,
+              "score" => score,
+              "verdict" => verdict,
+              "failed" => failed_entries
+            )
+            frontmatter_yaml = YAML.dump(frontmatter_hash).sub(/\A---\s*\n/, "").sub(/\.\.\.\s*\n\z/, "")
+
+            tc_info_rows = if test_case
+              "| TC ID | #{test_case.tc_id} |\n| TC Title | #{test_case.title} |\n"
+            else
+              ""
+            end
+
+            content = <<~REPORT
+              ---
+              #{frontmatter_yaml.rstrip}
+              ---
+
+              # E2E Test Report: #{result.test_id}
+
+              ## Test Information
+
+              | Field | Value |
+              |-------|-------|
+              | Test ID | #{result.test_id} |
+              #{tc_info_rows}| Title | #{scenario.title} |
+              | Package | #{scenario.package} |
+              | Agent | ace-test-e2e |
+              | Executed | #{result.completed_at.utc.strftime("%Y-%m-%dT%H:%M:%SZ")} |
+              | Duration | #{result.duration_display} |
+
+              ## Results Summary
+
+              | Test Case | Description | Status |
+              |-----------|-------------|--------|
+              #{tc_rows}
+
+              ## Overall Status: #{result.status.upcase}
+
+              #{goal_criteria_sections}
+
+              #{result.summary}
+              #{"## Error\n\n#{result.error}" if result.error}
+            REPORT
+
+            File.write(path, content)
+            path
+          end
+
+          # Write experience report
+          # @return [String] Path to written file
+          def write_experience(result, scenario, report_dir, test_case = nil)
+            path = File.join(report_dir, "experience.r.md")
+
+            tc_title_suffix = test_case ? " / #{test_case.tc_id}" : ""
+
+            exp_frontmatter_lines = [
+              "test-id: #{result.test_id}"
+            ]
+            exp_frontmatter_lines << "tc-id: #{test_case.tc_id}" if test_case
+            exp_frontmatter_lines.concat([
+              "test-title: #{scenario.title}",
+              "package: #{scenario.package}",
+              "agent: ace-test-e2e",
+              "executed: #{result.completed_at.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}",
+              "status: #{(result.status == "pass") ? "complete" : "incomplete"}"
+            ])
+
+            content = <<~REPORT
+              ---
+              #{exp_frontmatter_lines.join("\n")}
+              ---
+
+              # Agent Experience Report: #{result.test_id}#{tc_title_suffix}
+
+              ## Summary
+
+              Executed via ace-test-e2e CLI using LLM provider.
+              #{(result.status == "pass") ? "No significant friction encountered." : "Test execution completed with issues noted below."}
+
+              ## Friction Points
+
+              ### Documentation Gaps
+
+              - Automated execution via LLM - no documentation gaps observed
+
+              ### Tool Behavior Issues
+
+              - #{result.error || "None observed"}
+
+              ## Positive Observations
+
+              - Automated test execution completed successfully via LLM
+            REPORT
+
+            File.write(path, content)
+            path
+          end
+
+          # Write metadata file
+          # @return [String] Path to written file
+          def write_metadata(result, scenario, report_dir, test_case = nil)
+            path = File.join(report_dir, "metadata.yml")
+
+            metadata = {
+              "run-id" => File.basename(report_dir).sub(/-reports\z/, ""),
+              "test-id" => result.test_id,
+              "package" => scenario.package,
+              "agent" => "ace-test-e2e",
+              "started" => result.started_at.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+              "completed" => result.completed_at.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+              "duration" => "#{result.duration.round(0)}s",
+              "status" => result.status,
+              "score" => (result.total_count.zero? ? 0.0 : (result.passed_count.to_f / result.total_count).round(3)),
+              "verdict" => (if result.status == "error"
+                              "fail"
+                            else
+                              (if result.failed_count.zero?
+                                 "pass"
+                               else
+                                 (result.passed_count.zero? ? "fail" : "partial")
+                               end)
+                            end),
+              "tcs-passed" => result.passed_count,
+              "tcs-failed" => result.failed_count,
+              "tcs-total" => result.total_count,
+              "results" => {
+                "passed" => result.passed_count,
+                "failed" => result.failed_count,
+                "total" => result.total_count
+              },
+              "failed" => result.test_cases
+                .select { |tc| tc[:status] == "fail" }
+                .map do |tc|
+                  {
+                    "tc" => tc[:id],
+                    "category" => tc[:category] || "runner-error",
+                    "evidence" => tc[:notes].to_s
+                  }
+              end,
+              "failed_test_cases" => result.failed_test_case_ids
+            }
+
+            if test_case
+              metadata["scenario-id"] = scenario.test_id
+              metadata["tc-id"] = test_case.tc_id
+            end
+
+            File.write(path, YAML.dump(metadata))
+            path
+          end
+
+          def build_goal_criteria_sections(test_cases)
+            sections = test_cases.filter_map do |tc|
+              criteria = tc[:criteria]
+              next if criteria.nil? || criteria.empty?
+
+              rows = criteria.map do |criterion|
+                desc = criterion[:description].to_s.empty? ? criterion[:id] : criterion[:description]
+                "| #{desc} | #{criterion[:status].to_s.upcase} | #{criterion[:evidence]} |"
+              end.join("\n")
+
+              <<~SECTION
+                ### Goal Criteria: #{tc[:id]}
+
+                | Criterion | Status | Evidence |
+                |-----------|--------|----------|
+                #{rows}
+              SECTION
+            end
+
+            return "" if sections.empty?
+
+            "## Goal Evaluation\n\n#{sections.join("\n")}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/test/end_to_end_runner/molecules/scenario_loader.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module Ace
+  module Test
+    module EndToEndRunner
+      module Molecules
+        # Loads a TS-format scenario directory into TestScenario + TestCase models.
+        #
+        # Supported test case format is standalone TC pairs only:
+        # - `TC-*.runner.md`
+        # - `TC-*.verify.md`
+        class ScenarioLoader
+          LEGACY_FIELDS = %w[mode execution-model].freeze
+
+          # Load a scenario directory
+          #
+          # @param scenario_dir [String] Path to the TS-* scenario directory
+          # @return [Models::TestScenario] Populated test scenario
+          # @raise [ArgumentError] If scenario.yml is missing, invalid, or has missing required fields
+          def load(scenario_dir)
+            yml_path = File.join(scenario_dir, "scenario.yml")
+            raise ArgumentError, "scenario.yml not found: #{yml_path}" unless File.exist?(yml_path)
+
+            frontmatter = parse_scenario_yml(yml_path)
+            validate_scenario!(frontmatter, yml_path)
+
+            test_cases = discover_test_cases(scenario_dir)
+            fixture_path = detect_fixture_path(scenario_dir)
+
+            Models::TestScenario.new(
+              test_id: frontmatter["test-id"],
+              title: frontmatter["title"],
+              area: frontmatter["area"],
+              package: frontmatter["package"] || infer_package(scenario_dir),
+              priority: frontmatter["priority"] || "medium",
+              duration: frontmatter["duration"] || "~5min",
+              timeout: parse_timeout(frontmatter["timeout"], yml_path),
+              requires: frontmatter["requires"] || {},
+              file_path: File.expand_path(yml_path),
+              content: File.read(yml_path),
+              setup_steps: frontmatter["setup"] || [],
+              dir_path: File.expand_path(scenario_dir),
+              fixture_path: fixture_path,
+              test_cases: test_cases,
+              tags: parse_tags(frontmatter["tags"]),
+              tool_under_test: frontmatter["tool-under-test"],
+              sandbox_layout: frontmatter["sandbox-layout"] || {}
+            )
+          end
+
+          private
+
+          # Parse an optional per-scenario timeout in seconds.
+          #
+          # @param raw_timeout [Object] Raw YAML timeout value
+          # @param source_path [String] Source file path for errors
+          # @return [Integer, nil] Timeout in seconds
+          # @raise [ArgumentError] If timeout is present and invalid
+          def parse_timeout(raw_timeout, source_path)
+            return nil if raw_timeout.nil?
+
+            value =
+              case raw_timeout
+              when Integer
+                raw_timeout
+              when Numeric
+                raw_timeout.to_i
+              when String
+                stripped = raw_timeout.strip
+                return nil if stripped.empty?
+                raise ArgumentError, "Invalid timeout in #{source_path}: #{raw_timeout.inspect}" unless stripped.match?(/\\A\\d+\\z/)
+                stripped.to_i
+              else
+                raise ArgumentError, "Invalid timeout in #{source_path}: #{raw_timeout.inspect}"
+              end
+
+            raise ArgumentError, "Invalid timeout in #{source_path}: must be greater than 0" if value <= 0
+            value
+          end
+
+          # Parse scenario.yml with safe YAML loading
+          #
+          # @param path [String] Path to scenario.yml
+          # @return [Hash] Parsed YAML frontmatter
+          # @raise [ArgumentError] If YAML is invalid or empty
+          def parse_scenario_yml(path)
+            content = File.read(path)
+            result = YAML.safe_load(content, permitted_classes: [Date])
+            raise ArgumentError, "Empty or invalid YAML in #{path}" if result.nil?
+
+            result
+          rescue Psych::SyntaxError => e
+            raise ArgumentError, "Invalid YAML in #{path}: #{e.message}"
+          end
+
+          # Validate required fields in scenario frontmatter
+          #
+          # @param frontmatter [Hash] Parsed scenario.yml
+          # @param path [String] File path for error messages
+          # @raise [ArgumentError] If required fields are missing
+          def validate_scenario!(frontmatter, path)
+            required = %w[test-id title area]
+            missing = required.reject { |field| frontmatter&.key?(field) }
+            unless missing.empty?
+              raise ArgumentError, "Missing required fields in #{path}: #{missing.join(", ")}"
+            end
+
+            legacy = LEGACY_FIELDS.select { |field| frontmatter.key?(field) }
+            return if legacy.empty?
+
+            raise ArgumentError,
+              "Legacy field(s) not supported in #{path}: #{legacy.join(", ")}. " \
+              "Remove these fields; standalone runner/verify scenarios are the only supported format."
+          end
+
+          # Discover and parse standalone TC files in the scenario directory.
+          #
+          # @param scenario_dir [String] Path to the scenario directory
+          # @return [Array<Models::TestCase>] Parsed test case models, sorted by TC ID
+          def discover_test_cases(scenario_dir)
+            runner_files = Dir.glob(File.join(scenario_dir, "TC-*.runner.md")).sort
+            verify_files = Dir.glob(File.join(scenario_dir, "TC-*.verify.md")).sort
+
+            if runner_files.empty? && verify_files.empty?
+              reject_inline_tc_files!(scenario_dir)
+              return []
+            end
+
+            validate_standalone_files!(scenario_dir, runner_files, verify_files)
+
+            runner_by_id = runner_files.to_h { |f| [extract_tc_id_from_standalone_name(f), f] }
+            verify_by_id = verify_files.to_h { |f| [extract_tc_id_from_standalone_name(f), f] }
+
+            runner_by_id.keys.sort.map do |tc_id|
+              runner_file = runner_by_id.fetch(tc_id)
+              verify_file = verify_by_id.fetch(tc_id)
+              parse_standalone_test_case(tc_id, runner_file, verify_file)
+            end
+          end
+
+          def reject_inline_tc_files!(scenario_dir)
+            inline_files = Dir.glob(File.join(scenario_dir, "TC-*.tc.md")).sort
+            return if inline_files.empty?
+
+            raise ArgumentError,
+              "Inline TC files are no longer supported in #{scenario_dir}. " \
+              "Replace #{inline_files.map { |f| File.basename(f) }.join(", ")} with standalone " \
+              "TC-*.runner.md and TC-*.verify.md pairs."
+          end
+
+          def parse_standalone_test_case(tc_id, runner_file, verify_file)
+            runner_content = File.read(runner_file)
+            verify_content = File.read(verify_file)
+
+            Models::TestCase.new(
+              tc_id: tc_id,
+              title: extract_title_from_markdown(runner_content) || tc_id,
+              content: build_standalone_content(runner_content, verify_content),
+              file_path: File.expand_path(runner_file),
+              pending: nil,
+              goal_format: "standalone"
+            )
+          end
+
+          def extract_tc_id_from_standalone_name(file_path)
+            basename = File.basename(file_path)
+            match = basename.match(/\A(TC-\d+[a-z]*)(?:-[^.]+)?\.(?:runner|verify)\.md\z/i)
+            return match[1].upcase if match
+
+            raise ArgumentError, "Invalid standalone test case filename: #{basename}"
+          end
+
+          def extract_title_from_markdown(markdown)
+            line = markdown.each_line.find { |l| l.strip.start_with?("#") }
+            return nil unless line
+
+            line.sub(/\A#+\s*/, "").strip
+          end
+
+          def build_standalone_content(runner_content, verify_content)
+            <<~CONTENT
+              ## Runner
+
+              #{runner_content.rstrip}
+
+              ## Verifier
+
+              #{verify_content.rstrip}
+            CONTENT
+          end
+
+          def validate_standalone_files!(scenario_dir, runner_files, verify_files)
+            runner_ids = runner_files.map { |f| extract_tc_id_from_standalone_name(f) }.uniq
+            verify_ids = verify_files.map { |f| extract_tc_id_from_standalone_name(f) }.uniq
+
+            missing_runner_ids = verify_ids - runner_ids
+            missing_verify_ids = runner_ids - verify_ids
+
+            unless missing_runner_ids.empty?
+              raise ArgumentError,
+                "Missing standalone runner file(s) for: #{missing_runner_ids.join(", ")} in #{scenario_dir}"
+            end
+
+            unless missing_verify_ids.empty?
+              raise ArgumentError,
+                "Missing standalone verify file(s) for: #{missing_verify_ids.join(", ")} in #{scenario_dir}"
+            end
+
+            runner_yml = File.join(scenario_dir, "runner.yml.md")
+            verifier_yml = File.join(scenario_dir, "verifier.yml.md")
+
+            raise ArgumentError, "Missing standalone file: #{runner_yml}" unless File.exist?(runner_yml)
+            raise ArgumentError, "Missing standalone file: #{verifier_yml}" unless File.exist?(verifier_yml)
+          end
+
+          def parse_tags(raw_tags)
+            return [] unless raw_tags
+
+            tags = raw_tags.is_a?(Array) ? raw_tags : [raw_tags]
+            tags.map(&:to_s).map(&:strip).reject(&:empty?).map(&:downcase)
+          end
+
+          # Detect fixtures directory if it exists
+          #
+          # @param scenario_dir [String] Path to the scenario directory
+          # @return [String, nil] Absolute path to fixtures/ or nil
+          def detect_fixture_path(scenario_dir)
+            path = File.join(scenario_dir, "fixtures")
+            Dir.exist?(path) ? File.expand_path(path) : nil
+          end
+
+          # Infer package name from scenario directory path
+          #
+          # @param scenario_dir [String] Path to scenario directory
+          # @return [String] Inferred package name
+          def infer_package(scenario_dir)
+            # Expected path: {package}/test/e2e/TS-{AREA}-{NNN}-{slug}/
+            parts = File.expand_path(scenario_dir).split("/")
+            parts.each_with_index do |part, idx|
+              next unless part == "test" && idx > 0 && parts[idx + 1] == "e2e"
+
+              return parts[idx - 1]
+            end
+
+            "unknown"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/test/end_to_end_runner/molecules/setup_executor.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "shellwords"
+
+module Ace
+  module Test
+    module EndToEndRunner
+      module Molecules
+        # Executes setup steps deterministically to create a populated sandbox
+        #
+        # Processes the setup array from scenario.yml, running each action
+        # via Ruby system calls (no LLM involved). Supports: git-init,
+        # copy-fixtures, run, write-file, agent-env, and tmux-session actions.
+        #
+        # Note: This is a Molecule because it performs filesystem I/O and
+        # system calls via Open3 and FileUtils.
+        class SetupExecutor
+          # Execute all setup steps in a sandbox directory
+          #
+          # @param setup_steps [Array] Setup steps from scenario.yml
+          # @param sandbox_dir [String] Path to the sandbox directory
+          # @param fixture_source [String, nil] Path to the fixtures/ directory
+          # @param scenario_name [String, nil] Test ID for tmux session naming (e.g., "TS-OVERSEER-001")
+          # @param run_id [String, nil] Unique run ID for deterministic tmux session naming
+          # @return [Hash] Result with :success, :steps_completed, :error, :env, :tmux_session keys
+          def execute(setup_steps:, sandbox_dir:, fixture_source: nil, scenario_name: nil, run_id: nil)
+            FileUtils.mkdir_p(sandbox_dir)
+            env = {}
+            steps_completed = 0
+            @tmux_session = nil
+            @scenario_name = scenario_name
+            @run_id = run_id
+
+            setup_steps.each do |step|
+              execute_step(step, sandbox_dir, env, fixture_source)
+              steps_completed += 1
+            end
+
+            {success: true, steps_completed: steps_completed, error: nil, env: env, tmux_session: @tmux_session}
+          rescue => e
+            {success: false, steps_completed: steps_completed, error: e.message, env: env, tmux_session: @tmux_session}
+          end
+
+          # Clean up resources created during setup (e.g. tmux session)
+          def teardown
+            return unless @tmux_session
+
+            system("tmux", "kill-session", "-t", @tmux_session, out: File::NULL, err: File::NULL)
+            @tmux_session = nil
+          end
+
+          private
+
+          # Dispatch a single step to the appropriate handler
+          #
+          # @param step [String, Hash] Step definition
+          # @param sandbox_dir [String] Sandbox path
+          # @param env [Hash] Environment variables
+          # @param fixture_source [String, nil] Fixtures path
+          def execute_step(step, sandbox_dir, env, fixture_source)
+            case step
+            when "git-init"
+              handle_git_init(sandbox_dir, env)
+            when "copy-fixtures"
+              handle_copy_fixtures(sandbox_dir, fixture_source)
+            when "tmux-session"
+              handle_tmux_session(env)
+            when Hash
+              execute_hash_step(step, sandbox_dir, env)
+            else
+              raise ArgumentError, "Unknown setup step: #{step.inspect}"
+            end
+          end
+
+          # Dispatch hash-based steps
+          def execute_hash_step(step, sandbox_dir, env)
+            key = step.keys.first
+            value = step.values.first
+
+            case key
+            when "run"
+              handle_run(value, sandbox_dir, env)
+            when "write-file"
+              handle_write_file(value["path"], value["content"], sandbox_dir)
+            when "agent-env"
+              handle_env(value, env)
+            when "tmux-session"
+              handle_tmux_session(env, value)
+            else
+              raise ArgumentError, "Unknown setup step type: #{key.inspect}"
+            end
+          end
+
+          # Create an isolated detached tmux session and store its name in env
+          def handle_tmux_session(env, config = nil)
+            name_source = config.is_a?(Hash) ? config["name-source"] : nil
+            session_name = if name_source == "run-id" && @run_id && !@run_id.to_s.empty?
+              @run_id
+            else
+              @scenario_name ? "#{@scenario_name}-e2e" : "ace-e2e-#{Time.now.to_i}"
+            end
+            _stdout, stderr, status = Open3.capture3("tmux", "new-session", "-d", "-s", session_name)
+            raise "Failed to create tmux session '#{session_name}': #{stderr.strip}" unless status.success?
+
+            @tmux_session = session_name
+            env["ACE_TMUX_SESSION"] = session_name
+          end
+
+          # Initialize a git repo with test user config
+          def handle_git_init(sandbox_dir, env)
+            run_command("git", "init", "-b", "main", chdir: sandbox_dir, env: env)
+            run_command("git", "config", "user.name", "Test User", chdir: sandbox_dir, env: env)
+            run_command("git", "config", "user.email", "test@example.com", chdir: sandbox_dir, env: env)
+          end
+
+          # Copy fixture files into sandbox
+          def handle_copy_fixtures(sandbox_dir, fixture_source)
+            raise ArgumentError, "No fixture source provided for copy-fixtures step" if fixture_source.nil?
+
+            FixtureCopier.new.copy(source_dir: fixture_source, target_dir: sandbox_dir)
+          end
+
+          # Execute a shell command in the sandbox
+          # NOTE: Uses shell invocation (bash -lc) intentionally to support
+          # shell operators (&&, |, >) in scenario.yml setup steps. Commands originate from
+          # committed scenario.yml files, not user input, so shell injection risk is mitigated.
+          def handle_run(command, sandbox_dir, env)
+            full_env = merged_environment(env)
+            # Re-export env vars after profile sourcing to protect against
+            # mise's shell hook clobbering (mise manages PROJECT_ROOT_PATH).
+            export_vars = env.dup
+            %w[PROJECT_ROOT_PATH ACE_TASKFLOW_PATH].each do |key|
+              export_vars[key] ||= ENV[key] if ENV[key]
+            end
+            exports = export_vars.map { |k, v| "export #{k}=#{Shellwords.shellescape(v.to_s)}" }.join("; ")
+            wrapped = exports.empty? ? command : "#{exports}; #{command}"
+            stdout, stderr, status = Open3.capture3(full_env, "bash", "-lc", wrapped, chdir: sandbox_dir)
+
+            unless status.success?
+              raise "Setup step 'run' failed (exit #{status.exitstatus}): #{command}\n#{stderr}"
+            end
+
+            stdout
+          end
+
+          # Write inline content to a file in the sandbox
+          def handle_write_file(path, content, sandbox_dir)
+            full_path = File.join(sandbox_dir, path)
+            FileUtils.mkdir_p(File.dirname(full_path))
+            File.write(full_path, content)
+          end
+
+          # Merge environment variables for subsequent steps
+          def handle_env(vars, env)
+            vars.each { |k, v| env[k.to_s] = v.to_s }
+          end
+
+          # Merge custom env vars with the process environment
+          #
+          # @param env [Hash] Custom environment variables
+          # @return [Hash] Merged environment
+          def merged_environment(env)
+            return ENV.to_h if env.empty?
+            ENV.to_h.merge(env.transform_keys(&:to_s))
+          end
+
+          # Run a command and raise on failure
+          def run_command(*args, chdir:, env: {})
+            _stdout, stderr, status = Open3.capture3(merged_environment(env), *args, chdir: chdir)
+
+            unless status.success?
+              raise "Command failed (exit #{status.exitstatus}): #{args.join(" ")}\n#{stderr}"
+            end
+          end
+        end
+      end
+    end
+  end
+end