asgard 0.2.0 → 0.3.0

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

data/examples/kitchen_sink.loki

@@ -5,9 +5,20 @@
 # install, release) so this file can be loaded alongside them without conflict.
 
 class Tasks
-  # ── Asgard: var — static value and lazy lambda ─────────────────────────────
-  var :app_name,  "my_app"
-  var :build_dir, -> { "builds/#{app_name}" }
+  # ── Ruby class variables — shared across all tasks and subcommands ──────────
+  @@app_name  ||= "my_app".freeze
+  @@build_dir ||= "builds/#{@@app_name}".freeze
+
+  # ── Computed values — plain private methods replace the removed var DSL ──────
+  # Declare as private so Thor does not try to register them as commands.
+  # Use @ivar ||= inside the method body to memoize expensive calls.
+  private
+
+  def version = `git describe --tags --always`.strip
+  def sha     = `git rev-parse --short HEAD`.strip
+  def branch  = @branch ||= `git rev-parse --abbrev-ref HEAD`.strip
+
+  public
 
   # ── Asgard: dotenv — load environment variables ────────────────────────────
   # Uncomment to activate:
@@ -37,9 +48,9 @@ class Tasks
   map "pl" => :pipeline
 
   # ── Basic task — no parameters ─────────────────────────────────────────────
-  desc "greet", "Say hello (default task when no command is given)"
+  desc "Say hello (default task when no command is given)"
   def greet
-    puts "Hello from #{app_name} (#{options[:env]})!"
+    puts "Hello from #{@@app_name} #{version} (#{branch}) in #{options[:env]} mode!"
   end
 
   # ── Positional parameter with default ──────────────────────────────────────
@@ -72,14 +83,14 @@ class Tasks
   end
 
   # ── method_option — all five option types ──────────────────────────────────
-  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"
   option :tags,                   type: :array,                              desc: "Build tags to apply"
   option :defines,                type: :hash,                               desc: "Preprocessor defines (KEY:VALUE)"
   def compile
-    puts "Compiling #{app_name} → #{options[:output]}"
+    puts "Compiling #{@@app_name} → #{options[:output]}"
   end
 
   # ── required option + enum + banner ────────────────────────────────────────
@@ -99,7 +110,7 @@ class Tasks
          default: "main",
          desc:    "Git branch to deploy"
   def deploy(env = "staging")
-    puts "Deploying #{app_name}@#{options[:branch]} to #{env}..."
+    puts "Deploying #{@@app_name}@#{options[:branch]} to #{env}..."
   end
 
   # ── long_desc — extended help shown by `asgard help report` ────────────────
@@ -115,7 +126,7 @@ class Tasks
       asgard report --format json --output report.json\x5
       asgard rp --format text
   LONGDESC
-  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"
   option :output, type: :string,                  banner: "FILE",            desc: "Write output to FILE"
@@ -124,30 +135,52 @@ class Tasks
   end
 
   # ── Asgard depends_on: sequential — analyze runs before spec ───────────────
-  desc "analyze", "Check code style and complexity"
+  desc "Check code style and complexity"
   def analyze = puts "Analyzing..."
 
   depends_on :analyze
-  desc "spec", "Run the test suite (depends on: analyze)"
+  desc "Run the test suite (depends on: analyze)"
   def spec = puts "Running specs..."
 
   # ── Asgard depends_on: parallel — analyze and typecheck run concurrently ───
-  desc "typecheck", "Run the type checker"
+  desc "Run the type checker"
   def typecheck = puts "Type checking..."
 
   depends_on [:analyze, :typecheck]
-  desc "check", "Run analyze and typecheck in parallel"
+  desc "Run analyze and typecheck in parallel"
   def check = puts "All checks passed."
 
   # ── Asgard depends_on: mixed sequential + parallel ─────────────────────────
-  desc "pack", "Create distribution archive"
+  desc "Create distribution archive"
   def pack = puts "Packing..."
 
   #   check → compile+spec (parallel) → pack → pipeline
   depends_on :check, [:compile, :spec], :pack
-  desc "pipeline", "Full pipeline: check → compile+spec → pack"
+  desc "Full pipeline: check → compile+spec → pack"
   def pipeline = puts "Pipeline complete."
 
+  # ── Asgard: debug? / verbose? — Kernel predicates for conditional output ──────
+  # debug?   returns true when --debug is passed  (sets $DEBUG)
+  # verbose? returns true when --verbose is passed (sets $VERBOSE)
+  # Both are set by Asgard before invoke_command runs, so they are safe
+  # to read inside any task body.
+  #
+  # Run with:
+  #   asgard status --verbose
+  #   asgard status --debug
+  #   asgard status --verbose --debug
+  desc "Show application status"
+  def status
+    puts "#{@@app_name} is running in #{options[:env]} mode."
+    puts "  build dir : #{@@build_dir}" if verbose?
+    puts "  sha       : #{current_sha}" if verbose?
+    if debug?
+      puts "  $DEBUG    : #{$DEBUG.inspect}"
+      puts "  $VERBOSE  : #{$VERBOSE.inspect}"
+      puts "  options   : #{options.inspect}"
+    end
+  end
+
   # ── Thor: no_commands — public helper excluded from CLI and --help ──────────
   no_commands do
     def current_sha