asgard 0.5.1 → 0.6.0

data/docs/dependencies.md

@@ -1,313 +0,0 @@
-# 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 "Compile the project"
-  def build = sh "rake build"
-
-  depends_on :build
-  desc "Run the test suite"
-  def test = sh "rake test"
-
-  depends_on :test
-  desc "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 "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 "Check code style"
-  def lint = sh "bundle exec rubocop"
-
-  desc "Run type checks"
-  def typecheck = sh "bundle exec srb tc"
-
-  depends_on [:lint, :typecheck]
-  desc "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 "Install dependencies"; def setup  = sh "bundle install"
-  desc "Check code style";     def lint   = sh "bundle exec rubocop"
-  desc "Compile assets";       def build  = sh "rake assets:precompile"
-  desc "Run tests";            def test   = sh "bundle exec rake test"
-  desc "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 "Full CI pipeline"
-  def ci = puts "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 "Install gems"
-  def setup = sh "bundle install"
-
-  depends_on :setup
-  desc "Run tests"
-  def test = sh "rake test"
-
-  depends_on :setup
-  desc "Check style"
-  def lint = sh "rubocop"
-
-  depends_on [:test, :lint]
-  desc "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.
-
----
-
-## Transitive Dependencies
-
-When a dependency has its own dependencies, Asgard resolves them recursively before running the dependent task. The deduplication set ensures each task runs at most once regardless of how many paths lead to it.
-
-Consider this graph:
-
-```ruby
-class Tasks
-  desc "Fetch gems"
-  def setup = sh "bundle install"
-
-  depends_on :setup
-  desc "Compile assets"
-  def build = sh "rake assets:precompile"
-
-  desc "Check code style"
-  def lint = sh "bundle exec rubocop"
-
-  depends_on :build, :lint, :setup
-  desc "Run the full pipeline"
-  def ci = puts "Done."
-end
-```
-
-`ci` declares three sequential dependencies: `build`, `lint`, `setup`. But `build` itself depends on `setup`. The effective execution order is:
-
-```
-setup          ← run as build's prerequisite
-  ↓
-build
-  ↓
-lint
-  ↓
-(setup skipped — already done)
-  ↓
-ci
-```
-
-`setup` runs once — on its first encounter as `build`'s prerequisite. When `ci`'s own stage for `setup` is reached, the deduplication set skips it.
-
-!!! tip
-    When a task is both a transitive dependency and a direct dependency, declare it only where it logically belongs — as a prerequisite of the task that needs it. Declaring it redundantly at the top level is harmless (deduplication handles it) but adds noise.
-
----
-
-## Circular Dependency Detection
-
-Asgard validates the full dependency graph using stdlib [TSort](https://docs.ruby-lang.org/en/master/TSort.html) before any task runs. A circular dependency produces a clean error and exits:
-
-```ruby
-class Tasks
-  depends_on :b
-  desc "Task A"; def a = puts "a"
-
-  depends_on :a
-  desc "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 "Compile"
-  def build = sh "rake build"
-end
-
-# test.loki
-class Tasks
-  depends_on :build           # build.loki must be loaded first
-  desc "Test"
-  def test = sh "rake test"
-end
-```
-
-Because `*.loki` files are loaded alphabetically when `import "*.loki"` is used, `build.loki` loads before `test.loki`. If you need to control load order precisely, use explicit `import` calls with full filenames rather than a glob.
-
----
-
-## Dynamic Dependencies (Proc / Block Form)
-
-`depends_on` normally takes a fixed list, recorded the moment the `def` right after it is encountered — which is why load order matters, as above. Pass a `Proc` or lambda instead — or, equivalently, a block — and that list is computed *later*, after every `.loki` file has finished loading, rather than at the point `depends_on` itself is evaluated:
-
-```ruby
-depends_on -> { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
-desc "Run every *_check quality gate task in parallel"
-def quality
-  # ...
-end
-
-depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
-desc "Same thing, written as a block"
-def quality2
-  # ...
-end
-```
-
-This solves exactly the "load order matters" problem from the previous section: a plain array can only name tasks that already exist in `.loki` files loaded *before* this one. A Proc/block is resolved once every file has loaded, so it can safely reference a task defined in a file that hasn't been imported yet at the point `depends_on` is written — including one that only exists conditionally, e.g. a Rails-specific task file imported with `import "quality_rails.loki" if defined?(Rails)`. `depends_on` accepts task arguments *or* a block, never both — combining them raises `Asgard::Error`.
-
-**Shape:** the Proc/block must return exactly what the plain-array form would receive as its splat arguments — an array of stages, each a `Symbol`/`String` (sequential) or an `Array` of `Symbol`/`String` (parallel group), nested no deeper than that. The example above returns `[[:a_check, :b_check, :c_check]]`: one stage, containing every matching task, all running in parallel — the same shape as `depends_on [:a_check, :b_check, :c_check]`. This shape is validated once the result comes back — a bad return value (wrong type, a stage that isn't a Symbol/String/Array, a leaf inside a parallel group that isn't a Symbol/String, or nesting more than one level deep) raises `Asgard::Error` naming the task and the offending value, instead of failing later with an opaque `NoMethodError`:
-
-```bash
-asgard quality
-# asgard: depends_on proc/block for 'quality' returned invalid stage 123 (Integer); expected a Symbol, String, or Array of them
-```
-
-**When it runs:** once, when `validate_deps!` runs (right after the `.loki` chain finishes loading, before any task dispatches). The resolved result replaces the Proc/block in the dependency table, so cycle detection, undefined-task checks, and arity checks all run against the *resolved* list — a Proc/block that references an undefined task, or that itself introduces a cycle, is caught at startup exactly like a plain array would be:
-
-```bash
-asgard quality
-# asgard: undefined task(s) in depends_on: ghost_check
-```
-
-**`self` inside the Proc/block:** since it's written directly in a `class Tasks` body, it lexically captures that class as `self` — so it can call `all_commands`, `_deps`, or any other class-level method bare, without a `self.class.` prefix, even though it's actually invoked later from inside `validate_deps!`.
-
-**If the Proc/block raises**, the error is caught and re-raised as `Asgard::Error` naming the task it was declared for:
-
-```
-asgard: depends_on proc for 'quality' raised RuntimeError: boom
-```
-
-!!! tip
-    Reach for this only when the dependency list genuinely can't be known until every file has loaded — like "every task whose name ends in `_check`," discovered across several `.loki` files. For a fixed, known-upfront list, the plain array form is simpler and reads just as clearly.
-
----
-
-## 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 "Run migrations"
-  def migrate = sh "rails db:migrate"
-
-  desc "Load seed data"
-  def seed = sh "rails db:seed"
-
-  depends_on :migrate, :seed
-  desc "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

@@ -1,129 +0,0 @@
-# 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

@@ -1,194 +0,0 @@
-# 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.
-
----
-
-## `do.loki`
-
-**Path:** `examples/do.loki`
-
-A plain user task that runs other tasks in sequence, the way `rake a b c` or `just a b c` does. No gem changes needed:
-
-- Steps are comma-separated, so each step can carry its own arguments and options; with no commas, every word is a task of its own
-- Each step is parsed by Thor as if it were typed on the command line
-- The sequence stops at the first failure (a failing `sh`, or a step returning `:fail`)
-
-```bash
-asgard do greet finish
-asgard do hello Alice, farewell Bob --formal
-# Hello, Alice!
-# Goodbye, Bob.
-```
-
-!!! note
-    Every task runs at most once per `asgard` invocation, so `asgard do hello Alice, hello Bob` greets only Alice. The same rule makes a dependency shared by several steps run once.
-
----
-
-## `confirm.loki`
-
-**Path:** `examples/confirm.loki`
-
-A guard task. List `confirm` first in a dangerous task's `depends_on`, and the task runs only after the user answers yes:
-
-```ruby
-depends_on :confirm
-desc "Drop and recreate the database"
-def reset_database = sh "bin/rails db:reset"
-```
-
-```bash
-asgard reset_database
-# Really run `asgard reset_database`? [y/N] n
-# asgard: aborted `asgard reset_database`      (exit 1)
-
-ASGARD_YES=1 asgard reset_database             # no question, for scripts and CI
-```
-
-- Answering no **raises** `Asgard::Error`, which stops the dependent task. Returning `:fail` would not: a dependency's return value never stops the task that depends on it
-- A dependency doesn't know which task asked for it, so the question shows the whole command line
-- With no terminal (a schedule, the watcher, a pipe) it refuses unless `ASGARD_YES` is set
-- `confirm` is declared with `hide: true`, so it stays out of `asgard help`
-
-!!! note
-    `confirm` runs at most once per `asgard` invocation, so `asgard do reset_database, drop_cache` asks once for the whole line. Keep it in its own first stage: in `depends_on [:confirm, :backup]`, `backup` runs while the question waits.
-
----
-
-## 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 |
-| `do.loki` | Running several tasks in sequence from one command line |
-| `confirm.loki` | A guard dependency that asks before a dangerous task runs |