asgard 0.1.1 → 0.2.0

data/docs/getting-started.md

@@ -0,0 +1,180 @@
+# Getting Started
+
+This guide walks you through installing Asgard, creating your first `.loki` task file, and running tasks from the command line.
+
+---
+
+## Installation
+
+=== "RubyGems"
+
+    ```bash
+    gem install asgard
+    ```
+
+=== "Bundler"
+
+    ```bash
+    bundle add asgard
+    ```
+
+    Or add it manually to your `Gemfile`:
+
+    ```ruby
+    gem "asgard", "~> 0.1"
+    ```
+
+    then run `bundle install`.
+
+---
+
+## Verify the Installation
+
+```bash
+asgard --version
+# 0.1.2
+```
+
+---
+
+## Create Your First Task File
+
+Every Asgard project needs a `.loki` file at its root. This hidden file is both the project root marker (Asgard searches upward from CWD to find it) and the entry point for your tasks.
+
+```bash
+# Create the root marker in your project directory
+touch .loki
+```
+
+Open `.loki` in your editor and add a task:
+
+```ruby
+class Tasks
+  desc "hello", "Say hello to the world"
+  def hello = sh 'echo "Hello, World!"'
+end
+```
+
+!!! note
+    The `Tasks` class is pre-defined by the gem as `class Tasks < Asgard::Base`. You just reopen it — no `require` or superclass declaration needed.
+
+---
+
+## Run Your Task
+
+```bash
+asgard hello
+# echo "Hello, World!"
+# Hello, World!
+```
+
+See all available tasks:
+
+```bash
+asgard help
+```
+
+See help for a specific task:
+
+```bash
+asgard help hello
+```
+
+---
+
+## Add a Parameter
+
+Positional parameters are declared directly in the method signature. Document them in the `desc` usage string:
+
+```ruby
+class Tasks
+  desc "greet NAME", "Greet someone by name"
+  def greet(name = "World")
+    sh "echo 'Hello, #{name}!'"
+  end
+end
+```
+
+```bash
+asgard greet
+# Hello, World!
+
+asgard greet Alice
+# Hello, Alice!
+```
+
+---
+
+## Add an Option
+
+Use `method_option` (alias: `option`) to declare named flags:
+
+```ruby
+class Tasks
+  desc "greet NAME", "Greet someone by name"
+  option :shout, aliases: "-s", type: :boolean, desc: "Uppercase the greeting"
+  def greet(name = "World")
+    msg = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
+    sh "echo '#{msg}'"
+  end
+end
+```
+
+```bash
+asgard greet Alice --shout
+# HELLO, ALICE!
+```
+
+---
+
+## Multi-Loki Structure
+
+A large Asgard project might look like this:
+
+```
+myproject/
+  .loki          ← root marker and entry point (may be empty or contain tasks)
+  build.loki     ← build-related and library dependency-related tasks
+  deploy.loki    ← deployment tasks
+  qa.loki        ← test and lint tasks
+```
+
+Each `*.loki` file reopens `class Tasks`. To load them, pass `--auto-load` to the `asgard` command — they are loaded alphabetically before `.loki`. See [Task Files](task-files.md) for full details.
+
+---
+
+## Built-in Flags
+
+Every task automatically has three flags available, defined as `class_option` on `Tasks`:
+
+| Flag | Description |
+|---|---|
+| `--version` | Print the Asgard version and exit |
+| `--debug` | Set `$DEBUG = true` before the task runs |
+| `--verbose` | Set `$VERBOSE = true` before the task runs |
+
+```bash
+asgard --version
+asgard hello --debug
+asgard hello --verbose
+```
+
+Inside a task body, use the `debug?` and `verbose?` predicates:
+
+```ruby
+def hello
+  sh "echo 'building...'"
+  sh "make --debug" if debug?
+end
+```
+
+---
+
+## Next Steps
+
+- [Defining Tasks](tasks.md) — parameters, options, aliases, long_desc
+- [Dependencies](dependencies.md) — sequential, parallel, and mixed dependency graphs
+- [Variables](variables.md) — share values across tasks
+- [Shell Helpers](shell.md) — `sh`, `shebang`, and polyglot scripts
+- [Subcommands](subcommands.md) — group related tasks under a namespace
+- [Examples](examples.md) — working `.loki` files for every feature

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.