asgard 0.1.2 → 0.2.0

data/docs/helpers.md

@@ -0,0 +1,154 @@
+# Helper Methods
+
+Not every method needs to be a CLI command. Asgard (via Thor) provides two mechanisms to define callable helper methods that are excluded from `asgard help` and cannot be invoked directly from the command line.
+
+---
+
+## Private Methods
+
+Methods declared after `private` are callable from any task in the same class but are invisible to Thor's command dispatcher. They will not appear in `--help` output and cannot be called from the CLI:
+
+```ruby
+class Tasks
+  desc "build", "Compile and package"
+  def build
+    compile("src")
+    package(app_version)
+  end
+
+  desc "release", "Build and publish to RubyGems"
+  def release
+    build
+    sh "gem push pkg/myapp-#{app_version}.gem"
+  end
+
+  private
+
+  def compile(dir)
+    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
+  end
+
+  def package(ver)
+    sh "tar czf pkg/myapp-#{ver}.tar.gz bin/"
+  end
+
+  def app_version
+    `git describe --tags`.strip
+  end
+end
+```
+
+!!! note
+    In Ruby, `private` applies to all methods defined after it in the same class body. You can group all helpers at the bottom of the class after a single `private` declaration.
+
+---
+
+## The `no_commands` Block
+
+Thor's `no_commands` block marks public methods as excluded from CLI discovery. Unlike `private`, these methods are still publicly accessible from Ruby code (e.g., from a subclass or a module). They are useful for methods that must be public for technical reasons but should not appear as commands:
+
+```ruby
+class Tasks
+  desc "build", "Compile the project"
+  def build
+    puts "Revision: #{current_sha}"
+    sh "rake build"
+  end
+
+  desc "deploy", "Deploy to production"
+  def deploy
+    puts "Deploying revision #{current_sha}..."
+    sh "cap production deploy"
+  end
+
+  no_commands do
+    def current_sha
+      `git rev-parse --short HEAD`.strip
+    end
+
+    def timestamp
+      Time.now.strftime("%Y%m%d-%H%M%S")
+    end
+  end
+end
+```
+
+`var`-declared variables are also implemented using `no_commands` internally, which is why they appear as callable methods but not as CLI commands.
+
+---
+
+## Choosing Between `private` and `no_commands`
+
+| | `private` | `no_commands` |
+|---|---|---|
+| Hidden from `--help` | Yes | Yes |
+| Blocked from CLI | Yes | Yes |
+| Accessible from subclass | No | Yes |
+| Accessible from module include | No | Yes |
+| Ruby idiom | Familiar | Thor-specific |
+
+For most helpers, `private` is the right choice. Use `no_commands` when the helper must remain technically public (e.g., it will be inherited by a subcommand class).
+
+---
+
+## Sharing Helpers Across Files
+
+Extract shared helpers into a plain Ruby module and load it from `.loki` using `require_relative`:
+
+```ruby
+# shared/helpers.rb
+module BuildHelpers
+  private
+
+  def compile(dir)
+    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
+  end
+
+  def dist_path(ver)
+    "pkg/myapp-#{ver}.tar.gz"
+  end
+end
+```
+
+```ruby
+# .loki
+require_relative "shared/helpers"
+
+class Tasks
+  include BuildHelpers
+
+  desc "build", "Compile the project"
+  def build = compile("src")
+
+  desc "package", "Create distribution archive"
+  def package = sh "tar czf #{dist_path(app_version)} bin/"
+end
+```
+
+Because `include` in the class body makes the module methods available as instance methods, and they are declared `private` inside the module, they remain invisible to Thor.
+
+!!! tip
+    Helpers in a shared module can call `sh`, `shebang`, and other Asgard DSL methods because those are included in `Tasks` (via `Asgard::Base` and `Asgard::Shell`) and are available in `self` when the module method is invoked.
+
+---
+
+## Helper Methods in Subcommands
+
+Subcommand classes that inherit from `Tasks` also inherit all private helpers and `no_commands` methods defined on `Tasks`. You can also define helpers local to the subcommand class:
+
+```ruby
+class DeployCommands < Tasks
+  desc "staging", "Deploy to staging"
+  def staging = deploy_to("staging")
+
+  desc "production", "Deploy to production"
+  def production = deploy_to("production")
+
+  private
+
+  def deploy_to(env)
+    sh "cap #{env} deploy REV=#{current_sha}"
+  end
+  # current_sha is inherited from Tasks if defined there
+end
+```

data/docs/index.md

