wheneverd 0.1.0

data/Rakefile

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+  BUNDLER_SETUP_AVAILABLE = true
+rescue LoadError
+  BUNDLER_SETUP_AVAILABLE = false
+end
+
+require "json"
+require "open3"
+require "rake/testtask"
+
+begin
+  require "yard"
+  require "yard/rake/yardoc_task"
+  YARD_AVAILABLE = true
+rescue LoadError
+  YARD_AVAILABLE = false
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.pattern = "test/**/*_test.rb"
+  t.ruby_opts << "-rbundler/setup" if BUNDLER_SETUP_AVAILABLE
+end
+
+task default: :ci
+
+def rubocop_corrected_count(output)
+  output.scan(/(\d+)\s+offenses?\s+corrected\b/i).flatten.sum(&:to_i)
+end
+
+def run_and_echo(command)
+  output, status = Open3.capture2e(command)
+  $stdout.print(output)
+  [output, status]
+end
+
+def announce(message)
+  puts("\n==> #{message}")
+end
+
+CI_STATE = {
+  rubocop: { ran: false, reran: false, corrected: 0, success: nil },
+  test: { ran: false, success: nil },
+  coverage: { line: nil, minimum: nil }
+}.freeze
+
+def record_ci(section, key, value)
+  CI_STATE.fetch(section)[key] = value
+end
+
+def ci_status_label(value)
+  case value
+  when true
+    "OK"
+  when false
+    "FAILED"
+  else
+    "SKIPPED"
+  end
+end
+
+def read_line_coverage
+  coverage_path = File.expand_path("coverage/.last_run.json", __dir__)
+  return nil unless File.exist?(coverage_path)
+
+  JSON.parse(File.read(coverage_path)).dig("result", "line")
+rescue JSON::ParserError
+  nil
+end
+
+def print_ci_rubocop_summary
+  rubocop = CI_STATE.fetch(:rubocop)
+  details = []
+  details << "corrected #{rubocop[:corrected]}" if rubocop[:ran]
+  details << "reran" if rubocop[:reran]
+  suffix = details.any? ? " (#{details.join(', ')})" : ""
+  puts("RuboCop: #{ci_status_label(rubocop[:success])}#{suffix}")
+end
+
+def print_ci_test_summary
+  test = CI_STATE.fetch(:test)
+  puts("Tests: #{ci_status_label(test[:success])}")
+end
+
+def print_ci_coverage_summary
+  coverage = CI_STATE.fetch(:coverage)
+  line = coverage[:line]
+  min = coverage[:minimum]
+
+  unless line
+    puts("Coverage: (no data)")
+    return
+  end
+
+  min_label = min ? format(" (min %<min>d%%)", min: min) : ""
+  puts(format("Coverage: %<line>.1f%%%<min_label>s", line: line, min_label: min_label))
+end
+
+def print_ci_summary
+  announce("Summary")
+  print_ci_rubocop_summary
+  print_ci_test_summary
+  print_ci_coverage_summary
+end
+
+def init_rubocop_state
+  record_ci(:rubocop, :ran, true)
+  record_ci(:rubocop, :reran, false)
+end
+
+def run_rubocop_pass(command, label)
+  announce(label)
+  run_and_echo(command)
+end
+
+def record_rubocop_corrections(output)
+  corrected = rubocop_corrected_count(output)
+  record_ci(:rubocop, :corrected, corrected)
+  corrected
+end
+
+def rerun_rubocop_if_corrected(command, corrected)
+  return nil unless corrected.positive?
+
+  announce("Re-running RuboCop (-A) after corrections")
+  record_ci(:rubocop, :reran, true)
+  _output, status = run_and_echo(command)
+  status
+end
+
+def finalize_rubocop(status)
+  record_ci(:rubocop, :success, status.success?)
+  abort("RuboCop failed") unless status.success?
+end
+
+def run_ci_rubocop
+  command = "bundle exec rubocop -A ."
+  init_rubocop_state
+  output, status = run_rubocop_pass(command, "Running RuboCop (-A)")
+  corrected = record_rubocop_corrections(output)
+  status = rerun_rubocop_if_corrected(command, corrected) || status
+  finalize_rubocop(status)
+rescue Errno::ENOENT => e
+  abort(e.message)
+end
+
+def run_ci_tests
+  announce("Running tests (Minitest + SimpleCov)")
+
+  record_ci(:test, :ran, true)
+  record_ci(:coverage, :minimum, ENV.fetch("MINIMUM_COVERAGE", "100").to_i)
+
+  Rake::Task["test"].invoke
+  record_ci(:test, :success, true)
+rescue SystemExit, StandardError
+  record_ci(:test, :success, false)
+  raise
+ensure
+  record_ci(:coverage, :line, read_line_coverage)
+end
+
+namespace :ci do
+  desc "Run RuboCop with autocorrect (-A) (twice if corrections were made)"
+  task :rubocop do
+    run_ci_rubocop
+  end
+
+  desc "Run tests (with coverage)"
+  task :test do
+    run_ci_tests
+  end
+
+  desc "Print a summary of the last CI run"
+  task :summary do
+    record_ci(:coverage, :minimum, ENV.fetch("MINIMUM_COVERAGE", "100").to_i)
+    record_ci(:coverage, :line, read_line_coverage)
+    print_ci_summary
+  end
+end
+
+desc "Run RuboCop and tests (with coverage)"
+task :ci do
+  Rake::Task["ci:rubocop"].invoke
+  Rake::Task["ci:test"].invoke
+ensure
+  print_ci_summary
+end
+
+if YARD_AVAILABLE
+  YARD::Rake::YardocTask.new(:yard)
+  desc "Alias for `rake yard`"
+  task doc: :yard
+end

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "wheneverd"
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bundle install
+

