asgard 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6045b69a572bacdc07c1ae149f2978000fb690c180cf536512caf4714345317
-  data.tar.gz: defa5899f4e66143fe3118d835c60f128534075d2ce4a41652a0bbf54f61e790
+  metadata.gz: d5752f0e0d294dfb08b809b62b0fbcb4d26f281c6c6a9ddc4ca2b9ae9c310cfc
+  data.tar.gz: 918cbb04f6b285b0d96f674b963cd98c899f151159a73e8ccba72824c8c485f5
 SHA512:
-  metadata.gz: 8d27eb2c214be342a64561c8f2287cd05aa48a30e411676dbd69b20f36ec9b706456d7c805c3bfa3a4b64897b8f79831a0a55b96c38b77e3981de551c8737750
-  data.tar.gz: 6bbd01f8c90195fc9b7428dbe7b56721a70d9ffe4b881853497df84c68db7d96400cb279ab9006ff3b6841ab85bd5f54d6838f3d887469331dbe04873bd5dca5
+  metadata.gz: d4a32a84315d0367316ea813f5106d55e54c465f8d1ff1ca6958955fd8c23153483a0002a5396af63ad980ec37dacba6c2b3b311516901ff6bd0dc8ecd4dea37
+  data.tar.gz: 87b809a6e2900d22bec4cff5d9b133a4620bf6c2972312c02243bea916aa6cc01dcf668c3ea80786d710ddf39e7e5c3b773d35ec27577253b131a2e0463e1b39

data/.loki

@@ -2,33 +2,22 @@
 # Asgard gem's own task file.
 # Task is pre-defined by the gem — just reopen it to add tasks.
 
-class Tasks
-  @@gem_name ||= "asgard".freeze
-
-  desc "Run the test suite"
-  def test
-    sh "bundle exec rake test"
-  end
+import "quality.loki"
+import "gem_tasks.loki"
 
-  desc "Run all quality gates (tests, RuboCop, Flog)"
-  def quality
-    sh "bundle exec rake quality"
-  end
+class Tasks
+  @@project      ||= "asgard".freeze
+  @@project_desc ||= "CLI-task runner"
 
-  desc "Build the gem package"
-  def build
-    sh "bundle exec rake build"
+  helper(:project_version) do
+    @@project_version ||= File.read("lib/#{@@project}/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
   end
 
-  depends_on :test
-  desc "Build and install gem locally"
-  def install
-    sh "bundle exec rake install"
-  end
+  default_task :quality
 
-  depends_on :quality
-  desc "Release to RubyGems"
-  def release
-    sh "bundle exec rake release"
-  end
+  header <<~HEAD
+    Porject:  #{@@project} (v#{project_version}) - #{@@project_desc}
+    Root Dir: #{loki_up.parent}
+    Default task: #{default_task}
+  HEAD
 end

data/CHANGELOG.md

@@ -5,10 +5,50 @@ 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.0] - Unreleased
+## [0.3.1] - Unreleased
 
 ### Added
 
