asgard 0.2.0 → 0.3.1

data/docs/dependencies.md

@@ -26,15 +26,15 @@ Bare symbols run one after another in the order declared:
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 
   depends_on :build
-  desc "test", "Run the test suite"
+  desc "Run the test suite"
   def test = sh "rake test"
 
   depends_on :test
-  desc "release", "Publish the gem"
+  desc "Publish the gem"
   def release = sh "bundle exec rake release"
 end
 ```
@@ -47,7 +47,7 @@ Multiple sequential dependencies in a single `depends_on` call run left to right
 
 ```ruby
 depends_on :clean, :build, :test
-desc "package", "Clean, build, and test"
+desc "Clean, build, and test"
 def package = sh "rake package"
 ```
 
@@ -59,14 +59,14 @@ Wrap symbols in an array to declare they can run concurrently. Asgard waits for
 
 ```ruby
 class Tasks
-  desc "lint", "Check code style"
+  desc "Check code style"
   def lint = sh "bundle exec rubocop"
 
-  desc "typecheck", "Run type checks"
+  desc "Run type checks"
   def typecheck = sh "bundle exec srb tc"
 
   depends_on [:lint, :typecheck]
-  desc "test", "Run tests (after lint and typecheck)"
+  desc "Run tests (after lint and typecheck)"
   def test = sh "bundle exec rake test"
 end
 ```
@@ -85,16 +85,16 @@ Mix bare symbols and arrays in a single `depends_on` call. Execution proceeds st
 
 ```ruby
 class Tasks
-  desc "setup",  "Install dependencies"; def setup  = sh "bundle install"
-  desc "lint",   "Check code style";     def lint   = sh "bundle exec rubocop"
-  desc "build",  "Compile assets";       def build  = sh "rake assets:precompile"
-  desc "test",   "Run tests";            def test   = sh "bundle exec rake test"
-  desc "notify", "Post to Slack";        def notify = sh "curl $SLACK_WEBHOOK -d '{\"text\":\"done\"}'"
+  desc "Install dependencies"; def setup  = sh "bundle install"
+  desc "Check code style";     def lint   = sh "bundle exec rubocop"
+  desc "Compile assets";       def build  = sh "rake assets:precompile"
+  desc "Run tests";            def test   = sh "bundle exec rake test"
+  desc "Post to Slack";        def notify = sh "curl $SLACK_WEBHOOK -d '{\"text\":\"done\"}'"
 
   # setup first, then lint+build in parallel, then test, then notify
   depends_on :setup, [:lint, :build], :test, :notify
-  desc "ci", "Full CI pipeline"
-  def ci = sh "echo 'CI complete'"
+  desc "Full CI pipeline"
+  def ci = puts "CI complete"
 end
 ```
 
@@ -124,19 +124,19 @@ Each task runs at most once per `asgard` invocation. If multiple tasks declare t
 
 ```ruby
 class Tasks
-  desc "setup", "Install gems"
+  desc "Install gems"
   def setup = sh "bundle install"
 
   depends_on :setup
-  desc "test", "Run tests"
+  desc "Run tests"
   def test = sh "rake test"
 
   depends_on :setup
-  desc "lint", "Check style"
+  desc "Check style"
   def lint = sh "rubocop"
 
   depends_on [:test, :lint]
-  desc "ci", "Test and lint (setup runs once)"
+  desc "Test and lint (setup runs once)"
   def ci = puts "done"
 end
 ```
@@ -152,10 +152,10 @@ Asgard validates the full dependency graph using [Dagwood](https://rubygems.org/
 ```ruby
 class Tasks
   depends_on :b
-  desc "a", "Task A"; def a = puts "a"
+  desc "Task A"; def a = puts "a"
 
   depends_on :a
-  desc "b", "Task B"; def b = puts "b"
+  desc "Task B"; def b = puts "b"
 end
 ```
 
@@ -175,14 +175,14 @@ No backtrace is shown — just a single diagnostic line.
 ```ruby
 # build.loki
 class Tasks
