asgard 0.1.2 → 0.3.0

data/docs/environment.md

@@ -0,0 +1,129 @@
+# Environment Variables
+
+Asgard provides the `dotenv` class method to load `.env` files into the process environment before tasks run. It is a thin wrapper around the [dotenv gem](https://github.com/bkeepers/dotenv).
+
+---
+
+## Basic Usage
+
+Call `dotenv` inside the class body (not inside a task method) to load the default `.env` file:
+
+```ruby
+class Tasks
+  dotenv   # loads .env from the current working directory
+
+  desc "Print the app name from .env"
+  def check = puts env(:app_name)
+end
+```
+
+### Load a Named File
+
+Pass a file path string to load a specific file:
+
+```ruby
+class Tasks
+  dotenv ".env.local"     # load a local override
+  dotenv ".env.staging"   # load staging-specific vars
+end
+```
+
+### Multiple Calls
+
+Call `dotenv` multiple times to load several files. Each call merges the loaded variables into `ENV`. Later calls do not overwrite variables already set by earlier calls (standard dotenv behavior):
+
+```ruby
+class Tasks
+  dotenv              # loads .env (base config)
+  dotenv ".env.local" # loads .env.local (local overrides)
+end
+```
+
+---
+
+## When `dotenv` Runs
+
+`dotenv` is a **class-level** call — it executes at Ruby class-load time, not when a task is invoked. This means:
+
+1. Variables are available in `ENV` before any task method runs.
+2. They are available during `depends_on` dependency resolution.
+
+```ruby
+class Tasks
+  dotenv
+
+  desc "Run migrations"
+  def migrate = sh "DATABASE_URL=#{env(:database_url)} rails db:migrate"
+end
+```
+
+!!! warning
+    If `.env` does not exist, `dotenv` silently does nothing — it checks `File.exist?` before loading. There is no error for a missing file.
+
+---
+
+## File Not Found
+
+Asgard calls `Dotenv.load(path)` only when `File.exist?(path)` is true. If the file is absent, the call is a no-op:
+
+```ruby
+class Tasks
+  dotenv ".env.local"   # silently skipped if .env.local does not exist
+end
+```
+
+This makes it safe to commit a `.env.local` line to your `.loki` without requiring every developer to create the file.
+
+---
+
+## Environment Variables vs. Class Variables
+
+Use `dotenv` to bring external configuration into `ENV`. Use `@@` class variables for fixed values declared in the task file, and read from `ENV` directly in task bodies or helper methods when the value comes from the environment:
+
+```ruby
+class Tasks
+  dotenv
+
+  @@app_name ||= "myapp".freeze
+
+  desc "Start the server"
+  def start
+    port = ENV.fetch("PORT", "3000").to_i
+    sh "puma -b tcp://0.0.0.0:#{port} -w #{ENV.fetch('WORKERS', '2')}"
+  end
+end
+```
+
+For `ENV` values used in multiple tasks, define a private helper method:
+
+```ruby
+class Tasks
+  dotenv
+
+  desc "Start the server"
+  def start = sh "puma -p #{port}"
+
+  desc "Show config"
+  def config = puts "#{@@app_name} on port #{port}"
+
+  private
+
+  def port = ENV.fetch("PORT", "3000").to_i
+end
+```
+
+---
+
+## Dotenv File Format
+
+Standard dotenv file syntax applies:
+
+```bash
+# .env
+APP_NAME=myapp
+DATABASE_URL=postgres://localhost/myapp_development
+REDIS_URL=redis://localhost:6379/0
+PORT=3000
+```
+
+Multi-line values and quotes are supported per the dotenv gem's own documentation.

data/docs/examples.md

@@ -0,0 +1,140 @@
+# Examples
+
+The `examples/` directory in the Asgard repository contains complete, working `.loki` files that demonstrate every feature of the gem. You can use them as a standalone Asgard project or as copy-paste references.
+
+---
+
+## Using the Examples Directory
+
+The `examples/` directory contains its own `.loki` root marker (the gem's project-level `.loki`), which means you can run `asgard` from inside the `examples/` directory and all example files will be loaded:
+
+```bash
+git clone https://github.com/MadBomber/asgard.git
+cd asgard/examples
+asgard help
+```
+
+Alternatively, copy individual example files into your own project's directory.
+
+!!! note
+    Some examples (notably `concurrent.loki`) produce visible interleaved output to demonstrate real thread concurrency. They are designed to be run, not just read.
+
+---
+
+## `kitchen_sink.loki`
+
+**Path:** `examples/kitchen_sink.loki`
+
+The most comprehensive example — demonstrates every Thor DSL feature available in Asgard:
+
+- `@@` class variables for shared configuration values
+- `dotenv` (commented out, ready to activate)
+- `class_option` with `:boolean` and `:string` types, including `enum`
+- `default_task` — sets the default command when `asgard` is run with no arguments
+- `map` — short aliases for multiple tasks
+- A basic task with no parameters
+- A task with a positional parameter and default
+- A task with `option` (the `method_option` alias)
+- All five `method_option` types: `:string`, `:boolean`, `:numeric`, `:array`, `:hash`
+- `required` option, `enum` validation, and `banner` customization
+- `long_desc` with `\x5` line-break trick for formatted examples in help text
+- Sequential `depends_on` (`:analyze` before `:spec`)
+- Parallel `depends_on` (`[:analyze, :typecheck]` run concurrently)
+- Mixed sequential + parallel `depends_on` (`:check`, `[:compile, :spec]`, `:pack`)
+- `no_commands` block for a public helper excluded from CLI
+- `private` methods for internal helpers
+
+```bash
+asgard help                # see all tasks
+asgard greet               # default task
+asgard hello Alice
+asgard compile --jobs 4 --tags debug release --defines VERSION:2 MODE:fast
+asgard deploy --strategy rolling
+asgard report --format html --since 2024-01-01
+asgard pipeline
+```
+
+---
+
+## Server Subcommands
+
+**Path:** `examples/server_subcommands.loki`
+
+Demonstrates Thor subcommands with a server management group. Covers:
+
+- Defining a subcommand class (`ServerCommands < Tasks`)
+- Registering it with `subcommand "server", ServerCommands`
+- Per-command options (`--daemon`, `--workers`, `--log`, `--force`, `--wait`)
+- `depends_on` inside a subcommand group (`:stop` and `:start` before `:restart`)
+
+```bash
+asgard server help
+asgard server start
+asgard server start 4000 --workers 4 --daemon
+asgard server stop --force
+asgard server status
+asgard server restart 4000
+```
+
+The `ServerCommands` class inherits from `Tasks`, giving it access to `sh`, `depends_on`, and the built-in `--debug`/`--verbose` flags.
+
+---
+
+## DB Subcommands
+
+**Path:** `examples/db_subcommands.loki`
+
+Demonstrates subcommands with more complex `depends_on` chaining within the group. Covers:
+
+- `DBCommands < Tasks` with migrate, rollback, seed, reset, console, and status commands
+- Multi-step `depends_on` chain: `rollback → migrate → seed → reset`
+- `long_desc` with formatted examples inside a subcommand class
+- `enum` validation on subcommand options
+- Optional positional parameters (`migrate [VERSION]`, `rollback [STEPS]`, `seed [FILE]`)
+
+```bash
+asgard db help
+asgard db migrate
+asgard db migrate 20240101120000 --dry-run
+asgard db rollback
+asgard db rollback 3
+asgard db seed --env staging
+asgard db reset         # rollback → migrate → seed → reset
+asgard db console --env staging
+asgard db status
+```
+
+---
+
+## `concurrent.loki`
+
+**Path:** `examples/concurrent.loki`
+
+A focused demonstration of true concurrent execution via parallel `depends_on` groups:
+
+- Three worker tasks (`worker_a`, `worker_b`, `worker_c`) each print a character repeatedly with random sleep delays
+- All three run in parallel threads when `asgard finish` is invoked
+- The interleaved output proves that real concurrency is occurring (not sequential batching)
+- Uses `$stdout.sync = true` to ensure thread-safe immediate output flushing
+
+```bash
+asgard finish
+# starting demo of concurrent task execution ...
+# ABCBACBACBABCBACBACB   (order varies every run)
+# fini - the end of concurrent task demo
+```
+
+Execution order: `start` → `worker_a ∥ worker_b ∥ worker_c` → `finish`
+
+This example is also useful as a test harness for verifying that parallel execution is working correctly on a given system.
+
+---
+
+## Summary
+
+| File | Primary Focus |
+|---|---|
+| `kitchen_sink.loki` | Comprehensive Thor DSL reference — options, aliases, long_desc, depends_on |
+| `server_subcommands.loki` | Subcommand groups, per-command options, depends_on in subcommands |
+| `db_subcommands.loki` | Multi-step depends_on chains, enum validation, long_desc in subcommands |
+| `concurrent.loki` | Parallel task execution, thread concurrency demonstration |

data/docs/getting-started.md

@@ -0,0 +1,179 @@
+# 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 "Say hello to the world"
+  def hello = puts "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
+# 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")
+    puts "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}!"
+    puts 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
+  puts "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,178 @@
+# 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 "Compile and package"
+  def build
+    compile("src")
+    package(app_version)
+  end
+
+  desc "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 "Compile the project"
+  def build
+    puts "Revision: #{current_sha}"
+    sh "rake build"
+  end
+
+  desc "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
+```
+
+---
+
+## 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
+
+### Within a project
+
+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 "Compile the project"
+  def build = compile("src")
+
+  desc "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.
+
+### Across projects with `import_up`
+
+If helpers are defined as tasks in a shared `.loki` file, use `import_up` to load them from any sub-project without knowing the absolute path:
+
+```
+~/sandbox/
+  shared_helpers.loki   ← defines helper tasks available to all sub-projects
+  projectA/
+    .loki
+  projectB/
+    .loki
+```
+
+```ruby
+# projectA/.loki  (and identically in projectB/.loki)
+import_up "shared_helpers.loki"
+
+class Tasks
+  # shared tasks are already defined in Tasks by here
+end
+```
+
+`import_up` walks up from `Dir.pwd` until it finds `shared_helpers.loki`, then loads it. It returns `false` without raising if the file is not found, making it safe to use in projects where the shared file may not always be present.
+
+---
+
+## 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 "Deploy to staging"
+  def staging = deploy_to("staging")
+
+  desc "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> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands</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 via <code>import</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 "Say hello"
+  def hello = puts "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 via `import "*.loki"` at the top of `.loki`. 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`, `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`