wheneverd 0.1.0

data/lib/wheneverd/systemd/unit_deleter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Wheneverd
+  module Systemd
+    # Deletes previously generated unit files for a given identifier.
+    class UnitDeleter
+      DEFAULT_UNIT_DIR = UnitWriter::DEFAULT_UNIT_DIR
+
+      # @param identifier [String]
+      # @param unit_dir [String]
+      # @param dry_run [Boolean] return paths without deleting
+      # @return [Array<String>] deleted paths
+      def self.delete(identifier:, unit_dir: DEFAULT_UNIT_DIR, dry_run: false)
+        dest_dir = File.expand_path(unit_dir.to_s)
+        return [] unless Dir.exist?(dest_dir)
+
+        deleted = deletable_paths(dest_dir, basename_pattern(identifier))
+        deleted.each { |path| FileUtils.rm_f(path) unless dry_run }
+        deleted
+      end
+
+      def self.deletable_paths(dest_dir, pattern)
+        Dir.children(dest_dir).sort.filter_map do |basename|
+          next unless pattern.match?(basename)
+
+          path = File.join(dest_dir, basename)
+          next unless File.file?(path)
+          next unless generated_marker?(path)
+
+          path
+        end
+      end
+      private_class_method :deletable_paths
+
+      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
+    end
+  end
+end

data/lib/wheneverd/systemd/unit_lister.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Systemd
+    # Lists previously generated unit file paths for a given identifier.
+    class UnitLister
+      DEFAULT_UNIT_DIR = UnitWriter::DEFAULT_UNIT_DIR
+
+      # @param identifier [String]
+      # @param unit_dir [String]
+      # @return [Array<String>] unit file paths
+      def self.list(identifier:, unit_dir: DEFAULT_UNIT_DIR)
+        dest_dir = File.expand_path(unit_dir.to_s)
+        return [] unless Dir.exist?(dest_dir)
+
+        unit_paths(dest_dir, basename_pattern(identifier))
+      end
+
+      def self.unit_paths(dest_dir, pattern)
+        Dir.children(dest_dir).sort.filter_map do |basename|
+          next unless pattern.match?(basename)
+
+          path = File.join(dest_dir, basename)
+          next unless File.file?(path)
+          next unless generated_marker?(path)
+
+          path
+        end
+      end
+      private_class_method :unit_paths
+
+      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
+    end
+  end
+end

data/lib/wheneverd/systemd/unit_namer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Wheneverd
+  module Systemd
+    # Computes stable unit IDs for jobs so units keep names across schedule reordering.
+    class UnitNamer
+      def self.stable_ids_for(schedule)
+        signatures = signatures_for(schedule)
+        counts_by_signature = signatures.tally
+        occurrences_by_signature = Hash.new(0)
+
+        signatures.map do |sig|
+          disambiguate(stable_id_for(sig), sig, counts_by_signature, occurrences_by_signature)
+        end
+      end
+
+      def self.signatures_for(schedule)
+        schedule.entries.flat_map do |entry|
+          entry.jobs.map { |job| signature(entry.trigger, job) }
+        end
+      end
+      private_class_method :signatures_for
+
+      def self.disambiguate(stable, signature, counts_by_signature, occurrences_by_signature)
+        return stable if counts_by_signature.fetch(signature) == 1
+
+        occurrences_by_signature[signature] += 1
+        "#{stable}-#{occurrences_by_signature.fetch(signature)}"
+      end
+      private_class_method :disambiguate
+
+      def self.signature(trigger, job)
+        [trigger_signature(trigger), job_signature(job)].join("\n")
+      end
+      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
+          raise ArgumentError, "Unsupported trigger type: #{trigger.class}"
+        end
+      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
+      end
+      private_class_method :job_signature
+
+      def self.stable_id_for(signature)
+        Digest::SHA256.hexdigest(signature).slice(0, 12)
+      end
+      private_class_method :stable_id_for
+    end
+  end
+end

