asgard 0.1.2 → 0.3.0

data/docs/variables.md

@@ -0,0 +1,338 @@
+# Variables
+
+Asgard task files are plain Ruby. Shared configuration values are declared using Ruby class variables (`@@name`) at the top of the `Tasks` class body.
+
+---
+
+## Ruby Variable Types
+
+Ruby has four kinds of variables plus constants, each with a distinct prefix and scope. Understanding the differences matters because tasks are instance methods — the wrong variable type will simply not be visible where you expect it.
+
+| Kind | Prefix | Example | Scope |
+|------|--------|---------|-------|
+| Local | none | `count = 0` | The method or block it is defined in only |
+| Instance | `@` | `@name = "myapp"` | One specific object instance |
+| Class | `@@` | `@@name = "myapp"` | The class and all its subclasses |
+| Global | `$` | `$DEBUG = true` | Everywhere in the process |
+| Constant | uppercase first letter | `APP = "myapp"` | Everywhere (namespaced to where defined) |
+
+### Local variables
+
+```ruby
+def build
+  output_dir = "dist"   # only visible inside this method
+  sh "rake build OUTDIR=#{output_dir}"
+end
+```
+
+`output_dir` disappears when the method returns. It cannot be seen by any other task.
+
+### Instance variables (`@`)
+
+```ruby
+class Tasks
+  @app = "myapp"   # class instance variable — lives on the Tasks class object
+
+  def build
+    puts @app      # nil — this @app is on the instance, not the class
+  end
+end
+```
+
+`@` in the class body sets a variable on the class object itself, not on the instances that run tasks. Inside a task method body, `@name` refers to the instance, which is a different object. They do not share state.
+
+`@` inside a method is useful for memoization within a single task invocation:
+
+```ruby
+def version
+  @version ||= `git describe --tags`.strip   # computed once, cached for this run
+end
+```
+
+### Class variables (`@@`)
+
+```ruby
+class Tasks
+  @@app = "myapp"   # visible in every task method and every subclass
+
+  def build
+    puts @@app      # "myapp"
+  end
+end
+```
+
+`@@` is shared across the class body, all instance methods, and all subclasses (including Thor subcommand classes). This makes it the right choice for configuration values in Asgard task files.
+
+### Global variables (`$`)
+
+```ruby
+$DEBUG   = true   # visible everywhere in the Ruby process
+$VERBOSE = true
+```
+
+Asgard uses `$DEBUG` and `$VERBOSE` internally — they are set by the `--debug` and `--verbose` CLI flags. Avoid declaring your own `$` variables in `.loki` files; they affect the entire Ruby process including all loaded gems.
+
+Several important Ruby globals you may encounter in task files:
+
+| Variable | Purpose |
+|----------|---------|
+| `$stdout` / `$STDOUT` | Standard output stream — `puts` writes here |
+| `$stderr` / `$STDERR` | Standard error stream — `warn` writes here |
+| `$DEBUG` | Enables debug mode when `true` |
+| `$VERBOSE` | Enables verbose warnings when `true` |
+| `$PROGRAM_NAME` / `$0` | The name of the running script |
+
+The uppercase versions (`$STDOUT`, `$STDERR`) are the original stream objects. The lowercase versions (`$stdout`, `$stderr`) are reassignable aliases — libraries sometimes redirect them temporarily to capture output. In task files, use `$stdout.puts` or `$stderr.puts` when you need explicit stream control; use plain `puts` and `warn` for normal output.
+
+### Constants
+
+Any name that begins with an uppercase letter is a constant in Ruby. Constants are available everywhere — inside methods, across files, and across classes — without any prefix:
+
+```ruby
+APP_NAME    = "myapp".freeze
+MAX_RETRIES = 3
+BASE_URL    = "https://example.com".freeze
+
+class Tasks
+  desc "Deploy the app"
+  def deploy
+    puts "Deploying #{APP_NAME} to #{BASE_URL}"
+    sh "cap deploy"
+  end
+end
+```
+
+The convention is `ALL_CAPS_WITH_UNDERSCORES` for values that are truly fixed. Class and module names are also constants — `Tasks`, `Asgard`, `String`, `Integer` all start with an uppercase letter.
+
+Ruby will issue a warning if you reassign a constant but will not prevent it. Use `.freeze` to make the value itself immutable:
+
+```ruby
+APP_NAME = "myapp".freeze   # value cannot be mutated; reassignment still warns
+```
+
+**Constants vs `@@` class variables in task files:**
+
+| | Constant | `@@` class variable |
+|---|---|---|
+| Accessible in task methods | Yes | Yes |
+| Accessible in subcommand subclasses | Yes | Yes |
+| Visible outside the class | Yes — anywhere | Only within the class hierarchy |
+| Reassignment warning | Yes | No |
+| Convention | `ALL_CAPS` | `snake_case` |
+
+For fixed values that will never change — app names, version strings, URLs, port numbers — constants are often the clearest choice. For values that might reasonably vary across environments or be overridden in a different `.loki` file, `@@` with `||=` is more flexible.
+
+---
+
+## Strings and Interpolation
+
+### Always use double quotes
+
+Ruby supports both single and double quoted strings. In Asgard task files, always use double quotes:
+
+```ruby
+@@app ||= "myapp".freeze     # correct
+sh "bundle exec rake test"   # correct
+```
+
+Single-quoted strings look similar but behave differently — they do not support interpolation or escape sequences. Mixing the two styles adds confusion for no benefit. Double quotes work everywhere single quotes do, and more.
+
+### String interpolation
+
+Embedding a variable's value inside a string uses the `#{}` syntax. Everything inside the braces is Ruby code — the result is converted to a string and inserted in place:
+
+```ruby
+class Tasks
+  @@app  ||= "myapp".freeze
+  @@env  ||= "production".freeze
+
+  desc "Deploy the app"
+  def deploy
+    sh "cap #{@@env} deploy APP=#{@@app}"
+  end
+end
+```
+
+Any Ruby expression works inside `#{}`:
+
+```ruby
+puts "build started at #{Time.now}"
+sh "puma -p #{env(:port, '3000').to_i + 1}"
+sh "git tag #{@@app}-#{`git describe --tags`.strip}"
+```
+
+Interpolation only works inside double-quoted strings. This is the primary reason Asgard tasks use double quotes exclusively — shell commands almost always need to embed variable values.
+
+### Multi-line strings
+
+For shell scripts with multiple lines, use a heredoc. The `~` modifier strips leading indentation so the script aligns with your code:
+
+```ruby
+desc "Bootstrap the project"
+def bootstrap
+  sh <<~SHELL
+    bundle install
+    rails db:create db:migrate
+    echo "#{@@app} ready on #{env(:port, '3000')}"
+  SHELL
+end
+```
+
+Interpolation works inside heredocs the same as in double-quoted strings.
+
+---
+
+## System Environment Variables
+
+System environment variables are set outside Ruby — in the shell, a CI environment, or a `.env` file — and are accessed inside tasks via the `env` Kernel method:
+
+```ruby
+class Tasks
+  desc "Start the server"
+  def start
+    sh "puma -p #{env(:port, '3000')} -e #{env(:rack_env, 'development')}"
+  end
+
+  desc "Deploy the app"
+  def deploy
+    sh "cap #{env(:deploy_target)} deploy"  # raises KeyError if DEPLOY_TARGET is not set
+  end
+end
+```
+
+`env` accepts a symbol or string and converts it to an uppercase `ENV` key automatically:
+
+| Call | Equivalent | Behaviour |
+|------|-----------|-----------|
+| `env(:port, "3000")` | `ENV.fetch("PORT", "3000")` | Returns `"3000"` if `PORT` is unset |
+| `env(:api_key)` | `ENV.fetch("API_KEY")` | Raises `KeyError` if `API_KEY` is unset |
+| `env("DATABASE_URL")` | `ENV.fetch("DATABASE_URL")` | Raises `KeyError` if unset |
+| `env("database_url")` | `ENV.fetch("DATABASE_URL")` | Same — name is always upcased |
+
+!!! note
+    All environment variable values are strings. Convert to other types explicitly: `env(:port, "3000").to_i`, `env(:debug, "false") == "true"`.
+
+Use `dotenv` to load a `.env` file before tasks run — see [Environment](environment.md).
+
+---
+
+## The Pattern
+
+```ruby
+class Tasks
+  @@app  ||= "myapp".freeze
+  @@port ||= 3000
+  @@env  ||= "production".freeze
+
+  desc "Print app info"
+  def info
+    puts "#{@@app} running on port #{@@port} in #{@@env}"
+  end
+end
+```
+
+**Why `||=` instead of `=`?**
+Because multiple `.loki` files reopen the same `class Tasks`. Using `||=` means the first file to declare a value wins, and subsequent files that reopen `Tasks` won't accidentally overwrite it.
+
+**Why `.freeze`?**
+It prevents mutation of the value (e.g. `@@app << "-extra"` raises a `FrozenError`). Numbers and symbols are already frozen. Use `.freeze` on strings, arrays, and hashes.
+
+**Why `@@` instead of `@`?**
+A single `@` in the class body sets a class instance variable — it lives on the `Tasks` class object and is **not** accessible inside task method bodies. `@@` is a class variable and is visible everywhere: in all instance methods, and in any subclass (including Thor subcommand classes).
+
+---
+
+## Sharing Values Across Subcommands
+
+Class variables are visible in subclasses, which makes them the right choice when you have Thor subcommands defined in separate classes:
+
+```ruby
+# config.loki
+class Tasks
+  @@app ||= "myapp".freeze
+end
+
+# deploy.loki
+class DeployCommands < Tasks
+  desc "Deploy to production"
+  def production
+    sh "cap production deploy APP=#{@@app}"  # @@app is visible here
+  end
+end
+
+class Tasks
+  desc "deploy SUBCOMMAND", "Deployment tasks"
+  subcommand "deploy", DeployCommands
+end
+```
+
+---
+
+## Computed Values
+
+For values that require a shell call, file read, or any runtime computation, define a method instead:
+
+```ruby
+class Tasks
+  def version = `git describe --tags`.strip
+  def sha     = `git rev-parse --short HEAD`.strip
+
+  desc "Show version info"
+  def info = puts "#{version} (#{sha})"
+end
+```
+
+Methods defined without `desc` do not appear in `--help` output or as CLI commands. If you need memoization (the computation is expensive and called multiple times), use `||=` on an instance variable inside the method:
+
+```ruby
+class Tasks
+  def version
+    @version ||= `git describe --tags`.strip
+  end
+end
+```
+
+---
+
+## Sharing Values Across Files
+
+Because all `.loki` files reopen the same `class Tasks`, a `@@` variable declared in one file is available in all other files loaded in the same session:
+
+```ruby
+# config.loki
+class Tasks
+  @@app  ||= "myapp".freeze
+  @@port ||= 8080
+end
+
+# deploy.loki
+class Tasks
+  desc "Deploy the app"
+  def deploy = sh "cap deploy APP=#{@@app} PORT=#{@@port}"
+end
+```
+
+---
+
+## Naming Conventions
+
+Class variable names use `snake_case` — the standard Ruby convention for variables and methods:
+
+```ruby
+class Tasks
+  @@app_name    ||= "myapp".freeze
+  @@deploy_host ||= "production.example.com".freeze
+  @@max_workers ||= 4
+end
+```
+
+Multi-word names are separated by underscores, not camelCase or hyphens.
+
+---
+
+## Naming Caution
+
+!!! warning
+    Avoid `@@` names that conflict with built-in Ruby or Thor internals. Safe practice: use descriptive names that are unlikely to clash.
+
+Names to avoid: `options`, `shell`, `invoke`, `command`, `args`.

