wheneverd 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ef1858fab03a38b36da00bf0093d4025762263ca868d05a78c1876d8aeb6441
-  data.tar.gz: 539fbeec1db7023059767501172d7337da50a966e0727c29879f88cd81770303
+  metadata.gz: c4d813e1e0ad0b44e738d4ba42767b5fb490dcaf5a7883328c91faa2ab726305
+  data.tar.gz: 1185929834d9f12adb4afd8a1bc2d1a4a366d99b260afe1d075a1ca58dc6dc26
 SHA512:
-  metadata.gz: 2656962166f254b2d48f94d23329db78a16964eda9c164457c5586b4dabfa095077b75372b94da9f9cad38862d5548be15ba7b2567cef5d2fb2cdc3cb94d4984
-  data.tar.gz: a06b649a079b18fd3f321bc818e322d3284c98d96bfbabaf43244b4d604193b395186d31548efdf2296fe12509f47e665f1cdf96f47e2af25512b3eae53ba20d
+  metadata.gz: ed43947461d6e8dadf5825c8075e08816535c42202a9764c7b57d1fb4a7948a0dbfe1ff57e13cc710a853efa6910f802b93774b239736ed30bcec145812c08fc
+  data.tar.gz: 4406adc4f70afde1953cd8ea82979d2c37bf6b096232930724f2537b04d5ae187437fafa29215163ebd985eb132b89c7ee990497ba2cdb70617166b5d88114ee

data/CHANGELOG.md

@@ -5,6 +5,12 @@ On release, entries are moved into `## x.y.z` sections that match the gem versio
 
 ## Unreleased
 
+## 0.3.0
+
+- Schedule DSL: `command` accepts argv arrays, adds a `shell` helper for `/bin/bash -lc`, and `wheneverd init` includes examples.
+- Adds `wheneverd status` (show `systemctl --user list-timers` + `systemctl --user status` for installed timers) and `wheneverd diff` (diff rendered units vs files on disk).
+- Adds `wheneverd validate` to validate rendered `OnCalendar=` values via `systemd-analyze calendar` (and with `--verify`, runs `systemd-analyze --user verify` on temporary unit files).
+
 ## 0.2.1
 
 - Removes an unused filtering metadata keyword argument from the schedule DSL.

data/FEATURE_SUMMARY.md

@@ -12,13 +12,22 @@ It complements [`CHANGELOG.md`](CHANGELOG.md) by staying high-level and focusing
 
 ## Unreleased
 
+## 0.3.0
+
+- Schedule DSL: `command` accepts argv arrays, adds a `shell` helper for `/bin/bash -lc`, and `wheneverd init` includes examples.
+- Adds `wheneverd status` (show `systemctl --user list-timers` + `systemctl --user status` for installed timers) and `wheneverd diff` (diff rendered units vs files on disk).
+- Adds `wheneverd validate` to validate rendered `OnCalendar=` values via `systemd-analyze calendar` (and with `--verify`, runs `systemd-analyze --user verify` on temporary unit files).
+
 ## 0.2.1
 
-- Adds `wheneverd linger enable|disable|status` for managing systemd user lingering via `loginctl`.
 - Removes an unused filtering metadata keyword argument from the schedule DSL.
 
 ## 0.2.0
 
+- Adds `wheneverd linger enable|disable|status` for managing systemd user lingering via `loginctl`.
+
+## 0.1.0
+
 - The `wheneverd` CLI is implemented using Clamp (`--help`, usage errors in `ERROR: ...` format, `--verbose` for details).
 - The gem includes a small “whenever-like” domain model (interval parsing, durations, triggers, schedules).
 - The gem can load a Ruby schedule DSL file via `Wheneverd::DSL::Loader.load_file`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    wheneverd (0.2.0)
+    wheneverd (0.3.0)
       clamp (~> 1.3)
 
 GEM
@@ -122,7 +122,7 @@ CHECKSUMS
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
-  wheneverd (0.2.0)
+  wheneverd (0.3.0)
   yard (0.9.38) sha256=721fb82afb10532aa49860655f6cc2eaa7130889df291b052e1e6b268283010f
 
 BUNDLED WITH

data/README.md

@@ -34,6 +34,9 @@ bundle install
 wheneverd --help
 wheneverd init
 wheneverd show
+wheneverd status
+wheneverd diff
+wheneverd validate
 wheneverd write
 wheneverd delete
 wheneverd activate
