asgard 0.3.2 → 0.4.0

data/lib/asgard/schedule/systemd.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "etc"
+
+module Asgard
+  module Schedule
+    # Linux backend: each declaration becomes a systemd user service + timer
+    # pair (~/.config/systemd/user/asgard.<project>.<name>.{service,timer}).
+    # Calendar timers are Persistent=, so a run missed while the machine was
+    # off or asleep happens on the next boot/wake. Requires systemd 240+ (for
+    # StandardOutput=append:). User timers only run while you are logged in
+    # unless lingering is enabled (`loginctl enable-linger`); #notes says so.
+    # Implements the backend API documented in declaration.rb.
+    class Systemd
+      UNIT_PREFIX = "asgard"
+      DAY_ABBREVIATIONS = %w[Sun Mon Tue Wed Thu Fri Sat].freeze
+
+      # ---- pure helpers -----------------------------------------------------
+
+      def self.unit_prefix(project) = "#{UNIT_PREFIX}.#{Schedule.slug(project)}."
+
+      def self.unit(project, name) = "#{unit_prefix(project)}#{name}"
+
+      # { hour: 17, minute: 30, days: [1, 5] } => "Mon,Fri *-*-* 17:30:00"
+      def self.on_calendar(entry)
+        days = entry[:days]&.map { |day| DAY_ABBREVIATIONS.fetch(day) }&.join(",")
+        [days, format("*-*-* %<hour>02d:%<minute>02d:00", entry)].compact.join(" ")
+      end
+
+      # systemd expands %specifiers everywhere; % must be doubled to be literal.
+      def self.escape_specifiers(text) = text.to_s.gsub("%", "%%")
+
+      # A double-quoted word for ExecStart=/Environment=. $ is doubled too so
+      # ExecStart= doesn't expand it as a variable.
+      def self.quote(text)
+        %("#{escape_specifiers(text).gsub('\\') { '\\\\' }.gsub('"', '\\"').gsub('$', '$$')}")
+      end
+
+      def self.service_unit(description:, arguments:, working_directory:, environment:, log_path:)
+        env_lines = environment.map { |key, value| "Environment=#{quote("#{key}=#{value}")}" }
+        log       = escape_specifiers(log_path)
+        <<~UNIT
+          [Unit]
+          Description=#{escape_specifiers(description)}
+
+          [Service]
+          Type=oneshot
+          WorkingDirectory=#{escape_specifiers(working_directory)}
+          #{env_lines.join("\n")}
+          ExecStart=#{arguments.map { |arg| quote(arg) }.join(' ')}
+          StandardOutput=append:#{log}
+          StandardError=append:#{log}
+        UNIT
+      end
+
+      # every: runs one interval after the timer starts, then one interval
+      # after each run, matching launchd's StartInterval.
+      def self.timer_unit(description:, service:, calendar: nil, every: nil)
+        schedule = if every
+                     ["OnActiveSec=#{every}", "OnUnitActiveSec=#{every}"]
+                   else
+                     [*calendar.map { |entry| "OnCalendar=#{on_calendar(entry)}" }, "Persistent=true"]
+                   end
+        <<~UNIT
+          [Unit]
+          Description=#{escape_specifiers(description)}
+
+          [Timer]
+          #{schedule.join("\n")}
+          AccuracySec=1s
+          Unit=#{service}
+
+          [Install]
+          WantedBy=timers.target
+        UNIT
+      end
+
+      # `systemctl show -p A -p B` output => { "A" => "...", "B" => "..." }
+      def self.parse_show(output) = output.lines.to_h { |line| line.chomp.split("=", 2) }.reject { |k, _| k.to_s.empty? }
+
+      # ---- backend API ------------------------------------------------------
+
+      def initialize(project:, root:, home: Dir.home, runner: Schedule.runner, env: ENV, user: Etc.getpwuid(Process.uid).name)
+        @project = project
+        @root    = root
+        @runner  = runner
+        @user    = user
+        @config  = env["XDG_CONFIG_HOME"] || File.join(home, ".config")
+        @state   = env["XDG_STATE_HOME"] || File.join(home, ".local", "state")
+      end
+
+      def scheduler = "systemd"
+
+      def unit(name) = self.class.unit(@project, name)
+
+      def service_path(name) = File.join(@config, "systemd", "user", "#{unit(name)}.service")
+
+      def timer_path(name) = File.join(@config, "systemd", "user", "#{unit(name)}.timer")
+
+      def log_path(name) = File.join(@state, "asgard", "#{unit(name)}.log")
+
+      def files(spec, asgard:, direnv:)
+        name, task, args, every = spec.values_at(:name, :task, :args, :every)
+        klass       = self.class
+        description = "#{Schedule.command_line(task, args)} (#{@project})"
+        service = klass.service_unit(
+          description:,
+          arguments:         Schedule.program_arguments(task, args, root: @root, asgard:, direnv:),
+          working_directory: @root,
+          environment:       Schedule.environment(spec),
+          log_path:          log_path(name)
+        )
+        timer = klass.timer_unit(
+          description:,
+          service:  "#{unit(name)}.service",
+          calendar: every ? nil : Schedule.calendar(at: spec[:at], on: spec[:on]),
+          every:
+        )
+        { service_path(name) => service, timer_path(name) => timer }
+      end
+
+      # A timer that exists but is disabled was stopped on purpose; keep it so.
+      def install(spec, asgard:, direnv:)
+        name       = spec[:name]
+        timer_file = timer_path(name)
+        timer_unit = timer(name)
+        stopped    = File.exist?(timer_file) && !enabled?(name)
+        FileUtils.mkdir_p [File.dirname(timer_file), File.dirname(log_path(name))]
+        files(spec, asgard:, direnv:).each { |path, content| File.write(path, content) }
+        systemctl! "daemon-reload"
+        return :stopped if stopped
+
+        systemctl! "enable", timer_unit
+        systemctl! "restart", timer_unit # picks up a changed schedule
+        :active
+      end
+
+      def uninstall(name)
+        service_unit = service(name)
+        systemctl "disable", "--now", timer(name)
+        systemctl "stop", service_unit
+        FileUtils.rm_f [service_path(name), timer_path(name)]
+        systemctl "daemon-reload"
+        systemctl "reset-failed", service_unit
+      end
+
+      def start(name) = systemctl!("enable", "--now", timer(name))
+
+      def stop(name) = systemctl!("disable", "--now", timer(name))
+
+      def trigger(name) = systemctl!("start", "--no-block", service(name))
+
+      def installed_names
+        prefix = self.class.unit_prefix(@project)
+        Dir.glob(timer_path("*")).map { |path| File.basename(path, ".timer").delete_prefix(prefix) }.sort
+      end
+
+      def status(name)
+        _, active = systemctl("is-active", "--quiet", timer(name))
+        state = if active then :active
+                elsif enabled?(name) then :not_loaded
+                else :stopped
+                end
+        out, = systemctl("show", service(name), "-p", "ExecMainStatus", "-p", "ExecMainExitTimestampMonotonic")
+        props = self.class.parse_show(out)
+        stamp = props["ExecMainExitTimestampMonotonic"].to_s
+        ran   = !stamp.empty? && stamp != "0"
+        { state:, last_exit: ran ? props["ExecMainStatus"] : nil }
+      end
+
+      def notes
+        out, ok = run("loginctl", "show-user", @user.to_s, "-p", "Linger", "--value")
+        return [] unless ok && out.strip == "no"
+
+        ["systemd: user timers only run while #{@user} is logged in; run `loginctl enable-linger` to keep them running."]
+      end
+
+      private
+
+      def timer(name) = "#{unit(name)}.timer"
+
+      def service(name) = "#{unit(name)}.service"
+
+      def enabled?(name) = systemctl("is-enabled", "--quiet", timer(name)).last
+
+      def systemctl(*) = run("systemctl", "--user", *)
+
+      def systemctl!(*args)
+        out, ok = systemctl(*args)
+        raise Error, "systemctl --user #{args.join(' ')} failed: #{out.strip}" unless ok
+
+        out
+      end
+
+      def run(*argv) = @runner.call(*argv)
+    end
+  end
+end

data/lib/asgard/schedule.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "schedule/declaration"
+require_relative "schedule/launchd"
+require_relative "schedule/systemd"
+require_relative "schedule/commands"
+
+module Asgard
+  # Runs asgard tasks periodically under the platform's own scheduler.
+  # Declare entries at class level in a .loki file:
+  #
+  #   class Tasks
+  #     schedule :daily_summary, at: "17:30", on: :weekdays
+  #     schedule :sync,          every: 3600
+  #     schedule :report, options: "--period week", at: "16:00", on: :friday
+  #   end
+  #
+  # then manage them with `asgard schedule install|list|start|stop|...`.
+  module Schedule
+    class << self
+      # Declared entries for this run, keyed by entry name.
+      def declarations
+        @declarations ||= {}
+      end
+
+      # Records one declaration. Redeclaring an identical entry is a no-op
+      # (a .loki file loaded twice); a different entry under the same name
+      # is an error.
+      def declare(task, **settings)
+        spec  = normalize(task, **settings)
+        name  = spec[:name]
+        taken = declarations[name]
+        raise ArgumentError, "schedule: #{name.inspect} is already declared; give one a distinct as: name" if taken && taken != spec
+
+        declarations[name] = spec
+      end
+    end
+
+    # The class-level `schedule` declaration helper for Tasks.
+    module DSL
+      def schedule(task, **) = Schedule.declare(task, **)
+    end
+  end
+end

data/lib/asgard/shell.rb

@@ -8,17 +8,21 @@ module Asgard
     # Run a shell script. Multiline strings are passed to bash -c; single-line
     # strings are passed to system directly. Exits with the command's status
     # code on failure.
-    def sh(script, silent: false)
+    #
+    # Pass exec: true to replace the current process instead of forking —
+    # useful for a task's final, long-running command (e.g. a dev server)
+    # so the asgard/ruby process doesn't sit resident in memory alongside it.
+    def sh(script, silent: false, exec: false)
       script = script.strip
       $stdout.puts script unless silent
+      argv = shell_argv(script)
 
-      success = if script.include?("\n")
-                  system("bash", "-c", script)
-                else
-                  system(script)
-                end
-
-      exit($CHILD_STATUS.exitstatus) unless success
+      if exec
+        $stdout.flush
+        Kernel.exec(*argv)
+      else
+        exit($CHILD_STATUS.exitstatus) unless system(*argv)
+      end
     end
 
     # Write +script+ to a tempfile and execute it with +interpreter+.
@@ -42,5 +46,14 @@ module Asgard
         exit($CHILD_STATUS.exitstatus) unless $CHILD_STATUS.success?
       end
     end
+
+    private
+
+    # The argv passed to system/exec for +script+: multi-line scripts run
+    # through `bash -c` so assignments carry across lines; single-line
+    # scripts run directly.
+    def shell_argv(script)
+      script.include?("\n") ? ["bash", "-c", script] : [script]
+    end
   end
 end

data/lib/asgard/tasks.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "schedule"
+
 # Tasks is the single conventional entry point for all .loki files.
 # It is pre-defined by the gem so .loki files never need to declare a class.
 # Auxiliary *.loki files define modules which are imported into Tasks.
@@ -32,4 +34,14 @@ class Tasks < Asgard::Base
                default: false,
                desc:    "Diagnose .loki resolution, imports, and task definitions for the CWD, then exit"
   no_negate :doctor
+
+  # Class-level `schedule :task, at: "HH:MM"` declarations (see Asgard::Schedule).
+  extend Asgard::Schedule::DSL
+
+  # Gem-owned, so the command is _schedule; the map keeps `asgard schedule`
+  # as the name users type, and ancestor_name keeps it in subcommand help.
+  desc "schedule SUBCOMMAND", "Manage schedules declared with `schedule :task, ...` (launchd on macOS, systemd on Linux)"
+  subcommand "_schedule", Asgard::Schedule::Commands
+  map "schedule" => :_schedule
+  Asgard::Schedule::Commands.commands.each_value { |command| command.ancestor_name = "schedule" }
 end

data/lib/asgard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Asgard
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/asgard.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "asgard/errors"
 require_relative "asgard/version"
 require_relative "asgard/kernel_methods"
 require_relative "asgard/shell"
@@ -8,9 +9,6 @@ require_relative "asgard/tasks"
 require_relative "asgard/doctor"
 
 module Asgard
-  class Error < StandardError; end
-  class CircularDependencyError < Error; end
-
   # Search the current directory and its ancestors for a .loki task file.
   # Returns the path string, or nil if not found.
   def self.find_task_file
@@ -35,10 +33,17 @@ module Asgard
     newly_defined = Asgard::Base.subclasses - before
     (newly_defined + [Tasks]).uniq.each(&:validate_deps!)
     Tasks._reset_ran!
-    Tasks.start(argv)
+    result = Tasks.start(argv)
+    # Quality-gate convention: a task signals failure by returning :fail
+    # (see dev/quality.loki's *_check tasks). Surface that as a nonzero
+    # exit so callers (CI, cross-repo runners) can rely on $?.
+    exit(1) if result == :fail
+    result
   rescue CircularDependencyError => e
     abort "asgard: circular dependency — #{e.message}"
   rescue Error => e
     abort "asgard: #{e.message}"
+  rescue Interrupt
+    exit(130)
   end
 end

data/mkdocs.yml

@@ -158,6 +158,7 @@ nav:
       - Subcommands: subcommands.md
       - Shell Helpers: shell.md
       - Environment: environment.md
+      - Scheduled Tasks: schedule.md
   - Task Files: task-files.md
   - API Reference: api.md
   - Examples: examples.md

data/quality.loki

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 # Quality gate tasks — imported by .loki
 
+require "shellwords"
+
 class Tasks
+  # One process for every test/test_*.rb, so SimpleCov sees the whole suite.
+  TEST_LOADER = %q(Dir["test/test_*.rb"].each { |f| require File.expand_path(f) }).shellescape.freeze
+
   desc "Run the test suite"
   def test_check
-    output = `bundle exec ruby -Ilib:test test/test_asgard.rb 2>&1`
+    output = `bundle exec ruby -Ilib:test -e #{TEST_LOADER} 2>&1`
     result = $?.success? ? :pass : :fail
     File.write("test_output.txt", output)
     summary = output.lines.reverse.find { |l| l =~ /\d+ runs,/ }&.strip || result.to_s
@@ -14,7 +19,7 @@ class Tasks
 
   desc "Run the test suite with verbose output"
   def test_verbose
-    sh "bundle exec ruby -Ilib:test test/test_asgard.rb -v"
+    sh "bundle exec ruby -Ilib:test -e #{TEST_LOADER} -- -v"
   end
 
   desc "Run every *_check quality gate task in parallel"

data/quality_rails.loki

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
-# Rails-specific quality gate tasks — imported by .loki only when the Rails
-# constant is defined.
+# Rails-specific quality gate tasks — imported by .loki only when RAILS_ROOT
+# is set. asgard runs as a separate process outside the app it's checking,
+# so `defined?(Rails)` never sees the app's Rails constant.
 #
 # `quality` (in quality.loki) discovers every *_check task at run time by
 # introspecting Tasks.all_commands, rather than a fixed depends_on list — so

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asgard
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -40,7 +40,8 @@ dependencies:
 description: |
   A powerful Ruby-based task runner for any kind of project with task dependency tracking
   and concurrent execution of designated tasks. Uses Thor for its rich CLI options, var
-  declarations, dotenv, sh/shebang helpers, and importable task files.
+  declarations, dotenv, sh/shebang helpers, importable task files, and scheduled
+  execution of tasks via launchd (macOS) or systemd timers (Linux).
 email:
 - dewayne@vanhoozer.me
 executables:
@@ -62,6 +63,7 @@ files:
 - bin/asgard
 - bin/console
 - bin/setup
+- doc_tasks.loki
 - docs/api.md
 - docs/assets/css/custom.css
 - docs/assets/images/asgard.jpg
@@ -73,6 +75,7 @@ files:
 - docs/helpers.md
 - docs/index.md
 - docs/options.md
+- docs/schedule.md
 - docs/shell.md
 - docs/subcommands.md
 - docs/task-files.md
@@ -83,6 +86,8 @@ files:
 - examples/bad.loki
 - examples/concurrent.loki
 - examples/db_subcommands.loki
+- examples/depends_on_block/bad/.loki
+- examples/depends_on_block/good/.loki
 - examples/env_usage.loki
 - examples/kitchen_sink.loki
 - examples/server_subcommands.loki
@@ -100,7 +105,13 @@ files:
 - lib/asgard/doctor.rb
 - lib/asgard/doctor/report.rb
 - lib/asgard/doctor/task_sections.rb
+- lib/asgard/errors.rb
 - lib/asgard/kernel_methods.rb
+- lib/asgard/schedule.rb
+- lib/asgard/schedule/commands.rb
+- lib/asgard/schedule/declaration.rb
+- lib/asgard/schedule/launchd.rb
+- lib/asgard/schedule/systemd.rb
 - lib/asgard/shell.rb
 - lib/asgard/tasks.rb
 - lib/asgard/version.rb
@@ -131,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.21
 specification_version: 4
 summary: A powerful Ruby-based task runner
 test_files: []