data/lib/wheneverd/systemd/unit_writer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+module Wheneverd
+  module Systemd
+    # Writes rendered systemd units to a target directory (defaulting to the user unit dir).
+    class UnitWriter
+      DEFAULT_UNIT_DIR = File.join(Dir.home, ".config", "systemd", "user").freeze
+
+      # @param units [Array<Wheneverd::Systemd::Unit>]
+      # @param identifier [String, nil] required when pruning
+      # @param unit_dir [String]
+      # @param dry_run [Boolean] return paths without writing
+      # @param prune [Boolean] delete previously generated units for `identifier` not in `units`
+      # @return [Array<String>] destination paths
+      def self.write(units, unit_dir: DEFAULT_UNIT_DIR, dry_run: false, prune: false,
+                     identifier: nil)
+        validate_units!(units)
+        dest_dir = File.expand_path(unit_dir.to_s)
+        paths = destination_paths(units, dest_dir)
+        return paths if dry_run
+
+        write_units(units, paths, dest_dir, prune: prune, identifier: identifier)
+        paths
+      end
+
+      def self.validate_units!(units)
+        raise ArgumentError, "units must be an Array" unless units.is_a?(Array)
+      end
+      private_class_method :validate_units!
+
+      def self.destination_paths(units, dest_dir)
+        units.map { |unit| File.join(dest_dir, unit.path_basename) }
+      end
+      private_class_method :destination_paths
+
+      def self.write_units(units, paths, dest_dir, prune:, identifier:)
+        FileUtils.mkdir_p(dest_dir)
+        if prune
+          prune_stale_units(
+            dest_dir,
+            identifier: identifier,
+            keep_basenames: units.map(&:path_basename)
+          )
+        end
+        write_unit_files(units, paths, dest_dir)
+      end
+      private_class_method :write_units
+
+      def self.write_unit_files(units, paths, dest_dir)
+        units.each_with_index do |unit, idx|
+          atomic_write(paths.fetch(idx), unit.contents.to_s, dir: dest_dir)
+        end
+      end
+      private_class_method :write_unit_files
+
+      def self.prune_stale_units(dest_dir, identifier:, keep_basenames:)
+        raise ArgumentError, "identifier is required when prune is true" if identifier.nil?
+
+        keep = keep_basenames.to_h { |basename| [basename, true] }
+        stale_unit_paths(dest_dir, identifier: identifier, keep: keep).each do |path|
+          FileUtils.rm_f(path)
+        end
+      end
+      private_class_method :prune_stale_units
+
+      def self.stale_unit_paths(dest_dir, identifier:, keep:)
+        pattern = basename_pattern(identifier)
+        Dir.children(dest_dir).filter_map do |basename|
+          next if keep.key?(basename)
+
+          path = File.join(dest_dir, basename)
+          next unless stale_unit_path?(basename, path, pattern)
+
+          path
+        end
+      end
+      private_class_method :stale_unit_paths
+
+      def self.stale_unit_path?(basename, path, pattern)
+        return false unless pattern.match?(basename)
+        return false unless File.file?(path)
+
+        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)
+        tmp.write(contents)
+        tmp.flush
+        tmp.fsync
+        tmp.close
+
+        File.rename(tmp.path, dest_path)
+      ensure
+        tmp&.close
+        tmp&.unlink
+      end
+      private_class_method :atomic_write
+    end
+  end
+end

data/lib/wheneverd/trigger/boot.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Trigger
+    # A boot trigger, rendered as `OnBootSec=`.
+    class Boot
+      # @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
+      end
+
+      # @return [Array<String>] systemd `[Timer]` lines for this trigger
+      def systemd_timer_lines
+        ["OnBootSec=#{seconds}"]
+      end
+    end
+  end
+end

data/lib/wheneverd/trigger/calendar.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Trigger
+    # A calendar trigger, rendered as one or more `OnCalendar=` lines.
+    class Calendar
+      # @return [Array<String>] calendar specs (already in `systemd` OnCalendar format)
+      attr_reader :on_calendar
+
+      # @param on_calendar [Array<String>] non-empty calendar specs
+      def initialize(on_calendar:)
+        unless on_calendar.is_a?(Array) && !on_calendar.empty? &&
+               on_calendar.all? { |v| v.is_a?(String) && !v.strip.empty? }
+          raise ArgumentError, "on_calendar must be a non-empty Array of non-empty Strings"
+        end
+
+        @on_calendar = on_calendar.map(&:strip)
+      end
+
+      # @return [Array<String>] systemd `[Timer]` lines for this trigger
+      def systemd_timer_lines
+        on_calendar.map { |spec| "OnCalendar=#{spec}" }
+      end
+    end
+  end
+end

