asgard 0.2.0 → 0.3.1

data/docs/tasks.md

@@ -10,12 +10,12 @@ A task with no parameters and no options:
 
 ```ruby
 class Tasks
-  desc "hello", "Say hello"
-  def hello = sh 'echo "Hello, World!"'
+  desc "Say hello"
+  def hello = puts "Hello, World!"
 end
 ```
 
-`desc` takes two arguments: the usage string and the one-line description shown in `asgard help`.
+`desc` accepts either one or two strings. With one argument, the description is shown in `asgard help` and the usage string defaults to the method name. Pass two arguments when the usage string needs to document parameters — `desc "greet NAME", "Greet NAME by name"`.
 
 ```bash
 asgard hello
@@ -31,7 +31,7 @@ Positional parameters are declared directly in the method signature. Document th
 class Tasks
   desc "greet NAME", "Greet NAME; omit NAME to greet the world"
   def greet(name = "World")
-    sh "echo 'Hello, #{name}!'"
+    puts "Hello, #{name}!"
   end
 end
 ```
@@ -51,7 +51,7 @@ Use `method_option` (alias: `option`) for named flags. Access them inside the me
 
 ```ruby
 class Tasks
-  desc "compile", "Compile the project"
+  desc "Compile the project"
   option :output,  aliases: "-o", type: :string,  default: "dist/",  desc: "Output directory"
   option :verbose, aliases: "-v", type: :boolean, default: false,    desc: "Enable verbose output"
   option :jobs,    aliases: "-j", type: :numeric, default: 1,        desc: "Number of parallel jobs"
@@ -117,7 +117,7 @@ asgard deploy production --strategy blue-green
 
 ```ruby
 class Tasks
-  desc "build", "Build the project"
+  desc "Build the project"
   option :env,
          type:    :string,
          default: "development",
@@ -139,7 +139,7 @@ Thor validates the value against the enum and shows a helpful error if it doesn'
 
 ```ruby
 class Tasks
-  desc "wait", "Wait for a service to become available"
+  desc "Wait for a service to become available"
   option :timeout, type: :numeric, default: 30, banner: "SECONDS", desc: "Give up after SECONDS"
   def wait
     sh "wait-for-it --timeout #{options[:timeout]}"
@@ -169,7 +169,7 @@ class Tasks
       asgard report --format json --output report.json\x5
       asgard report --format text
   DESC
-  desc "report", "Generate a project report"
+  desc "Generate a project report"
   option :format, type: :string, default: "text", enum: %w[text html json], desc: "Output format"
   option :since,  type: :string, banner: "DATE",                            desc: "Limit to changes after DATE"
   def report
@@ -191,7 +191,7 @@ end
 class Tasks
   default_task :greet
 
-  desc "greet", "Say hello (runs by default)"
+  desc "Say hello (runs by default)"
   def greet
     puts "Hello from Asgard!"
   end
@@ -202,6 +202,8 @@ end
 asgard        # same as: asgard greet
 ```
 
+Without `default_task`, running `asgard` with no arguments displays the help message.
+
 ---
 
 ## Command Aliases
@@ -215,13 +217,13 @@ class Tasks
   map "t"   => "test"
   map "b"   => "build"
 
-  desc "version", "Print the version"
+  desc "Print the version"
   def version = puts Asgard::VERSION
 
-  desc "test", "Run tests"
+  desc "Run tests"
   def test = sh "bundle exec rake test"
 
-  desc "build", "Build the gem"
+  desc "Build the gem"
   def build = sh "bundle exec rake build"
 end
 ```
@@ -249,14 +251,14 @@ class Tasks
            desc:    "Name to greet"
 
   desc "hello NAME", "Say hello to NAME"
-  def hello = sh "echo 'Hello, #{name}!'"
+  def hello = puts "Hello, #{name}!"
 end
 ```
 
 For most multi-task `.loki` files, the simpler positional default pattern is safer:
 
 ```ruby
-def hello(name = "World") = sh "echo 'Hello, #{name}!'"
+def hello(name = "World") = puts "Hello, #{name}!"
 ```
 
 ---
