asgard 0.1.1 → 0.2.0

data/docs/shell.md

@@ -0,0 +1,208 @@
+# Shell Helpers
+
+Asgard provides two methods for running shell commands and scripts from within task bodies: `sh` for shell commands and heredocs, and `shebang` for polyglot scripts. Both are provided by `Asgard::Shell` and mixed into every `Tasks` instance.
+
+Both methods exit with the command's status code on failure — they do not raise Ruby exceptions.
+
+---
+
+## `sh` — Run Shell Commands
+
+### Single-Line Command
+
+Pass a single-line string to run it via `system`:
+
+```ruby
+class Tasks
+  desc "build", "Compile the project"
+  def build = sh "rake build"
+
+  desc "clean", "Remove build artifacts"
+  def clean = sh "rm -rf dist/ tmp/"
+end
+```
+
+By default, `sh` prints the command before running it:
+
+```
+rake build
+```
+
+### Multi-Line Heredoc
+
+Pass a multiline string (e.g., a heredoc) to run it as a single `bash -c` script. All lines execute in the same shell session, so variable assignments carry across lines:
+
+```ruby
+class Tasks
+  desc "setup", "Bootstrap the development environment"
+  def setup
+    sh <<~SHELL
+      brew install redis postgresql
+      brew services start redis
+      bundle install
+      rails db:setup
+    SHELL
+  end
+end
+```
+
+Asgard detects the newline and automatically routes multiline scripts through `bash -c`.
+
+### Silent Mode
+
+Pass `silent: true` to suppress the command echo. The command still runs and still exits on failure; it just doesn't print the command text first:
+
+```ruby
+class Tasks
+  desc "build", "Compile (quiet)"
+  def build = sh "rake build", silent: true
+
+  desc "info", "Print environment info without noise"
+  def info
+    sh "printenv | grep APP_", silent: true
+  end
+end
+```
+
+### Exit on Failure
+
+`sh` always calls `exit($?.exitstatus)` if the command fails. There is no rescue path — a failing command terminates the `asgard` process. This is intentional: failed steps should stop the pipeline rather than silently continue.
+
+```ruby
+class Tasks
+  depends_on :test
+  desc "release", "Test then release"
+  def release
+    sh "bundle exec rake release"
+    # Never reached if rake release fails
+    puts "Released!"
+  end
+end
+```
+
+---
+
+## `shebang` — Polyglot Scripts
+
+`shebang` writes the script body to a tempfile with the appropriate extension and executes it with the specified interpreter. Use it to embed Python, Node.js, Ruby, Perl, or any other interpreter directly in a task:
+
+### Python
+
+```ruby
+class Tasks
+  desc "analyze", "Run Python data analysis"
+  def analyze
+    shebang :python3, <<~PYTHON
+      import json
+      data = json.load(open("results.json"))
+      print(f"Total: {sum(data.values())}")
+    PYTHON
+  end
+end
+```
+
+### Node.js
+
+```ruby
+class Tasks
+  desc "bundle_assets", "Build frontend assets with esbuild"
+  def bundle_assets
+    shebang :node, <<~JS
+      const esbuild = require("esbuild")
+      esbuild.buildSync({
+        entryPoints: ["src/app.js"],
+        bundle: true,
+        outfile: "dist/app.js"
+      })
+    JS
+  end
+end
+```
+
+### Ruby
+
+```ruby
+class Tasks
+  desc "transform", "Transform data with Ruby"
+  def transform
+    shebang :ruby, <<~RUBY
+      require "json"
+      data = JSON.parse(File.read("input.json"))
+      File.write("output.json", JSON.pretty_generate(data.transform_values(&:upcase)))
+    RUBY
+  end
+end
+```
+
+### Bash
+
+```ruby
+class Tasks
+  desc "provision", "Run a bash provisioning script"
+  def provision
+    shebang :bash, <<~BASH
+      set -euo pipefail
+      apt-get update
+      apt-get install -y curl wget git
+      echo "Provisioned at $(date)"
+    BASH
+  end
+end
+```
+
+---
+
+## Supported Interpreters
+
+| Symbol | File Extension | Interpreter |
+|---|---|---|
+| `:python3` | `.py` | `python3` |
+| `:python` | `.py` | `python` |
+| `:node` | `.js` | `node` |
+| `:ruby` | `.rb` | `ruby` |
+| `:perl` | `.pl` | `perl` |
+| `:bash` | `.sh` | `bash` |
+| `:sh` | `.sh` | `sh` |
+| Any other symbol | `.tmp` | Passed directly to `system` |
+
+!!! note
+    Unknown interpreter symbols get a `.tmp` extension and are passed to `system` directly. This makes it easy to use interpreters not in the table above:
+
+    ```ruby
+    shebang :lua, <<~LUA
+      print("Hello from Lua!")
+    LUA
+    ```
+
+### Silent Mode
+
+`shebang` also accepts `silent: true`, though in practice the interpreter itself controls what is printed:
+
+```ruby
+def analyze
+  shebang :python3, script_body, silent: true
+end
+```
+
+---
+
+## Combining `sh` and `shebang`
+
+You can mix both in the same task:
+
+```ruby
+class Tasks
+  desc "pipeline", "Run a mixed shell + Python pipeline"
+  def pipeline
+    sh "bundle exec rake build"
+
+    shebang :python3, <<~PYTHON
+      import subprocess
+      result = subprocess.run(["./bin/validate"], capture_output=True, text=True)
+      print(result.stdout)
+    PYTHON
+
+    sh "rake deploy"
+  end
+end
+```

