asgard 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e81b8d0d4ce7904a7483a06348d488730f258171af1d0d6897a99fc058829d91
-  data.tar.gz: a25c7c2dccc05df8ac533a17a118f93361aa8eabbb6ad8fde36af65088107cb2
+  metadata.gz: 299e2b451fc4acf80bf87970012a5fea712bf7f2efc4103465355d091d2b1282
+  data.tar.gz: e9dc3f90d5abaaac9b735e2b92a35296b5956bc0e261526244aff5d1ba500a8e
 SHA512:
-  metadata.gz: ee9be83865e0fa5a50e5fac52e6d720e7d76b3da4f56790d8badb708a93d603d30628c5a960f1aca209f030f89b34c726f151caa3b6c337be4e69b1c00c15fb1
-  data.tar.gz: 9741a4dcac57f091e00a5f6b84f1cd70d5c5e9c04b2059a8483edbb17166fca17762d38d6161eea6fd294e09fcc129394fce88c58c53a7d240d1eb664ca5d750
+  metadata.gz: 5279427ba559b0067881a8e828642222c3189b002c01dbeb409f69bfe39a018e7288a088125ea29b56d71f8a16370965ed4bea03a9328be9ef6c29b7a4c5d3af
+  data.tar.gz: cf33a3581b2fceeec5baf59d8fe42505c3d29e9d7f0717e5b81110208c1f9aa339883e06a1c5e9bc29487eba13e4f63ab37d509e48d03285a0ef90a20a64fcb1

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.5.0] - Unreleased
+## [0.5.1] - 2026-10-19
 
 ### Added
 
@@ -31,6 +31,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `empty?`); every list is empty when the task is run by hand.
 - **`Asgard::Watch::Error`** (subclass of `Asgard::Error`) — raised when a
   `watch` names a task the project does not define.
+- **`examples/do.loki`** — `asgard do lint test build` runs tasks in
+  sequence, with comma-separated steps for arguments and options
+  (`asgard do hello Alice, farewell Bob --formal`). A plain user task, not
+  a built-in; it stops at the first failure.
+- **`examples/confirm.loki`** — a hidden `confirm` task to list first in a
+  dangerous task's `depends_on`; answering anything but y/yes aborts with
+  exit 1. Refuses without a terminal unless `ASGARD_YES` is set.
 
 ### Changed
 
@@ -43,6 +50,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Asgard.machine_wide?` is true for `watcher list` as well as
   `schedule list`, so both work from a directory with no `.loki` above it.
 
+### Fixed
+
+- **Usage errors exit 1** — a missing argument, an unknown command, or a bad
+  subcommand (`asgard greet` with no NAME, `asgard nope`) printed Thor's
+  error but exited 0, so CI and scripts saw success. `Asgard::Base` now
+  defines `exit_on_failure?` as true.
+
 ## [0.4.1] - 2026-10-02
 
 ### Added

data/docs/examples.md

@@ -130,6 +130,58 @@ This example is also useful as a test harness for verifying that parallel execut
 
 ---
 
+## `do.loki`
+
+**Path:** `examples/do.loki`
+
+A plain user task that runs other tasks in sequence, the way `rake a b c` or `just a b c` does. No gem changes needed:
+
+- Steps are comma-separated, so each step can carry its own arguments and options; with no commas, every word is a task of its own
+- Each step is parsed by Thor as if it were typed on the command line
+- The sequence stops at the first failure (a failing `sh`, or a step returning `:fail`)
+
+```bash
+asgard do greet finish
+asgard do hello Alice, farewell Bob --formal
+# Hello, Alice!
+# Goodbye, Bob.
+```
+
+!!! note
+    Every task runs at most once per `asgard` invocation, so `asgard do hello Alice, hello Bob` greets only Alice. The same rule makes a dependency shared by several steps run once.
+
+---
+
+## `confirm.loki`
+
+**Path:** `examples/confirm.loki`
+
+A guard task. List `confirm` first in a dangerous task's `depends_on`, and the task runs only after the user answers yes:
+
+```ruby
+depends_on :confirm
+desc "Drop and recreate the database"
+def reset_database = sh "bin/rails db:reset"
+```
+
+```bash
+asgard reset_database
+# Really run `asgard reset_database`? [y/N] n
+# asgard: aborted `asgard reset_database`      (exit 1)
+
+ASGARD_YES=1 asgard reset_database             # no question, for scripts and CI
+```
+
+- Answering no **raises** `Asgard::Error`, which stops the dependent task. Returning `:fail` would not: a dependency's return value never stops the task that depends on it
+- A dependency doesn't know which task asked for it, so the question shows the whole command line
+- With no terminal (a schedule, the watcher, a pipe) it refuses unless `ASGARD_YES` is set
+- `confirm` is declared with `hide: true`, so it stays out of `asgard help`
+
+!!! note
+    `confirm` runs at most once per `asgard` invocation, so `asgard do reset_database, drop_cache` asks once for the whole line. Keep it in its own first stage: in `depends_on [:confirm, :backup]`, `backup` runs while the question waits.
+
+---
+
 ## Summary
 
 | File | Primary Focus |
@@ -138,3 +190,5 @@ This example is also useful as a test harness for verifying that parallel execut
 | `server_subcommands.loki` | Subcommand groups, per-command options, depends_on in subcommands |
 | `db_subcommands.loki` | Multi-step depends_on chains, enum validation, long_desc in subcommands |
 | `concurrent.loki` | Parallel task execution, thread concurrency demonstration |
+| `do.loki` | Running several tasks in sequence from one command line |
+| `confirm.loki` | A guard dependency that asks before a dangerous task runs |

data/examples/confirm.loki

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# Demonstrates a guard task: list `confirm` first in a dangerous task's
+# depends_on and the task only runs after the user answers yes.
+#
+# Run with:
+#   asgard reset_database                  # asks, runs only on y/yes
+#   ASGARD_YES=1 asgard reset_database     # no question (scripts, CI)
+#
+# Behavior:
+#   - A dependency doesn't know which task asked for it, so the question
+#     shows the whole command line: "Really run `asgard reset_database`?"
+#   - Answering no raises Asgard::Error, which stops everything that
+#     hasn't run yet; asgard prints "asgard: aborted ..." and exits 1.
+#     Returning :fail would NOT work: a dependency's return value never
+#     stops the task that depends on it.
+#   - With no terminal to ask (a schedule, the watcher, a pipe) it refuses
+#     unless ASGARD_YES is set, rather than hanging or guessing.
+#   - It runs at most once per asgard invocation, so
+#     `asgard do reset_database, drop_cache` asks once for the whole line.
+#   - Put confirm in its own first stage. In a parallel group,
+#     `depends_on [:confirm, :backup]`, backup runs while the question waits.
+
+class Tasks
+  # Not a Thor command (a class method), so it can be tested on its own:
+  #   Tasks.confirmed?("y", yes_env: nil) #=> true
+  def self.confirmed?(answer, yes_env:)
+    return true if yes_env && !yes_env.empty?
+
+    %w[y yes].include?(answer.to_s.strip.downcase)
+  end
+
+  desc "Ask before running the task that depends on this", hide: true
+  def confirm
+    command = "asgard #{ARGV.join(' ')}"
+    yes_env = env(:asgard_yes, "")
+    return if self.class.confirmed?(nil, yes_env:)
+    raise Asgard::Error, "refusing `#{command}`: no terminal to confirm on (set ASGARD_YES=1)" unless $stdin.tty?
+
+    answer = ask("Really run `#{command}`? [y/N]")
+    raise Asgard::Error, "aborted `#{command}`" unless self.class.confirmed?(answer, yes_env:)
+  end
+
+  depends_on :confirm
+  desc "Pretend to drop and recreate the database (demo for confirm)"
+  def reset_database
+    puts "Database reset."
+  end
+end

