wheneverd 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48c6bdb7f18c775a63b874f0509d276f9f5a9b585193aa9f3b1795f3374f26c8
-  data.tar.gz: ef19f548714b7c70998e7e53ee560876742108199f8418e342a7c2f7117fe796
+  metadata.gz: c4d813e1e0ad0b44e738d4ba42767b5fb490dcaf5a7883328c91faa2ab726305
+  data.tar.gz: 1185929834d9f12adb4afd8a1bc2d1a4a366d99b260afe1d075a1ca58dc6dc26
 SHA512:
-  metadata.gz: 5e19a91cc2c5ad5ecd4d040cdc450de1153a8f685ef1c8be7db022d6f4189f628d8c9effe52d2a3428734a4de088e5eb1b4fba5d7d1a655fb9e38b6110794d60
-  data.tar.gz: 027fabc2a861d96f3f79afe6930d18758aaeaec2e39490ab93a8b7b0939a5ff543de0f6ac06438ce6ac100b68a4dd8375d0dcedf104d82f90618368bd82c7621
+  metadata.gz: ed43947461d6e8dadf5825c8075e08816535c42202a9764c7b57d1fb4a7948a0dbfe1ff57e13cc710a853efa6910f802b93774b239736ed30bcec145812c08fc
+  data.tar.gz: 4406adc4f70afde1953cd8ea82979d2c37bf6b096232930724f2537b04d5ae187437fafa29215163ebd985eb132b89c7ee990497ba2cdb70617166b5d88114ee

data/CHANGELOG.md

@@ -5,10 +5,22 @@ On release, entries are moved into `## x.y.z` sections that match the gem versio
 
 ## Unreleased
 
-- Adds `wheneverd linger enable|disable|status` for managing systemd user lingering via `loginctl`.
+## 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.
 
 ## 0.2.0
 
+- Adds `wheneverd linger enable|disable|status` for managing systemd user lingering via `loginctl`.
+
+## 0.1.0
+
 - Provides a Clamp-based `wheneverd` CLI with `--help`, `--version`, and `--verbose` (usage errors in `ERROR: ...` format).
 - Adds core domain objects and helpers for building schedules (interval parsing, durations, triggers, entries, jobs).
 - Adds a Ruby DSL loader (`Wheneverd::DSL::Loader.load_file`) supporting `every(...)` blocks with `command(...)` jobs.

data/FEATURE_SUMMARY.md

@@ -12,19 +12,30 @@ It complements [`CHANGELOG.md`](CHANGELOG.md) by staying high-level and focusing
 
 ## Unreleased
 
-- Adds `wheneverd linger enable|disable|status` for managing systemd user lingering via `loginctl`.
+## 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.
 
 ## 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`.
-- Schedule DSL supports `every(period, at: ..., roles: ...) { command("...") }` entries (multiple `command` calls per entry).
+- Schedule DSL supports `every(period, at: ...) { command("...") }` entries (multiple `command` calls per entry).
 - Schedule DSL supports multiple calendar period symbols per `every` block (e.g. `every :tuesday, :wednesday`).
 - Supported `every` periods include interval strings/durations, calendar shortcuts (`:hour`, `:day`, `:month`, `:year`),
   day selectors (`:monday..:sunday`, `:weekday`, `:weekend`), and standard 5-field cron strings.
 - `at:` supports a string or an array of strings (for calendar schedules), like `"4:30 am"` or `"00:15"`.
-- `roles:` is accepted and stored on entries, but is not used for filtering yet.
 - The gem can render systemd `.service` and `.timer` units via `Wheneverd::Systemd::Renderer.render`.
 - Generated unit basenames include a stable ID derived from the job’s trigger + command (reordering schedule blocks won’t rename units).
 - Interval timers include both `OnActiveSec=` and `OnUnitActiveSec=` to ensure a newly started timer has a next run scheduled.

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

