wheneverd 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4d813e1e0ad0b44e738d4ba42767b5fb490dcaf5a7883328c91faa2ab726305
-  data.tar.gz: 1185929834d9f12adb4afd8a1bc2d1a4a366d99b260afe1d075a1ca58dc6dc26
+  metadata.gz: 9469e813aa6390a8e7eb911ce672a9fdaf7ab861e435d71d2d8887d551f8b8f8
+  data.tar.gz: dcf0211fe96fe0faff489a82ab3d0f12f36c3703083a949606eed4ab8eb9fa28
 SHA512:
-  metadata.gz: ed43947461d6e8dadf5825c8075e08816535c42202a9764c7b57d1fb4a7948a0dbfe1ff57e13cc710a853efa6910f802b93774b239736ed30bcec145812c08fc
-  data.tar.gz: 4406adc4f70afde1953cd8ea82979d2c37bf6b096232930724f2537b04d5ae187437fafa29215163ebd985eb132b89c7ee990497ba2cdb70617166b5d88114ee
+  metadata.gz: 4a448263264d7322c6622d111f5bf2f51f916ee0dc22193388e4b8b15a4336c3d136c475102db7c772b5be35fd53fa3800fcb733ef3850d620e982baeb9fa9a9
+  data.tar.gz: 62aad81a000a60510e6b230660321ec40951ecdcaed1317517f33fa10688fa319aa2afc43f8b003704b364d0f0f68a1d12e95482dce408208269a400ebee9a87

data/.ruby-version

@@ -0,0 +1 @@
+4.0.3

data/CHANGELOG.md

@@ -5,6 +5,22 @@ On release, entries are moved into `## x.y.z` sections that match the gem versio
 
 ## Unreleased
 
+## 0.5.0
+
+- Adds top-level `service` DSL entries for long-running systemd user services.
+- `activate`, `deactivate`, `reload`, and `status` now manage standalone services alongside timers.
+- Standalone services render as `Type=simple` units with configurable `Restart=`, `RestartSec=`, and extra `[Service]` settings.
+
+## 0.4.0
+
+- Docs: adds a copy/paste "deploy a simple schedule" example and refines README status section.
+- Refactor: extracts `UnitPathUtils` module for shared identifier/path utilities across `UnitWriter`, `UnitDeleter`, `UnitLister`, and `Renderer`.
+- Refactor: adds polymorphic `Trigger::Base` interface with `#systemd_timer_lines` and `#signature` methods for all trigger types.
+- Refactor: splits `CronParser` into focused `FieldParser` and `DowParser` submodules for maintainability.
+- Refactor: implements strategy pattern for `PeriodParser` with dedicated strategies for Duration, String, Symbol, and Array inputs.
+- Refactor: extracts `UnitContentBuilder` from `Renderer` for cleaner separation of unit content generation.
+- Refactor: adds `Validation` module with composable validators (`type`, `positive_integer`, `non_empty_string`, `non_empty_array`, `in_range`).
+
 ## 0.3.0
 
 - Schedule DSL: `command` accepts argv arrays, adds a `shell` helper for `/bin/bash -lc`, and `wheneverd init` includes examples.

data/Gemfile.lock

@@ -1,61 +1,64 @@
 PATH
   remote: .
   specs:
-    wheneverd (0.3.0)
+    wheneverd (0.5.0)
       clamp (~> 1.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    clamp (1.3.2)
+    clamp (1.5.2)
     date (3.5.1)
     docile (1.4.1)
-    erb (6.0.1)
+    drb (2.2.3)
+    erb (6.0.4)
     io-console (0.8.2)
-    irb (1.16.0)
+    irb (1.18.0)
       pp (>= 0.6.0)
+      prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.18.0)
+    json (2.19.4)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    minitest (6.0.1)
+    minitest (6.0.5)
+      drb (~> 2.0)
       prism (~> 1.5)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    parallel (2.1.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.7.0)
+    prism (1.9.0)
     psych (5.3.1)
       date
       stringio
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
-    rdoc (7.1.0)
+    rake (13.4.2)
+    rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
     redcarpet (3.6.1)
