asgard 0.1.2 → 0.2.0

data/docs/dependencies.md

@@ -0,0 +1,221 @@
+# Task Dependencies
+
+`depends_on` declares what must run before a task. Asgard resolves the dependency graph at startup, validates it for cycles, and executes prerequisites automatically when a task is invoked.
+
+!!! note
+    `desc` and `depends_on` are independent — either can come first. Both must appear before the `def`.
+
+---
+
+## How It Works
+
+When you run `asgard <task>`, Asgard:
+
+1. Validates the full dependency graph for circular references (fails fast with a clear error).
+2. Resolves the dependency stages for the requested task in order.
+3. Executes each stage — running parallel groups in native Ruby threads.
+4. Runs the task itself after all prerequisites complete.
+
+**Deduplication:** each task runs at most once per `asgard` invocation, regardless of how many other tasks declare it as a dependency. This is enforced thread-safely via a class-level `Set` and `Mutex`.
+
+---
+
+## Sequential Dependencies
+
+Bare symbols run one after another in the order declared:
+
+```ruby
+class Tasks
+  desc "build", "Compile the project"
+  def build = sh "rake build"
+
+  depends_on :build
+  desc "test", "Run the test suite"
+  def test = sh "rake test"
+
+  depends_on :test
+  desc "release", "Publish the gem"
+  def release = sh "bundle exec rake release"
+end
+```
+
+```bash
+asgard release   # build → test → release
+```
+
+Multiple sequential dependencies in a single `depends_on` call run left to right:
+
+```ruby
+depends_on :clean, :build, :test
+desc "package", "Clean, build, and test"
+def package = sh "rake package"
+```
+
+---
+
+## Parallel Dependencies
+
+Wrap symbols in an array to declare they can run concurrently. Asgard waits for all tasks in a parallel group to finish before moving to the next stage:
+
+```ruby
+class Tasks
+  desc "lint", "Check code style"
+  def lint = sh "bundle exec rubocop"
+
+  desc "typecheck", "Run type checks"
+  def typecheck = sh "bundle exec srb tc"
+
+  depends_on [:lint, :typecheck]
+  desc "test", "Run tests (after lint and typecheck)"
+  def test = sh "bundle exec rake test"
+end
+```
+
+```bash
+asgard test   # lint ∥ typecheck → test
+```
+
+Parallel groups run in native Ruby threads. For CPU-bound work, keep in mind the GVL; for I/O-bound work (shell commands, network), true concurrency is achieved.
+
+---
+
+## Mixed Sequential and Parallel
+
+Mix bare symbols and arrays in a single `depends_on` call. Execution proceeds stage by stage — each stage completes before the next begins:
+
+```ruby
+class Tasks
+  desc "setup",  "Install dependencies"; def setup  = sh "bundle install"
+  desc "lint",   "Check code style";     def lint   = sh "bundle exec rubocop"
+  desc "build",  "Compile assets";       def build  = sh "rake assets:precompile"
+  desc "test",   "Run tests";            def test   = sh "bundle exec rake test"
+  desc "notify", "Post to Slack";        def notify = sh "curl $SLACK_WEBHOOK -d '{\"text\":\"done\"}'"
+
+  # setup first, then lint+build in parallel, then test, then notify
+  depends_on :setup, [:lint, :build], :test, :notify
+  desc "ci", "Full CI pipeline"
+  def ci = sh "echo 'CI complete'"
+end
+```
+
+```bash
+asgard ci
+```
+
+Execution order:
+
+```
+setup
+  ↓
+lint ∥ build    (concurrent)
+  ↓
+test
+  ↓
+notify
+  ↓
+ci
+```
+
+---
+
+## Deduplication
+
+Each task runs at most once per `asgard` invocation. If multiple tasks declare the same dependency, it executes only on its first encounter:
+
+```ruby
+class Tasks
+  desc "setup", "Install gems"
+  def setup = sh "bundle install"
+
+  depends_on :setup
+  desc "test", "Run tests"
+  def test = sh "rake test"
+
+  depends_on :setup
+  desc "lint", "Check style"
+  def lint = sh "rubocop"
+
+  depends_on [:test, :lint]
+  desc "ci", "Test and lint (setup runs once)"
+  def ci = puts "done"
+end
+```
+
+When `asgard ci` runs, `setup` executes once even though both `test` and `lint` declare it as a dependency. The deduplication set is managed with a `Mutex` so parallel groups are also safe.
+
+---
+
+## Circular Dependency Detection
+
+Asgard validates the full dependency graph using [Dagwood](https://rubygems.org/gems/dagwood) before any task runs. A circular dependency produces a clean error and exits:
+
+```ruby
+class Tasks
+  depends_on :b
+  desc "a", "Task A"; def a = puts "a"
+
+  depends_on :a
+  desc "b", "Task B"; def b = puts "b"
+end
+```
+
+```bash
+asgard a
+# asgard: circular dependency — TSort::Cyclic: ...
+```
+
+No backtrace is shown — just a single diagnostic line.
+
+---
+
+## depends_on Across Multiple Files
+
+`depends_on` works across `.loki` files because all files reopen the same `class Tasks`. The dependency is recorded when the `def` is encountered, so load order matters:
+
+```ruby
+# build.loki
+class Tasks
+  desc "build", "Compile"
+  def build = sh "rake build"
+end
+
+# test.loki
+class Tasks
+  depends_on :build           # build.loki must be loaded first
+  desc "test", "Test"
+  def test = sh "rake test"
+end
+```
+
+When `--auto-load` is used, `*.loki` files are loaded alphabetically, so `build.loki` loads before `test.loki`. If you need to control load order, use explicit `require_relative` from `.loki`.
+
+---
+
+## depends_on Inside Subcommands
+
+`depends_on` works within subcommand classes exactly as it does at the top level. Dependency scope is per-class:
+
+```ruby
+class DBCommands < Tasks
+  desc "migrate", "Run 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
+```
+
+See [Subcommands](subcommands.md) for the full guide.

data/docs/environment.md

@@ -0,0 +1,113 @@
+# 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 "check", "Print the app name from .env"
+  def check = sh "echo $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 also available to lambda variables declared with `var` that reference `ENV`.
+3. They are available during `depends_on` dependency resolution.
+
+```ruby
+class Tasks
+  dotenv
+
+  var :database_url, -> { ENV.fetch("DATABASE_URL") }
+
+  desc "migrate", "Run migrations"
+  def migrate = sh "DATABASE_URL=#{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. `var`
+
+Use `dotenv` to bring external configuration into `ENV`, and `var` to define task-internal computed values:
+
+```ruby
+class Tasks
+  dotenv
+
+  # Read from ENV (set by dotenv or the shell)
+  var :app_name, -> { ENV.fetch("APP_NAME", "myapp") }
+  var :port,     -> { ENV.fetch("PORT", "3000").to_i }
+
+  desc "start", "Start the server"
+  def start = sh "puma -p #{port}"
+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:
+
+- `var` with a static value and a lazy lambda
+- `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.loki`
+
+**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.loki`
+
+**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,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