@@ -43,6 +46,8 @@ wheneverd current
 wheneverd linger
 ```
 
+Use `wheneverd init` to create a starter `config/schedule.rb` template (including examples for `command` and `shell`).
+
 ### Minimal `config/schedule.rb` example
 
 ```ruby
@@ -137,13 +142,26 @@ end
 
 ### `command`
 
-`command("...")` appends a oneshot `ExecStart=` job. Commands must be non-empty strings.
+`command(...)` appends a oneshot `ExecStart=` job.
+
+Accepted forms:
 
-The command string is inserted into `ExecStart=` as-is (no shell wrapping). If you need shell features
-(pipes, redirects, globbing, env var expansion), wrap it yourself, for example:
+- `command("...")` (String): inserted into `ExecStart=` as-is (after stripping surrounding whitespace).
+- `command(["bin", "arg1", "arg2"])` (argv Array): formatted/escaped into a systemd-compatible `ExecStart=` string.
+
+If you need shell features (pipes, redirects, globbing, env var expansion), either wrap it yourself, or use `shell`:
 
 ```ruby
 command "/bin/bash -lc 'echo hello | sed -e s/hello/hi/'"
+command ["/bin/bash", "-lc", "echo hello | sed -e s/hello/hi/"]
+```
+
+### `shell`
+
+`shell("...")` is a convenience helper for the common `/bin/bash -lc` pattern:
+
+```ruby
+shell "echo hello | sed -e s/hello/hi/"
 ```
 
 ### `every` periods
@@ -203,11 +221,15 @@ Notes:
 - Unit basenames include a stable ID derived from the job’s trigger + command (reordering schedule blocks won’t rename units).
 - `wheneverd write` / `wheneverd reload` prune previously generated units for the identifier by default (use `--no-prune` to keep old units around).
 - `--unit-dir` controls where unit files are written/read/deleted; `activate`/`deactivate` use systemd’s unit search path.
+- `wheneverd diff` returns exit status `0` when no differences are found, and `1` when differences are found.
 
 Commands:
 
 - `wheneverd init [--schedule PATH] [--force]` writes a template schedule file.
 - `wheneverd show [--schedule PATH] [--identifier NAME]` prints rendered units to stdout.
+- `wheneverd status [--identifier NAME] [--unit-dir PATH]` prints `systemctl --user list-timers` and `systemctl --user status` for installed timers.
+- `wheneverd diff [--schedule PATH] [--identifier NAME] [--unit-dir PATH]` diffs rendered units vs unit files on disk.
+- `wheneverd validate [--schedule PATH] [--identifier NAME] [--verify]` validates rendered `OnCalendar=` values via `systemd-analyze calendar` (and with `--verify`, runs `systemd-analyze --user verify` on temporary unit files).
 - `wheneverd write [--schedule PATH] [--identifier NAME] [--unit-dir PATH] [--dry-run] [--[no-]prune]` writes units to disk (or prints paths in `--dry-run` mode).
 - `wheneverd delete [--identifier NAME] [--unit-dir PATH] [--dry-run]` deletes previously generated units for the identifier.
 - `wheneverd activate [--schedule PATH] [--identifier NAME]` runs `systemctl --user daemon-reload` and enables/starts the timers.

