wheneverd 0.2.1 → 0.4.0

data/lib/wheneverd/systemd/unit_namer.rb

@@ -37,26 +37,18 @@ module Wheneverd
       private_class_method :signature
 
       def self.trigger_signature(trigger)
-        case trigger
-        when Wheneverd::Trigger::Interval
-          "interval:#{trigger.seconds}"
-        when Wheneverd::Trigger::Boot
-          "boot:#{trigger.seconds}"
-        when Wheneverd::Trigger::Calendar
-          "calendar:#{trigger.on_calendar.sort.join('|')}"
-        else
+        unless trigger.respond_to?(:signature)
           raise ArgumentError, "Unsupported trigger type: #{trigger.class}"
         end
+
+        trigger.signature
       end
       private_class_method :trigger_signature
 
       def self.job_signature(job)
-        case job
-        when Wheneverd::Job::Command
-          "command:#{job.command}"
-        else
-          raise ArgumentError, "Unsupported job type: #{job.class}"
-        end
+        raise ArgumentError, "Unsupported job type: #{job.class}" unless job.respond_to?(:signature)
+
+        job.signature
       end
       private_class_method :job_signature
 

data/lib/wheneverd/systemd/unit_path_utils.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # Shared utilities for unit file path operations.
+    #
+    # These methods are used by {UnitWriter}, {UnitDeleter}, {UnitLister}, and {Renderer}
+    # to ensure consistent identifier sanitization, path pattern matching, and marker detection.
+    module UnitPathUtils
+      # Sanitizes an identifier for use in unit file names.
+      #
+      # Invalid characters are replaced with `-`, and consecutive/leading/trailing dashes
+      # are collapsed or removed.
+      #
+      # @param identifier [String]
+      # @return [String]
+      # @raise [InvalidIdentifierError] if the identifier is empty or contains no alphanumeric chars
+      def self.sanitize_identifier(identifier)
+        raw = identifier.to_s.strip
+        raise InvalidIdentifierError, "identifier must not be empty" if raw.empty?
+
+        sanitized = raw.gsub(/[^A-Za-z0-9_-]/, "-").gsub(/-+/, "-").gsub(/\A-|-+\z/, "")
+        if sanitized.empty?
+          raise InvalidIdentifierError,
+                "identifier must include at least one alphanumeric character"
+        end
+
+        sanitized
+      end
+
+      # Returns a regex pattern matching unit basenames for the given identifier.
+      #
+      # Matches both new-style (SHA-based) and legacy (eN-jN) unit names.
+      #
+      # @param identifier [String]
+      # @return [Regexp]
+      def self.basename_pattern(identifier)
+        id = sanitize_identifier(identifier)
+        /\Awheneverd-#{Regexp.escape(id)}-(?:[0-9a-f]{12}(?:-\d+)?|e\d+-j\d+)\.(service|timer)\z/
+      end
+
+      # Checks if a unit file was generated by wheneverd.
+      #
+      # Reads the first line of the file and checks for the marker prefix.
+      #
+      # @param path [String] path to the unit file
+      # @return [Boolean]
+      def self.generated_marker?(path)
+        first_line = File.open(path, "r") { |f| f.gets.to_s }
+        first_line.start_with?(Wheneverd::Systemd::Renderer::MARKER_PREFIX)
+      end
+    end
+  end
+end

data/lib/wheneverd/systemd/unit_writer.rb

@@ -67,7 +67,7 @@ module Wheneverd
       private_class_method :prune_stale_units
 
       def self.stale_unit_paths(dest_dir, identifier:, keep:)
-        pattern = basename_pattern(identifier)
+        pattern = UnitPathUtils.basename_pattern(identifier)
         Dir.children(dest_dir).filter_map do |basename|
           next if keep.key?(basename)
 
@@ -83,36 +83,10 @@ module Wheneverd
         return false unless pattern.match?(basename)
         return false unless File.file?(path)
 
-        generated_marker?(path)
+        UnitPathUtils.generated_marker?(path)
       end
       private_class_method :stale_unit_path?
 
