asgard 0.1.2 → 0.2.0

data/docs/tasks.md

@@ -0,0 +1,284 @@
+# Defining Tasks
+
+Every task is a public method inside `class Tasks`. Asgard pre-defines `Tasks` as a subclass of `Asgard::Base` (which is itself a Thor subclass), so your `.loki` files just reopen the class and add methods. The full Thor DSL is available everywhere.
+
+---
+
+## Basic Task
+
+A task with no parameters and no options:
+
+```ruby
+class Tasks
+  desc "hello", "Say hello"
+  def hello = sh 'echo "Hello, World!"'
+end
+```
+
+`desc` takes two arguments: the usage string and the one-line description shown in `asgard help`.
+
+```bash
+asgard hello
+```
+
+---
+
+## Positional Parameter with Default
+
+Positional parameters are declared directly in the method signature. Document them in the `desc` usage string (uppercase by convention):
+
+```ruby
+class Tasks
+  desc "greet NAME", "Greet NAME; omit NAME to greet the world"
+  def greet(name = "World")
+    sh "echo 'Hello, #{name}!'"
+  end
+end
+```
+
+```bash
+asgard greet           # Hello, World!
+asgard greet Alice     # Hello, Alice!
+```
+
+---
+
+## Named Options
+
+Use `method_option` (alias: `option`) for named flags. Access them inside the method via `options[:name]`.
+
+### All Five Option Types
+
+```ruby
+class Tasks
+  desc "compile", "Compile the project"
+  option :output,  aliases: "-o", type: :string,  default: "dist/",  desc: "Output directory"
+  option :verbose, aliases: "-v", type: :boolean, default: false,    desc: "Enable verbose output"
+  option :jobs,    aliases: "-j", type: :numeric, default: 1,        desc: "Number of parallel jobs"
+  option :tags,                   type: :array,                       desc: "Build tags to apply"
+  option :defines,                type: :hash,                        desc: "Preprocessor defines (KEY:VALUE)"
+  def compile
+    puts "Compiling → #{options[:output]} with #{options[:jobs]} job(s)"
+    puts "Tags: #{options[:tags].join(', ')}" if options[:tags]
+    puts "Defines: #{options[:defines]}"      if options[:defines]
+  end
+end
+```
+
+### Option Types Reference
+
+| Type | CLI Example | Ruby Value |
+|---|---|---|
+| `:string` | `--output dist/` | `"dist/"` |
+| `:boolean` | `--verbose` / `--no-verbose` | `true` / `false` |
+| `:numeric` | `--jobs 4` | `4` |
+| `:array` | `--tags foo bar baz` | `["foo", "bar", "baz"]` |
+| `:hash` | `--defines KEY:val FOO:bar` | `{"KEY"=>"val", "FOO"=>"bar"}` |
+
+### Common Option Keys
+
+| Key | Description |
+|---|---|
+| `aliases` | Short-form flag, e.g. `"-o"` |
+| `type` | `:string`, `:boolean`, `:numeric`, `:array`, or `:hash` |
+| `default` | Value used when the flag is omitted |
+| `required` | If `true`, Thor raises an error when the flag is missing |
+| `desc` | One-line description shown in help |
+| `enum` | Array of allowed values; Thor validates automatically |
+| `banner` | Placeholder shown in help for the value slot, e.g. `"SECONDS"` |
+
+---
+
+## Required Option
+
+```ruby
+class Tasks
+  desc "deploy ENV", "Deploy to ENV"
+  option :strategy,
+         type:     :string,
+         required: true,
+         enum:     %w[blue-green rolling canary],
+         desc:     "Deployment strategy"
+  def deploy(env = "staging")
+    sh "cap #{env} deploy --strategy #{options[:strategy]}"
+  end
+end
+```
+
+```bash
+asgard deploy          # Error: required option '--strategy' is missing
+asgard deploy --strategy rolling
+asgard deploy production --strategy blue-green
+```
+
+---
+
+## Enum Validation
+
+```ruby
+class Tasks
+  desc "build", "Build the project"
+  option :env,
+         type:    :string,
+         default: "development",
+         enum:    %w[development staging production],
+         desc:    "Target environment"
+  def build
+    sh "rake build ENV=#{options[:env]}"
+  end
+end
+```
+
+Thor validates the value against the enum and shows a helpful error if it doesn't match.
+
+---
+
+## Banner
+
+`banner` replaces the default `VALUE` placeholder in help output with a more descriptive name:
+
+```ruby
+class Tasks
+  desc "wait", "Wait for a service to become available"
+  option :timeout, type: :numeric, default: 30, banner: "SECONDS", desc: "Give up after SECONDS"
+  def wait
+    sh "wait-for-it --timeout #{options[:timeout]}"
+  end
+end
+```
+
+Help output shows: `[--timeout=SECONDS]` instead of `[--timeout=VALUE]`.
+
+---
+
+## Extended Description
+
+`long_desc` provides detailed help shown by `asgard help <task>`. Use `\x5` at the start of a line to force a line break within the wrapped text (a Thor convention):
+
+```ruby
+class Tasks
+  long_desc <<~DESC
+    Generates a project report covering test coverage, lint results,
+    and a dependency audit.
+
+    Pass --format to control output style. Use --since to scope the
+    report to changes after a given date.
+
+    Examples:\x5
+      asgard report --format html --since 2024-01-01\x5
+      asgard report --format json --output report.json\x5
+      asgard report --format text
+  DESC
+  desc "report", "Generate a project report"
+  option :format, type: :string, default: "text", enum: %w[text html json], desc: "Output format"
+  option :since,  type: :string, banner: "DATE",                            desc: "Limit to changes after DATE"
+  def report
+    sh "generate-report --format #{options[:format]}"
+  end
+end
+```
+
+!!! tip
+    `desc` and `depends_on` are independent of each other — either can come first, but both must appear before the `def`.
+
+---
+
+## Default Task
+
+`default_task` declares which command runs when `asgard` is invoked with no arguments:
+
+```ruby
+class Tasks
+  default_task :greet
+
+  desc "greet", "Say hello (runs by default)"
+  def greet
+    puts "Hello from Asgard!"
+  end
+end
+```
+
+```bash
+asgard        # same as: asgard greet
+```
+
+---
+
+## Command Aliases
+
+`map` creates short aliases for existing tasks:
+
+```ruby
+class Tasks
+  map "-v"  => "version"
+  map "--v" => "version"
+  map "t"   => "test"
+  map "b"   => "build"
+
+  desc "version", "Print the version"
+  def version = puts Asgard::VERSION
+
+  desc "test", "Run tests"
+  def test = sh "bundle exec rake test"
+
+  desc "build", "Build the gem"
+  def build = sh "bundle exec rake build"
+end
+```
+
+```bash
+asgard t      # same as: asgard test
+asgard b      # same as: asgard build
+asgard -v     # same as: asgard version (note: --version is the built-in flag)
+```
+
+---
+
+## Formal Argument Declaration
+
+`argument` provides rich positional-parameter metadata including type checking, enums, and help text.
+
+!!! warning "Class-level scope"
+    `argument` is a **class-level declaration** that applies to **every task in the class**, not just the one that follows it. It is best suited for single-command CLIs or when every task in the file genuinely shares the same positional input. In multi-task files, prefer method signature parameters instead.
+
+```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
+```
+
+For most multi-task `.loki` files, the simpler positional default pattern is safer:
+
+```ruby
+def hello(name = "World") = sh "echo 'Hello, #{name}!'"
+```
+
+---
+
+## No Commands Block
+
+`no_commands` marks a block of methods as public helpers that are excluded from the CLI and `--help` output. They are callable from any task in the same class:
+
+```ruby
+class Tasks
+  desc "build", "Compile the project"
+  def build
+    puts "Revision: #{current_sha}"
+    sh "rake build"
+  end
+
+  no_commands do
+    def current_sha
+      `git rev-parse --short HEAD`.strip
+    end
+  end
+end
+```
+
+See [Helper Methods](helpers.md) for the full guide on helpers, `private`, and cross-file sharing.