+- **`helper(name, &block)` DSL method on `Asgard::Base`** — defines a method available in both class context (e.g. inside `header` or `footer`) and as a private instance method inside task bodies, with a single declaration. Eliminates the manual `def self.name` + `no_commands { private def name = self.class.name }` boilerplate. Supports positional arguments, keyword arguments, default values, and block arguments.
+  ```ruby
+  class Tasks
+    @@project ||= "myapp".freeze
+
+    helper(:version) {
+      File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+    }
+
+    header "#{@@project} v#{version}"   # class context
+
+    desc "Show the current version"
+    def show_version = puts version     # instance context
+  end
+  ```
+
+- **`header(text)` and `footer(text)` DSL methods on `Asgard::Base`** — attach static text to the general help output. `header` lines are printed above the commands list; `footer` lines are printed below the options block. Multiple calls accumulate: each `header` call appends a line, each `footer` call prepends a line, so content from later-loaded files naturally wraps around content from earlier files. Neither appears when `asgard help <command>` is called for per-command detail.
+  ```ruby
+  class Tasks
+    header "my-project — build & release tasks"
+    footer "See https://example.com/docs for details"
+  end
+  ```
+- **`no_negate(*names)` DSL method on `Asgard::Base`** — suppresses the `[--no-name]` and `[--skip-name]` negation variants from help output for boolean class options where negation is meaningless. Call it after the `class_option` declaration:
+  ```ruby
+  class_option :version, type: :boolean, default: false, desc: "Show version and exit"
+  no_negate :version
+  ```
+
+### Changed
+
+- **`--version` reimplemented as a `class_option`** — the flag now appears in the "Options" section of `asgard help` alongside `--debug` and `--verbose`, rather than as a listed command. The `_version` method and its `map "--version" => :_version` registration have been removed. The actual early-exit behaviour still lives in `Asgard.run!` (before the `.loki` file is required), so `--version` works even when no `.loki` file exists. `no_negate :version` suppresses the spurious `[--no-version]` / `[--skip-version]` variants.
+- **`loki_up` returns `Pathname` instead of `String`** — the return value is now a `Pathname` instance (or `nil` when not found). `Pathname` is accepted everywhere `loki_up`'s result is used: `import`, `dotenv`, `load`, and standard Ruby file methods all accept `Pathname` via `to_path` / `to_s`. Code that passes the result directly to those methods is unaffected; code that performs string operations on the path should call `.to_s` first.
+
+### Fixed
+
+- **Help output showed `tasks` prefix before every command** — `asgard help` displayed `asgard tasks build` instead of `asgard build`. The cause was a keyword-vs-positional mismatch in the `Asgard::Base#help` override: declaring `subcommand: false` as a keyword argument caused Ruby's `super` to forward it as the hash `{subcommand: false}`. Thor's `banner` method received this hash as the positional `subcommand` argument, treated it as truthy, and prepended the class namespace (`tasks`) to every command name. Fixed by changing the override signature to match Thor's positional signature: `def help(command = nil, subcommand = false)`.
+
+### Added (continued)
+
 - **`loki_up(name = ".loki")` Kernel method** — searches `Dir.pwd` and each ancestor directory for a file with the given name; returns the absolute path of the first match or `nil`. Available everywhere in Ruby (task bodies, `.loki` files, top-level code) as a `module_function` on `Kernel`.
 - **`import(path)` Kernel method** — loads a `.loki` file (or a glob of `.loki` files) with `require`-like idempotency via `$LOADED_FEATURES`. Accepts a `String` or `Pathname`. Relative paths are resolved relative to the caller's file (like `require_relative`). Glob patterns (`*.loki`, `**/*.loki`) expand via `Dir.glob` and load all matches. Returns `true` if any file was newly loaded, `false` if all were already loaded or no glob matches were found. Raises `ArgumentError` if the path does not end with `.loki`.
 - **`import_up(name = ".loki")` Kernel method** — combines `loki_up` and `import`. For exact names, finds the first ancestor directory containing that file and loads it. For glob names, finds the first ancestor directory containing any matching files and loads them all — stopping at that level rather than aggregating across multiple ancestors. Returns `false` if nothing is found.
@@ -16,7 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`env(name, default = nil)` Kernel method** — fetches a system environment variable by symbol or string name, upcasing the key automatically. `env(:port, "3000")` returns `"3000"` when `PORT` is unset; `env(:api_key)` raises `KeyError` when `API_KEY` is missing and no default is provided. Accepts both `env(:port)` and `env("PORT")` forms. Cleaner than `ENV['PORT']` in task bodies.
 - **Verbose/debug feedback for `import` and `import_up`** — when `verbose?` is true, each file loaded is printed to stderr. When `debug?` is true, already-loaded files are also reported (with an "already loaded" suffix), and `import_up` reports when a file is not found.
 - **RuboCop lint gate** — RuboCop is now a first-class quality gate alongside tests and Flog. Added `rubocop` to the Gemfile, a `.rubocop.yml` tuned for this codebase (Ruby 3.2 target, relaxed `Metrics` thresholds consistent with Flog as the primary complexity gate, `examples/` excluded), and `rake rubocop` / `rake rubocop_fix` tasks backed by a `tmp/rubocop_cache` directory for fast re-runs.
-- **Expanded `rake quality` task** — `quality` now runs three independent gates (tests + coverage, RuboCop, Flog) and prints a formatted pass/fail summary table after all gates complete, so every failure is visible in a single run rather than stopping at the first.
+- **Expanded `rake quality` task** — `quality` now runs three independent gates (tests + coverage, RuboCop, Flog) in parallel using `depends_on [:test, :rubocop, :flog_check]`. Each gate captures its pass/fail result in an instance variable; output is suppressed on pass and filtered to failures only on fail, preventing interleaved output from concurrent subprocesses. A formatted pass/fail summary table is printed after all gates complete, so every failure is visible in a single run.
 - **`rake flog_check` task** — replaces the bare `flog lib/` call with a structured task that enforces per-method thresholds (warn ≥20, fail ≥50), lists warnings and failures in separate sections, and exits non-zero only when the failure threshold is breached.
 - **Single-argument `desc` shorthand** — `desc` now accepts one string (the description) with the usage string omitted. The usage defaults to the method name, eliminating the redundant first argument for the common case:
   ```ruby

data/README.md

@@ -18,11 +18,12 @@
 - <strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads<br>
 - <strong>Subcommands</strong> — group related tasks under a named namespace<br>
 - <strong>Variables</strong> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands<br>
+- <strong>`helper` DSL</strong> — define a method once, available in both class-level DSL calls (<code>header</code>) and inside task instance methods<br>
 - <strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts<br>
 - <strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code><br>
 - <strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories<br>
 - <strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded via <code>import</code> from your <code>.loki</code><br>
-- <strong>Built-in Flags</strong> — <code>--debug</code> and <code>--verbose</code> available on every task; <code>--version</code> at the top level<br>
+- <strong>Built-in Flags</strong> — <code>--debug</code>, <code>--verbose</code>, and <code>--version</code> built-in class options; header/footer DSL for static help text<br>
 </td>
 </tr>
 </table>
@@ -274,6 +275,40 @@ class Tasks
 end
 ```
 