data/examples/.env

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

data/examples/.loki

@@ -1,2 +1,24 @@
-# The .loki file can be empty if there are *.loki files define the tasks
-# they will be auto loaded.
+# 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/concurrent.loki

@@ -0,0 +1,58 @@
+# 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/db_subcommands.loki

@@ -39,7 +39,7 @@ class DBCommands < Tasks
   # depends_on chains within the subcommand group:
   #   rollback → migrate → seed → reset
   depends_on :rollback, :migrate, :seed
-  desc "reset", "Rollback all migrations, re-migrate, and reseed"
+  desc "Rollback all migrations, re-migrate, and reseed"
   def reset
     puts "Database reset complete."
   end
@@ -54,7 +54,7 @@ class DBCommands < Tasks
       asgard db console\x5
       asgard db console --env staging
   DESC
-  desc "console", "Open an interactive database console"
+  desc "Open an interactive database console"
   option :env, type: :string, default: "development",
                enum:  %w[development staging production],
                desc:  "Environment to connect to"
@@ -62,7 +62,7 @@ class DBCommands < Tasks
     puts "Opening #{options[:env]} database console..."
   end
 
-  desc "status", "Show applied and pending migrations"
+  desc "Show applied and pending migrations"
   def status
     puts "Checking migration status..."
   end

