asgard 0.2.0 → 0.3.0

data/examples/server_subcommands.loki

@@ -2,7 +2,7 @@
 # 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.
+# depends_on, and the built-in --debug/--verbose class options.
 #
 # Usage:
 #   asgard server          # shows subcommand help
@@ -26,7 +26,7 @@ class ServerCommands < Tasks
     ]
   end
 
-  desc "stop", "Stop the running server"
+  desc "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
@@ -37,7 +37,7 @@ class ServerCommands < Tasks
     end
   end
 
-  desc "status", "Show server status and process info"
+  desc "Show server status and process info"
   def status
     puts "Checking server status..."
   end

data/examples/subdir/.loki

@@ -0,0 +1,12 @@
+# examples/subdir/.loki — root task file for this subdirectory.
+#
+# When asgard is run from examples/subdir/, it loads this file.
+# From here, import pulls in sibling task files explicitly.
+#
+# import accepts a direct path or a glob:
+#   import "import_up_demo.loki"       # a single file
+#   import "*.loki"                    # all loki files in this directory
+#   import "tasks/**/*.loki"           # all loki files under a tasks/ tree
+#   import "../shared/*.loki"          # files in a sibling directory
+
+import "import_up_demo.loki"

data/examples/subdir/import_demo.loki

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+# This file lives in a subdirectory and is explicitly imported by the
+# parent examples/.loki via import "subdir/import_demo.loki".
+#
+# In a real project a subdirectory might hold task files scoped to a
+# specific concern (deploy, database, CI) while the root .loki wires
+# them all together with import.
+
+class Tasks
+  desc "Confirm this task was loaded from a subdirectory via import"
+  def subdir_task
+    puts "Loaded from examples/subdir/import_demo.loki"
+  end
+end

data/examples/subdir/import_up_demo.loki

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Demonstrates import_up — find a file by walking up the directory tree
+# and load it, without needing to know how deep the current file is.
+#
+# import_up(name) combines loki_up(name) + import(path) in one call.
+# It searches CWD, then each ancestor in turn, and loads the first match.
+#
+# This is useful when a nested task file needs to pull in something from
+# the project root — a shared config, a common helpers file — without
+# hardcoding a relative path that would break if the file moves.
+#
+# import_up also accepts a glob:
+#   import_up "*.loki"                 # first directory (walking up) that contains any .loki file
+#   import_up "config/settings.loki"   # first ancestor with config/settings.loki
+#   import_up ".env"                   # locate a .env file anywhere up the tree
+
+# Load env_usage.loki from the nearest ancestor directory that contains it.
+import_up "env_usage.loki"

data/lib/asgard/base.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "thor"
-require "set"
 require "dagwood"
 
 module Asgard
@@ -16,9 +15,10 @@ module Asgard
       def inherited(subclass)
         super
         Asgard::Base.subclasses << subclass
-        subclass.instance_variable_set(:@_deps,         {})
-        subclass.instance_variable_set(:@_vars,         {})
-        subclass.instance_variable_set(:@_pending_deps, [])
+        subclass.instance_variable_set(:@_deps,              {})
+        subclass.instance_variable_set(:@_pending_deps,      [])
+        subclass.instance_variable_set(:@_pending_single_desc,      nil)
+        subclass.instance_variable_set(:@_pending_single_desc_opts, nil)
         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 })
@@ -29,10 +29,6 @@ module Asgard
         @_deps ||= {}
       end
 
-      def _vars
-        @_vars ||= {}
-      end
-
       def _running
         @_running ||= Set.new
       end
@@ -65,7 +61,7 @@ module Asgard
       def _build_dep_graph(stages)
         graph = {}
         stages.each_with_index do |stage, i|
-          prev_stage = i > 0 ? stages[i - 1] : []
+          prev_stage = i.positive? ? stages[i - 1] : []
           stage.each { |task| graph[task] = prev_stage.dup }
         end
         graph