@@ -2,15 +2,17 @@
 
 Wheneverd is to systemd timers what the [`whenever` gem](https://github.com/javan/whenever) is to cron.
 
-Tagline / repo: `git@github.com:bigcurl/wheneverd.git`
-
 ## Status
 
-Working end-to-end: schedule DSL loading, systemd unit rendering, and safe unit write/list/delete are implemented, along with a CLI for `init`, `show`, `write`, `delete`, `activate`, `deactivate`, `reload`, and `current`.
+Pre-1.0, but working end-to-end for user systemd timers:
 
-Known limitations: `roles:` is accepted but not used for filtering yet.
+- Loads a Ruby schedule DSL file (default: `config/schedule.rb`).
+- Renders systemd `.service`/`.timer` units (interval, calendar, and 5-field cron schedules).
+- Writes, lists, and deletes generated unit files (default: `~/.config/systemd/user`).
+- Enables/starts/stops/disables/restarts timers via `systemctl --user`.
+- Manages lingering via `loginctl` (so timers can run while logged out).
 
-See `FEATURE_SUMMARY.md` for high-level user-visible behavior, and `CHANGELOG.md` for release notes.
+See `FEATURE_SUMMARY.md` for user-visible behavior, and `CHANGELOG.md` for release notes.
 
 ## Installation
 
@@ -32,15 +34,20 @@ bundle install
 wheneverd --help
 wheneverd init
 wheneverd show
+wheneverd status
+wheneverd diff
+wheneverd validate
 wheneverd write
 wheneverd delete
 wheneverd activate
 wheneverd deactivate
 wheneverd reload
 wheneverd current
-wheneverd linger status
+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
@@ -120,7 +127,7 @@ Note: schedule files are executed as Ruby. Do not run untrusted schedule code.
 The core shape is:
 
 ```ruby
-every(period, at: nil, roles: nil) do
+every(period, at: nil) do
   command "echo hello"
 end
 ```
@@ -135,13 +142,26 @@ end
 
 ### `command`
 
-`command("...")` appends a oneshot `ExecStart=` job. Commands must be non-empty strings.
+`command(...)` appends a oneshot `ExecStart=` job.
 
-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:
+Accepted forms:
+
+- `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
@@ -185,10 +205,6 @@ Cron translation supports standard 5-field crontab strings (`minute hour day-of-
 
 Unsupported cron patterns raise an error at render time (e.g. non-5-field strings, `@daily`, `L`, `W`, `#`, `?`).
 
-### `roles:`
-
-`roles:` is accepted and stored on entries, but is ignored in v1 (no role-based filtering yet).
-
 ## CLI
 
 Defaults:
@@ -204,17 +220,23 @@ Notes:
 - Identifiers are sanitized for use in unit file names (non-alphanumeric characters become `-`).
 - 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 write [--dry-run] [--unit-dir PATH] [--[no-]prune]` writes units to disk (or prints paths in `--dry-run` mode).
-- `wheneverd delete [--dry-run] [--unit-dir PATH]` deletes previously generated units for the identifier.
+- `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.
 - `wheneverd deactivate [--schedule PATH] [--identifier NAME]` stops and disables the timers.
 - `wheneverd reload [--schedule PATH] [--identifier NAME] [--unit-dir PATH] [--[no-]prune]` writes units, reloads systemd, and restarts timers.
 - `wheneverd current [--identifier NAME] [--unit-dir PATH]` prints the currently installed unit file contents from disk.
+- `wheneverd linger [--user NAME] [enable|disable|status]` manages lingering via `loginctl` (`status` is the default).
 
 ## Development
 

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
@@ -25,16 +25,15 @@ module Wheneverd
       #
       # @param periods [Array<String, Symbol, Wheneverd::Duration, Array<Symbol>>]
       # @param at [String, Array<String>, nil]
-      # @param roles [Object] stored but currently not used for filtering
       # @return [Wheneverd::Entry]
-      def every(*periods, at: nil, roles: nil, &block)
+      def every(*periods, at: nil, &block)
         raise InvalidPeriodError.new("every() requires a block", path: path) unless block
 
         raise InvalidPeriodError.new("every() requires a period", path: path) if periods.empty?
 
         period = periods.length == 1 ? periods.first : periods
         trigger = @period_parser.trigger_for(period, at: at)
-        entry = Wheneverd::Entry.new(trigger: trigger, roles: roles)
+        entry = Wheneverd::Entry.new(trigger: trigger)
 
         schedule.add_entry(entry)
 
@@ -45,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/entry.rb

@@ -6,17 +6,15 @@ module Wheneverd
   # An entry ties together a trigger (when to run) and one or more jobs (what to run).
   class Entry
     # @return [Wheneverd::Trigger::Interval, Wheneverd::Trigger::Calendar, Wheneverd::Trigger::Boot]
-    attr_reader :trigger, :jobs, :roles
+    attr_reader :trigger, :jobs
 
     # @param trigger [Object] a trigger object describing when to run
     # @param jobs [Array<Object>] job objects (usually {Wheneverd::Job::Command})
-    # @param roles [Object] stored but currently not used for filtering
-    def initialize(trigger:, jobs: [], roles: nil)
+    def initialize(trigger:, jobs: [])
       raise ArgumentError, "trigger is required" if trigger.nil?
 
       @trigger = trigger
       @jobs = jobs.dup
-      @roles = roles
     end
 
     # Append a job to the 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