asgard 0.2.0 → 0.3.0

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,8 +73,6 @@ 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.
-
 ---
 
 ## Choosing Between `private` and `no_commands`
@@ -93,6 +91,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 +117,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 +130,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 +162,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

data/docs/shell.md

@@ -14,10 +14,10 @@ Pass a single-line string to run it via `system`:
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build = sh "rake build"
 
-  desc "clean", "Remove build artifacts"
+  desc "Remove build artifacts"
   def clean = sh "rm -rf dist/ tmp/"
 end
 ```
@@ -34,7 +34,7 @@ Pass a multiline string (e.g., a heredoc) to run it as a single `bash -c` script
 
 ```ruby
 class Tasks
-  desc "setup", "Bootstrap the development environment"
+  desc "Bootstrap the development environment"
   def setup
     sh <<~SHELL
       brew install redis postgresql
@@ -54,10 +54,10 @@ Pass `silent: true` to suppress the command echo. The command still runs and sti
 
 ```ruby
 class Tasks
-  desc "build", "Compile (quiet)"
+  desc "Compile (quiet)"
   def build = sh "rake build", silent: true
 
-  desc "info", "Print environment info without noise"
+  desc "Print environment info without noise"
   def info
     sh "printenv | grep APP_", silent: true
   end
@@ -71,7 +71,7 @@ end
 ```ruby
 class Tasks
   depends_on :test
-  desc "release", "Test then release"
+  desc "Test then release"
   def release
     sh "bundle exec rake release"
     # Never reached if rake release fails
@@ -90,7 +90,7 @@ end
 
 ```ruby
 class Tasks
-  desc "analyze", "Run Python data analysis"
+  desc "Run Python data analysis"
   def analyze
     shebang :python3, <<~PYTHON
       import json
@@ -105,7 +105,7 @@ end
 
 ```ruby
 class Tasks
-  desc "bundle_assets", "Build frontend assets with esbuild"
+  desc "Build frontend assets with esbuild"
   def bundle_assets
     shebang :node, <<~JS
       const esbuild = require("esbuild")
@@ -123,7 +123,7 @@ end
 
 ```ruby
 class Tasks
-  desc "transform", "Transform data with Ruby"
+  desc "Transform data with Ruby"
   def transform
     shebang :ruby, <<~RUBY
       require "json"
@@ -138,7 +138,7 @@ end
 
 ```ruby
 class Tasks
-  desc "provision", "Run a bash provisioning script"
+  desc "Run a bash provisioning script"
   def provision
     shebang :bash, <<~BASH
       set -euo pipefail
@@ -192,7 +192,7 @@ You can mix both in the same task:
 
 ```ruby
 class Tasks
-  desc "pipeline", "Run a mixed shell + Python pipeline"
+  desc "Run a mixed shell + Python pipeline"
   def pipeline
     sh "bundle exec rake build"
 

data/docs/subcommands.md

@@ -10,10 +10,10 @@ Define a subcommand class that inherits from `Tasks`, then register it on the to
 
 ```ruby
 class DeployCommands < Tasks
-  desc "staging", "Deploy to staging"
+  desc "Deploy to staging"
   def staging = sh "cap staging deploy"
 
-  desc "production", "Deploy to production"
+  desc "Deploy to production"
   def production = sh "cap production deploy"
 end
 
@@ -37,8 +37,8 @@ Inheriting from `Tasks` (rather than `Asgard::Base` or `Thor`) gives the subcomm
 
 - `sh` and `shebang` shell helpers (from `Asgard::Shell`)
 - `depends_on` for dependency declarations
-- `var` for variables
 - `dotenv` for environment loading
+- `@@` class variables declared on `Tasks` (visible in all subclasses)
 - The built-in `--debug` and `--verbose` class options
 - The `debug?` and `verbose?` private predicates
 - Any private helpers or `no_commands` methods defined on `Tasks`
@@ -54,14 +54,14 @@ Inheriting from `Tasks` (rather than `Asgard::Base` or `Thor`) gives the subcomm
 
 ```ruby
 class DBCommands < Tasks
-  desc "migrate", "Run pending migrations"
+  desc "Run pending 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
 
@@ -94,13 +94,13 @@ class ServerCommands < Tasks
     sh "puma -p #{port} #{flags.join(' ')}"
   end
 
-  desc "stop", "Stop the running server"
+  desc "Stop the running server"
   option :force, aliases: "-f", type: :boolean, default: false, desc: "Force-kill without draining"
   def stop
     options[:force] ? sh "pkill -9 puma" : sh "pumactl stop"
   end
 
-  desc "status", "Show server status"
+  desc "Show server status"
   def status = sh "pumactl stats"
 
   depends_on :stop, :start
@@ -176,6 +176,6 @@ myproject/
   db_subcommands.loki      ← defines DBCommands
 ```
 
-When `--auto-load` is used, `*.loki` files are loaded alphabetically before `.loki`, so both `DBCommands` and `ServerCommands` are defined by the time `.loki` runs its `subcommand` calls.
+Because siblings loaded via `import "*.loki"` execute before `.loki`'s own class body, both `DBCommands` and `ServerCommands` are defined by the time `.loki` runs its `subcommand` calls.
 
 See [`examples/server_subcommands.loki`](examples.md#server-subcommands) and [`examples/db_subcommands.loki`](examples.md#db-subcommands) for complete working examples.