asgard 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1c6d1f87eea50ba02ac92aff8d7822f9106a7a99afa5ff5c44c7faa7b5e9c87
-  data.tar.gz: dcd334548a5a8d67688cd139482d6a0a3a3ce77c0aa59b2515e81d568849356f
+  metadata.gz: e81b8d0d4ce7904a7483a06348d488730f258171af1d0d6897a99fc058829d91
+  data.tar.gz: a25c7c2dccc05df8ac533a17a118f93361aa8eabbb6ad8fde36af65088107cb2
 SHA512:
-  metadata.gz: b45b01bc870415ee36a931278c88ed251c8723a36e7795c6a36d0a142ce5a93822db91e96a099045ef5d35137cd86bc2ce571a37faea7b93818de94be78daca1
-  data.tar.gz: 837ab94dabc90b119831d2effc0c4dba00b55fc5a7cd1221d4cc16799f4376985a4dc5150673ca1e5910d6f1932a04d8782d6a87c6883342b312836e921dc40b
+  metadata.gz: ee9be83865e0fa5a50e5fac52e6d720e7d76b3da4f56790d8badb708a93d603d30628c5a960f1aca209f030f89b34c726f151caa3b6c337be4e69b1c00c15fb1
+  data.tar.gz: 9741a4dcac57f091e00a5f6b84f1cd70d5c5e9c04b2059a8483edbb17166fca17762d38d6161eea6fd294e09fcc129394fce88c58c53a7d240d1eb664ca5d750

data/.loki

@@ -19,6 +19,9 @@ class Tasks
   @@project      ||= "asgard".freeze
   @@project_desc ||= "CLI-task runner"
 
+  # Dogfood: `asgard watcher start` reruns the tests whenever a Ruby file changes.
+  watch :test_check, paths: %w[lib test], only: /\.rb\z/
+
   desc "xyzzy"
   def xyzzy = puts "everything in Ruby metaprogramming is magic"
 

data/.reek.yml

@@ -21,6 +21,8 @@ detectors:
   # Default is 4 — Doctor legitimately tracks several pieces of diagnostic state.
   TooManyInstanceVariables:
     max_instance_variables: 6
+    exclude:
+      - Asgard::Watch::Daemon  # wires reporter, dispatcher, listeners, inbox and the stop flag for one run
 
   # Accept standard Ruby short-name conventions for limited-scope variables.
   UncommunicativeVariableName:
@@ -57,6 +59,7 @@ detectors:
       - Asgard::Shell#sh
       - Asgard::Shell#shebang
       - Asgard::Schedule#entry_name                 # as: is the user's explicit override of the derived name
+      - Asgard::Watch#normalize                     # same: as: overrides the task name as the entry name
 
   DuplicateMethodCall:
     exclude:
@@ -114,9 +117,11 @@ detectors:
       - Asgard::Base::Dispatch#with_dep_results        # same: stashes results on Thread.current, not self
       - Asgard::Shell#shell_argv                       # extracted pure on purpose so it's testable without invoking system/exec
       - Asgard::Schedule::DSL#schedule                 # class-level DSL delegating to the Schedule registry
+      - Asgard::Watch::DSL#watch                       # same, for the Watch registry
       - Asgard::Schedule::Commands#schedules           # Thor no_commands helpers: reads of the registry / CWD shared by the subcommands
       - Asgard::Schedule::Commands#schedule_root
       - Asgard::Schedule::Commands#schedule_summary
+      - Asgard::Watch::Commands#watches                # same: the Watch registry read by every subcommand
 
   # Asgard::Schedule: the backends implement a fixed API (see
   # lib/asgard/schedule/declaration.rb) plus pure, separately tested helpers,
@@ -125,16 +130,21 @@ detectors:
   DataClump:
     exclude:
       - Asgard::Schedule                            # at:/on: and task/args are the declaration's vocabulary
+      - Asgard::Watch::Spawn                        # spec + context are the two inputs of every spawn function
 
   LongParameterList:
     exclude:
       - Asgard::Schedule#normalize                  # the `schedule` DSL keywords
+      - Asgard::Watch#normalize                     # the `watch` DSL keywords
       - Asgard::Schedule#describe
       - Asgard::Schedule#program_arguments