data/lib/wheneverd/cli/diff.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd diff` (rendered output vs files on disk).
+  #
+  # Exit statuses follow `diff` semantics:
+  # - 0: no differences
+  # - 1: differences found
+  # - 2: error
+  class CLI::Diff < CLI
+    def execute
+      diffs = unit_diffs
+      return 0 if diffs.empty?
+
+      diffs.each_with_index do |diff, idx|
+        puts "" if idx.positive?
+        puts diff
+      end
+      1
+    rescue StandardError => e
+      handle_error(e)
+      2
+    end
+
+    private
+
+    def unit_diffs
+      rendered = rendered_units_by_basename
+      installed = installed_units_by_basename
+
+      diffs = rendered.map do |basename, contents|
+        diff_for_rendered_unit(basename, contents, installed[basename])
+      end
+      diffs.concat(stale_unit_diffs(rendered: rendered, installed: installed))
+      diffs.compact
+    end
+
+    def stale_unit_diffs(rendered:, installed:)
+      (installed.keys - rendered.keys).sort.map do |basename|
+        diff_for_removed_unit(basename, installed.fetch(basename))
+      end
+    end
+
+    def rendered_units_by_basename
+      render_units.to_h { |unit| [unit.path_basename, unit.contents.to_s] }
+    end
+
+    def installed_units_by_basename
+      paths = Wheneverd::Systemd::UnitLister.list(identifier: identifier_value, unit_dir: unit_dir)
+      paths.to_h { |path| [File.basename(path), path] }
+    end
+
+    def diff_for_rendered_unit(basename, rendered_contents, installed_path)
+      return diff_for_added_unit(basename, rendered_contents) if installed_path.nil?
+
+      installed_contents = File.read(installed_path)
+      return nil if installed_contents == rendered_contents
+
+      diff_for_changed_unit(basename, installed_path, installed_contents, rendered_contents)
+    end
+
+    def diff_for_added_unit(basename, rendered_contents)
+      dest_path = File.join(File.expand_path(unit_dir.to_s), basename)
+      header = ["diff --wheneverd #{basename}", "--- /dev/null", "+++ #{dest_path}"]
+      (header + line_diff("", rendered_contents)).join("\n")
+    end
+
+    def diff_for_removed_unit(basename, installed_path)
+      header = ["diff --wheneverd #{basename}", "--- #{installed_path}", "+++ /dev/null"]
+      (header + line_diff(File.read(installed_path), "")).join("\n")
+    end
+
+    def diff_for_changed_unit(basename, installed_path, installed_contents, rendered_contents)
+      header = ["diff --wheneverd #{basename}", "--- #{installed_path}",
+                "+++ #{basename} (rendered)"]
+      (header + line_diff(installed_contents, rendered_contents)).join("\n")
+    end
+
+    def line_diff(old_contents, new_contents)
+      old_lines = old_contents.to_s.lines.map(&:chomp)
+      new_lines = new_contents.to_s.lines.map(&:chomp)
+      max = [old_lines.length, new_lines.length].max
+
+      (0...max).flat_map do |idx|
+        diff_lines_for(old_lines[idx], new_lines[idx])
+      end
+    end
+
+    def diff_lines_for(old_line, new_line)
+      return [] if old_line.nil? && new_line.nil?
+      return [" #{old_line}"] if old_line == new_line
+      return ["-#{old_line}", "+#{new_line}"] if old_line && new_line
+      return ["-#{old_line}"] if old_line
+
+      ["+#{new_line}"]
+    end
+  end
+end

data/lib/wheneverd/cli/init.rb

@@ -32,7 +32,7 @@ module Wheneverd
       end
 
       every :hour do
-        command "echo hourly"
+        command ["echo", "hello world"]
       end
 
       every :sunday, at: "12pm" do
@@ -43,6 +43,10 @@ module Wheneverd
         command "echo midweek"
       end
 
+      every :day, at: "12:15" do
+        shell "echo hello | sed -e s/hello/hi/"
+      end
+
       every "0 0 27-31 * *" do
         command "echo raw_cron"
       end

data/lib/wheneverd/cli/status.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  # Implements `wheneverd status` (show installed timer status via `systemctl --user`).
+  class CLI::Status < CLI
+    def execute
+      timer_units = installed_timer_unit_basenames
+      return 0 if timer_units.empty?
+
+      print_list_timers(timer_units)
+      print_status(timer_units)
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    private
+
+    # @return [Array<String>]
+    def installed_timer_unit_basenames
+      paths = Wheneverd::Systemd::UnitLister.list(identifier: identifier_value, unit_dir: unit_dir)
+      paths.map { |path| File.basename(path) }.grep(/\.timer\z/).uniq
+    end
+
+    def print_list_timers(timer_units)
+      stdout, = Wheneverd::Systemd::Systemctl.run("list-timers", "--all", *timer_units)
+      print stdout
+    end
+
+    def print_status(timer_units)
+      timer_units.each do |unit|
+        stdout, = Wheneverd::Systemd::Systemctl.run("status", unit)
+        print stdout
+      end
+    end
+  end
+end

data/lib/wheneverd/cli/validate.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Wheneverd
+  # Implements `wheneverd validate` (validate rendered OnCalendar values and unit files).
+  class CLI::Validate < CLI
+    option "--verify", :flag,
+           "Also run systemd-analyze --user verify (writes units to a temporary directory)"
+
+    def execute
+      units = render_units
+      validate_on_calendar(units)
+      validate_units(units) if verify?
+      0
+    rescue StandardError => e
+      handle_error(e)
+    end
+
+    private
+
+    def validate_on_calendar(units)
+      values = on_calendar_values(units)
+      if values.empty?
+        puts "No OnCalendar= values found" if verbose?
+        return
+      end
+
+      values.each do |value|
+        Wheneverd::Systemd::Analyze.calendar(value)
+        puts "OK OnCalendar=#{value}" if verbose?
+      end
+    end
+
+    def on_calendar_values(units)
+      units.select { |unit| unit.kind == :timer }
+           .flat_map { |timer| timer.contents.to_s.lines.grep(/\AOnCalendar=/) }
+           .map { |line| line.delete_prefix("OnCalendar=").strip }
+           .uniq
+    end
+
+    def validate_units(units)
+      Dir.mktmpdir("wheneverd-validate-") do |dir|
+        paths = Wheneverd::Systemd::UnitWriter.write(units, unit_dir: dir, prune: false)
+        Wheneverd::Systemd::Analyze.verify(paths, user: true)
+        puts "OK systemd-analyze --user verify" if verbose?
+      end
+    end
+  end
+end

data/lib/wheneverd/cli.rb

@@ -63,6 +63,9 @@ end
 require_relative "cli/help"
 require_relative "cli/init"
 require_relative "cli/show"
+require_relative "cli/status"
+require_relative "cli/diff"
+require_relative "cli/validate"
 require_relative "cli/write"
 require_relative "cli/delete"
 require_relative "cli/activate"
@@ -78,6 +81,9 @@ module Wheneverd
     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 "status", "Show systemctl list-timers + status for this identifier", Wheneverd::CLI::Status
+    subcommand "diff", "Diff rendered units vs files on disk", Wheneverd::CLI::Diff
+    subcommand "validate", "Validate schedule via systemd-analyze", Wheneverd::CLI::Validate
     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

data/lib/wheneverd/dsl/context.rb

@@ -5,7 +5,7 @@ module Wheneverd
     # 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`).
