asgard 0.4.0 → 0.5.0

data/examples/watcher_examples/README.md

@@ -0,0 +1,112 @@
+# Watcher example
+
+A small project whose tasks run when its files change. The `.loki` here
+declares four watches; `lib/`, `bin/`, `docs/` and `data/` hold one
+placeholder file each so the watcher has something to watch right away.
+
+## Before you start
+
+The watcher runs its daemon and every triggered task as separate `asgard`
+processes. If you are running asgard from a git checkout of this
+repository rather than an installed gem, install the checkout as the gem
+first, from the repository root:
+
+```bash
+asgard install        # builds pkg/asgard-<version>.gem and gem-installs it
+gem list asgard       # the checkout's version should be listed
+```
+
+Otherwise an older asgard gem already on the machine can be the one the
+spawned processes run, and it will not understand `watch`.
+
+## Walkthrough
+
+From this directory:
+
+```bash
+asgard watcher start
+```
+
+```
+started watcher for watcher_examples (pid 12345); log: ~/.local/state/asgard/watch/watcher-examples/watcher.log
+```
+
+Now make some changes and watch the log fill up:
+
+```bash
+echo '# a change' >> lib/greeter.rb         # lint runs, with the path in changes.modified
+echo 'more' >> docs/index.md               # docs runs; BUILD_ENV=demo comes from env:
+echo 'more' >> docs/drafts/ideas.md        # nothing: drafts/ is ignored
+echo '{}' > data/new.json                  # reindex runs: a file was added
+echo '{"edited": true}' > data/new.json    # nothing: events: is added and removed only
+rm data/new.json                           # reindex runs again: a file was removed
+asgard watcher log
+```
+
+```
+2026-10-18 23:40:01 trigger lint task=lint lib/greeter.rb
+2026-10-18 23:40:01 spawn lint task=lint pid=12351 lib/greeter.rb
+lint: lib/greeter.rb (7 lines) triggered by lint
+2026-10-18 23:40:02 exit lint task=lint pid=12351 status=0 seconds=0.41
+2026-10-18 23:40:05 trigger docs task=docs docs/index.md
+2026-10-18 23:40:05 spawn docs task=docs pid=12360 docs/index.md
+docs: building for demo; changed: docs/index.md
+2026-10-18 23:40:06 exit docs task=docs pid=12360 status=0 seconds=0.40
+2026-10-18 23:40:09 trigger reindex task=reindex data/new.json
+2026-10-18 23:40:09 spawn reindex task=reindex pid=12371 data/new.json
+reindex: 1 added, 0 removed; 2 data file(s) now
+2026-10-18 23:40:10 exit reindex task=reindex pid=12371 status=0 seconds=0.40
+...
+```
+
+Each trigger line names the entry and the changed paths. Each spawn and
+exit line carries the task's pid, so the lines of overlapping tasks can be
+told apart; a task's own output sits between its spawn and its exit. Save
+`lib/greeter.rb` twice in quick succession and the second trigger says
+`(queued behind pid N)`: the same task never overlaps itself, while
+different tasks run at the same time.
+
+```bash
+asgard watcher list
+```
+
+```
+┌──────────┬────────────────┬──────────────────────────────────────┬──────────┬────────────────────────────────┐
+│ NAME     │ TASK           │ WATCHES                              │ DAEMON   │ LAST RUN                       │
+├──────────┼────────────────┼──────────────────────────────────────┼──────────┼────────────────────────────────┤
+│ lint     │ asgard lint    │ lib/**/*.rb                          │ running  │ 0 (0.4s, 2026-10-18 23:40:02)  │
+│ docs     │ asgard docs    │ docs                                 │ running  │ 0 (0.4s, 2026-10-18 23:40:06)  │
+│ reindex  │ asgard reindex │ data/**/*.json [added, removed]      │ running  │ 0 (0.4s, 2026-10-18 23:40:14)  │
+│ lint-bin │ asgard lint    │ bin/**/*                             │ running  │ never                          │
+└──────────┴────────────────┴──────────────────────────────────────┴──────────┴────────────────────────────────┘
+```
+
+```bash
+asgard watcher stop
+```
+
+A task that is still running finishes first; `stop` names it while it
+waits.
+
+## Running the tasks by hand
+
+Every task works without the watcher too. `changes` is then empty, which
+`lint` turns into "lint everything":
+
+```bash
+asgard lint
+asgard docs
+asgard reindex
+```
+
+## What the watcher restricts
+
+A triggered task does not inherit the shell the watcher was started from.
+It sees `PATH`, `HOME`, `USER`, `LANG` and a few other basics, the entry's
+`env:`, a project `.envrc` through `direnv`, and the trigger variables
+`ASGARD_WATCH`, `ASGARD_WATCH_ROOT`, `ASGARD_MODIFIED`, `ASGARD_ADDED` and
+`ASGARD_REMOVED`. `asgard watcher preview` prints the exact command and
+environment each entry would run.
+
+Edit `.loki` while the watcher runs and it restarts itself with the new
+declarations.

