asgard 0.5.1 → 0.6.0

data/docs/tasks.md

@@ -1,326 +0,0 @@
-# Defining Tasks
-
-Every task is a public method inside `class Tasks`. Asgard pre-defines `Tasks` as a subclass of `Asgard::Base` (which is itself a Thor subclass), so your `.loki` files just reopen the class and add methods. The full Thor DSL is available everywhere.
-
----
-
-## Basic Task
-
-A task with no parameters and no options:
-
-```ruby
-class Tasks
-  desc "Say hello"
-  def hello = puts "Hello, World!"
-end
-```
-
-`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
-```
-
----
-
-## Positional Parameter with Default
-
-Positional parameters are declared directly in the method signature. Document them in the `desc` usage string (uppercase by convention):
-
-```ruby
-class Tasks
-  desc "greet NAME", "Greet NAME; omit NAME to greet the world"
-  def greet(name = "World")
-    puts "Hello, #{name}!"
-  end
-end
-```
-
-```bash
-asgard greet           # Hello, World!
-asgard greet Alice     # Hello, Alice!
-```
-
----
-
-## Named Options
-
-Use `method_option` (alias: `option`) for named flags. Access them inside the method via `options[:name]`.
-
-### All Five Option Types
-
-```ruby
-class Tasks
-  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 → #{options[:output]} with #{options[:jobs]} job(s)"
-    puts "Tags: #{options[:tags].join(', ')}" if options[:tags]
-    puts "Defines: #{options[:defines]}"      if options[:defines]
-  end
-end
-```
-
-### Option Types Reference
-
-| Type | CLI Example | Ruby Value |
-|---|---|---|
-| `:string` | `--output dist/` | `"dist/"` |
-| `:boolean` | `--verbose` / `--no-verbose` | `true` / `false` |
-| `:numeric` | `--jobs 4` | `4` |
-| `:array` | `--tags foo bar baz` | `["foo", "bar", "baz"]` |
-| `:hash` | `--defines KEY:val FOO:bar` | `{"KEY"=>"val", "FOO"=>"bar"}` |
-
-### Common Option Keys
-
-| Key | Description |
-|---|---|
-| `aliases` | Short-form flag, e.g. `"-o"` |
-| `type` | `:string`, `:boolean`, `:numeric`, `:array`, or `:hash` |
-| `default` | Value used when the flag is omitted |
-| `required` | If `true`, Thor raises an error when the flag is missing |
-| `desc` | One-line description shown in help |
-| `enum` | Array of allowed values; Thor validates automatically |
-| `banner` | Placeholder shown in help for the value slot, e.g. `"SECONDS"` |
-
----
-
-## Required Option
-
-```ruby
-class Tasks
-  desc "deploy ENV", "Deploy to ENV"
-  option :strategy,
-         type:     :string,
-         required: true,
-         enum:     %w[blue-green rolling canary],
-         desc:     "Deployment strategy"
-  def deploy(env = "staging")
-    sh "cap #{env} deploy --strategy #{options[:strategy]}"
-  end
-end
-```
-
-```bash
-asgard deploy          # Error: required option '--strategy' is missing
-asgard deploy --strategy rolling
-asgard deploy production --strategy blue-green
-```
-
----
-
-## Enum Validation
-
-```ruby
-class Tasks
-  desc "Build the project"
-  option :env,
-         type:    :string,
-         default: "development",
-         enum:    %w[development staging production],
-         desc:    "Target environment"
-  def build
-    sh "rake build ENV=#{options[:env]}"
-  end
-end
-```
-
-Thor validates the value against the enum and shows a helpful error if it doesn't match.
-
----
-
-## Banner
-
-`banner` replaces the default `VALUE` placeholder in help output with a more descriptive name:
-
-```ruby
-class Tasks
-  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]}"
-  end
-end
-```
-
-Help output shows: `[--timeout=SECONDS]` instead of `[--timeout=VALUE]`.
-
----
-
-## Extended Description
-
-`long_desc` provides detailed help shown by `asgard help <task>`. Use `\x5` at the start of a line to force a line break within the wrapped text (a Thor convention):
-
-```ruby
-class Tasks
-  long_desc <<~DESC
-    Generates a project report covering test coverage, lint results,
-    and a dependency audit.
-
-    Pass --format to control output style. Use --since to scope the
-    report to changes after a given date.
-
-    Examples:\x5
-      asgard report --format html --since 2024-01-01\x5
-      asgard report --format json --output report.json\x5
-      asgard report --format text
-  DESC
-  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
-    sh "generate-report --format #{options[:format]}"
-  end
-end
-```
-
-!!! tip
-    `desc` and `depends_on` are independent of each other — either can come first, but both must appear before the `def`.
-
----
-
-## Default Task
-
-`default_task` declares which command runs when `asgard` is invoked with no arguments:
-
-```ruby
-class Tasks
-  default_task :greet
-
-  desc "Say hello (runs by default)"
-  def greet
-    puts "Hello from Asgard!"
-  end
-end
-```
-
-```bash
-asgard        # same as: asgard greet
-```
-
-Without `default_task`, running `asgard` with no arguments displays the help message.
-
----
-
-## Abbreviated Command Matching
-
-Every task is a Thor command, and Thor resolves any unambiguous prefix of a command name to that command automatically — no Asgard code involved, and nothing to declare. Given:
-
-```ruby
-class Tasks
-  desc "Check code style with RuboCop"
-  def rubocop_check = sh "bundle exec rubocop"
-
-  desc "Run the test suite"
-  def test_check = sh "bundle exec rake test"
-
-  desc "Run the test suite with verbose output"
-  def test_verbose = sh "bundle exec rake test -v"
-
-  desc "Deploy to production"
-  def deploy = sh "cap production deploy"
-
-  desc "Deploy to staging"
-  def deploy_staging = sh "cap staging deploy"
-end
-```
-
-```bash
-asgard r             # same as: asgard rubocop_check — the only task starting with "r"
-asgard test_c        # same as: asgard test_check     — enough of the name to be unique
-asgard test          # Ambiguous command test matches [test_check, test_verbose]
-asgard deploy        # runs deploy, not deploy_staging — see below
-```
-
-Thor matches on a plain prefix (`command_name.start_with?(typed_string)`), so the shortest string that is still unique for your task set works. Two details worth knowing:
-
-- **An exact full name always wins**, even if it's also a prefix of another task. `asgard deploy` runs `deploy` itself, never the ambiguous-prefix error, because `deploy` is a defined command — not merely a prefix of `deploy_staging`.
-- **An ambiguous prefix produces a clean error listing every candidate** (`Ambiguous command X matches [...]`) rather than guessing or running the alphabetically-first match. Type enough of the name to disambiguate.
-
-!!! tip
-    Because matching depends on every task name currently defined, a short prefix that's unique today can become ambiguous tomorrow when a new task with the same stem is added — e.g. adding `rubocop_fix` alongside `rubocop_check` turns `asgard r` from a clean match into `Ambiguous command r matches [rubocop_check, rubocop_fix]`. Use [`map`](#command-aliases) below for a short name you want to guarantee stays stable regardless of what other tasks get added later.
-
----
-
-## Command Aliases
-
-`map` creates short aliases for existing tasks:
-
-```ruby
-class Tasks
-  map "-v"  => "version"
-  map "--v" => "version"
-  map "t"   => "test"
-  map "b"   => "build"
-
-  desc "Print the version"
-  def version = puts Asgard::VERSION
-
-  desc "Run tests"
-  def test = sh "bundle exec rake test"
-
-  desc "Build the gem"
-  def build = sh "bundle exec rake build"
-end
-```
-
-```bash
-asgard t      # same as: asgard test
-asgard b      # same as: asgard build
-asgard -v     # same as: asgard version (note: --version is the built-in flag)
-```
-
----
-
-## Formal Argument Declaration
-
-`argument` provides rich positional-parameter metadata including type checking, enums, and help text.
-
-!!! warning "Class-level scope"
-    `argument` is a **class-level declaration** that applies to **every task in the class**, not just the one that follows it. It is best suited for single-command CLIs or when every task in the file genuinely shares the same positional input. In multi-task files, prefer method signature parameters instead.
-
-```ruby
-class Tasks
-  argument :name,
-           type:    :string,
-           default: "World",
-           desc:    "Name to greet"
-
-  desc "hello NAME", "Say hello to 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") = puts "Hello, #{name}!"
-```
-
----
-
-## No Commands Block
-
-`no_commands` marks a block of methods as public helpers that are excluded from the CLI and `--help` output. They are callable from any task in the same class:
-
-```ruby
-class Tasks
-  desc "Compile the project"
-  def build
-    puts "Revision: #{current_sha}"
-    sh "rake build"
-  end
-
-  no_commands do
-    def current_sha
-      `git rev-parse --short HEAD`.strip
-    end
-  end
-end
-```
-
-See [Helper Methods](helpers.md) for the full guide on helpers, `private`, and cross-file sharing.

