asgard 0.3.2 → 0.4.0

data/lib/asgard/schedule/commands.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "shellwords"
+
+# warn is silent when $VERBOSE is nil and bypasses $stderr in Ruby 4.0 (see
+# base/task_dsl.rb); these messages are for the user, so they always print.
+# rubocop:disable Style/StderrPuts
+
+module Asgard
+  module Schedule
+    # `asgard schedule SUBCOMMAND` — installs and manages the entries declared
+    # with `schedule :task, ...` in a .loki file. Subclasses Asgard::Base
+    # rather than Tasks so `asgard schedule help` lists only these
+    # subcommands, not every project task.
+    class Commands < Asgard::Base
+      namespace "schedule"
+
+      desc "tree", "Print a tree of the schedule subcommands", hide: true
+      # Redefined only to re-register tree as hidden in this namespace.
+      def tree = super # rubocop:disable Lint/UselessMethodDefinition
+
+      no_commands do
+        def schedules = Schedule.declarations
+
+        def schedule_root = (Asgard.find_task_file&.dirname || Pathname.pwd).to_s
+
+        def schedule_project = File.basename(schedule_root)
+
+        def scheduler
+          @scheduler ||= Schedule.backend_class.new(project: schedule_project, root: schedule_root)
+        end
+
+        def declared_schedules
+          if schedules.empty?
+            abort "No schedules declared. Add `schedule :task, at: \"HH:MM\"` inside class Tasks in #{schedule_root}/.loki."
+          end
+
+          specs   = schedules.values
+          unknown = specs.map { |spec| spec[:task] }.uniq - Tasks.all_commands.keys
+          abort "schedule: no such task(s): #{unknown.join(', ')}" unless unknown.empty?
+
+          specs
+        end
+
+        def schedule_direnv
+          return unless File.exist?(File.join(schedule_root, ".envrc"))
+
+          Schedule.which("direnv", ENV.fetch("PATH", nil)) or
+            $stderr.puts "schedule: .envrc found but direnv is not on PATH; its variables will not be loaded"
+        end
+
+        def schedule_asgard = Schedule.which("asgard", ENV.fetch("PATH", nil)) || abort("schedule: asgard is not on PATH")
+
+        def schedule_summary(spec) = "#{Schedule.command_line(spec[:task], spec[:args])} (#{Schedule.describe(**spec)})"
+
+        def schedule_install(spec, asgard:, direnv:)
+          name  = spec[:name]
+          state = scheduler.install(spec, asgard:, direnv:)
+          note  = state == :stopped ? " [stopped; `asgard schedule start #{name}` to resume]" : ""
+          puts "installed #{name}: #{schedule_summary(spec)}#{note}"
+        end
+
+        def schedule_uninstall(name)
+          scheduler.uninstall(name)
+          puts "removed #{name}"
+        end
+
+        def require_installed!(name)
+          abort "#{name} is not installed (see `asgard schedule list`)." unless scheduler.installed_names.include?(name)
+        end
+
+        def require_known!(name)
+          return if schedules.key?(name) || scheduler.installed_names.include?(name)
+
+          abort "#{name} is neither declared nor installed (see `asgard schedule list`)."
+        end
+      end
+
+      desc "preview", "Show the job files install would write, without installing them"
+      def preview
+        asgard = Schedule.which("asgard", ENV.fetch("PATH", nil)) || "asgard"
+        direnv = schedule_direnv
+        declared_schedules.each do |spec|
+          scheduler.files(spec, asgard:, direnv:).each do |path, content|
+            puts "# #{path}: #{schedule_summary(spec)}"
+            puts content
+          end
+        end
+      end
+
+      desc "install", "Install this project's schedule declarations (removes undeclared ones)"
+      def install
+        specs  = declared_schedules
+        asgard = schedule_asgard
+        direnv = schedule_direnv
+
+        (scheduler.installed_names - specs.map { |spec| spec[:name] }).each { |name| schedule_uninstall(name) }
+        specs.each { |spec| schedule_install(spec, asgard:, direnv:) }
+        scheduler.notes.each { |note| $stderr.puts note }
+      end
+
+      desc "list", "Show this project's installed entries, their state, and last exit status"
+      def list
+        names = scheduler.installed_names
+        return puts "No scheduled tasks installed for #{schedule_project} (#{scheduler.scheduler})." if names.empty?
+
+        names.each do |name|
+          status = scheduler.status(name)
+          state  = case status[:state]
+                   when :active  then "active; last exit: #{status[:last_exit] || 'never run'}"
+                   when :stopped then "stopped"
+                   else "not loaded"
+                   end
+          spec   = schedules[name]
+          timing = spec ? schedule_summary(spec) : "no longer declared"
+          puts "#{name}  #{timing}  [#{state}]  log: #{scheduler.log_path(name)}"
+        end
+      end
+
+      desc "stop NAME", "Stop one scheduled entry; it stays stopped across reboots and installs until started"
+      def stop(name)
+        require_installed!(name)
+        scheduler.stop(name)
+        puts "stopped #{name}"
+      end
+
+      desc "start NAME", "Start a stopped entry, or install and start just this declared entry"
+      def start(name)
+        require_known!(name)
+        spec = schedules[name]
+
+        if spec
+          declared_schedules # validates the task exists
+          scheduler.install(spec, asgard: schedule_asgard, direnv: schedule_direnv) # refresh the job files
+        else
+          $stderr.puts "schedule: #{name} is no longer declared; starting its installed job as-is"
+        end
+        scheduler.start(name)
+        puts "started #{name}"
+      end
+
+      desc "trigger NAME", "Run an installed entry now, under the scheduler's environment"
+      def trigger(name)
+        require_installed!(name)
+        abort "#{name} is stopped; `asgard schedule start #{name}` first." if scheduler.status(name)[:state] == :stopped
+
+        scheduler.trigger(name)
+        puts "triggered #{name}; output goes to #{scheduler.log_path(name)}"
+      end
+
+      desc "log NAME", "Print the named entry's log file to STDOUT"
+      method_option :follow, aliases: "-f", type: :boolean, desc: "Keep printing new output as it arrives (tail -f)"
+      def log(name)
+        require_known!(name)
+
+        path = scheduler.log_path(name)
+        return $stderr.puts "#{name} has no log yet (#{path}); it is created on the first run." unless File.exist?(path)
+        return sh("tail -n +1 -f #{path.shellescape}", silent: true, exec: true) if options[:follow]
+
+        IO.copy_stream(path, $stdout)
+      end
+
+      desc "remove", "Remove all of this project's installed entries"
+      def remove
+        names = scheduler.installed_names
+        return puts "No scheduled tasks installed for #{schedule_project}." if names.empty?
+
+        names.each { |name| schedule_uninstall(name) }
+      end
+    end
+  end
+end
+# rubocop:enable Style/StderrPuts