data/docs/subcommands.md

@@ -0,0 +1,181 @@
+# 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 "staging", "Deploy to staging"
+  def staging = sh "cap staging deploy"
+
+  desc "production", "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
+- `var` for variables
+- `dotenv` for environment loading
+- 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 "migrate", "Run pending migrations"
+  def migrate = sh "rails db:migrate"
+
+  desc "seed", "Load seed data"
+  def seed = sh "rails db:seed"
+
+  depends_on :migrate, :seed
+  desc "reset", "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", "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"
+  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
+```
+
+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.
+
+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

@@ -0,0 +1,254 @@
+# 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`.
+
+---
+
+## 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:
+
+```
+myproject/
+  .loki         ← found regardless of which subdirectory you're in
+  src/
+    app/
+      # 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.
+
+---
+
+## Loading `*.loki` Files with `--auto-load`
+
+By default, `asgard` only loads `.loki`. To also load `*.loki` files, pass `--auto-load`:
+
+```bash
+asgard --auto-load <task>
+```
+
+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.
+
+**Load order when `--auto-load` is passed:**
+
+1. All `*.loki` files alphabetically (e.g., `build.loki`, `deploy.loki`, `test.loki`)
+2. `.loki` itself (the entry point)
+
+This means any tasks, classes, or variables defined in `*.loki` files are available when `.loki` runs.
+
+### Task Name Overloading
+
+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.
+
+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. 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.
+
+!!! 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 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:
+
+```ruby
+# build.loki  (loaded first)
+class Tasks
+  desc "build", "Compile the project"
+  def build
+    sh "rake build"
+  end
+end
+```
+
+```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 }
+
+  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
+end
+```
+
+`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.
+
+!!! 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.
+
+    The idiomatic Asgard solution is to express the relationship explicitly with `depends_on`:
+
+    ```ruby
+    # build.loki
+    class Tasks
+      desc "build", "Compile the project"
+      def build = sh "rake build"
+
+      desc "copy_assets", "Copy build output to public/"
+      def copy_assets = sh "cp -r dist/ public/"
+
+      depends_on :build, :copy_assets
+      desc "build_all", "Compile and copy assets"
+      def build_all; end
+    end
+    ```
+
+    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.
+
+---
+
+## Single File Layout
+
+The simplest structure: all tasks in `.loki`, nothing else:
+
+```
+myproject/
+  .loki
+```
+
+```ruby
+# .loki
+class Tasks
+  var :app, "myapp"
+
+  desc "build", "Compile the project"
+  def build = sh "rake build"
+
+  desc "test", "Run the test suite"
+  def test = sh "rake test"
+
+  desc "release", "Build and push the gem"
+  def release = sh "gem push pkg/#{app}-*.gem"
+end
+```
+
+---
+
+## Multi-File Layout
+
+Split tasks across files by concern — each file reopens `class Tasks`:
+
+```
+myproject/
+  .loki          ← entry point (may be empty or contain top-level task)
+  build.loki     ← build-related tasks
+  deploy.loki    ← deployment tasks
+  test.loki      ← test tasks
+```
+
+```ruby
+# build.loki
+class Tasks
+  desc "build", "Compile the project"
+  def build = sh "rake build"
+end
+```
+
+```ruby
+# test.loki
+class Tasks
+  depends_on :build
+  desc "test", "Run the test suite"
+  def test = sh "bundle exec rake test"
+end
+```
+
+```ruby
+# deploy.loki
+class Tasks
+  depends_on :test
+  desc "deploy", "Deploy to production"
+  def deploy = sh "cap production deploy"
+end
+```
+
+```ruby
+# .loki — can be empty, or can register subcommands, add top-level vars, etc.
+```
+
+Load order: `build.loki` → `deploy.loki` → `test.loki` → `.loki`.
+
+!!! 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.
+
+---
+
+## Explicit Loading
+
+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:
+
+```ruby
+# .loki
+require_relative "shared/helpers"
+require_relative "ci.loki"
+
+class Tasks
+  include BuildHelpers   # defined in shared/helpers.rb
+
+  desc "full-ci", "Complete CI run"
+  def full_ci = sh "echo 'full CI complete'"
+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`.
+
+!!! 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`.
+
+---
+
+## Subcommands Across Files
+
+Subcommand classes defined in separate `*.loki` files are available in `.loki` when `--auto-load` is used, because the `*.loki` files load first:
+
+```
+myproject/
+  .loki                    ← registers subcommands
+  db_subcommands.loki      ← defines DBCommands
+  server_subcommands.loki  ← defines ServerCommands
+```
+
+```ruby
+# db_subcommands.loki
+class DBCommands < Tasks
+  desc "migrate", "Run migrations"
+  def migrate = sh "rails db:migrate"
+end
+
+# server_subcommands.loki
+class ServerCommands < Tasks
+  desc "start", "Start the server"
+  def start = sh "rails server"
+end
+
+# .loki
+class Tasks
+  desc "db SUBCOMMAND",     "Manage the database"; subcommand "db",     DBCommands
+  desc "server SUBCOMMAND", "Manage the server";   subcommand "server", ServerCommands
+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 |