asgard 0.5.1 → 0.6.0

data/docs/watch.md

@@ -1,123 +0,0 @@
-# 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/.env

@@ -1,4 +0,0 @@
-APP_NAME=my_app
-PORT=4000
-API_KEY=secret-key-abc123
-DATABASE_URL=postgres://localhost/my_app_dev

data/examples/.envrc

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

data/examples/.loki

@@ -1,24 +0,0 @@
-# examples/.loki — root task file for the examples directory.
-#
-# Asgard loads only this file by default. Everything else must be
-# explicitly pulled in with import.
-#
-# import(path)
-#   Load a specific file or a glob of files, idempotently. Absolute
-#   paths, relative paths, and globs are all accepted.
-#
-# import_up(name)
-#   Walk CWD and every ancestor directory looking for `name`, then
-#   import it. Useful inside a nested task file that needs to pull in
-#   a shared config from the project root without knowing how deep it is.
-#
-# loki_up(name)
-#   Same walk as import_up but just returns the absolute path (or nil)
-#   without loading it — handy when you need the path for another purpose.
-
-# Load all *.loki files in this directory (kitchen_sink, concurrent, etc.)
-import "*.loki"
-
-# Load a task file from a subdirectory.
-# import also accepts a direct path, not just a glob.
-import "subdir/import_demo.loki"

data/examples/bad.loki

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates review.md Critical Issue #1: parallel depends_on tasks that
-# write to shared instance state on `self` race each other.
-#
-# quality.loki's *_check tasks each write a *different* named ivar
-# (@test_result, @rubocop_result, ...), so MRI's GVL happens to hide the
-# race in practice — every write lands on a distinct slot. This file
-# isolates the actual hazard by having 4 parallel workers read-modify-write
-# the SAME @hits counter, the way any real *_check task would if it
-# accumulated into one shared results structure instead of one ivar each.
-#
-# `@hits = @hits + 1` is not one atomic operation — it's a read, an add,
-# then a write — and MRI can switch threads between those steps. Thread.pass
-# inside the loop forces exactly those switches, so the lost-update race
-# shows up reliably instead of "most of the time."
-#
-# Run with:
-#   asgard bad_race
-#
-# Expected @hits: 4000 (4 workers x 1000 increments each)
-# Actual: consistently lower — proof of the lost-update race described in
-# review.md item #1.
-
-BAD_RACE_WORKERS = 4
-BAD_RACE_REPS    = 1000
-
-class Tasks
-  desc "Increment the shared @hits counter, unsynchronized (worker)"
-  def racer_1 = bump_shared_counter
-
-  desc "Increment the shared @hits counter, unsynchronized (worker)"
-  def racer_2 = bump_shared_counter
-
-  desc "Increment the shared @hits counter, unsynchronized (worker)"
-  def racer_3 = bump_shared_counter
-
-  desc "Increment the shared @hits counter, unsynchronized (worker)"
-  def racer_4 = bump_shared_counter
-
-  depends_on [:racer_1, :racer_2, :racer_3, :racer_4]
-  desc "Show the lost-update race in @hits"
-  def bad_race
-    expected = BAD_RACE_WORKERS * BAD_RACE_REPS
-    puts "expected @hits == #{expected}, got #{@hits}"
-
-    if @hits == expected
-      puts "no corruption this run — the race is timing-dependent, rerun a few times"
-    else
-      puts "DATA RACE CONFIRMED: #{expected - @hits} update(s) lost"
-    end
-  end
-
-  no_commands do
-    def bump_shared_counter
-      @hits ||= 0
-      BAD_RACE_REPS.times do
-        current = @hits    # read
-        Thread.pass        # force a context switch before the write lands
-        @hits = current + 1 # write — another thread's read may already be stale
-      end
-    end
-  end
-end

data/examples/concurrent.loki

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates concurrent task execution via parallel depends_on groups.
-#
-# Each worker prints its letter repeatedly with random delays. Because
-# worker_a, worker_b, and worker_c run in separate threads their output
-# interleaves on stdout, proving real concurrency.
-#
-# Execution order:
-#   start → worker_a + worker_b + worker_c (all three concurrent) → finish
-#
-# Run with:
-#   asgard finish
-#
-# Sample output (character order varies every run):
-#   start
-#   ABCBACBACBABCBACBACB
-#   end
-
-$stdout.sync = true   # flush every print immediately across all threads
-
-CONCURRENT_REPS = 10  # how many times each worker prints its character
-
-class Tasks
-  desc "Print start marker"
-  def start
-    puts "starting demo of concurrent task execution ..."
-  end
-
-  desc "Print 'A' repeatedly with random delays"
-  def worker_a
-    CONCURRENT_REPS.times do
-      print "A"
-      sleep rand(0.05..0.3)
-    end
-  end
-
-  desc "Print 'B' repeatedly with random delays"
-  def worker_b
-    CONCURRENT_REPS.times do
-      print "B"
-      sleep rand(0.05..0.3)
-    end
-  end
-
-  desc "Print 'C' repeatedly with random delays"
-  def worker_c
-    CONCURRENT_REPS.times do
-      print "C"
-      sleep rand(0.05..0.3)
-    end
-  end
-
-  depends_on :start, [:worker_a, :worker_b, :worker_c]
-  desc "Print end marker after all workers complete"
-  def finish
-    puts "\nfini - the end of concurrent task demo"
-  end
-end

