sandcrawler 0.1.0

data/lib/sandcrawler/cli/devices.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Sandcrawler
+  class CLI
+    module Devices
+      private
+
+      def picotool
+        Acquisition::Picotool.new(executable: @options[:picotool], log: @log)
+      end
+
+      def run_doctor(_args)
+        @log.warn("Preserve a BOOTSEL dump before using flash_nuke.uf2 or reinstalling firmware.")
+        result = { ruby: RUBY_VERSION, platform: RUBY_PLATFORM, serialport: !Gem::Specification.find_all_by_name("serialport").empty? }
+        begin
+          tool = picotool
+          result[:picotool] = { version: tool.version }
+          begin
+            result[:device] = tool.info
+          rescue Error => e
+            result[:device] = { available: false, detail: e.message }
+          end
+        rescue Error => e
+          result[:picotool] = { available: false, detail: e.message }
+        end
+        if RUBY_PLATFORM.include?("linux")
+          result[:usb_permissions] =
+            "picotool info checks access; install the upstream udev rules if permission is denied"
+        end
+        emit(result) { result.each { |key, value| @stdout.puts("#{key}: #{value}") } }
+        0
+      end
+
+      def run_dump(_args)
+        result = picotool.dump(@options[:out], passes: @options[:passes], force: @options[:force])
+        emit(result) { @stdout.puts("Preserved dump in #{@options[:out]}: #{result.dig(:result, :sha256)}") }
+        result.dig(:result, :unstable_blocks).to_a.empty? ? 0 : 5
+      end
+
+      def run_copy(args)
+        result = Acquisition::MountedVolume.new(args.first).copy(@options[:out], force: @options[:force], log: @log)
+        emit(result) { @stdout.puts("Copied #{result[:files].size} files to #{@options[:out]}") }
+        result_code(result)
+      end
+
+      def run_serial(_args)
+        port = @options[:port] || select_port
+        shell = Acquisition::SerialShell.new(port: port, log: @log)
+        result = shell.copy(@options[:out], force: @options[:force], root: @options[:root] || "/")
+        emit(result) { @stdout.puts("Transferred #{result[:files].size} files to #{@options[:out]}") }
+        result_code(result)
+      end
+
+      def select_port
+        ports = Acquisition::SerialShell.ports
+        raise DeviceNotFoundError, "No serial ports found; pass --port for R2P2 CDC0" if ports.empty?
+
+        @stderr.puts("Choose R2P2 CDC0 (shell), not CDC1/CDC2:")
+        ports.each_with_index { |port, i| @stderr.puts("#{i + 1}: #{port}") }
+        index = number(prompt("Port number")) - 1
+        raise UsageError, "Invalid serial port selection" unless index.between?(0, ports.size - 1)
+
+        ports[index]
+      end
+
+      def run_auto(_args)
+        base = @options[:out]
+        raise SafetyError, "Output is a symlink: #{base}" if File.symlink?(base)
+        if File.exist?(base) && (!File.directory?(base) || (!@options[:force] && !Dir.empty?(base)))
+          raise SafetyError, "Output must be an empty directory (or use --force): #{base}"
+        end
+
+        route = prompt("Recovery route: [a] BOOTSEL (recommended), [b] mounted volume, [c] serial",
+                       default: "a").downcase
+        raise UsageError, "Choose a, b, or c" unless %w[a b c].include?(route)
+
+        @options[:out] = File.join(base, "acquisition") if route == "a"
+        code = case route
+               when "a"
+                 dump = picotool.dump(@options[:out], passes: @options[:passes], force: @options[:force])
+                 unless dump.dig(:result, :unstable_blocks).to_a.empty?
+                   emit(dump) { @stdout.puts("Dump contains unstable blocks; inspect dump.json before recovery") }
+                   return 5
+                 end
+
+                 image = File.join(@options[:out], "dump.bin")
+                 @options[:out] = File.join(base, "recovered")
+                 run_extract([image])
+               when "b"
+                 run_copy([prompt("Mounted R2P2 directory")])
+               when "c"
+                 run_serial([])
+               end
+        code
+      ensure
+        @stderr.puts("Check the dump and recovered files before erasing or reinstalling R2P2. Keep dump.bin.")
+      end
+
+      def prompt(message, default: nil)
+        @stderr.print("#{message}: ")
+        input = @stdin.gets
+        raise UsageError, "Interactive input required; use an explicit command for unattended operation" unless input
+
+        value = input.strip
+        value.empty? && default ? default : value
+      end
+    end
+  end
+end

