asgard 0.1.0 → 0.1.2

data/README.md

@@ -1,9 +1,11 @@
 # Asgard
 
-A [just](https://just.systems)-like task runner for Ruby. Define project recipes in a `.loki` file and run them with the `asgard` command. Built on [Thor](https://github.com/rails/thor) for argument handling and [SimpleFlow](https://github.com/madbomber/simple_flow) for dependency ordering.
+A Ruby task runner built on [Thor](https://github.com/rails/thor) for argument handling and [Dagwood](https://github.com/rewindio/dagwood) for dependency ordering.
 
 The name comes from Norse mythology: **Thor** is the CLI framework, **Asgard** is the realm where tasks live, and the task file is named **loki** — because Loki holds all the tricks.
 
+> **Asgard is a wrapper around [Thor](https://github.com/rails/thor).** Anything Thor can do — subcommands, typed options, argument validation, shell completion — is available inside a `.loki` file. Familiarity with Thor's DSL will make you immediately productive with Asgard.
+
 ## Installation
 
 ```bash
@@ -16,241 +18,518 @@ Or add to your Gemfile:
 bundle add asgard
 ```
 
-## Quick Start
+---
+
+## Tasks
+
+Every `.loki` file defines tasks as methods inside `class Tasks`. The `Tasks` class is pre-defined by the gem — just reopen it and add methods.
 
-Create a `.loki` file at your project root. `sh` runs any shell command — a single line or a multiline heredoc:
+### A task with no parameters
 
 ```ruby
-# filename: .loki
+class Tasks
+  desc "hello", "Say hello"
+  def hello = sh 'echo "Hello, World!"'
+end
+```
 
-class Tasks < Asgard::Base
-  desc "deps", "Install project dependencies"
-  def deps
-    sh <<~SHELL
-      brew install redis
-      npm install
-      bundle install
-    SHELL
-  end
+```bash
+asgard hello
+```
 
-  depends_on :deps
-  desc "test", "Run the test suite"
-  def test
-    sh "bundle exec rake test"
-  end
+### A task with a positional parameter
 
-  depends_on :test
-  desc "release", "Tag and publish the gem"
-  def release
-    sh <<~SHELL
-      git tag v$(ruby -r./lib/my_gem/version -e 'puts MyGem::VERSION')
-      git push --tags
-      bundle exec rake release
-    SHELL
-  end
+Declare positional parameters directly in the method signature. Document them in the `desc` usage string:
+
+```ruby
+class Tasks
+  desc "hello NAME", "Say hello to NAME"
+  def hello(name = "World") = sh "echo 'Hello, #{name}!'"
+end
+```
+
+```bash
+asgard hello
+asgard hello Alice
+```
+
+### A task with a formal argument declaration
+
+Use `argument` for richer metadata — type checking, enums, and help text:
+
+```ruby
+class Tasks
+  argument :name,
+           type:    :string,
+           default: "World",
+           desc:    "Name to greet"
+
+  desc "hello NAME", "Say hello to NAME"
+  def hello = sh "echo 'Hello, #{name}!'"
 end
 ```
 
-Then run tasks from any directory in the project tree:
+### A task with named options
+
+Use `method_option` (alias: `option`) for named flags. Access them inside the method via `options[:name]`:
+
+```ruby
+class Tasks
+  desc "hello NAME", "Say hello to NAME"
+  method_option :shout,  aliases: "-s", type: :boolean, desc: "Uppercase the output"
+  method_option :count,  aliases: "-n", type: :numeric, default: 1, desc: "Repeat N times"
+  def hello(name = "World")
+    message = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
+    options[:count].times { sh "echo '#{message}'" }
+  end
+end
+```
 
 ```bash
-asgard test       # runs deps, then test
-asgard release    # runs deps, then test, then release
-asgard help       # list all available tasks
+asgard hello Alice --shout --count 3
 ```
 
-## Task Files
+### A task with an extended description
+
+`long_desc` provides detailed help shown by `asgard help <task>`:
+
+```ruby
+class Tasks
+  long_desc <<~DESC
+    Says hello to NAME.
+    Repeats the greeting COUNT times.
+    Use --shout to uppercase the output.
+  DESC
+  desc "hello NAME", "Say hello to NAME"
+  method_option :shout, aliases: "-s", type: :boolean, desc: "Uppercase the output"
+  method_option :count, aliases: "-n", type: :numeric, default: 1, desc: "Repeat N times"
+  def hello(name = "World")
+    message = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
+    options[:count].times { sh "echo '#{message}'" }
+  end
+end
+```
+
+---
+
+## Dependencies
+
+`depends_on` declares what must run before a task. Each dependency runs at most once per `asgard` invocation regardless of how many tasks declare it. Circular dependencies are caught at startup.
 
-Asgard searches the current directory and its ancestors for task files, in this order:
+`desc` and `depends_on` are independent — either can come first, both must appear before `def`.
 
-1. **`.loki`** — the hidden default. Found alone, takes priority over everything.
-2. **`*.loki`** — all matching files loaded alphabetically when no `.loki` exists.
+### Sequential dependencies
 
-This means you can split a large task set across multiple files:
+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
 ```
-deploy.loki
-test.loki
-build.loki        # loaded as: build.loki, deploy.loki, test.loki
+
+```bash
+asgard release   # build → test → release
 ```
 
-Or use a single hidden default:
+### 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"
 
+  # lint and typecheck run in parallel, test waits for both
+  depends_on [:lint, :typecheck]
+  desc "test", "Run the test suite"
+  def test = sh "bundle exec rake test"
+end
 ```
-.loki             # takes priority, *.loki files are ignored
+
+```bash
+asgard test   # lint ∥ typecheck → test
 ```
 
-## Features
+### Mixed sequential and parallel
 
-### Task dependencies
+Mix bare symbols (sequential) and arrays (parallel) in a single `depends_on` call. Execution proceeds stage by stage — each stage must complete before the next begins:
 
 ```ruby
-depends_on :build
-desc "test", "Run tests"
-def test
-  sh "bundle exec rake test"
+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
 ```
 
-Dependencies run before the recipe, at most once per invocation regardless of how many recipes declare them. Circular dependencies are caught at startup via `SimpleFlow::DependencyGraph`.
+```
+asgard ci executes:
+
+  setup
+    ↓
+  lint ∥ build    (concurrent)
+    ↓
+  test
+    ↓
+  notify
+    ↓
+  ci
+```
+
+---
+
+## Variables
 
-### Variables
+`var` declares a named value available to all tasks as a method. Pass a lambda for lazy evaluation — it is called once on first use:
 
 ```ruby
-var :app,     "myapp"
-var :version, -> { `git describe --tags`.strip }   # lazy, evaluated on first use
+class Tasks
+  var :app,     "myapp"
+  var :version, -> { `git describe --tags`.strip }
 
-desc "tag", "Create a git tag"
-def tag
-  sh "git tag #{version}"
+  desc "tag", "Create a release tag"
+  def tag = sh "git tag #{app}-#{version}"
 end
 ```
 
-### Multi-line shell scripts
+---
+
+## Helper methods
+
+Private methods are callable from any task in the same class but are never registered as commands — they won't appear in `--help` output and can't be invoked from the CLI.
 
 ```ruby
-desc "setup", "Bootstrap the dev environment"
-def setup
-  sh <<~SHELL
-    brew install redis postgresql
-    brew services start redis
-    bundle install
-    rails db:setup
-  SHELL
+class Tasks
+  desc "build", "Compile and package"
+  def build
+    compile("src")
+    package(version)
+  end
+
+  desc "release", "Build and publish"
+  def release
+    build
+    sh "gem push pkg/myapp-#{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
 end
 ```
 
-### Embedded scripts in other languages
+Helpers can also be shared across multiple `.loki` files by extracting them into a plain Ruby file and loading it explicitly:
 
 ```ruby
-desc "analyze", "Run data analysis"
-def analyze
-  shebang :python3, <<~PYTHON
-    import json
-    data = json.load(open("results.json"))
-    print(f"Total: {sum(data.values())}")
-  PYTHON
+# shared/helpers.rb
+module BuildHelpers
+  private
+
+  def compile(dir)
+    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
+  end
 end
 
-desc "bundle", "Build frontend assets"
-def bundle_assets
-  shebang :node, <<~JS
-    const esbuild = require("esbuild")
-    esbuild.buildSync({ entryPoints: ["src/app.js"], bundle: true, outfile: "dist/app.js" })
-  JS
+# .loki
+require_relative "shared/helpers"
+
+class Tasks
+  include BuildHelpers
+
+  desc "build", "Compile the project"
+  def build = compile("src")
 end
 ```
 
-Supported interpreters: `:python3`, `:python`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`. Any other symbol is passed directly to `system` with a `.tmp` extension.
+---
 
-### Importing task modules
+## Options shared across all tasks
 
-Split tasks into reusable modules and include them flat (all tasks in the same namespace):
+`class_option` defines an option available to every task in the class:
 
 ```ruby
-# shared/deploy_tasks.rb
-module DeployTasks
-  def self.included(base)
-    base.desc "deploy", "Deploy to production"
-    base.define_method(:deploy) { sh "cap production deploy" }
+class Tasks
+  class_option :dry_run, aliases: "-n", type: :boolean, desc: "Print commands without running"
+
+  desc "deploy ENV", "Deploy to the given environment"
+  def deploy(env = "staging")
+    if options[:dry_run]
+      puts "Would deploy to #{env}"
+    else
+      sh "cap #{env} deploy"
+    end
   end
 end
+```
 
-# .loki
-require_relative "shared/deploy_tasks"
+---
+
+## Shell helpers
 
-class Tasks < Asgard::Base
-  import DeployTasks
+`sh` runs any shell command or multiline heredoc. `shebang` writes a script body to a tempfile and executes it with the given interpreter. Both exit with the command's status code on failure.
+
+```ruby
+class Tasks
+  desc "setup", "Bootstrap the development environment"
+  def setup
+    sh <<~SHELL
+      brew install redis postgresql
+      brew services start redis
+      bundle install
+      rails db:setup
+    SHELL
+  end
+
+  desc "analyze", "Run Python data analysis"
+  def analyze
+    shebang :python3, <<~PYTHON
+      import json
+      data = json.load(open("results.json"))
+      print(f"Total: {sum(data.values())}")
+    PYTHON
+  end
+
+  desc "bundle_assets", "Build frontend assets with esbuild"
+  def bundle_assets
+    shebang :node, <<~JS
+      const esbuild = require("esbuild")
+      esbuild.buildSync({ entryPoints: ["src/app.js"], bundle: true, outfile: "dist/app.js" })
+    JS
+  end
 end
 ```
 
-For namespaced subcommands, use Thor's `register`:
+Supported interpreters: `:python3`, `:python`, `:node`, `:ruby`, `:perl`, `:bash`, `:sh`. Any other symbol is passed directly to `system` with a `.tmp` extension.
+
+Pass `silent: true` to suppress the command echo:
 
 ```ruby
-register DeployTasks, "deploy", "deploy COMMAND", "Deployment tasks"
-# invoked as: asgard deploy production
+def build = sh "rake build", silent: true
 ```
 
-### Dotenv
+---
+
+## Environment variables
+
+`dotenv` loads a `.env` file into the environment before tasks run:
 
 ```ruby
-class Tasks < Asgard::Base
-  dotenv          # loads .env from CWD
-  dotenv ".env.local"
+class Tasks
+  dotenv              # loads .env
+  dotenv ".env.local" # or a specific file
 
-  desc "check", "Print the app name"
-  def check
-    sh "echo $APP_NAME"
-  end
+  desc "check", "Print the app name from .env"
+  def check = sh "echo $APP_NAME"
 end
 ```
 
-### Echo suppression
+---
+
+## Command aliases
 
-Pass `silent: true` to suppress the command echo (equivalent to `just`'s `@` prefix):
+`map` creates alternative names for a task:
 
 ```ruby
-def build
-  sh "bundle exec rake build", silent: true   # runs quietly, output still shown
+class Tasks
+  map "-v"  => "version"
+  map "--v" => "version"
+  map "t"   => "test"
+
+  desc "version", "Print the version"
+  def version = puts Asgard::VERSION
 end
 ```
 
-## Shell helpers
+---
 
-| Method | Description |
-|---|---|
-| `sh(script, silent: false)` | Run a shell command or multiline script |
-| `shebang(interpreter, script, silent: false)` | Write script to a tempfile and execute it |
+## Subcommands
 
-Both exit with the command's status code on failure.
+Group related tasks under a common name using Thor's `subcommand` method. Define a subcommand class that inherits from `Tasks`, then register it with a name and description.
 
-## Full example `.loki`
+```ruby
+class DeployCommands < Tasks
+  desc "staging", "Deploy to staging"
+  def staging = sh "cap staging deploy"
+
+  desc "production", "Deploy to production"
+  def production = sh "cap production deploy"
+end
+
+class Tasks
+  desc "deploy SUBCOMMAND", "Deploy the application"
+  subcommand "deploy", DeployCommands
+end
+```
+
+```bash
+asgard deploy           # shows deploy subcommand help
+asgard deploy staging
+asgard deploy production
+```
+
+Subcommand tasks have all the same access to helper methods like `sh`, `shebang`, `depends_on`, `var`, and the built-in `--debug`/`--verbose` class options as normal tasks.
+
+`depends_on` only works within a subcommand group exactly as it does at the top level:
 
 ```ruby
-require "asgard"
+class DBCommands < Tasks
+  desc "migrate", "Run pending migrations"
+  def migrate = sh "rails db:migrate"
 
-class Tasks < Asgard::Base
-  dotenv
+  desc "seed", "Load seed data"
+  def seed = sh "rails db:seed"
 
-  var :app,     "myapp"
-  var :version, -> { File.read("VERSION").strip }
+  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
+```
+
+Each subcommand group can have its own `desc`, `long_desc`, `option`, `class_option`, and `map` declarations, all scoped to that group.
+
+See [`examples/server_subcommands.loki`](examples/server_subcommands.loki) and [`examples/db_subcommands.loki`](examples/db_subcommands.loki) for full working examples.
+
+---
+
+## `method_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"}` |
+
+Common `method_option` keys: `aliases`, `type`, `default`, `required`, `desc`, `enum`, `banner`.
+
+---
+
+## Task files
+
+Asgard searches the current directory and its ancestors for a `.loki` file. That file marks the project root. All `*.loki` files in the same directory are auto-loaded alphabetically before `.loki` is loaded.
+
+### Single file
+
+```
+myproject/
+  .loki
+```
+
+### Multiple files
+
+Split tasks across files — each reopens `class Tasks`:
+
+```
+myproject/
+  .loki          ← entry point, can be empty
+  build.loki
+  deploy.loki
+  test.loki
+```
+
+```ruby
+# build.loki
+class Tasks
+  desc "build", "Compile the project"
+  def build = sh "rake build"
+end
+```
+
+```ruby
+# test.loki
+class Tasks
+  depends_on :build
   desc "test", "Run the test suite"
-  def test
-    sh "bundle exec rake test"
-  end
+  def test = sh "bundle exec rake test"
+end
+```
 
+```ruby
+# deploy.loki
+class Tasks
   depends_on :test
-  desc "quality", "Run tests then check complexity"
-  def quality
-    sh "flog lib/"
-  end
+  desc "deploy", "Deploy to production"
+  def deploy = sh "cap production deploy"
+end
+```
 
-  desc "build", "Build the gem"
-  def build
-    sh "bundle exec rake build"
-  end
+The `.loki` entry point can be completely empty — it only needs to exist to mark the project root.
 
-  depends_on :quality, :build
-  desc "release", "Release #{version} to RubyGems"
-  def release
-    sh "bundle exec rake release"
-  end
+### Explicit loading
+
+Load any Ruby or `.loki` file manually from `.loki`:
+
+```ruby
+# .loki
+require_relative "shared/helpers"
+require_relative "ci.loki"
+
+class Tasks
+  # additional tasks
 end
 ```
 
+---
+
+## `Asgard` module API
+
+| Method | Description |
+|---|---|
+| `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
+| `Asgard.find_task_file` | Returns path to `.loki` searching from CWD upward, or nil |
+| `Asgard.load_loki(dir)` | Loads all `*.loki` files in dir alphabetically |
+
+`run!` handles its own errors — a missing `.loki` or a circular dependency both produce a clean one-line message and exit 1.
+
+---
+
 ## Development
 
 ```bash
 git clone git@github.com:MadBomber/asgard.git
 cd asgard
 bundle install
-bundle exec rake test       # run tests with coverage
-bundle exec bin/asgard help # try the CLI against this gem's own .loki file
+bundle exec rake test       # run tests (95% coverage minimum enforced)
+bundle exec bin/asgard help # exercise the CLI against this gem's own .loki
 ```
 
-Coverage threshold is enforced at 95% via SimpleCov.
-
 ## Contributing
 
 Bug reports and pull requests are welcome at https://github.com/MadBomber/asgard.

data/bin/asgard

@@ -2,23 +2,4 @@
 # frozen_string_literal: true
 
 require "asgard"
-
-task_files = Asgard.find_task_files
-
-unless task_files
-  warn "asgard: no .loki or *.loki task file found in #{Dir.pwd} or any parent directory"
-  exit 1
-end
-
-task_files.each { |f| load f }
-
-klass = Asgard::Base.subclasses.last
-
-unless klass
-  warn "asgard: no class inheriting Asgard::Base found in #{task_files.join(', ')}"
-  exit 1
-end
-
-klass.validate_deps!
-klass._reset_ran!
-klass.start(ARGV)
+Asgard.run!(ARGV)