data/examples/confirm.loki

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates a guard task: list `confirm` first in a dangerous task's
-# depends_on and the task only runs after the user answers yes.
-#
-# Run with:
-#   asgard reset_database                  # asks, runs only on y/yes
-#   ASGARD_YES=1 asgard reset_database     # no question (scripts, CI)
-#
-# Behavior:
-#   - A dependency doesn't know which task asked for it, so the question
-#     shows the whole command line: "Really run `asgard reset_database`?"
-#   - Answering no raises Asgard::Error, which stops everything that
-#     hasn't run yet; asgard prints "asgard: aborted ..." and exits 1.
-#     Returning :fail would NOT work: a dependency's return value never
-#     stops the task that depends on it.
-#   - With no terminal to ask (a schedule, the watcher, a pipe) it refuses
-#     unless ASGARD_YES is set, rather than hanging or guessing.
-#   - It runs at most once per asgard invocation, so
-#     `asgard do reset_database, drop_cache` asks once for the whole line.
-#   - Put confirm in its own first stage. In a parallel group,
-#     `depends_on [:confirm, :backup]`, backup runs while the question waits.
-
-class Tasks
-  # Not a Thor command (a class method), so it can be tested on its own:
-  #   Tasks.confirmed?("y", yes_env: nil) #=> true
-  def self.confirmed?(answer, yes_env:)
-    return true if yes_env && !yes_env.empty?
-
-    %w[y yes].include?(answer.to_s.strip.downcase)
-  end
-
-  desc "Ask before running the task that depends on this", hide: true
-  def confirm
-    command = "asgard #{ARGV.join(' ')}"
-    yes_env = env(:asgard_yes, "")
-    return if self.class.confirmed?(nil, yes_env:)
-    raise Asgard::Error, "refusing `#{command}`: no terminal to confirm on (set ASGARD_YES=1)" unless $stdin.tty?
-
-    answer = ask("Really run `#{command}`? [y/N]")
-    raise Asgard::Error, "aborted `#{command}`" unless self.class.confirmed?(answer, yes_env:)
-  end
-
-  depends_on :confirm
-  desc "Pretend to drop and recreate the database (demo for confirm)"
-  def reset_database
-    puts "Database reset."
-  end
-end

data/examples/db_subcommands.loki

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates Thor subcommands with Asgard's depends_on chaining within
-# the subcommand group. Inherits from Tasks for full Asgard DSL access.
-#
-# Usage:
-#   asgard db               # shows subcommand help
-#   asgard db migrate
-#   asgard db migrate 20240101120000 --dry-run
-#   asgard db rollback
-#   asgard db rollback 3
-#   asgard db seed --file db/seeds/staging.rb
-#   asgard db reset         # runs: rollback → migrate → seed
-#   asgard db console --env staging
-#   asgard db status
-
-class DBCommands < Tasks
-  desc "migrate [VERSION]", "Run pending migrations up to VERSION"
-  option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Print SQL without executing"
-  option :verbose, aliases: "-v", type: :boolean, default: false, desc: "Show each migration as it runs"
-  def migrate(version = nil)
-    target = version ? "to version #{version}" : "to latest"
-    puts "Migrating #{target}#{options[:dry_run] ? " (dry run)" : ""}..."
-  end
-
-  desc "rollback [STEPS]", "Roll back the last STEPS migrations (default: 1)"
-  option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Print SQL without executing"
-  def rollback(steps = "1")
-    puts "Rolling back #{steps} migration(s)#{options[:dry_run] ? " (dry run)" : ""}..."
-  end
-
-  desc "seed [FILE]", "Load seed data into the database"
-  option :env, type: :string, default: "development",
-               enum:  %w[development staging production],
-               desc:  "Environment to seed"
-  def seed(file = "db/seeds.rb")
-    puts "Seeding #{options[:env]} from #{file}..."
-  end
-
-  # depends_on chains within the subcommand group:
-  #   rollback → migrate → seed → reset
-  depends_on :rollback, :migrate, :seed
-  desc "Rollback all migrations, re-migrate, and reseed"
-  def reset
-    puts "Database reset complete."
-  end
-
-  long_desc <<~DESC
-    Opens an interactive SQL console connected to the configured database.
-
-    The console inherits credentials from the current environment's
-    database.yml (Rails) or DATABASE_URL.
-
-    Examples:\x5
-      asgard db console\x5
-      asgard db console --env staging
-  DESC
-  desc "Open an interactive database console"
-  option :env, type: :string, default: "development",
-               enum:  %w[development staging production],
-               desc:  "Environment to connect to"
-  def console
-    puts "Opening #{options[:env]} database console..."
-  end
-
-  desc "Show applied and pending migrations"
-  def status
-    puts "Checking migration status..."
-  end
-end
-
-class Tasks
-  desc "db SUBCOMMAND", "Manage the database"
-  subcommand "db", DBCommands
-end

