asgard 0.1.1 → 0.2.0

data/docs/assets/css/custom.css

@@ -0,0 +1,93 @@
+/* ==========================================================================
+   Asgard documentation — custom styles
+   Material theme handles the heavy lifting; this file adds targeted polish.
+   ========================================================================== */
+
+/* --------------------------------------------------------------------------
+   .loki filename display
+   Used whenever the filename ".loki" or "*.loki" appears inline or in code.
+   -------------------------------------------------------------------------- */
+
+/* Give inline code that looks like a .loki filename a subtle Norse-gold tint */
+code:is([class*="language-"]) .token.string:has-text(".loki"),
+.md-typeset code.loki-file {
+  color: var(--md-accent-fg-color);
+  font-weight: 600;
+}
+
+/* Highlight .loki filenames in directory tree code blocks */
+.md-typeset .highlight .filename {
+  background-color: color-mix(in srgb, var(--md-primary-fg-color) 12%, transparent);
+  border-bottom: 2px solid var(--md-accent-fg-color);
+  border-radius: 4px 4px 0 0;
+  color: var(--md-default-fg-color);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  padding: 0.3rem 0.8rem;
+}
+
+/* --------------------------------------------------------------------------
+   Admonition tweaks — slightly warmer warning border for the "argument"
+   class-level scope warning that appears on the tasks page.
+   -------------------------------------------------------------------------- */
+
+.md-typeset .admonition.warning,
+.md-typeset details.warning {
+  border-left-color: #e6a817;
+}
+
+.md-typeset .admonition.warning > .admonition-title,
+.md-typeset details.warning > summary {
+  background-color: rgba(230, 168, 23, 0.12);
+}
+
+/* --------------------------------------------------------------------------
+   Table of Contents — emphasise the current section a touch more
+   -------------------------------------------------------------------------- */
+
+.md-nav__link--active {
+  font-weight: 600;
+}
+
+/* --------------------------------------------------------------------------
+   Home page feature table (HTML table in index.md)
+   -------------------------------------------------------------------------- */
+
+.md-typeset table:not([class]) td {
+  vertical-align: top;
+}
+
+/* --------------------------------------------------------------------------
+   Execution diagram in dependencies.md — keep it tight and readable
+   -------------------------------------------------------------------------- */
+
+.md-typeset pre code {
+  font-size: 0.85em;
+  line-height: 1.5;
+}
+
+/* --------------------------------------------------------------------------
+   Subtle Norse-shield watermark on the hero block (index page only).
+   Relies on the Material "primary: indigo" palette.
+   -------------------------------------------------------------------------- */
+
+.md-header {
+  box-shadow: 0 2px 8px rgba(63, 81, 181, 0.25);
+}
+
+/* --------------------------------------------------------------------------
+   Code annotations — keep them readable across both light and dark palettes
+   -------------------------------------------------------------------------- */
+
+.md-typeset .md-annotation__index > * {
+  font-size: 0.7rem;
+}
+
+/* --------------------------------------------------------------------------
+   Task-runner specific: distinguish shell prompt lines from output lines
+   in bash code blocks by dimming lines that don't start with '#' or 'asgard'
+   -------------------------------------------------------------------------- */
+
+/* (Future: add targeted styles once MkDocs Material supports per-line
+   highlighting via config; for now this is intentionally minimal.) */