@@ -267,7 +269,7 @@ def hello(name = "World") = sh "echo 'Hello, #{name}!'"
 
 ```ruby
 class Tasks
-  desc "build", "Compile the project"
+  desc "Compile the project"
   def build
     puts "Revision: #{current_sha}"
     sh "rake build"

data/docs/variables.md

@@ -1,122 +1,338 @@
 # Variables
 
-`var` declares a named value that is available to all tasks in the class as a method call. Values can be static or lazily evaluated.
+Asgard task files are plain Ruby. Shared configuration values are declared using Ruby class variables (`@@name`) at the top of the `Tasks` class body.
 
 ---
 
-## Static Value
+## Ruby Variable Types
 
-Pass the value directly as the second argument:
+Ruby has four kinds of variables plus constants, each with a distinct prefix and scope. Understanding the differences matters because tasks are instance methods — the wrong variable type will simply not be visible where you expect it.
+
+| Kind | Prefix | Example | Scope |
+|------|--------|---------|-------|
+| Local | none | `count = 0` | The method or block it is defined in only |
+| Instance | `@` | `@name = "myapp"` | One specific object instance |
+| Class | `@@` | `@@name = "myapp"` | The class and all its subclasses |
+| Global | `$` | `$DEBUG = true` | Everywhere in the process |
+| Constant | uppercase first letter | `APP = "myapp"` | Everywhere (namespaced to where defined) |
+
+### Local variables
+
+```ruby
+def build
+  output_dir = "dist"   # only visible inside this method
+  sh "rake build OUTDIR=#{output_dir}"
+end
+```
+
+`output_dir` disappears when the method returns. It cannot be seen by any other task.
+
+### Instance variables (`@`)
 
 ```ruby
 class Tasks
-  var :app,  "myapp"
-  var :env,  "production"
-  var :port, 3000
+  @app = "myapp"   # class instance variable — lives on the Tasks class object
 