-      def self.basename_pattern(identifier)
-        id = sanitize_identifier(identifier)
-        /\Awheneverd-#{Regexp.escape(id)}-(?:[0-9a-f]{12}(?:-\d+)?|e\d+-j\d+)\.(service|timer)\z/
-      end
-      private_class_method :basename_pattern
-
-      def self.generated_marker?(path)
-        first_line = File.open(path, "r") { |f| f.gets.to_s }
-        first_line.start_with?(Wheneverd::Systemd::Renderer::MARKER_PREFIX)
-      end
-      private_class_method :generated_marker?
-
-      def self.sanitize_identifier(identifier)
-        raw = identifier.to_s.strip
-        raise InvalidIdentifierError, "identifier must not be empty" if raw.empty?
-
-        sanitized = raw.gsub(/[^A-Za-z0-9_-]/, "-").gsub(/-+/, "-").gsub(/\A-|-+\z/, "")
-        if sanitized.empty?
-          raise InvalidIdentifierError,
-                "identifier must include at least one alphanumeric character"
-        end
-
-        sanitized
-      end
-      private_class_method :sanitize_identifier
-
       def self.atomic_write(dest_path, contents, dir:)
         basename = File.basename(dest_path)
         tmp = Tempfile.new([".#{basename}.", ".tmp"], dir)

data/lib/wheneverd/trigger/base.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Trigger
+    # Base module for trigger types.
+    #
+    # All trigger types must implement:
+    # - `#systemd_timer_lines` - returns Array<String> of systemd [Timer] lines
+    # - `#signature` - returns a String signature for stable unit naming
+    module Base
+      # @return [Array<String>] systemd `[Timer]` lines for this trigger
+      def systemd_timer_lines
+        raise NotImplementedError, "#{self.class} must implement #systemd_timer_lines"
+      end
+
+      # @return [String] stable signature for unit naming
+      def signature
+        raise NotImplementedError, "#{self.class} must implement #signature"
+      end
+    end
+  end
+end

data/lib/wheneverd/trigger/boot.rb

@@ -4,23 +4,25 @@ module Wheneverd
   module Trigger
     # A boot trigger, rendered as `OnBootSec=`.
     class Boot
+      include Base
+
       # @return [Integer]
       attr_reader :seconds
 
       # @param seconds [Integer] seconds after boot (must be positive)
       def initialize(seconds:)
-        unless seconds.is_a?(Integer)
-          raise ArgumentError, "Boot seconds must be an Integer (got #{seconds.class})"
-        end
-        raise ArgumentError, "Boot seconds must be positive (got #{seconds})" if seconds <= 0
-
-        @seconds = seconds
+        @seconds = Validation.positive_integer(seconds, name: "Boot seconds")
       end
 
       # @return [Array<String>] systemd `[Timer]` lines for this trigger
       def systemd_timer_lines
         ["OnBootSec=#{seconds}"]
       end
+
+      # @return [String] stable signature for unit naming
+      def signature
+        "boot:#{seconds}"
+      end
     end
   end
 end

data/lib/wheneverd/trigger/calendar.rb

@@ -4,6 +4,8 @@ module Wheneverd
   module Trigger
     # A calendar trigger, rendered as one or more `OnCalendar=` lines.
     class Calendar
+      include Base
+
       # @return [Array<String>] calendar specs (already in `systemd` OnCalendar format)
       attr_reader :on_calendar
 
@@ -21,6 +23,11 @@ module Wheneverd
       def systemd_timer_lines
         on_calendar.map { |spec| "OnCalendar=#{spec}" }
       end
+
+      # @return [String] stable signature for unit naming
+      def signature
+        "calendar:#{on_calendar.sort.join('|')}"
+      end
     end
   end
 end

data/lib/wheneverd/trigger/interval.rb

@@ -8,23 +8,25 @@ module Wheneverd
     # - `OnActiveSec=` to schedule the first run relative to timer activation.
     # - `OnUnitActiveSec=` to schedule subsequent runs relative to the last run.
     class Interval
+      include Base
+
       # @return [Integer]
       attr_reader :seconds
 
       # @param seconds [Integer] seconds between runs (must be positive)
       def initialize(seconds:)
-        unless seconds.is_a?(Integer)
-          raise ArgumentError, "Interval seconds must be an Integer (got #{seconds.class})"
-        end
-        raise ArgumentError, "Interval seconds must be positive (got #{seconds})" if seconds <= 0
-
-        @seconds = seconds
+        @seconds = Validation.positive_integer(seconds, name: "Interval seconds")
       end
 
       # @return [Array<String>] systemd `[Timer]` lines for this trigger
       def systemd_timer_lines
         ["OnActiveSec=#{seconds}", "OnUnitActiveSec=#{seconds}"]
       end