data/examples/env_usage.loki

@@ -0,0 +1,27 @@
+# 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

data/examples/kitchen_sink.loki

@@ -5,9 +5,20 @@
 # install, release) so this file can be loaded alongside them without conflict.
 
 class Tasks
-  # ── Asgard: var — static value and lazy lambda ─────────────────────────────
-  var :app_name,  "my_app"
-  var :build_dir, -> { "builds/#{app_name}" }
+  # ── Ruby class variables — shared across all tasks and subcommands ──────────
+  @@app_name  ||= "my_app".freeze
+  @@build_dir ||= "builds/#{@@app_name}".freeze
+
+  # ── Computed values — plain private methods replace the removed var DSL ──────
+  # Declare as private so Thor does not try to register them as commands.
+  # Use @ivar ||= inside the method body to memoize expensive calls.
+  private
+
+  def version = `git describe --tags --always`.strip
+  def sha     = `git rev-parse --short HEAD`.strip
+  def branch  = @branch ||= `git rev-parse --abbrev-ref HEAD`.strip
+
+  public
 
   # ── Asgard: dotenv — load environment variables ────────────────────────────
   # Uncomment to activate:
@@ -37,9 +48,9 @@ class Tasks
   map "pl" => :pipeline
 
   # ── Basic task — no parameters ─────────────────────────────────────────────
