asgard 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7920fc28de5f8644ccc7934f576142d433de3fb5af1ac21b28cbd350d930af66
-  data.tar.gz: e651f2956eb2f9fc076548fc04cae92e6835fb508b5960eeda952929d9197253
+  metadata.gz: 2d904144543326c15257e4e61584c46fa9b0ab4f1ba522680daa930950361e6a
+  data.tar.gz: fea08260a5db1fdde268eaf4ca930b1e52a07a39f12eaf2ce20e31736319cdff
 SHA512:
-  metadata.gz: 19e473102e5850db42c777b9dd824765b9e4a187f1de6f009d80ae85fa1d6992984587a7ca4e9dc40cb301aadc11093826f913d3c5c7dac8e17a47c47f7cdefe
-  data.tar.gz: '09c0f72476c8690f055e6aeb2b052449a4eb9fd415bff06a82e4cd5dc4255cfb8709721a76ae347226b31b8dafcbd3e63a439fcd6f249975f134156f578edb1f'
+  metadata.gz: 9f75f50ba53970998d047e21078b120090ba6c232ac698b0ba705b84a3de542bfef313690e11d2e09989101045323c7cd6549bf51826b316ccf1beeb96ada50d
+  data.tar.gz: 497bee99076f476b8fe680962f59b369898381470b27fd59e0f7e4dc7636e620004660cbcf3ceb10a2678e65ddf78a2a7e24e6571362fc7ad3e7929eeb61a614

data/CHANGELOG.md

@@ -39,8 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `Asgard::Base` — Thor subclass providing the task DSL
-- `depends_on` — declare recipe dependencies; dependencies run at most once per invocation
-- `var` — declare static or lazy-evaluated variables available to all recipes
+- `depends_on` — declare task dependencies; dependencies run at most once per invocation
+- `var` — declare static or lazy-evaluated variables available to all tasks
 - `import` — flat-merge a task module into the current class
 - `dotenv` — load a `.env` file into the environment
 - `sh` — run a shell command or multiline heredoc script; exits with the command's status on failure

data/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What Asgard Is
+
+Asgard is a Ruby task runner. Users define tasks in `.loki` files by reopening the pre-defined `Tasks` class. The name is intentional: Thor handles the CLI, Asgard is where tasks live, and Loki (the `.loki` file) holds all the tricks.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rake test          # run tests (enforces 95% SimpleCov coverage)
+bundle exec rake quality       # test + flog complexity check
+bundle exec rake build         # build .gem into pkg/
+bundle exec rake install       # install locally
+
+# or use the gem's own .loki file:
+asgard test
+asgard quality
+asgard release
+```
+
+Single test: `ruby -Ilib:test test/test_asgard.rb`
+
+## Architecture
+
+### Entry Point Flow
+
+`bin/asgard` → `Asgard.run!(ARGV)` (`lib/asgard.rb`):
+1. Walk CWD + ancestors for `.loki` (marker only, not a task file)
+2. Glob + sort `*.loki` files from that dir, `load` each alphabetically
+3. Load `.loki` itself last
+4. `Tasks.validate_deps!` — build full dep graph, raise `CircularDependencyError` if cyclic
+5. `Tasks._reset_ran!` — clear execution tracking
+6. `Tasks.start(argv)` — Thor dispatches the command
+
+### Core Classes
+
+| File | Role |
+|------|------|
+| `lib/asgard/base.rb` | DSL engine; inherits Thor, includes Shell |
+| `lib/asgard/shell.rb` | `sh` / `shebang` helpers |
+| `lib/asgard/tasks.rb` | `class Tasks < Asgard::Base` — the convention class users reopen; also holds gem-owned built-in tasks |
+
+### Naming Convention for Gem-Owned Methods
+
+Any task or method defined by Asgard itself inside `Tasks` (i.e. not by the user's `.loki` files) must be prefixed with `_`. This distinguishes built-in gem behavior from user-defined tasks and prevents naming collisions.
+
+```ruby
+# lib/asgard/tasks.rb — gem-owned built-ins use _ prefix
+class Tasks < Asgard::Base
+  desc "--version", "Show version"
+  map "--version" => :_version
+  def _version
+    puts Asgard::VERSION
+    exit
+  end
+end
+```
+
+`method_added` in `Base` already skips `_`-prefixed methods when attaching dependency metadata, so built-ins are naturally excluded from the dependency graph.
+
+Do not define `_`-prefixed methods in user `.loki` files — that namespace is reserved for the gem.
+
+### DSL Mechanics (`lib/asgard/base.rb`)
+
+**`depends_on`** stores stages in `@_pending_deps`. On `method_added`, those stages are popped and stored in `@_deps[method_name]`. Bare symbols are sequential stages; arrays within a `depends_on` call are parallel stages:
+
+```ruby
+depends_on :a, [:b, :c], :d   # stages: [[:a], [:b, :c], [:d]]
+```
+
+**`var`** stores values or lambdas in `@_vars` and creates an instance method that evaluates the lambda once on first access.
+
+**`invoke_command`** (Thor dispatch hook):
+1. Atomically check `@_ran_tasks` Set (with `@_ran_mutex`); return early if already run
+2. Resolve `@_deps` stages → `_build_dep_graph` → `Dagwood::DependencyGraph#parallel_order`
+3. For each parallel group: spawn one thread per task, join; single-task groups run inline
+4. Execute the target task
+
+**`_build_dep_graph(stages)`** converts stages to a DAG hash:
+- `[[:a], [:b, :c], [:d]]` → `{ a: [], b: [:a], c: [:a], d: [:b, :c] }`
+
+### Dependency Resolution
+
+Dagwood topologically sorts the DAG and returns parallel groups. The thread-safe deduplication (`_ran_tasks` Set + Mutex) ensures each task runs exactly once even when multiple tasks share a common dependency.
+
+### Shell Helpers
+
+- `sh(script, silent: false)` — single-line strings use `system(script)`; multi-line strings pipe through `bash -c`; exits with the command's status on failure
+- `shebang(interpreter, script)` — writes script to a tempfile and executes with the named interpreter (`:python3`, `:node`, `:ruby`, `:perl`, `:bash`, etc.)
+
+## Testing
+
+All tests are in `test/test_asgard.rb` (one file, ~11 named classes). SimpleCov minimum is 95%; the Rakefile configures this with a prelude that loads coverage before the library.
+
+Key test patterns: tests frequently subclass `Asgard::Base` directly (not `Tasks`) to test the engine in isolation, and use `capture_io` for output assertions.
+
+## The `.loki` Format
+
+A `.loki` file is plain Ruby that reopens `Tasks`:
+
+```ruby
+class Tasks
+  var :gem_name, "asgard"
+
+  desc "test", "Run tests"
+  def test = sh "bundle exec rake test"
+
+  depends_on :test
+  desc "release", "Build and release"
+  def release = sh "bundle exec rake release"
+end
+```
+
+Multiple `*.loki` files in the same directory are all loaded (alphabetically). The bare `.loki` file serves only as the project root marker — its content is loaded last.

data/README.md

@@ -1,9 +1,11 @@
 # Asgard
 
-A [just](https://just.systems)-like task runner for Ruby. Built on [Thor](https://github.com/rails/thor) for argument handling and [Dagwood](https://github.com/rewindio/dagwood) for dependency ordering.
+A Ruby task runner built on [Thor](https://github.com/rails/thor) for argument handling and [Dagwood](https://github.com/rewindio/dagwood) for dependency ordering.
 
 The name comes from Norse mythology: **Thor** is the CLI framework, **Asgard** is the realm where tasks live, and the task file is named **loki** — because Loki holds all the tricks.
 
+> **Asgard is a wrapper around [Thor](https://github.com/rails/thor).** Anything Thor can do — subcommands, typed options, argument validation, shell completion — is available inside a `.loki` file. Familiarity with Thor's DSL will make you immediately productive with Asgard.
+
 ## Installation
 
 ```bash
@@ -213,6 +215,61 @@ end
 
 ---
 
+## Helper methods
+
+Private methods are callable from any task in the same class but are never registered as commands — they won't appear in `--help` output and can't be invoked from the CLI.
+
+```ruby
+class Tasks
+  desc "build", "Compile and package"
+  def build
+    compile("src")
+    package(version)
+  end
+
+  desc "release", "Build and publish"
+  def release
+    build
+    sh "gem push pkg/myapp-#{version}.gem"
+  end
+
+  private
+
+  def compile(dir)
+    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
+  end
+
+  def package(ver)
+    sh "tar czf pkg/myapp-#{ver}.tar.gz bin/"
+  end
+end
+```
+
+Helpers can also be shared across multiple `.loki` files by extracting them into a plain Ruby file and loading it explicitly:
+
+```ruby
+# shared/helpers.rb
+module BuildHelpers
+  private
+
+  def compile(dir)
+    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
+  end
+end
+
+# .loki
+require_relative "shared/helpers"
+
+class Tasks
+  include BuildHelpers
+
+  desc "build", "Compile the project"
+  def build = compile("src")
+end
+```
+
+---
+
 ## Options shared across all tasks
 
 `class_option` defines an option available to every task in the class:
@@ -312,6 +369,64 @@ end
 
 ---
 
+## Subcommands
+
+Group related tasks under a common name using Thor's `subcommand` method. Define a subcommand class that inherits from `Tasks`, then register it with a name and description.
+
+```ruby
+class DeployCommands < Tasks
+  desc "staging", "Deploy to staging"
+  def staging = sh "cap staging deploy"
+
+  desc "production", "Deploy to production"
+  def production = sh "cap production deploy"
+end
+
+class Tasks
+  desc "deploy SUBCOMMAND", "Deploy the application"
+  subcommand "deploy", DeployCommands
+end
+```
+
+```bash
+asgard deploy           # shows deploy subcommand help
+asgard deploy staging
+asgard deploy production
+```
+
+Subcommand tasks have all the same access to helper methods like `sh`, `shebang`, `depends_on`, `var`, and the built-in `--debug`/`--verbose` class options as normal tasks.
+
+`depends_on` only works within a subcommand group exactly as it does at the top level:
+
+```ruby
+class DBCommands < Tasks
+  desc "migrate", "Run pending migrations"
+  def migrate = sh "rails db:migrate"
+
+  desc "seed", "Load seed data"
+  def seed = sh "rails db:seed"
+
+  depends_on :migrate, :seed
+  desc "reset", "Migrate then seed"
+  def reset = puts "Done."
+end
+
+class Tasks
+  desc "db SUBCOMMAND", "Manage the database"
+  subcommand "db", DBCommands
+end
+```
+
+```bash
+asgard db reset   # migrate → seed → reset
+```
+
+Each subcommand group can have its own `desc`, `long_desc`, `option`, `class_option`, and `map` declarations, all scoped to that group.
+
+See [`examples/server_subcommands.loki`](examples/server_subcommands.loki) and [`examples/db_subcommands.loki`](examples/db_subcommands.loki) for full working examples.
+
+---
+
 ## `method_option` types reference
 
 | Type | CLI example | Ruby value |

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

@@ -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)
@@ -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

data/lib/asgard/tasks.rb

@@ -3,4 +3,26 @@
 # 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 "--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.1.2"
 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,14 @@ 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)
+    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
-    warn "asgard: circular dependency — #{e.message}"
-    exit 1
+    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.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -51,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 Dagwood::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:
@@ -64,6 +64,7 @@ files:
 - ".envrc"
 - ".loki"
 - CHANGELOG.md
+- CLAUDE.md
 - COMMITS.md
 - LICENSE.txt
 - README.md
@@ -71,6 +72,10 @@ 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
@@ -100,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 Dagwood.
+summary: A powerful Ruby-based task runner
 test_files: []