+### The `helper` DSL method
+
+Some values need to be available in both class context (e.g. inside `header`) and inside task instance methods. `helper` defines the method once in both contexts:
+
+```ruby
+class Tasks
+  @@project ||= "myapp".freeze
+
+  helper(:version) {
+    File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+  }
+
+  header "#{@@project} v#{version}"   # class context
+
+  desc "Show the current version"
+  def show_version
+    puts version                        # instance context
+  end
+end
+```
+
+Without `helper`, achieving this requires two separate definitions:
+
+```ruby
+def self.version = File.read(...).match(...)[1].freeze
+no_commands { private def version = self.class.version }
+```
+
+`helper` accepts positional arguments, keyword arguments, and blocks — any signature valid in a Ruby method definition:
+
+```ruby
+helper(:tag) { |name, ver, prefix: "v"| "#{prefix}#{name}-#{ver}" }
+```
+
 Helpers can also be shared across multiple `.loki` files by extracting them into a plain Ruby file and loading it explicitly:
 
 ```ruby
@@ -299,6 +334,53 @@ end
 
 ---
 
+## Help header and footer
+
+Add static text above and below the command list in `asgard help` output:
+
+```ruby
+class Tasks
+  header "my-project — build & release tasks"
+  footer "See https://example.com/docs for details"
+end
+```
+
+Multiple calls accumulate. `header` appends each line (top to bottom); `footer` prepends each line (bottom to top), so content from a later-loaded `.loki` file sits closer to the commands:
+
+```ruby
+# .loki
+class Tasks
+  header "my-project"
+  footer "Maintainer: you@example.com"
+end
+
+import "*.loki"
+
+# deploy.loki
+class Tasks
+  header "  deploy targets: staging, production"
+  footer "See runbook at wiki/deploy"
+end
+```
+
+```
+my-project
+  deploy targets: staging, production
+
+Commands:
+  ...
+
+Options:
+  ...
+
+See runbook at wiki/deploy
+Maintainer: you@example.com
+```
+
+Header and footer text is only shown for the general `asgard help` page, not for `asgard help <command>`.
+
+---
+
 ## Options shared across all tasks
 
 `class_option` defines an option available to every task in the class:
@@ -566,7 +648,7 @@ end
 | Method | Description |
 |---|---|
 | `Asgard.run!(argv)` | Entry point — finds `.loki`, loads task files, starts CLI |
-| `Asgard.find_task_file` | Returns path to `.loki` searching from CWD upward, or nil |
+| `Asgard.find_task_file` | Returns a `Pathname` to `.loki` searching from CWD upward, or `nil` |
 
 `run!` handles its own errors — a missing `.loki`, a circular dependency, or a `depends_on` that names a task that doesn't exist all produce a clean one-line message and exit 1.
 

data/docs/api.md

@@ -11,7 +11,7 @@ These class methods are defined on the `Asgard` module itself.
 | Method | Signature | Description |
 |---|---|---|
 | `run!` | `Asgard.run!(argv)` | Main entry point. Finds `.loki`, loads all task files, validates the dependency graph, and dispatches via Thor. Handles its own errors: missing `.loki` and circular dependencies both produce a clean one-line message and `exit 1`. |
-| `find_task_file` | `Asgard.find_task_file → String, nil` | Searches `Dir.pwd` and each ancestor directory for a `.loki` file. Returns the absolute path string of the first match, or `nil` if none is found. |
+| `find_task_file` | `Asgard.find_task_file → Pathname, nil` | Searches `Dir.pwd` and each ancestor directory for a `.loki` file. Returns a `Pathname` of the first match, or `nil` if none is found. |
 
 ### `run!` Details
 
@@ -35,7 +35,7 @@ These methods are defined as `module_function` on `Kernel` and are therefore ava
 
 | Method | Signature | Returns | Description |
 |---|---|---|---|
-| `loki_up` | `loki_up(name = ".loki") → String, nil` | Absolute path or `nil` | Searches `Dir.pwd` and each ancestor directory for a file named `name`. Returns the first match's absolute path, or `nil` if not found. Exact filenames only — does not expand globs. |
+| `loki_up` | `loki_up(name = ".loki") → Pathname, nil` | `Pathname` or `nil` | Searches `Dir.pwd` and each ancestor directory for a file named `name`. Returns a `Pathname` for the first match, or `nil` if not found. Exact filenames only — does not expand globs. |
 | `import` | `import(path) → true, false` | `true` if any file newly loaded | Loads one `.loki` file or a glob of `.loki` files. Relative paths resolve relative to the caller's file (like `require_relative`). Idempotent via `$LOADED_FEATURES`. Raises `ArgumentError` if `path` does not end with `.loki`. Raises `LoadError` if a non-glob path does not exist. |
 | `import_up` | `import_up(name = ".loki") → true, false` | `true` if any file newly loaded | Combines `loki_up` and `import`. Walks ancestors to find the file or glob match, then loads it. Returns `false` if nothing is found. |
 | `debug?` | `debug? → true, false` | `$DEBUG` | Returns the current value of `$DEBUG`. Set to `true` by `--debug` on the CLI or directly via `$DEBUG = true`. |
@@ -53,11 +53,11 @@ loki_up(".env")               # find the nearest .env file up the tree
 loki_up("VERSION")            # find a VERSION file in CWD or any ancestor
 ```
 