+
+      # @return [String] stable signature for unit naming
+      def signature
+        "interval:#{seconds}"
+      end
     end
   end
 end

data/lib/wheneverd/validation.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Common validation utilities for consistent error handling across the codebase.
+  #
+  # These validators follow a consistent pattern:
+  # - Return the validated value if valid
+  # - Raise an appropriate error with a descriptive message if invalid
+  #
+  # @example Type validation
+  #   Validation.type(value, Integer, name: "seconds")
+  #   # => value or raises ArgumentError
+  #
+  # @example Positive integer validation
+  #   Validation.positive_integer(value, name: "seconds")
+  #   # => value or raises ArgumentError
+  module Validation
+    # Validate that a value is of the expected type.
+    #
+    # @param value [Object] the value to validate
+    # @param expected_type [Class, Module] the expected type
+    # @param name [String] the parameter name for error messages
+    # @return [Object] the validated value
+    # @raise [ArgumentError] if the value is not of the expected type
+    def self.type(value, expected_type, name:)
+      return value if value.is_a?(expected_type)
+
+      raise ArgumentError,
+            "#{name} must be #{expected_type_name(expected_type)} (got #{value.class})"
+    end
+
+    # Validate that a value is a positive integer.
+    #
+    # @param value [Object] the value to validate
+    # @param name [String] the parameter name for error messages
+    # @return [Integer] the validated value
+    # @raise [ArgumentError] if the value is not a positive integer
+    def self.positive_integer(value, name:)
+      type(value, Integer, name: name)
+      return value if value.positive?
+
+      raise ArgumentError, "#{name} must be positive (got #{value})"
+    end
+
+    # Validate that a string is non-empty after stripping whitespace.
+    #
+    # @param value [String] the value to validate
+    # @param name [String] the parameter name for error messages
+    # @return [String] the stripped value
+    # @raise [ArgumentError] if the value is empty after stripping
+    def self.non_empty_string(value, name:)
+      stripped = value.to_s.strip
+      return stripped unless stripped.empty?
+
+      raise ArgumentError, "#{name} must not be empty"
+    end
+
+    # Validate that an array is non-empty.
+    #
+    # @param value [Array] the value to validate
+    # @param name [String] the parameter name for error messages
+    # @return [Array] the validated value
+    # @raise [ArgumentError] if the array is empty
+    def self.non_empty_array(value, name:)
+      type(value, Array, name: name)
+      return value unless value.empty?
+
+      raise ArgumentError, "#{name} must not be empty"
+    end
+
+    # Validate that a value is within a range.
+    #
+    # @param value [Comparable] the value to validate
+    # @param range [Range] the valid range
+    # @param name [String] the parameter name for error messages
+    # @return [Comparable] the validated value
+    # @raise [ArgumentError] if the value is outside the range
+    def self.in_range(value, range, name:)
+      return value if range.cover?(value)
+
+      raise ArgumentError, "#{name} must be in #{range} (got #{value})"
+    end
+
+    def self.expected_type_name(expected_type)
+      "a #{expected_type}"
+    end
+    private_class_method :expected_type_name
+  end
+end

data/lib/wheneverd/version.rb

@@ -2,5 +2,5 @@
 
 module Wheneverd
   # Gem version.
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

data/lib/wheneverd.rb

@@ -11,14 +11,15 @@ module Wheneverd
   # - {Wheneverd::DSL::Loader} for evaluating `config/schedule.rb`
   # - {Wheneverd::Systemd::Renderer} for generating unit contents
   # - {Wheneverd::CLI} for the command-line interface
-  class Error < StandardError; end
 end
 
 require_relative "wheneverd/errors"
+require_relative "wheneverd/validation"
 require_relative "wheneverd/duration"
 require_relative "wheneverd/interval"
 require_relative "wheneverd/core_ext/numeric_duration"
 require_relative "wheneverd/job/command"
+require_relative "wheneverd/trigger/base"
 require_relative "wheneverd/trigger/interval"
 require_relative "wheneverd/trigger/calendar"
 require_relative "wheneverd/trigger/boot"
@@ -30,11 +31,14 @@ require_relative "wheneverd/dsl/period_parser"
 require_relative "wheneverd/dsl/context"
 require_relative "wheneverd/dsl/loader"
 require_relative "wheneverd/systemd/errors"
