wheneverd 0.1.0

data/lib/wheneverd/dsl/calendar_symbol_period_list.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    # Validates `every(:monday, :tuesday, ...)` symbol lists.
+    module CalendarSymbolPeriodList
+      # @param periods [Array<Symbol>]
+      # @param allowed_symbols [Array<Symbol>]
+      # @param path [String]
+      # @return [Array<Symbol>] the validated input
+      def self.validate(periods, allowed_symbols:, path:)
+        validate_array!(periods, path: path)
+        validate_symbols!(periods, path: path)
+        validate_allowed_symbols!(periods, allowed_symbols: allowed_symbols, path: path)
+        periods
+      end
+
+      def self.validate_array!(periods, path:)
+        return if periods.is_a?(Array) && !periods.empty?
+
+        raise InvalidPeriodError.new("every() periods must be a non-empty Array", path: path)
+      end
+      private_class_method :validate_array!
+
+      def self.validate_symbols!(periods, path:)
+        return if periods.all?(Symbol)
+
+        raise InvalidPeriodError.new("every() periods must be Symbols", path: path)
+      end
+      private_class_method :validate_symbols!
+
+      def self.validate_allowed_symbols!(periods, allowed_symbols:, path:)
+        invalid = periods.reject { |sym| allowed_symbols.include?(sym) }.uniq
+        return if invalid.empty?
+
+        unknown = invalid.map(&:inspect).join(", ")
+        raise InvalidPeriodError.new("Unknown period symbol(s): #{unknown}", path: path)
+      end
+      private_class_method :validate_allowed_symbols!
+    end
+  end
+end

data/lib/wheneverd/dsl/context.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    # The evaluation context used for schedule files.
+    #
+    # The schedule file is evaluated via `instance_eval`, so methods defined here become available
+    # as the schedule DSL (`every`, `command`).
+    class Context
+      # @return [String] absolute schedule path
+      attr_reader :path
+
+      # @return [Wheneverd::Schedule] schedule being built during evaluation
+      attr_reader :schedule
+
+      # @param path [String]
+      def initialize(path:)
+        @path = path
+        @schedule = Wheneverd::Schedule.new
+        @current_entry = nil
+        @period_parser = Wheneverd::DSL::PeriodParser.new(path: path)
+      end
+
+      # Define a scheduled entry and evaluate its jobs block.
+      #
+      # @param periods [Array<String, Symbol, Wheneverd::Duration, Array<Symbol>>]
+      # @param at [String, Array<String>, nil]
+      # @param roles [Object] stored but currently not used for filtering
+      # @return [Wheneverd::Entry]
+      def every(*periods, at: nil, roles: nil, &block)
+        raise InvalidPeriodError.new("every() requires a block", path: path) unless block
+
+        raise InvalidPeriodError.new("every() requires a period", path: path) if periods.empty?
+
+        period = periods.length == 1 ? periods.first : periods
+        trigger = @period_parser.trigger_for(period, at: at)
+        entry = Wheneverd::Entry.new(trigger: trigger, roles: roles)
+
+        schedule.add_entry(entry)
+
+        with_current_entry(entry) { instance_eval(&block) }
+
+        entry
+      end
+
+      # Add a oneshot command job to the current `every` entry.
+      #
+      # @param command_str [String]
+      # @return [void]
+      def command(command_str)
+        unless @current_entry
+          raise LoadError.new("command() must be called inside every() block",
+                              path: path)
+        end
+
+        @current_entry.add_job(Wheneverd::Job::Command.new(command: command_str))
+      rescue Wheneverd::InvalidCommandError => e
+        raise LoadError.new(e.message, path: path)
+      end
+
+      private
+
+      def with_current_entry(entry)
+        previous_entry = @current_entry
+        @current_entry = entry
+        yield
+      ensure
+        @current_entry = previous_entry
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    # Base error class for schedule DSL problems.
+    #
+    # These errors include the path to the schedule file to make CLI output more actionable.
+    class Error < Wheneverd::Error
+      # @return [String]
+      attr_reader :path
+
+      # @param message [String]
+      # @param path [String]
+      def initialize(message, path:)
+        super(message)
+        @path = path
+      end
+    end
+
+    # Raised when a schedule file cannot be evaluated or is invalid.
+    class LoadError < Error; end
+
+    # Raised when an `every(...)` period cannot be parsed or validated.
+    class InvalidPeriodError < Error; end
+
+    # Raised when `at:` times cannot be validated.
+    class InvalidAtError < Error; end
+  end
+end