-Returns an absolute path string or `nil`. Does not load the file.
+Returns a `Pathname` or `nil`. Does not load the file. `Pathname` is accepted by `import`, `dotenv`, `load`, and standard Ruby file methods — no `.to_s` conversion needed in common usage.
 
 ```ruby
 if (path = loki_up("gem_tasks.loki"))
-  import path
+  import path          # Pathname accepted directly
 end
 
 # Pass the located .env to dotenv — works from any subdirectory
@@ -113,6 +113,9 @@ import_up "*.loki"                 # find the nearest ancestor with *.loki files
 |---|---|---|
 | `depends_on` | `depends_on(*tasks)` | Declare prerequisites for the next `def`. Bare symbols run sequentially; arrays within the splat run as a parallel group. |
 | `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. |
 | `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 Dagwood. Raises `Asgard::CircularDependencyError` on cycles. Called by `run!` at startup. |
@@ -137,7 +140,7 @@ depends_on :setup, [:lint, :build], :test  # setup, then lint+build concurrently
 |---|---|---|
 | `class_option :debug` | class option | `--debug` flag. Sets `$DEBUG = true` before any task runs. Boolean, default `false`. |
 | `class_option :verbose` | class option | `--verbose` flag. Sets `$VERBOSE = true` before any task runs. Boolean, default `false`. |
-| `_version` | private task method | Implements `--version`. Prints `Asgard::VERSION` and exits. Registered via `map "--version" => :_version`. Uses `_` prefix convention. |
+| `class_option :version` | class option | `--version` flag. Handled by `Asgard.run!` before the `.loki` file is loaded — prints `Asgard::VERSION` and exits. `no_negate :version` suppresses the `[--no-version]` / `[--skip-version]` help entries. |
 | `debug?` | Kernel module function | Returns `$DEBUG`. Available everywhere via `Kernel`. |
 | `verbose?` | Kernel module function | Returns `$VERBOSE`. Available everywhere via `Kernel`. |
 

data/docs/changelog.md

@@ -8,6 +8,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Asg
 
 ## [Unreleased]
 
+### Added
+
+- **`helper` DSL method** — defines a method available in both class context (e.g. inside `header`) and instance context (inside task methods) with a single declaration. Eliminates the manual `def self.name` + `no_commands { private def name = self.class.name }` boilerplate. Supports positional arguments, keyword arguments, and block arguments. See [Helper Methods](helpers.md).
+
+### Changed
+
+- **`quality` task** — all three gates (`test`, `rubocop`, `flog_check`) now run in parallel. Each gate captures its own pass/fail result; output is suppressed on pass and filtered to failures only on fail. A summary table is printed after all gates complete.
+
 ### Removed
 
 - **`var` DSL method** — replaced by native Ruby class variables. Use `@@name ||= "value".freeze` in the class body. Class variables are visible in all task instance methods and in subcommand subclasses, making them the correct tool for shared configuration in a Thor-based task runner. See [Variables](variables.md).

data/docs/helpers.md

@@ -75,6 +75,90 @@ end
 
 ---
 
+## The `helper` DSL Method
+
+`helper` is an Asgard DSL method that defines a helper available in **both class context and instance context** with a single declaration. It is the right tool when a value needs to be used inside a `header` or `footer` call (which execute at class load time) and also inside task instance methods.
+
+### The problem it solves
+
+Thor task methods run as instance methods. Class-level DSL calls like `header` and `footer` run as class methods. A plain `def` only creates an instance method, so it cannot be called inside `header`. Conversely, `def self.name` only creates a class method, so it cannot be called inside a task body without `self.class.name`.
+
+The manual workaround is verbose:
+
+```ruby
+class Tasks
+  @@project ||= "myapp".freeze
+
+  # class method for header/footer
+  def self.version
+    @@version ||= File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+  end
+
+  # private instance method delegating to the class method
+  no_commands do
+    private def version = self.class.version
+  end
+
+  header "#{@@project} v#{version}"
+
+  desc "Show version"
+  def show_version = puts version
+end
+```
+
+`helper` replaces those six lines with one:
+
+```ruby
+class Tasks
+  @@project ||= "myapp".freeze
+
+  helper(:version) {
+    @@version ||= File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
+  }
+
+  header "#{@@project} v#{version}"
+
+  desc "Show version"
+  def show_version = puts version
+end
+```
+
+### Arguments
+
+`helper` supports any argument signature valid in a Ruby method definition: positional, keyword, default values, and blocks.
+
+```ruby
+# No arguments
+helper(:project_root) { loki_up.parent.to_s }
+
+# Positional arguments
+helper(:gem_path) { |name| "lib/#{name}/version.rb" }
+
+# Positional with default
+helper(:tag_prefix) { |sep = "-"| "#{@@project}#{sep}" }
+
+# Positional and keyword arguments
+helper(:format_version) { |name, version, prefix: "v", separator: "-"|
+  "#{prefix}#{name}#{separator}#{version}"
+}
+```
+
+Wrong argument counts or unknown keyword names raise the same `ArgumentError` Ruby raises for any method call — no special error handling needed.
+
+### Visibility
+
+`helper`-defined methods are:
+
+- **Excluded from `asgard help`** — they never appear as commands
+- **Blocked from CLI invocation** — cannot be called directly from the command line
+- **Private on the instance side** — not accessible from outside the class
+
+### When to use `helper`
+
+Use `helper` when the value or computation must be available in both a class-level DSL call (`header`, `footer`, a `@@var` initializer) and inside task instance methods. For helpers that are only needed inside task bodies, a plain `private` method is simpler.
+
+---
+
 ## Choosing Between `private` and `no_commands`
 
 | | `private` | `no_commands` |

data/docs/options.md

@@ -71,19 +71,53 @@ end
 
 Both `deploy` and `migrate` automatically accept `--dry-run` and `--env`.
 
+### Boolean class options and `no_negate`
+
+Thor automatically generates `[--no-name]` and `[--skip-name]` help entries alongside every boolean `class_option`. When negation is meaningful — `--dry-run` paired with `--no-dry-run` — this is useful. When negation is meaningless, call `no_negate` immediately after the declaration to remove the extra variants from the help output:
+
+```ruby
+class Tasks
+  class_option :color,
+               type:    :boolean,
+               default: true,
+               desc:    "Colorise output"
+  no_negate :color
+end
+```
+
+Help output before `no_negate`:
+
+```
+[--color], [--no-color], [--skip-color]  # Colorise output
+```
+
+Help output after `no_negate`:
+
+```
+[--color]                                # Colorise output
+```
+
+`no_negate` accepts multiple option names in a single call:
+
+```ruby
+no_negate :color, :version, :emoji
+```
+
+It has no effect on runtime behaviour — `--no-color` still works on the CLI; only the help display is affected.
+
 ---
 
 ## Built-in Flags
 
-`Tasks` ships with three built-in class options and a version flag:
+`Tasks` ships with three built-in `class_option` declarations — `--debug`, `--verbose`, and `--version` — all visible in the Options section of `asgard help`.
 
 ### `--version`
 
-Prints `Asgard::VERSION` and exits. Implemented as the `_version` method with the `_` prefix convention (gem-owned, blocked from direct CLI invocation):
+A `class_option :version` of type `:boolean`. Prints `Asgard::VERSION` and exits. Handled by `Asgard.run!` before the `.loki` file is loaded, so it works even in a directory without a `.loki` file. `no_negate :version` suppresses the `[--no-version]` / `[--skip-version]` variants (see [Boolean class options and `no_negate`](#boolean-class-options-and-no_negate) above):
 
 ```bash
 asgard --version