data/examples/depends_on_block/bad/.loki

@@ -1,51 +0,0 @@
-# examples/depends_on_block/bad/.loki
-# BAD example: depends_on block returning a mis-shaped result.
-#
-# Compare with ../good/.loki, which does this correctly:
-#
-#   depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
-#     ^                                                                ^
-#     one wrapping [ ] — this is "one stage, containing every matching
-#     task, all running in parallel."
-#
-# It's an easy typo to add a SECOND wrapping array, thinking the outer
-# array is "the list of stages" and the inner one is "this stage's tasks"
-# as two separate concerns:
-#
-#   depends_on { [[all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)]] }
-#                ^                                                        ^
-#                that's one stage too many — the middle array ends up
-#                *inside* a stage as a dependency, not as the stage itself.
-#
-# depends_on's block/Proc result is validated the moment it resolves
-# (during validate_deps!, before any task runs): every stage must be a
-# Symbol/String (sequential) or an Array of Symbol/String (parallel group)
-# — nesting one level deeper than that is rejected with Asgard::Error
-# instead of failing later with a confusing NoMethodError.
-#
-# Run with (from this directory):
-#   asgard quality
-#
-# Expected output (validate_deps! aborts before quality — or any other
-# task — ever runs):
-#   asgard: depends_on proc/block for 'quality' returned invalid dependency
-#   [:a_check, :b_check, :c_check] (Array) in a parallel group; expected a
-#   Symbol or String
-
-class Tasks
-  desc "Run the first check"
-  def a_check = puts "running a_check ..."
-
-  desc "Run the second check"
-  def b_check = puts "running b_check ..."
-
-  desc "Run the third check"
-  def c_check = puts "running c_check ..."
-
-  # BUG: double-wrapped — [[ ... ]] instead of [ ... ]. See comment above.
-  depends_on { [[all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)]] }
-  desc "Run every *_check task in parallel, then report"
-  def quality
-    puts "quality: all *_check tasks passed"
-  end
-end

data/examples/depends_on_block/good/.loki

@@ -1,83 +0,0 @@
-# examples/depends_on_block/good/.loki
-# GOOD example: depends_on with a block instead of a Proc/lambda.
-#
-# A block behaves exactly like `-> { ... }` — it defers resolution to
-# validate_deps! (once, after every .loki file has loaded) instead of
-# resolving the moment depends_on is evaluated. This is the real pattern
-# from this gem's own quality.loki: gather every task whose name ends in
-# `_check`, without having to know their names or load order upfront.
-#
-# The block's return value is validated once it resolves: it must be an
-# Array of stages, each a Symbol/String (sequential) or an Array of
-# Symbol/String (parallel group) — see ../bad/.loki for what happens when
-# that shape is wrong.
-#
-# `{ ... }` braces are used below for the short, single-line blocks (quality,
-# full_cycle) — standard Ruby style reserves `do ... end` for a block that
-# spans multiple statements, shown in smoke further down.
-#
-# Run with (from this directory):
-#   asgard quality
-#
-# Expected output:
-#   running a_check ...
-#   running b_check ...
-#   running c_check ...
-#   quality: all *_check tasks passed
-
-class Tasks
-  desc "Run the first check"
-  def a_check = puts "running a_check ..."
-
-  desc "Run the second check"
-  def b_check = puts "running b_check ..."
-
-  desc "Run the third check"
-  def c_check = puts "running c_check ..."
-
-  # self inside the block is the Tasks class (it's written directly in the
-  # class body), so all_commands can be called bare, with no self.class.
-  # prefix — even though the block itself isn't invoked until later.
-  depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
-  desc "Run every *_check task in parallel, then report"
-  def quality
-    puts "quality: all *_check tasks passed"
-  end
-
-  # A block can also return a mix of sequential Symbols and parallel Arrays,
-  # exactly like the plain splat form: depends_on :setup, [:a_check, :b_check], :teardown
-  desc "Prepare fixtures before the checks run"
-  def setup = puts "setup: fixtures ready"
-
-  desc "Clean up fixtures after the checks run"
-  def teardown = puts "teardown: fixtures removed"
-
-  depends_on { [:setup, %i[a_check b_check], :teardown] }
-  desc "setup, then a_check+b_check in parallel, then teardown"
-  def full_cycle
-    puts "full_cycle: done"
-  end
-
-  # A block spanning multiple statements — local variables, some computation
-  # — reads more naturally as do...end than as one long `{ ... }` line.
-  # Whatever it does along the way, the last expression is still what gets
-  # returned and validated: here, [:setup, Array, :teardown], the same shape
-  # as full_cycle above.
-  #
-  # Gotcha: this block runs during validate_deps!, which happens *before*
-  # Thor parses this invocation's CLI options (see the Entry Point Flow in
-  # CLAUDE.md) — so checking `--verbose`/`--debug` in here would always see
-  # the pre-flag default, never what was actually passed on this run. Keep
-  # depends_on blocks limited to shaping the dependency graph itself.
-  depends_on do
-    all_checks  = all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)
-    slow_checks = %i[c_check]
-    fast_checks = all_checks - slow_checks
-
-    [:setup, fast_checks, :teardown]
-  end
-  desc "setup, then every *_check except the slow ones, then teardown"
-  def smoke
-    puts "smoke: done"
-  end
-end