-  desc "build", "Compile"
+  desc "Compile"
   def build = sh "rake build"
 end
 
 # test.loki
 class Tasks
   depends_on :build           # build.loki must be loaded first
-  desc "test", "Test"
+  desc "Test"
   def test = sh "rake test"
 end
 ```
@@ -197,14 +197,14 @@ When `--auto-load` is used, `*.loki` files are loaded alphabetically, so `build.
 
 ```ruby
 class DBCommands < Tasks
-  desc "migrate", "Run migrations"
+  desc "Run migrations"
   def migrate = sh "rails db:migrate"
 
-  desc "seed", "Load seed data"
+  desc "Load seed data"
   def seed = sh "rails db:seed"
 
   depends_on :migrate, :seed
-  desc "reset", "Migrate then seed"
+  desc "Migrate then seed"
   def reset = puts "Done."
 end
 

data/docs/environment.md

@@ -12,8 +12,8 @@ Call `dotenv` inside the class body (not inside a task method) to load the defau
 class Tasks
   dotenv   # loads .env from the current working directory
 
-  desc "check", "Print the app name from .env"
-  def check = sh "echo $APP_NAME"
+  desc "Print the app name from .env"
+  def check = puts env(:app_name)
 end
 ```
 
@@ -46,17 +46,14 @@ end
 `dotenv` is a **class-level** call — it executes at Ruby class-load time, not when a task is invoked. This means:
 
 1. Variables are available in `ENV` before any task method runs.
-2. They are also available to lambda variables declared with `var` that reference `ENV`.
-3. They are available during `depends_on` dependency resolution.
+2. They are available during `depends_on` dependency resolution.
 
 ```ruby
 class Tasks
   dotenv
 
-  var :database_url, -> { ENV.fetch("DATABASE_URL") }
-
-  desc "migrate", "Run migrations"
-  def migrate = sh "DATABASE_URL=#{database_url} rails db:migrate"
+  desc "Run migrations"
+  def migrate = sh "DATABASE_URL=#{env(:database_url)} rails db:migrate"
 end
 ```
 
@@ -79,20 +76,39 @@ This makes it safe to commit a `.env.local` line to your `.loki` without requiri
 
 ---
 
-## Environment Variables vs. `var`
+## Environment Variables vs. Class Variables
 
-Use `dotenv` to bring external configuration into `ENV`, and `var` to define task-internal computed values:
+Use `dotenv` to bring external configuration into `ENV`. Use `@@` class variables for fixed values declared in the task file, and read from `ENV` directly in task bodies or helper methods when the value comes from the environment:
 
 ```ruby
 class Tasks
   dotenv
 
-  # Read from ENV (set by dotenv or the shell)
-  var :app_name, -> { ENV.fetch("APP_NAME", "myapp") }
-  var :port,     -> { ENV.fetch("PORT", "3000").to_i }
+  @@app_name ||= "myapp".freeze
+
+  desc "Start the server"
+  def start
+    port = ENV.fetch("PORT", "3000").to_i
+    sh "puma -b tcp://0.0.0.0:#{port} -w #{ENV.fetch('WORKERS', '2')}"
+  end
+end
+```
+
+For `ENV` values used in multiple tasks, define a private helper method:
+
+```ruby
+class Tasks
+  dotenv
 
-  desc "start", "Start the server"
+  desc "Start the server"
   def start = sh "puma -p #{port}"
+
+  desc "Show config"
+  def config = puts "#{@@app_name} on port #{port}"
+
+  private
+
+  def port = ENV.fetch("PORT", "3000").to_i
 end
 ```
 

data/docs/examples.md

@@ -27,7 +27,7 @@ Alternatively, copy individual example files into your own project's directory.
 
 The most comprehensive example — demonstrates every Thor DSL feature available in Asgard:
 
-- `var` with a static value and a lazy lambda
+- `@@` class variables for shared configuration values
 - `dotenv` (commented out, ready to activate)
 - `class_option` with `:boolean` and `:string` types, including `enum`
 - `default_task` — sets the default command when `asgard` is run with no arguments