-  desc "greet", "Say hello (default task when no command is given)"
+  desc "Say hello (default task when no command is given)"
   def greet
-    puts "Hello from #{app_name} (#{options[:env]})!"
+    puts "Hello from #{@@app_name} #{version} (#{branch}) in #{options[:env]} mode!"
   end
 
   # ── Positional parameter with default ──────────────────────────────────────
@@ -72,14 +83,14 @@ class Tasks
   end
 
   # ── method_option — all five option types ──────────────────────────────────
-  desc "compile", "Compile the project"
+  desc "Compile the project"
   option :output,  aliases: "-o", type: :string,  default: "dist/",        desc: "Output directory"
   option :verbose, aliases: "-v", type: :boolean, default: false,           desc: "Enable verbose output"
   option :jobs,    aliases: "-j", type: :numeric, default: 1,               desc: "Number of parallel jobs"
   option :tags,                   type: :array,                              desc: "Build tags to apply"
   option :defines,                type: :hash,                               desc: "Preprocessor defines (KEY:VALUE)"
   def compile
-    puts "Compiling #{app_name} → #{options[:output]}"
+    puts "Compiling #{@@app_name} → #{options[:output]}"
   end
 
   # ── required option + enum + banner ────────────────────────────────────────
@@ -99,7 +110,7 @@ class Tasks
          default: "main",
          desc:    "Git branch to deploy"
   def deploy(env = "staging")
-    puts "Deploying #{app_name}@#{options[:branch]} to #{env}..."
+    puts "Deploying #{@@app_name}@#{options[:branch]} to #{env}..."
   end
 
   # ── long_desc — extended help shown by `asgard help report` ────────────────
@@ -115,7 +126,7 @@ class Tasks
       asgard report --format json --output report.json\x5
       asgard rp --format text
   LONGDESC
-  desc "report", "Generate a project report"
+  desc "Generate a project report"
   option :format, type: :string, default: "text", enum: %w[text html json], desc: "Output format"
   option :since,  type: :string,                  banner: "DATE",            desc: "Limit to changes after DATE"
   option :output, type: :string,                  banner: "FILE",            desc: "Write output to FILE"
@@ -124,30 +135,52 @@ class Tasks
   end
 
   # ── Asgard depends_on: sequential — analyze runs before spec ───────────────
-  desc "analyze", "Check code style and complexity"
+  desc "Check code style and complexity"
   def analyze = puts "Analyzing..."
 
   depends_on :analyze
-  desc "spec", "Run the test suite (depends on: analyze)"
+  desc "Run the test suite (depends on: analyze)"
   def spec = puts "Running specs..."
 
   # ── Asgard depends_on: parallel — analyze and typecheck run concurrently ───
-  desc "typecheck", "Run the type checker"
+  desc "Run the type checker"
   def typecheck = puts "Type checking..."
 
   depends_on [:analyze, :typecheck]
-  desc "check", "Run analyze and typecheck in parallel"
+  desc "Run analyze and typecheck in parallel"
   def check = puts "All checks passed."
 
   # ── Asgard depends_on: mixed sequential + parallel ─────────────────────────