-  desc "info", "Print app info"
-  def info
-    puts "#{app} running on port #{port} in #{env}"
+  def build
+    puts @app      # nil — this @app is on the instance, not the class
   end
 end
 ```
 
+`@` in the class body sets a variable on the class object itself, not on the instances that run tasks. Inside a task method body, `@name` refers to the instance, which is a different object. They do not share state.
+
+`@` inside a method is useful for memoization within a single task invocation:
+
+```ruby
+def version
+  @version ||= `git describe --tags`.strip   # computed once, cached for this run
+end
+```
+
+### Class variables (`@@`)
+
+```ruby
+class Tasks
+  @@app = "myapp"   # visible in every task method and every subclass
+
+  def build
+    puts @@app      # "myapp"
+  end
+end
+```
+
+`@@` is shared across the class body, all instance methods, and all subclasses (including Thor subcommand classes). This makes it the right choice for configuration values in Asgard task files.
+
+### Global variables (`$`)
+
+```ruby
+$DEBUG   = true   # visible everywhere in the Ruby process
+$VERBOSE = true
+```
+
+Asgard uses `$DEBUG` and `$VERBOSE` internally — they are set by the `--debug` and `--verbose` CLI flags. Avoid declaring your own `$` variables in `.loki` files; they affect the entire Ruby process including all loaded gems.
+
+Several important Ruby globals you may encounter in task files:
+
+| Variable | Purpose |
+|----------|---------|
+| `$stdout` / `$STDOUT` | Standard output stream — `puts` writes here |
+| `$stderr` / `$STDERR` | Standard error stream — `warn` writes here |
+| `$DEBUG` | Enables debug mode when `true` |
+| `$VERBOSE` | Enables verbose warnings when `true` |
+| `$PROGRAM_NAME` / `$0` | The name of the running script |
+
+The uppercase versions (`$STDOUT`, `$STDERR`) are the original stream objects. The lowercase versions (`$stdout`, `$stderr`) are reassignable aliases — libraries sometimes redirect them temporarily to capture output. In task files, use `$stdout.puts` or `$stderr.puts` when you need explicit stream control; use plain `puts` and `warn` for normal output.
+
+### Constants
+
+Any name that begins with an uppercase letter is a constant in Ruby. Constants are available everywhere — inside methods, across files, and across classes — without any prefix:
+
+```ruby
+APP_NAME    = "myapp".freeze
+MAX_RETRIES = 3
+BASE_URL    = "https://example.com".freeze
+
+class Tasks
+  desc "Deploy the app"
+  def deploy
+    puts "Deploying #{APP_NAME} to #{BASE_URL}"
+    sh "cap deploy"
+  end
+end
+```
+
+The convention is `ALL_CAPS_WITH_UNDERSCORES` for values that are truly fixed. Class and module names are also constants — `Tasks`, `Asgard`, `String`, `Integer` all start with an uppercase letter.
+
+Ruby will issue a warning if you reassign a constant but will not prevent it. Use `.freeze` to make the value itself immutable:
+
+```ruby
+APP_NAME = "myapp".freeze   # value cannot be mutated; reassignment still warns
+```
+
+**Constants vs `@@` class variables in task files:**
+
+| | Constant | `@@` class variable |
+|---|---|---|
+| Accessible in task methods | Yes | Yes |
+| Accessible in subcommand subclasses | Yes | Yes |
+| Visible outside the class | Yes — anywhere | Only within the class hierarchy |
+| Reassignment warning | Yes | No |
+| Convention | `ALL_CAPS` | `snake_case` |
+
+For fixed values that will never change — app names, version strings, URLs, port numbers — constants are often the clearest choice. For values that might reasonably vary across environments or be overridden in a different `.loki` file, `@@` with `||=` is more flexible.
+
 ---
 
-## Lazy Lambda
+## Strings and Interpolation
+
+### Always use double quotes
 
-Pass a lambda (or proc) to defer evaluation until the variable is first accessed. The lambda is called once and its return value is used for all subsequent accesses:
+Ruby supports both single and double quoted strings. In Asgard task files, always use double quotes:
+
+```ruby
+@@app ||= "myapp".freeze     # correct
+sh "bundle exec rake test"   # correct
+```
+
+Single-quoted strings look similar but behave differently — they do not support interpolation or escape sequences. Mixing the two styles adds confusion for no benefit. Double quotes work everywhere single quotes do, and more.
+
+### String interpolation
+
+Embedding a variable's value inside a string uses the `#{}` syntax. Everything inside the braces is Ruby code — the result is converted to a string and inserted in place:
 
 ```ruby
 class Tasks
-  var :version, -> { `git describe --tags`.strip }
-  var :sha,     -> { `git rev-parse --short HEAD`.strip }
+  @@app  ||= "myapp".freeze
+  @@env  ||= "production".freeze
 
-  desc "tag", "Create a release tag"
-  def tag = sh "git tag v#{version}"
+  desc "Deploy the app"
+  def deploy
+    sh "cap #{@@env} deploy APP=#{@@app}"
+  end
+end
+```
 
-  desc "info", "Show version info"
-  def info = puts "#{version} (#{sha})"
+Any Ruby expression works inside `#{}`:
+
+```ruby
+puts "build started at #{Time.now}"
+sh "puma -p #{env(:port, '3000').to_i + 1}"
+sh "git tag #{@@app}-#{`git describe --tags`.strip}"
+```
+
+Interpolation only works inside double-quoted strings. This is the primary reason Asgard tasks use double quotes exclusively — shell commands almost always need to embed variable values.
+
+### Multi-line strings
+
+For shell scripts with multiple lines, use a heredoc. The `~` modifier strips leading indentation so the script aligns with your code:
+
+```ruby
+desc "Bootstrap the project"
+def bootstrap
+  sh <<~SHELL
+    bundle install
+    rails db:create db:migrate
+    echo "#{@@app} ready on #{env(:port, '3000')}"
+  SHELL
 end
 ```
 