@@ -56,7 +56,7 @@ asgard pipeline
 
 ---
 
-## `server_subcommands.loki`
+## Server Subcommands
 
 **Path:** `examples/server_subcommands.loki`
 
@@ -80,7 +80,7 @@ The `ServerCommands` class inherits from `Tasks`, giving it access to `sh`, `dep
 
 ---
 
-## `db_subcommands.loki`
+## DB Subcommands
 
 **Path:** `examples/db_subcommands.loki`
 

data/docs/getting-started.md

@@ -50,8 +50,8 @@ Open `.loki` in your editor and add a task:
 
 ```ruby
 class Tasks
-  desc "hello", "Say hello to the world"
-  def hello = sh 'echo "Hello, World!"'
+  desc "Say hello to the world"
+  def hello = puts "Hello, World!"
 end
 ```
 
@@ -64,7 +64,6 @@ end
 
 ```bash
 asgard hello
-# echo "Hello, World!"
 # Hello, World!
 ```
 
@@ -90,7 +89,7 @@ Positional parameters are declared directly in the method signature. Document th
 class Tasks
   desc "greet NAME", "Greet someone by name"
   def greet(name = "World")
-    sh "echo 'Hello, #{name}!'"
+    puts "Hello, #{name}!"
   end
 end
 ```
@@ -115,7 +114,7 @@ class Tasks
   option :shout, aliases: "-s", type: :boolean, desc: "Uppercase the greeting"
   def greet(name = "World")
     msg = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
-    sh "echo '#{msg}'"
+    puts msg
   end
 end
 ```
@@ -163,7 +162,7 @@ Inside a task body, use the `debug?` and `verbose?` predicates:
 
 ```ruby
 def hello
-  sh "echo 'building...'"
+  puts "building..."
   sh "make --debug" if debug?
 end
 ```

data/docs/helpers.md

@@ -10,13 +10,13 @@ Methods declared after `private` are callable from any task in the same class bu
 
 ```ruby
 class Tasks
-  desc "build", "Compile and package"
+  desc "Compile and package"
   def build
     compile("src")
     package(app_version)
   end
 
-  desc "release", "Build and publish to RubyGems"
+  desc "Build and publish to RubyGems"
   def release
     build
     sh "gem push pkg/myapp-#{app_version}.gem"
@@ -49,13 +49,13 @@ Thor's `no_commands` block marks public methods as excluded from CLI discovery.
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build
     puts "Revision: #{current_sha}"
     sh "rake build"
   end
 
-  desc "deploy", "Deploy to production"
+  desc "Deploy to production"
   def deploy
     puts "Deploying revision #{current_sha}..."
     sh "cap production deploy"
@@ -73,7 +73,89 @@ class Tasks
 end
 ```
 
-`var`-declared variables are also implemented using `no_commands` internally, which is why they appear as callable methods but not as CLI commands.
+---
+
+## 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.
 
 ---
 
@@ -93,6 +175,8 @@ For most helpers, `private` is the right choice. Use `no_commands` when the help
 
 ## Sharing Helpers Across Files
 
+### Within a project
+
 Extract shared helpers into a plain Ruby module and load it from `.loki` using `require_relative`:
 
 ```ruby
@@ -117,10 +201,10 @@ require_relative "shared/helpers"
 class Tasks
   include BuildHelpers
 
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = compile("src")
 
