ruby_raider 4.1.0 → 4.2.0

data/lib/utilities/{flows → schedules}/os/systemd.rb

@@ -3,25 +3,26 @@
 require 'fileutils'
 require 'securerandom'
 require_relative 'command_runner'
-require_relative '../schedule'
+require_relative '../base'
 
 module RubyRaider
-  module Flows
+  module Schedules
     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
+      # :reek:TooManyConstants { max_constants: 5 } -- the tool, NOFOLLOW, the escapes, the calendar days, the path rule
       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))
+        # kind: the Kind whose units this adapter writes and removes
+        def initialize(kind:, runner: CommandRunner.new, home: Dir.home, config_home: ENV.fetch('XDG_CONFIG_HOME', nil))
+          @kind = kind
           @runner = runner
           @home = home
           @config_home = config_home
@@ -37,7 +38,7 @@ module RubyRaider
           log = specifiers(schedule.log_path)
           <<~UNIT
             [Unit]
-            Description=raider flow #{schedule.name}
+            Description=#{@kind.service_description(schedule.name)}
 
             [Service]
             Type=oneshot
@@ -56,7 +57,7 @@ module RubyRaider
           hour = every == 'hour' ? '*' : format('%02d', schedule.hour)
           <<~UNIT
             [Unit]
-            Description=raider flow #{schedule.name} schedule
+            Description=#{@kind.timer_description(schedule.name)}
 
             [Timer]
             OnCalendar=#{day}*-*-* #{hour}:#{format('%02d', schedule.minute)}:00
@@ -67,7 +68,7 @@ module RubyRaider
           UNIT
         end
 
-        def unit_path(os_id, kind) = File.join(units_dir, "#{checked_os_id(os_id)}.#{kind}")
+        def unit_path(os_id, unit) = File.join(units_dir, "#{checked_os_id(os_id)}.#{unit}")
 
         # Writes both units (temp files renamed into place), reloads and enables the timer; a failure leaves no unit behind
         def install(schedule)
@@ -77,25 +78,40 @@ module RubyRaider
           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)}"
+          message = "systemd could not enable #{os_id}: #{Schedules.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) }
+          paths = %w[service timer].map { |unit| unit_path(os_id, unit) }
           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?
+          raise Error, "systemd could not reload after removing #{os_id}: #{Schedules.printable(reload.stderr.strip)}" unless reload.success?
 
           removed
         end
 
         def present?(os_id) = systemctl('is-enabled', "#{checked_os_id(os_id)}.timer").success?
 
+        # The os_ids of this kind starting with prefix that have a unit file, sorted (no user manager needed)
+        def list_ids(prefix)
+          dir = units_dir
+          Dir.children(dir).filter_map do |file|
+            next unless file.valid_encoding?
+
+            id = file.sub(/\.(?:service|timer)\z/, '')
+            id if id != file && @kind.listed?(id, prefix)
+          end.uniq.sort
+        rescue Errno::ENOENT
+          []
+        rescue SystemCallError => e
+          raise Error, "Could not read #{dir}: #{e.message}"
+        end
+
         # 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)) }
+        def unit_files?(os_id) = %w[service timer].any? { |unit| File.exist?(unit_path(os_id, unit)) }
 
         # True when the user's systemd manager answers
         def usable? = systemctl('show-environment').success?
@@ -111,13 +127,13 @@ module RubyRaider
         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])
+          return os_id if @kind.name_in(os_id)
 
-          raise Error, "Invalid os_id #{Flows.printable(os_id.inspect)}: not a flow schedule"
+          raise Error, "Invalid os_id #{Schedules.printable(os_id.inspect)}: #{@kind.not_ours}"
         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)
+          raise Error, "systemd can not use the path #{Schedules.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 %
@@ -139,9 +155,9 @@ module RubyRaider
         # 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)) }
+          %w[service timer].each { |unit| unlink(unit_path(os_id, unit)) }
           reload = systemctl('daemon-reload')