-# 0.1.2
+# 0.3.0
 ```
 
 ### `--debug`
@@ -173,8 +207,8 @@ asgard deploy production --verbose
 Methods whose names start with `_` are considered gem-owned in Asgard's naming convention. `run!` guards against invoking them directly from the CLI:
 
 ```bash
-asgard _version
-# asgard: unknown command '_version'
+asgard _something
+# asgard: unknown command '_something'
 ```
 
-If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being silently blocked.
+If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being blocked. Built-in `class_option` declarations (like `--version`, `--debug`, `--verbose`) do not use the `_` prefix because they are options, not commands.

data/docs/task-files.md

@@ -93,7 +93,7 @@ import("gem_tasks.loki") ? "loaded now" : "already loaded"
 
 ## Finding Files with `loki_up`
 
-`loki_up(name = ".loki")` searches `Dir.pwd` and each ancestor directory for a file with the given name, returning its absolute path or `nil`. It does **not** load the file — it only finds it.
+`loki_up(name = ".loki")` searches `Dir.pwd` and each ancestor directory for a file with the given name, returning a `Pathname` or `nil`. It does **not** load the file — it only finds it.
 
 Despite the name, `loki_up` is not limited to `.loki` files — it will locate any file by name. This makes it useful for finding shared config files, `.env` files, or any other resource that lives somewhere up the directory tree:
 
@@ -401,7 +401,7 @@ end
 
 | Method | Finds? | Loads? | Glob? | Ancestor search? |
 |---|---|---|---|---|
-| `loki_up(name)` | Yes | No | No | Yes |
+| `loki_up(name)` | Yes (`Pathname`) | No | No | Yes |
 | `import(path)` | No | Yes | Yes | No |
 | `import_up(name)` | Yes | Yes | Yes | Yes |
 | Asgard's `run!` | Yes | `.loki` only | No | Yes |

data/examples/server_subcommands.loki

@@ -1,29 +1,38 @@
 # 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,
-# depends_on, and the built-in --debug/--verbose class options.
+# Port state is persisted to .server.port so stop and restart always
+# operate on the same port the server was started on.
 #
 # Usage:
-#   asgard server          # shows subcommand help
+#   asgard server                    # shows subcommand help
 #   asgard server start
-#   asgard server start 4000 --workers 4 --daemon
+#   asgard server start -p 8000
+#   asgard server start -p 4000 --workers 4 --daemon
+#   asgard server stop
 #   asgard server stop --force
 #   asgard server status
-#   asgard server restart 4000
+#   asgard server restart            # stops then starts on the persisted port
+
+SERVER_PORT_FILE = "tmp/.server.port".freeze
 
 class ServerCommands < Tasks
-  desc "start [PORT]", "Start the server on PORT (default: 3000)"
-  option :daemon,  aliases: "-d", type: :boolean, default: false, desc: "Run as a background daemon"
-  option :workers, aliases: "-w", type: :numeric, default: 2,     desc: "Number of worker processes"
+  default_task :help  # This is the default value for the default_task
+
+  helper(:server_port) {
+    File.exist?(SERVER_PORT_FILE) ? File.read(SERVER_PORT_FILE).strip.to_i : 3000
+  }
+
+  desc "Start the server"
+  option :port,    aliases: "-p", type: :numeric, default: 3000,             desc: "Port to listen on"
+  option :daemon,  aliases: "-d", type: :boolean, default: false,            desc: "Run as a background daemon"
+  option :workers, aliases: "-w", type: :numeric, default: 2,                desc: "Number of worker processes"
   option :log,                    type: :string,  default: "log/server.log",
                                   banner: "FILE", desc:    "Write logs to FILE"
-  def start(port = "3000")
-    puts "Starting server on :%s with %d workers%s" % [
-      port,
-      options[:workers],
-      options[:daemon] ? " (daemon)" : ""
-    ]
+  def start
+    FileUtils.mkdir_p("tmp")
+    File.write(SERVER_PORT_FILE, options[:port].to_s)
+    puts "Starting server on :#{options[:port]} with #{options[:workers]} workers#{options[:daemon] ? " (daemon)" : ""}..."
   end
 
   desc "Stop the running server"
@@ -31,22 +40,22 @@ class ServerCommands < Tasks
   option :wait,                  type: :numeric, default: 30,   desc: "Seconds to wait for shutdown"
   def stop
     if options[:force]
-      puts "Force-stopping server..."
+      puts "Force-stopping server on :#{server_port}..."
     else
-      puts "Gracefully stopping server (timeout: #{options[:wait]}s)..."
+      puts "Gracefully stopping server on :#{server_port} (timeout: #{options[:wait] || 30}s)..."
     end
   end
 
   desc "Show server status and process info"
   def status
-    puts "Checking server status..."
+    puts "Server is listening on :#{server_port}"
   end
 
-  # depends_on works inside subcommand groups — stop runs before start
-  depends_on :stop, :start
-  desc "restart [PORT]", "Restart the server on PORT (stop, then start)"
-  def restart(port = "3000")
-    puts "Server restarted on port #{port}."
+  depends_on :stop
+  desc "Restart the server on the same port it was started on"
+  def restart
+    puts "Starting server on :#{server_port}..."
+    puts "Server restarted."
   end
 end
 

data/gem_tasks.loki

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

data/lib/asgard/base.rb

@@ -92,17 +92,46 @@ module Asgard
         end
       end
 
+      # Suppress [--no-name] / [--skip-name] from help for boolean class options
+      # where negation is meaningless. Call after class_option declarations.
+      def no_negate(*names)
+        names.each do |name|
+          opt = class_options[name]
+          next unless opt
+          opt.define_singleton_method(:usage) do |padding = 0|
+            aliases_for_usage.ljust(padding) + "[#{switch_name}]"
+          end
+        end
+      end
+
+      def header(text = nil)
+        return @_header if text.nil?
+        (@_header ||= []) << text
+      end
+
+      def footer(text = nil)
+        return @_footer if text.nil?
+        (@_footer ||= []).unshift(text)
+      end
+
       def dotenv(path = ".env")
         require "dotenv"
         Dotenv.load(path) if File.exist?(path)
       end
 
+      def helper(name, &)
+        define_singleton_method(name, &)
+        no_commands { private define_method(name) { |*args, **kwargs, &blk| self.class.send(name, *args, **kwargs, &blk) } }
+      end
+
       def default_task(meth = nil)
         if meth && meth != :none && @_default_task_location
           here = caller_locations(1, 1).first
-          warn "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:disable Style/StderrPuts -- warn bypasses $stderr in Ruby 4.0, breaking capture_io in tests
+          $stderr.puts "asgard: default_task :#{meth} at #{here.path}:#{here.lineno} " \
+                       "overrides default_task :#{@_default_task_name} set at " \
+                       "#{@_default_task_location.path}:#{@_default_task_location.lineno}"
+          # rubocop:enable Style/StderrPuts
         end
         if meth && meth != :none
           @_default_task_location = caller_locations(1, 1).first
@@ -184,6 +213,13 @@ module Asgard
       end
     end
 
+    def help(command = nil, subcommand = false) # rubocop:disable Style/OptionalBooleanParameter
+      say self.class.header.join("\n\n") if self.class.header && command.nil?
+      say "\n"
+      super
+      say self.class.footer.join("\n\n") if self.class.footer && command.nil?
+    end
+
     no_commands do
       # Dispatch hook: resolves and runs all deps (in parallel where declared)
       # before executing the target command.

data/lib/asgard/kernel_methods.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module Kernel
   def debug?   = $DEBUG
   def verbose? = $VERBOSE
@@ -15,11 +17,11 @@ module Kernel
   module_function :env
 
   def loki_up(name = ".loki")
-    dir = Dir.pwd
+    dir = Pathname.new(Dir.pwd)
     loop do
-      candidate = File.join(dir, name)
-      return candidate if File.exist?(candidate)
-      parent = File.dirname(dir)
+      candidate = dir + name
+      return candidate if candidate.exist?
+      parent = dir.parent
       break if parent == dir
       dir = parent
     end

data/lib/asgard/tasks.rb

@@ -4,6 +4,13 @@
 # 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
+  header "\nasgard v#{Asgard::VERSION} The Mighty Thor and Loki working for you"
+
+  footer <<~FOOT
+    \nDocumentation ... https://madbomber.github.io/asgard
+    Github Repo ..... https://github.com/MadBomber/asgard\n
+  FOOT
+
   class_option :debug,
                type:    :boolean,
                default: false,
@@ -14,10 +21,9 @@ class Tasks < Asgard::Base
                default: false,
                desc:    "Enable verbose output ($VERBOSE = true)"
 
-  desc "--version", "Show asgard version"
-  map "--version" => :_version
-  def _version
-    puts Asgard::VERSION
-    exit
-  end
+  class_option :version,
+               type:    :boolean,
+               default: false,
+               desc:    "Show asgard version and exit"
+  no_negate :version
 end

data/lib/asgard/version.rb

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

data/lib/asgard.rb

@@ -19,6 +19,10 @@ module Asgard
   # Main entry point invoked by the asgard executable.
   def self.run!(argv)
     abort "asgard: unknown command '#{argv.first}'" if argv.first&.start_with?("_")
+    if argv.include?("--version")
+      puts Asgard::VERSION
+      exit
+    end
     task_file = find_task_file or abort "asgard: no .loki file found in #{Dir.pwd}"
     before = Asgard::Base.subclasses.dup
     load task_file

data/quality.loki

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+# Quality gate tasks — imported by .loki
+
+class Tasks
+  desc "Run the test suite"
+  def test
+    output = `bundle exec ruby -Ilib:test test/test_asgard.rb 2>&1`
+    @test_result = $?.success? ? :pass : :fail
+    if @test_result == :fail
+      lines  = output.lines
+      start  = lines.index { |l| l =~ /^\s+1\) / } || 0
+      finish = lines.rindex { |l| l =~ /\d+ runs,/ } || -1
+      print lines[start..finish].join
+    end
+  end
+
+  desc "Run all quality gates (tests, RuboCop, Flog) in parallel"
+  depends_on [:test, :rubocop, :flog_check]
+  def quality
+    results = { tests: @test_result, rubocop: @rubocop_result, flog: @flog_result }
+
+    if @flog_failures&.any?
+      puts "\nFlog failures (must be refactored):"
+      @flog_failures.each { |v| puts "  #{v}" }
+    end
+
+    puts "\n#{"=" * 60}"
+    puts "Quality Summary"
+    puts "=" * 60
+    results.each { |gate, status| puts "  [#{status == :pass ? "PASS" : "FAIL"}] #{gate}" }
+    puts "=" * 60
+
+    abort "\nQuality gate failed" if results.values.any?(:fail)
+    puts "\nAll quality gates passed."
+  end
+
+  desc "Check code style with RuboCop"
+  def rubocop
+    output = `RUBOCOP_CACHE_ROOT=tmp/rubocop_cache bundle exec rubocop 2>&1`
+    @rubocop_result = $?.success? ? :pass : :fail
+    if @rubocop_result == :fail
+      output.each_line { |l| print l if l =~ /:\d+:\d+: [CWEF]: / }
+    end
+  end
+
+  desc "Auto-correct RuboCop offenses"
+  def rubocop_fix
+    sh "RUBOCOP_CACHE_ROOT=tmp/rubocop_cache bundle exec rubocop -a"
+  end
+
+  desc "Check code complexity with Flog (warn >=20, fail >=50)"
+  def flog_check
+    require "flog"
+
+    method_warn = 20.0
+    method_fail = 50.0
+
+    flogger = Flog.new(all: true)
+    flogger.flog(*Dir.glob("lib/**/*.rb"))
+
+    warnings  = []
+    @flog_failures = []
+
+    flogger.each_by_score do |method_name, score|
+      next if method_name.end_with?("#none")
+      if score > method_fail
+        @flog_failures << "#{"%.1f" % score}: #{method_name}"
+      elsif score > method_warn
+        warnings << "#{"%.1f" % score}: #{method_name}"
+      end
+    end
+
+    @flog_result = @flog_failures.empty? ? :pass : :fail
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asgard
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -71,7 +71,6 @@ files:
 - COMMITS.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - bin/asgard
 - bin/console
 - bin/setup
@@ -101,6 +100,7 @@ files:
 - examples/subdir/.loki
 - examples/subdir/import_demo.loki
 - examples/subdir/import_up_demo.loki
+- gem_tasks.loki
 - lib/asgard.rb
 - lib/asgard/base.rb
 - lib/asgard/kernel_methods.rb
@@ -108,6 +108,7 @@ files:
 - lib/asgard/tasks.rb
 - lib/asgard/version.rb
 - mkdocs.yml
+- quality.loki
 - sig/asgard.rbs
 homepage: https://github.com/madbomber/asgard
 licenses:

data/Rakefile

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "minitest/test_task"
-
-SIMPLECOV_PRELUDE = <<~RUBY
-  require "simplecov"
-  SimpleCov.start do
-    add_filter "/test/"
-    minimum_coverage 95
-  end
-RUBY
-
-Minitest::TestTask.create do |t|
-  t.test_prelude = SIMPLECOV_PRELUDE
-end
-
-task default: :test
-
-RUBOCOP_ENV = { "RUBOCOP_CACHE_ROOT" => "tmp/rubocop_cache" }.freeze
-
-desc "Check code style with RuboCop"
-task :rubocop do
-  sh RUBOCOP_ENV, "bundle exec rubocop"
-end
-
-desc "Auto-correct RuboCop offenses"
-task :rubocop_fix do
-  sh RUBOCOP_ENV, "bundle exec rubocop -a"
-end
-
-desc "Check code complexity with Flog (warn >=20, fail >=50)"
-task :flog_check do
-  require "flog"
-
-  # Target to work toward; methods above this are warned but don't fail the gate.
-  METHOD_WARN = 20.0
-  # Current baseline floor — established from first run. Reduce incrementally.
-  METHOD_FAIL = 50.0
-
-  flogger = Flog.new(all: true)
-  flogger.flog(*Dir.glob("lib/**/*.rb"))
-
-  warnings = []
-  failures = []
-
-  flogger.each_by_score do |method, score|
-    next if method.end_with?("#none")
-    if score > METHOD_FAIL
-      failures << "#{"%.1f" % score}: #{method}"
-    elsif score > METHOD_WARN
-      warnings << "#{"%.1f" % score}: #{method}"
-    end
-  end
-
-  unless warnings.empty?
-    puts "\nFlog warnings (#{METHOD_WARN}–#{METHOD_FAIL}) — target for future refactoring:"
-    warnings.each { |v| puts "  #{v}" }
-  end
-
-  if failures.empty?
-    puts "\nFlog: no methods exceed the failure threshold (>=#{METHOD_FAIL})"
-  else
-    puts "\nFlog failures (>=#{METHOD_FAIL}) — must be refactored:"
-    failures.each { |v| puts "  #{v}" }
-    $stdout.flush
-    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{METHOD_FAIL}"
-  end
-end
-
-desc "Run all quality checks: tests (with coverage), RuboCop, and Flog"
-task :quality do
-  results = {}
-
-  puts "\n#{"=" * 60}"
-  puts "Quality Gate: Tests + Coverage"
-  puts "=" * 60
-  results[:tests] = system("bundle exec rake test") ? :pass : :fail
-
-  puts "\n#{"=" * 60}"
-  puts "Quality Gate: RuboCop"
-  puts "=" * 60
-  results[:rubocop] = system(RUBOCOP_ENV, "bundle exec rubocop") ? :pass : :fail
-
-  puts "\n#{"=" * 60}"
-  puts "Quality Gate: Flog Complexity"
-  puts "=" * 60
-  results[:flog] = system("bundle exec rake flog_check") ? :pass : :fail
-
-  puts "\n#{"=" * 60}"
-  puts "Quality Summary"
-  puts "=" * 60
-  results.each do |gate, status|
-    icon = status == :pass ? "PASS" : "FAIL"
-    puts "  [#{icon}] #{gate}"
-  end
-  puts "=" * 60
-
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
-end