data/examples/watcher_examples/bin/hello

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Edit this file while the watcher runs: the lint-bin entry picks it up.
+echo "hello from bin/"

data/examples/watcher_examples/data/records.json

@@ -0,0 +1 @@
+{ "records": ["one", "two"] }

data/examples/watcher_examples/docs/drafts/ideas.md

@@ -0,0 +1,5 @@
+# Drafts are ignored
+
+Editing this file never triggers the docs entry: its declaration has
+`ignore: %r{\Adrafts/}`.
+more

data/examples/watcher_examples/docs/index.md

@@ -0,0 +1,4 @@
+# Watcher example
+
+Edit this file while the watcher runs: the docs entry picks it up.
+more

data/examples/watcher_examples/lib/greeter.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Edit this file while the watcher runs: the lint entry picks it up.
+module Greeter
+  def self.greet(name) = "Hello, #{name}!"
+end
+# a change

data/lib/asgard/kernel_methods.rb

@@ -16,6 +16,12 @@ module Kernel
   end
   module_function :env
 
+  # The files the watcher saw change when it triggered this task, as an
+  # Asgard::Changes (modified, added, removed, all). Every list is empty
+  # when the task is run by hand.
+  def changes = Asgard::Changes.current
+  module_function :changes
+
   def loki_up(name = ".loki")
     dir = Pathname.new(Dir.pwd)
     loop do

data/lib/asgard/schedule/commands.rb

@@ -54,6 +54,11 @@ module Asgard
 
         def schedule_summary(spec) = "#{Schedule.command_line(spec[:task], spec[:args])} (#{Schedule.describe(**spec)})"
 
+        # One `list` row for this project: its declaration (if still declared) plus live state.
+        def schedule_row(name)
+          { name:, **Schedule.declared_columns(schedules[name], "no longer declared"), **Schedule.live_columns(scheduler, name) }
+        end
+
         def schedule_install(spec, asgard:, direnv:)
           name  = spec[:name]
           state = scheduler.install(spec, asgard:, direnv:)
@@ -65,16 +70,6 @@ module Asgard
           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"
@@ -100,61 +95,132 @@ module Asgard
         scheduler.notes.each { |note| $stderr.puts note }
       end
 
+      no_commands do
+        # [backend, entry name] for an installed entry of this or any project: a
+        # bare name, or project/name when several projects use the same one. nil if none.
+        def find_installed(name)
+          return [scheduler, name] if scheduler.installed_names.include?(name)
+
+          project, entry = name.include?("/") ? name.split("/", 2) : [nil, name]
+          matches = scheduler.installed_entries.select { |slug, found| found == entry && (project.nil? || slug == project) }
+          abort "#{name} is in several projects (#{matches.map(&:first).join(', ')}); name one as project/#{entry}." if matches.size > 1
+
+          matches.first&.then { |slug, found| [backend_for(slug), found] }
+        end
+
+        def resolve_installed(name) = find_installed(name) || abort("#{name} is not installed (see `asgard schedule list --all`).")
+
+        # Like resolve_installed, but a declared entry of this project counts even before it is installed.
+        def resolve_known(name)
+          return [scheduler, name] if schedules.key?(name)
+
+          find_installed(name) || abort("#{name} is neither declared nor installed (see `asgard schedule list --all`).")
+        end
+
+        # True when list should cover every project: asked for with --all, or
+        # there is no .loki here, so no single project to scope to.
+        def list_all? = options[:all] || Asgard.find_task_file.nil?
+
+        # What `list` says when there is nothing to show; a project-scoped list
+        # also tells the user how to look further.
+        def no_schedules_message
+          backend = scheduler.scheduler
+          return "No scheduled tasks installed (#{backend})." if list_all?
+
+          "No scheduled tasks installed for #{schedule_project} (#{backend}).\n" \
+            "Use `asgard schedule list --all` to see all currently scheduled tasks."
+        end
+
+        # The rows to list, grouped under a project title: { "Project: name (/path)" => [row, ...] }
+        # for every project, or { nil => [row, ...] } for this one. Empty groups drop out.
+        def list_groups
+          groups = list_all? ? all_schedule_groups : { nil => scheduler.installed_names.map { |name| schedule_row(name) } }
+          groups.reject { |_, rows| rows.empty? }
+        end
+
+        # Every installed entry on the machine, grouped by project.
+        def all_schedule_groups
+          by_project = scheduler.installed_entries.group_by(&:first)
+          by_project.to_h { |slug, entries| [project_title(slug, entries.first.last), entry_rows(entries)] }
+        end
+
+        # "Project: slug (/full/path)", the path read from one of the project's job files.
+        def project_title(slug, name)
+          dir = slug == current_slug ? schedule_root : backend_for(slug).installed_directory(name)
+          ["Project: #{slug}", ("(#{dir})" if dir)].compact.join(" ")
+        end
+
+        def current_slug = Asgard.find_task_file && Schedule.slug(schedule_project)
+
+        def backend_for(slug) = Schedule.backend_class.new(project: slug, root: schedule_root)
+
+        def entry_rows(entries) = entries.map { |slug, name| entry_row(slug, name) }
+
+        # This project's entries keep their declaration columns; see other_project_row.
+        def entry_row(slug, name)
+          return schedule_row(name) if slug == current_slug
+
+          other_project_row(slug, name)
+        end
+
+        # A row for an entry of another project: its .loki isn't loaded, so the
+        # command and schedule are read back from the installed job files.
+        def other_project_row(slug, name)
+          backend = backend_for(slug)
+          shown   = backend.installed_columns(name) || Schedule.declared_columns(nil, "(unreadable)")
+          { name:, **shown, **Schedule.live_columns(backend, name) }
+        end
+      end
+
       desc "list", "Show this project's installed entries, their state, and last exit status"
