asgard 0.2.0 → 0.3.1

data/examples/kitchen_sink.loki

@@ -5,9 +5,20 @@
 # 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}" }
+  # ── Ruby class variables — shared across all tasks and subcommands ──────────
+  @@app_name  ||= "my_app".freeze
+  @@build_dir ||= "builds/#{@@app_name}".freeze
+
+  # ── Computed values — plain private methods replace the removed var DSL ──────
+  # Declare as private so Thor does not try to register them as commands.
+  # Use @ivar ||= inside the method body to memoize expensive calls.
+  private
+
+  def version = `git describe --tags --always`.strip
+  def sha     = `git rev-parse --short HEAD`.strip
+  def branch  = @branch ||= `git rev-parse --abbrev-ref HEAD`.strip
+
+  public
 
   # ── Asgard: dotenv — load environment variables ────────────────────────────
   # Uncomment to activate:
@@ -37,9 +48,9 @@ class Tasks
   map "pl" => :pipeline
 
   # ── Basic task — no parameters ─────────────────────────────────────────────
-  desc "greet", "Say hello (default task when no command is given)"
+  desc "Say hello (default task when no command is given)"
   def greet
-    puts "Hello from #{app_name} (#{options[:env]})!"
+    puts "Hello from #{@@app_name} #{version} (#{branch}) in #{options[:env]} mode!"
   end
 
   # ── Positional parameter with default ──────────────────────────────────────
@@ -72,14 +83,14 @@ class Tasks
   end
 
   # ── method_option — all five option types ──────────────────────────────────
-  desc "compile", "Compile the project"
+  desc "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]}"
+    puts "Compiling #{@@app_name} → #{options[:output]}"
   end
 
   # ── required option + enum + banner ────────────────────────────────────────
@@ -99,7 +110,7 @@ class Tasks
          default: "main",
          desc:    "Git branch to deploy"
   def deploy(env = "staging")
-    puts "Deploying #{app_name}@#{options[:branch]} to #{env}..."
+    puts "Deploying #{@@app_name}@#{options[:branch]} to #{env}..."
   end
 
   # ── long_desc — extended help shown by `asgard help report` ────────────────
@@ -115,7 +126,7 @@ class Tasks
       asgard report --format json --output report.json\x5
       asgard rp --format text
   LONGDESC
-  desc "report", "Generate a project report"
+  desc "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"
@@ -124,30 +135,52 @@ class Tasks
   end
 
   # ── Asgard depends_on: sequential — analyze runs before spec ───────────────
-  desc "analyze", "Check code style and complexity"
+  desc "Check code style and complexity"
   def analyze = puts "Analyzing..."
 
   depends_on :analyze
-  desc "spec", "Run the test suite (depends on: analyze)"
+  desc "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"
+  desc "Run the type checker"
   def typecheck = puts "Type checking..."
 
   depends_on [:analyze, :typecheck]
-  desc "check", "Run analyze and typecheck in parallel"
+  desc "Run analyze and typecheck in parallel"
   def check = puts "All checks passed."
 
   # ── Asgard depends_on: mixed sequential + parallel ─────────────────────────
-  desc "pack", "Create distribution archive"
+  desc "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"
+  desc "Full pipeline: check → compile+spec → pack"
   def pipeline = puts "Pipeline complete."
 
+  # ── Asgard: debug? / verbose? — Kernel predicates for conditional output ──────
+  # debug?   returns true when --debug is passed  (sets $DEBUG)
+  # verbose? returns true when --verbose is passed (sets $VERBOSE)
+  # Both are set by Asgard before invoke_command runs, so they are safe
+  # to read inside any task body.
+  #
+  # Run with:
+  #   asgard status --verbose
+  #   asgard status --debug
+  #   asgard status --verbose --debug
+  desc "Show application status"
+  def status
+    puts "#{@@app_name} is running in #{options[:env]} mode."
+    puts "  build dir : #{@@build_dir}" if verbose?
+    puts "  sha       : #{current_sha}" if verbose?
+    if debug?
+      puts "  $DEBUG    : #{$DEBUG.inspect}"
+      puts "  $VERBOSE  : #{$VERBOSE.inspect}"
+      puts "  options   : #{options.inspect}"
+    end
+  end
+
   # ── Thor: no_commands — public helper excluded from CLI and --help ──────────
   no_commands do
     def current_sha

data/examples/server_subcommands.loki

@@ -1,52 +1,61 @@
 # 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.
+# Port state is persisted to .server.port so stop and restart always
+# operate on the same port the server was started on.
 #
 # Usage:
-#   asgard server          # shows subcommand help
+#   asgard server                    # shows subcommand help
 #   asgard server start
-#   asgard server start 4000 --workers 4 --daemon
+#   asgard server start -p 8000
+#   asgard server start -p 4000 --workers 4 --daemon
+#   asgard server stop
 #   asgard server stop --force
 #   asgard server status