+require_relative "wheneverd/systemd/unit_path_utils"
 require_relative "wheneverd/systemd/time_parser"
 require_relative "wheneverd/systemd/cron_parser"
 require_relative "wheneverd/systemd/calendar_spec"
 require_relative "wheneverd/systemd/unit_namer"
+require_relative "wheneverd/systemd/unit_content_builder"
 require_relative "wheneverd/systemd/renderer"
+require_relative "wheneverd/systemd/analyze"
 require_relative "wheneverd/systemd/systemctl"
 require_relative "wheneverd/systemd/loginctl"
 require_relative "wheneverd/systemd/unit_writer"

data/test/cli_diff_test.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/cli_test_helpers"
+
+class CLIDiffTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_exits_one_and_shows_added_diff_when_units_are_not_installed
+    with_inited_unit_dir("missing_units") do |unit_dir|
+      timer = first_timer
+      status, out, err = run_diff(unit_dir)
+      assert_diff_added(status, out, err, unit_dir, timer)
+    end
+  end
+
+  def test_exits_zero_when_no_differences
+    with_installed_units do |unit_dir|
+      status, out, err = run_diff(unit_dir)
+      assert_equal 0, status
+      assert_equal "", err
+      assert_equal "", out
+    end
+  end
+
+  def test_exits_one_and_shows_removed_lines_when_installed_unit_was_modified
+    with_installed_units do |unit_dir|
+      timer = first_timer
+      File.open(File.join(unit_dir, timer), "a") { |f| f.puts "# local edit" }
+      status, out, err = run_diff(unit_dir)
+      assert_diff_contains(status, out, err, timer, "-# local edit")
+    end
+  end
+
+  def test_exits_one_and_shows_added_lines_when_installed_unit_is_missing_lines
+    with_installed_units do |unit_dir|
+      timer = first_timer
+      remove_exact_line(File.join(unit_dir, timer), "Persistent=true\n")
+      status, out, err = run_diff(unit_dir)
+      assert_diff_contains(status, out, err, timer, "+Persistent=true")
+    end
+  end
+
+  def test_exits_one_and_shows_diff_for_stale_units_on_disk
+    with_installed_units do |unit_dir|
+      stale_timer = "wheneverd-demo-000000000000.timer"
+      stale_path = write_stale_timer(unit_dir, stale_timer)
+      status, out, err = run_diff(unit_dir)
+      assert_diff_removed(status, out, err, stale_timer, stale_path)
+    end
+  end
+
+  def test_returns_two_on_error
+    with_project_dir do
+      status, out, err = run_cli(["diff", "--schedule", "missing.rb"])
+      assert_equal 2, status
+      assert_equal "", out
+      assert_includes err, "Schedule file not found"
+    end
+  end
+
+  private
+
+  def with_inited_unit_dir(name)
+    with_inited_project_dir do |project_dir|
+      yield File.join(project_dir, name)
+    end
+  end
+
+  def with_installed_units
+    with_inited_unit_dir("tmp_units") do |unit_dir|
+      assert_equal 0, run_cli(["write", "--identifier", "demo", "--unit-dir", unit_dir]).first
+      yield unit_dir
+    end
+  end
+
+  def run_diff(unit_dir)
+    run_cli(["diff", "--identifier", "demo", "--unit-dir", unit_dir])
+  end
+
+  def first_timer
+    expected_timer_basenames(identifier: "demo").fetch(0)
+  end
+
+  def remove_exact_line(path, line)
+    File.write(path, File.read(path).lines.reject { |l| l == line }.join)
+  end
+
+  def write_stale_timer(unit_dir, basename)
+    path = File.join(unit_dir, basename)
+    File.write(path, "#{Wheneverd::Systemd::Renderer::MARKER_PREFIX} test\n# stale\n")
+    path
+  end
+
+  def assert_diff_added(status, out, err, unit_dir, timer)
+    assert_equal 1, status
+    assert_equal "", err
+    assert_includes out, "diff --wheneverd #{timer}"
+    assert_includes out, "--- /dev/null"
+    assert_includes out, "+++ #{File.join(File.expand_path(unit_dir), timer)}"
+  end
+
+  def assert_diff_contains(status, out, err, timer, expected_line)
+    assert_equal 1, status
+    assert_equal "", err
+    assert_includes out, "diff --wheneverd #{timer}"
+    assert_includes out, expected_line
+  end
+
+  def assert_diff_removed(status, out, err, timer, path)
+    assert_equal 1, status
+    assert_equal "", err
+    assert_includes out, "diff --wheneverd #{timer}"
+    assert_includes out, "--- #{path}"
+    assert_includes out, "+++ /dev/null"
+    assert_includes out, "-# stale"
+  end
+end