+      method_option :all, aliases: "-a", type: :boolean, desc: "List every project's entries, not just this one's"
       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
+        groups = list_groups
+        return puts(no_schedules_message) if groups.empty?
+
+        puts groups.map { |title, rows| Schedule::Table.draw(rows, title:) }.join("\n\n")
+        puts "\nLogs: #{File.dirname(scheduler.log_path(groups.values.first.first[:name]))}  (asgard schedule log NAME)"
       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)
+        backend, entry = resolve_installed(name)
+        backend.stop(entry)
         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]
+        backend, entry = resolve_known(name)
+        own  = backend.equal?(scheduler)
+        spec = schedules[entry] if own
 
         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"
+          why = own ? "is no longer declared" : "belongs to another project"
+          $stderr.puts "schedule: #{name} #{why}; starting its installed job as-is"
         end
-        scheduler.start(name)
+        backend.start(entry)
         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
+        backend, entry = resolve_installed(name)
+        abort "#{name} is stopped; `asgard schedule start #{name}` first." if backend.status(entry)[:state] == :stopped
 
-        scheduler.trigger(name)
-        puts "triggered #{name}; output goes to #{scheduler.log_path(name)}"
+        backend.trigger(entry)
+        puts "triggered #{name}; output goes to #{backend.log_path(entry)}"
       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)
+        backend, entry = resolve_known(name)
 
-        path = scheduler.log_path(name)
+        path = backend.log_path(entry)
         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]
 

data/lib/asgard/schedule/declaration.rb

@@ -24,6 +24,9 @@ module Asgard
   #   #start(name) / #stop(name)          # stop persists across reboots and reinstalls
   #   #trigger(name)                      # run once now, under the scheduler
   #   #installed_names                    # => ["demo", ...] for this project
+  #   #installed_entries                  # => [[project_slug, "demo"], ...] for every project
+  #   #installed_columns(name)            # => { command:, schedule: } read back from the job files, or nil
+  #   #installed_directory(name)          # => the project root the job runs in, or nil
   #   #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
@@ -121,6 +124,64 @@ module Asgard
       "#{Array(at).join(', ')} #{Array(on).join(', ')}"
     end
 