-!!! tip
-    Lazy lambdas are ideal for values that require a shell call or file read — they only pay the cost if the variable is actually used in the task being run.
+Interpolation works inside heredocs the same as in double-quoted strings.
 
 ---
 
-## Block Syntax
+## System Environment Variables
 
-You can also use a block instead of a lambda:
+System environment variables are set outside Ruby — in the shell, a CI environment, or a `.env` file — and are accessed inside tasks via the `env` Kernel method:
 
 ```ruby
 class Tasks
-  var(:build_dir) { "builds/#{app}" }
-  var(:app)       { "myapp" }
+  desc "Start the server"
+  def start
+    sh "puma -p #{env(:port, '3000')} -e #{env(:rack_env, 'development')}"
+  end
 
-  desc "build", "Compile into build_dir"
-  def build = sh "rake build OUTDIR=#{build_dir}"
+  desc "Deploy the app"
+  def deploy
+    sh "cap #{env(:deploy_target)} deploy"  # raises KeyError if DEPLOY_TARGET is not set
+  end
 end
 ```
 
+`env` accepts a symbol or string and converts it to an uppercase `ENV` key automatically:
+
+| Call | Equivalent | Behaviour |
+|------|-----------|-----------|
+| `env(:port, "3000")` | `ENV.fetch("PORT", "3000")` | Returns `"3000"` if `PORT` is unset |
+| `env(:api_key)` | `ENV.fetch("API_KEY")` | Raises `KeyError` if `API_KEY` is unset |
+| `env("DATABASE_URL")` | `ENV.fetch("DATABASE_URL")` | Raises `KeyError` if unset |
+| `env("database_url")` | `ENV.fetch("DATABASE_URL")` | Same — name is always upcased |
+
 !!! note
-    The block form and the lambda form behave identically — both are stored as callables and invoked on first access.
+    All environment variable values are strings. Convert to other types explicitly: `env(:port, "3000").to_i`, `env(:debug, "false") == "true"`.
+
+Use `dotenv` to load a `.env` file before tasks run — see [Environment](environment.md).
 
 ---
 
-## Accessing Variables from Tasks
+## The Pattern
 
-Variables are available as method calls from within any task body (or other method) in the same class. They are defined using `no_commands`, so they appear neither in `--help` output nor as CLI commands:
+```ruby
+class Tasks
+  @@app  ||= "myapp".freeze
+  @@port ||= 3000
+  @@env  ||= "production".freeze
+
+  desc "Print app info"
+  def info
+    puts "#{@@app} running on port #{@@port} in #{@@env}"
+  end
+end
+```
+
+**Why `||=` instead of `=`?**
+Because multiple `.loki` files reopen the same `class Tasks`. Using `||=` means the first file to declare a value wins, and subsequent files that reopen `Tasks` won't accidentally overwrite it.
+
+**Why `.freeze`?**
+It prevents mutation of the value (e.g. `@@app << "-extra"` raises a `FrozenError`). Numbers and symbols are already frozen. Use `.freeze` on strings, arrays, and hashes.
+
+**Why `@@` instead of `@`?**
+A single `@` in the class body sets a class instance variable — it lives on the `Tasks` class object and is **not** accessible inside task method bodies. `@@` is a class variable and is visible everywhere: in all instance methods, and in any subclass (including Thor subcommand classes).
+
+---
+
+## Sharing Values Across Subcommands
+
+Class variables are visible in subclasses, which makes them the right choice when you have Thor subcommands defined in separate classes:
 
 ```ruby
+# config.loki
 class Tasks
-  var :app,     "myapp"
-  var :version, -> { `git describe --tags`.strip }
-  var :pkg,     -> { "pkg/#{app}-#{version}.gem" }
+  @@app ||= "myapp".freeze
+end
 
-  desc "build", "Build the gem"
-  def build = sh "gem build #{app}.gemspec"
+# deploy.loki
+class DeployCommands < Tasks
+  desc "Deploy to production"
+  def production
+    sh "cap production deploy APP=#{@@app}"  # @@app is visible here
+  end
+end
 
-  desc "push", "Push the gem to RubyGems"
-  def push = sh "gem push #{pkg}"
+class Tasks
+  desc "deploy SUBCOMMAND", "Deployment tasks"
+  subcommand "deploy", DeployCommands
 end
 ```
 