data/lib/wheneverd/trigger/interval.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module Trigger
+    # A monotonic interval trigger for `systemd` timers.
+    #
+    # We emit both:
+    # - `OnActiveSec=` to schedule the first run relative to timer activation.
+    # - `OnUnitActiveSec=` to schedule subsequent runs relative to the last run.
+    class Interval
+      # @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
+      end
+
+      # @return [Array<String>] systemd `[Timer]` lines for this trigger
+      def systemd_timer_lines
+        ["OnActiveSec=#{seconds}", "OnUnitActiveSec=#{seconds}"]
+      end
+    end
+  end
+end

data/lib/wheneverd/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Gem version.
+  VERSION = "0.1.0"
+end

data/lib/wheneverd.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "wheneverd/version"
+
+module Wheneverd
+  # Top-level namespace for `wheneverd`.
+  #
+  # This gem loads a Ruby schedule DSL (similar to the `whenever` gem), then renders the result into
+  # `systemd` timer + service units. The main entrypoints are:
+  #
+  # - {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/duration"
+require_relative "wheneverd/interval"
+require_relative "wheneverd/core_ext/numeric_duration"
+require_relative "wheneverd/job/command"
+require_relative "wheneverd/trigger/interval"
+require_relative "wheneverd/trigger/calendar"
+require_relative "wheneverd/trigger/boot"
+require_relative "wheneverd/entry"
+require_relative "wheneverd/schedule"
+require_relative "wheneverd/dsl/errors"
+require_relative "wheneverd/dsl/at_normalizer"
+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/time_parser"
+require_relative "wheneverd/systemd/cron_parser"
+require_relative "wheneverd/systemd/calendar_spec"
+require_relative "wheneverd/systemd/unit_namer"
+require_relative "wheneverd/systemd/renderer"
+require_relative "wheneverd/systemd/systemctl"
+require_relative "wheneverd/systemd/unit_writer"
+require_relative "wheneverd/systemd/unit_deleter"
+require_relative "wheneverd/systemd/unit_lister"

data/test/cli_activate_test.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/cli_test_helpers"
+
+class CLIActivateSuccessTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_exits_zero
+    with_inited_project_dir do
+      status, _out, _err, _calls = run_activate_with_capture3_stub
+      assert_equal 0, status
+    end
+  end
+
+  def test_prints_timer_units
+    with_inited_project_dir do
+      status, out, err, _calls = run_activate_with_capture3_stub
+      assert_cli_success(status, err)
+      assert_includes out, expected_timer_basenames.fetch(0)
+    end
+  end
+
+  def test_runs_daemon_reload
+    with_inited_project_dir do
+      status, _out, err, calls = run_activate_with_capture3_stub
+      assert_cli_success(status, err)
+      assert_systemctl_call(calls, 0, SYSTEMCTL_USER_PREFIX + ["daemon-reload"])
+    end
+  end
+
+  def test_runs_enable_now
+    with_inited_project_dir do
+      status, _out, err, calls = run_activate_with_capture3_stub
+      assert_cli_success(status, err)
+      assert_systemctl_call_starts_with(calls, 1, SYSTEMCTL_USER_PREFIX + ["enable", "--now"],
+                                        includes: expected_timer_basenames)
+    end
+  end
+end
+
+class CLIActivateScheduleMissingTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_exits_one
+    with_project_dir do
+      status, _out, _err = run_cli(["activate"])
+      assert_equal 1, status
+    end
+  end
+
+  def test_prints_error_message
+    with_project_dir do
+      _status, out, err = run_cli(["activate"])
+      assert_equal "", out
+      assert_includes err, "Schedule file not found"
+    end
+  end
+end
+
+class CLIActivateEmptyScheduleTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_makes_no_systemctl_calls
+    with_project_dir do
+      write_empty_schedule
+      status, _out, err, calls = run_activate_with_capture3_stub
+      assert_cli_success(status, err)
+      assert_equal [], calls
+    end
+  end
+
+  def test_prints_nothing
+    with_project_dir do
+      write_empty_schedule
+      status, out, err, _calls = run_activate_with_capture3_stub
+      assert_cli_success(status, err)
+      assert_equal "", out
+    end
+  end
+end
+
+class CLIActivateSystemctlFailureTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_exits_one
+    with_inited_project_dir do
+      status, _out, _err, _calls = run_activate_with_capture3_stub(exitstatus: 1,
+                                                                   stderr: "no bus\n")
+      assert_equal 1, status
+    end
+  end
+
+  def test_prints_systemctl_failed
+    with_inited_project_dir do
+      _status, _out, err, _calls = run_activate_with_capture3_stub(exitstatus: 1,
+                                                                   stderr: "no bus\n")
+      assert_includes err, "systemctl failed"
+    end
+  end
+
+  def test_only_calls_daemon_reload
+    with_inited_project_dir do
+      _status, _out, _err, calls = run_activate_with_capture3_stub(exitstatus: 1,
+                                                                   stderr: "no bus\n")
+      assert_equal 1, calls.length
+      assert_systemctl_call(calls, 0, SYSTEMCTL_USER_PREFIX + ["daemon-reload"])
+    end
+  end
+end