+    # For the `list` table: like describe, but a run of hourly times
+    # collapses ("10:00, 11:00 ... 17:00" => "10:00-17:00 hourly").
+    def describe_compact(at: nil, on: :daily, every: nil, **)
+      return "every #{every}s" if every
+
+      "#{compact_times(Array(at))} #{Array(on).join(', ')}"
+    end
+
+    # The command and schedule columns of a `list` row for a declared entry.
+    def list_columns(spec) = { command: command_line(spec[:task], spec[:args]), schedule: describe_compact(**spec) }
+
+    # The command and schedule columns of a `list` row: the declaration's, or
+    # `missing` in the schedule column when there is none.
+    def declared_columns(spec, missing) = spec ? list_columns(spec) : { command: "-", schedule: missing }
+
+    # The state and last-exit columns of a `list` row, from a backend's live status.
+    def live_columns(backend, name)
+      state, last_exit = backend.status(name).values_at(:state, :last_exit)
+      { state: state.to_s.tr("_", " "), last_exit: state == :active ? (last_exit || "never run") : "-" }
+    end
+
+    # The command a job runs, from its program arguments: everything from
+    # `asgard` on, so a direnv wrapper and the asgard install path drop out.
+    def command_from_arguments(arguments)
+      start = arguments.index { |word| File.basename(word) == "asgard" }
+      Shellwords.join(["asgard", *arguments.drop(start ? start + 1 : 0)])
+    end
+
+    # describe_compact for calendar entries (the shape `calendar` returns), one
+    # group per distinct set of days: "17:30 weekdays; 09:00 saturday".
+    def describe_calendar(entries)
+      entries.group_by { |entry| entry[:days]&.sort }.map { |days, group| describe_days(days, group) }.join("; ")
+    end
+
+    def describe_days(days, group)
+      describe_compact(at: group.map { |entry| format("%<hour>02d:%<minute>02d", entry) }, on: day_names(days))
+    end
+
+    # The command and schedule columns for a job read back from its files.
+    def installed_columns(arguments:, calendar:, every:)
+      { command: command_from_arguments(arguments), schedule: every ? "every #{every}s" : describe_calendar(calendar) }
+    end
+
+    # Weekday numbers back to what on: took: nil => :daily, [1, 2, 3, 4, 5] => :weekdays, [5] => [:friday].
+    def day_names(days)
+      return :daily unless days
+
+      names = days.map { |day| DAYS.fetch(day) }
+      DAY_GROUPS.key(names) || names
+    end
+
+    def compact_times(times)
+      parsed = times.map { |time| parse_time(time) }
+      hourly = parsed.size >= 3 && parsed.map(&:last).uniq.size == 1 &&
+               parsed.each_cons(2).all? { |(hour, _), (next_hour, _)| next_hour == hour + 1 }
+      hourly ? "#{times.first}-#{times.last} hourly" : times.join(", ")
+    end
+
     # "17:30" => [17, 30]
     def parse_time(time)
       shown = time.inspect

data/lib/asgard/schedule/launchd.rb

@@ -64,6 +64,40 @@ module Asgard
         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 ------------------------------------------------------
@@ -136,6 +170,27 @@ module Asgard
         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

data/lib/asgard/schedule/systemd.rb

@@ -76,6 +76,30 @@ module Asgard
         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? }
 
@@ -156,6 +180,29 @@ module Asgard
         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

data/lib/asgard/schedule/table.rb

@@ -0,0 +1,79 @@
+# 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. headers: relabels the five columns.
+      def self.draw(rows, title: nil, io: $stdout, headers: HEADERS)
+        table = new(rows, color: io.tty? && !ENV.key?("NO_COLOR"), width: terminal_width(io), headers:).render
+        [title, table].compact.join("\n")
+      end
+
+      # color: styles the header, state and last exit with ANSI codes.
+      def initialize(rows, color:, width:, headers: HEADERS)
+        require "pastel"
+
+        @headers = headers
+        @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, "running" => :green, "stopped" => :yellow }.fetch(state, :red)
+        exit_color  = last_exit.match?(/\A[1-9]\d*\b/) ? :red : :dim
+        [*lead, @pastel.decorate(state, state_color), @pastel.decorate(last_exit, exit_color)]
+      end
+    end
+  end
+end

data/lib/asgard/schedule.rb

@@ -3,6 +3,7 @@
 require_relative "schedule/declaration"
 require_relative "schedule/launchd"
 require_relative "schedule/systemd"
+require_relative "schedule/table"
 require_relative "schedule/commands"
 
 module Asgard

data/lib/asgard/tasks.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "schedule"
+require_relative "watch"
 
 # 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.
@@ -38,10 +39,18 @@ class Tasks < Asgard::Base
   # Class-level `schedule :task, at: "HH:MM"` declarations (see Asgard::Schedule).
   extend Asgard::Schedule::DSL
 
+  # Class-level `watch :task, paths: "lib"` declarations (see Asgard::Watch).
+  extend Asgard::Watch::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" }
+
+  desc "watcher SUBCOMMAND", "Run and manage the file watcher declared with `watch :task, paths: ...`"
+  subcommand "_watcher", Asgard::Watch::Commands
+  map "watcher" => :_watcher
+  Asgard::Watch::Commands.commands.each_value { |command| command.ancestor_name = "watcher" }
 end