@@ -82,68 +78,98 @@ module Asgard
         @_pending_deps = tasks
       end
 
-      def var(name, value = nil, &block)
-        value = block if block_given?
-        _vars[name.to_sym] = value
-        no_commands do
-          define_method(name) do
-            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
+      # Allow single-argument desc: desc "Run the tests"
+      # The usage string defaults to the method name when the description is the only arg.
+      def desc(usage_or_desc, description = nil, options = {})
+        if description.nil? || description.is_a?(Hash)
+          options = description if description.is_a?(Hash)
+          @_pending_single_desc      = usage_or_desc
+          @_pending_single_desc_opts = options
+        else
+          @_pending_single_desc      = nil
+          @_pending_single_desc_opts = nil
+          super
         end
       end
 
-      def import(mod)
-        include mod
-      end
-
       def dotenv(path = ".env")
         require "dotenv"
         Dotenv.load(path) if File.exist?(path)
       end
 
-      # 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"
+      def default_task(meth = nil)
+        if meth && meth != :none && @_default_task_location
+          here = caller_locations(1, 1).first
+          warn "asgard: default_task :#{meth} at #{here.path}:#{here.lineno} " \
+               "overrides default_task :#{@_default_task_name} set at " \
+               "#{@_default_task_location.path}:#{@_default_task_location.lineno}"
+        end
+        if meth && meth != :none
+          @_default_task_location = caller_locations(1, 1).first
+          @_default_task_name     = meth
         end
+        super
+      end
 
+      # Validate the full dep graph for cycles using Dagwood::DependencyGraph.
+      def validate_deps!
+        _check_orphaned_deps!
         return if _deps.empty?
 
         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
+        _check_undefined_deps!(all_task_names)
+        _check_dep_arities!
+        _build_and_sort_graph(all_task_names)
+      rescue TSort::Cyclic => e
+        raise Asgard::CircularDependencyError, e.message
+      end
+
+      private
+
+      def _check_orphaned_deps!
+        pending = Array(@_pending_deps)
+        return unless pending.any?
 
+        raise Asgard::Error,
+              "depends_on(#{pending.join(', ')}) declared without a following task definition"
+      end
+
+      def _check_undefined_deps!(all_task_names)
         undefined = _deps.values.flatten.uniq - all_task_names
-        if undefined.any?
-          raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
-        end
+        return unless undefined.any?
 
-        _deps.each do |_task, stages|
+        raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
+      end
+
+      def _check_dep_arities!
+        _deps.each_value do |stages|
           stages.flatten.each do |dep|
-            meth = instance_method(dep.to_s) rescue nil
-            next unless meth
+            meth = instance_method(dep.to_s)
             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
+            next unless required.positive?
+
+            raise Asgard::Error,
+                  "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency"
           end
         end
+      end
 
+      def _build_and_sort_graph(all_task_names)
+        full_graph = all_task_names.to_h { |task| [task, _deps.fetch(task, []).flatten] }
         Dagwood::DependencyGraph.new(full_graph).order
-      rescue TSort::Cyclic => e
-        raise Asgard::CircularDependencyError, e.message
       end
 
+      public
+
       def method_added(method_name)
+        if @_pending_single_desc && !no_commands?
+          pending_desc = @_pending_single_desc
+          pending_opts = @_pending_single_desc_opts || {}
+          @_pending_single_desc      = nil
+          @_pending_single_desc_opts = nil
+          desc(method_name.to_s, pending_desc, pending_opts)
+        end
+
         return super unless @usage
 
         pending = Array(@_pending_deps).dup
@@ -171,51 +197,67 @@ module Asgard
         $DEBUG   = true if options[:debug]
         $VERBOSE = true if options[:verbose]
         target = command.name.to_sym
-
-        should_run = self.class._ran_mutex.synchronize do
-          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
+        return unless acquire_run_token(target)
 
         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