data/test/cli_current_test.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/cli_test_helpers"
+
+class CLICurrentInstalledUnitsTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_exits_zero
+    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
+      status, _out, err = run_cli(["current", "--identifier", "demo", "--unit-dir", unit_dir])
+      assert_cli_success(status, err)
+    end
+  end
+
+  def test_includes_header_for_generated_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
+      status, out, err = run_cli(["current", "--identifier", "demo", "--unit-dir", unit_dir])
+      assert_cli_success(status, err)
+      assert_includes out, "# #{File.join(unit_dir, expected_timer_basenames.fetch(0))}"
+    end
+  end
+
+  def test_includes_generated_marker
+    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
+      status, out, err = run_cli(["current", "--identifier", "demo", "--unit-dir", unit_dir])
+      assert_cli_success(status, err)
+      assert_includes out, Wheneverd::Systemd::Renderer::MARKER_PREFIX
+    end
+  end
+
+  def test_excludes_units_without_generated_marker
+    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
+      File.write(File.join(unit_dir, "wheneverd-demo-000000000000.timer"), "# not generated\n")
+      status, out, err = run_cli(["current", "--identifier", "demo", "--unit-dir", unit_dir])
+      assert_cli_success(status, err)
+      refute_includes out, "wheneverd-demo-000000000000.timer"
+    end
+  end
+end
+
+class CLICurrentInvalidIdentifierTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_exits_one
+    with_project_dir do |project_dir|
+      unit_dir = File.join(project_dir, "tmp_units")
+      FileUtils.mkdir_p(unit_dir)
+      status, _out, _err = run_cli(["current", "--identifier", "!!!", "--unit-dir", unit_dir])
+      assert_equal 1, status
+    end
+  end
+
+  def test_prints_error_message
+    with_project_dir do |project_dir|
+      unit_dir = File.join(project_dir, "tmp_units")
+      FileUtils.mkdir_p(unit_dir)
+      _status, out, err = run_cli(["current", "--identifier", "!!!", "--unit-dir", unit_dir])
+      assert_equal "", out
+      assert_includes err, "identifier must include at least one alphanumeric character"
+    end
+  end
+end
+
+class CLICurrentEmptyUnitDirTest < Minitest::Test
+  include CLITestHelpers
+
+  def test_prints_nothing_when_unit_dir_missing
+    with_project_dir do |project_dir|
+      unit_dir = File.join(project_dir, "missing_units")
+      status, out, err = run_cli(["current", "--identifier", "demo", "--unit-dir", unit_dir])
+      assert_cli_success(status, err)
+      assert_equal "", out
+    end
+  end
+
+  def test_prints_nothing_when_no_units_installed
+    with_project_dir do |project_dir|
+      unit_dir = File.join(project_dir, "empty_units")
+      FileUtils.mkdir_p(unit_dir)
+      status, out, err = run_cli(["current", "--identifier", "demo", "--unit-dir", unit_dir])
+      assert_cli_success(status, err)
+      assert_equal "", out
+    end
+  end
+end