+      - Asgard::Schedule::Table#self.draw            # rows plus the title, io and headers the caller chooses
       - Asgard::Schedule::Launchd#self.plist        # one keyword per plist field
       - Asgard::Schedule::Systemd#self.service_unit # one keyword per unit field
       - Asgard::Schedule::Systemd#self.timer_unit
       - Asgard::Schedule::Systemd#initialize        # injectable home/runner/env/user for tests
+      - Asgard::Watch::Dispatcher#initialize        # injectable worker starter and clock for tests
+      - Asgard::Watch::Daemon#initialize            # injectable listen/exec/out for tests
 
   RepeatedConditional:
     exclude:
@@ -143,8 +153,10 @@ detectors:
   TooManyMethods:
     exclude:
       - Asgard::Schedule::Commands                  # one method per subcommand plus its helpers
+      - Asgard::Watch::Commands                     # same
       - Asgard::Schedule::Launchd                   # backend API + pure helpers
       - Asgard::Schedule::Systemd
+      - Asgard::Watch::State                        # one reader/writer pair per file it keeps
 
 
 exclude_paths:

data/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - Unreleased
+
+### Added
+
+- **Watched files, built in** — `watch :task, paths: "lib/**/*.rb"` at class
+  level in a `.loki` declares that a task runs when matching files change,
+  with `only:`, `ignore:`, `events:`, `debounce:`, `env:` and `as:` keywords.
+  `asgard watcher start|stop|list|preview|log|run` manages the watcher: one
+  background process per project that runs each trigger as `asgard <task>`
+  from the project root, with a fixed environment (a whitelist of the
+  daemon's variables, the entry's `env:`, `.envrc` through `direnv exec`) plus
+  the changed paths in `ASGARD_MODIFIED`, `ASGARD_ADDED` and `ASGARD_REMOVED`.
+  Different tasks run concurrently; the same task never overlaps itself, and a
+  trigger that arrives while its task runs is queued behind it. Saving a
+  `.loki` file restarts the watcher with the new declarations. `stop` lets a
+  running task finish. `list` shows each entry's last run; `--all` covers
+  every project. State and logs live under `~/.local/state/asgard/watch/`.
+  The command is registered as the gem-owned `_watcher` and mapped to
+  `watcher`. The daemon and every trigger run the same `asgard` executable
+  that started the watcher, by absolute path, even under `direnv exec`.
+  See [Watched Files](https://madbomber.github.io/asgard/watch/).
+- **`changes`** Kernel method — inside a task, the `Asgard::Changes` the
+  watcher triggered it with (`modified`, `added`, `removed`, `all`,
+  `empty?`); every list is empty when the task is run by hand.
+- **`Asgard::Watch::Error`** (subclass of `Asgard::Error`) — raised when a
+  `watch` names a task the project does not define.
+
+### Changed
+
+- New runtime dependencies: `listen` (file events) and `ractor_queue` (the
+  queue between the daemon and its worker Ractors). `ractor_queue` is a
+  native extension, so `gem install asgard` now compiles and needs a C++17
+  compiler; Asgard was pure Ruby before.
+- `Asgard::Schedule::Table.draw` takes `headers:` so `watcher list` can
+  reuse it; a `running` state renders green.
+- `Asgard.machine_wide?` is true for `watcher list` as well as
+  `schedule list`, so both work from a directory with no `.loki` above it.
+
 ## [0.4.1] - 2026-10-02
 
 ### Added
@@ -331,6 +369,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 100% test coverage enforced via SimpleCov (95% minimum threshold)
 - Quality task in `.loki` runs flog after tests
 
+[0.5.0]: https://github.com/MadBomber/asgard/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/MadBomber/asgard/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/MadBomber/asgard/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/MadBomber/asgard/compare/v0.2.0...v0.3.3
 [0.2.0]: https://github.com/MadBomber/asgard/compare/v0.1.2...v0.2.0

data/CLAUDE.md

@@ -47,6 +47,14 @@ Single file: `ruby -Ilib:test test/test_asgard.rb` (a single file alone will fal
 | `lib/asgard/schedule/declaration.rb` | Pure declaration validation + the backend API contract |
 | `lib/asgard/schedule/launchd.rb`, `systemd.rb` | Platform backends; shell out through an injectable runner |
 | `lib/asgard/schedule/commands.rb` | `asgard schedule ...` subcommands (registered as `_schedule`, mapped to `schedule`) |
+| `lib/asgard/watch.rb` | `Asgard::Watch` — the `watch` DSL registry; requires the files below |
+| `lib/asgard/watch/declaration.rb` | Pure declaration validation: globs to directories plus `only:` Regexps, events, ignores |
+| `lib/asgard/watch/changes.rb` | `Asgard::Changes` (the trigger's path lists) and `Watch.filter_events` |
+| `lib/asgard/watch/spawn.rb` | Pure: the frozen, Ractor-shareable description of one task run (argv, whitelisted env) |
+| `lib/asgard/watch/worker.rb` | One Ractor per task; runs its triggers serially and reports each spawn and exit |
+| `lib/asgard/watch/reporter.rb`, `dispatcher.rb` | Single writer of log and entry records; batch routing to worker queues |
+| `lib/asgard/watch/state.rb`, `daemon.rb` | Pidfile, log and records under XDG state; the foreground `watcher run` process |
+| `lib/asgard/watch/commands.rb` | `asgard watcher ...` subcommands (registered as `_watcher`, mapped to `watcher`) |
 
 ### Naming Convention for Gem-Owned Methods
 
@@ -98,6 +106,7 @@ Asgard adds the following `module_function` methods to `Kernel`, making them ava
 | Method | Description |
 |--------|-------------|
 | `env(name, default = nil)` | Fetch a system environment variable by symbol or string; name is upcased automatically. Raises `KeyError` when missing and no default given. |
+| `changes` | The `Asgard::Changes` a watcher trigger passed in (`modified`, `added`, `removed`, `all`, `empty?`); every list is empty when the task is run by hand. |
 | `loki_up(name = ".loki")` | Walk CWD and ancestors for a file by name; returns absolute path or `nil`. |
 | `import(path)` | Load a `.loki` file or glob of `.loki` files, idempotently. |
 | `import_up(name = ".loki")` | Combine `loki_up` and `import` — find and load in one call. |
@@ -106,7 +115,7 @@ Asgard adds the following `module_function` methods to `Kernel`, making them ava
 
 ## Testing
 
-Engine tests are in `test/test_asgard.rb`; scheduling tests are in `test/test_schedule.rb`, which uses a `FakeRunner` (records launchctl/systemctl argv) so both backends test on any platform. SimpleCov minimum is 95%; the Rakefile configures this with a prelude that loads coverage before the library.
+Engine tests are in `test/test_asgard.rb`; scheduling tests are in `test/test_schedule.rb`, which uses a `FakeRunner` (records launchctl/systemctl argv) so both backends test on any platform. Watcher tests are in `test/test_watcher.rb`: pure functions directly, the worker and reporter loops in threads with recording stand-ins, and a few real-process tests (a real Ractor worker, a real daemon with a fake Listen, one real Listen run) with no mocks. SimpleCov minimum is 95%; the Rakefile configures this with a prelude that loads coverage before the library.
 
 Key test patterns: tests frequently subclass `Asgard::Base` directly (not `Tasks`) to test the engine in isolation, and use `capture_io` for output assertions.
 

data/README.md

@@ -24,6 +24,7 @@
 - <strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories<br>
 - <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded via <code>import</code> from your <code>.loki</code><br>
 - <strong>Scheduled Tasks</strong> — run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code><br>
+- <strong>Watched Files</strong> — run any task when files change with <code>watch</code> and <code>asgard watcher start</code>; the task reads what changed through <code>changes</code><br>
 - <strong>Built-in Flags</strong> — <code>--debug</code>, <code>--verbose</code>, <code>--version</code>, and <code>--doctor</code> built-in class options; header/footer DSL for static help text<br>
 </td>
 </tr>
@@ -642,6 +643,42 @@ the `PATH` captured at install time; a project `.envrc` is loaded at run time
 through `direnv exec`. See [Scheduled Tasks](https://madbomber.github.io/asgard/schedule/)
 for every keyword, entry naming, and file locations.
 
+## Watched files
+
+Any task can run when files change. Declare what each task watches at class
+level in `.loki`:
+
+```ruby
+class Tasks
+  watch :lint, paths: "lib/**/*.rb"
+  watch :test, paths: %w[lib test], only: /\.rb\z/
+  watch :reindex, paths: "data/**/*.json", events: %i[added removed]
+
+  desc "lint", "Lint whatever changed"
+  def lint
+    files = changes.modified + changes.added   # empty when run by hand
+    sh "rubocop #{files.shelljoin}" unless files.empty?
+  end
+end
+```
+
+Then manage the watcher with the built-in `watcher` command:
+
+```bash
+asgard watcher start        # watch this project in the background
+asgard watcher stop         # stop it; a task already running finishes first
+asgard watcher list         # watches, daemon state, each entry's last run (--all: every project's)
+asgard watcher preview      # the command and environment each watch would run
+asgard watcher log [-f]     # print (or follow) the watcher's log
+```
+
+Each trigger runs `asgard <task>` from the project root with a fixed
+environment plus the changed paths in `ASGARD_MODIFIED`, `ASGARD_ADDED` and
+`ASGARD_REMOVED`. Different tasks run concurrently; the same task never
+overlaps itself. Saving a `.loki` file restarts the watcher with the new
+declarations. See [Watched Files](https://madbomber.github.io/asgard/watch/)
+for every keyword, the environment, and file locations.
+
 ## `method_option` types reference
 
 | Type | CLI example | Ruby value |

data/docs/api.md

@@ -40,6 +40,7 @@ These methods are defined as `module_function` on `Kernel` and are therefore ava
 | `loki_up` | `loki_up(name = ".loki") → Pathname, nil` | `Pathname` or `nil` | Searches `Dir.pwd` and each ancestor directory for a file named `name`. Returns a `Pathname` for the first match, or `nil` if not found. Exact filenames only — does not expand globs. |
 | `import` | `import(path) → true, false` | `true` if any file newly loaded | Loads one `.loki` file or a glob of `.loki` files. Relative paths resolve relative to the caller's file (like `require_relative`). Idempotent via `$LOADED_FEATURES`. Raises `ArgumentError` if `path` does not end with `.loki`. Raises `LoadError` if a non-glob path does not exist. |
 | `import_up` | `import_up(name = ".loki") → true, false` | `true` if any file newly loaded | Combines `loki_up` and `import`. Walks ancestors to find the file or glob match, then loads it. Returns `false` if nothing is found. |
+| `changes` | `changes → Asgard::Changes` | `Asgard::Changes` | The files the watcher saw change when it triggered this task: `modified`, `added`, `removed`, `all`, `empty?`. Read once per process from `ASGARD_MODIFIED`, `ASGARD_ADDED` and `ASGARD_REMOVED`; every list is empty when the task is run by hand. See [`Asgard::Watch`](#asgardwatch). |
 | `debug?` | `debug? → true, false` | `$DEBUG` | Returns the current value of `$DEBUG`. Set to `true` by `--debug` on the CLI or directly via `$DEBUG = true`. |
 | `verbose?` | `verbose? → true, false` | `$VERBOSE` | Returns the current value of `$VERBOSE`. Set to `true` by `--verbose` on the CLI or directly via `$VERBOSE = true`. |
 | `env` | `env(name, default = nil) → String, nil` | `ENV` value or default | Fetches an environment variable by symbol or string name. The name is upcased automatically. Raises `KeyError` when the variable is missing and no default is given. |
@@ -202,6 +203,8 @@ See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-block-form)
 | `verbose?` | Kernel module function | Returns `$VERBOSE`. Available everywhere via `Kernel`. |
 | `schedule` | class method (DSL) | `schedule :task, at:/every:, ...` — declares a scheduled entry. Extended from `Asgard::Schedule::DSL`; see [`Asgard::Schedule`](#asgardschedule). |
 | `_schedule` | subcommand | `asgard schedule SUBCOMMAND`, backed by `Asgard::Schedule::Commands`. `map "schedule" => :_schedule` keeps the typed name `schedule`, and a user task named `schedule` cannot shadow it. |
+| `watch` | class method (DSL) | `watch :task, paths: ...` — declares a watched entry. Extended from `Asgard::Watch::DSL`; see [`Asgard::Watch`](#asgardwatch). |
+| `_watcher` | subcommand | `asgard watcher SUBCOMMAND`, backed by `Asgard::Watch::Commands`. `map "watcher" => :_watcher` keeps the typed name `watcher`. |
 
 ---
 
@@ -287,6 +290,23 @@ Both backends, `Asgard::Schedule::Launchd` and `Asgard::Schedule::Systemd`, impl
 
 ---
 
+## `Asgard::Watch`
+
+Watched files. The user-facing guide is [Watched Files](watch.md); this section covers the Ruby API.
+
+| Method | Signature | Description |
+|---|---|---|
+| `declare` | `Asgard::Watch.declare(task, **settings) → Hash` | What `Tasks.watch` calls. Validates via `normalize` and records the entry. Redeclaring an identical entry is a no-op; a different entry under the same name raises `ArgumentError`. |
+| `declarations` | `Asgard::Watch.declarations → Hash` | Declared entries for this run, keyed by entry name. |
+| `normalize` | `Asgard::Watch.normalize(task, paths:, only: nil, ignore: nil, events: :all, debounce: 0.5, env: {}, as: nil) → Hash` | Validates one declaration and returns `{ name:, task:, paths:, dirs:, only:, ignore:, events:, debounce:, env: }`: the directories listen watches and one `only:` Regexp (or nil) built from the globs and the declared filter. Pure, as are its helpers `split_glob`, `glob_regexp`, `combine_only` and `normalize_events`. |
+| `filter_events` | `Asgard::Watch.filter_events(batch, events) → Asgard::Changes, nil` | A listener batch narrowed to the entry's `events:`; `nil` when nothing is left. |
+
+`Asgard::Changes` is a `Data` class with `modified`, `added` and `removed` path lists, `all`, `empty?`, `to_env` (the three trigger variables) and `Changes.from_env(env = ENV)`. `Changes.current` is the per-process memo behind the `changes` Kernel method; `Changes.forget` clears it.
+
+The daemon is assembled from small classes, each testable alone: `Spawn` builds the frozen, Ractor-shareable description of one run (argv, whitelisted environment, root, log, changes); `Worker` runs one task's triggers serially in its own Ractor and reports every spawn and exit; `Dispatcher` routes listener batches to the worker queues; `Reporter` is the single writer of the log and the per-entry records and tracks in-flight pids; `State` owns the pidfile, log, recorded declarations and entry records under the XDG state directory; `Daemon` wires them to listen and handles signals and reloads.
+
+---
+
 ## `Asgard::Base` Internal Class Methods
 
 These are implementation details exposed for extensibility. Prefer the DSL methods above in normal use.
@@ -319,6 +339,7 @@ These are implementation details exposed for extensibility. Prefer the DSL metho
 |---|---|---|
 | `Asgard::Error` | `StandardError` | Base error class for all Asgard errors. |
 | `Asgard::Schedule::Error` | `Asgard::Error` | Raised when a `launchctl`/`systemctl` command fails, or on an unsupported platform. `run!` reports it as `asgard: <message>`. |
+| `Asgard::Watch::Error` | `Asgard::Error` | Raised when the watcher cannot run: a `watch` names a task the project does not define. `run!` reports it as `asgard: <message>`. |
 | `Asgard::CircularDependencyError` | `Asgard::Error` | Raised by `validate_deps!` when a cycle is detected in the dependency graph. `run!` catches this and calls `abort` with a clean message. |
 
 ```ruby

data/docs/index.md

@@ -19,6 +19,7 @@
 <li><strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories</li>
 <li><strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files loaded via <code>import</code></li>
 <li><strong>Scheduled Tasks</strong> — run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code></li>
+<li><strong>Watched Files</strong> — run any task when files change with <code>watch</code> and <code>asgard watcher start</code>; the task reads what changed through <code>changes</code></li>
 <li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, <code>--verbose</code>, and <code>--doctor</code> available on every task</li>
 </ul>
 </td>

data/docs/watch.md

@@ -0,0 +1,123 @@
+# Watched Files
+
+Asgard can run a task whenever files change. You declare what each task watches in the project's own `.loki`, and `asgard watcher start` runs a background process that listens for changes and runs the matching tasks, handing each one the list of changed files in a known, reproducible environment.
+
+Watching is built into the gem, so there is nothing to import or require. File events come from the [listen](https://github.com/guard/listen) gem: native adapters on macOS and Linux, polling elsewhere.
+
+---
+
+## Declaring Watches
+
+Call `watch` at class level inside `Tasks`:
+
+```ruby
+# .loki
+class Tasks
+  desc "lint", "Lint whatever changed"
+  def lint
+    files = changes.modified + changes.added
+    sh "rubocop #{files.shelljoin}" unless files.empty?
+  end
+
+  watch :lint,    paths: "lib/**/*.rb"
+  watch :test,    paths: %w[lib test], only: /\.rb\z/, ignore: %r{\Afixtures/}
+  watch :docs,    paths: "docs", env: { BUILD_ENV: "dev" }
+  watch :reindex, paths: "data/**/*.json", events: %i[added removed]
+  watch :lint,    paths: "bin/**/*", as: "lint-bin"
+end
+```
+
+| Keyword | Meaning |
+|---------|---------|
+| `paths:` | A directory, a file, or a glob relative to the project root, or an Array of them |
+| `only:` | Regexp or Array of Regexps a changed path must match (relative to the watched directory) |
+| `ignore:` | Regexp or Array of Regexps that silence a path, added to the defaults below |
+| `events:` | Which kinds of change count: `:changed`, `:added`, `:removed`, or `:all` (default); `:modified` means `:changed` |
+| `debounce:` | Seconds to wait after the last event before the task runs (default 0.5) |
+| `env:` | `{ "KEY" => "value" }`: environment variables added to the task |
+| `as:` | The entry's name (letters, digits, `_ . -`) |
+
+### Entry Names
+
+Every entry has a name, shown by `list` and in the log. It defaults to the task name. To watch one task from two declarations, give the second an `as:` name; declaring two *different* entries with the same name raises an error.
+
+### Paths, Patterns and Filters
+
+A glob such as `lib/**/*.rb` watches `lib` and keeps the paths that match the pattern, the way a shell would: `**` spans directories, `*` and `?` stay within one, `{a,b}` is an alternative. A plain file watches its directory and keeps just that name, so a file that does not exist yet can still be watched. A bare directory takes everything beneath it.
+
+`only:` combines with the patterns: a path must match one of the patterns *and* one of the `only:` expressions. Several patterns in one declaration are alternatives, and because the filter applies to every directory the declaration watches, `%w[lib/**/*.rb docs/**/*.md]` also accepts a `.md` file under `lib`.
+
+A bare directory cannot share a declaration with a pattern or a file, because the pattern would silently filter the directory too. Write the directory as `dir/**/*`, or declare it separately.
+
+### Default Ignores
+
+Every watch ignores `.git/`, `coverage/`, `pkg/`, `tmp/`, `log/` and `node_modules/` at any depth, plus listen's own defaults, so a task that writes its output inside the project never retriggers itself.
+
+---
+
+## Managing the Watcher
+
+`watcher` is also a command with subcommands:
+
+```bash
+asgard watcher start        # start the watcher for this project in the background
+asgard watcher stop         # stop it; a task already running finishes first
+asgard watcher list         # this project's watches, daemon state, each entry's last run (--all: every project's)
+asgard watcher preview      # the command and environment each watch would run
+asgard watcher log [-f]     # print (or follow) the watcher's log
+asgard watcher run          # watch in the foreground (what start runs detached)
+```
+
+The watcher watches its own `.loki` files too. Save one, and the running watcher restarts itself with the new declarations.
+
+`stop` never signals a running task. It stops listening, drops triggers that have not started, waits for in-flight tasks to exit (naming them while it waits), then exits. A task that hangs keeps `stop` waiting; kill the task and `stop` completes.
+
+---
+
+## How Tasks Run
+
+A trigger runs `asgard <task>` from the project root as a separate process, using the very `asgard` executable that started the watcher, by absolute path, so a different version installed elsewhere on `PATH` is never picked up. Different tasks run concurrently. The same task never overlaps itself: a trigger that arrives while its task is still running waits, and the log says `queued behind pid N`. Save three times during a long test run and three more runs follow, one at a time.
+
+Two declarations for the same task that both match a file run that task twice, back to back. A task's own `depends_on` runs inside its process as usual; the watcher does not collapse dependencies across entries.
+
+### The Environment
+
+The task sees the same environment whether the watcher was started from an interactive shell or from a service. Nothing else leaks in from the daemon.
+
+| Layer | Contents |
+|---|---|
+| Base | `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TMPDIR`, `SSH_AUTH_SOCK`, captured when the watcher starts |
+| Declared | The entry's `env:`; a project `.envrc` through `direnv exec` when direnv is on `PATH`; a `.env` through your `.loki`'s own `dotenv` call |
+| Trigger | `ASGARD_WATCH` (the entry name), `ASGARD_WATCH_ROOT`, and the changed paths in `ASGARD_MODIFIED`, `ASGARD_ADDED` and `ASGARD_REMOVED`, one path per line, relative to the root |
+
+### The `changes` Accessor
+
+Inside a task, `changes` returns what triggered it:
+
+```ruby
+changes.modified   # => ["lib/asgard/base.rb"]
+changes.added      # => []
+changes.removed    # => []
+changes.all        # => every path once, in that order
+changes.empty?     # => true when the task was run by hand
+```
+
+Every list is empty when the task is run from the command line, so one task body serves both.
+
+---
+
+## Files and Logs
+
+The watcher keeps its state outside the repository under `~/.local/state/asgard/watch/<project>/` (honors `XDG_STATE_HOME`): the pidfile, `watcher.log` with one line per trigger, spawn and exit plus every task's output, the declarations recorded at `start`, and one JSON record per entry with its last run. `asgard watcher list --all` reads those records for every project without loading any `.loki`.
+
+Running the watcher as a launchd or systemd service is not yet built in; `asgard watcher run` is the foreground process a service would keep alive.
+
+---
+
+## Requirements
+
+Watching needs Ruby 3.2 or later. The gem depends on `listen` and on `ractor_queue`, a native extension, so `gem install asgard` compiles it and needs a C++17 compiler on the machine.
+
+## Name Collisions
+
+The built-in command is registered as `_watcher` and mapped to `watcher`, following Asgard's `_` convention for gem-owned tasks. If your `.loki` defines its own `watcher` task, `asgard watcher` still dispatches to the built-in command.

data/examples/.envrc

@@ -0,0 +1,3 @@
+# asgard/examples/.envrc
+
+source_up

data/examples/watcher_examples/.envrc

@@ -0,0 +1,3 @@
+# asgard/examples/watcher_examples/.envrc
+
+source_up

data/examples/watcher_examples/.loki

@@ -0,0 +1,54 @@
+# examples/watcher_examples/.loki
+# A small project whose tasks run when its files change.
+#
+# `watch :task, paths: ...` at class level says which files a task cares
+# about. `asgard watcher start` runs one background process for this
+# project that listens for changes and runs the matching tasks, each as a
+# separate `asgard <task>` process started from this directory. The task
+# reads what changed through `changes`.
+#
+# Run with (from this directory):
+#   asgard watcher start      # background; log and state under ~/.local/state/asgard/watch/
+#   asgard watcher list       # the four entries, daemon state, each entry's last run
+#   # ... edit lib/greeter.rb, docs/index.md, add or remove a data/*.json ...
+#   asgard watcher log        # one line per trigger, spawn and exit, plus each task's output
+#   asgard watcher stop       # a task still running finishes first
+#
+# Each task also runs by hand (`asgard lint`), when `changes` is empty.
+# See README.md here for a walkthrough with expected output.
+
+class Tasks
+  # A glob: watches lib/ and keeps the paths that match, like a shell would.
+  watch :lint, paths: "lib/**/*.rb"
+
+  # A directory with filters. only: narrows to Markdown; ignore: silences
+  # the drafts folder; env: adds a variable the task can read with env().
+  watch :docs, paths: "docs", only: /\.md\z/, ignore: %r{\Adrafts/}, env: { BUILD_ENV: "demo" }
+
+  # events: picks which kinds of change count. Editing a data file does
+  # nothing; creating or deleting one triggers a reindex. debounce: waits
+  # a full second after the last event, so a batch of files lands at once.
+  watch :reindex, paths: "data/**/*.json", events: %i[added removed], debounce: 1
+
+  # The same task watched from a second declaration needs its own entry
+  # name. Both entries share one worker, so lint never overlaps itself.
+  watch :lint, paths: "bin/**/*", as: "lint-bin"
+
+  desc "lint", "Report the Ruby files that changed"
+  def lint
+    files = changes.modified + changes.added
+    return puts "lint: nothing changed (run by hand), so linting everything under lib/" if files.empty?
+
+    files.each { |file| puts "lint: #{file} (#{File.foreach(file).count} lines) triggered by #{env(:asgard_watch, 'nothing')}" }
+  end
+
+  desc "docs", "Rebuild the documentation"
+  def docs
+    puts "docs: building for #{env(:build_env, 'development')}; changed: #{changes.all.join(', ')}"
+  end
+
+  desc "reindex", "Rebuild the data index"
+  def reindex
+    puts "reindex: #{changes.added.size} added, #{changes.removed.size} removed; #{Dir['data/**/*.json'].size} data file(s) now"
+  end
+end

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