-
+          run_deps_for(target)
           command.run(self, *args)
         ensure
-          self.class._ran_mutex.synchronize do
-            self.class._done.add(target)
-            self.class._cond[target].broadcast
-          end
+          signal_done(target)
+        end
+      end
+    end
+
+    private
+
+    def acquire_run_token(target)
+      self.class._ran_mutex.synchronize do
+        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
+    end
+
+    def run_deps_for(target)
+      stages = self.class._deps[target]
+      return unless stages&.any?
+
+      groups = Dagwood::DependencyGraph.new(self.class._build_dep_graph(stages)).parallel_order
+      groups.each { |group| run_dep_group(group) }
+    end
 
-      def _run_dep(task)
-        command = self.class.all_commands[task.to_s]
-        invoke_command(command) if command
+    def run_dep_group(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 }
+        if errors.size == 1
+          raise errors.first
+        elsif errors.any?
+          errors.each { |e| warn "asgard: #{e.message}" }
+          raise Asgard::Error, "#{errors.size} parallel dependencies failed"
+        end
+      else
+        run_dep(group.first)
+      end
+    end
+
+    def signal_done(target)
+      self.class._ran_mutex.synchronize do
+        self.class._done.add(target)
+        self.class._cond[target].broadcast
       end
     end
+
+    def run_dep(task)
+      command = self.class.all_commands[task.to_s]
+      invoke_command(command) if command
+    end
   end
 end