data/docs/variables.md

@@ -0,0 +1,122 @@
+# Variables
+
+`var` declares a named value that is available to all tasks in the class as a method call. Values can be static or lazily evaluated.
+
+---
+
+## Static Value
+
+Pass the value directly as the second argument:
+
+```ruby
+class Tasks
+  var :app,  "myapp"
+  var :env,  "production"
+  var :port, 3000
+
+  desc "info", "Print app info"
+  def info
+    puts "#{app} running on port #{port} in #{env}"
+  end
+end
+```
+
+---
+
+## Lazy Lambda
+
+Pass a lambda (or proc) to defer evaluation until the variable is first accessed. The lambda is called once and its return value is used for all subsequent accesses:
+
+```ruby
+class Tasks
+  var :version, -> { `git describe --tags`.strip }
+  var :sha,     -> { `git rev-parse --short HEAD`.strip }
+
+  desc "tag", "Create a release tag"
+  def tag = sh "git tag v#{version}"
+
+  desc "info", "Show version info"
+  def info = puts "#{version} (#{sha})"
+end
+```
+
+!!! tip
+    Lazy lambdas are ideal for values that require a shell call or file read — they only pay the cost if the variable is actually used in the task being run.
+
+---
+
+## Block Syntax
+
+You can also use a block instead of a lambda:
+
+```ruby
+class Tasks
+  var(:build_dir) { "builds/#{app}" }
+  var(:app)       { "myapp" }
+
+  desc "build", "Compile into build_dir"
+  def build = sh "rake build OUTDIR=#{build_dir}"
+end
+```
+
+!!! note
+    The block form and the lambda form behave identically — both are stored as callables and invoked on first access.
+
+---
+
+## Accessing Variables from Tasks
+
+Variables are available as method calls from within any task body (or other method) in the same class. They are defined using `no_commands`, so they appear neither in `--help` output nor as CLI commands:
+
+```ruby
+class Tasks
+  var :app,     "myapp"
+  var :version, -> { `git describe --tags`.strip }
+  var :pkg,     -> { "pkg/#{app}-#{version}.gem" }
+
+  desc "build", "Build the gem"
+  def build = sh "gem build #{app}.gemspec"
+
+  desc "push", "Push the gem to RubyGems"
+  def push = sh "gem push #{pkg}"
+end
+```
+
+Variables can reference other variables in their lambdas as long as the referenced variable is also defined with `var` on the same class.
+
+---
+
+## Sharing Variables Across Files
+
+Because all `.loki` files reopen the same `class Tasks`, variables declared in one file are available in all other files loaded in the same session:
+
+```ruby
+# config.loki
+class Tasks
+  var :app,  "myapp"
+  var :port, 8080
+end
+
+# deploy.loki
+class Tasks
+  desc "deploy", "Deploy the app"
+  def deploy = sh "cap deploy APP=#{app} PORT=#{port}"
+end
+```
+
+---
+
+## Naming Caution
+
+!!! warning
+    Do not use `var` names that conflict with built-in Ruby method names, Thor DSL method names, or Asgard's own built-in methods. In particular, avoid naming a variable `version` — `Tasks` already defines `_version` (the `--version` flag handler), and a `var :version` would collide with that namespace and produce confusing behavior. Use a more specific name like `app_version` or `gem_version` instead.
+
+```ruby
+# Avoid this — conflicts with the built-in version infrastructure:
+# var :version, -> { "1.0.0" }
+
+# Use this instead:
+var :app_version, -> { `git describe --tags`.strip }
+```
+
+Other names to avoid: `options`, `class_options`, `shell`, `invoke`, `invoke_command`.