data/docs/changelog.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to Asgard are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asgard adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+## [0.2.0] — 2026-05-29
+
+### Changed
+
+- `*.loki` files are no longer auto-loaded by default. Pass `--auto-load` to `asgard` to load all `*.loki` files from the project root alphabetically before `.loki`. This is a breaking change for projects using the multi-file layout.
+- Added `--auto-load` as a built-in CLI flag in `Tasks`, visible in `asgard help`
+
+---
+
+## [0.1.2] — 2026-05-29
+
+### Added
+
+- `--version` built-in CLI flag — prints `Asgard::VERSION` and exits; implemented as a `_`-prefixed method in `Tasks` per the gem-owned naming convention
+- `--debug` and `--verbose` built-in `class_option` declarations on `Tasks` — set `$DEBUG`/`$VERBOSE` before any task runs via the `invoke_command` hook in `Asgard::Base`
+- `debug?` and `verbose?` private predicate helpers on `Tasks` — thin wrappers around `$DEBUG` and `$VERBOSE` for use inside task bodies
+- `_` prefix convention for gem-owned methods in `Tasks` — built-in methods use `_` prefix to distinguish them from user-defined tasks
+- `run!` guards against direct invocation of `_`-prefixed commands with a clean error message and exit 1
+- `examples/` directory with working `.loki` files:
+  - `kitchen_sink.loki` — demonstrates the full Thor DSL (all option types, `long_desc`, `class_option`, `default_task`, `map`, `depends_on`, `var`, `no_commands`, `private`)
+  - `server_subcommands.loki` — subcommand group for server management
+  - `db_subcommands.loki` — subcommand group for database management with `depends_on` chaining
+  - `concurrent.loki` — demonstrates parallel task execution with interleaved thread output
+- README sections: Helper methods, Subcommands, Thor wrapper callout
+
+### Fixed
+
+- Replaced `warn`/`exit 1` with `abort` throughout `run!` — `Kernel#warn` is silenced when `$VERBOSE = nil`, which is the default in Ruby 4.0; `abort` writes to `$stderr` regardless
+
+### Changed
+
+- `--debug` and `--verbose` promoted from mapped tasks to `class_option` — they now work as modifiers alongside other commands (e.g. `asgard build --debug`) rather than as standalone commands
+- Removed all references to `just` task runner and `recipe` terminology; Asgard uses "task" throughout
+- `depends_on` parameter renamed from `*recipes` to `*tasks` for consistency
+
+---
+
+## [0.1.1] — 2026-05-28
+
+### Added
+
+- Parallel dependency execution — wrap deps in an array to run them concurrently:
+  `depends_on [:build, :lint]` or `depends_on :setup, [:build, :lint], :deploy`
+- `Asgard.run!(argv)` — single entry point encapsulating find, load, validate, and start
+- `Asgard.load_loki(dir)` — auto-loads all `*.loki` files in a directory alphabetically
+- `Tasks` class pre-defined by the gem (`class Tasks < Asgard::Base`) — task files reopen it without restating the superclass
+- `lib/asgard/tasks.rb` — ships the pre-defined `Tasks` class
+
+### Changed
+
+- Replaced `SimpleFlow` dependency with `Dagwood` — purpose-built DAG library with no extra dependencies and no Ruby 4 compatibility issues
+- `bin/asgard` simplified to two lines: `require "asgard"` + `Asgard.run!(ARGV)`
+- Task file convention: `.loki` is the project root marker and entry point; `*.loki` files each reopen `class Tasks` and are auto-loaded before `.loki`
+- `Asgard.find_task_files` renamed to `Asgard.find_task_file` (singular — only `.loki` is the entry point)
+- `depends_on` now accepts mixed sequential/parallel stages; bare symbols run sequentially, arrays within the splat run in parallel
+- `run!` handles its own errors — missing `.loki` and circular dependencies produce a clean one-line message and exit 1 rather than a backtrace
+- Thread-safe dep deduplication via class-level `_ran_tasks` Set + Mutex replaces Thor's `@_invocations`
+- Removed `import` macro — task files use Ruby class reopening instead of modules
+
+### Removed
+
+- `SimpleFlow` dependency (replaced by `Dagwood`)
+- `logger` gem workaround (was only needed for SimpleFlow on Ruby 4)
+- `*.loki` glob fallback in `find_task_file` — only `.loki` is the auto-discovered entry point
+
+---
+
+## [0.1.0] — 2026-05-28
+
+### Added
+
+- `Asgard::Base` — Thor subclass providing the task DSL
+- `depends_on` — declare task dependencies; dependencies run at most once per invocation
+- `var` — declare static or lazy-evaluated variables available to all tasks
+- `import` — flat-merge a task module into the current class
+- `dotenv` — load a `.env` file into the environment
+- `sh` — run a shell command or multiline heredoc script; exits with the command's status on failure
+- `shebang` — write a script body to a tempfile and execute it with a given interpreter (`:python3`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`, or any custom interpreter)
+- `Asgard.find_task_files` — search current directory and ancestors for task files
+- Task file resolution: `.loki` takes priority; falls back to all `*.loki` files sorted alphabetically
+- `asgard` executable — finds task files, validates dependency graph, dispatches via Thor
+- Circular dependency detection via `SimpleFlow::DependencyGraph` at startup
+- 100% test coverage enforced via SimpleCov (95% minimum threshold)
+- Quality task in `.loki` runs flog after tests
+
+[Unreleased]: https://github.com/MadBomber/asgard/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/MadBomber/asgard/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/MadBomber/asgard/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/MadBomber/asgard/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/MadBomber/asgard/releases/tag/v0.1.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 |