asgard 0.2.0 → 0.3.1

data/docs/shell.md

@@ -14,10 +14,10 @@ Pass a single-line string to run it via `system`:
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 
-  desc "clean", "Remove build artifacts"
+  desc "Remove build artifacts"
   def clean = sh "rm -rf dist/ tmp/"
 end
 ```
@@ -34,7 +34,7 @@ Pass a multiline string (e.g., a heredoc) to run it as a single `bash -c` script
 
 ```ruby
 class Tasks
-  desc "setup", "Bootstrap the development environment"
+  desc "Bootstrap the development environment"
   def setup
     sh <<~SHELL
       brew install redis postgresql
@@ -54,10 +54,10 @@ Pass `silent: true` to suppress the command echo. The command still runs and sti
 
 ```ruby
 class Tasks
-  desc "build", "Compile (quiet)"
+  desc "Compile (quiet)"
   def build = sh "rake build", silent: true
 
-  desc "info", "Print environment info without noise"
+  desc "Print environment info without noise"
   def info
     sh "printenv | grep APP_", silent: true
   end
@@ -71,7 +71,7 @@ end
 ```ruby
 class Tasks
   depends_on :test
-  desc "release", "Test then release"
+  desc "Test then release"
   def release
     sh "bundle exec rake release"
     # Never reached if rake release fails
@@ -90,7 +90,7 @@ end
 
 ```ruby
 class Tasks
-  desc "analyze", "Run Python data analysis"
+  desc "Run Python data analysis"
   def analyze
     shebang :python3, <<~PYTHON
       import json
@@ -105,7 +105,7 @@ end
 
 ```ruby
 class Tasks
-  desc "bundle_assets", "Build frontend assets with esbuild"
+  desc "Build frontend assets with esbuild"
   def bundle_assets
     shebang :node, <<~JS
       const esbuild = require("esbuild")
@@ -123,7 +123,7 @@ end
 
 ```ruby
 class Tasks
-  desc "transform", "Transform data with Ruby"
+  desc "Transform data with Ruby"
   def transform
     shebang :ruby, <<~RUBY
       require "json"
@@ -138,7 +138,7 @@ end
 
 ```ruby
 class Tasks
-  desc "provision", "Run a bash provisioning script"
+  desc "Run a bash provisioning script"
   def provision
     shebang :bash, <<~BASH
       set -euo pipefail
@@ -192,7 +192,7 @@ You can mix both in the same task:
 
 ```ruby
 class Tasks
-  desc "pipeline", "Run a mixed shell + Python pipeline"
+  desc "Run a mixed shell + Python pipeline"
   def pipeline
     sh "bundle exec rake build"
 

data/docs/subcommands.md

@@ -10,10 +10,10 @@ Define a subcommand class that inherits from `Tasks`, then register it on the to
 
 ```ruby
 class DeployCommands < Tasks
-  desc "staging", "Deploy to staging"
+  desc "Deploy to staging"
   def staging = sh "cap staging deploy"
 
-  desc "production", "Deploy to production"
+  desc "Deploy to production"
   def production = sh "cap production deploy"
 end
 
@@ -37,8 +37,8 @@ Inheriting from `Tasks` (rather than `Asgard::Base` or `Thor`) gives the subcomm
 
 - `sh` and `shebang` shell helpers (from `Asgard::Shell`)
 - `depends_on` for dependency declarations
-- `var` for variables
 - `dotenv` for environment loading
+- `@@` class variables declared on `Tasks` (visible in all subclasses)
 - The built-in `--debug` and `--verbose` class options
 - The `debug?` and `verbose?` private predicates
 - Any private helpers or `no_commands` methods defined on `Tasks`