data/examples/concurrent.loki

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# Demonstrates concurrent task execution via parallel depends_on groups.
+#
+# Each worker prints its letter repeatedly with random delays. Because
+# worker_a, worker_b, and worker_c run in separate threads their output
+# interleaves on stdout, proving real concurrency.
+#
+# Execution order:
+#   start → worker_a + worker_b + worker_c (all three concurrent) → finish
+#
+# Run with:
+#   asgard finish
+#
+# Sample output (character order varies every run):
+#   start
+#   ABCBACBACBABCBACBACB
+#   end
+
+$stdout.sync = true   # flush every print immediately across all threads
+
+CONCURRENT_REPS = 10  # how many times each worker prints its character
+
+class Tasks
+  desc "start", "Print start marker"
+  def start
+    puts "starting demo of concurrent task execution ..."
+  end
+
+  desc "worker_a", "Print 'A' repeatedly with random delays"
+  def worker_a
+    CONCURRENT_REPS.times do
+      print "A"
+      sleep rand(0.05..0.3)
+    end
+  end
+
+  desc "worker_b", "Print 'B' repeatedly with random delays"
+  def worker_b
+    CONCURRENT_REPS.times do
+      print "B"
+      sleep rand(0.05..0.3)
+    end
+  end
+
+  desc "worker_c", "Print 'C' repeatedly with random delays"
+  def worker_c
+    CONCURRENT_REPS.times do
+      print "C"
+      sleep rand(0.05..0.3)
+    end
+  end
+
+  depends_on :start, [:worker_a, :worker_b, :worker_c]
+  desc "finish", "Print end marker after all workers complete"
+  def finish
+    puts "\nfini - the end of concurrent task demo"
+  end
+end

