asgard 0.1.1 → 0.2.0

data/examples/kitchen_sink.loki

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+# kitchen_sink.loki — demonstrates every Thor DSL feature available in Asgard.
+#
+# Task names deliberately avoid the gem's own .loki tasks (test, build, quality,
+# install, release) so this file can be loaded alongside them without conflict.
+
+class Tasks
+  # ── Asgard: var — static value and lazy lambda ─────────────────────────────
+  var :app_name,  "my_app"
+  var :build_dir, -> { "builds/#{app_name}" }
+
+  # ── Asgard: dotenv — load environment variables ────────────────────────────
+  # Uncomment to activate:
+  # dotenv              # loads .env
+  # dotenv ".env.local" # or a specific file
+
+  # ── Thor: class_option — option present on every task ──────────────────────
+  class_option :dry_run,
+               aliases: "-n",
+               type:    :boolean,
+               default: false,
+               desc:    "Print commands without executing them"
+
+  class_option :env,
+               type:    :string,
+               default: "development",
+               enum:    %w[development staging production],
+               desc:    "Target environment"
+
+  # ── Thor: default_task — runs when no command is given ─────────────────────
+  default_task :greet
+
+  # ── Thor: map — short aliases for tasks ────────────────────────────────────
+  map "g"  => :greet
+  map "ck" => :check
+  map "rp" => :report
+  map "pl" => :pipeline
+
+  # ── Basic task — no parameters ─────────────────────────────────────────────
+  desc "greet", "Say hello (default task when no command is given)"
+  def greet
+    puts "Hello from #{app_name} (#{options[:env]})!"
+  end
+
+  # ── Positional parameter with default ──────────────────────────────────────
+  desc "hello NAME", "Greet NAME; omit NAME to greet the world"
+  def hello(name = "World")
+    puts "Hello, #{name}!"
+  end
+
+  # ── Positional parameter with method_option ────────────────────────────────
+  desc "farewell NAME", "Say goodbye to NAME"
+  option :formal, aliases: "-f", type: :boolean, default: false, desc: "Use formal language"
+  def farewell(name = "friend")
+    msg = options[:formal] ? "Goodbye, #{name}." : "See ya, #{name}!"
+    puts msg
+  end
+
+  # ── argument — formal positional with type metadata ────────────────────────
+  # WARNING: argument is a CLASS-LEVEL declaration that pollutes every task's
+  # usage line. Only use it when every task in the class shares the same input,
+  # or in a single-command CLI. Shown here as a commented-out reference only.
+  #
+  # argument :target,
+  #          type:    :string,
+  #          default: "localhost",
+  #          desc:    "Deployment target host"
+
+  desc "notify RECIPIENT", "Send a notification to RECIPIENT"
+  def notify(recipient = "team")
+    puts "Notifying #{recipient}..."
+  end
+
+  # ── method_option — all five option types ──────────────────────────────────
+  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 #{app_name} → #{options[:output]}"
+  end
+
+  # ── required option + enum + banner ────────────────────────────────────────
+  desc "deploy ENV", "Deploy to ENV (default: staging)"
+  option :strategy,
+         type:     :string,
+         required: true,
+         enum:     %w[blue-green rolling canary],
+         desc:     "Deployment strategy"
+  option :timeout,
+         type:    :numeric,
+         default: 300,
+         banner:  "SECONDS",
+         desc:    "Abort deployment after SECONDS"
+  option :branch,
+         type:    :string,
+         default: "main",
+         desc:    "Git branch to deploy"
+  def deploy(env = "staging")
+    puts "Deploying #{app_name}@#{options[:branch]} to #{env}..."
+  end
+
+  # ── long_desc — extended help shown by `asgard help report` ────────────────
+  long_desc <<~LONGDESC
+    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 rp --format text
+  LONGDESC
+  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"
+  option :output, type: :string,                  banner: "FILE",            desc: "Write output to FILE"
+  def report
+    puts "Generating #{options[:format]} report..."
+  end
+
+  # ── Asgard depends_on: sequential — analyze runs before spec ───────────────
+  desc "analyze", "Check code style and complexity"
+  def analyze = puts "Analyzing..."
+
+  depends_on :analyze
+  desc "spec", "Run the test suite (depends on: analyze)"
+  def spec = puts "Running specs..."
+
+  # ── Asgard depends_on: parallel — analyze and typecheck run concurrently ───
+  desc "typecheck", "Run the type checker"
+  def typecheck = puts "Type checking..."
+
+  depends_on [:analyze, :typecheck]
+  desc "check", "Run analyze and typecheck in parallel"
+  def check = puts "All checks passed."
+
+  # ── Asgard depends_on: mixed sequential + parallel ─────────────────────────
+  desc "pack", "Create distribution archive"
+  def pack = puts "Packing..."
+
+  #   check → compile+spec (parallel) → pack → pipeline
+  depends_on :check, [:compile, :spec], :pack
+  desc "pipeline", "Full pipeline: check → compile+spec → pack"
+  def pipeline = puts "Pipeline complete."
+
+  # ── Thor: no_commands — public helper excluded from CLI and --help ──────────
+  no_commands do
+    def current_sha
+      `git rev-parse --short HEAD`.strip
+    end
+  end
+
+  # ── private — also excluded from CLI and --help ────────────────────────────
+  private
+
+  def banner(msg)
+    puts "=== #{msg} ==="
+  end
+end