data/lib/wheneverd/dsl/loader.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    # Loads a schedule file into a {Wheneverd::Schedule}.
+    #
+    # This evaluates the file as Ruby in an isolated DSL context, and wraps errors with the
+    # schedule path for clearer CLI output.
+    #
+    # Note that schedules are arbitrary Ruby code. Do not load untrusted schedule files.
+    class Loader
+      # Load and evaluate a schedule file.
+      #
+      # @param path [String]
+      # @return [Wheneverd::Schedule]
+      def self.load_file(path)
+        absolute_path = File.expand_path(path.to_s)
+        evaluate_file(absolute_path)
+      rescue Wheneverd::DSL::Error => e
+        raise_with_path(e, absolute_path)
+      rescue Wheneverd::Error, StandardError => e
+        raise_load_error(e, absolute_path)
+      end
+
+      def self.evaluate_file(absolute_path)
+        context = Wheneverd::DSL::Context.new(path: absolute_path)
+        source = File.read(absolute_path)
+
+        context.instance_eval(source, absolute_path, 1)
+        context.schedule
+      end
+      private_class_method :evaluate_file
+
+      def self.raise_with_path(error, absolute_path)
+        wrapped = error.class.new("#{absolute_path}: #{error.message}", path: absolute_path)
+        wrapped.set_backtrace(error.backtrace)
+        raise wrapped
+      end
+      private_class_method :raise_with_path
+
+      def self.raise_load_error(error, absolute_path)
+        wrapped = LoadError.new("#{absolute_path}: #{error.message}", path: absolute_path)
+        wrapped.set_backtrace(error.backtrace)
+        raise wrapped
+      end
+      private_class_method :raise_load_error
+    end
+  end
+end