+    # as the schedule DSL (`every`, `command`, `shell`).
     class Context
       # @return [String] absolute schedule path
       attr_reader :path
@@ -44,21 +44,64 @@ module Wheneverd
 
       # Add a oneshot command job to the current `every` entry.
       #
-      # @param command_str [String]
+      # @example String command
+      #   command "echo hello"
+      #
+      # @example argv command
+      #   command ["echo", "hello world"]
+      #
+      # @param command_value [String, Array<String>]
       # @return [void]
-      def command(command_str)
-        unless @current_entry
-          raise LoadError.new("command() must be called inside every() block",
-                              path: path)
-        end
+      def command(command_value)
+        ensure_in_every_block!("command")
 
-        @current_entry.add_job(Wheneverd::Job::Command.new(command: command_str))
+        @current_entry.add_job(Wheneverd::Job::Command.new(command: command_value))
       rescue Wheneverd::InvalidCommandError => e
         raise LoadError.new(e.message, path: path)
       end
 
+      # Add a oneshot command job that runs via `/bin/bash -lc`.
+      #
+      # @example
+      #   shell "echo hello | sed -e s/hello/hi/"
+      #
+      # @param script [String] non-empty script to pass as `bash -lc <script>`
+      # @param shell [String] shell executable (default: "/bin/bash")
+      # @return [void]
+      def shell(script, shell: "/bin/bash")
+        ensure_in_every_block!("shell")
+        script_stripped = normalize_shell_script(script)
+        shell_executable = normalize_shell_executable(shell)
+        command([shell_executable, "-lc", script_stripped])
+      end
+
       private
 
+      def ensure_in_every_block!(name)
+        return if @current_entry
+
+        raise LoadError.new("#{name}() must be called inside every() block", path: path)
+      end
+
+      def normalize_shell_script(script)
+        unless script.is_a?(String)
+          raise LoadError.new("shell() script must be a String (got #{script.class})",
+                              path: path)
+        end
+
+        stripped = script.strip
+        raise LoadError.new("shell() script must not be empty", path: path) if stripped.empty?
+
+        stripped
+      end
+
+      def normalize_shell_executable(shell)
+        stripped = shell.to_s.strip
+        raise LoadError.new("shell() shell must not be empty", path: path) if stripped.empty?
+
+        stripped
+      end
+
       def with_current_entry(entry)
         previous_entry = @current_entry
         @current_entry = entry

data/lib/wheneverd/job/command.rb

@@ -4,25 +4,105 @@ 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:
+    # This job accepts either:
+    #
+    # - A String (inserted into `ExecStart=` as-is, after stripping surrounding whitespace), or
+    # - An argv Array (formatted/escaped into a systemd-compatible `ExecStart=` string).
+    #
+    # 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/'"
+    #
+    # @example argv form (safer argument handling)
+    #   command ["/bin/bash", "-lc", "echo hello | sed -e s/hello/hi/"]
     class Command
