asgard 0.1.0 → 0.1.2

data/examples/.loki

@@ -0,0 +1,2 @@
+# The .loki file can be empty if there are *.loki files define the tasks
+# they will be auto loaded.

data/examples/db_subcommands.loki

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# Demonstrates Thor subcommands with Asgard's depends_on chaining within
+# the subcommand group. Inherits from Tasks for full Asgard DSL access.
+#
+# Usage:
+#   asgard db               # shows subcommand help
+#   asgard db migrate
+#   asgard db migrate 20240101120000 --dry-run
+#   asgard db rollback
+#   asgard db rollback 3
+#   asgard db seed --file db/seeds/staging.rb
+#   asgard db reset         # runs: rollback → migrate → seed
+#   asgard db console --env staging
+#   asgard db status
+
+class DBCommands < Tasks
+  desc "migrate [VERSION]", "Run pending migrations up to VERSION"
+  option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Print SQL without executing"
+  option :verbose, aliases: "-v", type: :boolean, default: false, desc: "Show each migration as it runs"
+  def migrate(version = nil)
+    target = version ? "to version #{version}" : "to latest"
+    puts "Migrating #{target}#{options[:dry_run] ? " (dry run)" : ""}..."
+  end
+
+  desc "rollback [STEPS]", "Roll back the last STEPS migrations (default: 1)"
+  option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Print SQL without executing"
+  def rollback(steps = "1")
+    puts "Rolling back #{steps} migration(s)#{options[:dry_run] ? " (dry run)" : ""}..."
+  end
+
+  desc "seed [FILE]", "Load seed data into the database"
+  option :env, type: :string, default: "development",
+               enum:  %w[development staging production],
+               desc:  "Environment to seed"
+  def seed(file = "db/seeds.rb")
+    puts "Seeding #{options[:env]} from #{file}..."
+  end
+
+  # depends_on chains within the subcommand group:
+  #   rollback → migrate → seed → reset
+  depends_on :rollback, :migrate, :seed
+  desc "reset", "Rollback all migrations, re-migrate, and reseed"
+  def reset
+    puts "Database reset complete."
+  end
+
+  long_desc <<~DESC
+    Opens an interactive SQL console connected to the configured database.
+
+    The console inherits credentials from the current environment's
+    database.yml (Rails) or DATABASE_URL.
+
+    Examples:\x5
+      asgard db console\x5
+      asgard db console --env staging
+  DESC
+  desc "console", "Open an interactive database console"
+  option :env, type: :string, default: "development",
+               enum:  %w[development staging production],
+               desc:  "Environment to connect to"
+  def console
+    puts "Opening #{options[:env]} database console..."
+  end
+
+  desc "status", "Show applied and pending migrations"
+  def status
+    puts "Checking migration status..."
+  end
+end
+
+class Tasks
+  desc "db SUBCOMMAND", "Manage the database"
+  subcommand "db", DBCommands
+end

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

@@ -2,7 +2,7 @@
 
 require "thor"
 require "set"
-require "simple_flow"
+require "dagwood"
 
 module Asgard
   class Base < Thor
@@ -57,15 +57,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)
@@ -88,7 +88,7 @@ module Asgard
         Dotenv.load(path) if File.exist?(path)
       end
 
-      # Validate the full dep graph for cycles using SimpleFlow::DependencyGraph.
+      # Validate the full dep graph for cycles using Dagwood::DependencyGraph.
       def validate_deps!
         return if _deps.empty?
 
@@ -97,7 +97,7 @@ module Asgard
           hash[task] = _deps.fetch(task, []).flatten
         end
 
-        SimpleFlow::DependencyGraph.new(full_graph).order
+        Dagwood::DependencyGraph.new(full_graph).order
       rescue TSort::Cyclic => e
         raise Asgard::CircularDependencyError, e.message
       end
@@ -118,8 +118,10 @@ 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.
+      # the class-level _ran_tasks set ensures each task runs at most once.
       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
@@ -132,7 +134,7 @@ module Asgard
         stages = self.class._deps[target]
         if stages&.any?
           graph  = self.class._build_dep_graph(stages)
-          groups = SimpleFlow::DependencyGraph.new(graph).parallel_order
+          groups = Dagwood::DependencyGraph.new(graph).parallel_order
 
           groups.each do |group|
             if group.size > 1

data/lib/asgard/tasks.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# 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
+  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 "--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.0"
+  VERSION = "0.1.2"
 end

data/lib/asgard.rb

@@ -3,30 +3,43 @@
 require_relative "asgard/version"
 require_relative "asgard/shell"
 require_relative "asgard/base"
+require_relative "asgard/tasks"
 
 module Asgard
   class Error < StandardError; end
   class CircularDependencyError < Error; end
 
-  # Search the current directory and its ancestors for task files.
-  # Returns an array of paths, or nil if nothing is found.
-  #
-  # Priority:
-  #   1. A single .loki file in the directory (default/hidden task file)
-  #   2. All *.loki files in the directory, sorted alphabetically
-  def self.find_task_files
+  # 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
-      dot_loki = File.join(dir, ".loki")
-      return [dot_loki] if File.exist?(dot_loki)
-
-      matches = Dir.glob(File.join(dir, "*.loki")).sort
-      return matches unless matches.empty?
-
+      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 }
+  end
+
+  # Main entry point invoked by the asgard executable.
+  def self.run!(argv)
+    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))
+    load task_file
+    Tasks.validate_deps!
+    Tasks._reset_ran!
+    Tasks.start(argv)
+  rescue CircularDependencyError => e
+    abort "asgard: circular dependency — #{e.message}"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asgard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: logger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -38,19 +24,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: simple_flow
+  name: dagwood
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -65,9 +51,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: 'Asgard brings just-style recipes to Ruby: Thor-powered CLI, dep ordering
-  via SimpleFlow::DependencyGraph, var declarations, dotenv, sh/shebang helpers, and
-  importable task modules.'
+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:
@@ -78,6 +64,7 @@ files:
 - ".envrc"
 - ".loki"
 - CHANGELOG.md
+- CLAUDE.md
 - COMMITS.md
 - LICENSE.txt
 - README.md
@@ -85,9 +72,14 @@ files:
 - bin/asgard
 - bin/console
 - bin/setup
+- examples/.loki
+- examples/db_subcommands.loki
+- examples/kitchen_sink.loki
+- examples/server_subcommands.loki
 - lib/asgard.rb
 - lib/asgard/base.rb
 - lib/asgard/shell.rb
+- lib/asgard/tasks.rb
 - lib/asgard/version.rb
 - sig/asgard.rbs
 homepage: https://github.com/madbomber/asgard
@@ -113,5 +105,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.12
 specification_version: 4
-summary: A just-like task runner built on Thor, with recipe dependencies via SimpleFlow.
+summary: A powerful Ruby-based task runner
 test_files: []