@@ -54,14 +54,14 @@ Inheriting from `Tasks` (rather than `Asgard::Base` or `Thor`) gives the subcomm
 
 ```ruby
 class DBCommands < Tasks
-  desc "migrate", "Run pending migrations"
+  desc "Run pending migrations"
   def migrate = sh "rails db:migrate"
 
-  desc "seed", "Load seed data"
+  desc "Load seed data"
   def seed = sh "rails db:seed"
 
   depends_on :migrate, :seed
-  desc "reset", "Migrate then seed"
+  desc "Migrate then seed"
   def reset = puts "Done."
 end
 
@@ -94,13 +94,13 @@ class ServerCommands < Tasks
     sh "puma -p #{port} #{flags.join(' ')}"
   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"
   def stop
     options[:force] ? sh "pkill -9 puma" : sh "pumactl stop"
   end
 
-  desc "status", "Show server status"
+  desc "Show server status"
   def status = sh "pumactl stats"
 
   depends_on :stop, :start
@@ -176,6 +176,6 @@ myproject/
   db_subcommands.loki      ← defines DBCommands
 ```
 
-When `--auto-load` is used, `*.loki` files are loaded alphabetically before `.loki`, so both `DBCommands` and `ServerCommands` are defined by the time `.loki` runs its `subcommand` calls.
+Because siblings loaded via `import "*.loki"` execute before `.loki`'s own class body, both `DBCommands` and `ServerCommands` are defined by the time `.loki` runs its `subcommand` calls.
 
 See [`examples/server_subcommands.loki`](examples.md#server-subcommands) and [`examples/db_subcommands.loki`](examples.md#db-subcommands) for complete working examples.

data/docs/task-files.md

@@ -1,14 +1,12 @@
 # Task Files
 
-Asgard uses a convention-based file discovery system. A hidden `.loki` file marks the project root; `*.loki` files in the same directory contain tasks that are loaded on demand via `--auto-load`.
+Asgard uses a convention-based file discovery system. A hidden `.loki` file marks the project root. Everything else — loading sibling files, shared task libraries, monorepo-wide tasks — is controlled explicitly from inside your `.loki` file using the `import` and `import_up` Kernel methods.
 
 ---
 
 ## The `.loki` Root Marker
 
-When you run `asgard`, it searches for a `.loki` file starting in the current working directory and walking upward through parent directories until it finds one or reaches the filesystem root. The first `.loki` file found marks the project root.  It may also contain the main task definitions for the project.
-
-This means you can run `asgard` from any subdirectory of your project and it will find your tasks:
+When you run `asgard`, it searches for a `.loki` file starting in the current working directory and walking upward through parent directories until it finds one or reaches the filesystem root. The first `.loki` file found marks the project root and is the only file Asgard loads automatically.
 
 ```
 myproject/
@@ -18,143 +16,223 @@ myproject/
       # asgard still works from here
 ```
 
-!!! note
-    The `.loki` file can be completely empty. Its presence alone is sufficient to mark the project root. If it is empty and you have `*.loki` files, you must pass `--auto-load` when running `asgard` — otherwise Asgard has nothing to do.
+The `.loki` file can be completely empty — its presence alone marks the project root. It can also contain task definitions, `import` calls, or any valid Ruby.
 
 ---
 
-## Loading `*.loki` Files with `--auto-load`
+## Loading Files with `import`
+
+`import` is a Kernel method available everywhere in Ruby — at the top level of `.loki` files, inside class bodies, and inside task method bodies. It loads `.loki` files with `require`-like idempotency: a file is loaded at most once per process, no matter how many times `import` is called with the same path.
 
-By default, `asgard` only loads `.loki`. To also load `*.loki` files, pass `--auto-load`:
+### Single file by absolute path
 
-```bash
-asgard --auto-load <task>
+```ruby
+import "/home/shared/gem_tasks.loki"
 ```
 
-When `--auto-load` is active, Asgard loads all files matching `*.loki` in the same directory in alphabetical order before loading `.loki`. Each file typically reopens `class Tasks` to add more tasks. The `*.loki` glob specifically excludes `.loki` (note the leading dot) — the entry point is always loaded last.
+### Single file by relative path
 
-**Load order when `--auto-load` is passed:**
+Relative paths are resolved relative to the **caller's file location**, like `require_relative`:
 
-1. All `*.loki` files alphabetically (e.g., `build.loki`, `deploy.loki`, `test.loki`)
-2. `.loki` itself (the entry point)
+```ruby
+# .loki — relative to this file's directory
+import "build.loki"
+import "../shared/gem_tasks.loki"
+import "tasks/ci.loki"
+```
 
-This means any tasks, classes, or variables defined in `*.loki` files are available when `.loki` runs.
+### All files in the same directory (glob)
 
-### Task Name Overloading
+```ruby
+import "*.loki"      # all *.loki files in the same directory as the calling file
+```
 
-Because all `*.loki` files reopen the same `class Tasks`, it is possible — by accident or by design — for two files to define a method with the same name. This is **task overloading**. Ruby's class reopening semantics apply: the last definition loaded wins, silently replacing the earlier one.
+`*.loki` never matches `.loki` (the dotfile entry point) — Ruby's `Dir.glob` excludes dotfiles from `*` patterns by default.
 
-Three things are overwritten when a task name is reused:
+### All files recursively (recursive glob)
 
-| What | Effect |
-|---|---|
-| `def method_name` | The Ruby method body — the earlier implementation is gone |
-| `desc` metadata | Thor registers the new usage/description string, discarding the old one |
-| `depends_on` stages | `method_added` captures the pending deps for the new definition; the earlier dep chain is replaced |
+```ruby
+import "**/*.loki"   # every .loki file in this directory and all subdirectories
+```
 
-**Accidental overloading** is a silent bug. If `build.loki` and `ci.loki` both define `def build`, only the alphabetically-later file's version runs — with no warning. Keep task names unique across files, or move shared tasks into a dedicated file loaded first.
+### Specific named files
 
-!!! warning
-    There is no runtime error when a task is overloaded. If a task is not behaving as expected, check whether another `*.loki` file defines the same method name and loads after it.
+```ruby
+import "gem_tasks.loki"
+import "ci_tasks.loki"
+```
 
-**Intentional overloading** lets you extend or wrap a task defined in an earlier file. Use `alias_method` inside a `no_commands` block to preserve the original implementation under a private name, then redefine the task to call it:
+### Combining patterns
 
 ```ruby
-# build.loki  (loaded first)
+# .loki
+import "*.loki"           # load all siblings
+import "../shared/*.loki" # load a parent-level shared library
+```
+
+### Typical `.loki` entry point
+
+```ruby
+# .loki
+import "*.loki"    # load all sibling task files
+
 class Tasks
-  desc "build", "Compile the project"
-  def build
-    sh "rake build"
-  end
+  # any top-level task definitions or overrides
 end
 ```
 
+### Return value
+
+`import` returns `true` if at least one file was newly loaded, `false` if all files were already loaded or no glob pattern matched any file. If a specific (non-glob) file does not exist, `import` raises `LoadError`.
+
 ```ruby
-# postbuild.loki  (loaded after build.loki, alphabetically)
-class Tasks
-  # Preserve the original under a private name before overwriting it.
-  no_commands { alias_method :_build_original, :build }
+import("gem_tasks.loki") ? "loaded now" : "already loaded"
+```
 
-  desc "build", "Compile the project and copy assets"
-  def build
-    _build_original          # runs the original sh "rake build"
-    sh "cp -r dist/ public/" # adds post-build step
-  end
+---
+
+## Finding Files with `loki_up`
+
+`loki_up(name = ".loki")` searches `Dir.pwd` and each ancestor directory for a file with the given name, returning a `Pathname` or `nil`. It does **not** load the file — it only finds it.
+
+Despite the name, `loki_up` is not limited to `.loki` files — it will locate any file by name. This makes it useful for finding shared config files, `.env` files, or any other resource that lives somewhere up the directory tree:
+
+```ruby
+loki_up                    # finds .loki (the project root marker)
+loki_up("gem_tasks.loki")  # finds gem_tasks.loki in CWD or any ancestor
+loki_up(".env")            # finds the nearest .env file up the tree
+loki_up("VERSION")         # finds a VERSION file in CWD or any ancestor
+```
+
+Use `loki_up` when you need the path for other purposes, or to check whether a file exists before deciding to load it:
+
+```ruby
+if (path = loki_up("gem_tasks.loki"))
+  import path
 end
+
+# Pass the located .env to dotenv — works from any subdirectory
+dotenv loki_up(".env") || ".env"
 ```
 
-`no_commands` prevents `_build_original` from appearing as a CLI command. The aliased method retains the original's full body including any `sh` calls, `var` access, and private helper calls.
+`loki_up` accepts exact filenames only. Glob patterns are not expanded by `loki_up` — use `import_up` for glob-aware ancestor search.
 
-!!! tip
-    The `_` prefix on the alias name (`_build_original`) follows Asgard's convention for non-user-facing methods and reinforces that it is an implementation detail, not a task to be invoked directly.
+---
 
-!!! warning "Prefer `depends_on` over intentional overloading"
-    Using `alias_method` to bolt post-task behaviour onto an existing task is a code smell. It is fragile (load-order dependent), obscures intent, and makes the dependency chain invisible to Asgard's cycle-detection and deduplication logic.
+## Loading Files Found up the Tree with `import_up`
 
-    The idiomatic Asgard solution is to express the relationship explicitly with `depends_on`:
+`import_up(name = ".loki")` combines `loki_up` and `import` into a single call. It finds the file (or files) up the ancestor chain and loads them.
 
-    ```ruby
-    # build.loki
-    class Tasks
-      desc "build", "Compile the project"
-      def build = sh "rake build"
+### Exact filename
 
-      desc "copy_assets", "Copy build output to public/"
-      def copy_assets = sh "cp -r dist/ public/"
+```ruby
+import_up "gem_tasks.loki"
+```
 
-      depends_on :build, :copy_assets
-      desc "build_all", "Compile and copy assets"
-      def build_all; end
-    end
-    ```
+Walks up from `Dir.pwd` until it finds `gem_tasks.loki`, then loads it. Returns `false` if not found anywhere.
+
+### Glob pattern
+
+```ruby
+import_up "*.loki"
+```
+
+Walks up from `Dir.pwd` and stops at the **first ancestor directory** that contains any `*.loki` files, loading all of them. It does not aggregate matches from multiple levels — it loads only the nearest match, then stops.
+
+```
+~/sandbox/
+  gem_tasks.loki     ← loaded by import_up("*.loki") from ~/sandbox/myproject/sub/
+  ci_tasks.loki      ← also loaded — same directory as the first match
+  myproject/
+    .loki
+    sub/
+      # Dir.pwd here; import_up("*.loki") finds ~/sandbox/*.loki files
+```
+
+### Return value
+
+Returns `true` if any file was newly loaded, `false` if the file was not found or was already loaded.
+
+### Conditional load
+
+Since `import_up` returns `false` when a file is not found (rather than raising), it composes naturally with `||`:
 
-    This approach is transparent, testable, and benefits from Asgard's deduplication — `build` will never run twice even if multiple tasks declare it as a dependency.
+```ruby
+import_up("project_tasks.loki") || import_up("gem_tasks.loki")
+```
+
+---
+
+## Idempotency
+
+Both `import` and `import_up` track loaded files in Ruby's `$LOADED_FEATURES`. A second call with the same path is a no-op and returns `false`. This means:
+
+- You can call `import "*.loki"` from both `.loki` and a shared task file without double-loading.
+- `import_up("gem_tasks.loki")` from two different projects in the same process each load their nearest match once.
+- Swapping `require` for `import` in a `.loki` file gives the same once-per-process guarantee.
 
 ---
 
-## Single File Layout
+## Verbose and Debug Feedback
 
-The simplest structure: all tasks in `.loki`, nothing else:
+`import` and `import_up` emit diagnostic messages to stderr when the `verbose?` or `debug?` flags are active (set via `--verbose` or `--debug` on the CLI, or by setting `$VERBOSE`/`$DEBUG` directly):
+
+| Flag | `import` output | `import_up` output |
+|---|---|---|
+| `--verbose` | Prints each file path as it is loaded | Prints `name → /full/path` when found |
+| `--debug` | Same as verbose, plus prints a skip message for already-loaded files | Same as verbose, plus prints `name not found` when the search comes up empty |
 
 ```
-myproject/
-  .loki
+$ asgard --verbose build
+import: /home/user/myproject/build.loki
+import: /home/user/myproject/test.loki
 ```
 
+---
+
+## Loading Patterns
+
+### Single-file project
+
+All tasks in `.loki`, nothing else:
+
 ```ruby
 # .loki
 class Tasks
-  var :app, "myapp"
+  @@app ||= "myapp".freeze
 
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "rake test"
 
-  desc "release", "Build and push the gem"
-  def release = sh "gem push pkg/#{app}-*.gem"
+  desc "Build and push the gem"
+  def release = sh "gem push pkg/#{@@app}-*.gem"
 end
 ```
 
----
-
-## Multi-File Layout
+### Multi-file project
 
-Split tasks across files by concern — each file reopens `class Tasks`:
+Split tasks across files by concern. Load them all from `.loki` with a glob:
 
 ```
 myproject/
-  .loki          ← entry point (may be empty or contain top-level task)
-  build.loki     ← build-related tasks
-  deploy.loki    ← deployment tasks
+  .loki          ← entry point; imports siblings
+  build.loki     ← build tasks
+  deploy.loki    ← deploy tasks
   test.loki      ← test tasks
 ```
 
+```ruby
+# .loki
+import "*.loki"
+```
+
 ```ruby
 # build.loki
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 end
 ```
@@ -163,7 +241,7 @@ end
 # test.loki
 class Tasks
   depends_on :build
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "bundle exec rake test"
 end
 ```
@@ -172,83 +250,158 @@ end
 # deploy.loki
 class Tasks
   depends_on :test
-  desc "deploy", "Deploy to production"
+  desc "Deploy to production"
   def deploy = sh "cap production deploy"
 end
 ```
 
-```ruby
-# .loki — can be empty, or can register subcommands, add top-level vars, etc.
-```
+Files loaded via glob are sorted alphabetically by `Dir.glob`, so `build.loki` loads before `test.loki`. Tasks defined in earlier files are available to later files via `depends_on`.
 
-Load order: `build.loki` → `deploy.loki` → `test.loki` → `.loki`.
+### Controlled load order
 
-!!! tip
-    When `--auto-load` is used, `*.loki` files are sorted alphabetically, so `build.loki` loads before `test.loki`, which means `depends_on :build` in `test.loki` correctly references a task that already exists.
+When alphabetical order does not match your dependency order, import explicitly:
 
----
+```ruby
+# .loki
+import "infra.loki"    # must be first
+import "build.loki"    # depends on infra
+import "deploy.loki"   # depends on build
+```
 
-## Explicit Loading
+### Shared task library in a monorepo
 
-You can explicitly load files from `.loki` using `require_relative`. This gives you control over load order, and lets you load plain Ruby files that are not `.loki` files:
+Place shared tasks in a parent directory and load them from any sub-project:
+
+```
+~/sandbox/
+  gem_tasks.loki        ← shared: build, install, release tasks for any gem
+  myproject/
+    .loki               ← loads gem_tasks.loki via import_up
+  other_project/
+    .loki               ← also loads gem_tasks.loki via import_up
+```
 
 ```ruby
-# .loki
-require_relative "shared/helpers"
-require_relative "ci.loki"
+# myproject/.loki
+import_up "gem_tasks.loki"   # finds ~/sandbox/gem_tasks.loki
 
 class Tasks
-  include BuildHelpers   # defined in shared/helpers.rb
-
-  desc "full-ci", "Complete CI run"
-  def full_ci = sh "echo 'full CI complete'"
+  # project-specific overrides here
 end
 ```
 
-Explicitly required files are loaded before `.loki`'s own class body is evaluated. Files loaded via `require_relative` are **not** re-loaded by the alphabetical glob — Ruby's `require_relative` marks them as loaded in `$LOADED_FEATURES`.
+### Conditional shared library
 
-!!! warning
-    If you `require_relative "ci.loki"` from `.loki` and also run `asgard --auto-load`, Asgard's glob will also load `ci.loki`. To prevent double-loading, either: (a) put explicitly loaded files in a subdirectory outside the alphabetical sweep, or (b) rely solely on `--auto-load` without `require_relative`.
+```ruby
+# .loki
+import_up("ci_tasks.loki") || import_up("gem_tasks.loki")
+```
 
----
+Loads `ci_tasks.loki` if found up the tree, otherwise falls back to `gem_tasks.loki`.
 
-## Subcommands Across Files
+### Subcommand classes across files
 
-Subcommand classes defined in separate `*.loki` files are available in `.loki` when `--auto-load` is used, because the `*.loki` files load first:
+Define subcommand classes in separate files and register them in `.loki`:
 
 ```
 myproject/
-  .loki                    ← registers subcommands
-  db_subcommands.loki      ← defines DBCommands
-  server_subcommands.loki  ← defines ServerCommands
+  .loki
+  db.loki
+  server.loki
 ```
 
 ```ruby
-# db_subcommands.loki
+# db.loki
 class DBCommands < Tasks
-  desc "migrate", "Run migrations"
+  desc "Run migrations"
   def migrate = sh "rails db:migrate"
 end
+```
 
-# server_subcommands.loki
+```ruby
+# server.loki
 class ServerCommands < Tasks
-  desc "start", "Start the server"
+  desc "Start the server"
   def start = sh "rails server"
 end
+```
 
+```ruby
 # .loki
+import "*.loki"   # db.loki and server.loki load first
+
 class Tasks
   desc "db SUBCOMMAND",     "Manage the database"; subcommand "db",     DBCommands
   desc "server SUBCOMMAND", "Manage the server";   subcommand "server", ServerCommands
 end
 ```
 
+Subcommand classes are available in `.loki` because siblings loaded via `import "*.loki"` execute before `.loki`'s own class body.
+
+---
+
+## Task Name Overloading
+
+Because all `*.loki` files reopen the same `class Tasks`, two files can define a method with the same name. Ruby's class reopening semantics apply: the last definition loaded wins, silently replacing the earlier one.
+
+Three things are overwritten when a task name is reused:
+
+| What | Effect |
+|---|---|
+| `def method_name` | The Ruby method body — the earlier implementation is gone |
+| `desc` metadata | Thor registers the new usage/description string, discarding the old one |
+| `depends_on` stages | `method_added` captures the pending deps for the new definition; the earlier dep chain is replaced |
+
+**Accidental overloading** is a silent bug. Keep task names unique across files.
+
+!!! warning
+    There is no runtime error when a task is overloaded. If a task is not behaving as expected, check whether another `.loki` file defines the same method name and loads after it.
+
+**Intentional overloading** lets you extend a task defined in an earlier file using `alias_method`:
+
+```ruby
+# build.loki  (loaded first)
+class Tasks
+  desc "Compile the project"
+  def build = sh "rake build"
+end
+
+# postbuild.loki  (loaded after build.loki, alphabetically)
+class Tasks
+  no_commands { alias_method :_build_original, :build }
+
+  desc "Compile the project and copy assets"
+  def build
+    _build_original
+    sh "cp -r dist/ public/"
+  end
+end
+```
+
+!!! warning "Prefer `depends_on` over intentional overloading"
+    Using `alias_method` to bolt post-task behaviour onto an existing task is fragile and load-order dependent. The idiomatic alternative is `depends_on`:
+
+    ```ruby
+    class Tasks
+      desc "Compile the project"
+      def build = sh "rake build"
+
+      desc "Copy build output to public/"
+      def copy_assets = sh "cp -r dist/ public/"
+
+      depends_on :build, :copy_assets
+      desc "Compile and copy assets"
+      def build_all; end
+    end
+    ```
+
 ---
 
 ## Summary of Loading Rules
 
-| File | When loaded | Purpose |
-|---|---|---|
-| `.loki` | After all `*.loki` | Project root marker; entry point |
-| `*.loki` | When `--auto-load` is passed, alphabetically before `.loki` | Task definitions that reopen `class Tasks` |
-| `require_relative` targets | At the point of the `require_relative` call | Shared helpers, explicit task files |
+| Method | Finds? | Loads? | Glob? | Ancestor search? |
+|---|---|---|---|---|
+| `loki_up(name)` | Yes (`Pathname`) | No | No | Yes |
+| `import(path)` | No | Yes | Yes | No |
+| `import_up(name)` | Yes | Yes | Yes | Yes |
+| Asgard's `run!` | Yes | `.loki` only | No | Yes |