-  desc "pack", "Create distribution archive"
+  desc "Create distribution archive"
   def pack = puts "Packing..."
 
   #   check → compile+spec (parallel) → pack → pipeline
   depends_on :check, [:compile, :spec], :pack
-  desc "pipeline", "Full pipeline: check → compile+spec → pack"
+  desc "Full pipeline: check → compile+spec → pack"
   def pipeline = puts "Pipeline complete."
 
+  # ── Asgard: debug? / verbose? — Kernel predicates for conditional output ──────
+  # debug?   returns true when --debug is passed  (sets $DEBUG)
+  # verbose? returns true when --verbose is passed (sets $VERBOSE)
+  # Both are set by Asgard before invoke_command runs, so they are safe
+  # to read inside any task body.
+  #
+  # Run with:
+  #   asgard status --verbose
+  #   asgard status --debug
+  #   asgard status --verbose --debug
+  desc "Show application status"
+  def status
+    puts "#{@@app_name} is running in #{options[:env]} mode."
+    puts "  build dir : #{@@build_dir}" if verbose?
+    puts "  sha       : #{current_sha}" if verbose?
+    if debug?
+      puts "  $DEBUG    : #{$DEBUG.inspect}"
+      puts "  $VERBOSE  : #{$VERBOSE.inspect}"
+      puts "  options   : #{options.inspect}"
+    end
+  end
+
   # ── Thor: no_commands — public helper excluded from CLI and --help ──────────
   no_commands do
     def current_sha

data/examples/server_subcommands.loki

@@ -2,7 +2,7 @@
 # Demonstrates Thor subcommands registered on the top-level Tasks class.
 #
 # The subcommand class inherits from Tasks so it has access to sh, shebang,
-# var, depends_on, and the built-in --debug/--verbose class options.
+# depends_on, and the built-in --debug/--verbose class options.
 #
 # Usage:
 #   asgard server          # shows subcommand help
@@ -26,7 +26,7 @@ class ServerCommands < Tasks
     ]
   end
 
-  desc "stop", "Stop the running server"
+  desc "Stop the running server"
   option :force, aliases: "-f", type: :boolean, default: false, desc: "Force-kill without draining"
   option :wait,                  type: :numeric, default: 30,   desc: "Seconds to wait for shutdown"
   def stop
@@ -37,7 +37,7 @@ class ServerCommands < Tasks
     end
   end
 
-  desc "status", "Show server status and process info"
+  desc "Show server status and process info"
   def status
     puts "Checking server status..."
   end

data/examples/subdir/.loki

@@ -0,0 +1,12 @@
+# examples/subdir/.loki — root task file for this subdirectory.
+#
+# When asgard is run from examples/subdir/, it loads this file.
+# From here, import pulls in sibling task files explicitly.
+#
+# import accepts a direct path or a glob:
+#   import "import_up_demo.loki"       # a single file
+#   import "*.loki"                    # all loki files in this directory
+#   import "tasks/**/*.loki"           # all loki files under a tasks/ tree
+#   import "../shared/*.loki"          # files in a sibling directory
+
+import "import_up_demo.loki"

data/examples/subdir/import_demo.loki

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# This file lives in a subdirectory and is explicitly imported by the
+# parent examples/.loki via import "subdir/import_demo.loki".
+#
+# In a real project a subdirectory might hold task files scoped to a
+# specific concern (deploy, database, CI) while the root .loki wires
+# them all together with import.
+
+class Tasks
+  desc "Confirm this task was loaded from a subdirectory via import"
+  def subdir_task
+    puts "Loaded from examples/subdir/import_demo.loki"
+  end
+end

data/examples/subdir/import_up_demo.loki

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Demonstrates import_up — find a file by walking up the directory tree
+# and load it, without needing to know how deep the current file is.
+#
+# import_up(name) combines loki_up(name) + import(path) in one call.
+# It searches CWD, then each ancestor in turn, and loads the first match.
+#
+# This is useful when a nested task file needs to pull in something from
+# the project root — a shared config, a common helpers file — without
+# hardcoding a relative path that would break if the file moves.
+#
+# import_up also accepts a glob:
+#   import_up "*.loki"                 # first directory (walking up) that contains any .loki file
+#   import_up "config/settings.loki"   # first ancestor with config/settings.loki
+#   import_up ".env"                   # locate a .env file anywhere up the tree
+
+# Load env_usage.loki from the nearest ancestor directory that contains it.
+import_up "env_usage.loki"