data/lib/asgard/schedule/declaration.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+
+module Asgard
+  # Scheduled asgard tasks, run by the platform's own scheduler: launchd on
+  # macOS (Schedule::Launchd), systemd user timers on Linux
+  # (Schedule::Systemd). Both run a calendar job missed while the machine
+  # slept as soon as it wakes.
+  #
+  # This file is the platform-neutral half: it validates `schedule`
+  # declarations and builds the command a job runs. Everything here is pure,
+  # so each method can be tested on its own.
+  #
+  # Every backend implements the same instance API, which is all
+  # Schedule::Commands uses:
+  #
+  #   Backend.new(project:, root:, home: Dir.home, runner: Schedule.runner)
+  #   #scheduler                          # => "launchd" / "systemd"
+  #   #files(spec, asgard:, direnv:)      # => { path => content } install would write
+  #   #install(spec, asgard:, direnv:)    # write + load; => :active, or :stopped if stopped earlier
+  #   #uninstall(name)                    # unload, clear any stop, delete files
+  #   #start(name) / #stop(name)          # stop persists across reboots and reinstalls
+  #   #trigger(name)                      # run once now, under the scheduler
+  #   #installed_names                    # => ["demo", ...] for this project
+  #   #status(name)                       # => { state: :active|:stopped|:not_loaded, last_exit: String|nil }
+  #   #log_path(name)                     # => path the job's output is appended to
+  #   #notes                              # => [String] platform hints to show after install
+  module Schedule
+    # A scheduler command (launchctl, systemctl) failed.
+    class Error < Asgard::Error; end
+
+    # Weekday numbers follow launchd and cron: 0 (Sunday) through 6 (Saturday).
+    DAYS = %i[sunday monday tuesday wednesday thursday friday saturday].freeze
+
+    DAY_GROUPS = {
+      weekdays: %i[monday tuesday wednesday thursday friday],
+      weekends: %i[saturday sunday]
+    }.freeze
+
+    # Default command runner for the backends: argv in, [output, success?] out.
+    RUNNER = lambda do |*argv|
+      out, status = Open3.capture2e(*argv)
+      [out, status.success?]
+    rescue SystemCallError => e
+      [e.message, false]
+    end
+
+    class << self
+      # The runner new backends get. Tests assign one that records commands
+      # instead of running them; nil restores RUNNER.
+      attr_writer :runner
+
+      def runner = @runner || RUNNER
+
+      # The backend class for +platform+ (a RUBY_PLATFORM string).
+      def backend_class(platform = RUBY_PLATFORM)
+        case platform
+        when /darwin/ then Launchd
+        when /linux/  then Systemd
+        else raise Error, "#{platform} is not supported (needs macOS launchd or Linux systemd)"
+        end
+      end
+    end
+
+    module_function
+
+    # Validates a declaration and returns it as a plain Hash. options: is the
+    # task's command-line options as a String, split shell-style with quotes
+    # respected ("--period week --title 'Week End'"), or an Array of words.
+    # Exactly one of at: ("HH:MM" or an Array of them, with on:) or every:
+    # (seconds or a Duration) is required. as: names the entry.
+    def normalize(task, options: nil, at: nil, on: :daily, every: nil, env: {}, as: nil)
+      task = task.to_s
+      unless task.match?(/\A[\w:-]+\z/)
+        raise ArgumentError,
+              "schedule: task name #{task.inspect} must be a single word; put its flags in options:"
+      end
+      raise ArgumentError, "schedule :#{task} needs either at: or every:, not both" unless at.nil? ^ every.nil?
+
+      if every
+        every = seconds(every)
+        unless every&.positive?
+          raise ArgumentError,
+                "schedule :#{task} every: must be a positive number of seconds or a Duration (3.minutes)"
+        end
+      else
+        calendar(at:, on:) # raises on a bad time or day
+      end
+
+      args = options.is_a?(Array) ? options.map(&:to_s) : Shellwords.split(options.to_s)
+      { name: entry_name(task, args, as), task:, args:, at:, on:, every:, env: env.to_h { |key, value| [key.to_s, value.to_s] } }
+    end
+
+    # Integer seconds from an Integer or anything Duration-like (ActiveSupport's
+    # 3.minutes responds to in_seconds); nil for anything else.
+    def seconds(value)
+      return value if value.is_a?(Integer)
+
+      value.respond_to?(:in_seconds) ? value.in_seconds.to_i : nil
+    end
+
+    # The task alone, or a slug of the whole command when it has arguments,
+    # so one task can be scheduled more than once with different flags.
+    def entry_name(task, args, as = nil)
+      name = (as || (args.empty? ? task : slug([task, *args].join(" ")))).to_s
+      raise ArgumentError, "schedule as: #{name.inspect} may only contain letters, digits, _ . -" unless name.match?(/\A[\w.-]+\z/)
+
+      name
+    end
+
+    def slug(name) = name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").delete_prefix("-").delete_suffix("-")
+
+    # For display: the command line the job runs.
+    def command_line(task, args = []) = Shellwords.join(["asgard", task.to_s, *args])
+
+    def describe(at: nil, on: :daily, every: nil, **)
+      return "every #{every}s" if every
+
+      "#{Array(at).join(', ')} #{Array(on).join(', ')}"
+    end
+
+    # "17:30" => [17, 30]
+    def parse_time(time)
+      shown = time.inspect
+      match = /\A(\d{1,2}):(\d{2})\z/.match(time.to_s) or
+        raise ArgumentError, %(at: expects "HH:MM" (got #{shown}))
+      hour = match[1].to_i
+      minute = match[2].to_i
+      raise ArgumentError, "at: #{shown} is not a valid time" unless hour <= 23 && minute <= 59
+
+      [hour, minute]
+    end
+
+    # :daily => nil (every day); :weekdays => [1, 2, 3, 4, 5]; :friday => [5];
+    # %i[monday thursday] => [1, 4]
+    def weekdays(on)
+      return nil if on.to_s == "daily"
+
+      names = DAY_GROUPS.fetch(on.is_a?(Array) ? nil : on.to_sym) { Array(on) }
+      names.map do |day|
+        DAYS.index(day.to_sym) or raise ArgumentError, "on: unknown day #{day.inspect}"
+      end
+    end
+
+    # One entry per time: [{ hour: 17, minute: 30, days: [1, 2, 3, 4, 5] }];
+    # days is nil for every day.
+    def calendar(at:, on: :daily)
+      days = weekdays(on)
+      Array(at).map do |time|
+        hour, minute = parse_time(time)
+        { hour:, minute:, days: }
+      end
+    end
+
+    # PATH captured at install time, plus the declaration's env:.
+    def environment(spec, path = ENV.fetch("PATH", nil)) = { "PATH" => path.to_s }.merge(spec[:env])
+
+    # First executable named +command+ on +path+ (a PATH-style String), or nil.
+    def which(command, path)
+      path.to_s.split(File::PATH_SEPARATOR)
+          .map { |dir| File.join(dir, command) }
+          .find { |file| File.file?(file) && File.executable?(file) }
+    end
+
+    # The job's argv. Schedulers need an absolute program. With direnv, the
+    # repo's .envrc (API keys, ...) is loaded at run time instead of being
+    # copied into the job definition, and direnv finds asgard on the job's
+    # PATH. Each argument is its own element, so no shell re-splits them.
+    def program_arguments(task, args = [], root:, asgard:, direnv: nil)
+      argv = [task.to_s, *args.map(&:to_s)]
+      direnv ? [direnv, "exec", root, "asgard", *argv] : [asgard, *argv]
+    end
+  end
+end

data/lib/asgard/schedule/launchd.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Asgard
+  module Schedule
+    # macOS backend: each declaration becomes a launchd user agent
+    # (~/Library/LaunchAgents/com.madbomber.asgard.<project>.<name>.plist).
+    # launchd runs a calendar job missed while the Mac slept as soon as it
+    # wakes. Implements the backend API documented in declaration.rb.
+    class Launchd
+      LABEL_PREFIX = "com.madbomber.asgard"
+
+      # ---- pure helpers -----------------------------------------------------
+
+      def self.label_prefix(project) = "#{LABEL_PREFIX}.#{Schedule.slug(project)}."
+
+      def self.label(project, name) = "#{label_prefix(project)}#{name}"
+
+      # One StartCalendarInterval entry per (time, weekday) pair.
+      def self.calendar_intervals(at:, on: :daily)
+        Schedule.calendar(at:, on:).flat_map do |entry|
+          (entry[:days] || [nil]).map { |day| { "Hour" => entry[:hour], "Minute" => entry[:minute], "Weekday" => day }.compact }
+        end
+      end
+
+      # Labels marked disabled in `launchctl print-disabled` output
+      # ("label" => disabled, or "label" => true on older macOS).
+      def self.disabled_labels(output) = output.scan(/"([^"]+)"\s*=>\s*(disabled|true)\b/).map(&:first)
+
+      def self.plist(label:, arguments:, working_directory:, environment:, log_path:, intervals: nil, every: nil)
+        dict = {
+          "Label"                => label,
+          "ProgramArguments"     => arguments,
+          "WorkingDirectory"     => working_directory,
+          "EnvironmentVariables" => environment,
+          "StandardOutPath"      => log_path,
+          "StandardErrorPath"    => log_path
+        }
+        every ? dict["StartInterval"] = every : dict["StartCalendarInterval"] = intervals
+
+        <<~XML
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          #{to_xml(dict)}
+          </plist>
+        XML
+      end
+
+      def self.to_xml(value, indent = "")
+        case value
+        in Hash
+          body = value.flat_map { |key, item| ["#{indent}  <key>#{escape(key)}</key>", to_xml(item, "#{indent}  ")] }
+          ["#{indent}<dict>", *body, "#{indent}</dict>"].join("\n")
+        in Array
+          ["#{indent}<array>", *value.map { |element| to_xml(element, "#{indent}  ") }, "#{indent}</array>"].join("\n")
+        in Integer
+          "#{indent}<integer>#{value}</integer>"
+        in true | false
+          "#{indent}<#{value}/>"
+        else
+          "#{indent}<string>#{escape(value)}</string>"
+        end
+      end
+
+      def self.escape(text) = text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+
+      # ---- backend API ------------------------------------------------------
+
+      def initialize(project:, root:, home: Dir.home, runner: Schedule.runner, uid: Process.uid)
+        @project = project
+        @root    = root
+        @home    = home
+        @runner  = runner
+        @domain  = "gui/#{uid}"
+      end
+
+      def scheduler = "launchd"
+
+      def label(name) = self.class.label(@project, name)
+
+      def plist_path(name) = File.join(@home, "Library", "LaunchAgents", "#{label(name)}.plist")
+
+      def log_path(name) = File.join(@home, "Library", "Logs", "asgard", "#{label(name)}.log")
+
+      def files(spec, asgard:, direnv:)
+        name  = spec[:name]
+        every = spec[:every]
+        klass = self.class
+        plist = klass.plist(
+          label:             label(name),
+          arguments:         Schedule.program_arguments(spec[:task], spec[:args], root: @root, asgard:, direnv:),
+          working_directory: @root,
+          environment:       Schedule.environment(spec),
+          log_path:          log_path(name),
+          intervals:         every ? nil : klass.calendar_intervals(at: spec[:at], on: spec[:on]),
+          every:
+        )
+        { plist_path(name) => plist }
+      end
+
+      def install(spec, asgard:, direnv:)
+        name  = spec[:name]
+        plist = plist_path(name)
+        FileUtils.mkdir_p [File.dirname(plist), File.dirname(log_path(name))]
+        files(spec, asgard:, direnv:).each { |path, content| File.write(path, content) }
+        run! "plutil", "-lint", "-s", plist
+        unload(name)
+        return :stopped if stopped?(name)
+
+        run! "launchctl", "bootstrap", @domain, plist
+        :active
+      end
+
+      def uninstall(name)
+        unload(name)
+        run "launchctl", "enable", target(name) # clear any stop
+        FileUtils.rm_f(plist_path(name))
+      end
+
+      def start(name)
+        run! "launchctl", "enable", target(name)
+        run! "launchctl", "bootstrap", @domain, plist_path(name) unless loaded?(name)
+      end
+
+      def stop(name)
+        run! "launchctl", "disable", target(name)
+        unload(name)
+      end
+
+      def trigger(name) = run!("launchctl", "kickstart", target(name))
+
+      def installed_names
+        prefix = self.class.label_prefix(@project)
+        Dir.glob(plist_path("*")).map { |path| File.basename(path, ".plist").delete_prefix(prefix) }.sort
+      end
+
+      def status(name)
+        out, ok = run("launchctl", "print", target(name))
+        return { state: stopped?(name) ? :stopped : :not_loaded, last_exit: nil } unless ok
+
+        code = out[/last exit code = (\d+)/, 1]
+        { state: :active, last_exit: code }
+      end
+
+      def notes = []
+
+      private
+
+      def target(name) = "#{@domain}/#{label(name)}"
+
+      def loaded?(name) = run("launchctl", "print", target(name)).last
+
+      def stopped?(name)
+        out, = run("launchctl", "print-disabled", @domain)
+        self.class.disabled_labels(out).include?(label(name))
+      end
+
+      # bootout returns before the job is fully gone; bootstrapping the same
+      # label too soon fails with "Input/output error", so wait for it.
+      def unload(name)
+        return unless loaded?(name)
+
+        run "launchctl", "bootout", target(name)
+        20.times do
+          break unless loaded?(name)
+
+          sleep 0.1
+        end
+      end
+
+      def run(*argv) = @runner.call(*argv)
+
+      def run!(*argv)
+        out, ok = run(*argv)
+        raise Error, "#{argv.join(' ')} failed: #{out.strip}" unless ok
+
+        out
+      end
+    end
+  end
+end