agent-harness 0.5.8 → 0.6.0

data/lib/agent_harness/docker_command_executor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module AgentHarness
   # Executes commands inside a Docker container
   #
@@ -21,7 +23,9 @@ module AgentHarness
     # @param logger [Logger, nil] optional logger
     # @raise [CommandExecutionError] if Docker CLI is not found on the host
     def initialize(container_id:, logger: nil)
-      raise ArgumentError, "container_id cannot be nil or empty" if container_id.nil? || container_id.empty?
+      unless container_id.is_a?(String) && !container_id.strip.empty?
+        raise ArgumentError, "container_id cannot be nil or blank"
+      end
 
       super(logger: logger)
       @container_id = container_id
@@ -38,17 +42,142 @@ module AgentHarness
     # @param idle_timeout [Integer, Float, nil] idle timeout in seconds based on output activity
     # @param env [Hash] environment variables to set in the container
     # @param stdin_data [String, nil] data to send to stdin
+    # @param preparation [ExecutionPreparation, nil] request-scoped bootstrap
+    #   work to materialize inside the container before the main command runs
     # @return [Result] execution result
-    def execute(command, timeout: nil, idle_timeout: nil, env: {}, stdin_data: nil, **execution_options)
-      docker_cmd = build_docker_command(command, env: env, stdin_data: stdin_data)
-      super(
-        docker_cmd,
+    def execute(command, timeout: nil, idle_timeout: nil, env: {}, stdin_data: nil, preparation: nil, **execution_options)
+      start_time = current_time
+      normalized_command = normalize_command(command)
+      command_name = normalized_command.first
+      deadline = timeout_deadline(timeout)
+      cleanup_steps = []
+      execution_tracking = nil
+      held_preparation_locks = acquire_preparation_locks(
+        preparation,
+        env: env,
         timeout: timeout,
-        idle_timeout: idle_timeout,
-        env: {},
+        deadline: deadline,
+        command_name: command_name
+      )
+      background_cleanup_scheduled = false
+
+      apply_container_preparation(preparation, timeout: timeout, deadline: deadline, env: env, cleanup_steps: cleanup_steps)
+      execution_tracking = if timeout && !preparation.nil? && !preparation.empty?
+        build_container_execution_tracking(normalized_command, env: env)
+      end
+      docker_cmd = build_docker_command_for_execution(
+        normalized_command,
+        env: env,
         stdin_data: stdin_data,
-        **execution_options
+        execution_tracking: execution_tracking
+      )
+      begin
+        result = super(
+          docker_cmd,
+          timeout: remaining_timeout(deadline, timeout:, command_name: command_name),
+          idle_timeout: idle_timeout,
+          env: {},
+          stdin_data: stdin_data,
+          **execution_options
+        )
+      rescue IdleTimeoutError
+        raise
+      rescue TimeoutError
+        schedule_container_cleanup_preparation(
+          cleanup_steps,
+          held_preparation_locks,
+          command_name: command_name,
+          termination_command: execution_tracking && execution_tracking[:terminate_command],
+          finalizer_command: execution_tracking && execution_tracking[:cleanup_command]
+        )
+        background_cleanup_scheduled = true
+        held_preparation_locks = []
+        raise TimeoutError, "Command timed out after #{timeout} seconds: #{command_name}"
+      end
+      begin
+        cleanup_container_preparation(
+          cleanup_steps,
+          timeout:,
+          deadline: cleanup_deadline(deadline, timeout:),
+          command_name: command_name
+        )
+        cleanup_container_execution_tracking(
+          execution_tracking,
+          timeout:,
+          deadline: cleanup_deadline(deadline, timeout:),
+          command_name: command_name
+        )
+        execution_tracking = nil
+      rescue TimeoutError
+        # The main command already finished; omit termination_command so
+        # background cleanup does not TERM/KILL based on a stale PID file
+        # that may have been reused by an unrelated process.
+        schedule_container_cleanup_preparation(
+          cleanup_steps,
+          held_preparation_locks,
+          command_name: command_name,
+          termination_command: nil,
+          finalizer_command: execution_tracking && execution_tracking[:cleanup_command]
+        )
+        background_cleanup_scheduled = true
+        held_preparation_locks = []
+      end
+      Result.new(
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exit_code: result.exit_code,
+        duration: current_time - start_time
       )
+    ensure
+      pending_exception = $!
+      cleanup_pending = !cleanup_steps.nil? && !cleanup_steps.empty?
+      tracking_cleanup_pending = !execution_tracking.nil?
+      if !background_cleanup_scheduled && (cleanup_pending || tracking_cleanup_pending)
+        begin
+          cleanup_container_preparation(
+            cleanup_steps,
+            timeout:,
+            deadline: cleanup_deadline(deadline, timeout:),
+            command_name: command_name
+          )
+          cleanup_container_execution_tracking(
+            execution_tracking,
+            timeout:,
+            deadline: cleanup_deadline(deadline, timeout:),
+            command_name: command_name
+          )
+        rescue TimeoutError => e
+          raise e if pending_exception.nil?
+
+          if pending_exception.is_a?(TimeoutError)
+            schedule_container_cleanup_preparation(
+              cleanup_steps,
+              held_preparation_locks,
+              command_name: command_name,
+              termination_command: execution_tracking && execution_tracking[:terminate_command],
+              finalizer_command: execution_tracking && execution_tracking[:cleanup_command]
+            )
+            background_cleanup_scheduled = true
+            held_preparation_locks = []
+          else
+            # Preserve the original non-timeout exception; surface that
+            # cleanup also timed out so callers know bootstrap state may
+            # have leaked.
+            raise pending_exception.class,
+              "#{pending_exception.message} (cleanup also failed: #{e.message})"
+          end
+        rescue => e
+          raise e if pending_exception.nil?
+
+          # Surface cleanup failures even when unwinding from another exception,
+          # so callers know request-scoped bootstrap state may have leaked.
+          raise pending_exception.class,
+            "#{pending_exception.message} (cleanup also failed: #{e.message})"
+        end
+      end
+      unless background_cleanup_scheduled || held_preparation_locks.nil? || held_preparation_locks.empty?
+        release_preparation_locks(held_preparation_locks)
+      end
     end
 
     # Check if a binary exists inside the container
@@ -62,12 +191,374 @@ module AgentHarness
 
     private
 
+    def preparation_lock_scope
+      "docker:#{container_id}"
+    end
+
+    def preparation_lock_keys(preparation, env)
+      preparation.file_writes.map do |write|
+        "#{preparation_lock_scope}:#{normalize_container_lock_path(write.path, env)}"
+      end.uniq.sort
+    end
+
+    def apply_container_preparation(preparation, timeout:, deadline:, env:, cleanup_steps:)
+      return if preparation.nil? || preparation.empty?
+
+      preparation.file_writes.each do |write|
+        # materialize_file_write records the cleanup command after backing up
+        # the target, and its own rescue block runs that cleanup if any later
+        # step (mkdir, write, chmod) raises partway through.  Only fully
+        # materialized writes are appended to cleanup_steps here.
+        cleanup = materialize_file_write(write, timeout:, deadline:, env:)
+        cleanup_steps << cleanup
+      rescue => e
+        begin
+          cleanup_container_preparation(cleanup_steps, timeout:, deadline:, command_name: "docker")
+        rescue => cleanup_error
+          log_debug("Failed to clean up container runtime preparation", error: cleanup_error.message)
+        end
+        raise e
+      end
+    end
+
+    def cleanup_container_preparation(cleanup_steps, timeout:, deadline:, command_name:)
+      until cleanup_steps.empty?
+        cleanup = cleanup_steps.last
+        run_host_command(
+          cleanup[:command],
+          timeout: remaining_timeout(deadline, timeout:, command_name:),
+          stdin_data: nil
+        )
+        cleanup_steps.pop
+      end
+    end
+
+    def schedule_container_cleanup_preparation(
+      cleanup_steps,
+      held_preparation_locks,
+      command_name:,
+      termination_command: nil,
+      finalizer_command: nil
+    )
+      cleanup_deadline = timeout_deadline(PREPARATION_CLEANUP_GRACE_PERIOD)
+      Thread.new(
+        cleanup_steps,
+        held_preparation_locks,
+        cleanup_deadline,
+        command_name,
+        termination_command,
+        finalizer_command
+      ) do |steps, locks, deadline_at, cleanup_command_name, terminate_cmd, finalizer_cmd|
+        Thread.current.report_on_exception = false if Thread.current.respond_to?(:report_on_exception=)
+
+        begin
+          if terminate_cmd
+            run_host_command(
+              terminate_cmd,
+              timeout: remaining_timeout(deadline_at, timeout: PREPARATION_CLEANUP_GRACE_PERIOD, command_name: cleanup_command_name)
+            )
+          end
+          cleanup_container_preparation(
+            steps,
+            timeout: PREPARATION_CLEANUP_GRACE_PERIOD,
+            deadline: deadline_at,
+            command_name: cleanup_command_name
+          )
+        rescue => e
+          log_debug("Failed to clean up container runtime preparation after timeout", error: e.message)
+        ensure
+          if finalizer_cmd
+            begin
+              run_host_command(
+                finalizer_cmd,
+                timeout: remaining_timeout(deadline_at, timeout: PREPARATION_CLEANUP_GRACE_PERIOD, command_name: cleanup_command_name)
+              )
+            rescue => e
+              log_debug("Failed to clean up container execution tracking after timeout", error: e.message)
+            end
+          end
+          release_preparation_locks(locks) unless locks.nil? || locks.empty?
+        end
+      end
+    end
+
+    def build_container_execution_tracking(command, env:)
+      state_dir_path = "/tmp/agent-harness-execution-#{SecureRandom.hex(8)}"
+      state_dir = shell_path(state_dir_path)
+      pid_file = shell_path(File.join(state_dir_path, "pid"))
+      tracked_script = "printf %s $$ > #{pid_file} && exec #{Shellwords.join(normalize_command(command))}"
+      tracked_command = [
+        "sh",
+        "-lc",
+        "umask 077 && mkdir -p #{state_dir} && if command -v setsid >/dev/null 2>&1; then " \
+          "exec setsid sh -lc #{Shellwords.escape(tracked_script)}; else exec sh -lc " \
+          "#{Shellwords.escape(tracked_script)}; fi"
+      ]
+
+      {
+        command: tracked_command,
+        terminate_command: build_container_shell_command(
+          "if [ -f #{pid_file} ]; then pid=$(cat #{pid_file} 2>/dev/null); if [ -n \"$pid\" ]; then " \
+            "kill -TERM -- \"-$pid\" 2>/dev/null || kill -TERM \"$pid\" 2>/dev/null || true; " \
+            "i=0; while kill -0 \"$pid\" 2>/dev/null && [ \"$i\" -lt 10 ]; do sleep 0.1; i=$((i + 1)); done; " \
+            "kill -KILL -- \"-$pid\" 2>/dev/null || kill -KILL \"$pid\" 2>/dev/null || true; fi; fi",
+          env: env
+        ),
+        cleanup_command: build_container_shell_command("rm -rf #{state_dir}", env: env)
+      }
+    end
+
+    def build_docker_command_for_execution(command, env:, stdin_data:, execution_tracking:)
+      actual_command = execution_tracking ? execution_tracking[:command] : command
+      build_docker_command(actual_command, env: env, stdin_data: stdin_data)
+    end
+
+    def cleanup_container_execution_tracking(execution_tracking, timeout:, deadline:, command_name:)
+      return if execution_tracking.nil?
+
+      run_host_command(
+        execution_tracking.fetch(:cleanup_command),
+        timeout: remaining_timeout(deadline, timeout:, command_name:),
+        stdin_data: nil
+      )
+    end
+
+    def materialize_file_write(write, timeout:, deadline:, env:)
+      validate_preparation_path_security!(write.path)
+      validate_preparation_path_env!(write.path, env)
+      validate_home_relative_preparation_path!(write.path, env)
+      resolved_write_path = resolve_container_preparation_path(write.path, env)
+      path = shell_path(resolved_write_path)
+      dir = shell_path(File.dirname(resolved_write_path))
+      state_dir_path = "/tmp/agent-harness-preparation-#{SecureRandom.hex(8)}"
+      state_dir = shell_path(state_dir_path)
+      backup = shell_path(File.join(state_dir_path, "backup"))
+      state = shell_path(File.join(state_dir_path, "state"))
+      symlink_target = shell_path(File.join(state_dir_path, "symlink_target"))
+      created_directories = shell_path(File.join(state_dir_path, "created_directories"))
+      invalid_target_message = Shellwords.escape(
+        "preparation target must be a regular file or symlink: #{write.path}"
+      )
+      directory_change_message = Shellwords.escape(
+        "preparation target changed into a directory during execution: #{write.path}"
+      )
+      cleanup_state_dir_cmd = build_container_shell_command("rm -rf #{state_dir}", env: env)
+      backup_cmd = build_container_shell_command(
+        "umask 077 && mkdir -p #{state_dir} && : > #{created_directories} && " \
+          "#{record_created_directories_script(resolved_write_path, created_directories)}" \
+          "if [ -L #{path} ]; then readlink #{path} > #{symlink_target} && printf symlink > #{state}; " \
+          "elif [ -d #{path} ]; then printf '%s\\n' #{invalid_target_message} >&2; exit 1; " \
+          "elif [ -e #{path} ]; then cp -p #{path} #{backup} && printf file > #{state}; " \
+          "else printf missing > #{state}; fi",
+        env: env
+      )
+      run_host_command(backup_cmd, timeout: remaining_timeout(deadline, timeout:, command_name: "docker"))
+      cleanup = {
+        command: build_container_shell_command(
+          "cleanup_status=0; state_value=$(cat #{state} 2>/dev/null); if [ -d #{path} ] && [ ! -L #{path} ]; then " \
+            "printf '%s\\n' #{directory_change_message} >&2; cleanup_status=1; " \
+            "elif [ \"$state_value\" = symlink ]; then " \
+            "mkdir -p #{dir} && rm -f -- #{path} && ln -s -- \"$(cat #{symlink_target})\" #{path} || cleanup_status=$?; " \
+            "elif [ \"$state_value\" = file ]; then " \
+            "if [ -f #{backup} ]; then mkdir -p #{dir} && rm -f -- #{path} && cp -p #{backup} #{path} || cleanup_status=$?; " \
+            "else echo \"missing runtime preparation backup: #{backup}\" >&2; cleanup_status=1; fi; " \
+            "elif [ \"$state_value\" = missing ]; then rm -f -- #{path} || cleanup_status=$?; " \
+            "else cleanup_status=1; " \
+            "fi; #{cleanup_created_directories_script(created_directories)}" \
+            "if [ $cleanup_status -eq 0 ]; then rm -rf #{state_dir}; fi; exit $cleanup_status",
+          env: env
+        )
+      }
+
+      mkdir_cmd = build_container_shell_command("mkdir -p #{dir}", env: env)
+      run_host_command(mkdir_cmd, timeout: remaining_timeout(deadline, timeout:, command_name: "docker"))
+
+      remove_symlink_cmd = build_container_shell_command(
+        "state_value=$(cat #{state} 2>/dev/null); if [ \"$state_value\" = symlink ]; then rm -f -- #{path}; fi",
+        env: env
+      )
+      run_host_command(remove_symlink_cmd, timeout: remaining_timeout(deadline, timeout:, command_name: "docker"))
+
+      write_cmd = build_container_shell_command("cat > #{path}", env: env, stdin_data: write.content)
+      run_host_command(
+        write_cmd,
+        timeout: remaining_timeout(deadline, timeout:, command_name: "docker"),
+        stdin_data: write.content
+      )
+
+      if write.mode
+        chmod_cmd = build_container_shell_command("chmod #{write.mode.to_s(8)} #{path}", env: env)
+        run_host_command(chmod_cmd, timeout: remaining_timeout(deadline, timeout:, command_name: "docker"))
+      end
+
+      cleanup
+    rescue => e
+      if cleanup
+        begin
+          run_host_command(
+            cleanup[:command],
+            timeout: remaining_timeout(deadline, timeout:, command_name: "docker")
+          )
+        rescue => cleanup_error
+          log_debug("Failed to clean up container runtime preparation", error: cleanup_error.message)
+        end
+      elsif defined?(cleanup_state_dir_cmd)
+        begin
+          run_host_command(
+            cleanup_state_dir_cmd,
+            timeout: remaining_timeout(deadline, timeout:, command_name: "docker")
+          )
+        rescue => cleanup_error
+          log_debug("Failed to clean up container runtime preparation", error: cleanup_error.message)
+        end
+      end
+      raise e
+    end
+
+    def record_created_directories_script(path, created_directories_file)
+      parent_preparation_paths(path).map do |parent_path|
+        rendered_parent = shell_path(parent_path)
+        "if [ ! -e #{rendered_parent} ]; then printf '%s\\n' #{rendered_parent} >> #{created_directories_file}; fi; "
+      end.join
+    end
+
+    def cleanup_created_directories_script(created_directories_file)
+      "while IFS= read -r cleanup_dir; do " \
+        "if [ -d \"$cleanup_dir\" ] && [ ! -L \"$cleanup_dir\" ]; then rmdir -- \"$cleanup_dir\" 2>/dev/null || true; fi; " \
+        "done < #{created_directories_file}; "
+    end
+
+    def parent_preparation_paths(path)
+      parents = []
+      current = File.dirname(path)
+
+      until current == "." || current == "/" || current == File.dirname(current)
+        parents << current
+        current = File.dirname(current)
+      end
+
+      parents << current if current == "~"
+      parents
+    end
+
+    def run_host_command(command, timeout:, stdin_data: nil)
+      result = CommandExecutor.instance_method(:execute).bind_call(
+        self,
+        command,
+        timeout: timeout,
+        env: {},
+        stdin_data: stdin_data,
+        preparation: nil
+      )
+      return result if result.success?
+
+      message = result.stderr.to_s.strip
+      message = result.stdout.to_s.strip if message.empty?
+      message = "command failed with exit code #{result.exit_code}" if message.empty?
+      raise CommandExecutionError, "Failed to apply runtime preparation: #{message}"
+    end
+
     def validate_docker!
       return if ENV["PATH"]&.split(File::PATH_SEPARATOR)&.any? { |path| File.executable?(File.join(path, "docker")) }
 
       raise CommandExecutionError, "Docker CLI not found on host PATH"
     end
 
+    def build_container_shell_command(script, env:, stdin_data: nil)
+      build_docker_command(["sh", "-lc", script], env: env, stdin_data: stdin_data)
+    end
+
+    def resolve_preparation_path_env_var(key, env)
+      unless env.key?(key)
+        raise ArgumentError, "#{key} cannot be nil or empty for env-backed preparation paths"
+      end
+
+      value = env[key]
+      raise ArgumentError, "#{key} cannot be nil or empty for env-backed preparation paths" if value.nil? || value.empty?
+      raise ArgumentError, "#{key} must not contain path traversal" if value.include?("..")
+
+      value
+    end
+
+    def normalize_container_lock_path(path, env)
+      validate_home_relative_preparation_path!(path, env)
+
+      expanded_path = path.gsub(/\$(\w+)|\$\{([^}]+)\}/) do
+        key = Regexp.last_match(1) || Regexp.last_match(2)
+        resolve_preparation_path_env_var(key, env)
+      end
+
+      return env.key?("HOME") ? File.expand_path(env.fetch("HOME")) : "home" if expanded_path == "~"
+      if expanded_path.start_with?("~/")
+        if env.key?("HOME")
+          return File.expand_path(File.join(env.fetch("HOME"), expanded_path.delete_prefix("~/")))
+        end
+
+        normalized = File.expand_path(expanded_path.delete_prefix("~/"), "/").delete_prefix("/")
+        return normalized.empty? ? "home" : "home/#{normalized}"
+      end
+
+      return File.expand_path(expanded_path) if expanded_path.start_with?("/")
+
+      normalized = File.expand_path(expanded_path, "/").delete_prefix("/")
+      normalized.empty? ? "relative" : "relative/#{normalized}"
+    end
+
+    def validate_home_relative_preparation_path!(path, env)
+      return unless path == "~" || path.start_with?("~/")
+      return unless env.key?("HOME")
+
+      home = env["HOME"]
+      raise ArgumentError, "HOME cannot be nil or empty for home-relative preparation paths" if home.nil? || home.empty?
+      raise ArgumentError, "HOME must not contain path traversal" if home.include?("..")
+    end
+
+    def resolve_container_preparation_path(path, env)
+      return path unless path == "~" || path.start_with?("~/")
+      return path unless env.key?("HOME")
+
+      home = env.fetch("HOME")
+      return home if path == "~"
+
+      File.join(home, path.delete_prefix("~/"))
+    end
+
+    def shell_path(path)
+      return "~" if path == "~"
+      return shell_escaped_path(path) unless path.start_with?("~/")
+
+      suffix = path.delete_prefix("~/")
+      escaped_suffix = suffix.split("/").map { |segment| shell_path_segment(segment) }.join("/")
+      "~/#{escaped_suffix}"
+    end
+
+    def shell_escaped_path(path)
+      prefix = path.start_with?("/") ? "/" : ""
+      trimmed_path = path.delete_prefix("/")
+      escaped_segments = trimmed_path.split("/").map { |segment| shell_path_segment(segment) }
+      "#{prefix}#{escaped_segments.join("/")}"
+    end
+
+    def shell_path_segment(segment)
+      rendered = +""
+      index = 0
+
+      segment.to_enum(:scan, /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/).each do
+        match = Regexp.last_match
+        literal = segment[index...match.begin(0)]
+        rendered << Shellwords.escape(literal) unless literal.empty?
+
+        var_name = match[1] || match[2]
+        rendered << %("${#{var_name}}")
+        index = match.end(0)
+      end
+
+      tail = segment[index..]
+      rendered << Shellwords.escape(tail) unless tail.nil? || tail.empty?
+
+      rendered.empty? ? "''" : rendered
+    end
+
     def build_docker_command(command, env:, stdin_data:)
       cmd = ["docker", "exec"]
       unset_env_keys = []

