ruby_raider 4.0.1 → 4.1.0

data/lib/utilities/flows/os/systemd.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+require_relative 'command_runner'
+require_relative '../schedule'
+
+module RubyRaider
+  module Flows
+    module Os
+      # Linux: a oneshot service and a persistent timer per schedule in the user's systemd folder, enabled
+      # with systemctl --user. Words in ExecStart= and Environment= are double-quoted with C escapes; every
+      # value has % doubled (specifiers) and ExecStart= also has $ doubled (variable expansion).
+      # :reek:TooManyConstants { max_constants: 6 } -- the tool, NOFOLLOW, the escapes, the calendar days, the os_id and path rules
+      class Systemd
+        SYSTEMCTL = 'systemctl'
+        NOFOLLOW = defined?(File::NOFOLLOW) ? File::NOFOLLOW : 0
+        QUOTED = { '\\' => '\\\\', '"' => '\\"', '%' => '%%' }.freeze
+        CALENDAR = { 'hour' => '', 'day' => '', 'weekday' => 'Mon..Fri ' }.freeze
+        OS_ID = /\A#{Regexp.escape(Schedule::OS_ID_PREFIX)}\.[0-9a-f]{10}\.([a-z0-9_]{1,60})\z/
+        # The unit parser strips whitespace at the ends of a value and reads a trailing backslash as "continued"
+        UNSAFE_PATH = /\s\z|\\\z/
+
+        def initialize(runner: CommandRunner.new, home: Dir.home, config_home: ENV.fetch('XDG_CONFIG_HOME', nil))
+          @runner = runner
+          @home = home
+          @config_home = config_home
+        end
+
+        def label = 'systemd'
+
+        def missed_runs_note = nil
+
+        def service(schedule)
+          env = schedule.env.map { |key, value| "Environment=#{quote("#{key}=#{value}")}" }
+          exec = schedule.argv.map { |arg| quote(arg.gsub('$', '$$')) }.join(' ')
+          log = specifiers(schedule.log_path)
+          <<~UNIT
+            [Unit]
+            Description=raider flow #{schedule.name}
+
+            [Service]
+            Type=oneshot
+            WorkingDirectory=#{specifiers(schedule.working_directory)}
+            #{env.join("\n")}
+            ExecStart=#{exec}
+            StandardOutput=append:#{log}
+            StandardError=append:#{log}
+          UNIT
+        end
+
+        # Local time; Persistent= runs a missed time once the user manager is back
+        def timer(schedule)
+          every = schedule.every
+          day = CALENDAR.fetch(every) { "#{schedule.on.to_s.capitalize} " }
+          hour = every == 'hour' ? '*' : format('%02d', schedule.hour)
+          <<~UNIT
+            [Unit]
+            Description=raider flow #{schedule.name} schedule
+
+            [Timer]
+            OnCalendar=#{day}*-*-* #{hour}:#{format('%02d', schedule.minute)}:00
+            Persistent=true
+
+            [Install]
+            WantedBy=timers.target
+          UNIT
+        end
+
+        def unit_path(os_id, kind) = File.join(units_dir, "#{checked_os_id(os_id)}.#{kind}")
+
+        # Writes both units (temp files renamed into place), reloads and enables the timer; a failure leaves no unit behind
+        def install(schedule)
+          os_id = schedule.os_id
+          [schedule.working_directory, schedule.log_path].each { |path| checked_path(path) }
+          write({ unit_path(os_id, 'service') => service(schedule), unit_path(os_id, 'timer') => timer(schedule) })
+          failure = [systemctl('daemon-reload'), systemctl('enable', '--now', "#{os_id}.timer")].find { |result| !result.success? }
+          return true unless failure
+
+          message = "systemd could not enable #{os_id}: #{Flows.printable(failure.stderr.strip)}"
+          raise Error, "#{message}#{discard(os_id)}"
+        end
+
+        # True when a unit file was removed, false when it was already gone
+        def remove(os_id)
+          paths = %w[service timer].map { |kind| unit_path(os_id, kind) }
+          systemctl('disable', '--now', "#{os_id}.timer")
+          removed = paths.map { |path| unlink(path) }.any?
+          reload = systemctl('daemon-reload')
+          raise Error, "systemd could not reload after removing #{os_id}: #{Flows.printable(reload.stderr.strip)}" unless reload.success?
+
+          removed
+        end
+
+        def present?(os_id) = systemctl('is-enabled', "#{checked_os_id(os_id)}.timer").success?
+
+        # True when a unit file for the schedule is on disk (no user manager needed)
+        def unit_files?(os_id) = %w[service timer].any? { |kind| File.exist?(unit_path(os_id, kind)) }
+
+        # True when the user's systemd manager answers
+        def usable? = systemctl('show-environment').success?
+
+        private
+
+        def systemctl(*args) = @runner.call(SYSTEMCTL, '--user', *args)
+
+        def units_dir
+          config = @config_home
+          base = config.is_a?(String) && File.absolute_path?(config) ? config : File.join(@home, '.config')
+          File.join(base, 'systemd', 'user')
+        end
+
+        def checked_os_id(os_id)
+          return os_id if os_id.is_a?(String) && (match = OS_ID.match(os_id)) && Flows.valid_name?(match[1])
+
+          raise Error, "Invalid os_id #{Flows.printable(os_id.inspect)}: not a flow schedule"
+        end
+
+        def checked_path(path)
+          raise Error, "systemd can not use the path #{Flows.printable(path.inspect)}: it ends in whitespace or a backslash" if UNSAFE_PATH.match?(path)
+        end
+
+        # A word systemd gives back exactly: double quotes, \\ and \" escapes, %% for %
+        def quote(text) = %("#{text.gsub(/[\\"%]/, QUOTED)}")
+
+        # A raw path value: only specifiers apply
+        def specifiers(text) = text.gsub('%', '%%')
+
+        # True when the file was there; a unit that stays behind is an error, not "already gone"
+        def unlink(path)
+          File.unlink(path)
+          true
+        rescue Errno::ENOENT
+          false
+        rescue SystemCallError => e
+          raise Error, "Could not remove #{path}: #{e.message}"
+        end
+
+        # Disables the timer, removes both units and reloads; returns what to add to the error when that fails too
+        def discard(os_id)
+          systemctl('disable', "#{os_id}.timer")
+          %w[service timer].each { |kind| unlink(unit_path(os_id, kind)) }
+          reload = systemctl('daemon-reload')
+          reload.success? ? '' : "; also: reload failed: #{Flows.printable(reload.stderr.strip)}"
+        rescue Error => e
+          "; also: #{e.message}"
+        end
+
+        # Every temp file is written before any unit is replaced, so a failed write changes nothing
+        def write(texts)
+          temps = {}
+          texts.each { |path, text| temps[path] = temp_file(path, text) }
+          temps.each { |path, temp| File.rename(temp, path) }
+        rescue SystemCallError => e
+          raise Error, "Could not write the systemd units in #{units_dir}: #{e.message}"
+        ensure
+          temps&.each_value { |temp| FileUtils.rm_f(temp) if File.exist?(temp) }
+        end
+
+        def temp_file(path, text)
+          dir = File.dirname(path)
+          FileUtils.mkdir_p(dir)
+          temp = File.join(dir, ".#{File.basename(path)}.#{SecureRandom.hex(6)}.tmp")
+          File.open(temp, File::WRONLY | File::CREAT | File::EXCL | NOFOLLOW, 0o644) do |file|
+            file.write(text)
+            file.flush
+            file.fsync
+            file.chmod(0o644)
+          end
+          temp
+        rescue SystemCallError
+          FileUtils.rm_f(temp) if temp && File.file?(temp)
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/utilities/flows/os/task_scheduler.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require_relative 'command_runner'
+require_relative '../schedule'
+require_relative '../next_run'
+
+module RubyRaider
+  module Flows
+    module Os
+      # Windows: one task per schedule in the \RubyRaider\ folder, registered from task XML with schtasks.
+      # The task runs ruby.exe directly (never cmd.exe or powershell), with the user's own environment and
+      # no log file: the outcome lives in runs.jsonl like any flow run. Argument values get Windows CRT
+      # quoting, then every value in the XML goes through one XML escaper.
+      # Task Scheduler expands %NAME% in Command, Arguments and WorkingDirectory with no escape, so a value
+      # holding one is refused before schtasks runs.
+      # :reek:TooManyConstants { max_constants: 8 } -- the folder, the XML escapes and namespace, the os_id rule, quoting, globs, %NAME%, day names
+      class TaskScheduler
+        FOLDER = '\\RubyRaider\\'
+        ESCAPES = { '&' => '&amp;', '<' => '&lt;', '>' => '&gt;', '"' => '&quot;', "'" => '&apos;' }.freeze
+        NAMESPACE = 'http://schemas.microsoft.com/windows/2004/02/mit/task'
+        OS_ID = /\A#{Regexp.escape(Schedule::OS_ID_PREFIX)}\.[0-9a-f]{10}\.([a-z0-9_]{1,60})\z/
+        # ruby.exe reads its own command line (w32_cmdvector in win32.c): ' quotes too, and a * ? [ { outside
+        # '...' (even inside "...") makes it glob the argument
+        NEEDS_QUOTES = /[ \t\n\v"']/
+        GLOB = /[*?\[{]/
+        EXPANDS = /%[^%]+%/
+        DAY_NAMES = %w[Monday Tuesday Wednesday Thursday Friday Saturday Sunday].freeze
+
+        # One argument as ruby.exe reads it back (w32_cmdvector). With a glob character: '...', where nothing
+        # is special and nothing globs (and with a ' too: refused). Otherwise "..." when empty or holding
+        # whitespace or a quote: backslashes before " (or the closing ") are doubled plus one escapes the ",
+        # and an odd run before ' becomes 2n+1 (ruby.exe eats (n+1)/2 of them; an even run is kept as is).
+        def self.quote(arg)
+          return glob_quote(arg) if arg.match?(GLOB)
+          return arg if !arg.empty? && !arg.match?(NEEDS_QUOTES)
+
+          body = arg.gsub(/(\\*)"/) { "#{Regexp.last_match(1).to_s * 2}\\\"" }
+                    .gsub(/(\\+)'/) { "#{odd_doubled(Regexp.last_match(1).to_s)}'" }
+                    .sub(/(\\+)\z/) { Regexp.last_match(1).to_s * 2 }
+          "\"#{body}\""
+        end
+
+        def self.glob_quote(arg)
+          return "'#{arg}'" unless arg.include?("'")
+
+          raise Error, "Task Scheduler can not pass #{Flows.printable(arg.inspect)} to ruby.exe: an argument with both ' and * ? [ or { would be globbed"
+        end
+
+        def self.odd_doubled(slashes) = slashes.length.odd? ? "#{slashes * 2}\\" : slashes
+
+        def self.join(args) = args.map { |arg| quote(arg) }.join(' ')
+
+        def initialize(runner: CommandRunner.new, clock: Time, schtasks: File.join(ENV.fetch('SystemRoot', 'C:\\Windows'), 'System32', 'schtasks.exe'))
+          @runner = runner
+          @clock = clock
+          @schtasks = schtasks
+        end
+
+        def label = 'Task Scheduler'
+
+        def task_name(os_id) = "#{FOLDER}#{checked_os_id(os_id)}"
+
+        # The task XML (a UTF-8 String; install writes it as UTF-16LE with a BOM)
+        def task_xml(schedule)
+          refuse_expansion(schedule)
+          body = [
+            element('RegistrationInfo', [text('Description', "Ruby Raider flow #{schedule.name} (#{schedule.rule_text})"),
+                                         text('URI', task_name(schedule.os_id))]),
+            element('Triggers', element('CalendarTrigger', trigger(schedule))),
+            element('Principals', element('Principal id="Author"', [text('LogonType', 'InteractiveToken'), text('RunLevel', 'LeastPrivilege')])),
+            element('Settings', settings),
+            element('Actions Context="Author"', element('Exec', action(schedule)))
+          ]
+          lines = ['<?xml version="1.0" encoding="UTF-16"?>', %(<Task version="1.2" xmlns="#{NAMESPACE}">), *indent(body.flatten), '</Task>']
+          "#{lines.join("\n")}\n"
+        end
+
+        # Registers (or replaces) the task from a UTF-16LE temp file, deleted whatever happens
+        def install(schedule)
+          os_id = schedule.os_id
+          file = Tempfile.new(['raider-flow-task', '.xml'], binmode: true)
+          file.write("\uFEFF#{task_xml(schedule)}".encode(Encoding::UTF_16LE))
+          file.close
+          result = schtasks('/Create', '/TN', task_name(os_id), '/XML', file.path.to_s, '/F')
+          return true if result.success?
+
+          raise Error, "Task Scheduler could not create #{os_id}: #{Flows.printable(result.stderr.strip)}"
+        ensure
+          file&.close!
+        end
+
+        # True when the task was deleted, false when it was already gone. schtasks words "not found" in
+        # the system language, so a failed delete is checked against the task list; a list that can not
+        # be read, or still shows the task, is an error.
+        def remove(os_id)
+          name = task_name(os_id)
+          result = schtasks('/Delete', '/TN', name, '/F')
+          return true if result.success?
+
+          listing = list
+          return false if listing.success? && !listed?(listing, name)
+
+          raise Error, "Task Scheduler could not delete #{os_id}: #{Flows.printable(result.stderr.strip)}"
+        end
+
+        def present?(os_id)
+          name = task_name(os_id)
+          listing = list
+          return listed?(listing, name) if listing.success?
+
+          raise Error, "Task Scheduler could not list tasks: #{Flows.printable(listing.stderr.strip)}"
+        end
+
+        private
+
+        def schtasks(*args) = @runner.call(@schtasks, *args)
+
+        # Every task, one CSV row each, the full task name in the first field
+        def list = schtasks('/Query', '/FO', 'CSV', '/NH')
+
+        def listed?(listing, name) = listing.stdout.each_line.any? { |line| line.start_with?(%("#{name}",)) }
+
+        def refuse_expansion(schedule)
+          # The joined Arguments, as Task Scheduler expands them: a %...% can span two arguments
+          value = [schedule.ruby, self.class.join(schedule.argv.drop(1)), schedule.working_directory].find { |item| item.match?(EXPANDS) }
+          return unless value
+
+          raise Error, "Task Scheduler would expand #{Flows.printable(value[EXPANDS])} as an environment variable in #{Flows.printable(value.inspect)}: " \
+                       'remove the %...% from it'
+        end
+
+        def checked_os_id(os_id)
+          return os_id if os_id.is_a?(String) && (match = OS_ID.match(os_id)) && Flows.valid_name?(match[1])
+
+          raise Error, "Invalid os_id #{Flows.printable(os_id.inspect)}: not a flow schedule"
+        end
+
+        def escape(value) = value.to_s.gsub(/[&<>"']/, ESCAPES)
+
+        def text(name, value) = ["<#{name}>#{escape(value)}</#{name}>"]
+
+        # tag may carry fixed attributes ('Principal id="Author"'); the closing tag is its first word
+        def element(tag, children) = ["<#{tag}>", *indent(children.flatten), "</#{tag.split.first}>"]
+
+        def indent(lines) = lines.map { |line| "  #{line}" }
+
+        # Local time without an offset, never in the past (StartWhenAvailable would run a missed start at
+        # once): the next run's date, at the rule's own HH:MM so a DST-shifted next run does not move the
+        # daily time; an hour rule starts at its next run.
+        def trigger(schedule)
+          every = schedule.every
+          next_run = NextRun.after(schedule, @clock.now)
+          hour = every == 'hour' ? next_run.hour : schedule.hour
+          start = format('%<date>sT%<hour>02d:%<minute>02d:00', date: next_run.strftime('%Y-%m-%d'), hour: hour, minute: schedule.minute)
+          repeat = every == 'hour' ? [element('Repetition', [text('Interval', 'PT1H'), text('Duration', 'P1D')])] : []
+          [*repeat, text('StartBoundary', start), text('Enabled', 'true'), *calendar(schedule, every)]
+        end
+
+        def calendar(schedule, every)
+          return element('ScheduleByDay', text('DaysInterval', '1')) if %w[hour day].include?(every)
+
+          days = schedule.days.map { |day| ["<#{DAY_NAMES.fetch(Schedule::DAYS.index(day).to_i)} />"] }
+          element('ScheduleByWeek', [element('DaysOfWeek', days), text('WeeksInterval', '1')])
+        end
+
+        def settings
+          [text('MultipleInstancesPolicy', 'IgnoreNew'), text('DisallowStartIfOnBatteries', 'false'),
+           text('StopIfGoingOnBatteries', 'false'), text('StartWhenAvailable', 'true'), text('Enabled', 'true')]
+        end
+
+        def action(schedule)
+          ruby, *args = schedule.argv
+          [text('Command', ruby), text('Arguments', self.class.join(args)), text('WorkingDirectory', schedule.working_directory)]
+        end
+      end
+    end
+  end
+end

data/lib/utilities/flows/project.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+
+module RubyRaider
+  module Flows
+    NAME = /\A[a-z0-9_]{1,60}\z/
+    # .raider/flows/env is the secrets file, so no flow may log to .raider/flows/env/
+    RESERVED = %w[env].freeze
+
+    def self.valid_name?(name) = NAME.match?(name.to_s) && !RESERVED.include?(name.to_s)
+
+    # Text from a run log, safe to print: page text in a step title can't move the cursor or forge lines
+    def self.printable(text) = text.to_s.gsub(/[[:cntrl:]]/, '?')
+
+    # A problem that stops a flow command; exit_code follows `raider flow run` (2 = setup failed).
+    class Error < StandardError
+      attr_reader :exit_code
+
+      def initialize(message, exit_code: 2)
+        super(message)
+        @exit_code = exit_code
+      end
+    end
+
+    # A Ruby Raider project that holds flows in flows/<name>_flow.rb.
+    class Project
+      UNSUPPORTED = 'Flows need a Selenium web project made with Ruby Raider 4.0 or later'
+      GITIGNORE_LINES = %w[flow-results/ .raider/flows/].freeze
+      TEMPLATES = {
+        'flows/flow_helper.rb' => 'flow_helper.tt',
+        'flows/support/run.rb' => 'run.tt'
+      }.freeze
+      # gem 'ruby_raider', '~> 4.0' (any quotes); captures the major and minor
+      PIN = /^(\s*gem\s+(["'])ruby_raider\2\s*,\s*(["']))~>\s*(\d+)\.(\d+)(?:\.\d+)?(\3)/
+      FLOWS_PIN = [4, 1].freeze
+
+      attr_reader :root
+
+      def initialize(path)
+        @root = File.realpath(path)
+      rescue SystemCallError
+        raise Error, "Project folder not found: #{path}"
+      end
+
+      def path(relative) = File.join(root, relative)
+
+      # The flow file for a name, realpath-checked inside the project.
+      def flow_file(name)
+        raise Error, "Invalid flow name #{name.inspect}: use 1 to 60 of a-z, 0-9 and _ (not env)" unless Flows.valid_name?(name)
+
+        file = path("flows/#{name}_flow.rb")
+        raise Error, "No flow #{name}: flows/#{name}_flow.rb not found" unless File.file?(file)
+
+        real = File.realpath(file)
+        raise Error, "flows/#{name}_flow.rb points outside the project" unless real.start_with?("#{root}#{File::SEPARATOR}")
+
+        real
+      end
+
+      def flow_names
+        Dir.glob(path('flows/*_flow.rb')).map { |file| File.basename(file, '_flow.rb') }.select { |name| Flows.valid_name?(name) }.sort
+      end
+
+      def set_up? = TEMPLATES.keys.all? { |file| File.file?(path(file)) }
+
+      # nil when flows can be added, otherwise why not
+      def unsupported_reason
+        gemfile = read('Gemfile')
+        return UNSUPPORTED unless gemfile && selenium?(gemfile) && runtime?
+        return UNSUPPORTED if old_pin?(gemfile)
+
+        nil
+      end
+
+      # Returns the exit code: 0 done (or already done), 2 refused.
+      def init(out: $stdout, err: $stderr)
+        reason = unsupported_reason
+        if reason
+          err.puts(reason)
+          return 2
+        end
+
+        created = write_templates
+        updated = add_gitignore_lines
+        pinned = pin_gem
+        updated << 'Gemfile' if pinned
+        report(out, created, updated, pinned)
+        warn_unknown_pin(err)
+        0
+      end
+
+      private
+
+      def template_dir = File.expand_path('../../generators/templates/flows', __dir__)
+
+      def read(relative)
+        file = path(relative)
+        File.file?(file) ? File.read(file) : nil
+      end
+
+      def selenium?(gemfile)
+        gemfile.match?(/["']selenium-webdriver["']/) && !gemfile.match?(/["']appium_lib["']/)
+      end
+
+      # 4.0 projects load the runtime from the driver helper; 3.x ones used WaitHelper
+      def runtime?
+        read('helpers/driver_helper.rb').to_s.include?("require 'ruby_raider/runtime'")
+      end
+
+      def old_pin?(gemfile)
+        match = gemfile.match(PIN)
+        match ? match[4].to_i < FLOWS_PIN.first : false
+      end
+
+      def write_templates
+        TEMPLATES.filter_map do |relative, template|
+          file = path(relative)
+          next if File.exist?(file)
+
+          FileUtils.mkdir_p(File.dirname(file))
+          File.write(file, ERB.new(File.read(File.join(template_dir, template)), trim_mode: '-').result)
+          relative
+        end
+      end
+
+      def add_gitignore_lines
+        file = path('.gitignore')
+        content = File.file?(file) ? File.read(file) : ''
+        missing = GITIGNORE_LINES - content.lines.map(&:strip)
+        return [] if missing.empty?
+
+        prefix = content.empty? || content.end_with?("\n") ? '' : "\n"
+        File.write(file, "#{content}#{prefix}#{missing.join("\n")}\n")
+        ['.gitignore']
+      end
+
+      # Raises a ~> 4.0 pin to ~> 4.1 so `bundle exec raider flow` runs a gem that has flows.
+      def pin_gem
+        gemfile = read('Gemfile').to_s
+        match = gemfile.match(PIN)
+        return false unless match && ([match[4].to_i, match[5].to_i] <=> FLOWS_PIN).negative?
+
+        File.write(path('Gemfile'), gemfile.sub(PIN) { "#{match[1]}~> #{FLOWS_PIN.join('.')}#{match[6]}" })
+        true
+      end
+
+      # gem 'ruby_raider', '4.0.1' or path: ... isn't raised here, and an old gem has no `raider flow`
+      def warn_unknown_pin(err)
+        gemfile = read('Gemfile').to_s
+        return if gemfile.match?(PIN) || !gemfile.match?(/^\s*gem\s+["']ruby_raider["']/)
+
+        err.puts("Check that the ruby_raider line in your Gemfile allows #{FLOWS_PIN.join('.')} or later, then run bundle install")
+      end
+
+      def report(out, created, updated, pinned)
+        if created.empty? && updated.empty?
+          out.puts('Flows already set up')
+          return
+        end
+
+        created.each { |file| out.puts("Created #{file}") }
+        updated.each { |file| out.puts("Updated #{file}") }
+        out.puts('Run bundle install') if pinned
+        out.puts('Write a flow in flows/<name>_flow.rb, then run it with: raider flow run <name>')
+      end
+    end
+  end
+end

data/lib/utilities/flows/run_log.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyRaider
+  module Flows
+    # Reads .raider/flows/<name>/runs.jsonl, which the project's flows/support/run.rb appends to.
+    class RunLog
+      MAX_BYTES = 1024 * 1024
+      NOFOLLOW = defined?(File::NOFOLLOW) ? File::NOFOLLOW : 0
+      NONBLOCK = defined?(File::NONBLOCK) ? File::NONBLOCK : 0
+      SUMMARY = %w[status finished_at failed_step results_dir].freeze
+
+      # [{name, file, last: {status, finished_at, failed_step, results_dir} | nil}], the shape `raider flow list --json` prints
+      def self.summaries(project)
+        project.flow_names.map do |name|
+          last = new(project, name).last_result
+          { 'name' => name, 'file' => "flows/#{name}_flow.rb", 'last' => last && SUMMARY.to_h { |key| [key, last[key]] } }
+        end
+      end
+
+      def initialize(project, name)
+        @file = project.path(".raider/flows/#{name}/runs.jsonl")
+      end
+
+      # Every readable line in the last MAX_BYTES, oldest first; a broken line is skipped
+      def lines
+        tail.lines.filter_map do |line|
+          parsed = JSON.parse(line)
+          parsed if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      def last = lines.last
+
+      # The last run that ran: a busy line only says another run held the lock
+      def last_result = lines.reverse.find { |line| line['status'] != 'busy' }
+
+      def find(run_id) = lines.reverse.find { |line| line['run_id'] == run_id }
+
+      private
+
+      # Read through one handle that is not a link, so the checks and the read see the same file
+      def tail
+        File.open(@file, File::RDONLY | NONBLOCK | NOFOLLOW) do |file|
+          stat = file.stat
+          return '' unless stat.file?
+
+          skip = [stat.size - MAX_BYTES, 0].max
+          file.seek(skip)
+          text = file.read.to_s.force_encoding(Encoding::UTF_8)
+          skip.positive? ? text.partition("\n").last : text
+        end
+      rescue SystemCallError
+        ''
+      end
+    end
+  end
+end