+      SAFE_UNQUOTED = %r{\A[A-Za-z0-9_@%+=:,./-]+\z}.freeze
+
+      # Rendered `ExecStart=` value.
+      #
       # @return [String]
       attr_reader :command
 
-      # @param command [String] non-empty command to run
+      # Original argv form (when constructed with an Array).
+      #
+      # @return [Array<String>, nil]
+      attr_reader :argv
+
+      # Stable signature used for unit naming.
+      #
+      # @return [String]
+      attr_reader :signature
+
+      # @param command [String, Array<String>] non-empty command to run
       def initialize(command:)
-        unless command.is_a?(String)
-          raise InvalidCommandError, "Command must be a String (got #{command.class})"
+        @argv = nil
+        @signature = nil
+        @command = nil
+
+        case command
+        when String then init_string(command)
+        when Array then init_argv(command)
+        else
+          raise InvalidCommandError,
+                "Command must be a String or an Array (got #{command.class})"
         end
+      end
+
+      private
+
+      def init_string(command)
+        stripped = command.strip
+        raise InvalidCommandError, "Command must not be empty" if stripped.empty?
+
+        @command = stripped
+        @signature = "command:#{@command}"
+      end
+
+      def init_argv(argv)
+        normalized = normalize_argv(argv)
+        @argv = normalized
+        @command = format_execstart(normalized)
+        @signature = ["command:argv", normalized.join("\n")].join("\n")
+      end
 
-        command_stripped = command.strip
-        raise InvalidCommandError, "Command must not be empty" if command_stripped.empty?
+      def normalize_argv(argv)
+        raise InvalidCommandError, "Command argv must not be empty" if argv.empty?
+
+        elements = argv.map { |arg| validate_argv_element(arg) }
+        elements[0] = elements[0].strip
+        raise InvalidCommandError, "Command argv executable must not be empty" if elements[0].empty?
+
+        elements
+      end
+
+      def validate_argv_element(arg)
+        unless arg.is_a?(String)
+          raise InvalidCommandError, "Command argv elements must be Strings (got #{arg.class})"
+        end
+
+        if arg.match?(/[\0\r\n]/)
+          raise InvalidCommandError,
+                "Command argv elements must not include NUL or newlines"
+        end
+
+        arg
+      end
+
+      def format_execstart(argv)
+        argv.map { |arg| format_exec_arg(arg) }.join(" ")
+      end
+
+      def format_exec_arg(arg)
+        return "\"\"" if arg.empty?
+        return arg if SAFE_UNQUOTED.match?(arg)
+
+        "\"#{escape_exec_arg(arg)}\""
+      end
 