data/lib/agent_harness/error_taxonomy.rb

@@ -122,17 +122,17 @@ module AgentHarness
         case message
         when /idle.?timeout/i
           :idle_timeout
-        when /rate.?limit|too many requests|429/i
+        when /rate.?limit|too many requests|\b429\b/i
           :rate_limited
         when /quota|usage.?limit|billing/i
           :quota_exceeded
-        when /auth|unauthorized|forbidden|invalid.*(key|token)|401|403/i
+        when /auth|unauthorized|forbidden|invalid.*(key|token)|\b401\b|\b403\b/i
           :auth_expired
         when /timeout|timed.?out/i
           :timeout
-        when /temporary|retry|503|502|500/i
+        when /temporary|retry|\b503\b|\b502\b|\b500\b/i
           :transient
-        when /invalid|malformed|bad.?request|400/i
+        when /invalid|malformed|bad.?request|\b400\b/i
           :permanent
         else
           :unknown

data/lib/agent_harness/execution_preparation.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Structured runtime bootstrap contract for request-scoped executor setup.
+  #
+  # Providers can use this to request file materialization or similar
+  # preparation without forcing downstream applications to shell-wrap the main
+  # provider command.
+  class ExecutionPreparation
+    # Declarative file write request that executors can materialize in their
+    # own runtime environment.
+    FileWrite = Struct.new(:path, :content, :mode, keyword_init: true) do
+      def initialize(path:, content:, mode: nil)
+        raise ArgumentError, "path must be a non-empty String" unless path.is_a?(String) && !path.empty?
+        raise ArgumentError, "content must be a String" unless content.is_a?(String)
+        if !mode.nil? && (!mode.is_a?(Integer) || mode.negative?)
+          raise ArgumentError, "mode must be a non-negative Integer or nil"
+        end
+
+        super
+        freeze
+      end
+    end
+
+    attr_reader :file_writes
+
+    def initialize(file_writes: [])
+      writes = file_writes || []
+      unless writes.is_a?(Array)
+        raise ArgumentError, "file_writes must be an Array (got #{writes.class})"
+      end
+
+      @file_writes = writes.map.with_index do |write, index|
+        case write
+        when FileWrite
+          write
+        when Hash
+          FileWrite.new(
+            path: fetch_value(write, :path),
+            content: fetch_value(write, :content),
+            mode: write.key?(:mode) ? write[:mode] : write["mode"]
+          )
+        else
+          raise ArgumentError,
+            "file_writes must contain FileWrite or Hash entries; invalid element at index #{index}: #{write.inspect} (#{write.class})"
+        end
+      end.freeze
+
+      freeze
+    end
+
+    def empty?
+      file_writes.empty?
+    end
+
+    private
+
+    def fetch_value(hash, key)
+      return hash[key] if hash.key?(key)
+
+      hash[key.to_s]
+    end
+  end
+end