data/lib/wheneverd/dsl/period_parser.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "calendar_symbol_period_list"
+
+module Wheneverd
+  module DSL
+    # Converts DSL `every(...)` period values into trigger objects.
+    #
+    # Supported period forms are described in the README.
+    #
+    # Notes:
+    #
+    # - Interval strings and {Wheneverd::Duration} values produce monotonic triggers
+    #   ({Wheneverd::Trigger::Interval}).
+    # - Calendar symbol periods and cron strings produce calendar triggers
+    #   ({Wheneverd::Trigger::Calendar}).
+    # - The `at:` option is only valid for calendar triggers, with a convenience exception for
+    #   `every 1.day, at: ...` which is treated as a daily calendar trigger.
+    class PeriodParser
+      DAY_SECONDS = 60 * 60 * 24
+      REBOOT_NOT_SUPPORTED_MESSAGE =
+        "The :reboot period is not supported; use an interval or calendar period instead"
+
+      CALENDAR_SYMBOLS = %i[
+        hour day month year weekday weekend
+        monday tuesday wednesday thursday friday saturday sunday
+      ].freeze
+
+      attr_reader :path
+
+      # @param path [String] schedule path for error reporting
+      def initialize(path:)
+        @path = path
+      end
+
+      # @param period [String, Symbol, Array<Symbol>, Wheneverd::Duration]
+      # @param at [String, Array<String>, nil]
+      # @return [Wheneverd::Trigger::Interval, Wheneverd::Trigger::Calendar]
+      def trigger_for(period, at:)
+        at_times = AtNormalizer.normalize(at, path: path)
+        trigger_for_period(period, at_times: at_times)
+      rescue Wheneverd::InvalidIntervalError => e
+        raise InvalidPeriodError.new(e.message, path: path)
+      end
+
+      private
+
+      def trigger_for_period(period, at_times:)
+        return duration_trigger_for(period, at_times: at_times) if period.is_a?(Wheneverd::Duration)
+        return array_trigger_for(period, at_times: at_times) if period.is_a?(Array)
+        return string_trigger_for(period, at_times: at_times) if period.is_a?(String)
+        return symbol_trigger_for(period, at_times: at_times) if period.is_a?(Symbol)
+
+        raise InvalidPeriodError.new("Unsupported period type: #{period.class}", path: path)
+      end
+
+      def duration_trigger_for(duration, at_times:)
+        if at_times.any?
+          return daily_calendar_trigger(at_times) if duration.to_i == DAY_SECONDS
+
+          raise InvalidPeriodError.new("at: is only supported with calendar periods", path: path)
+        end
+
+        Wheneverd::Trigger::Interval.new(seconds: duration.to_i)
+      end
+
+      def daily_calendar_trigger(at_times)
+        Wheneverd::Trigger::Calendar.new(on_calendar: build_calendar_specs("day", at_times))
+      end
+
+      def string_trigger_for(str, at_times:)
+        period_str = str.strip
+
+        return interval_trigger(period_str, at_times: at_times) if interval_string?(period_str)
+
+        return cron_trigger(period_str, at_times: at_times) if cron_string?(period_str)
+
+        raise InvalidPeriodError.new("Unrecognized period #{period_str.inspect}", path: path)
+      end
+
+      def interval_trigger(period_str, at_times:)
+        if at_times.any?
+          raise InvalidPeriodError.new("at: is not supported for interval periods", path: path)
+        end
+
+        seconds = Wheneverd::Interval.parse(period_str)
+        Wheneverd::Trigger::Interval.new(seconds: seconds)
+      end
+
+      def cron_trigger(period_str, at_times:)
+        if at_times.any?
+          raise InvalidPeriodError.new("at: is not supported for cron periods", path: path)
+        end
+
+        Wheneverd::Trigger::Calendar.new(on_calendar: ["cron:#{period_str}"])
+      end
+
+      def symbol_trigger_for(sym, at_times:)
+        raise InvalidPeriodError.new(REBOOT_NOT_SUPPORTED_MESSAGE, path: path) if sym == :reboot
+
+        if CALENDAR_SYMBOLS.include?(sym)
+          return Wheneverd::Trigger::Calendar.new(
+            on_calendar: build_calendar_specs(sym.to_s, at_times)
+          )
+        end
+
+        raise InvalidPeriodError.new("Unknown period symbol: #{sym.inspect}", path: path)
+      end
+
+      def array_trigger_for(periods, at_times:)
+        bases = CalendarSymbolPeriodList.validate(
+          periods,
+          allowed_symbols: CALENDAR_SYMBOLS,
+          path: path
+        ).map(&:to_s)
+        specs = bases.flat_map { |base| build_calendar_specs(base, at_times) }.uniq
+        Wheneverd::Trigger::Calendar.new(on_calendar: specs)
+      end
+
+      def build_calendar_specs(base, at_times)
+        return [base] if at_times.empty?
+
+        at_times.map { |t| "#{base}@#{t}" }
+      end
+
+      def interval_string?(str)
+        /\A-?\d+[smhdw]\z/.match?(str)
+      end
+
+      def cron_string?(str)
+        str.split(/\s+/).length == 5
+      end
+    end
+  end
+end

data/lib/wheneverd/duration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # A positive duration represented as a whole number of seconds.
+  #
+  # This type is produced by the `Numeric` helpers from {Wheneverd::CoreExt::NumericDuration}
+  # (for example, `5.minutes`), and is used by the DSL period parser.
+  class Duration
+    # @return [Integer] duration in seconds
+    attr_reader :seconds
+
+    # @param seconds [Integer] duration in seconds (must be positive)
+    def initialize(seconds)
+      unless seconds.is_a?(Integer)
+        raise ArgumentError, "Duration seconds must be an Integer (got #{seconds.class})"
+      end
+
+      raise ArgumentError, "Duration seconds must be positive (got #{seconds})" if seconds <= 0
+
+      @seconds = seconds
+    end
+
+    def to_i
+      seconds
+    end
+  end
+end

