asgard 0.2.0 → 0.3.0

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 its absolute path 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 | No | No | Yes |
+| `import(path)` | No | Yes | Yes | No |
+| `import_up(name)` | Yes | Yes | Yes | Yes |
+| Asgard's `run!` | Yes | `.loki` only | No | Yes |

data/docs/tasks.md

@@ -10,12 +10,12 @@ A task with no parameters and no options:
 
 ```ruby
 class Tasks
-  desc "hello", "Say hello"
-  def hello = sh 'echo "Hello, World!"'
+  desc "Say hello"
+  def hello = puts "Hello, World!"
 end
 ```
 
-`desc` takes two arguments: the usage string and the one-line description shown in `asgard help`.
+`desc` accepts either one or two strings. With one argument, the description is shown in `asgard help` and the usage string defaults to the method name. Pass two arguments when the usage string needs to document parameters — `desc "greet NAME", "Greet NAME by name"`.
 
 ```bash
 asgard hello
@@ -31,7 +31,7 @@ Positional parameters are declared directly in the method signature. Document th
 class Tasks
   desc "greet NAME", "Greet NAME; omit NAME to greet the world"
   def greet(name = "World")
-    sh "echo 'Hello, #{name}!'"
+    puts "Hello, #{name}!"
   end
 end
 ```
@@ -51,7 +51,7 @@ Use `method_option` (alias: `option`) for named flags. Access them inside the me
 
 ```ruby
 class Tasks
-  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"
@@ -117,7 +117,7 @@ asgard deploy production --strategy blue-green
 
 ```ruby
 class Tasks
-  desc "build", "Build the project"
+  desc "Build the project"
   option :env,
          type:    :string,
          default: "development",
@@ -139,7 +139,7 @@ Thor validates the value against the enum and shows a helpful error if it doesn'
 
 ```ruby
 class Tasks
-  desc "wait", "Wait for a service to become available"
+  desc "Wait for a service to become available"
   option :timeout, type: :numeric, default: 30, banner: "SECONDS", desc: "Give up after SECONDS"
   def wait
     sh "wait-for-it --timeout #{options[:timeout]}"
@@ -169,7 +169,7 @@ class Tasks
       asgard report --format json --output report.json\x5
       asgard report --format text
   DESC
-  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"
   def report
@@ -191,7 +191,7 @@ end
 class Tasks
   default_task :greet
 
-  desc "greet", "Say hello (runs by default)"
+  desc "Say hello (runs by default)"
   def greet
     puts "Hello from Asgard!"
   end
@@ -202,6 +202,8 @@ end
 asgard        # same as: asgard greet
 ```
 
+Without `default_task`, running `asgard` with no arguments displays the help message.
+
 ---
 
 ## Command Aliases
@@ -215,13 +217,13 @@ class Tasks
   map "t"   => "test"
   map "b"   => "build"
 
-  desc "version", "Print the version"
+  desc "Print the version"
   def version = puts Asgard::VERSION
 
-  desc "test", "Run tests"
+  desc "Run tests"
   def test = sh "bundle exec rake test"
 
-  desc "build", "Build the gem"
+  desc "Build the gem"
   def build = sh "bundle exec rake build"
 end
 ```
@@ -249,14 +251,14 @@ class Tasks
            desc:    "Name to greet"
 
   desc "hello NAME", "Say hello to NAME"
-  def hello = sh "echo 'Hello, #{name}!'"
+  def hello = puts "Hello, #{name}!"
 end
 ```
 
 For most multi-task `.loki` files, the simpler positional default pattern is safer:
 
 ```ruby
-def hello(name = "World") = sh "echo 'Hello, #{name}!'"
+def hello(name = "World") = puts "Hello, #{name}!"
 ```
 
 ---
@@ -267,7 +269,7 @@ def hello(name = "World") = sh "echo 'Hello, #{name}!'"
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build
     puts "Revision: #{current_sha}"
     sh "rake build"