data/examples/do.loki

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates a plain user task that runs other tasks in sequence — the
-# `rake a b c` / `just a b c` style, which Thor's one-command dispatch
-# doesn't offer on its own.
-#
-# Steps are comma-separated so a step can carry its own arguments and
-# options; with no commas, every word is a task of its own.
-#
-# Run with:
-#   asgard do greet finish
-#   asgard do hello Alice, farewell Bob --formal, finish
-#
-# Behavior:
-#   - Each step is parsed by Thor exactly as if typed on the command line,
-#     so its arguments and options work as usual.
-#   - The sequence stops at the first failure: a failing `sh` exits the
-#     process, and a step returning :fail makes `do` return :fail (exit 1).
-#   - Every task runs at most once per asgard invocation, so
-#     `asgard do hello Alice, hello Bob` greets only Alice, and a dependency
-#     shared by several steps runs once.
-
-require "shellwords"
-
-class Tasks
-  # Not a Thor command (a class method), so it can be tested on its own:
-  #   Tasks.do_steps("lint, hello Alice") #=> [["lint"], ["hello", "Alice"]]
-  def self.do_steps(line)
-    line.include?(",") ? line.split(",").map { |step| Shellwords.split(step) }.reject(&:empty?)
-                       : Shellwords.split(line).map { |word| [word] }
-  end
-
-  desc "do STEPS...", "Run several tasks in sequence, e.g. `asgard do hello Alice, farewell Bob --formal`"
-  stop_on_unknown_option! :do
-  def do(*words)
-    steps = self.class.do_steps(words.join(" "))
-    raise Asgard::Error, "do: no tasks given" if steps.empty?
-
-    steps.each do |name, *args|
-      raise Asgard::Error, "do: unknown task '#{name}'" if name == "do" || !self.class.all_commands.key?(name)
-      # dispatch with nil options is what Tasks.start does: Thor parses this
-      # step's argv itself. (invoke would reuse the options parsed for `do`.)
-      return :fail if self.class.send(:dispatch, nil, [name, *args], nil, shell: shell) == :fail
-    end
-  end
-end

data/examples/env_usage.loki

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates the env() Kernel helper for reading system environment variables.
-#
-# env() is cleaner than ENV[] — it accepts symbols or strings, upcases
-# automatically, and raises KeyError when a required variable is missing
-# rather than silently returning nil.
-#
-# Run from examples/ or any subdirectory — loki_up locates .env automatically:
-#   asgard env_demo
-
-class Tasks
-  # loki_up walks CWD and every ancestor until it finds .env, returning
-  # its absolute path. This works regardless of which directory asgard
-  # is run from — no hardcoded relative path needed.
-  dotenv loki_up(".env") || ".env"
-
-  desc "Print environment variable values resolved via env()"
-  def env_demo
-    puts <<~OUT
-      APP_NAME     : #{env(:app_name)}
-      PORT         : #{env(:port)}
-      API_KEY      : #{env(:api_key)}
-      DATABASE_URL : #{env(:database_url)}
-      LOG_LEVEL    : #{env(:log_level, "info")}
-    OUT
-  end
-end