data/lib/sandcrawler/cli/offline.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Sandcrawler
+  class CLI
+    module Offline
+      private
+
+      def run_scan(args)
+        image = Image.open(args.first)
+        candidates = locate(image)
+        emit(candidates.map(&:to_h)) do
+          candidates.each do |candidate|
+            line = format("0x%<offset>08X  score=%<score>s  %<geometry>s",
+                          offset: candidate.offset, score: candidate.score, geometry: candidate.boot_sector.to_h)
+            @stdout.puts(line)
+          end
+        end
+        0
+      ensure
+        image&.close
+      end
+
+      def run_ls(args)
+        image = Image.open(args.first)
+        volume = open_volume(image)
+        entries = volume.each_entry(deleted: @options[:deleted]).to_a
+        emit(entries.map(&:to_h)) do
+          entries.each do |entry|
+            prefix = @options[:long] ? "#{entry.size.to_s.rjust(10)} #{entry.mtime&.iso8601 || '-'} " : ""
+            name = Log.escape(entry.path)
+            @stdout.puts("#{prefix}#{'[deleted] ' if entry.deleted?}#{name}#{'/' if entry.directory?}")
+          end
+        end
+        volume.warnings.each { |warning| @log.warn(warning.to_s) }
+        volume.warnings.empty? ? 0 : 4
+      ensure
+        image&.close
+      end
+
+      def run_extract(args)
+        path = args.first
+        protect_input(path)
+        protect_input(@options[:reference]) if @options[:reference]
+        image = Image.open(path)
+        source = { type: "image", path: File.expand_path(path), sha256: Digest::SHA256.file(path).hexdigest,
+                   size: File.size(path), image_size: image.size }
+        if @options[:reference]
+          source[:reference_image] = { path: File.expand_path(@options[:reference]),
+                                       sha256: Digest::SHA256.file(@options[:reference]).hexdigest }
+        end
+        volume = volume_for_extraction(image)
+        output = Extractor.new(@options[:out], source: source, volume: volume&.metadata,
+                                               force: @options[:force], log: @log)
+        if @options[:reference]
+          output.warning("REFERENCE_GEOMETRY",
+                         "Geometry borrowed from #{@options[:reference]}; verify firmware and board match")
+        end
+        output.warning("MANUAL_GEOMETRY", @options[:geometry].inspect) if @options[:geometry]
+        Array(image.respond_to?(:warnings) ? image.warnings : []).each { |w| record_warning(output, w) }
+        if volume
+          extract_volume(volume, output)
+        else
+          output.warning("NO_FAT_VOLUME", "No usable FAT boot sector; carving the image without filesystem metadata")
+        end
+        carve(image, volume, output) if @options[:carve]
+        verify_source(source, output)
+        verify_source(source[:reference_image], output) if source[:reference_image]
+        manifest = output.finish
+        emit(manifest) { @stdout.puts("Recovered #{manifest[:files].size} files to #{output.out}") }
+        volume ? result_code(manifest) : 4
+      rescue Error, IOError, SystemCallError => e
+        if output
+          output.warning("EXTRACTION_FAILED", e.message)
+          output.finish
+        end
+        raise
+      ensure
+        image&.close
+      end
+
+      def verify_source(source, output)
+        return if Digest::SHA256.file(source[:path]).hexdigest == source[:sha256]
+
+        output.warning("SOURCE_CHANGED", "Source changed during recovery: #{source[:path]}")
+        raise IntegrityError, "Source changed during recovery; saved results need a fresh acquisition"
+      rescue IOError, SystemCallError => e
+        output.warning("SOURCE_CHANGED", "Cannot verify source after recovery: #{e.message}")
+        raise IntegrityError, "Source could not be verified after recovery"
+      end
+
+      def volume_for_extraction(image)
+        open_volume(image)
+      rescue FormatError
+        raise unless @options[:carve] && !@options[:geometry] && !@options[:reference] && !@options[:offset]
+
+        nil
+      end
+
+      def extract_volume(volume, output)
+        volume.each_entry do |entry|
+          if entry.directory?
+            output.directory(path: entry.path, mtime: entry.mtime, attributes: entry.attributes,
+                             first_cluster: entry.first_cluster)
+          else
+            write_result(output, entry, volume.read(entry), "files")
+          end
+        end
+        if @options[:deleted]
+          Recovery::Undelete.new(volume).each { |entry, result| write_result(output, entry, result, "deleted") }
+        end
+        if @options[:orphans]
+          Recovery::Orphans.new(volume).each { |entry, result| write_result(output, entry, result, "lost+found") }
+        end
+        volume.warnings.each { |warning| record_warning(output, warning) }
+      end
+
+      def write_result(output, entry, result, category)
+        output.write(path: entry.path, original_name: entry.name, data: result.data, category: category,
+                     status: result.status, mtime: entry.mtime, attributes: entry.attributes,
+                     first_cluster: entry.first_cluster, expected_size: entry.size, warnings: result.warnings)
+        result.warnings.each { |warning| record_warning(output, warning) }
+      end
+
+      def record_warning(output, warning)
+        if warning.is_a?(Hash)
+          output.warning(warning[:code] || warning["code"], warning[:detail] || warning["detail"])
+        else
+          output.warning("RECOVERY_WARNING", warning.to_s)
+        end
+      end
+
+      def carve(image, volume, output)
+        boot = volume&.boot_sector
+        options = if boot
+                    { offset: volume.offset + (boot.first_data_sector * boot.bytes_per_sector),
+                      block_size: boot.cluster_size, length: boot.cluster_count * boot.cluster_size }
+                  else
+                    {}
+                  end
+        Recovery::Carver.new(image, **options).each { |entry, result| write_result(output, entry, result, "carved") }
+      end
+
+      def open_volume(image)
+        candidate = locate(image).first
+        raise FormatError, "No FAT volume found; try --reference-image, --geometry, or extract --carve" unless candidate
+
+        volume = FAT::Volume.new(image, offset: candidate.offset, boot_sector: candidate.boot_sector,
+                                        fat: @options[:fat], codepage: @options[:codepage])
+        volume.warnings.concat(candidate.warnings) if candidate.respond_to?(:warnings)
+        volume
+      end
+
+      def locate(image)
+        if @options[:geometry]
+          offset = @options[:offset] || @options[:geometry][:offset] || 0
+          begin
+            boot = FAT::BootSector.from_geometry(@options[:geometry], available_size: image.size - offset)
+          rescue FormatError => e
+            raise UsageError, e.message
+          end
+          return [manual_candidate(offset, boot)]
+        end
+        source = @options[:reference] ? Image.open(@options[:reference]) : image
+        if @options.key?(:offset)
+          offset = @options[:offset]
+          boot = FAT::BootSector.new(source.read_at(offset, 512), available_size: image.size - offset)
+          return [manual_candidate(offset, boot)]
+        end
+        candidates = FAT::VolumeLocator.new(source).candidates
+        candidates.each { |candidate| @log.debug(candidate.to_h.inspect) }
+        candidates
+      ensure
+        source&.close if source && source != image
+      end
+
+      def manual_candidate(offset, boot)
+        Struct.new(:offset, :boot_sector, :score) do
+          def to_h
+            boot_sector.to_h.merge(offset: offset, score: score)
+          end
+        end.new(offset, boot, 0)
+      end
+
+      def protect_input(path)
+        input = File.realpath(path)
+        parent = File.expand_path(@options[:out])
+        tail = []
+        until File.exist?(parent) || File.symlink?(parent)
+          tail.unshift(File.basename(parent))
+          parent = File.dirname(parent)
+        end
+        destination = File.join(File.realpath(parent), *tail)
+        return unless input == destination || input.start_with?(destination + File::SEPARATOR)
+
+        raise SafetyError, "Output must not contain the source image: #{path}"
+      end
+    end
+  end
+end