-    regexp_parser (2.11.3)
+    regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
-    rubocop (1.82.1)
+    rubocop (1.86.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.48.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-progressbar (1.13.0)
@@ -70,7 +73,7 @@ GEM
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
-    yard (0.9.38)
+    yard (0.9.43)
 
 PLATFORMS
   ruby
@@ -89,31 +92,33 @@ DEPENDENCIES
 
 CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
-  clamp (1.3.2) sha256=4f6a99a8678d51abbf1650263a74d1ac50939edc11986271431d2e03a0d7a022
+  bundler (4.0.11) sha256=5bcec0fb78302e48d02ee46f10ee6e6942be647ba5b44a6d1ddfda9a240ce785
+  clamp (1.5.2) sha256=2fed212e5c9b60447eb5097af39d4c12c3c7e6788e8d791e9c436e0e755f4adc
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
-  irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
-  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  json (2.19.4) sha256=670a7d333fb3b18ca5b29cb255eb7bef099e40d88c02c80bd42a3f30fe5239ac
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
-  minitest (6.0.1) sha256=7854c74f48e2e975969062833adc4013f249a4b212f5e7b9d5c040bf838d54bb
-  parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
-  parser (3.3.10.0) sha256=ce3587fa5cc55a88c4ba5b2b37621b3329aadf5728f9eafa36bbd121462aabd6
+  minitest (6.0.5) sha256=f007d7246bf4feea549502842cd7c6aba8851cdc9c90ba06de9c476c0d01155c
+  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  parser (3.3.11.1) sha256=d17ace7aabe3e72c3cc94043714be27cc6f852f104d81aa284c2281aecc65d54
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
-  prism (1.7.0) sha256=10062f734bf7985c8424c44fac382ac04a58124ea3d220ec3ba9fe4f2da65103
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
-  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
-  rdoc (7.1.0) sha256=494899df0706c178596ca6e1d50f1b7eb285a9b2aae715be5abd742734f17363
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rdoc (7.2.0) sha256=8650f76cd4009c3b54955eb5d7e3a075c60a57276766ebf36f9085e8c9f23192
   redcarpet (3.6.1) sha256=d444910e6aa55480c6bcdc0cdb057626e8a32c054c29e793fa642ba2f155f445
-  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
   reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  rubocop (1.82.1) sha256=09f1a6a654a960eda767aebea33e47603080f8e9c9a3f019bf9b94c9cab5e273
-  rubocop-ast (1.49.0) sha256=49c3676d3123a0923d333e20c6c2dbaaae2d2287b475273fddee0c61da9f71fd
+  rubocop (1.86.1) sha256=44415f3f01d01a21e01132248d2fd0867572475b566ca188a0a42133a08d4531
+  rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   simplecov (0.22.0) sha256=fe2622c7834ff23b98066bb0a854284b2729a569ac659f82621fc22ef36213a5
   simplecov-html (0.13.2) sha256=bd0b8e54e7c2d7685927e8d6286466359b6f16b18cb0df47b508e8d73c777246
@@ -122,8 +127,8 @@ CHECKSUMS
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
-  wheneverd (0.3.0)
-  yard (0.9.38) sha256=721fb82afb10532aa49860655f6cc2eaa7130889df291b052e1e6b268283010f
+  wheneverd (0.5.0)
+  yard (0.9.43) sha256=cf8733a8f0485df2a162927e9b5f182215a61f6d22de096b8f402c726a1c5821
 
 BUNDLED WITH
-  4.0.3
+  4.0.11

data/README.md

@@ -4,14 +4,23 @@ Wheneverd is to systemd timers what the [`whenever` gem](https://github.com/java
 
 ## Status
 
-Pre-1.0, but working end-to-end for user systemd timers:
+Pre-1.0, but working end-to-end for systemd user timers on Linux:
 
 - 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`).
+- Writes, diffs, shows, and deletes generated unit files (default: `~/.config/systemd/user`).
 - Enables/starts/stops/disables/restarts timers via `systemctl --user`.
+- Validates `OnCalendar=` values with `systemd-analyze` (optional unit verification).
 - Manages lingering via `loginctl` (so timers can run while logged out).
 
+Non-goals / not yet implemented:
+
+- System-level units (`/etc/systemd/system`) / `systemctl` without `--user`.
+- Non-systemd schedulers (cron, launchd, etc).
+- Non-Linux platforms (no Windows/macOS support).
+
+Expect the CLI and generated unit details to change until 1.0.
+
 See `FEATURE_SUMMARY.md` for user-visible behavior, and `CHANGELOG.md` for release notes.
 
 ## Installation
@@ -62,6 +71,40 @@ every 1.day, at: "4:30 am" do
 end
 ```
 
+### Deploy a simple schedule (copy/paste)
+
+From your project root (the default identifier is the current directory name):
+
+```bash
+# Install (skip if already in your Gemfile)
+bundle add wheneverd
+bundle install
+
+# Write a schedule that appends a timestamp to ~/.cache/wheneverd-demo.log every minute
+mkdir -p config
+cat > config/schedule.rb <<'RUBY'
+# frozen_string_literal: true
+
+every "1m" do
+  shell "mkdir -p ~/.cache && date >> ~/.cache/wheneverd-demo.log"
+end
+RUBY
+
+# Preview, write units, and enable/start the timer(s)
+bundle exec wheneverd show
+bundle exec wheneverd validate
+bundle exec wheneverd write
+bundle exec wheneverd activate
+
+# Verify it’s installed and running
+bundle exec wheneverd status
+tail -n 5 ~/.cache/wheneverd-demo.log
+
+# Stop/disable timers and remove generated unit files
+bundle exec wheneverd deactivate
+bundle exec wheneverd delete
+```
+
 Preview the generated units:
 
 ```bash
@@ -124,7 +167,7 @@ Schedules are defined in a Ruby file (default: `config/schedule.rb`) and evaluat
 
 Note: schedule files are executed as Ruby. Do not run untrusted schedule code.
 
-The core shape is:
+The core timer shape is:
 
 ```ruby
 every(period, at: nil) do
@@ -132,6 +175,20 @@ every(period, at: nil) do
 end
 ```
 
+Long-running services can be managed from the same schedule with top-level
+`service` entries:
+
+```ruby
+service "worker",
+        shell: "bundle exec bin/worker",
+        restart: "always",
+        restart_sec: "5s",
+        service: {
+          "WorkingDirectory" => "/srv/apps/myapp/current",
+          "Environment" => "RAILS_ENV=production"
+        }
+```
+
 For calendar schedules, you can also pass multiple period symbols (or an array) to run the same jobs on multiple days:
 
 ```ruby
@@ -227,14 +284,14 @@ 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 status [--identifier NAME] [--unit-dir PATH]` prints `systemctl --user list-timers` and `systemctl --user status` for installed timers/services.
 - `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 activate [--schedule PATH] [--identifier NAME]` runs `systemctl --user daemon-reload` and enables/starts the timers/services.
+- `wheneverd deactivate [--schedule PATH] [--identifier NAME]` stops and disables the timers/services.
+- `wheneverd reload [--schedule PATH] [--identifier NAME] [--unit-dir PATH] [--[no-]prune]` writes units, reloads systemd, and restarts timers/services.
 - `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).
 

data/lib/wheneverd/cli/activate.rb

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

data/lib/wheneverd/cli/deactivate.rb

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

data/lib/wheneverd/cli/reload.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
 module Wheneverd
-  # Implements `wheneverd reload` (write units, reload daemon, restart timers).
+  # Implements `wheneverd reload` (write units, reload daemon, restart timers/services).
   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?
+      paths, units = write_units_and_activatable_basenames
+      return 0 if units.empty?
 
-      reload_systemd(timer_units)
+      reload_systemd(units)
 
       paths.each { |path| puts path }
       0
@@ -21,7 +21,7 @@ module Wheneverd
 
     private
 
-    def write_units_and_timer_basenames
+    def write_units_and_activatable_basenames
       units = render_units
       paths = Wheneverd::Systemd::UnitWriter.write(
         units,
@@ -29,12 +29,12 @@ module Wheneverd
         prune: prune?,
         identifier: identifier_value
       )
-      [paths, timer_unit_basenames(units)]
+      [paths, activatable_unit_basenames(units)]
     end
 
-    def reload_systemd(timer_units)
+    def reload_systemd(units)
       Wheneverd::Systemd::Systemctl.run("daemon-reload")
-      Wheneverd::Systemd::Systemctl.run("restart", *timer_units)
+      Wheneverd::Systemd::Systemctl.run("restart", *units)
     end
   end
 end

data/lib/wheneverd/cli/status.rb

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

data/lib/wheneverd/cli.rb

@@ -51,12 +51,14 @@ module Wheneverd
     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
+    # @return [Array<String>] timer and standalone service unit basenames
+    def activatable_unit_basenames(units = render_units)
+      units.select { |unit| %i[timer service].include?(unit.activation) }
+           .map(&:path_basename)
+           .uniq
     end
 
-    private :render_units, :timer_unit_basenames
+    private :render_units, :activatable_unit_basenames
   end
 end
 
@@ -81,14 +83,14 @@ 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 "status", "Show systemctl 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
-    subcommand "deactivate", "Stop and disable timers via systemctl --user", Wheneverd::CLI::Deactivate
-    subcommand "reload", "Write units, reload daemon, restart timers", Wheneverd::CLI::Reload
+    subcommand "activate", "Enable and start timers/services via systemctl --user", Wheneverd::CLI::Activate
+    subcommand "deactivate", "Stop and disable timers/services via systemctl --user", Wheneverd::CLI::Deactivate
+    subcommand "reload", "Write units, reload daemon, restart timers/services", Wheneverd::CLI::Reload
     subcommand "current", "Show installed units from disk", Wheneverd::CLI::Current
     subcommand "linger", "Manage systemd user lingering via loginctl", Wheneverd::CLI::Linger
   end

data/lib/wheneverd/dsl/context.rb

@@ -75,6 +75,37 @@ module Wheneverd
         command([shell_executable, "-lc", script_stripped])
       end
 
+      # Add a long-running systemd user service to the schedule.
+      #
+      # @example Shell service
+      #   service "worker", shell: "bundle exec bin/worker"
+      #
+      # @example Argv service
+      #   service "worker", command: ["bundle", "exec", "bin/worker"]
+      #
+      # @param name [String] stable service name within the schedule
+      # @param command [String, Array<String>, nil]
+      # @param shell [String, nil] shell script to run via /bin/bash -lc
+      # @param restart [String]
+      # @param restart_sec [String]
+      # @param service [Hash, Array<String>] extra [Service] lines
+      # @return [Wheneverd::Service]
+      def service(name, command: nil, shell: nil, restart: "always", restart_sec: "5s",
+                  service: {})
+        command_value = normalize_service_command(command: command, shell: shell)
+        service_obj = Wheneverd::Service.new(
+          name: name,
+          command: command_value,
+          restart: restart,
+          restart_sec: restart_sec,
+          service: service
+        )
+        schedule.add_service(service_obj)
+        service_obj
+      rescue Wheneverd::InvalidCommandError => e
+        raise LoadError.new(e.message, path: path)
+      end
+
       private
 
       def ensure_in_every_block!(name)
@@ -102,6 +133,21 @@ module Wheneverd
         stripped
       end
 
+      def normalize_service_command(command:, shell:)
+        if command && shell
+          raise LoadError.new("service() accepts command: or shell:, not both", path: path)
+        end
+
+        return command if command
+
+        if shell
+          script = normalize_shell_script(shell)
+          return ["/bin/bash", "-lc", script]
+        end
+
+        raise LoadError.new("service() requires command: or shell:", path: path)
+      end
+
       def with_current_entry(entry)
         previous_entry = @current_entry
         @current_entry = entry