data/examples/do.loki

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# Demonstrates a plain user task that runs other tasks in sequence — the
+# `rake a b c` / `just a b c` style, which Thor's one-command dispatch
+# doesn't offer on its own.
+#
+# Steps are comma-separated so a step can carry its own arguments and
+# options; with no commas, every word is a task of its own.
+#
+# Run with:
+#   asgard do greet finish
+#   asgard do hello Alice, farewell Bob --formal, finish
+#
+# Behavior:
+#   - Each step is parsed by Thor exactly as if typed on the command line,
+#     so its arguments and options work as usual.
+#   - The sequence stops at the first failure: a failing `sh` exits the
+#     process, and a step returning :fail makes `do` return :fail (exit 1).
+#   - Every task runs at most once per asgard invocation, so
+#     `asgard do hello Alice, hello Bob` greets only Alice, and a dependency
+#     shared by several steps runs once.
+
+require "shellwords"
+
+class Tasks
+  # Not a Thor command (a class method), so it can be tested on its own:
+  #   Tasks.do_steps("lint, hello Alice") #=> [["lint"], ["hello", "Alice"]]
+  def self.do_steps(line)
+    line.include?(",") ? line.split(",").map { |step| Shellwords.split(step) }.reject(&:empty?)
+                       : Shellwords.split(line).map { |word| [word] }
+  end
+
+  desc "do STEPS...", "Run several tasks in sequence, e.g. `asgard do hello Alice, farewell Bob --formal`"
+  stop_on_unknown_option! :do
+  def do(*words)
+    steps = self.class.do_steps(words.join(" "))
+    raise Asgard::Error, "do: no tasks given" if steps.empty?
+
+    steps.each do |name, *args|
+      raise Asgard::Error, "do: unknown task '#{name}'" if name == "do" || !self.class.all_commands.key?(name)
+      # dispatch with nil options is what Tasks.start does: Thor parses this
+      # step's argv itself. (invoke would reuse the options parsed for `do`.)
+      return :fail if self.class.send(:dispatch, nil, [name, *args], nil, shell: shell) == :fail
+    end
+  end
+end

data/lib/asgard/base.rb

@@ -18,6 +18,10 @@ module Asgard
     include Dispatch
 
     class << self
+      # A usage error (missing argument, unknown command or option) exits 1,
+      # so CI and `asgard do` sequences see the failure. Thor's default is 0.
+      def exit_on_failure? = true
+
       def header(text = nil)
         return @_header if text.nil?
         (@_header ||= []) << text

data/lib/asgard/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asgard
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -129,9 +129,11 @@ files:
 - examples/.loki
 - examples/bad.loki
 - examples/concurrent.loki
+- examples/confirm.loki
 - examples/db_subcommands.loki
 - examples/depends_on_block/bad/.loki
 - examples/depends_on_block/good/.loki
+- examples/do.loki
 - examples/env_usage.loki
 - examples/kitchen_sink.loki
 - examples/server_subcommands.loki