data/test/cli_init_test.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/cli_test_helpers"
+
+class CLIInitTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_writes_template_with_shell_and_argv_examples
+    with_project_dir do |project_dir|
+      status, out, err = run_cli(["init"])
+      assert_equal 0, status
+      assert_equal "", err
+      assert_includes out, "Wrote schedule template to"
+
+      schedule_path = File.join(project_dir, "config", "schedule.rb")
+      schedule = File.read(schedule_path)
+      assert_includes schedule, "command [\"echo\", \"hello world\"]"
+      assert_includes schedule, "shell \"echo hello | sed -e s/hello/hi/\""
+    end
+  end
+
+  def test_refuses_to_overwrite_without_force
+    with_project_dir do
+      assert_equal 0, run_cli(["init"]).first
+
+      status, out, err = run_cli(["init"])
+      assert_equal 1, status
+      assert_equal "", out
+      assert_includes err, "already exists"
+      assert_includes err, "--force"
+    end
+  end
+
+  def test_overwrites_with_force
+    with_project_dir do |project_dir|
+      assert_equal 0, run_cli(["init"]).first
+
+      schedule_path = File.join(project_dir, "config", "schedule.rb")
+      File.write(schedule_path, "# custom\n")
+
+      status, out, err = run_cli(["init", "--force"])
+      assert_equal 0, status
+      assert_equal "", err
+      assert_includes out, "Overwrote schedule template to"
+      assert_includes File.read(schedule_path), "Supported `every` period forms:"
+    end
+  end
+end

data/test/cli_status_test.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/cli_test_helpers"
+
+class CLIStatusTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_runs_list_timers_and_status_for_each_installed_timer
+    with_installed_units do |unit_dir|
+      status, _out, err, calls = run_status(unit_dir)
+      assert_cli_success(status, err)
+      assert_status_calls(calls, expected_timer_units)
+    end
+  end
+
+  def test_returns_nonzero_when_systemctl_fails
+    with_installed_units do |unit_dir|
+      status, _out, err, calls = run_status(unit_dir, exitstatus: 1, stderr: "boom\n")
+      assert_equal 1, status
+      assert_includes err, "systemctl failed"
+      assert_includes err, "boom"
+      assert_includes calls.fetch(0).fetch(0), "list-timers"
+    end
+  end
+
+  def test_exits_zero_and_does_not_call_systemctl_when_no_timers_installed
+    with_project_dir do |project_dir|
+      unit_dir = File.join(project_dir, "empty_units")
+      FileUtils.mkdir_p(unit_dir)
+      status, out, err, calls = run_status(unit_dir)
+      assert_cli_success(status, err)
+      assert_equal "", out
+      assert_equal [], calls
+    end
+  end
+
+  private
+
+  def with_installed_units
+    with_inited_project_dir do |project_dir|
+      unit_dir = File.join(project_dir, "tmp_units")
+      assert_equal 0, run_cli(["write", "--identifier", "demo", "--unit-dir", unit_dir]).first
+      yield unit_dir
+    end
+  end
+
+  def run_status(unit_dir, **kwargs)
+    run_cli_with_capture3_stub(["status", "--identifier", "demo", "--unit-dir", unit_dir], **kwargs)
+  end
+
+  def expected_timer_units
+    expected_timer_basenames(identifier: "demo").sort
+  end
+
+  def assert_status_calls(calls, expected_timers)
+    assert_list_timers_call(calls, expected_timers)
+    assert_status_unit_calls(calls, expected_timers)
+  end
+
+  def assert_list_timers_call(calls, expected_timers)
+    assert_systemctl_call_starts_with(
+      calls,
+      0,
+      SYSTEMCTL_USER_PREFIX + ["list-timers", "--all"],
+      includes: expected_timers
+    )
+  end
+
+  def assert_status_unit_calls(calls, expected_timers)
+    status_calls = calls.drop(1).map(&:first)
+    assert_equal expected_timers.length, status_calls.length
+    assert_equal expected_timers, status_calls.map(&:last).sort
+    status_calls.each { |args| assert_equal SYSTEMCTL_USER_PREFIX + ["status", args.last], args }
+  end
+end