asgard 0.3.3 → 0.4.1

data/lib/asgard/schedule/launchd.rb

@@ -0,0 +1,238 @@
+# 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
+
+      # The parts of a plist (as `plist` writes it) that say what runs and when:
+      # { arguments: [String], calendar: [{ hour:, minute:, days: [Integer]|nil }], every: Integer|nil }
+      def self.parse_plist(xml)
+        {
+          arguments: array_body(xml, "ProgramArguments").scan(%r{<string>(.*?)</string>}m).flatten.map { |text| unescape(text) },
+          calendar:  calendar_entries(array_body(xml, "StartCalendarInterval").scan(%r{<dict>(.*?)</dict>}m).flatten),
+          every:     xml[%r{<key>StartInterval</key>\s*<integer>(\d+)</integer>}, 1]&.to_i
+        }
+      end
+
+      # StartCalendarInterval dict bodies => one entry per time, days collected.
+      def self.calendar_entries(dicts)
+        dicts.map { |body| parse_dict(body) }
+             .group_by { |dict| dict.values_at("Hour", "Minute") }
+             .map { |(hour, minute), group| calendar_entry(hour, minute, group) }
+      end
+
+      # <key>Hour</key><integer>13</integer>... => { "Hour" => 13, ... }
+      def self.parse_dict(body) = body.scan(%r{<key>(\w+)</key>\s*<integer>(\d+)</integer>}).to_h { |key, num| [key, num.to_i] }
+
+      # group: the Weekday-bearing dicts for one time; days is nil when there are none (every day).
+      def self.calendar_entry(hour, minute, group)
+        days = group.filter_map { |dict| dict["Weekday"] }
+        { hour:, minute:, days: days.empty? ? nil : days }
+      end
+
+      # The text inside the <array> that follows <key>key</key>.
+      def self.array_body(xml, key) = xml[%r{<key>#{key}</key>\s*<array>(.*?)</array>}m, 1].to_s
+
+      # The WorkingDirectory (the project root) of a plist, or nil.
+      def self.parse_directory(xml) = xml[%r{<key>WorkingDirectory</key>\s*<string>(.*?)</string>}m, 1]&.then { |text| unescape(text) }
+
+      def self.unescape(text) = text.gsub("&lt;", "<").gsub("&gt;", ">").gsub("&amp;", "&")
+
+      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
+
+      # Every asgard entry on this machine, whatever its project: [[project_slug, name], ...].
+      def installed_entries
+        paths = Dir.glob(File.join(@home, "Library", "LaunchAgents", "#{LABEL_PREFIX}.*.plist"))
+        paths.map { |path| File.basename(path, ".plist").delete_prefix("#{LABEL_PREFIX}.").split(".", 2) }
+             .select { |entry| entry.size == 2 }.sort
+      end
+
+      # { command:, schedule: } as installed, read from the plist; nil when there isn't one.
+      def installed_columns(name)
+        path = plist_path(name)
+        return unless File.exist?(path)
+
+        Schedule.installed_columns(**self.class.parse_plist(File.read(path)))
+      end
+
+      # The project root the job runs in, read from the plist; nil when there isn't one.
+      def installed_directory(name)
+        path = plist_path(name)
+        self.class.parse_directory(File.read(path)) if File.exist?(path)
+      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

data/lib/asgard/schedule/systemd.rb

@@ -0,0 +1,246 @@
+# 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
+
+      # ExecStart= words, undoing `quote`.
+      def self.parse_exec_start(service)
+        line = service[/^ExecStart=(.*)$/, 1].to_s
+        line.scan(/"((?:[^"\\]|\\.)*)"/).flatten.map { |word| word.gsub(/\\(.)/, '\1').gsub("$$", "$").gsub("%%", "%") }
+      end
+
+      # "Mon,Fri *-*-* 17:30:00" => { hour: 17, minute: 30, days: [1, 5] }
+      def self.parse_on_calendar(text)
+        days = text[/\A([A-Z][a-z]{2}(?:,[A-Z][a-z]{2})*) /, 1]
+        hour, minute = text.scan(/(\d+):(\d+)/).first.map(&:to_i)
+        { hour:, minute:, days: days&.split(",")&.map { |abbr| DAY_ABBREVIATIONS.index(abbr) } }
+      end
+
+      # The WorkingDirectory= (the project root) of a service unit, or nil.
+      def self.parse_directory(service) = service[/^WorkingDirectory=(.*)$/, 1]&.gsub("%%", "%")
+
+      # { calendar: [entry], every: Integer|nil } from a timer unit.
+      def self.parse_timer(timer)
+        {
+          calendar: timer.scan(/^OnCalendar=(.*)$/).flatten.map { |text| parse_on_calendar(text) },
+          every:    timer[/^OnUnitActiveSec=(\d+)/, 1]&.to_i
+        }
+      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
+
+      # Every asgard entry on this machine, whatever its project: [[project_slug, name], ...].
+      def installed_entries
+        paths = Dir.glob(File.join(@config, "systemd", "user", "#{UNIT_PREFIX}.*.timer"))
+        paths.map { |path| File.basename(path, ".timer").delete_prefix("#{UNIT_PREFIX}.").split(".", 2) }
+             .select { |entry| entry.size == 2 }.sort
+      end
+
+      # { command:, schedule: } as installed, read from the unit files; nil when there are none.
+      def installed_columns(name)
+        paths = [service_path(name), timer_path(name)]
+        return unless paths.all? { |path| File.exist?(path) }
+
+        klass = self.class
+        service, timer = paths.map { |path| File.read(path) }
+        Schedule.installed_columns(arguments: klass.parse_exec_start(service), **klass.parse_timer(timer))
+      end
+
+      # The project root the job runs in, read from the service unit; nil when there isn't one.
+      def installed_directory(name)
+        path = service_path(name)
+        self.class.parse_directory(File.read(path)) if File.exist?(path)
+      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/table.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Asgard
+  module Schedule
+    # The table `asgard schedule list` prints, drawn by tty-table. rows are
+    # hashes with :name, :command, :schedule, :state and :last_exit (strings).
+    # A cell that doesn't fit wraps onto extra lines; only COMMAND and SCHEDULE
+    # give up width, so the short columns always stay whole.
+    class Table
+      HEADERS      = ["NAME", "COMMAND", "SCHEDULE", "STATE", "LAST EXIT"].freeze
+      FLEXIBLE     = [1, 2].freeze
+      MIN_WIDTH    = 14
+      EXTRA        = 4 # a space either side of a cell, plus slack for tty-table's rounding
+      BORDERS      = HEADERS.size + 1 # one before each column and one after the last
+
+      # Columns available for output: the terminal's when io is one, else
+      # $COLUMNS, else a roomy default (piped output shouldn't wrap at 80).
+      def self.terminal_width(io = $stdout, env: ENV, default: 120)
+        return Integer(env["COLUMNS"], exception: false) || default unless io.tty?
+
+        require "tty-screen"
+        TTY::Screen.width
+      end
+
+      # rows rendered for the terminal, under title when given: colored when io
+      # is a tty and NO_COLOR is unset.
+      def self.draw(rows, title: nil, io: $stdout)
+        table = new(rows, color: io.tty? && !ENV.key?("NO_COLOR"), width: terminal_width(io)).render
+        [title, table].compact.join("\n")
+      end
+
+      # color: styles the header, state and last exit with ANSI codes.
+      def initialize(rows, color:, width:)
+        require "pastel"
+
+        @cells  = rows.map { |row| row.values_at(:name, :command, :schedule, :state, :last_exit) }
+        @pastel = Pastel.new(enabled: color)
+        @width  = width
+        @column_widths = natural_widths
+        shrink_widest while overflowing? && shrinkable?
+      end
+
+      def render
+        require "tty-table"
+
+        grid = TTY::Table.new(header: HEADERS.map { |text| @pastel.bold(text) }, rows: @cells.map { |cells| styled(cells) })
+        grid.render(:unicode, multiline: true, resize: true, width: total_width, column_widths:, padding: [0, 1]).to_s
+      end
+
+      # Width of each column, padding included. Every column starts at its
+      # natural width; when the table would be wider than the screen, the
+      # flexible columns give up a character at a time until it fits.
+      attr_reader :column_widths
+
+      # Rendered width: the columns plus their borders.
+      def total_width = column_widths.sum + BORDERS
+
+      private
+
+      def natural_widths = [HEADERS, *@cells].transpose.map { |column| column.max_by(&:length).length + EXTRA }
+
+      def overflowing? = total_width > @width
+
+      def widest_flexible = FLEXIBLE.max_by { |index| @column_widths[index] }
+
+      def shrinkable? = @column_widths[widest_flexible] > MIN_WIDTH
+
+      def shrink_widest = @column_widths[widest_flexible] -= 1
+
+      def styled(cells)
+        *lead, state, last_exit = cells
+        state_color = { "active" => :green, "stopped" => :yellow }.fetch(state, :red)
+        exit_color  = last_exit.match?(/\A[1-9]\d*\z/) ? :red : :dim
+        [*lead, @pastel.decorate(state, state_color), @pastel.decorate(last_exit, exit_color)]
+      end
+    end
+  end
+end

data/lib/asgard/schedule.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "schedule/declaration"
+require_relative "schedule/launchd"
+require_relative "schedule/systemd"
+require_relative "schedule/table"
+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/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.3"
+  VERSION = "0.4.1"
 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,15 +9,16 @@ 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
     loki_up
   end
 
+  # `asgard schedule list` reports every project's scheduled entries, so it
+  # works from a directory with no .loki above it.
+  def self.machine_wide?(argv) = argv.first(2) == %w[schedule list]
+
   # Main entry point invoked by the asgard executable.
   def self.run!(argv)
     first = argv.first
@@ -29,13 +31,19 @@ module Asgard
       Asgard::Doctor.new.run
       exit
     end
-    task_file = find_task_file or abort "asgard: no .loki file found in #{Dir.pwd}"
+    task_file = find_task_file
+    abort "asgard: no .loki file found in #{Dir.pwd}" unless task_file || machine_wide?(argv)
     before = Asgard::Base.subclasses.dup
-    load task_file
+    load task_file if task_file
     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