-        @command = command_stripped
+      def escape_exec_arg(arg)
+        arg.gsub(/[\\"]/) { |m| "\\#{m}" }
       end
     end
   end

data/lib/wheneverd/systemd/analyze.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Wheneverd
+  module Systemd
+    # Thin wrapper around `systemd-analyze`.
+    class Analyze
+      DEFAULT_SYSTEMD_ANALYZE = "systemd-analyze"
+
+      # Run `systemd-analyze calendar <value>`.
+      #
+      # @param value [String] an `OnCalendar=` value
+      # @param systemd_analyze [String] path to the `systemd-analyze` executable
+      # @return [Array(String, String)] stdout and stderr
+      # @raise [Wheneverd::Systemd::SystemdAnalyzeError]
+      def self.calendar(value, systemd_analyze: DEFAULT_SYSTEMD_ANALYZE)
+        run(systemd_analyze, "calendar", value.to_s)
+      end
+
+      # Run `systemd-analyze verify` for unit files.
+      #
+      # @param paths [Array<String>] unit file paths to verify
+      # @param user [Boolean] verify user units with `--user` (default: true)
+      # @param systemd_analyze [String] path to the `systemd-analyze` executable
+      # @return [Array(String, String)] stdout and stderr
+      # @raise [Wheneverd::Systemd::SystemdAnalyzeError]
+      def self.verify(paths, user: true, systemd_analyze: DEFAULT_SYSTEMD_ANALYZE)
+        run(systemd_analyze, "verify", *Array(paths).map(&:to_s), user: user)
+      end
+
+      def self.run(systemd_analyze, *args, user: false)
+        cmd = [systemd_analyze.to_s]
+        cmd << "--user" if user
+        cmd.concat(args.flatten.map(&:to_s))
+
+        stdout, stderr, status = Open3.capture3(*cmd)
+        raise SystemdAnalyzeError, format_error(cmd, status, stdout, stderr) unless status.success?
+
+        [stdout, stderr]
+      rescue Errno::ENOENT
+        raise SystemdAnalyzeError, "systemd-analyze not found (tried: #{systemd_analyze})"
+      end
+
+      def self.format_error(cmd, status, stdout, stderr)
+        details = []
+        details << "command: #{cmd.join(' ')}"
+        details << "status: #{status.exitstatus}"
+        details << "stdout: #{stdout.strip}" unless stdout.to_s.strip.empty?
+        details << "stderr: #{stderr.strip}" unless stderr.to_s.strip.empty?
+        "systemd-analyze failed (#{details.join(', ')})"
+      end
+      private_class_method :format_error
+    end
+  end
+end

data/lib/wheneverd/systemd/errors.rb

@@ -22,5 +22,8 @@ module Wheneverd
 
     # Raised when a `loginctl` invocation fails.
     class LoginctlError < Error; end
+
+    # Raised when a `systemd-analyze` invocation fails (or `systemd-analyze` is not available).
+    class SystemdAnalyzeError < Error; end
   end
 end

data/lib/wheneverd/systemd/unit_namer.rb

@@ -53,7 +53,7 @@ module Wheneverd
       def self.job_signature(job)
         case job
         when Wheneverd::Job::Command
-          "command:#{job.command}"
+          job.signature
         else
           raise ArgumentError, "Unsupported job type: #{job.class}"
         end

data/lib/wheneverd/version.rb

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

data/lib/wheneverd.rb

@@ -35,6 +35,7 @@ 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/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

data/test/cli_validate_test.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "support/cli_test_helpers"
+
+class CLIValidateTest < Minitest::Test
+  include CLITestHelpers
+
+  DUP_HOURLY_SCHEDULE = <<~RUBY
+    # frozen_string_literal: true
+
+    every :hour do
+      command "echo a"
+    end
+
+    every :hour do
+      command "echo b"
+    end
+  RUBY
+
+  HOURLY_SCHEDULE = <<~RUBY
+    # frozen_string_literal: true
+
+    every :hour do
+      command "echo a"
+    end
+  RUBY
+
+  def test_validate_runs_systemd_analyze_calendar_for_each_unique_on_calendar
+    with_project_dir do
+      write_schedule(DUP_HOURLY_SCHEDULE)
+      status, out, err, calls = run_validate("--verbose")
+      assert_cli_success(status, err)
+      assert_includes out, "OK OnCalendar=hourly"
+      assert_equal 1, calls.length
+      assert_equal %w[systemd-analyze calendar hourly], calls.fetch(0).fetch(0)
+    end
+  end
+
+  def test_validate_prints_message_when_no_on_calendar_and_verbose
+    with_project_dir do
+      write_empty_schedule
+      status, out, err, calls = run_validate("--verbose")
+      assert_cli_success(status, err)
+      assert_includes out, "No OnCalendar= values found"
+      assert_equal [], calls
+    end
+  end
+
+  def test_validate_verify_runs_systemd_analyze_verify
+    with_project_dir do
+      write_schedule(HOURLY_SCHEDULE)
+      status, out, err, calls = run_validate("--verify", "--verbose")
+      assert_cli_success(status, err)
+      assert_includes out, "OK systemd-analyze --user verify"
+      assert_equal %w[systemd-analyze --user verify], calls.fetch(1).fetch(0).take(3)
+    end
+  end
+
+  def test_validate_returns_nonzero_when_systemd_analyze_calendar_fails
+    with_project_dir do
+      write_schedule(HOURLY_SCHEDULE)
+      status, _out, err, calls = run_validate(exitstatus: 1, stderr: "boom\n")
+      assert_equal 1, status
+      assert_includes err, "systemd-analyze failed"
+      assert_includes err, "boom"
+      assert_equal %w[systemd-analyze calendar hourly], calls.fetch(0).fetch(0)
+    end
+  end
+
+  private
+
+  def run_validate(*args, **kwargs)
+    run_cli_with_capture3_stub(["validate", *args], **kwargs)
+  end
+
+  def write_schedule(contents)
+    FileUtils.mkdir_p("config")
+    File.write(File.join("config", "schedule.rb"), contents)
+  end
+end

data/test/domain_model_test.rb

@@ -61,7 +61,7 @@ class DomainModelTest < Minitest::Test
     assert_raises(Wheneverd::InvalidCommandError) { Wheneverd::Job::Command.new(command: "   ") }
 
     error = assert_raises(Wheneverd::InvalidCommandError) { Wheneverd::Job::Command.new(command: 123) }
-    assert_includes error.message, "String"
+    assert_includes error.message, "String or an Array"
   end
 
   def test_triggers_render_timer_lines

data/test/dsl_context_shell_test.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class DSLContextShellTest < Minitest::Test
+  def test_shell_requires_every_block
+    ctx = Wheneverd::DSL::Context.new(path: "/tmp/config/schedule.rb")
+    error = assert_raises(Wheneverd::DSL::LoadError) { ctx.shell("echo hi") }
+    assert_includes error.message, "shell() must be called inside every() block"
+  end
+
+  def test_shell_requires_string_script
+    ctx = Wheneverd::DSL::Context.new(path: "/tmp/config/schedule.rb")
+    error = assert_raises(Wheneverd::DSL::LoadError) { ctx.every("1m") { shell(123) } }
+    assert_includes error.message, "shell() script must be a String"
+  end
+
+  def test_shell_rejects_empty_script
+    ctx = Wheneverd::DSL::Context.new(path: "/tmp/config/schedule.rb")
+    error = assert_raises(Wheneverd::DSL::LoadError) { ctx.every("1m") { shell("   ") } }
+    assert_includes error.message, "shell() script must not be empty"
+  end
+end

data/test/dsl_loader_test.rb

@@ -45,6 +45,29 @@ class DSLLoaderIntervalAndDurationTest < Minitest::Test
     assert_equal ["echo hello"], entry.jobs.map(&:command)
   end
 
+  def test_loads_argv_command
+    schedule = load_schedule(<<~RUBY)
+      every "5m" do
+        command ["echo", "hello world"]
+      end
+    RUBY
+
+    job = schedule.entries.fetch(0).jobs.fetch(0)
+    assert_equal ["echo", "hello world"], job.argv
+    assert_equal "echo \"hello world\"", job.command
+  end
+
+  def test_loads_shell_helper
+    schedule = load_schedule(<<~RUBY)
+      every "5m" do
+        shell "echo hello | sed -e s/hello/hi/"
+      end
+    RUBY
+
+    job = schedule.entries.fetch(0).jobs.fetch(0)
+    assert_equal ["/bin/bash", "-lc", "echo hello | sed -e s/hello/hi/"], job.argv
+  end
+
   def test_loads_duration_with_at_as_calendar
     schedule = load_schedule(<<~RUBY)
       every 1.day, at: "4:30 am" do

data/test/job_command_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class JobCommandTest < Minitest::Test
+  def test_accepts_argv_and_formats_execstart
+    command = Wheneverd::Job::Command.new(command: ["echo", "hello world"])
+    assert_equal ["echo", "hello world"], command.argv
+    assert_equal "echo \"hello world\"", command.command
+  end
+
+  def test_accepts_empty_argv_argument
+    command = Wheneverd::Job::Command.new(command: ["printf", "%s", ""])
+    assert_equal "printf %s \"\"", command.command
+  end
+
+  def test_rejects_invalid_argv
+    assert_raises(Wheneverd::InvalidCommandError) { Wheneverd::Job::Command.new(command: []) }
+    assert_raises(Wheneverd::InvalidCommandError) { Wheneverd::Job::Command.new(command: ["   "]) }
+    assert_raises(Wheneverd::InvalidCommandError) { Wheneverd::Job::Command.new(command: ["echo", 1]) }
+  end
+
+  def test_rejects_argv_with_newlines
+    error = assert_raises(Wheneverd::InvalidCommandError) do
+      Wheneverd::Job::Command.new(command: %W[echo hi\nthere])
+    end
+    assert_includes error.message, "must not include NUL or newlines"
+  end
+end

data/test/systemd_analyze_test.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class SystemdAnalyzeTest < Minitest::Test
+  def with_capture3_stub(exitstatus:, stdout: "", stderr: "")
+    calls = []
+    Thread.current[:open3_capture3_stub] = {
+      calls: calls,
+      stdout: stdout,
+      stderr: stderr,
+      exitstatus: exitstatus
+    }
+    yield calls
+  ensure
+    Thread.current[:open3_capture3_stub] = nil
+  end
+
+  def test_calendar_builds_command_and_returns_output
+    with_capture3_stub(exitstatus: 0, stdout: "ok\n", stderr: "") do |calls|
+      out, err = Wheneverd::Systemd::Analyze.calendar("hourly")
+      assert_equal "ok\n", out
+      assert_equal "", err
+      assert_equal [%w[systemd-analyze calendar hourly], {}], calls.fetch(0)
+    end
+  end
+
+  def test_verify_builds_user_verify_command
+    with_capture3_stub(exitstatus: 0) do |calls|
+      Wheneverd::Systemd::Analyze.verify(["/tmp/a.timer", "/tmp/a.service"], user: true)
+      assert_equal(
+        [["systemd-analyze", "--user", "verify", "/tmp/a.timer", "/tmp/a.service"], {}],
+        calls.fetch(0)
+      )
+    end
+  end
+
+  def test_calendar_raises_systemd_analyze_error_on_failure_with_details
+    with_capture3_stub(exitstatus: 1, stdout: "oops\n", stderr: "nope\n") do
+      error = assert_raises(Wheneverd::Systemd::SystemdAnalyzeError) do
+        Wheneverd::Systemd::Analyze.calendar("hourly")
+      end
+      assert_includes error.message, "status: 1"
+      assert_includes error.message, "stdout: oops"
+      assert_includes error.message, "stderr: nope"
+    end
+  end
+
+  def test_calendar_raises_systemd_analyze_error_when_missing
+    error = assert_raises(Wheneverd::Systemd::SystemdAnalyzeError) do
+      Wheneverd::Systemd::Analyze.calendar("hourly", systemd_analyze: "/no/such/systemd-analyze")
+    end
+    assert_includes error.message, "systemd-analyze not found"
+  end
+end

data/test/systemd_renderer_test.rb

@@ -62,6 +62,12 @@ class SystemdRendererIntervalTest < Minitest::Test
     assert_includes service.contents, "Type=oneshot"
     assert_includes service.contents, "ExecStart=echo hello"
   end
+
+  def test_interval_service_contains_execstart_for_argv
+    entry = interval_entry(seconds: 60, command: ["echo", "hello world"])
+    service = service_for(entry)
+    assert_includes service.contents, "ExecStart=echo \"hello world\""
+  end
 end
 
 class SystemdRendererCalendarTest < Minitest::Test

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wheneverd
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - bigcurl
@@ -50,11 +50,14 @@ files:
 - lib/wheneverd/cli/current.rb
 - lib/wheneverd/cli/deactivate.rb
 - lib/wheneverd/cli/delete.rb
+- lib/wheneverd/cli/diff.rb
 - lib/wheneverd/cli/help.rb
 - lib/wheneverd/cli/init.rb
 - lib/wheneverd/cli/linger.rb
 - lib/wheneverd/cli/reload.rb
 - lib/wheneverd/cli/show.rb
+- lib/wheneverd/cli/status.rb
+- lib/wheneverd/cli/validate.rb
 - lib/wheneverd/cli/write.rb
 - lib/wheneverd/core_ext/numeric_duration.rb
 - lib/wheneverd/dsl/at_normalizer.rb
@@ -69,6 +72,7 @@ files:
 - lib/wheneverd/interval.rb
 - lib/wheneverd/job/command.rb
 - lib/wheneverd/schedule.rb
+- lib/wheneverd/systemd/analyze.rb
 - lib/wheneverd/systemd/calendar_spec.rb
 - lib/wheneverd/systemd/cron_parser.rb
 - lib/wheneverd/systemd/errors.rb
@@ -87,17 +91,24 @@ files:
 - test/cli_activate_test.rb
 - test/cli_current_test.rb
 - test/cli_deactivate_test.rb
+- test/cli_diff_test.rb
 - test/cli_end_to_end_test.rb
+- test/cli_init_test.rb
 - test/cli_linger_test.rb
 - test/cli_reload_test.rb
+- test/cli_status_test.rb
 - test/cli_systemctl_integration_test.rb
 - test/cli_systemd_analyze_test.rb
 - test/cli_test.rb
+- test/cli_validate_test.rb
 - test/domain_model_test.rb
 - test/dsl_calendar_symbol_period_list_test.rb
+- test/dsl_context_shell_test.rb
 - test/dsl_loader_test.rb
+- test/job_command_test.rb
 - test/support/cli_subprocess_test_helpers.rb
 - test/support/cli_test_helpers.rb
+- test/systemd_analyze_test.rb
 - test/systemd_calendar_spec_test.rb
 - test/systemd_cron_parser_test.rb
 - test/systemd_renderer_errors_test.rb
@@ -131,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.4
 specification_version: 4
 summary: Wheneverd is to systemd timers what whenever is to cron.
 test_files: []