-          reload.success? ? '' : "; also: reload failed: #{Flows.printable(reload.stderr.strip)}"
+          reload.success? ? '' : "; also: reload failed: #{Schedules.printable(reload.stderr.strip)}"
         rescue Error => e
           "; also: #{e.message}"
         end

data/lib/utilities/{flows → schedules}/os/task_scheduler.rb

@@ -2,30 +2,31 @@
 
 require 'tempfile'
 require_relative 'command_runner'
-require_relative '../schedule'
+require_relative '../base'
 require_relative '../next_run'
 
 module RubyRaider
-  module Flows
+  module Schedules
     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
+      # no log file: the outcome lives in runs.jsonl like any scheduled 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
+      # :reek:TooManyConstants { max_constants: 8 } -- the folder, the XML escapes and namespace, quoting, globs, %NAME%, day names, list rows
       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
+        # A /Query /FO CSV row of a task right in our folder: its name, which our ids never quote or escape
+        ROW = /\A"#{Regexp.escape(FOLDER)}([^"\\]*)",/
 
         # 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
@@ -44,14 +45,16 @@ module RubyRaider
         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"
+          raise Error, "Task Scheduler can not pass #{Schedules.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'))
+        # kind: the Kind whose tasks this adapter registers and deletes
+        def initialize(kind:, runner: CommandRunner.new, clock: Time, schtasks: File.join(ENV.fetch('SystemRoot', 'C:\\Windows'), 'System32', 'schtasks.exe'))
+          @kind = kind
           @runner = runner
           @clock = clock
           @schtasks = schtasks