-#   asgard server restart 4000
+#   asgard server restart            # stops then starts on the persisted port
+
+SERVER_PORT_FILE = "tmp/.server.port".freeze
 
 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"
+  default_task :help  # This is the default value for the default_task
+
+  helper(:server_port) {
+    File.exist?(SERVER_PORT_FILE) ? File.read(SERVER_PORT_FILE).strip.to_i : 3000
+  }
+
+  desc "Start the server"
+  option :port,    aliases: "-p", type: :numeric, default: 3000,             desc: "Port to listen on"
+  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)" : ""
-    ]
+  def start
+    FileUtils.mkdir_p("tmp")
+    File.write(SERVER_PORT_FILE, options[:port].to_s)
+    puts "Starting server on :#{options[:port]} with #{options[:workers]} workers#{options[:daemon] ? " (daemon)" : ""}..."
   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
     if options[:force]
-      puts "Force-stopping server..."
+      puts "Force-stopping server on :#{server_port}..."
     else
-      puts "Gracefully stopping server (timeout: #{options[:wait]}s)..."
+      puts "Gracefully stopping server on :#{server_port} (timeout: #{options[:wait] || 30}s)..."
     end
   end
 
-  desc "status", "Show server status and process info"
+  desc "Show server status and process info"
   def status
-    puts "Checking server status..."
+    puts "Server is listening on :#{server_port}"
   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}."
+  depends_on :stop
+  desc "Restart the server on the same port it was started on"
+  def restart
+    puts "Starting server on :#{server_port}..."
+    puts "Server restarted."
   end
 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/gem_tasks.loki

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+# Gem lifecycle tasks — imported by .loki
+
+class Tasks
+  desc "Build the gem package"
+  depends_on :quality
+  def build
+    sh "mkdir -p pkg"
+    sh "gem build asgard.gemspec"
+    sh "mv asgard-#{project_version}.gem pkg/"
+  end
+
+  desc "Build and install gem locally"
+  depends_on :build
+  def install
+    sh "gem install pkg/asgard-#{project_version}.gem"
+  end
+
+  desc "Release to RubyGems"
+  depends_on :quality
+  def release
+    tag      = "v#{project_version}"
+    gem_file = "pkg/asgard-#{project_version}.gem"
+
+    abort "Working directory is not clean — commit or stash changes first." unless `git status --porcelain`.strip.empty?
+    abort "Tag #{tag} already exists." unless `git tag -l #{tag}`.strip.empty?
+
+    sh "mkdir -p pkg"
+    sh "gem build asgard.gemspec"
+    sh "mv asgard-#{project_version}.gem pkg/"
+    sh "git tag #{tag}"
+    sh "git push origin #{tag}"
+    sh "gem push #{gem_file}"
+  end
+end

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,23 +78,40 @@ 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)
+      # 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
+
+      # Suppress [--no-name] / [--skip-name] from help for boolean class options
+      # where negation is meaningless. Call after class_option declarations.
+      def no_negate(*names)
+        names.each do |name|
+          opt = class_options[name]
+          next unless opt
+          opt.define_singleton_method(:usage) do |padding = 0|
+            aliases_for_usage.ljust(padding) + "[#{switch_name}]"
           end
         end
       end
 
-      def import(mod)
-        include mod
+      def header(text = nil)
+        return @_header if text.nil?
+        (@_header ||= []) << text
+      end
+
+      def footer(text = nil)
+        return @_footer if text.nil?
+        (@_footer ||= []).unshift(text)
       end
 
       def dotenv(path = ".env")
@@ -106,44 +119,86 @@ module Asgard
         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 helper(name, &)
+        define_singleton_method(name, &)
+        no_commands { private define_method(name) { |*args, **kwargs, &blk| self.class.send(name, *args, **kwargs, &blk) } }
+      end
+
+      def default_task(meth = nil)
+        if meth && meth != :none && @_default_task_location
+          here = caller_locations(1, 1).first
+          # rubocop:disable Style/StderrPuts -- warn bypasses $stderr in Ruby 4.0, breaking capture_io in tests
+          $stderr.puts "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}"
+          # rubocop:enable Style/StderrPuts
         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?
+
+        raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
+      end
 
-        _deps.each do |_task, stages|
+      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
@@ -158,6 +213,13 @@ module Asgard
       end
     end
 
+    def help(command = nil, subcommand = false) # rubocop:disable Style/OptionalBooleanParameter
+      say self.class.header.join("\n\n") if self.class.header && command.nil?
+      say "\n"
+      super
+      say self.class.footer.join("\n\n") if self.class.footer && command.nil?
+    end
+
     no_commands do
       # Dispatch hook: resolves and runs all deps (in parallel where declared)
       # before executing the target command.
@@ -171,51 +233,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