data/exe/wheneverd

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "wheneverd/cli"
+
+exit(Wheneverd::CLI.run || 0)

data/lib/wheneverd/cli/activate.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd activate` (enable + start timers via `systemctl --user`).
+  class CLI::Activate < CLI
+    def execute
+      timer_units = timer_unit_basenames
+      return 0 if timer_units.empty?
+
+      Wheneverd::Systemd::Systemctl.run("daemon-reload")
+      Wheneverd::Systemd::Systemctl.run("enable", "--now", *timer_units)
+
+      timer_units.each { |unit| puts unit }
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+  end
+end

data/lib/wheneverd/cli/current.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd current` (print installed unit files from disk).
+  class CLI::Current < CLI
+    def execute
+      paths = Wheneverd::Systemd::UnitLister.list(identifier: identifier_value, unit_dir: unit_dir)
+      print_unit_files(paths)
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    def print_unit_files(paths)
+      paths.each_with_index do |path, idx|
+        puts "# #{path}"
+        puts File.read(path)
+        puts "" if idx < paths.length - 1
+      end
+    end
+  end
+end

data/lib/wheneverd/cli/deactivate.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd deactivate` (stop + disable timers via `systemctl --user`).
+  class CLI::Deactivate < CLI
+    def execute
+      timer_units = timer_unit_basenames
+      return 0 if timer_units.empty?
+
+      Wheneverd::Systemd::Systemctl.run("stop", *timer_units)
+      Wheneverd::Systemd::Systemctl.run("disable", *timer_units)
+
+      timer_units.each { |unit| puts unit }
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+  end
+end

data/lib/wheneverd/cli/delete.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd delete` (delete previously generated units for the identifier).
+  class CLI::Delete < CLI
+    option "--dry-run", :flag, "Print paths only; do not delete"
+
+    def execute
+      paths = Wheneverd::Systemd::UnitDeleter.delete(
+        identifier: identifier_value,
+        unit_dir: unit_dir,
+        dry_run: dry_run?
+      )
+      paths.each { |p| puts p }
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+  end
+end