data/docs/variables.md

@@ -1,338 +0,0 @@
-# Variables
-
-Asgard task files are plain Ruby. Shared configuration values are declared using Ruby class variables (`@@name`) at the top of the `Tasks` class body.
-
----
-
-## Ruby Variable Types
-
-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
-  @app = "myapp"   # class instance variable — lives on the Tasks class object
-
-  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.
-
----
-
-## Strings and Interpolation
-
-### Always use double quotes
-
-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
-  @@app  ||= "myapp".freeze
-  @@env  ||= "production".freeze
-
-  desc "Deploy the app"
-  def deploy
-    sh "cap #{@@env} deploy APP=#{@@app}"
-  end
-end
-```
-
-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
-```
-
-Interpolation works inside heredocs the same as in double-quoted strings.
-
----
-
-## System Environment Variables
-
-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
-  desc "Start the server"
-  def start
-    sh "puma -p #{env(:port, '3000')} -e #{env(:rack_env, 'development')}"
-  end
-
-  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
-    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).
-
----
-
-## The Pattern
-
-```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
-  @@app ||= "myapp".freeze
-end
-
-# deploy.loki
-class DeployCommands < Tasks
-  desc "Deploy to production"
-  def production
-    sh "cap production deploy APP=#{@@app}"  # @@app is visible here
-  end
-end
-
-class Tasks
-  desc "deploy SUBCOMMAND", "Deployment tasks"
-  subcommand "deploy", DeployCommands
-end
-```
-
----
-
-## 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 Values Across Files
-
-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
-  @@app  ||= "myapp".freeze
-  @@port ||= 8080
-end
-
-# deploy.loki
-class Tasks
-  desc "Deploy the app"
-  def deploy = sh "cap deploy APP=#{@@app} PORT=#{@@port}"
-end
-```
-
----
-
-## Naming Conventions
-
-Class variable names use `snake_case` — the standard Ruby convention for variables and methods:
-
-```ruby
-class Tasks
-  @@app_name    ||= "myapp".freeze
-  @@deploy_host ||= "production.example.com".freeze
-  @@max_workers ||= 4
-end
-```
-
-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`.