asgard 0.5.1 → 0.6.0

data/docs/subcommands.md

@@ -1,181 +0,0 @@
-# Subcommands
-
-Subcommands group related tasks under a common namespace, giving you commands like `asgard server start` or `asgard db migrate`. Asgard uses Thor's `subcommand` method for this, with one important convention: subcommand classes inherit from `Tasks` rather than from `Asgard::Base` or `Thor` directly.
-
----
-
-## Basic Pattern
-
-Define a subcommand class that inherits from `Tasks`, then register it on the top-level `Tasks` class with `subcommand`:
-
-```ruby
-class DeployCommands < Tasks
-  desc "Deploy to staging"
-  def staging = sh "cap staging deploy"
-
-  desc "Deploy to production"
-  def production = sh "cap production deploy"
-end
-
-class Tasks
-  desc "deploy SUBCOMMAND", "Deploy the application"
-  subcommand "deploy", DeployCommands
-end
-```
-
-```bash
-asgard deploy              # shows deploy subcommand help
-asgard deploy staging
-asgard deploy production
-```
-
----
-
-## Why Inherit from `Tasks`?
-
-Inheriting from `Tasks` (rather than `Asgard::Base` or `Thor`) gives the subcommand class access to:
-
-- `sh` and `shebang` shell helpers (from `Asgard::Shell`)
-- `depends_on` for dependency declarations
-- `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`
-
-!!! warning
-    Do **not** redeclare `class_option :debug` or `class_option :verbose` in your subcommand class — they are already inherited from `Tasks`. Redeclaring them causes duplicate option errors.
-
----
-
-## depends_on Within a Subcommand
-
-`depends_on` works exactly as at the top level, scoped to the subcommand's own dependency graph:
-
-```ruby
-class DBCommands < Tasks
-  desc "Run pending migrations"
-  def migrate = sh "rails db:migrate"
-
-  desc "Load seed data"
-  def seed = sh "rails db:seed"
-
-  depends_on :migrate, :seed
-  desc "Migrate then seed"
-  def reset = puts "Done."
-end
-
-class Tasks
-  desc "db SUBCOMMAND", "Manage the database"
-  subcommand "db", DBCommands
-end
-```
-
-```bash
-asgard db reset   # migrate → seed → reset
-```
-
----
-
-## Server Subcommand Example
-
-```ruby
-class ServerCommands < Tasks
-  desc "start [PORT]", "Start the server on PORT (default: 3000)"
-  option :daemon,  aliases: "-d", type: :boolean, default: false, desc: "Run as a background daemon"
-  option :workers, aliases: "-w", type: :numeric, default: 2,     desc: "Number of worker processes"
-  option :log,                    type: :string,  default: "log/server.log",
-                                  banner: "FILE", desc: "Write logs to FILE"
-  def start(port = "3000")
-    flags = []
-    flags << "--daemon"              if options[:daemon]
-    flags << "--workers #{options[:workers]}"
-    flags << "--log #{options[:log]}"
-    sh "puma -p #{port} #{flags.join(' ')}"
-  end
-
-  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 "Show server status"
-  def status = sh "pumactl stats"
-
-  depends_on :stop, :start
-  desc "restart [PORT]", "Stop then start"
-  def restart(port = "3000") = puts "Server restarted on :#{port}."
-end
-
-class Tasks
-  desc "server SUBCOMMAND", "Manage the application server"
-  subcommand "server", ServerCommands
-end
-```
-
-```bash
-asgard server start
-asgard server start 4000 --workers 4 --daemon
-asgard server stop --force
-asgard server restart
-asgard server status
-```
-
----
-
-## Scoped DSL
-
-Each subcommand class has its own independent scope for:
-
-- `desc` / `long_desc` — documentation strings
-- `method_option` / `option` — per-command options
-- `class_option` — options shared across the subcommand's tasks (in addition to inherited ones)
-- `map` — aliases within the subcommand group
-- `default_task` — which command runs when the subcommand is invoked with no further arguments
-- `depends_on` — dependency declarations scoped to this class
-
-These do not bleed into the parent `Tasks` class or other subcommand classes.
-
----
-
-## Multiple Subcommands
-
-You can register as many subcommand groups as needed:
-
-```ruby
-class ServerCommands < Tasks
-  # ... server tasks ...
-end
-
-class DBCommands < Tasks
-  # ... database tasks ...
-end
-
-class DeployCommands < Tasks
-  # ... deploy tasks ...
-end
-
-class Tasks
-  desc "server SUBCOMMAND", "Manage the server";    subcommand "server", ServerCommands
-  desc "db SUBCOMMAND",     "Manage the database";  subcommand "db",     DBCommands
-  desc "deploy SUBCOMMAND", "Deploy";               subcommand "deploy", DeployCommands
-end
-```
-
----
-
-## Subcommands Across Files
-
-Define each subcommand class in its own `.loki` file. Because all files reopen the same Ruby classes, the classes are available when `.loki` registers them:
-
-```
-myproject/
-  .loki                    ← registers all subcommands
-  server_subcommands.loki  ← defines ServerCommands
-  db_subcommands.loki      ← defines DBCommands
-```
-
-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,407 +0,0 @@
-# Task Files
-
-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 and is the only file Asgard loads automatically.
-
-```
-myproject/
-  .loki         ← found regardless of which subdirectory you're in
-  src/
-    app/
-      # asgard still works from here
-```
-
-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 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.
-
-### Single file by absolute path
-
-```ruby
-import "/home/shared/gem_tasks.loki"
-```
-
-### Single file by relative path
-
-Relative paths are resolved relative to the **caller's file location**, like `require_relative`:
-
-```ruby
-# .loki — relative to this file's directory
-import "build.loki"
-import "../shared/gem_tasks.loki"
-import "tasks/ci.loki"
-```
-
-### All files in the same directory (glob)
-
-```ruby
-import "*.loki"      # all *.loki files in the same directory as the calling file
-```
-
-`*.loki` never matches `.loki` (the dotfile entry point) — Ruby's `Dir.glob` excludes dotfiles from `*` patterns by default.
-
-### All files recursively (recursive glob)
-
-```ruby
-import "**/*.loki"   # every .loki file in this directory and all subdirectories
-```
-
-### Specific named files
-
-```ruby
-import "gem_tasks.loki"
-import "ci_tasks.loki"
-```
-
-### Combining patterns
-
-```ruby
-# .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
-  # 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
-import("gem_tasks.loki") ? "loaded now" : "already loaded"
-```
-
----
-
-## 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"
-```
-
-`loki_up` accepts exact filenames only. Glob patterns are not expanded by `loki_up` — use `import_up` for glob-aware ancestor search.
-
----
-
-## Loading Files Found up the Tree with `import_up`
-
-`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.
-
-### Exact filename
-
-```ruby
-import_up "gem_tasks.loki"
-```
-
-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 `||`:
-
-```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.
-
----
-
-## Verbose and Debug Feedback
-
-`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 |
-
-```
-$ 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
-  @@app ||= "myapp".freeze
-
-  desc "Compile the project"
-  def build = sh "rake build"
-
-  desc "Run the test suite"
-  def test = sh "rake test"
-
-  desc "Build and push the gem"
-  def release = sh "gem push pkg/#{@@app}-*.gem"
-end
-```
-
-### Multi-file project
-
-Split tasks across files by concern. Load them all from `.loki` with a glob:
-
-```
-myproject/
-  .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 "Compile the project"
-  def build = sh "rake build"
-end
-```
-
-```ruby
-# test.loki
-class Tasks
-  depends_on :build
-  desc "Run the test suite"
-  def test = sh "bundle exec rake test"
-end
-```
-
-```ruby
-# deploy.loki
-class Tasks
-  depends_on :test
-  desc "Deploy to production"
-  def deploy = sh "cap production deploy"
-end
-```
-
-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`.
-
-### Controlled load order
-
-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
-```
-
-### Shared task library in a monorepo
-
-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
-# myproject/.loki
-import_up "gem_tasks.loki"   # finds ~/sandbox/gem_tasks.loki
-
-class Tasks
-  # project-specific overrides here
-end
-```
-
-### Conditional shared library
-
-```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`.
-
-### Subcommand classes across files
-
-Define subcommand classes in separate files and register them in `.loki`:
-
-```
-myproject/
-  .loki
-  db.loki
-  server.loki
-```
-
-```ruby
-# db.loki
-class DBCommands < Tasks
-  desc "Run migrations"
-  def migrate = sh "rails db:migrate"
-end
-```
-
-```ruby
-# server.loki
-class ServerCommands < Tasks
-  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
-
-| 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 |