@@ -0,0 +1,85 @@
+# Asgard
+
+<table>
+<tr>
+<td width="40%" align="center" valign="top">
+<img src="assets/images/asgard.jpg" alt="Asgard" width="300"><br>
+<em>"Loki collects the tricks.<br>Thor of Asgard runs them."</em>
+</td>
+<td width="60%" valign="top">
+<strong>Key Features</strong>
+<ul>
+<li><strong>Thor-Powered CLI</strong> — every Thor DSL feature available inside <code>.loki</code> task files</li>
+<li><strong>Task Dependencies</strong> — sequential, parallel, and mixed dependency graphs via <code>depends_on</code></li>
+<li><strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads</li>
+<li><strong>Subcommands</strong> — group related tasks under a named namespace</li>
+<li><strong>Variables</strong> — static values and lazy-evaluated lambdas via <code>var</code></li>
+<li><strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts</li>
+<li><strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code></li>
+<li><strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories</li>
+<li><strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded on demand with <code>--auto-load</code></li>
+<li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, and <code>--verbose</code> available on every task</li>
+</ul>
+</td>
+</tr>
+</table>
+
+Asgard is a [Thor](https://github.com/rails/thor)-based task runner for Ruby projects. Define tasks in `.loki` files, declare dependencies between them, and let Asgard handle ordering and concurrent execution. Anything Thor can do — subcommands, typed options, argument validation — is available inside a `.loki` file.
+
+---
+
+## Quick Start
+
+```bash
+# Install
+gem install asgard
+
+# Create your project root marker
+touch .loki
+
+# Add your first task
+cat >> .loki << 'EOF'
+class Tasks
+  desc "hello", "Say hello"
+  def hello = sh 'echo "Hello from Asgard!"'
+end
+EOF
+
+# Run it
+asgard hello
+```
+
+---
+
+## How It Works
+
+Asgard searches upward from your current directory for a `.loki` file. That file marks the project root. Additional `*.loki` files in the same directory can be loaded by passing `--auto-load` to the `asgard` command. All task files reopen `class Tasks`, which is pre-defined by the gem as a subclass of `Asgard::Base` (itself a Thor subclass).
+
+The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_desc`, `argument`, `default_task`, `map`, and `subcommand` all work exactly as documented in Thor — with Asgard's own `depends_on`, `var`, `sh`, `shebang`, and `dotenv` layered on top.
+
+---
+
+## Documentation
+
+| Section | Description |
+|---|---|
+| [Getting Started](getting-started.md) | Install, create your first `.loki`, run your first task |
+| [Defining Tasks](tasks.md) | Parameters, options, long_desc, aliases, default_task |
+| [Dependencies](dependencies.md) | Sequential, parallel, and mixed dependency graphs |
+| [Variables](variables.md) | Static and lazy-evaluated task variables |
+| [Helper Methods](helpers.md) | Private helpers and the `no_commands` block |
+| [Options & Flags](options.md) | class_option, built-in flags, debug? and verbose? |
+| [Subcommands](subcommands.md) | Grouping tasks under a namespace |
+| [Shell Helpers](shell.md) | `sh`, `shebang`, and supported interpreters |
+| [Environment](environment.md) | Loading `.env` files with `dotenv` |
+| [Task Files](task-files.md) | `.loki` root marker, `--auto-load`, multi-file layout |
+| [API Reference](api.md) | Module methods, DSL methods, error classes |
+| [Examples](examples.md) | Working `.loki` files for every feature |
+| [Changelog](changelog.md) | Release history |
+
+---
+
+## Requirements
+
+- Ruby >= 3.2.0
+- Dependencies: [thor](https://github.com/rails/thor) `~> 1.0`, [dagwood](https://rubygems.org/gems/dagwood) `~> 1.0`, [dotenv](https://github.com/bkeepers/dotenv) `~> 3.0`

data/docs/options.md

@@ -0,0 +1,180 @@
+# Options & Flags
+
+Asgard tasks use the full Thor option system. Options declared with `method_option` (alias: `option`) apply to a single task. Options declared with `class_option` apply to every task in the class. Asgard ships with three built-in `class_option` declarations on `Tasks`: `--debug`, `--verbose`, and `--version`.
+
+---
+
+## Per-Task Options
+
+`method_option` (or its alias `option`) declares an option for the immediately following task:
+
+```ruby
+class Tasks
+  desc "deploy ENV", "Deploy to ENV"
+  method_option :branch,
+                aliases: "-b",
+                type:    :string,
+                default: "main",
+                desc:    "Git branch to deploy"
+  method_option :dry_run,
+                aliases: "-n",
+                type:    :boolean,
+                default: false,
+                desc:    "Print commands without running"
+  def deploy(env = "staging")
+    if options[:dry_run]
+      puts "Would deploy #{options[:branch]} to #{env}"
+    else
+      sh "cap #{env} deploy BRANCH=#{options[:branch]}"
+    end
+  end
+end
+```
+
+Access option values inside the task body via `options[:name]` (a hash keyed by symbol).
+
+---
+
+## Class Options (Shared Across All Tasks)
+
+`class_option` defines an option available on every task in the class. Add your own to complement the built-in ones:
+
+```ruby
+class Tasks
+  class_option :dry_run,
+               aliases: "-n",
+               type:    :boolean,
+               default: false,
+               desc:    "Print commands without running"
+
+  class_option :env,
+               type:    :string,
+               default: "development",
+               enum:    %w[development staging production],
+               desc:    "Target environment"
+
+  desc "deploy", "Deploy the application"
+  def deploy
+    if options[:dry_run]
+      puts "Would deploy to #{options[:env]}"
+    else
+      sh "cap #{options[:env]} deploy"
+    end
+  end
+
+  desc "migrate", "Run database migrations"
+  def migrate
+    sh "rails db:migrate RAILS_ENV=#{options[:env]}"
+  end
+end
+```
+
+Both `deploy` and `migrate` automatically accept `--dry-run` and `--env`.
+
+---
+
+## Built-in Flags
+
+`Tasks` ships with three built-in class options and a version flag:
+
+### `--version`
+
+Prints `Asgard::VERSION` and exits. Implemented as the `_version` method with the `_` prefix convention (gem-owned, blocked from direct CLI invocation):
+
+```bash
+asgard --version
+# 0.1.2
+```
+
+### `--debug`
+
+A `class_option :debug` of type `:boolean`. When passed, sets `$DEBUG = true` before the task body runs (via the `invoke_command` hook in `Asgard::Base`):
+
+```bash
+asgard build --debug
+```
+
+Inside the task, use the `debug?` predicate:
+
+```ruby
+def build
+  sh "rake build"
+  sh "rake build --trace" if debug?
+end
+```
+
+### `--verbose`
+
+A `class_option :verbose` of type `:boolean`. When passed, sets `$VERBOSE = true` before the task body runs:
+
+```bash
+asgard test --verbose
+```
+
+Inside the task, use the `verbose?` predicate:
+
+```ruby
+def test
+  flags = verbose? ? "--verbose" : ""
+  sh "bundle exec rake test #{flags}"
+end
+```
+
+---
+
+## `debug?` and `verbose?` Predicates
+
+Both are private methods on `Tasks`, thin wrappers around the global variables:
+
+```ruby
+private
+
+def debug?   = $DEBUG
+def verbose? = $VERBOSE
+```
+
+They are available in every task body and in subcommand classes that inherit from `Tasks`. Because `--debug` and `--verbose` are `class_option` declarations (not standalone commands), they work as modifiers alongside any task:
+
+```bash
+asgard build --debug --verbose
+asgard deploy production --verbose
+```
+
+---
+
+## Option Types Reference
+
+| Type | CLI Example | Ruby Value |
+|---|---|---|
+| `:string` | `--branch main` | `"main"` |
+| `:boolean` | `--force` / `--no-force` | `true` / `false` |
+| `:numeric` | `--count 3` | `3` |
+| `:array` | `--tags foo bar baz` | `["foo", "bar", "baz"]` |
+| `:hash` | `--vars KEY:val FOO:bar` | `{"KEY"=>"val", "FOO"=>"bar"}` |
+
+---
+
+## Option Keys Reference
+
+| Key | Applies to | Description |
+|---|---|---|
+| `aliases` | `method_option`, `class_option` | Short-form flag string, e.g. `"-b"` |
+| `type` | `method_option`, `class_option` | One of the five types above |
+| `default` | `method_option`, `class_option` | Value used when the flag is omitted |
+| `required` | `method_option` | Raises an error if the flag is missing |
+| `desc` | `method_option`, `class_option` | One-line description shown in help |
+| `enum` | `method_option`, `class_option` | Allowed values; validated by Thor |
+| `banner` | `method_option` | Placeholder shown in help for the value slot |
+
+---
+
+## `_` Prefix Convention
+
+Methods whose names start with `_` are considered gem-owned in Asgard's naming convention. `run!` guards against invoking them directly from the CLI:
+
+```bash
+asgard _version
+# asgard: unknown command '_version'
+```
+
+If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being silently blocked.

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
+```