@@ -65,7 +68,7 @@ module RubyRaider
         def task_xml(schedule)
           refuse_expansion(schedule)
           body = [
-            element('RegistrationInfo', [text('Description', "Ruby Raider flow #{schedule.name} (#{schedule.rule_text})"),
+            element('RegistrationInfo', [text('Description', @kind.task_description(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')])),
@@ -79,13 +82,13 @@ module RubyRaider
         # 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 = Tempfile.new([@kind.task_file_prefix, '.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)}"
+          raise Error, "Task Scheduler could not create #{os_id}: #{Schedules.printable(result.stderr.strip)}"
         ensure
           file&.close!
         end
@@ -99,17 +102,22 @@ module RubyRaider
           return true if result.success?
 
           listing = list
-          return false if listing.success? && !listed?(listing, name)
+          return false if listing.success? && !listed?(listing.stdout, name)
 
-          raise Error, "Task Scheduler could not delete #{os_id}: #{Flows.printable(result.stderr.strip)}"
+          raise Error, "Task Scheduler could not delete #{os_id}: #{Schedules.printable(result.stderr.strip)}"
         end
 
         def present?(os_id)
           name = task_name(os_id)
-          listing = list
-          return listed?(listing, name) if listing.success?
+          listed?(tasks, name)
+        end
 
-          raise Error, "Task Scheduler could not list tasks: #{Flows.printable(listing.stderr.strip)}"
+        # The os_ids of this kind starting with prefix that are tasks in \\RubyRaider\\, sorted (one query)
+        def list_ids(prefix)
+          tasks.dup.force_encoding(Encoding::UTF_8).scrub.each_line.filter_map do |row|
+            id = row[ROW, 1]
+            id if @kind.listed?(id, prefix)
+          end.uniq.sort
         end
 
         private
@@ -119,21 +127,29 @@ module RubyRaider
         # 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}",)) }
+        # The task list's text; an Error when it can't be read
+        def tasks
+          listing = list
+          return listing.stdout if listing.success?
+
+          raise Error, "Task Scheduler could not list tasks: #{Schedules.printable(listing.stderr.strip)}"
+        end
+
+        def listed?(text, name) = text.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)}: " \
+          raise Error, "Task Scheduler would expand #{Schedules.printable(value[EXPANDS])} as an environment variable in #{Schedules.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])
+          return os_id if @kind.name_in(os_id)
 
-          raise Error, "Invalid os_id #{Flows.printable(os_id.inspect)}: not a flow schedule"
+          raise Error, "Invalid os_id #{Schedules.printable(os_id.inspect)}: #{@kind.not_ours}"
         end
 
         def escape(value) = value.to_s.gsub(/[&<>"']/, ESCAPES)
@@ -160,7 +176,7 @@ module RubyRaider
         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)} />"] }
+          days = schedule.days.map { |day| ["<#{DAY_NAMES.fetch(DAYS.index(day).to_i)} />"] }
           element('ScheduleByWeek', [element('DaysOfWeek', days), text('WeeksInterval', '1')])
         end
 

data/lib/utilities/schedules/os_enumerator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RubyRaider
+  module Schedules
+    # The schedules of one project and kind that the OS scheduler has, by enumerating it for the project's
+    # os_id prefix ("<kind prefix>.<hash10>."). Every id is checked again here, so another project's, another
+    # kind's or a malformed id never becomes a name. An OS scheduler that can't be read gives none.
+    class OsEnumerator
+      # schedule_class: a Rule subclass (its Kind and os_id_prefix_for); root: the project's real path
+      def initialize(adapter, schedule_class:, root:)
+        @adapter = adapter
+        @kind = schedule_class.kind
+        @prefix = schedule_class.os_id_prefix_for(root)
+      end
+
+      # The names, sorted and once each
+      def names
+        adapter = @adapter
+        return [] unless adapter.respond_to?(:list_ids)
+
+        prefix = @prefix
+        Array(adapter.list_ids(prefix)).filter_map { |os_id| @kind.name_in(os_id) if @kind.listed?(os_id, prefix) }.uniq.sort
+      rescue Error
+        []
+      end
+    end
+  end
+end

data/lib/utilities/schedules/project.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RubyRaider
+  module Schedules
+    # A project folder, by its real path: where its schedules and their files live
+    # :reek:MissingSafeMethod { exclude: [ check_show_browser!, check_raider_version! ] } -- checks that raise; runtime_driver? and locked_raider_version are their safe twins
+    # :reek:TooManyConstants { max_constants: 8 } -- the driver helper and Gemfile.lock checks
+    class Project
+      DRIVER_HELPER = 'helpers/driver_helper.rb'
+      # This gem's version, read as Raider#current_version reads it
+      OWN_VERSION = File.read(File.expand_path('../../version', __dir__)).strip.freeze
+      # The ruby_raider spec line of a GEM, PATH or GIT section (LF or CRLF); never evaluated
+      LOCKED_RAIDER = /^ {4}ruby_raider \(([0-9]+(?:\.[0-9A-Za-z]+)*)\)\r?$/
+      MAX_LOCK_BYTES = 5_000_000
+      # Every 4.x Selenium driver_helper loads the runtime, which honours RAIDER_SHOW_BROWSER
+      REQUIRES_RUNTIME = %r{^[ \t]*require[ \t]+(['"])ruby_raider/runtime\1}n
+      MAX_HELPER_BYTES = 1_000_000
+      NO_RUNTIME = 'Show the browser needs a project made with Ruby Raider 4.0 or later'
+
+      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)
+
+      # `add --show-browser` refuses a project whose driver_helper can't drop --headless
+      def check_show_browser!
+        raise Error, NO_RUNTIME unless runtime_driver?
+      end
+
+      # The OS entry runs `bundle exec raider schedule run`, so the project's own bundle must have this command
+      def check_raider_version!(own = OWN_VERSION)
+        needs = "Scheduling needs ruby_raider #{own} or later in this project"
+        raise Error, "#{needs}: no Gemfile found" unless File.file?(path('Gemfile'))
+
+        locked = locked_raider_version
+        raise Error, "#{needs}: run bundle install first" if locked == :no_lock
+        return if locked && Gem::Version.new(locked) >= Gem::Version.new(own)
+
+        raise Error, "#{needs}: bundle update ruby_raider"
+      end
+
+      # The ruby_raider version Gemfile.lock resolves (any source), nil when it lists none, :no_lock without a lock
+      def locked_raider_version
+        lock = path('Gemfile.lock')
+        return :no_lock unless File.file?(lock)
+
+        File.binread(lock, MAX_LOCK_BYTES).to_s[LOCKED_RAIDER, 1]
+      rescue SystemCallError
+        :no_lock
+      end
+
+      # true when helpers/driver_helper.rb is a regular file inside the project that requires the runtime
+      def runtime_driver?
+        real = File.realpath(path(DRIVER_HELPER))
+        return false unless real.start_with?("#{root}#{File::SEPARATOR}") && File.file?(real)
+
+        REQUIRES_RUNTIME.match?(File.binread(real, MAX_HELPER_BYTES).to_s)
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+end

data/lib/utilities/schedules/rule.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'time'
+require_relative 'kind'
+
+module RubyRaider
+  module Schedules
+    # What every schedule shares, tests or 4.1: the rule (every/at/on), retries and notify, and what the OS
+    # entry runs (absolute ruby and bundle, GEM_HOME/GEM_PATH captured when it was scheduled). A subclass
+    # names its Kind (self.kind), checks its own name and fields in its initialize, and freezes.
+    # :reek:TooManyConstants { max_constants: 7 } -- the rule vocabulary and the OS entry parts
+    class Rule
+      EVERY = %w[hour day weekday week].freeze
+      DAYS = Schedules::DAYS
+      DAYS_RULE = 'use mon, tue, wed, thu, fri, sat or sun'
+      CLOCK = /\A([01]\d|2[0-3]):([0-5]\d)\z/
+      MINUTE = /\A(?:[01]\d|2[0-3])?:([0-5]\d)\z/
+      GEM_ENV = %w[GEM_HOME GEM_PATH].freeze
+      SYSTEM_PATH = %w[/usr/bin /bin].freeze
+
+      attr_reader :name, :every, :at, :on, :retries, :notify, :os_id, :ruby, :bundle, :gem_env, :project_root, :created_at
+
+      # The Kind of the subclass's schedules
+      def self.kind = raise(NotImplementedError, "#{self} must name its Kind")
+
+      def self.os_id_for(project_root, name) = "#{os_id_prefix_for(project_root)}#{name}"
+
+      # What every os_id of this kind for the project starts with: "<kind prefix>.<hash10>."
+      def self.os_id_prefix_for(project_root) = "#{kind.os_id_prefix}.#{Digest::SHA256.hexdigest(project_root)[0, 10]}."
+
+      # The absolute bundle of this Ruby. Gem.bin_path can also answer nil (seen on CI with a bare env).
+      def self.bundle_path
+        path = Gem.bin_path('bundler', 'bundle')
+        return path if path.is_a?(String) && File.absolute_path?(path)
+
+        raise Error, "Bundler not found for this Ruby (no bundle executable, got #{path.inspect}): gem install bundler, then try again"
+      rescue Gem::GemNotFoundException, Gem::MissingSpecError => e
+        raise Error, "Bundler not found for this Ruby (#{e.message}): gem install bundler, then try again"
+      end
+
+      # The GEM_HOME and GEM_PATH raider started with (before bundle exec changed them), only when set
+      def self.captured_gem_env
+        env = defined?(Bundler) ? Bundler.original_env : ENV
+        GEM_ENV.each_with_object({}) do |key, captured|
+          value = env[key]
+          captured[key] = value if value.is_a?(String) && !value.empty?
+        end
+      end
+
+      def kind = self.class.kind
+
+      def hour = at[0, 2].to_i
+
+      def minute = at[3, 2].to_i
+
+      def days
+        case every
+        when 'weekday' then DAYS.first(5)
+        when 'week' then [on.to_s]
+        else DAYS
+        end
+      end
+
+      # `raider <command> run NAME`, as the OS entry runs it
+      def argv = [ruby, bundle, 'exec', 'raider', kind.command, 'run', name, '--project', project_root, '--trigger', 'schedule']
+
+      def env
+        path = [File.dirname(ruby), File.dirname(bundle), *SYSTEM_PATH].uniq.join(File::PATH_SEPARATOR)
+        { 'PATH' => path, 'LANG' => 'en_US.UTF-8' }.merge(gem_env)
+      end
+
+      def working_directory = project_root
+
+      def log_path = File.join(project_root, kind.dir, name, 'scheduler.log')
+
+      def rule_text
+        case every
+        when 'hour' then "every hour at #{at[2, 3]}"
+        when 'week' then "every week on #{on} at #{at}"
+        else "every #{every} at #{at}"
+        end
+      end
+
+      private
+
+      def checked_every(every)
+        return every.dup.freeze if EVERY.include?(every)
+
+        raise Error, "Invalid every #{every.inspect}: use hour, day, weekday or week"
+      end
+
+      # HH:MM, or for every hour :MM or HH:MM (the hour ignored, :00 when left out), kept as HH:MM
+      def checked_at(at)
+        return clock(at) unless every == 'hour'
+        return '00:00' if at.nil?
+
+        match = MINUTE.match(at.to_s)
+        raise Error, "Invalid at #{at.inspect}: use :MM or HH:MM for every hour" unless match
+
+        "00:#{match[1]}"
+      end
+
+      def clock(at)
+        raise Error, "Every #{every} needs at: use HH:MM (24h)" if at.nil?
+        return at.dup.freeze if at.is_a?(String) && CLOCK.match?(at)
+
+        raise Error, "Invalid at #{at.inspect}: use HH:MM (24h)"
+      end
+
+      def checked_on(on)
+        unless every == 'week'
+          raise Error, 'on is only for every week' unless on.nil?
+
+          return nil
+        end
+        raise Error, "Every week needs on: #{DAYS_RULE}" if on.nil?
+        return on.dup.freeze if DAYS.include?(on)
+
+        raise Error, "Invalid on #{on.inspect}: #{DAYS_RULE}"
+      end
+
+      def checked_retries(retries)
+        return retries if retries.is_a?(Integer) && retries.between?(0, 3)
+
+        raise Error, "Invalid retries #{retries.inspect}: use 0 to 3"
+      end
+
+      # An entry written before the flag existed has no key: off
+      def checked_flag(label, flag)
+        return flag == true if [true, false, nil].include?(flag)
+
+        raise Error, "Invalid #{label} #{flag.inspect}: use true or false"
+      end
+
+      def checked_os_id(os_id)
+        pattern = /\A#{Regexp.escape(kind.os_id_prefix)}\.[0-9a-f]{10}\.#{Regexp.escape(name)}\z/
+        return os_id.dup.freeze if os_id.is_a?(String) && pattern.match?(os_id)
+
+        raise Error, "Invalid os_id #{os_id.inspect} for #{name}"
+      end
+
+      def checked_path(label, path)
+        return checked_text(label, path) if path.is_a?(String) && File.absolute_path?(path)
+
+        raise Error, "Invalid #{label} #{path.inspect}: use an absolute path"
+      end
+
+      def checked_gem_env(gem_env)
+        raise Error, 'Invalid gem_env: use a mapping of GEM_HOME and GEM_PATH' unless gem_env.is_a?(Hash) && (gem_env.keys - GEM_ENV).empty?
+
+        gem_env.to_h { |key, value| [key.dup.freeze, checked_text(key, value)] }.freeze
+      end
+
+      def checked_text(label, text)
+        return text.dup.freeze if text.is_a?(String) && text.valid_encoding? && !text.empty? && !text.match?(/[[:cntrl:]]/)
+
+        raise Error, "Invalid #{label} #{text.inspect}"
+      end
+    end
+  end
+end