data/lib/asgard/kernel_methods.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Kernel
+  def debug?   = $DEBUG
+  def verbose? = $VERBOSE
+  module_function :debug?, :verbose?
+
+  # Fetch an environment variable by symbol or string name.
+  # The name is converted to an uppercase string automatically.
+  # Raises KeyError when the variable is missing and no default is given.
+  def env(name, default = nil)
+    key = name.to_s.upcase
+    default.nil? ? ENV.fetch(key) : ENV.fetch(key, default)
+  end
+  module_function :env
+
+  def loki_up(name = ".loki")
+    dir = Dir.pwd
+    loop do
+      candidate = File.join(dir, name)
+      return candidate if File.exist?(candidate)
+      parent = File.dirname(dir)
+      break if parent == dir
+      dir = parent
+    end
+    nil
+  end
+  module_function :loki_up
+
+  def import(path)
+    path = path.to_s
+    raise ArgumentError, "import: path must end with .loki (got #{path.inspect})" unless path.end_with?(".loki")
+    unless File.absolute_path?(path)
+      caller_dir = File.dirname(caller_locations(1, 1).first.absolute_path)
+      path = File.expand_path(path, caller_dir)
+    end
+    paths = path =~ /[*?\[{]/ ? Dir.glob(path) : [path]
+    loaded = paths.map do |p|
+      if $LOADED_FEATURES.include?(p)
+        warn "import: skip #{p} (already loaded)" if debug?
+        next false
+      end
+      warn "import: #{p}" if verbose? || debug?
+      load p
+      $LOADED_FEATURES << p
+      true
+    end
+    loaded.any?
+  end
+  module_function :import
+
+  def import_up(name = ".loki")
+    if name =~ /[*?\[{]/
+      dir = Dir.pwd
+      loop do
+        matches = Dir.glob(File.join(dir, name))
+        unless matches.empty?
+          warn "import_up: #{name} → #{dir}" if verbose? || debug?
+          return matches.map { |p| import(p) }.any?
+        end
+        parent = File.dirname(dir)
+        break if parent == dir
+        dir = parent
+      end
+      warn "import_up: #{name} not found" if debug?
+      return false
+    end
+    path = loki_up(name)
+    unless path
+      warn "import_up: #{name} not found" if debug?
+      return false
+    end
+    warn "import_up: #{name} → #{path}" if verbose? || debug?
+    import path
+  end
+  module_function :import_up
+end

data/lib/asgard/shell.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'English'
 require "tempfile"
 
 module Asgard
@@ -12,12 +13,12 @@ module Asgard
       $stdout.puts script unless silent
 
       success = if script.include?("\n")
-        system("bash", "-c", script)
-      else
-        system(script)
-      end
+                  system("bash", "-c", script)
+                else
+                  system(script)
+                end
 
-      exit($?.exitstatus) unless success
+      exit($CHILD_STATUS.exitstatus) unless success
     end
 
     # Write +script+ to a tempfile and execute it with +interpreter+.
@@ -34,11 +35,11 @@ module Asgard
 
       $stdout.puts script unless silent
 
-    Tempfile.create(["asgard_", ext]) do |f|
+      Tempfile.create(["asgard_", ext]) do |f|
         f.write(script)
         f.flush
         system(interpreter.to_s, f.path)
-        exit($?.exitstatus) unless $?.success?
+        exit($CHILD_STATUS.exitstatus) unless $CHILD_STATUS.success?
       end
     end
   end

data/lib/asgard/tasks.rb

@@ -14,21 +14,10 @@ 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
     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.2.0"
+  VERSION = "0.3.0"
 end

data/lib/asgard.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "asgard/version"
+require_relative "asgard/kernel_methods"
 require_relative "asgard/shell"
 require_relative "asgard/base"
 require_relative "asgard/tasks"
@@ -12,31 +13,14 @@ module Asgard
   # Search the current directory and its ancestors for a .loki task file.
   # Returns the path string, or nil if not found.
   def self.find_task_file
-    dir = Dir.pwd
-    loop do
-      candidate = File.join(dir, ".loki")
-      return candidate if File.exist?(candidate)
-      parent = File.dirname(dir)
-      break if parent == dir
-      dir = parent
-    end
-    nil
-  end
-
-  # Load all *.loki files from dir in alphabetical order.
-  # 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 }
+    loki_up
   end
 
   # 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}"
     before = Asgard::Base.subclasses.dup
-    load_loki(File.dirname(task_file)) if auto_load
     load task_file
     newly_defined = Asgard::Base.subclasses - before
     (newly_defined + [Tasks]).uniq.each(&:validate_deps!)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asgard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -51,9 +51,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: A powerful Ruby-based task runner for any kind of project with task dependency
-  tracking and concurrent execution of designated tasks. Uses Thor for its rich CLI
-  options, var declarations, dotenv, sh/shebang helpers, and importable task files.
+description: |
+  A powerful Ruby-based task runner for any kind of project with task dependency tracking
+  and concurrent execution of designated tasks. Uses Thor for its rich CLI options, var
+  declarations, dotenv, sh/shebang helpers, and importable task files.
 email:
 - dewayne@vanhoozer.me
 executables:
@@ -64,6 +65,7 @@ files:
 - ".envrc"
 - ".github/workflows/deploy-github-pages.yml"
 - ".loki"
+- ".rubocop.yml"
 - CHANGELOG.md
 - CLAUDE.md
 - COMMITS.md
@@ -89,13 +91,19 @@ files:
 - docs/task-files.md
 - docs/tasks.md
 - docs/variables.md
+- examples/.env
 - examples/.loki
 - examples/concurrent.loki
 - examples/db_subcommands.loki
+- examples/env_usage.loki
 - examples/kitchen_sink.loki
 - examples/server_subcommands.loki
+- examples/subdir/.loki
+- examples/subdir/import_demo.loki
+- examples/subdir/import_up_demo.loki
 - lib/asgard.rb
 - lib/asgard/base.rb
+- lib/asgard/kernel_methods.rb
 - lib/asgard/shell.rb
 - lib/asgard/tasks.rb
 - lib/asgard/version.rb
@@ -108,6 +116,7 @@ metadata:
   homepage_uri: https://github.com/madbomber/asgard
   source_code_uri: https://github.com/madbomber/asgard
   changelog_uri: https://github.com/madbomber/asgard/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib