asgard 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cec41525d2a749cb83bcd59a480fb4bbffa80e468ca4a35c453376a16c84640
-  data.tar.gz: 997da94f3b7bf4fadedaff8d78741ff2748b00fb7107b27402dc50cf73f897df
+  metadata.gz: 0f88b550d323b26b075a45f6a7d6e8781b7d54d062c1f724de25b2d253d2f3e4
+  data.tar.gz: 5c2a05803003793e14ad08f0453d0a549cb6f2f0202b31c38c600303a539d66b
 SHA512:
-  metadata.gz: d189e34cd3733b41e436460367130fa19451bf3938b693f1c5663a1268fab41f87866063e2c0c3a185a69dfda238aa8a5e6a253de9bbac0e2c5e97e6c9d2fa6e
-  data.tar.gz: d6fcbee1e4302dce37d7ea39cf22019ae0322f3f200e4ac5421ac247d7facca205e38cdb1f905ab20781142472b0010c46ff966dbba83be918a7fbabd49bebbd
+  metadata.gz: d9f2d214246e0960b2a2a4ca790818a8f57edfd45c17f0fca6edf1bcf486cc096d0331818d899c5ca929f9fcec404329744403a0f03aa2fe0faafb70b13ae172
+  data.tar.gz: e35a52164438b5734cdf86ee4f7210e2169edb391e8478cddd1548698691d3bddea5d703ef113e34bcdd1caeb0041d9851ec94b8ee7840b9115a0ca821f03f49

data/.loki

@@ -3,10 +3,16 @@
 # Task is pre-defined by the gem — just reopen it to add tasks.
 
 import "quality.loki"
-import "quality_rails.loki" if defined?(Rails)
+# asgard runs as a separate process outside the app it's checking, so
+# `defined?(Rails)` never sees the app's Rails constant. RAILS_ROOT — set in
+# a Rails repo's own .envrc (`export RAILS_ROOT=$RR`, after RR is defined)
+# — is the signal instead.
+import "quality_rails.loki" if ENV["RAILS_ROOT"]
 
 import "gem_tasks.loki"
 import "git.loki"
+import "doc_tasks.loki"
+
 import "xyzzy.loki"  # An example for the --doctor flag
 
 class Tasks

data/.reek.yml

@@ -75,6 +75,8 @@ detectors:
       - Asgard::Base::Registry#inherited            # inherited(subclass) configuring subclass is the whole point
       - Asgard::Base::DependencyGraph#_normalize_pending_deps # small transform of its own argument
       - Asgard::Base::DependencyGraph#_call_dep_proc          # rescue => e; e.class/e.message is inherent
+      - Asgard::Base::DependencyGraph#_validate_dep_stage!    # pure shape check of its own argument
+      - Asgard::Base::DependencyGraph#_validate_dep_leaf!     # pure shape check of its own argument
       - Asgard::Doctor::TaskSections#class_task_file_map
       - Asgard::Doctor::TaskSections#relative_path
       - Asgard::Doctor::TaskSections#task_status
@@ -104,6 +106,7 @@ detectors:
       - Asgard::Base::DependencyGraph#_build_dep_graph # genuinely pure, but tightly coupled to this graph model
       - Asgard::Base::Dispatch#dep_results             # thread-local by design, not self — that's the whole point
       - Asgard::Base::Dispatch#with_dep_results        # same: stashes results on Thread.current, not self
+      - Asgard::Shell#shell_argv                       # extracted pure on purpose so it's testable without invoking system/exec
 
 exclude_paths:
   - test

data/CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.3.2] - Unreleased
+## [0.3.3] - 2026-08-27
 
 ### Added
 
@@ -159,6 +159,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`examples/bad.loki`** — a worked demonstration of the race the fix above addresses: 4 parallel workers read-modify-write a shared `@hits` counter directly (the anti-pattern `quality.loki` used to have), reliably losing updates. Kept as a contrast example for what `dep_result`/`dep_results` is for.
 
+### Added (continued 5)
+
+- **`sh(script, exec: true)`** — hands the command the asgard process itself via `Kernel.exec` instead of forking. For a task's final, long-running command (a dev server, a REPL) this replaces the ruby process outright, so nothing sits resident in memory behind it and Ctrl-C is handled directly by the command instead of unwinding back through asgard. `doc_tasks.loki`'s `doc_server` task (`sh "mkdocs serve", exec: true`) is the motivating example. See [Shell Helpers](docs/shell.md#handing-off-with-exec).
+- **`bootstrap` and `env_info` tasks in `kitchen_sink.loki`** — demonstrate `sh` with a multi-line heredoc (routed through `bash -c`) and a single-line command, respectively.
+
+### Fixed (continued 3)
+
+- **Ctrl-C during a running `sh` command printed a raw `Interrupt` backtrace** — SIGINT hits the whole foreground process group, so asgard's own ruby process raised `Interrupt` independently of whatever the shelled-out command did with the signal, and it went uncaught, unwinding through Thor and printing a stack trace before exiting. `Asgard.run!` now rescues `Interrupt` and exits with the conventional 130 status.
+
+### Added (continued 6)
+
+- **`depends_on` accepts a block in addition to a Proc/lambda** — `depends_on { ... }` (or `depends_on do ... end` for a block spanning multiple statements) defers resolution to `validate_deps!` exactly like the existing sole-Proc/lambda form; the two are interchangeable. `depends_on` still accepts task arguments *or* a block, never both — combining them raises `Asgard::Error`. See [Dynamic Dependencies](docs/dependencies.md#dynamic-dependencies-proc-block-form).
+- **The resolved Proc/lambda/block result is now shape-validated** — once `validate_deps!` calls it, the return value must be an `Array` of stages, each a `Symbol`/`String` (sequential) or an `Array` of `Symbol`/`String` (parallel group), nested no deeper than that. A bad shape (wrong type, an invalid stage, a non-Symbol/String leaf, or nesting more than one level deep) now raises `Asgard::Error` naming the task and the offending value, instead of failing later with an opaque `NoMethodError`.
+- **`examples/depends_on_block/good/` and `examples/depends_on_block/bad/`** — two self-contained example projects (each its own `.loki` root, isolated from the main `examples/` tree) demonstrating the block form: `good/` covers single-line `{ ... }`, `do...end`, and a mixed sequential+parallel shape; `bad/` demonstrates the double-wrapped-array mistake that the new shape validation catches, with the exact `Asgard::Error` message it produces.
+
 ## [0.2.0] - 2026-05-29
 
 ### Changed

data/README.md

@@ -221,14 +221,28 @@ asgard ci executes:
   ci
 ```
 
-`depends_on` also accepts a `Proc`/lambda instead of a fixed list, resolved once every `.loki` file has finished loading rather than immediately — useful when the list can't be known upfront, e.g. "every task whose name ends in `_check`," discovered across several files:
+`depends_on` also accepts a `Proc`/lambda (or, equivalently, a block) instead of a fixed list, resolved once every `.loki` file has finished loading rather than immediately — useful when the list can't be known upfront, e.g. "every task whose name ends in `_check`," discovered across several files:
 
 ```ruby
 depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
 def quality = puts "running every *_check task..."
+
+depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+def quality2 = puts "same, as a block..."
+
+# do...end for a block spanning multiple statements — braces are for
+# single-line blocks like the two above. The last expression is still what
+# gets returned and validated.
+depends_on do
+  checks = all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)
+  slow   = %i[c_check]
+
+  [checks - slow]
+end
+def quality3 = puts "same, minus the slow checks, as a multi-line block..."
 ```
 
-See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-form) for the full explanation.
+See [Dependencies](https://madbomber.github.io/asgard/dependencies/#dynamic-dependencies-proc-block-form) for the full explanation.
 
 ---
 
@@ -489,6 +503,33 @@ end
 
 ---
 
+## Abbreviated command matching
+
+Every task is a Thor command, so you don't have to type the full name — Thor resolves any unambiguous prefix automatically, with no extra code:
+
+```ruby
+class Tasks
+  desc "Compile the project"
+  def build = sh "rake build"
+
+  desc "Deploy to production"
+  def deploy = sh "cap production deploy"
+
+  desc "Deploy to staging"
+  def deploy_staging = sh "cap staging deploy"
+end
+```
+
+```bash
+asgard b        # same as: asgard build   — only task starting with "b"
+asgard depl     # Ambiguous command depl matches [deploy, deploy_staging]
+asgard deploy   # runs deploy — an exact match always wins, even over a shorter ambiguous prefix
+```
+
+This is Thor's own dispatch behavior, not an Asgard feature — it applies to every task in every `.loki` file automatically. When a prefix matches more than one task, Thor lists the candidates instead of guessing; type enough of the name to disambiguate, or use `map` (below) to pin a short name that stays stable even if a later-added task would otherwise make it ambiguous.
+
+---
+
 ## Command aliases
 
 `map` creates alternative names for a task:

data/doc_tasks.loki

@@ -0,0 +1,21 @@
+# dev/doc_tasks.loki
+
+# TODO: create common tasks for documentation management
+class Tasks
+
+  if File.exist?(ENV['RR']+'/.config/tocer/configuration.yml')
+    desc "Management table of contents"
+    def tocer = sh "tocer help"
+  end
+
+
+  if File.exist?(ENV['RR']+'/mkdocs.yml')
+    desc "Documentation builder"
+    def doc_builder = sh "mkdocs build"
+
+    desc "Documentation server startup"
+    depends_on :doc_builder
+    def doc_server = sh "mkdocs serve", exec: true
+  end
+
+end

data/docs/api.md

@@ -111,12 +111,12 @@ import_up "*.loki"                 # find the nearest ancestor with *.loki files
 
 | Method | Signature | Description |
 |---|---|---|
-| `depends_on` | `depends_on(*tasks)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. A sole `Proc`/lambda defers resolution to `validate_deps!` (after every `.loki` file has loaded) instead of resolving immediately — see [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-form). |
+| `depends_on` | `depends_on(*tasks, &block)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. A sole `Proc`/lambda, or a block in place of the splat args, defers resolution to `validate_deps!` (after every `.loki` file has loaded) instead of resolving immediately — see [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-block-form). Passing both task arguments and a block raises `Asgard::Error`. |
 | `dotenv` | `dotenv(path = ".env")` | Load the specified `.env` file into `ENV` using the dotenv gem. Silently skipped if the file does not exist. Called at class-load time. |
 | `header` | `header(text)` | Append a line of text shown above the commands list in `asgard help`. Each call adds another line. No-op for per-command help. |
 | `footer` | `footer(text)` | Prepend a line of text shown below the options block in `asgard help`. Each call inserts above the previous lines. No-op for per-command help. |
 | `no_negate` | `no_negate(*names)` | Suppress `[--no-name]` / `[--skip-name]` help entries for one or more boolean class options. Call after the `class_option` declaration. |
-| `sh` | `sh(script, silent: false)` | Instance method. Run a shell command or multiline heredoc. Single-line → `system(script)`; multiline → `system("bash", "-c", script)`. Exits with the command's status on failure. |
+| `sh` | `sh(script, silent: false, exec: false)` | Instance method. Run a shell command or multiline heredoc. Single-line → `system(script)`; multiline → `system("bash", "-c", script)`. Exits with the command's status on failure. With `exec: true`, replaces the asgard process via `Kernel.exec` instead of forking — see [Shell Helpers](shell.md#handing-off-with-exec). |
 | `shebang` | `shebang(interpreter, script, silent: false)` | Instance method. Write `script` to a tempfile and execute it with `interpreter`. See the [Shell Helpers](shell.md) page for the full interpreter table. |
 | `validate_deps!` | `Tasks.validate_deps!` | Build and topologically sort the full dependency graph using stdlib `TSort`. Raises `Asgard::CircularDependencyError` on cycles. Called by `run!` at startup. |
 | `_reset_ran!` | `Tasks._reset_ran!` | Clear the per-invocation task deduplication set. Called by `run!` before dispatching. Thread-safe via Mutex. |
@@ -175,12 +175,14 @@ depends_on :clean, :build                  # two sequential deps
 depends_on [:lint, :typecheck]             # lint and typecheck run in parallel
 depends_on :setup, [:lint, :build], :test  # setup, then lint+build concurrently, then test
 
-# A sole Proc/lambda defers resolution to validate_deps!, after every .loki
-# file has loaded — must return the same shape the splat form above would.
+# A sole Proc/lambda (or, equivalently, a block) defers resolution to
+# validate_deps!, after every .loki file has loaded — must return the same
+# shape the splat form above would; the shape is validated when it resolves.
 depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
 ```
 
-See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-form) for the full explanation of the Proc form — why it exists, when it runs, and how errors are reported.
+See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-block-form) for the full explanation of the Proc/block form — why it exists, when it runs, and how errors are reported.
 
 ---
 

data/docs/changelog.md

@@ -22,7 +22,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asg
 - **`asgard tree`** now shows the project header/footer, matching `asgard help`.
 - **`bundler_audit_check` task** — `bundle-audit check --update` against `Gemfile.lock`; `FAIL` on any known vulnerability.
 - **`quality_rails.loki`** — imported only when `Rails` is defined; ships `brakeman_check` as a Rails security-scan example. No wiring needed — `quality` discovers it automatically (see `depends_on` below).
-- **`depends_on` accepts a Proc/lambda**, not just a fixed list — resolved once, in `validate_deps!`, after every `.loki` file has loaded, instead of immediately. Solves "load order matters" for a dependency list that can't be known upfront, e.g. every task ending in `_check` across several files. See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-form).
+- **`depends_on` accepts a Proc/lambda**, not just a fixed list — resolved once, in `validate_deps!`, after every `.loki` file has loaded, instead of immediately. Solves "load order matters" for a dependency list that can't be known upfront, e.g. every task ending in `_check` across several files. See [Dynamic Dependencies](dependencies.md#dynamic-dependencies-proc-block-form).
+- **`depends_on` also accepts a block** — `depends_on { ... }` or `depends_on do ... end`, interchangeable with the Proc/lambda form above. Task arguments and a block can't be combined; doing so raises `Asgard::Error`.
+- **The Proc/lambda/block result is now shape-validated** once resolved — it must be an `Array` of `Symbol`/`String` (sequential) or `Array` of `Symbol`/`String` (parallel group) stages, nested no deeper. A bad shape raises a clear `Asgard::Error` naming the task and the offending value instead of a raw `NoMethodError`. See `examples/depends_on_block/{good,bad}/`.
 
 ### Changed
 

data/docs/dependencies.md

@@ -236,9 +236,9 @@ Because `*.loki` files are loaded alphabetically when `import "*.loki"` is used,
 
 ---
 
-## Dynamic Dependencies (Proc Form)
+## Dynamic Dependencies (Proc / Block Form)
 
-`depends_on` normally takes a fixed list, recorded the moment the `def` right after it is encountered — which is why load order matters, as above. Pass a `Proc` or lambda instead, and that list is computed *later*, after every `.loki` file has finished loading, rather than at the point `depends_on` itself is evaluated:
+`depends_on` normally takes a fixed list, recorded the moment the `def` right after it is encountered — which is why load order matters, as above. Pass a `Proc` or lambda instead — or, equivalently, a block — and that list is computed *later*, after every `.loki` file has finished loading, rather than at the point `depends_on` itself is evaluated:
 
 ```ruby
 depends_on -> { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
@@ -246,22 +246,33 @@ desc "Run every *_check quality gate task in parallel"
 def quality
   # ...
 end
+
+depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
+desc "Same thing, written as a block"
+def quality2
+  # ...
+end
 ```
 
-This solves exactly the "load order matters" problem from the previous section: a plain array can only name tasks that already exist in `.loki` files loaded *before* this one. A Proc is resolved once every file has loaded, so it can safely reference a task defined in a file that hasn't been imported yet at the point `depends_on` is written — including one that only exists conditionally, e.g. a Rails-specific task file imported with `import "quality_rails.loki" if defined?(Rails)`.
+This solves exactly the "load order matters" problem from the previous section: a plain array can only name tasks that already exist in `.loki` files loaded *before* this one. A Proc/block is resolved once every file has loaded, so it can safely reference a task defined in a file that hasn't been imported yet at the point `depends_on` is written — including one that only exists conditionally, e.g. a Rails-specific task file imported with `import "quality_rails.loki" if defined?(Rails)`. `depends_on` accepts task arguments *or* a block, never both — combining them raises `Asgard::Error`.
+
+**Shape:** the Proc/block must return exactly what the plain-array form would receive as its splat arguments — an array of stages, each a `Symbol`/`String` (sequential) or an `Array` of `Symbol`/`String` (parallel group), nested no deeper than that. The example above returns `[[:a_check, :b_check, :c_check]]`: one stage, containing every matching task, all running in parallel — the same shape as `depends_on [:a_check, :b_check, :c_check]`. This shape is validated once the result comes back — a bad return value (wrong type, a stage that isn't a Symbol/String/Array, a leaf inside a parallel group that isn't a Symbol/String, or nesting more than one level deep) raises `Asgard::Error` naming the task and the offending value, instead of failing later with an opaque `NoMethodError`:
 
-**Shape:** the Proc must return exactly what the plain-array form would receive as its splat arguments — an array of stages, each a `Symbol` (sequential) or `Array` (parallel group). The example above returns `[[:a_check, :b_check, :c_check]]`: one stage, containing every matching task, all running in parallel — the same shape as `depends_on [:a_check, :b_check, :c_check]`.
+```bash
+asgard quality
+# asgard: depends_on proc/block for 'quality' returned invalid stage 123 (Integer); expected a Symbol, String, or Array of them
+```
 
-**When it runs:** once, when `validate_deps!` runs (right after the `.loki` chain finishes loading, before any task dispatches). The resolved result replaces the Proc in the dependency table, so cycle detection, undefined-task checks, and arity checks all run against the *resolved* list — a Proc that references an undefined task, or that itself introduces a cycle, is caught at startup exactly like a plain array would be:
+**When it runs:** once, when `validate_deps!` runs (right after the `.loki` chain finishes loading, before any task dispatches). The resolved result replaces the Proc/block in the dependency table, so cycle detection, undefined-task checks, and arity checks all run against the *resolved* list — a Proc/block that references an undefined task, or that itself introduces a cycle, is caught at startup exactly like a plain array would be:
 
 ```bash
 asgard quality
 # asgard: undefined task(s) in depends_on: ghost_check
 ```
 
-**`self` inside the Proc:** since the Proc is written directly in a `class Tasks` body, it lexically captures that class as `self` — so it can call `all_commands`, `_deps`, or any other class-level method bare, without a `self.class.` prefix, even though it's actually invoked later from inside `validate_deps!`.
+**`self` inside the Proc/block:** since it's written directly in a `class Tasks` body, it lexically captures that class as `self` — so it can call `all_commands`, `_deps`, or any other class-level method bare, without a `self.class.` prefix, even though it's actually invoked later from inside `validate_deps!`.
 
-**If the Proc raises**, the error is caught and re-raised as `Asgard::Error` naming the task it was declared for:
+**If the Proc/block raises**, the error is caught and re-raised as `Asgard::Error` naming the task it was declared for:
 
 ```
 asgard: depends_on proc for 'quality' raised RuntimeError: boom

data/docs/shell.md

@@ -2,7 +2,7 @@
 
 Asgard provides two methods for running shell commands and scripts from within task bodies: `sh` for shell commands and heredocs, and `shebang` for polyglot scripts. Both are provided by `Asgard::Shell` and mixed into every `Tasks` instance.
 
-Both methods exit with the command's status code on failure — they do not raise Ruby exceptions.
+Both methods exit with the command's status code on failure — they do not raise Ruby exceptions. `sh` also accepts `exec: true` to replace the asgard process outright instead of forking — see [Handing Off with `exec`](#handing-off-with-exec).
 
 ---
 
@@ -80,6 +80,35 @@ class Tasks
 end
 ```
 
+### Handing Off with `exec`
+
+Pass `exec: true` to hand the command the asgard process itself instead of forking a child. Under the hood this calls `Kernel.exec` rather than `system`, which replaces the running ruby process image with the command — asgard doesn't stick around waiting on it.
+
+Use this for a task's final, long-running command — a dev server, a REPL, anything meant to take over the terminal — so there's no idle ruby process sitting in memory alongside it, and Ctrl-C is handled directly by the command instead of unwinding back through asgard:
+
+```ruby
+class Tasks
+  desc "Documentation server startup"
+  depends_on :doc_builder
+  def doc_server = sh "mkdocs serve", exec: true
+end
+```
+
+Since the process is replaced, nothing after the `sh` call ever runs, and `depends_on` chains upstream of it must already have finished (they have — dependencies run before the task body).
+
+```ruby
+class Tasks
+  desc "Start a REPL — never returns to asgard"
+  def console
+    sh "bundle exec pry", exec: true
+    puts "unreachable"
+  end
+end
+```
+
+!!! note
+    `exec: true` only makes sense for a command meant to run for the lifetime of the process. Don't use it for a step with more work queued after it in the same task.
+
 ---
 
 ## `shebang` — Polyglot Scripts

data/docs/tasks.md

@@ -206,6 +206,46 @@ Without `default_task`, running `asgard` with no arguments displays the help mes
 
 ---
 
+## Abbreviated Command Matching
+
+Every task is a Thor command, and Thor resolves any unambiguous prefix of a command name to that command automatically — no Asgard code involved, and nothing to declare. Given:
+
+```ruby
+class Tasks
+  desc "Check code style with RuboCop"
+  def rubocop_check = sh "bundle exec rubocop"
+
+  desc "Run the test suite"
+  def test_check = sh "bundle exec rake test"
+
+  desc "Run the test suite with verbose output"
+  def test_verbose = sh "bundle exec rake test -v"
+
+  desc "Deploy to production"
+  def deploy = sh "cap production deploy"
+
+  desc "Deploy to staging"
+  def deploy_staging = sh "cap staging deploy"
+end
+```
+
+```bash
+asgard r             # same as: asgard rubocop_check — the only task starting with "r"
+asgard test_c        # same as: asgard test_check     — enough of the name to be unique
+asgard test          # Ambiguous command test matches [test_check, test_verbose]
+asgard deploy        # runs deploy, not deploy_staging — see below
+```
+
+Thor matches on a plain prefix (`command_name.start_with?(typed_string)`), so the shortest string that is still unique for your task set works. Two details worth knowing:
+
+- **An exact full name always wins**, even if it's also a prefix of another task. `asgard deploy` runs `deploy` itself, never the ambiguous-prefix error, because `deploy` is a defined command — not merely a prefix of `deploy_staging`.
+- **An ambiguous prefix produces a clean error listing every candidate** (`Ambiguous command X matches [...]`) rather than guessing or running the alphabetically-first match. Type enough of the name to disambiguate.
+
+!!! tip
+    Because matching depends on every task name currently defined, a short prefix that's unique today can become ambiguous tomorrow when a new task with the same stem is added — e.g. adding `rubocop_fix` alongside `rubocop_check` turns `asgard r` from a clean match into `Ambiguous command r matches [rubocop_check, rubocop_fix]`. Use [`map`](#command-aliases) below for a short name you want to guarantee stays stable regardless of what other tasks get added later.
+
+---
+
 ## Command Aliases
 
 `map` creates short aliases for existing tasks:

data/examples/depends_on_block/bad/.loki

@@ -0,0 +1,51 @@
+# examples/depends_on_block/bad/.loki
+# BAD example: depends_on block returning a mis-shaped result.
+#
+# Compare with ../good/.loki, which does this correctly:
+#
+#   depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
+#     ^                                                                ^
+#     one wrapping [ ] — this is "one stage, containing every matching
+#     task, all running in parallel."
+#
+# It's an easy typo to add a SECOND wrapping array, thinking the outer
+# array is "the list of stages" and the inner one is "this stage's tasks"
+# as two separate concerns:
+#
+#   depends_on { [[all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)]] }
+#                ^                                                        ^
+#                that's one stage too many — the middle array ends up
+#                *inside* a stage as a dependency, not as the stage itself.
+#
+# depends_on's block/Proc result is validated the moment it resolves
+# (during validate_deps!, before any task runs): every stage must be a
+# Symbol/String (sequential) or an Array of Symbol/String (parallel group)
+# — nesting one level deeper than that is rejected with Asgard::Error
+# instead of failing later with a confusing NoMethodError.
+#
+# Run with (from this directory):
+#   asgard quality
+#
+# Expected output (validate_deps! aborts before quality — or any other
+# task — ever runs):
+#   asgard: depends_on proc/block for 'quality' returned invalid dependency
+#   [:a_check, :b_check, :c_check] (Array) in a parallel group; expected a
+#   Symbol or String
+
+class Tasks
+  desc "Run the first check"
+  def a_check = puts "running a_check ..."
+
+  desc "Run the second check"
+  def b_check = puts "running b_check ..."
+
+  desc "Run the third check"
+  def c_check = puts "running c_check ..."
+
+  # BUG: double-wrapped — [[ ... ]] instead of [ ... ]. See comment above.
+  depends_on { [[all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)]] }
+  desc "Run every *_check task in parallel, then report"
+  def quality
+    puts "quality: all *_check tasks passed"
+  end
+end

data/examples/depends_on_block/good/.loki

@@ -0,0 +1,83 @@
+# examples/depends_on_block/good/.loki
+# GOOD example: depends_on with a block instead of a Proc/lambda.
+#
+# A block behaves exactly like `-> { ... }` — it defers resolution to
+# validate_deps! (once, after every .loki file has loaded) instead of
+# resolving the moment depends_on is evaluated. This is the real pattern
+# from this gem's own quality.loki: gather every task whose name ends in
+# `_check`, without having to know their names or load order upfront.
+#
+# The block's return value is validated once it resolves: it must be an
+# Array of stages, each a Symbol/String (sequential) or an Array of
+# Symbol/String (parallel group) — see ../bad/.loki for what happens when
+# that shape is wrong.
+#
+# `{ ... }` braces are used below for the short, single-line blocks (quality,
+# full_cycle) — standard Ruby style reserves `do ... end` for a block that
+# spans multiple statements, shown in smoke further down.
+#
+# Run with (from this directory):
+#   asgard quality
+#
+# Expected output:
+#   running a_check ...
+#   running b_check ...
+#   running c_check ...
+#   quality: all *_check tasks passed
+
+class Tasks
+  desc "Run the first check"
+  def a_check = puts "running a_check ..."
+
+  desc "Run the second check"
+  def b_check = puts "running b_check ..."
+
+  desc "Run the third check"
+  def c_check = puts "running c_check ..."
+
+  # self inside the block is the Tasks class (it's written directly in the
+  # class body), so all_commands can be called bare, with no self.class.
+  # prefix — even though the block itself isn't invoked until later.
+  depends_on { [all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)] }
+  desc "Run every *_check task in parallel, then report"
+  def quality
+    puts "quality: all *_check tasks passed"
+  end
+
+  # A block can also return a mix of sequential Symbols and parallel Arrays,
+  # exactly like the plain splat form: depends_on :setup, [:a_check, :b_check], :teardown
+  desc "Prepare fixtures before the checks run"
+  def setup = puts "setup: fixtures ready"
+
+  desc "Clean up fixtures after the checks run"
+  def teardown = puts "teardown: fixtures removed"
+
+  depends_on { [:setup, %i[a_check b_check], :teardown] }
+  desc "setup, then a_check+b_check in parallel, then teardown"
+  def full_cycle
+    puts "full_cycle: done"
+  end
+
+  # A block spanning multiple statements — local variables, some computation
+  # — reads more naturally as do...end than as one long `{ ... }` line.
+  # Whatever it does along the way, the last expression is still what gets
+  # returned and validated: here, [:setup, Array, :teardown], the same shape
+  # as full_cycle above.
+  #
+  # Gotcha: this block runs during validate_deps!, which happens *before*
+  # Thor parses this invocation's CLI options (see the Entry Point Flow in
+  # CLAUDE.md) — so checking `--verbose`/`--debug` in here would always see
+  # the pre-flag default, never what was actually passed on this run. Keep
+  # depends_on blocks limited to shaping the dependency graph itself.
+  depends_on do
+    all_checks  = all_commands.keys.grep(/_check\z/).sort.map(&:to_sym)
+    slow_checks = %i[c_check]
+    fast_checks = all_checks - slow_checks
+
+    [:setup, fast_checks, :teardown]
+  end
+  desc "setup, then every *_check except the slow ones, then teardown"
+  def smoke
+    puts "smoke: done"
+  end
+end

data/examples/kitchen_sink.loki

@@ -181,6 +181,19 @@ class Tasks
     end
   end
 
+  # ── Asgard: sh — run shell commands, single-line and multi-line heredoc ────
+  desc "Show environment info (single-line sh)"
+  def env_info = sh "echo Running #{@@app_name} on $(uname -s)"
+
+  desc "Bootstrap the local environment (multi-line sh / heredoc)"
+  def bootstrap
+    sh <<~SHELL
+      echo "App:  #{@@app_name}"
+      echo "Ruby: $(ruby -v)"
+      echo "Date: $(date)"
+    SHELL
+  end
+
   # ── Thor: no_commands — public helper excluded from CLI and --help ──────────
   no_commands do
     def current_sha

data/lib/asgard/base/dependency_graph.rb

@@ -17,13 +17,21 @@ module Asgard
       #   depends_on [:build, :lint]                 # build and lint in parallel
       #   depends_on :setup, [:build, :lint], :test  # setup, then build+lint, then test
       #
-      # A sole Proc/lambda defers resolution to validate_deps! (after every
-      # .loki file has loaded), instead of now. It must return the same shape
-      # the splat form above would: an array of stages, each a Symbol
-      # (sequential) or Array (parallel group).
+      # A sole Proc/lambda, or a block in place of the splat args, defers
+      # resolution to validate_deps! (after every .loki file has loaded),
+      # instead of now. It must return the same shape the splat form above
+      # would: an array of stages, each a Symbol (sequential) or Array
+      # (parallel group).
       #
       #   depends_on -> { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
-      def depends_on(*tasks)
+      #   depends_on { [all_commands.keys.grep(/_check\z/).map(&:to_sym)] }
+      def depends_on(*tasks, &block)
+        if block
+          raise Asgard::Error, "depends_on accepts either task arguments or a block, not both" if tasks.any?
+
+          tasks = [block]
+        end
+
         @_pending_deps = tasks
       end
 
@@ -65,7 +73,9 @@ module Asgard
         _deps.each do |task, stages_or_proc|
           next unless stages_or_proc.respond_to?(:call)
 
-          _deps[task] = _stages_from(Array(_call_dep_proc(task, stages_or_proc)))
+          result = Array(_call_dep_proc(task, stages_or_proc))
+          _validate_dep_shape!(task, result)
+          _deps[task] = _stages_from(result)
         end
       end
 
@@ -75,6 +85,32 @@ module Asgard
         raise Asgard::Error, "depends_on proc for '#{task}' raised #{e.class}: #{e.message}"
       end
 