-  desc "package", "Create distribution archive"
+  desc "Create distribution archive"
   def package = sh "tar czf #{dist_path(app_version)} bin/"
 end
 ```
@@ -130,6 +214,30 @@ Because `include` in the class body makes the module methods available as instan
 !!! tip
     Helpers in a shared module can call `sh`, `shebang`, and other Asgard DSL methods because those are included in `Tasks` (via `Asgard::Base` and `Asgard::Shell`) and are available in `self` when the module method is invoked.
 
+### Across projects with `import_up`
+
+If helpers are defined as tasks in a shared `.loki` file, use `import_up` to load them from any sub-project without knowing the absolute path:
+
+```
+~/sandbox/
+  shared_helpers.loki   ← defines helper tasks available to all sub-projects
+  projectA/
+    .loki
+  projectB/
+    .loki
+```
+
+```ruby
+# projectA/.loki  (and identically in projectB/.loki)
+import_up "shared_helpers.loki"
+
+class Tasks
+  # shared tasks are already defined in Tasks by here
+end
+```
+
+`import_up` walks up from `Dir.pwd` until it finds `shared_helpers.loki`, then loads it. It returns `false` without raising if the file is not found, making it safe to use in projects where the shared file may not always be present.
+
 ---
 
 ## Helper Methods in Subcommands
@@ -138,10 +246,10 @@ Subcommand classes that inherit from `Tasks` also inherit all private helpers an
 
 ```ruby
 class DeployCommands < Tasks
-  desc "staging", "Deploy to staging"
+  desc "Deploy to staging"
   def staging = deploy_to("staging")
 
-  desc "production", "Deploy to production"
+  desc "Deploy to production"
   def production = deploy_to("production")
 
   private

data/docs/index.md

@@ -13,11 +13,11 @@
 <li><strong>Task Dependencies</strong> — sequential, parallel, and mixed dependency graphs via <code>depends_on</code></li>
 <li><strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads</li>
 <li><strong>Subcommands</strong> — group related tasks under a named namespace</li>
-<li><strong>Variables</strong> — static values and lazy-evaluated lambdas via <code>var</code></li>
+<li><strong>Variables</strong> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands</li>
 <li><strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts</li>
 <li><strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code></li>
 <li><strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories</li>
-<li><strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files, loaded on demand with <code>--auto-load</code></li>
+<li><strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files loaded via <code>import</code></li>
 <li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, and <code>--verbose</code> available on every task</li>
 </ul>
 </td>
@@ -40,8 +40,8 @@ touch .loki
 # Add your first task
 cat >> .loki << 'EOF'
 class Tasks
-  desc "hello", "Say hello"
-  def hello = sh 'echo "Hello from Asgard!"'
+  desc "Say hello"
+  def hello = puts "Hello from Asgard!"
 end
 EOF
 
@@ -53,9 +53,9 @@ asgard hello
 
 ## How It Works
 
-Asgard searches upward from your current directory for a `.loki` file. That file marks the project root. Additional `*.loki` files in the same directory can be loaded by passing `--auto-load` to the `asgard` command. All task files reopen `class Tasks`, which is pre-defined by the gem as a subclass of `Asgard::Base` (itself a Thor subclass).
+Asgard searches upward from your current directory for a `.loki` file. That file marks the project root. Additional `*.loki` files in the same directory can be loaded via `import "*.loki"` at the top of `.loki`. All task files reopen `class Tasks`, which is pre-defined by the gem as a subclass of `Asgard::Base` (itself a Thor subclass).
 
-The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_desc`, `argument`, `default_task`, `map`, and `subcommand` all work exactly as documented in Thor — with Asgard's own `depends_on`, `var`, `sh`, `shebang`, and `dotenv` layered on top.
+The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_desc`, `argument`, `default_task`, `map`, and `subcommand` all work exactly as documented in Thor — with Asgard's own `depends_on`, `sh`, `shebang`, and `dotenv` layered on top.
 
 ---
 

data/docs/options.md

@@ -53,7 +53,7 @@ class Tasks
                enum:    %w[development staging production],
                desc:    "Target environment"
 
-  desc "deploy", "Deploy the application"
+  desc "Deploy the application"
   def deploy
     if options[:dry_run]
       puts "Would deploy to #{options[:env]}"
@@ -62,7 +62,7 @@ class Tasks
     end
   end
 
-  desc "migrate", "Run database migrations"
+  desc "Run database migrations"
   def migrate
     sh "rails db:migrate RAILS_ENV=#{options[:env]}"
   end
@@ -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.