data/lib/sandcrawler/cli.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "cli/offline"
+require_relative "cli/devices"
+
+module Sandcrawler
+  class CLI
+    include Offline
+    include Devices
+
+    COMMANDS = %w[doctor dump scan ls extract copy serial auto].freeze
+
+    def initialize(stdout: $stdout, stderr: $stderr, stdin: $stdin)
+      @stdout = stdout
+      @stderr = stderr
+      @stdin = stdin
+    end
+
+    def run(arguments)
+      args = arguments.dup
+      return @stdout.puts(VERSION) || 0 if args == ["--version"]
+      return @stdout.puts(help) || 0 if args.empty? || %w[-h --help].include?(args.first)
+
+      command = args.shift
+      raise UsageError, "Unknown command: #{command}" unless COMMANDS.include?(command)
+
+      @options = { passes: 2, codepage: "IBM437" }
+      parser = option_parser(command)
+      parser.parse!(args)
+      return @stdout.puts(parser) || 0 if @options[:help]
+
+      validate_arguments(command, args)
+      @log = Log.new(io: @stderr, verbose: @options[:verbose], quiet: @options[:quiet])
+      send("run_#{command}", args)
+    rescue UsageError, OptionParser::ParseError => e
+      @stderr.puts("#{Log.escape(e.message)}\nUse sandcrawler --help for usage.")
+      2
+    rescue DeviceNotFoundError => e
+      @stderr.puts(Log.escape(e.message))
+      3
+    rescue IntegrityError => e
+      @stderr.puts(Log.escape(e.message))
+      5
+    rescue Error, SystemCallError, IOError => e
+      @stderr.puts(Log.escape(e.message))
+      1
+    end
+
+    private
+
+    def help
+      <<~TEXT
+        sandcrawler #{VERSION} — read-only R2P2 file recovery
+        Usage: sandcrawler COMMAND [IMAGE|MOUNTPOINT] [options]
+          doctor                 Check environment and optional acquisition tools
+          dump -o DIR            Preserve BOOTSEL flash with repeated reads
+          scan IMAGE             List all FAT volume candidates
+          ls IMAGE               List files (--long, --deleted)
+          extract IMAGE -o DIR   Recover files (--deleted, --orphans, --carve)
+          copy MOUNTPOINT -o DIR Copy a mounted volume without following symlinks
+          serial -o DIR          Transfer files from CDC0 (--port PORT)
+          auto -o DIR            Choose a route interactively and recover
+        Use COMMAND --help for options. Dump before using flash_nuke.uf2.
+      TEXT
+    end
+
+    def option_parser(command)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: sandcrawler #{command} [IMAGE|MOUNTPOINT] [options]"
+        parser.on("-o", "--output DIR", "Output directory") { |v| @options[:out] = v }
+        parser.on("--offset N", "Volume byte offset (decimal or 0xHEX)") { |v| @options[:offset] = number(v) }
+        parser.on("--geometry VALUES", "bps,spc,rsvd,fats,fatsz,root[,total,offset,root_cluster]") do |v|
+          @options[:geometry] = geometry(v)
+        end
+        parser.on("--reference-image FILE") { |v| @options[:reference] = v }
+        parser.on("--fat N", %w[1 2]) { |v| @options[:fat] = v.to_i }
+        parser.on("--codepage NAME") do |v|
+          @options[:codepage] = Encoding.find(v).name
+        rescue ArgumentError
+          raise UsageError, "Unknown codepage: #{v}"
+        end
+        parser.on("--passes N", Integer) { |v| @options[:passes] = v }
+        parser.on("--picotool PATH") { |v| @options[:picotool] = v }
+        parser.on("--port PORT") { |v| @options[:port] = v }
+        parser.on("--root PATH", "Serial source directory (default /)") { |v| @options[:root] = v }
+        %i[deleted orphans carve long json verbose quiet force].each do |option|
+          parser.on("--#{option}") { @options[option] = true }
+        end
+        parser.on("-h", "--help") { @options[:help] = true }
+      end
+    end
+
+    def validate_arguments(command, args)
+      count = %w[scan ls extract copy].include?(command) ? 1 : 0
+      raise UsageError, "#{command} expects #{count} input path(s)" unless args.size == count
+      if %w[dump extract copy serial auto].include?(command) && !@options[:out]
+        raise UsageError, "#{command} requires -o DIR"
+      end
+      raise UsageError, "--passes must be at least 2" if @options[:passes] < 2
+      return unless @options[:geometry] && @options[:reference]
+
+      raise UsageError, "Choose --geometry or --reference-image"
+    end
+
+    def number(value)
+      result = Integer(value, value.start_with?("0x", "0X") ? 16 : 10)
+      raise ArgumentError if result.negative?
+
+      result
+    rescue ArgumentError
+      raise UsageError, "Invalid nonnegative integer: #{value}"
+    end
+
+    def geometry(value)
+      allowed = %w[bps spc rsvd fats fatsz root total totsec offset root_cluster media]
+      fields = value.split(",", -1).each_with_object({}) do |field, result|
+        key, number = field.split("=", 2)
+        raise UsageError, "Invalid geometry field: #{field}" unless allowed.include?(key) && number
+        raise UsageError, "Duplicate geometry field: #{key}" if result.key?(key.to_sym)
+
+        result[key.to_sym] = self.number(number)
+      end
+      missing = %i[bps spc rsvd fats fatsz root] - fields.keys
+      raise UsageError, "Missing geometry fields: #{missing.join(', ')}" unless missing.empty?
+      raise UsageError, "Specify either total or totsec, not both" if fields.key?(:total) && fields.key?(:totsec)
+
+      fields
+    end
+
+    def emit(value)
+      if @options[:json]
+        @stdout.puts(JSON.pretty_generate(Manifest.json_safe(value)))
+      elsif !@options[:quiet]
+        yield if block_given?
+      end
+    end
+
+    def result_code(manifest)
+      loss_codes = %w[DIRECTORY_DAMAGED DIRECTORY_ERROR DIRECTORY_LOOP DIRECTORY_WRITE_ERROR COPY_FAILED LIST_FAILED
+                      FILE_ERROR UF2_INCOMPLETE FAT_ERASED_ENTRY CHAIN_ERROR CHAIN_FREE CHAIN_TOO_LONG CROSS_LINK
+                      DUPLICATE_ENTRY]
+      partial = manifest[:files].any? { |file| file[:status] != "ok" }
+      partial ||= manifest[:warnings].any? { |warning| loss_codes.include?(warning[:code]) }
+      partial ? 4 : 0
+    end
+  end
+end