data/lib/wheneverd/cli/help.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd help` and the default command.
+  #
+  # The `--version` flag is supported here to match the common "help-or-version" UX.
+  class CLI::Help < CLI
+    def execute
+      if version?
+        puts Wheneverd::VERSION
+        return 0
+      end
+
+      warn Wheneverd::CLI.help(invocation_path.split.first)
+      1
+    end
+  end
+end

data/lib/wheneverd/cli/init.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Wheneverd
+  # Implements `wheneverd init` to create a schedule template file.
+  class CLI::Init < CLI
+    option "--force", :flag, "Overwrite existing file"
+
+    TEMPLATE = <<~RUBY
+      # frozen_string_literal: true
+
+      # This file is evaluated as Ruby.
+      #
+      # Supported `every` period forms:
+      # - interval strings: "5m", "1h", "2d"
+      # - duration objects: 1.day, 2.hours
+      # - symbol shortcuts: :hour, :day, :month, :year
+      # - day selectors: :monday..:sunday, :weekday, :weekend (multiple day symbols supported)
+      # - cron strings (5 fields): "0 0 27-31 * *"
+
+      every "5m" do
+        command "echo hello"
+      end
+
+      every 1.day, at: "4:30 am" do
+        command "echo four_thirty"
+      end
+
+      every 1.day, at: ["4:30 am", "6:00 pm"] do
+        command "echo twice_daily"
+      end
+
+      every :hour do
+        command "echo hourly"
+      end
+
+      every :sunday, at: "12pm" do
+        command "echo weekly"
+      end
+
+      every :tuesday, :wednesday, at: "12pm" do
+        command "echo midweek"
+      end
+
+      every "0 0 27-31 * *" do
+        command "echo raw_cron"
+      end
+    RUBY
+
+    def execute
+      path = File.expand_path(schedule)
+      return 1 if refuse_overwrite_without_force?(path)
+
+      existed = write_template(path)
+      puts "#{existed ? 'Overwrote' : 'Wrote'} schedule template to #{path}"
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    private
+
+    def refuse_overwrite_without_force?(path)
+      return false unless File.exist?(path) && !force?
+
+      warn "#{path}: already exists (use --force to overwrite)"
+      true
+    end
+
+    def write_template(path)
+      existed = File.exist?(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, TEMPLATE)
+      existed
+    end
+  end
+end

data/lib/wheneverd/cli/reload.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd reload` (write units, reload daemon, restart timers).
+  class CLI::Reload < CLI
+    option "--[no-]prune", :flag,
+           "Prune previously generated units for the identifier (default: enabled)",
+           default: true
+
+    def execute
+      paths, timer_units = write_units_and_timer_basenames
+      return 0 if timer_units.empty?
+
+      reload_systemd(timer_units)
+
+      paths.each { |path| puts path }
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    private
+
+    def write_units_and_timer_basenames
+      units = render_units
+      paths = Wheneverd::Systemd::UnitWriter.write(
+        units,
+        unit_dir: unit_dir,
+        prune: prune?,
+        identifier: identifier_value
+      )
+      [paths, timer_unit_basenames(units)]
+    end
+
+    def reload_systemd(timer_units)
+      Wheneverd::Systemd::Systemctl.run("daemon-reload")
+      Wheneverd::Systemd::Systemctl.run("restart", *timer_units)
+    end
+  end
+end

data/lib/wheneverd/cli/show.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd show` (render units to stdout).
+  class CLI::Show < CLI
+    def execute
+      schedule_obj = load_schedule
+      units = Wheneverd::Systemd::Renderer.render(schedule_obj, identifier: identifier_value)
+      print_units(units)
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    def print_units(units)
+      units.each_with_index do |unit, idx|
+        puts "# #{unit.path_basename}"
+        puts unit.contents
+        puts "" if idx < units.length - 1
+      end
+    end
+  end
+end

data/lib/wheneverd/cli/write.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd write` (write rendered units to disk).
+  class CLI::Write < CLI
+    option "--dry-run", :flag, "Print paths only; do not write"
+    option "--[no-]prune", :flag,
+           "Prune previously generated units for the identifier (default: enabled)",
+           default: true
+
+    def execute
+      write_paths.each { |path| puts path }
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    private
+
+    def write_paths
+      schedule_obj = load_schedule
+      units = Wheneverd::Systemd::Renderer.render(schedule_obj, identifier: identifier_value)
+      Wheneverd::Systemd::UnitWriter.write(
+        units,
+        unit_dir: unit_dir,
+        dry_run: dry_run?,
+        prune: prune?,
+        identifier: identifier_value
+      )
+    end
+  end
+end