data/lib/wheneverd/entry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # A single scheduled unit of work.
+  #
+  # An entry ties together a trigger (when to run) and one or more jobs (what to run).
+  class Entry
+    # @return [Wheneverd::Trigger::Interval, Wheneverd::Trigger::Calendar, Wheneverd::Trigger::Boot]
+    attr_reader :trigger, :jobs, :roles
+
+    # @param trigger [Object] a trigger object describing when to run
+    # @param jobs [Array<Object>] job objects (usually {Wheneverd::Job::Command})
+    # @param roles [Object] stored but currently not used for filtering
+    def initialize(trigger:, jobs: [], roles: nil)
+      raise ArgumentError, "trigger is required" if trigger.nil?
+
+      @trigger = trigger
+      @jobs = jobs.dup
+      @roles = roles
+    end
+
+    # Append a job to the entry.
+    #
+    # @param job [Object]
+    # @return [Entry] self
+    def add_job(job)
+      jobs << job
+      self
+    end
+  end
+end

data/lib/wheneverd/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Raised when {Wheneverd::Interval.parse} cannot parse or validate an interval string.
+  class InvalidIntervalError < Error; end
+
+  # Raised when a {Wheneverd::Job::Command} is created with an invalid command string.
+  class InvalidCommandError < Error; end
+end

data/lib/wheneverd/interval.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Parser for compact interval strings used by the DSL.
+  #
+  # The supported format is `"<n>s|m|h|d|w"`, for example `"5m"` or `"1h"`.
+  module Interval
+    MULTIPLIERS = {
+      "s" => 1,
+      "m" => 60,
+      "h" => 60 * 60,
+      "d" => 60 * 60 * 24,
+      "w" => 60 * 60 * 24 * 7
+    }.freeze
+
+    FORMAT = /\A(?<n>-?\d+)(?<unit>[smhdw])\z/.freeze
+
+    # Parse an interval string into seconds.
+    #
+    # @param str [String] interval like `"5m"`
+    # @return [Integer] seconds
+    # @raise [Wheneverd::InvalidIntervalError] if the input is invalid
+    def self.parse(str)
+      input = str.to_s.strip
+      match = FORMAT.match(input)
+      unless match
+        raise InvalidIntervalError,
+              "Invalid interval #{input.inspect}; expected <n>s|m|h|d|w (example: \"5m\")"
+      end
+
+      n = Integer(match[:n], 10)
+      raise InvalidIntervalError, "Interval must be positive (got #{input.inspect})" if n <= 0
+
+      n * MULTIPLIERS.fetch(match[:unit])
+    end
+  end
+end

data/lib/wheneverd/job/command.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Job
+    # A oneshot command job rendered as `ExecStart=` in a `systemd` service unit.
+    #
+    # Note that the command is inserted into `ExecStart=` as-is. If you need shell features like
+    # pipes, redirects, or environment variable expansion, wrap the command explicitly:
+    #
+    # @example
+    #   command "/bin/bash -lc 'echo hello | sed -e s/hello/hi/'"
+    class Command
+      # @return [String]
+      attr_reader :command
+
+      # @param command [String] non-empty command to run
+      def initialize(command:)
+        unless command.is_a?(String)
+          raise InvalidCommandError, "Command must be a String (got #{command.class})"
+        end
+
+        command_stripped = command.strip
+        raise InvalidCommandError, "Command must not be empty" if command_stripped.empty?
+
+        @command = command_stripped
+      end
+    end
+  end
+end

data/lib/wheneverd/schedule.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # A schedule is an ordered list of {Entry} objects.
+  #
+  # Schedules are typically created by evaluating a schedule file in the DSL context.
+  class Schedule
+    # @return [Array<Entry>]
+    attr_reader :entries
+
+    # @param entries [Array<Entry>]
+    def initialize(entries: [])
+      @entries = entries.dup
+    end
+
+    # Append an entry to the schedule.
+    #
+    # @param entry [Entry]
+    # @return [Schedule] self
+    def add_entry(entry)
+      entries << entry
+      self
+    end
+  end
+end