data/lib/asgard/base.rb

@@ -19,8 +19,10 @@ module Asgard
         subclass.instance_variable_set(:@_deps,         {})
         subclass.instance_variable_set(:@_vars,         {})
         subclass.instance_variable_set(:@_pending_deps, [])
-        subclass.instance_variable_set(:@_ran_tasks,    Set.new)
-        subclass.instance_variable_set(:@_ran_mutex,    Mutex.new)
+        subclass.instance_variable_set(:@_running,    Set.new)
+        subclass.instance_variable_set(:@_done,       Set.new)
+        subclass.instance_variable_set(:@_cond,       Hash.new { |h, k| h[k] = ConditionVariable.new })
+        subclass.instance_variable_set(:@_ran_mutex,  Mutex.new)
       end
 
       def _deps
@@ -31,8 +33,16 @@ module Asgard
         @_vars ||= {}
       end
 
-      def _ran_tasks
-        @_ran_tasks ||= Set.new
+      def _running
+        @_running ||= Set.new
+      end
+
+      def _done
+        @_done ||= Set.new
+      end
+
+      def _cond
+        @_cond ||= Hash.new { |h, k| h[k] = ConditionVariable.new }
       end
 
       def _ran_mutex
@@ -41,7 +51,11 @@ module Asgard
 
       # Reset execution tracking for a fresh asgard invocation.
       def _reset_ran!
-        _ran_mutex.synchronize { @_ran_tasks = Set.new }
+        _ran_mutex.synchronize do
+          @_running = Set.new
+          @_done    = Set.new
+          @_cond    = Hash.new { |h, k| h[k] = ConditionVariable.new }
+        end
       end
 
       # Translate stages into a DependencyGraph-compatible hash.
@@ -73,8 +87,12 @@ module Asgard
         _vars[name.to_sym] = value
         no_commands do
           define_method(name) do
-            v = self.class._vars[name.to_sym]
-            v.respond_to?(:call) ? v.call : v
+            ivar = :"@__var_#{name}"
+            unless instance_variable_defined?(ivar)
+              v = self.class._vars[name.to_sym]
+              instance_variable_set(ivar, v.respond_to?(:call) ? v.call : v)
+            end
+            instance_variable_get(ivar)
           end
         end
       end
@@ -90,19 +108,44 @@ module Asgard
 
       # Validate the full dep graph for cycles using Dagwood::DependencyGraph.
       def validate_deps!
+        pending = Array(@_pending_deps)
+        if pending.any?
+          raise Asgard::Error,
+            "depends_on(#{pending.join(', ')}) declared without a following task definition"
+        end
+
         return if _deps.empty?
 
-        all_tasks  = all_commands.keys.map(&:to_sym)
-        full_graph = all_tasks.each_with_object({}) do |task, hash|
+        all_task_names = all_commands.keys.map(&:to_sym)
+        full_graph     = all_task_names.each_with_object({}) do |task, hash|
           hash[task] = _deps.fetch(task, []).flatten
         end
 
+        undefined = _deps.values.flatten.uniq - all_task_names
+        if undefined.any?
+          raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
+        end
+
+        _deps.each do |_task, stages|
+          stages.flatten.each do |dep|
+            meth = instance_method(dep.to_s) rescue nil
+            next unless meth
+            required = meth.parameters.count { |type, _| type == :req }
+            if required > 0
+              raise Asgard::Error,
+                "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency"
+            end
+          end
+        end
+
         Dagwood::DependencyGraph.new(full_graph).order
       rescue TSort::Cyclic => e
         raise Asgard::CircularDependencyError, e.message
       end
 
       def method_added(method_name)
+        return super unless @usage
+
         pending = Array(@_pending_deps).dup
         @_pending_deps = []
 