data/examples/server_subcommands.loki

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+# Demonstrates Thor subcommands registered on the top-level Tasks class.
+#
+# The subcommand class inherits from Tasks so it has access to sh, shebang,
+# var, depends_on, and the built-in --debug/--verbose class options.
+#
+# Usage:
+#   asgard server          # shows subcommand help
+#   asgard server start
+#   asgard server start 4000 --workers 4 --daemon
+#   asgard server stop --force
+#   asgard server status
+#   asgard server restart 4000
+
+class ServerCommands < Tasks
+  desc "start [PORT]", "Start the server on PORT (default: 3000)"
+  option :daemon,  aliases: "-d", type: :boolean, default: false, desc: "Run as a background daemon"
+  option :workers, aliases: "-w", type: :numeric, default: 2,     desc: "Number of worker processes"
+  option :log,                    type: :string,  default: "log/server.log",
+                                  banner: "FILE", desc:    "Write logs to FILE"
+  def start(port = "3000")
+    puts "Starting server on :%s with %d workers%s" % [
+      port,
+      options[:workers],
+      options[:daemon] ? " (daemon)" : ""
+    ]
+  end
+
+  desc "stop", "Stop the running server"
+  option :force, aliases: "-f", type: :boolean, default: false, desc: "Force-kill without draining"
+  option :wait,                  type: :numeric, default: 30,   desc: "Seconds to wait for shutdown"
+  def stop
+    if options[:force]
+      puts "Force-stopping server..."
+    else
+      puts "Gracefully stopping server (timeout: #{options[:wait]}s)..."
+    end
+  end
+
+  desc "status", "Show server status and process info"
+  def status
+    puts "Checking server status..."
+  end
+
+  # depends_on works inside subcommand groups — stop runs before start
+  depends_on :stop, :start
+  desc "restart [PORT]", "Restart the server on PORT (stop, then start)"
+  def restart(port = "3000")
+    puts "Server restarted on port #{port}."
+  end
+end
+
+class Tasks
+  desc "server SUBCOMMAND", "Manage the application server"
+  subcommand "server", ServerCommands
+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.
@@ -57,15 +71,15 @@ module Asgard
         graph
       end
 
-      # Declare dependencies for the next recipe.
+      # Declare dependencies for the next task.
       # Bare symbols run sequentially; arrays within the splat run in parallel.
       #
       #   depends_on :build                          # sequential
       #   depends_on :build, :lint                   # both sequential
       #   depends_on [:build, :lint]                 # build and lint in parallel
       #   depends_on :setup, [:build, :lint], :test  # setup, then build+lint, then test
-      def depends_on(*recipes)
-        @_pending_deps = recipes
+      def depends_on(*tasks)
+        @_pending_deps = tasks
       end
 
       def var(name, value = nil, &block)
@@ -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,34 +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 recipe 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

@@ -3,4 +3,32 @@
 # Tasks is the single conventional entry point for all .loki files.
 # It is pre-defined by the gem so .loki files never need to declare a class.
 # Auxiliary *.loki files define modules which are imported into Tasks.
-class Tasks < Asgard::Base; end
+class Tasks < Asgard::Base
+  class_option :debug,
+               type:    :boolean,
+               default: false,
+               desc:    "Enable debug mode ($DEBUG = true)"
+
+  class_option :verbose,
+               type:    :boolean,
+               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
+    puts Asgard::VERSION
+    exit
+  end
+
+  private
+
+  def debug?   = $DEBUG
+  def verbose? = $VERBOSE
+end

data/lib/asgard/version.rb

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

data/lib/asgard.rb

@@ -24,7 +24,7 @@ module Asgard
   end
 
   # Load all *.loki files from dir in alphabetical order.
-  # Each file typically reopens class Tasks to add recipes.
+  # Each file typically reopens class Tasks to add tasks.
   # The .loki entry point is excluded — it is loaded separately by run!.
   def self.load_loki(dir)
     Dir.glob(File.join(dir, "*.loki")).sort.each { |f| load f }
@@ -32,14 +32,19 @@ module Asgard
 
   # Main entry point invoked by the asgard executable.
   def self.run!(argv)
-    task_file = find_task_file or (warn "asgard: no .loki file found in #{Dir.pwd}"; exit 1)
-    load_loki(File.dirname(task_file))
+    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}"
+    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
-    warn "asgard: circular dependency — #{e.message}"
-    exit 1
+    abort "asgard: circular dependency — #{e.message}"
+  rescue Error => e
+    abort "asgard: #{e.message}"
   end
 end

data/mkdocs.yml

@@ -0,0 +1,164 @@
+# MkDocs Configuration for Asgard Documentation
+site_name: Asgard
+site_description: Thor-based Ruby task runner with dependency graphs and concurrent execution
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/asgard
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+# Repository information
+repo_name: madbomber/asgard
+repo_url: https://github.com/MadBomber/asgard
+edit_uri: edit/main/docs/
+
+# Configuration
+theme:
+  name: material
+
+  # Color scheme
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: indigo
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  # Typography
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  # Logo and icon
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/shield
+
+  # Theme features
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
+
+# Extensions
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: asgard
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra CSS
+extra_css:
+  - assets/css/custom.css
+
+# Social media and extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/asgard
+      name: Asgard on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/asgard
+      name: Asgard on RubyGems
+
+  analytics:
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: Thanks for your feedback! Help us improve by creating an issue.
+
+# Navigation
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Tasks:
+      - Defining Tasks: tasks.md
+      - Dependencies: dependencies.md
+      - Variables: variables.md
+      - Helper Methods: helpers.md
+  - CLI:
+      - Options & Flags: options.md
+      - Subcommands: subcommands.md
+      - Shell Helpers: shell.md
+      - Environment: environment.md
+  - Task Files: task-files.md
+  - API Reference: api.md
+  - Examples: examples.md
+  - Changelog: changelog.md