+      # A resolved proc/lambda/block result must be an Array of stages, each
+      # either a Symbol/String (sequential) or an Array of Symbol/String
+      # (parallel group) — no deeper nesting, no other leaf types.
+      def _validate_dep_shape!(task, result)
+        result.each { |stage| _validate_dep_stage!(task, stage) }
+      end
+
+      def _validate_dep_stage!(task, stage)
+        case stage
+        when Symbol, String then nil
+        when Array           then stage.each { |leaf| _validate_dep_leaf!(task, leaf) }
+        else
+          raise Asgard::Error,
+                "depends_on proc/block for '#{task}' returned invalid stage #{stage.inspect} " \
+                "(#{stage.class}); expected a Symbol, String, or Array of them"
+        end
+      end
+
+      def _validate_dep_leaf!(task, leaf)
+        return if leaf.is_a?(Symbol) || leaf.is_a?(String)
+
+        raise Asgard::Error,
+              "depends_on proc/block for '#{task}' returned invalid dependency #{leaf.inspect} " \
+              "(#{leaf.class}) in a parallel group; expected a Symbol or String"
+      end
+
       def _check_orphaned_deps!
         pending = Array(@_pending_deps)
         return unless pending.any?
@@ -107,7 +143,7 @@ module Asgard
       # the order itself isn't otherwise used (execution order comes from the
       # stage groups each task's own depends_on declared).
       def _build_and_sort_graph(all_task_names)
-        full_graph = all_task_names.to_h { |task| [task, _deps.fetch(task, []).flatten] }
+        full_graph = all_task_names.to_h { |task| [task, _deps.fetch(task) { [] }.flatten] }
         Graph.new(full_graph).tsort
       end
 

data/lib/asgard/base/task_dsl.rb

@@ -48,11 +48,10 @@ module Asgard
         here   = caller_locations(1, 1).first if active
 
         if active && @_default_task_location
-          # rubocop:disable Style/StderrPuts -- warn bypasses $stderr in Ruby 4.0, breaking capture_io in tests
+          # rubocop:disable-next 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 active
           @_default_task_location = here

data/lib/asgard/shell.rb

@@ -8,17 +8,21 @@ module Asgard
     # Run a shell script. Multiline strings are passed to bash -c; single-line
     # strings are passed to system directly. Exits with the command's status
     # code on failure.
-    def sh(script, silent: false)
+    #
+    # Pass exec: true to replace the current process instead of forking —
+    # useful for a task's final, long-running command (e.g. a dev server)
+    # so the asgard/ruby process doesn't sit resident in memory alongside it.
+    def sh(script, silent: false, exec: false)
       script = script.strip
       $stdout.puts script unless silent
+      argv = shell_argv(script)
 
-      success = if script.include?("\n")
-                  system("bash", "-c", script)
-                else
-                  system(script)
-                end
-
-      exit($CHILD_STATUS.exitstatus) unless success
+      if exec
+        $stdout.flush
+        Kernel.exec(*argv)
+      else
+        exit($CHILD_STATUS.exitstatus) unless system(*argv)
+      end
     end
 
     # Write +script+ to a tempfile and execute it with +interpreter+.
@@ -42,5 +46,14 @@ module Asgard
         exit($CHILD_STATUS.exitstatus) unless $CHILD_STATUS.success?
       end
     end
+
+    private
+
+    # The argv passed to system/exec for +script+: multi-line scripts run
+    # through `bash -c` so assignments carry across lines; single-line
+    # scripts run directly.
+    def shell_argv(script)
+      script.include?("\n") ? ["bash", "-c", script] : [script]
+    end
   end
 end

data/lib/asgard/version.rb

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

data/lib/asgard.rb

@@ -40,5 +40,7 @@ module Asgard
     abort "asgard: circular dependency — #{e.message}"
   rescue Error => e
     abort "asgard: #{e.message}"
+  rescue Interrupt
+    exit(130)
   end
 end

data/quality_rails.loki

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
-# Rails-specific quality gate tasks — imported by .loki only when the Rails
-# constant is defined.
+# Rails-specific quality gate tasks — imported by .loki only when RAILS_ROOT
+# is set. asgard runs as a separate process outside the app it's checking,
+# so `defined?(Rails)` never sees the app's Rails constant.
 #
 # `quality` (in quality.loki) discovers every *_check task at run time by
 # introspecting Tasks.all_commands, rather than a fixed depends_on list — so

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asgard
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -62,6 +62,7 @@ files:
 - bin/asgard
 - bin/console
 - bin/setup
+- doc_tasks.loki
 - docs/api.md
 - docs/assets/css/custom.css
 - docs/assets/images/asgard.jpg
@@ -83,6 +84,8 @@ files:
 - examples/bad.loki
 - examples/concurrent.loki
 - examples/db_subcommands.loki
+- examples/depends_on_block/bad/.loki
+- examples/depends_on_block/good/.loki
 - examples/env_usage.loki
 - examples/kitchen_sink.loki
 - examples/server_subcommands.loki