data/lib/sandcrawler/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Sandcrawler
+  class Error < StandardError; end
+  class UsageError < Error; end
+  class SafetyError < Error; end
+  class DeviceNotFoundError < Error; end
+  class IntegrityError < Error; end
+  class OutOfRangeError < Error; end
+  class FormatError < Error; end
+end

data/lib/sandcrawler/extractor.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+require "json"
+require "digest"
+
+module Sandcrawler
+  class Extractor
+    CATEGORIES = [nil, "files", "deleted", "lost+found", "carved"].freeze
+    attr_reader :out, :manifest
+
+    def initialize(out, source:, volume: nil, force: false, log: nil)
+      @out = File.expand_path(out)
+      raise SafetyError, "Output is a symlink: #{@out}" if File.symlink?(@out)
+      if File.exist?(@out) && (!File.directory?(@out) || (!force && !Dir.empty?(@out)))
+        raise SafetyError, "Output must be an empty directory (or use --force): #{@out}"
+      end
+
+      FileUtils.mkdir_p(@out)
+      @out = File.realpath(@out)
+      @manifest = Manifest.new(source: source, volume: volume)
+      @paths = PathSanitizer.new
+      @log = log || Log.new
+      @directory_times = []
+    end
+
+    def write(path:, data:, category: "files", status: "ok", mtime: nil, original_name: nil, **metadata)
+      validate_category(category)
+      entry = metadata.merge(path: path, original_name: original_name || path.to_s.b.split("/").last,
+                             status: status, mtime: mtime&.iso8601)
+      %i[path original_name].each do |key|
+        text = entry[key].to_s.dup.force_encoding(Encoding::UTF_8)
+        entry[:"#{key}_hex"] = text.b.unpack1("H*") unless text.valid_encoding?
+        entry[key] = text.scrub
+      end
+      relative = output_path(path, category, status)
+      target = safe_target(relative)
+      Tempfile.create([".sandcrawler-", ".tmp"], File.dirname(target), binmode: true) do |file|
+        begin
+          data.is_a?(String) ? file.write(data.b) : IO.copy_stream(data, file)
+        rescue IOError, SystemCallError => e
+          raise unless file.size.positive?
+
+          warning("FILE_ERROR", "#{path}: #{e.message}; preserving readable prefix")
+          entry[:status] = "read_error"
+          relative = output_path(path, category, "read_error")
+          target = safe_target(relative)
+        end
+        if entry[:status] == "ok" && entry[:expected_size] && file.size != entry[:expected_size]
+          warning("SIZE_MISMATCH", "#{path}: expected #{entry[:expected_size]} bytes, recovered #{file.size}")
+          entry[:status] = file.size < entry[:expected_size] ? "truncated" : "read_error"
+          relative = output_path(path, category, entry[:status])
+          target = safe_target(relative)
+        end
+        commit_file(file, target)
+      end
+      entry.merge!(output: relative, size: File.size(target), sha256: Digest::SHA256.file(target).hexdigest)
+      restore_time(target, mtime) if mtime
+      @manifest.data[:files] << entry
+      entry
+    rescue IOError, SystemCallError => e
+      warning("FILE_ERROR", "#{path}: #{e.message}")
+      entry ||= { path: path, original_name: original_name }
+      entry.merge!(status: "read_error", output: nil, sha256: nil)
+      @manifest.data[:files] << entry
+      entry
+    end
+
+    def directory(path:, category: "files", mtime: nil, **metadata)
+      validate_category(category)
+      entry = metadata.merge(path: path, original_name: path.to_s.b.split("/").last,
+                             mtime: mtime&.iso8601, status: "ok")
+      relative = @paths.path(path, namespace: category, directory: true)
+      target = safe_target("#{relative}/.directory-check")
+      @directory_times << [File.dirname(target), mtime] if mtime
+      @manifest.data[:directories] << entry.merge(output: relative)
+      relative
+    rescue IOError, SystemCallError => e
+      warning("DIRECTORY_WRITE_ERROR", "#{path}: #{e.message}")
+      @manifest.data[:directories] << entry.merge(status: "write_error", output: nil)
+      nil
+    end
+
+    def warning(code, detail)
+      @log.warn("#{code}: #{detail}")
+      @manifest.warning(code, detail)
+    end
+
+    def finish
+      @directory_times.reverse_each do |path, time|
+        raise SafetyError, "Output became a symlink: #{path}" if File.symlink?(path)
+
+        File.utime(time, time, path)
+      rescue SystemCallError => e
+        warning("TIMESTAMP_ERROR", e.message)
+      end
+      result = Manifest.json_safe(@manifest.data)
+      @log.info("Manifest: files=#{result[:files].size}, directories=#{result[:directories].size}, " \
+                "warnings=#{result[:warnings].size}")
+      atomic_write(safe_target("manifest.json")) { |file| file.write("#{JSON.pretty_generate(result)}\n") }
+      atomic_write(safe_target("sandcrawler.log")) { |file| file.write("#{@log.lines.join("\n")}\n") }
+      result
+    end
+
+    private
+
+    def validate_category(category)
+      raise UsageError, "Unknown output category: #{category}" unless CATEGORIES.include?(category)
+    end
+
+    def output_path(path, category, status)
+      suffix = %w[truncated chain_error partial read_error transfer_error].include?(status) ? ".partial" : ""
+      @paths.path("#{path}#{suffix}", namespace: category)
+    end
+
+    def restore_time(target, time)
+      File.utime(time, time, target)
+    rescue SystemCallError => e
+      warning("TIMESTAMP_ERROR", e.message)
+    end
+
+    def safe_target(relative)
+      raise SafetyError, "Output became a symlink: #{@out}" if File.symlink?(@out)
+
+      current = @out
+      components = relative.split("/")
+      components.each_with_index do |component, index|
+        current = File.join(current, component)
+        raise SafetyError, "Refusing output symlink: #{current}" if File.symlink?(current)
+        next if index == components.size - 1
+
+        begin
+          Dir.mkdir(current)
+        rescue Errno::EEXIST
+          raise SafetyError, "Refusing output symlink: #{current}" if File.symlink?(current)
+        end
+        raise SafetyError, "Not a directory: #{current}" unless File.directory?(current)
+      end
+      current
+    end
+
+    def atomic_write(target)
+      Tempfile.create([".sandcrawler-", ".tmp"], File.dirname(target), binmode: true) do |file|
+        yield file
+        commit_file(file, target)
+      end
+    end
+
+    def commit_file(file, target)
+      file.flush
+      file.close
+      safe_target(target.delete_prefix(@out + File::SEPARATOR))
+      File.rename(file.path, target)
+    end
+  end
+end