data/lib/wheneverd/cli.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "clamp"
+require_relative "../wheneverd"
+
+module Wheneverd
+  # Command-line interface for `wheneverd`.
+  #
+  # This class defines global options and shared helpers used by each subcommand.
+  class CLI < Clamp::Command
+    option ["-v", "--version"], :flag, "Print version"
+    option "--verbose", :flag, "Verbose output"
+    option "--schedule", "PATH", "Schedule file path", default: "config/schedule.rb"
+    option "--identifier", "NAME", "Unit identifier (defaults to current directory name)"
+    option "--unit-dir", "PATH", "systemd unit directory",
+           default: Wheneverd::Systemd::UnitWriter::DEFAULT_UNIT_DIR
+
+    # @return [String] the identifier used for unit file names
+    def identifier_value
+      identifier || File.basename(Dir.pwd)
+    end
+
+    # Load the configured schedule file.
+    #
+    # @return [Wheneverd::Schedule]
+    def load_schedule
+      path = File.expand_path(schedule)
+      unless File.file?(path)
+        raise Wheneverd::DSL::LoadError.new("Schedule file not found: #{path}", path: path)
+      end
+
+      Wheneverd::DSL::Loader.load_file(path)
+    end
+
+    # Print an error message and return a non-zero exit status.
+    #
+    # @param error [Exception]
+    # @return [Integer]
+    def handle_error(error)
+      warn error.message
+      warn error.full_message if verbose?
+      1
+    end
+
+    # Render schedule units for this invocation.
+    #
+    # @return [Array<Wheneverd::Systemd::Unit>]
+    def render_units
+      schedule_obj = load_schedule
+      Wheneverd::Systemd::Renderer.render(schedule_obj, identifier: identifier_value)
+    end
+
+    # @param units [Array<Wheneverd::Systemd::Unit>]
+    # @return [Array<String>] timer unit basenames
+    def timer_unit_basenames(units = render_units)
+      units.select { |unit| unit.kind == :timer }.map(&:path_basename).uniq
+    end
+
+    private :render_units, :timer_unit_basenames
+  end
+end
+
+require_relative "cli/help"
+require_relative "cli/init"
+require_relative "cli/show"
+require_relative "cli/write"
+require_relative "cli/delete"
+require_relative "cli/activate"
+require_relative "cli/deactivate"
+require_relative "cli/reload"
+require_relative "cli/current"
+
+module Wheneverd
+  class CLI
+    self.default_subcommand = "help"
+
+    subcommand "help", "Show help", Wheneverd::CLI::Help
+    subcommand "init", "Create a schedule template", Wheneverd::CLI::Init
+    subcommand "show", "Render units to stdout", Wheneverd::CLI::Show
+    subcommand "write", "Write units to disk", Wheneverd::CLI::Write
+    subcommand "delete", "Delete units from disk", Wheneverd::CLI::Delete
+    subcommand "activate", "Enable and start timers via systemctl --user", Wheneverd::CLI::Activate
+    subcommand "deactivate", "Stop and disable timers via systemctl --user", Wheneverd::CLI::Deactivate
+    subcommand "reload", "Write units, reload daemon, restart timers", Wheneverd::CLI::Reload
+    subcommand "current", "Show installed units from disk", Wheneverd::CLI::Current
+  end
+end

data/lib/wheneverd/core_ext/numeric_duration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module CoreExt
+    # `Numeric` helpers for creating {Wheneverd::Duration} values.
+    #
+    # @example
+    #   every 5.minutes do
+    #     command "echo hello"
+    #   end
+    module NumericDuration
+      def second
+        Wheneverd::Duration.new(to_duration_seconds(1))
+      end
+      alias seconds second
+
+      def minute
+        Wheneverd::Duration.new(to_duration_seconds(60))
+      end
+      alias minutes minute
+
+      def hour
+        Wheneverd::Duration.new(to_duration_seconds(60 * 60))
+      end
+      alias hours hour
+
+      def day
+        Wheneverd::Duration.new(to_duration_seconds(60 * 60 * 24))
+      end
+      alias days day
+
+      def week
+        Wheneverd::Duration.new(to_duration_seconds(60 * 60 * 24 * 7))
+      end
+      alias weeks week
+
+      private
+
+      def to_duration_seconds(multiplier)
+        unless is_a?(Integer)
+          raise ArgumentError, "Duration helpers require an Integer receiver (got #{self.class})"
+        end
+
+        self * multiplier
+      end
+    end
+  end
+end
+
+# Extend Ruby's `Numeric` with duration helpers.
+#
+# @!parse
+#   class ::Numeric
+#     include Wheneverd::CoreExt::NumericDuration
+#   end
+Numeric.include(Wheneverd::CoreExt::NumericDuration)

data/lib/wheneverd/dsl/at_normalizer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    # Validates and normalizes the `at:` option from the schedule DSL.
+    #
+    # `at:` can be a single string (e.g. `"4:30 am"`) or an array of strings (multiple run times).
+    module AtNormalizer
+      # @param at [String, Array<String>, nil]
+      # @param path [String] schedule path for error reporting
+      # @return [Array<String>] normalized time strings (not parsed)
+      def self.normalize(at, path:)
+        return [] if at.nil?
+
+        return [normalize_string(at, path: path)] if at.is_a?(String)
+
+        return normalize_array(at, path: path) if at.is_a?(Array)
+
+        raise InvalidAtError.new("at: must be a String or an Array of Strings", path: path)
+      end
+
+      def self.normalize_string(value, path:)
+        at_str = value.strip
+        raise InvalidAtError.new("at: must not be empty", path: path) if at_str.empty?
+
+        at_str
+      end
+      private_class_method :normalize_string
+
+      def self.normalize_array(values, path:)
+        times = values.map do |v|
+          unless v.is_a?(String)
+            raise InvalidAtError.new("at: must be a String or an Array of Strings", path: path)
+          end
+
+          v.strip
+        end
+
+        if times.empty? || times.any?(&:empty?)
+          raise InvalidAtError.new("at: must not be empty", path: path)
+        end
+
+        times
+      end
+      private_class_method :normalize_array
+    end
+  end
+end