asgard 0.1.1 → 0.2.0

data/docs/tasks.md

@@ -0,0 +1,284 @@
+# 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 "hello", "Say hello"
+  def hello = sh 'echo "Hello, World!"'
+end
+```
+
+`desc` takes two arguments: the usage string and the one-line description shown in `asgard help`.
+
+```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")
+    sh "echo '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", "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", "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", "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 "report", "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 "greet", "Say hello (runs by default)"
+  def greet
+    puts "Hello from Asgard!"
+  end
+end
+```
+
+```bash
+asgard        # same as: asgard greet
+```
+
+---
+
+## 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 "version", "Print the version"
+  def version = puts Asgard::VERSION
+
+  desc "test", "Run tests"
+  def test = sh "bundle exec rake test"
+
+  desc "build", "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 = sh "echo '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}!'"
+```
+
+---
+
+## 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 "build", "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

@@ -0,0 +1,122 @@
+# 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.
+
+---
+
+## Static Value
+
+Pass the value directly as the second argument:
+
+```ruby
+class Tasks
+  var :app,  "myapp"
+  var :env,  "production"
+  var :port, 3000
+
+  desc "info", "Print app info"
+  def info
+    puts "#{app} running on port #{port} in #{env}"
+  end
+end
+```
+
+---
+
+## Lazy Lambda
+
+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
+class Tasks
+  var :version, -> { `git describe --tags`.strip }
+  var :sha,     -> { `git rev-parse --short HEAD`.strip }
+
+  desc "tag", "Create a release tag"
+  def tag = sh "git tag v#{version}"
+
+  desc "info", "Show version info"
+  def info = puts "#{version} (#{sha})"
+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.
+
+---
+
+## Block Syntax
+
+You can also use a block instead of a lambda:
+
+```ruby
+class Tasks
+  var(:build_dir) { "builds/#{app}" }
+  var(:app)       { "myapp" }
+
+  desc "build", "Compile into build_dir"
+  def build = sh "rake build OUTDIR=#{build_dir}"
+end
+```
+
+!!! note
+    The block form and the lambda form behave identically — both are stored as callables and invoked on first access.
+
+---
+
+## Accessing Variables from Tasks
+
+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
+  var :app,     "myapp"
+  var :version, -> { `git describe --tags`.strip }
+  var :pkg,     -> { "pkg/#{app}-#{version}.gem" }
+
+  desc "build", "Build the gem"
+  def build = sh "gem build #{app}.gemspec"
+
+  desc "push", "Push the gem to RubyGems"
+  def push = sh "gem push #{pkg}"
+end
+```
+
+Variables can reference other variables in their lambdas as long as the referenced variable is also defined with `var` on the same class.
+
+---
+
+## Sharing Variables 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:
+
+```ruby
+# config.loki
+class Tasks
+  var :app,  "myapp"
+  var :port, 8080
+end
+
+# deploy.loki
+class Tasks
+  desc "deploy", "Deploy the app"
+  def deploy = sh "cap deploy APP=#{app} PORT=#{port}"
+end
+```
+
+---
+
+## Naming Caution
+
+!!! 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.
+
+```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 }
+```
+
+Other names to avoid: `options`, `class_options`, `shell`, `invoke`, `invoke_command`.

data/examples/.loki

@@ -0,0 +1,2 @@
+# The .loki file can be empty if there are *.loki files define the tasks
+# they will be auto loaded.

data/examples/concurrent.loki

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+# Demonstrates concurrent task execution via parallel depends_on groups.
+#
+# Each worker prints its letter repeatedly with random delays. Because
+# worker_a, worker_b, and worker_c run in separate threads their output
+# interleaves on stdout, proving real concurrency.
+#
+# Execution order:
+#   start → worker_a + worker_b + worker_c (all three concurrent) → finish
+#
+# Run with:
+#   asgard finish
+#
+# Sample output (character order varies every run):
+#   start
+#   ABCBACBACBABCBACBACB
+#   end
+
+$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"
+  def start
+    puts "starting demo of concurrent task execution ..."
+  end
+
+  desc "worker_a", "Print 'A' repeatedly with random delays"
+  def worker_a
+    CONCURRENT_REPS.times do
+      print "A"
+      sleep rand(0.05..0.3)
+    end
+  end
+
+  desc "worker_b", "Print 'B' repeatedly with random delays"
+  def worker_b
+    CONCURRENT_REPS.times do
+      print "B"
+      sleep rand(0.05..0.3)
+    end
+  end
+
+  desc "worker_c", "Print 'C' repeatedly with random delays"
+  def worker_c
+    CONCURRENT_REPS.times do
+      print "C"
+      sleep rand(0.05..0.3)
+    end
+  end
+
+  depends_on :start, [:worker_a, :worker_b, :worker_c]
+  desc "finish", "Print end marker after all workers complete"
+  def finish
+    puts "\nfini - the end of concurrent task demo"
+  end
+end

data/examples/db_subcommands.loki

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# Demonstrates Thor subcommands with Asgard's depends_on chaining within
+# the subcommand group. Inherits from Tasks for full Asgard DSL access.
+#
+# Usage:
+#   asgard db               # shows subcommand help
+#   asgard db migrate
+#   asgard db migrate 20240101120000 --dry-run
+#   asgard db rollback
+#   asgard db rollback 3
+#   asgard db seed --file db/seeds/staging.rb
+#   asgard db reset         # runs: rollback → migrate → seed
+#   asgard db console --env staging
+#   asgard db status
+
+class DBCommands < Tasks
+  desc "migrate [VERSION]", "Run pending migrations up to VERSION"
+  option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Print SQL without executing"
+  option :verbose, aliases: "-v", type: :boolean, default: false, desc: "Show each migration as it runs"
+  def migrate(version = nil)
+    target = version ? "to version #{version}" : "to latest"
+    puts "Migrating #{target}#{options[:dry_run] ? " (dry run)" : ""}..."
+  end
+
+  desc "rollback [STEPS]", "Roll back the last STEPS migrations (default: 1)"
+  option :dry_run, aliases: "-n", type: :boolean, default: false, desc: "Print SQL without executing"
+  def rollback(steps = "1")
+    puts "Rolling back #{steps} migration(s)#{options[:dry_run] ? " (dry run)" : ""}..."
+  end
+
+  desc "seed [FILE]", "Load seed data into the database"
+  option :env, type: :string, default: "development",
+               enum:  %w[development staging production],
+               desc:  "Environment to seed"
+  def seed(file = "db/seeds.rb")
+    puts "Seeding #{options[:env]} from #{file}..."
+  end
+
+  # 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"
+  def reset
+    puts "Database reset complete."
+  end
+
+  long_desc <<~DESC
+    Opens an interactive SQL console connected to the configured database.
+
+    The console inherits credentials from the current environment's
+    database.yml (Rails) or DATABASE_URL.
+
+    Examples:\x5
+      asgard db console\x5
+      asgard db console --env staging
+  DESC
+  desc "console", "Open an interactive database console"
+  option :env, type: :string, default: "development",
+               enum:  %w[development staging production],
+               desc:  "Environment to connect to"
+  def console
+    puts "Opening #{options[:env]} database console..."
+  end
+
+  desc "status", "Show applied and pending migrations"
+  def status
+    puts "Checking migration status..."
+  end
+end
+
+class Tasks
+  desc "db SUBCOMMAND", "Manage the database"
+  subcommand "db", DBCommands
+end