-Variables can reference other variables in their lambdas as long as the referenced variable is also defined with `var` on the same class.
+---
+
+## Computed Values
+
+For values that require a shell call, file read, or any runtime computation, define a method instead:
+
+```ruby
+class Tasks
+  def version = `git describe --tags`.strip
+  def sha     = `git rev-parse --short HEAD`.strip
+
+  desc "Show version info"
+  def info = puts "#{version} (#{sha})"
+end
+```
+
+Methods defined without `desc` do not appear in `--help` output or as CLI commands. If you need memoization (the computation is expensive and called multiple times), use `||=` on an instance variable inside the method:
+
+```ruby
+class Tasks
+  def version
+    @version ||= `git describe --tags`.strip
+  end
+end
+```
 
 ---
 
-## Sharing Variables Across Files
+## Sharing Values Across Files
 
-Because all `.loki` files reopen the same `class Tasks`, variables declared in one file are available in all other files loaded in the same session:
+Because all `.loki` files reopen the same `class Tasks`, a `@@` variable declared in one file is available in all other files loaded in the same session:
 
 ```ruby
 # config.loki
 class Tasks
-  var :app,  "myapp"
-  var :port, 8080
+  @@app  ||= "myapp".freeze
+  @@port ||= 8080
 end
 
 # deploy.loki
 class Tasks
-  desc "deploy", "Deploy the app"
-  def deploy = sh "cap deploy APP=#{app} PORT=#{port}"
+  desc "Deploy the app"
+  def deploy = sh "cap deploy APP=#{@@app} PORT=#{@@port}"
 end
 ```
 
 ---
 
-## Naming Caution
+## Naming Conventions
 
-!!! warning
-    Do not use `var` names that conflict with built-in Ruby method names, Thor DSL method names, or Asgard's own built-in methods. In particular, avoid naming a variable `version` — `Tasks` already defines `_version` (the `--version` flag handler), and a `var :version` would collide with that namespace and produce confusing behavior. Use a more specific name like `app_version` or `gem_version` instead.
+Class variable names use `snake_case` — the standard Ruby convention for variables and methods:
 
 ```ruby
-# Avoid this — conflicts with the built-in version infrastructure:
-# var :version, -> { "1.0.0" }
-
-# Use this instead:
-var :app_version, -> { `git describe --tags`.strip }
+class Tasks
+  @@app_name    ||= "myapp".freeze
+  @@deploy_host ||= "production.example.com".freeze
+  @@max_workers ||= 4
+end
 ```
 
-Other names to avoid: `options`, `class_options`, `shell`, `invoke`, `invoke_command`.
+Multi-word names are separated by underscores, not camelCase or hyphens.
+
+---
+
+## Naming Caution
+
+!!! warning
+    Avoid `@@` names that conflict with built-in Ruby or Thor internals. Safe practice: use descriptive names that are unlikely to clash.
+
+Names to avoid: `options`, `shell`, `invoke`, `command`, `args`.

data/examples/.env

@@ -0,0 +1,4 @@
+APP_NAME=my_app
+PORT=4000
+API_KEY=secret-key-abc123
+DATABASE_URL=postgres://localhost/my_app_dev

data/examples/.loki

@@ -1,2 +1,24 @@
-# The .loki file can be empty if there are *.loki files define the tasks
-# they will be auto loaded.
+# examples/.loki — root task file for the examples directory.
+#
+# Asgard loads only this file by default. Everything else must be
+# explicitly pulled in with import.
+#
+# import(path)
+#   Load a specific file or a glob of files, idempotently. Absolute
+#   paths, relative paths, and globs are all accepted.
+#
+# import_up(name)
+#   Walk CWD and every ancestor directory looking for `name`, then
+#   import it. Useful inside a nested task file that needs to pull in
+#   a shared config from the project root without knowing how deep it is.
+#
+# loki_up(name)
+#   Same walk as import_up but just returns the absolute path (or nil)
+#   without loading it — handy when you need the path for another purpose.
+
+# Load all *.loki files in this directory (kitchen_sink, concurrent, etc.)
+import "*.loki"
+
+# Load a task file from a subdirectory.
+# import also accepts a direct path, not just a glob.
+import "subdir/import_demo.loki"