data/lib/wheneverd/systemd/calendar_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # Translates higher-level schedule period specs into systemd `OnCalendar=` values.
+    #
+    # The DSL produces values like `"day@4:30 am"` or `"cron:0 0 27-31 * *"`, which are normalized
+    # here into systemd-friendly calendar expressions.
+    module CalendarSpec
+      BASE_ALIASES = {
+        "hour" => "hourly",
+        "day" => "daily",
+        "month" => "monthly",
+        "year" => "yearly"
+      }.freeze
+
+      PREFIXES = {
+        "day" => "*-*-*",
+        "weekday" => "Mon..Fri *-*-*",
+        "weekend" => "Sat,Sun *-*-*"
+      }.freeze
+
+      WEEKDAYS = {
+        "monday" => "Mon",
+        "tuesday" => "Tue",
+        "wednesday" => "Wed",
+        "thursday" => "Thu",
+        "friday" => "Fri",
+        "saturday" => "Sat",
+        "sunday" => "Sun"
+      }.freeze
+
+      # Convert a calendar spec into a systemd `OnCalendar=` value.
+      #
+      # @param spec [String]
+      # @return [String]
+      # @raise [Wheneverd::Systemd::InvalidCalendarSpecError]
+      def self.to_on_calendar(spec)
+        values = to_on_calendar_values(spec)
+        return values.fetch(0) if values.length == 1
+
+        message =
+          "Invalid calendar spec: #{spec.to_s.strip.inspect} " \
+          "expands to multiple OnCalendar values"
+        raise InvalidCalendarSpecError, message
+      end
+
+      # Convert a calendar spec into one or more systemd `OnCalendar=` values.
+      #
+      # Some inputs (e.g., certain cron expressions) may require multiple `OnCalendar=` entries
+      # to preserve semantics.
+      #
+      # @param spec [String]
+      # @return [Array<String>]
+      # @raise [Wheneverd::Systemd::InvalidCalendarSpecError]
+      def self.to_on_calendar_values(spec)
+        input = spec.to_s.strip
+        raise InvalidCalendarSpecError, "Invalid calendar spec: empty" if input.empty?
+
+        return cron_to_on_calendar_values(input) if input.start_with?("cron:")
+
+        base, at = input.split("@", 2)
+        base = base.strip
+
+        raise InvalidCalendarSpecError, "Invalid calendar spec: #{input.inspect}" if base.empty?
+
+        [translate_base_with_optional_at(base, at)]
+      end
+
+      def self.translate_base_with_optional_at(base, at)
+        return base_to_systemd(base) if at.nil?
+
+        time = Wheneverd::Systemd::TimeParser.parse(at)
+        "#{time_prefix_for_at(base)} #{time}"
+      end
+      private_class_method :translate_base_with_optional_at
+
+      def self.base_to_systemd(base)
+        return BASE_ALIASES.fetch(base) if BASE_ALIASES.key?(base)
+
+        "#{time_prefix_for_midnight(base)} 00:00:00"
+      end
+      private_class_method :base_to_systemd
+
+      def self.cron_to_on_calendar_values(input)
+        cron = input.delete_prefix("cron:")
+        Wheneverd::Systemd::CronParser.to_on_calendar_values(cron)
+      end
+      private_class_method :cron_to_on_calendar_values
+
+      def self.time_prefix_for_at(base)
+        return PREFIXES.fetch(base) if PREFIXES.key?(base)
+        return "#{WEEKDAYS.fetch(base)} *-*-*" if WEEKDAYS.key?(base)
+
+        raise InvalidCalendarSpecError,
+              "Invalid calendar spec: #{base.inspect} does not support @time"
+      end
+      private_class_method :time_prefix_for_at
+
+      def self.time_prefix_for_midnight(base)
+        return PREFIXES.fetch(base) if PREFIXES.key?(base)
+        return "#{WEEKDAYS.fetch(base)} *-*-*" if WEEKDAYS.key?(base)
+
+        raise InvalidCalendarSpecError, "Invalid calendar spec: #{base.inspect}"
+      end
+      private_class_method :time_prefix_for_midnight
+    end
+  end
+end