@@ -117,36 +160,56 @@ module Asgard
 
     no_commands do
       # Dispatch hook: resolves and runs all deps (in parallel where declared)
-      # before executing the target command. Thread-safe deduplication via
-      # the class-level _ran_tasks set ensures each task runs at most once.
+      # before executing the target command.
+      #
+      # Completion-based deduplication: a task is only marked done after its
+      # body finishes. Threads that arrive at an already-running shared dep
+      # wait on its ConditionVariable rather than proceeding immediately,
+      # preventing the race where parallel tasks start before a shared dep
+      # has actually completed.
       def invoke_command(command, *args)
         $DEBUG   = true if options[:debug]
         $VERBOSE = true if options[:verbose]
         target = command.name.to_sym
 
         should_run = self.class._ran_mutex.synchronize do
-          next false if self.class._ran_tasks.include?(target)
-          self.class._ran_tasks.add(target)
-          true
+          if self.class._done.include?(target)
+            false
+          elsif self.class._running.include?(target)
+            self.class._cond[target].wait(self.class._ran_mutex) until self.class._done.include?(target)
+            false
+          else
+            self.class._running.add(target)
+            true
+          end
         end
         return unless should_run
 
-        stages = self.class._deps[target]
-        if stages&.any?
-          graph  = self.class._build_dep_graph(stages)
-          groups = Dagwood::DependencyGraph.new(graph).parallel_order
-
-          groups.each do |group|
-            if group.size > 1
-              threads = group.map { |task| Thread.new { _run_dep(task) } }
-              threads.each(&:join)
-            else
-              _run_dep(group.first)
+        begin
+          stages = self.class._deps[target]
+          if stages&.any?
+            graph  = self.class._build_dep_graph(stages)
+            groups = Dagwood::DependencyGraph.new(graph).parallel_order
+
+            groups.each do |group|
+              if group.size > 1
+                threads = group.map { |task| Thread.new { _run_dep(task) } }
+                errors  = []
+                threads.each { |t| begin; t.join; rescue => e; errors << e; end }
+                raise errors.first if errors.any?
+              else
+                _run_dep(group.first)
+              end
             end
           end
-        end
 
-        command.run(self, *args)
+          command.run(self, *args)
+        ensure
+          self.class._ran_mutex.synchronize do
+            self.class._done.add(target)
+            self.class._cond[target].broadcast
+          end
+        end
       end
 
       def _run_dep(task)

data/lib/asgard/shell.rb

@@ -32,7 +32,9 @@ module Asgard
       }
       ext = extensions.fetch(interpreter.to_sym, ".tmp")
 
-      Tempfile.create(["asgard_", ext]) do |f|
+      $stdout.puts script unless silent
+
+    Tempfile.create(["asgard_", ext]) do |f|
         f.write(script)
         f.flush
         system(interpreter.to_s, f.path)

data/lib/asgard/tasks.rb

@@ -14,6 +14,12 @@ class Tasks < Asgard::Base
                default: false,
                desc:    "Enable verbose output ($VERBOSE = true)"
 
+  desc "--auto-load", "Load all *.loki files from the project root before running"
+  map "--auto-load" => :_auto_load
+  def _auto_load
+    # Consumed by run! before Thor dispatch — never called directly.
+  end
+
   desc "--version", "Show asgard version"
   map "--version" => :_version
   def _version

data/lib/asgard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Asgard
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/asgard.rb

@@ -32,14 +32,19 @@ module Asgard
 
   # Main entry point invoked by the asgard executable.
   def self.run!(argv)
+    auto_load = argv.delete("--auto-load")
     abort "asgard: unknown command '#{argv.first}'" if argv.first&.start_with?("_")
     task_file = find_task_file or abort "asgard: no .loki file found in #{Dir.pwd}"
-    load_loki(File.dirname(task_file))
+    before = Asgard::Base.subclasses.dup
+    load_loki(File.dirname(task_file)) if auto_load
     load task_file
-    Tasks.validate_deps!
+    newly_defined = Asgard::Base.subclasses - before
+    (newly_defined + [Tasks]).uniq.each(&:validate_deps!)
     Tasks._reset_ran!
     Tasks.start(argv)
   rescue CircularDependencyError => e
     abort "asgard: circular dependency — #{e.message}"
+  rescue Error => e
+    abort "asgard: #{e.message}"
   end
 end