data/examples/concurrent.loki

@@ -21,12 +21,12 @@ $stdout.sync = true   # flush every print immediately across all threads
 CONCURRENT_REPS = 10  # how many times each worker prints its character
 
 class Tasks
-  desc "start", "Print start marker"
+  desc "Print start marker"
   def start
     puts "starting demo of concurrent task execution ..."
   end
 
-  desc "worker_a", "Print 'A' repeatedly with random delays"
+  desc "Print 'A' repeatedly with random delays"
   def worker_a
     CONCURRENT_REPS.times do
       print "A"
@@ -34,7 +34,7 @@ class Tasks
     end
   end
 
-  desc "worker_b", "Print 'B' repeatedly with random delays"
+  desc "Print 'B' repeatedly with random delays"
   def worker_b
     CONCURRENT_REPS.times do
       print "B"
@@ -42,7 +42,7 @@ class Tasks
     end
   end
 
-  desc "worker_c", "Print 'C' repeatedly with random delays"
+  desc "Print 'C' repeatedly with random delays"
   def worker_c
     CONCURRENT_REPS.times do
       print "C"
@@ -51,7 +51,7 @@ class Tasks
   end
 
   depends_on :start, [:worker_a, :worker_b, :worker_c]
-  desc "finish", "Print end marker after all workers complete"
+  desc "Print end marker after all workers complete"
   def finish
     puts "\nfini - the end of concurrent task demo"
   end

data/examples/db_subcommands.loki

@@ -39,7 +39,7 @@ class DBCommands < Tasks
   # depends_on chains within the subcommand group:
   #   rollback → migrate → seed → reset
   depends_on :rollback, :migrate, :seed
-  desc "reset", "Rollback all migrations, re-migrate, and reseed"
+  desc "Rollback all migrations, re-migrate, and reseed"
   def reset
     puts "Database reset complete."
   end
@@ -54,7 +54,7 @@ class DBCommands < Tasks
       asgard db console\x5
       asgard db console --env staging
   DESC
-  desc "console", "Open an interactive database console"
+  desc "Open an interactive database console"
   option :env, type: :string, default: "development",
                enum:  %w[development staging production],
                desc:  "Environment to connect to"
@@ -62,7 +62,7 @@ class DBCommands < Tasks
     puts "Opening #{options[:env]} database console..."
   end
 
-  desc "status", "Show applied and pending migrations"
+  desc "Show applied and pending migrations"
   def status
     puts "Checking migration status..."
   end

data/examples/env_usage.loki

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# Demonstrates the env() Kernel helper for reading system environment variables.
+#
+# env() is cleaner than ENV[] — it accepts symbols or strings, upcases
+# automatically, and raises KeyError when a required variable is missing
+# rather than silently returning nil.
+#
+# Run from examples/ or any subdirectory — loki_up locates .env automatically:
+#   asgard env_demo
+
+class Tasks
+  # loki_up walks CWD and every ancestor until it finds .env, returning
+  # its absolute path. This works regardless of which directory asgard
+  # is run from — no hardcoded relative path needed.
+  dotenv loki_up(".env") || ".env"
+
+  desc "Print environment variable values resolved via env()"
+  def env_demo
+    puts <<~OUT
+      APP_NAME     : #{env(:app_name)}
+      PORT         : #{env(:port)}
+      API_KEY      : #{env(:api_key)}
+      DATABASE_URL : #{env(:database_url)}
+      LOG_LEVEL    : #{env(:log_level, "info")}
+    OUT
+  end
+end