asgard 0.1.2 → 0.3.0

data/docs/options.md

@@ -0,0 +1,180 @@
+# Options & Flags
+
+Asgard tasks use the full Thor option system. Options declared with `method_option` (alias: `option`) apply to a single task. Options declared with `class_option` apply to every task in the class. Asgard ships with three built-in `class_option` declarations on `Tasks`: `--debug`, `--verbose`, and `--version`.
+
+---
+
+## Per-Task Options
+
+`method_option` (or its alias `option`) declares an option for the immediately following task:
+
+```ruby
+class Tasks
+  desc "deploy ENV", "Deploy to ENV"
+  method_option :branch,
+                aliases: "-b",
+                type:    :string,
+                default: "main",
+                desc:    "Git branch to deploy"
+  method_option :dry_run,
+                aliases: "-n",
+                type:    :boolean,
+                default: false,
+                desc:    "Print commands without running"
+  def deploy(env = "staging")
+    if options[:dry_run]
+      puts "Would deploy #{options[:branch]} to #{env}"
+    else
+      sh "cap #{env} deploy BRANCH=#{options[:branch]}"
+    end
+  end
+end
+```
+
+Access option values inside the task body via `options[:name]` (a hash keyed by symbol).
+
+---
+
+## Class Options (Shared Across All Tasks)
+
+`class_option` defines an option available on every task in the class. Add your own to complement the built-in ones:
+
+```ruby
+class Tasks
+  class_option :dry_run,
+               aliases: "-n",
+               type:    :boolean,
+               default: false,
+               desc:    "Print commands without running"
+
+  class_option :env,
+               type:    :string,
+               default: "development",
+               enum:    %w[development staging production],
+               desc:    "Target environment"
+
+  desc "Deploy the application"
+  def deploy
+    if options[:dry_run]
+      puts "Would deploy to #{options[:env]}"
+    else
+      sh "cap #{options[:env]} deploy"
+    end
+  end
+
+  desc "Run database migrations"
+  def migrate
+    sh "rails db:migrate RAILS_ENV=#{options[:env]}"
+  end
+end
+```
+
+Both `deploy` and `migrate` automatically accept `--dry-run` and `--env`.
+
+---
+
+## Built-in Flags
+
+`Tasks` ships with three built-in class options and a version flag:
+
+### `--version`
+
+Prints `Asgard::VERSION` and exits. Implemented as the `_version` method with the `_` prefix convention (gem-owned, blocked from direct CLI invocation):
+
+```bash
+asgard --version
+# 0.1.2
+```
+
+### `--debug`
+
+A `class_option :debug` of type `:boolean`. When passed, sets `$DEBUG = true` before the task body runs (via the `invoke_command` hook in `Asgard::Base`):
+
+```bash
+asgard build --debug
+```
+
+Inside the task, use the `debug?` predicate:
+
+```ruby
+def build
+  sh "rake build"
+  sh "rake build --trace" if debug?
+end
+```
+
+### `--verbose`
+
+A `class_option :verbose` of type `:boolean`. When passed, sets `$VERBOSE = true` before the task body runs:
+
+```bash
+asgard test --verbose
+```
+
+Inside the task, use the `verbose?` predicate:
+
+```ruby
+def test
+  flags = verbose? ? "--verbose" : ""
+  sh "bundle exec rake test #{flags}"
+end
+```
+
+---
+
+## `debug?` and `verbose?` Predicates
+
+Both are private methods on `Tasks`, thin wrappers around the global variables:
+
+```ruby
+private
+
+def debug?   = $DEBUG
+def verbose? = $VERBOSE
+```
+
+They are available in every task body and in subcommand classes that inherit from `Tasks`. Because `--debug` and `--verbose` are `class_option` declarations (not standalone commands), they work as modifiers alongside any task:
+
+```bash
+asgard build --debug --verbose
+asgard deploy production --verbose
+```
+
+---
+
+## Option Types Reference
+
+| Type | CLI Example | Ruby Value |
+|---|---|---|
+| `:string` | `--branch main` | `"main"` |
+| `:boolean` | `--force` / `--no-force` | `true` / `false` |
+| `:numeric` | `--count 3` | `3` |
+| `:array` | `--tags foo bar baz` | `["foo", "bar", "baz"]` |
+| `:hash` | `--vars KEY:val FOO:bar` | `{"KEY"=>"val", "FOO"=>"bar"}` |
+
+---
+
+## Option Keys Reference
+
+| Key | Applies to | Description |
+|---|---|---|
+| `aliases` | `method_option`, `class_option` | Short-form flag string, e.g. `"-b"` |
+| `type` | `method_option`, `class_option` | One of the five types above |
+| `default` | `method_option`, `class_option` | Value used when the flag is omitted |
+| `required` | `method_option` | Raises an error if the flag is missing |
+| `desc` | `method_option`, `class_option` | One-line description shown in help |
+| `enum` | `method_option`, `class_option` | Allowed values; validated by Thor |
+| `banner` | `method_option` | Placeholder shown in help for the value slot |
+
+---
+
+## `_` Prefix Convention
+
+Methods whose names start with `_` are considered gem-owned in Asgard's naming convention. `run!` guards against invoking them directly from the CLI:
+
+```bash
+asgard _version
+# asgard: unknown command '_version'
+```
+
+If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being silently blocked.

data/docs/shell.md

@@ -0,0 +1,208 @@
+# Shell Helpers
+
+Asgard provides two methods for running shell commands and scripts from within task bodies: `sh` for shell commands and heredocs, and `shebang` for polyglot scripts. Both are provided by `Asgard::Shell` and mixed into every `Tasks` instance.
+
+Both methods exit with the command's status code on failure — they do not raise Ruby exceptions.
+
+---
+
+## `sh` — Run Shell Commands
+
+### Single-Line Command
+
+Pass a single-line string to run it via `system`:
+
+```ruby
+class Tasks
+  desc "Compile the project"
+  def build = sh "rake build"
+
+  desc "Remove build artifacts"
+  def clean = sh "rm -rf dist/ tmp/"
+end
+```
+
+By default, `sh` prints the command before running it:
+
+```
+rake build
+```
+
+### Multi-Line Heredoc
+
+Pass a multiline string (e.g., a heredoc) to run it as a single `bash -c` script. All lines execute in the same shell session, so variable assignments carry across lines:
+
+```ruby
+class Tasks
+  desc "Bootstrap the development environment"
+  def setup
+    sh <<~SHELL
+      brew install redis postgresql
+      brew services start redis
+      bundle install
+      rails db:setup
+    SHELL
+  end
+end
+```
+
+Asgard detects the newline and automatically routes multiline scripts through `bash -c`.
+
+### Silent Mode
+
+Pass `silent: true` to suppress the command echo. The command still runs and still exits on failure; it just doesn't print the command text first:
+
+```ruby
+class Tasks
+  desc "Compile (quiet)"
+  def build = sh "rake build", silent: true
+
+  desc "Print environment info without noise"
+  def info
+    sh "printenv | grep APP_", silent: true
+  end
+end
+```
+
+### Exit on Failure
+
+`sh` always calls `exit($?.exitstatus)` if the command fails. There is no rescue path — a failing command terminates the `asgard` process. This is intentional: failed steps should stop the pipeline rather than silently continue.
+
+```ruby
+class Tasks
+  depends_on :test
+  desc "Test then release"
+  def release
+    sh "bundle exec rake release"
+    # Never reached if rake release fails
+    puts "Released!"
+  end
+end
+```
+
+---
+
+## `shebang` — Polyglot Scripts
+
+`shebang` writes the script body to a tempfile with the appropriate extension and executes it with the specified interpreter. Use it to embed Python, Node.js, Ruby, Perl, or any other interpreter directly in a task:
+
+### Python
+
+```ruby
+class Tasks
+  desc "Run Python data analysis"
+  def analyze
+    shebang :python3, <<~PYTHON
+      import json
+      data = json.load(open("results.json"))
+      print(f"Total: {sum(data.values())}")
+    PYTHON
+  end
+end
+```
+
+### Node.js
+
+```ruby
+class Tasks
+  desc "Build frontend assets with esbuild"
+  def bundle_assets
+    shebang :node, <<~JS
+      const esbuild = require("esbuild")
+      esbuild.buildSync({
+        entryPoints: ["src/app.js"],
+        bundle: true,
+        outfile: "dist/app.js"
+      })
+    JS
+  end
+end
+```
+
+### Ruby
+
+```ruby
+class Tasks
+  desc "Transform data with Ruby"
+  def transform
+    shebang :ruby, <<~RUBY
+      require "json"
+      data = JSON.parse(File.read("input.json"))
+      File.write("output.json", JSON.pretty_generate(data.transform_values(&:upcase)))
+    RUBY
+  end
+end
+```
+
+### Bash
+
+```ruby
+class Tasks
+  desc "Run a bash provisioning script"
+  def provision
+    shebang :bash, <<~BASH
+      set -euo pipefail
+      apt-get update
+      apt-get install -y curl wget git
+      echo "Provisioned at $(date)"
+    BASH
+  end
+end
+```
+
+---
+
+## Supported Interpreters
+
+| Symbol | File Extension | Interpreter |
+|---|---|---|
+| `:python3` | `.py` | `python3` |
+| `:python` | `.py` | `python` |
+| `:node` | `.js` | `node` |
+| `:ruby` | `.rb` | `ruby` |
+| `:perl` | `.pl` | `perl` |
+| `:bash` | `.sh` | `bash` |
+| `:sh` | `.sh` | `sh` |
+| Any other symbol | `.tmp` | Passed directly to `system` |
+
+!!! note
+    Unknown interpreter symbols get a `.tmp` extension and are passed to `system` directly. This makes it easy to use interpreters not in the table above:
+
+    ```ruby
+    shebang :lua, <<~LUA
+      print("Hello from Lua!")
+    LUA
+    ```
+
+### Silent Mode
+
+`shebang` also accepts `silent: true`, though in practice the interpreter itself controls what is printed:
+
+```ruby
+def analyze
+  shebang :python3, script_body, silent: true
+end
+```
+
+---
+
+## Combining `sh` and `shebang`
+
+You can mix both in the same task:
+
+```ruby
+class Tasks
+  desc "Run a mixed shell + Python pipeline"
+  def pipeline
+    sh "bundle exec rake build"
+
+    shebang :python3, <<~PYTHON
+      import subprocess
+      result = subprocess.run(["./bin/validate"], capture_output=True, text=True)
+      print(result.stdout)
+    PYTHON
+
+    sh "rake deploy"
+  end
+end
+```

data/docs/subcommands.md

@@ -0,0 +1,181 @@
+# Subcommands
+
+Subcommands group related tasks under a common namespace, giving you commands like `asgard server start` or `asgard db migrate`. Asgard uses Thor's `subcommand` method for this, with one important convention: subcommand classes inherit from `Tasks` rather than from `Asgard::Base` or `Thor` directly.
+
+---
+
+## Basic Pattern
+
+Define a subcommand class that inherits from `Tasks`, then register it on the top-level `Tasks` class with `subcommand`:
+
+```ruby
+class DeployCommands < Tasks
+  desc "Deploy to staging"
+  def staging = sh "cap staging deploy"
+
+  desc "Deploy to production"
+  def production = sh "cap production deploy"
+end
+
+class Tasks
+  desc "deploy SUBCOMMAND", "Deploy the application"
+  subcommand "deploy", DeployCommands
+end
+```
+
+```bash
+asgard deploy              # shows deploy subcommand help
+asgard deploy staging
+asgard deploy production
+```
+
+---
+
+## Why Inherit from `Tasks`?
+
+Inheriting from `Tasks` (rather than `Asgard::Base` or `Thor`) gives the subcommand class access to:
+
+- `sh` and `shebang` shell helpers (from `Asgard::Shell`)
+- `depends_on` for dependency declarations
+- `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`
+
+!!! warning
+    Do **not** redeclare `class_option :debug` or `class_option :verbose` in your subcommand class — they are already inherited from `Tasks`. Redeclaring them causes duplicate option errors.
+
+---
+
+## depends_on Within a Subcommand
+
+`depends_on` works exactly as at the top level, scoped to the subcommand's own dependency graph:
+
+```ruby
+class DBCommands < Tasks
+  desc "Run pending migrations"
+  def migrate = sh "rails db:migrate"
+
+  desc "Load seed data"
+  def seed = sh "rails db:seed"
+
+  depends_on :migrate, :seed
+  desc "Migrate then seed"
+  def reset = puts "Done."
+end
+
+class Tasks
+  desc "db SUBCOMMAND", "Manage the database"
+  subcommand "db", DBCommands
+end
+```
+
+```bash
+asgard db reset   # migrate → seed → reset
+```
+
+---
+
+## Server Subcommand Example
+
+```ruby
+class ServerCommands < Tasks
+  desc "start [PORT]", "Start the server on PORT (default: 3000)"
+  option :daemon,  aliases: "-d", type: :boolean, default: false, desc: "Run as a background daemon"
+  option :workers, aliases: "-w", type: :numeric, default: 2,     desc: "Number of worker processes"
+  option :log,                    type: :string,  default: "log/server.log",
+                                  banner: "FILE", desc: "Write logs to FILE"
+  def start(port = "3000")
+    flags = []
+    flags << "--daemon"              if options[:daemon]
+    flags << "--workers #{options[:workers]}"
+    flags << "--log #{options[:log]}"
+    sh "puma -p #{port} #{flags.join(' ')}"
+  end
+
+  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 "Show server status"
+  def status = sh "pumactl stats"
+
+  depends_on :stop, :start
+  desc "restart [PORT]", "Stop then start"
+  def restart(port = "3000") = puts "Server restarted on :#{port}."
+end
+
+class Tasks
+  desc "server SUBCOMMAND", "Manage the application server"
+  subcommand "server", ServerCommands
+end
+```
+
+```bash
+asgard server start
+asgard server start 4000 --workers 4 --daemon
+asgard server stop --force
+asgard server restart
+asgard server status
+```
+
+---
+
+## Scoped DSL
+
+Each subcommand class has its own independent scope for:
+
+- `desc` / `long_desc` — documentation strings
+- `method_option` / `option` — per-command options
+- `class_option` — options shared across the subcommand's tasks (in addition to inherited ones)
+- `map` — aliases within the subcommand group
+- `default_task` — which command runs when the subcommand is invoked with no further arguments
+- `depends_on` — dependency declarations scoped to this class
+
+These do not bleed into the parent `Tasks` class or other subcommand classes.
+
+---
+
+## Multiple Subcommands
+
+You can register as many subcommand groups as needed:
+
+```ruby
+class ServerCommands < Tasks
+  # ... server tasks ...
+end
+
+class DBCommands < Tasks
+  # ... database tasks ...
+end
+
+class DeployCommands < Tasks
+  # ... deploy tasks ...
+end
+
+class Tasks
+  desc "server SUBCOMMAND", "Manage the server";    subcommand "server", ServerCommands
+  desc "db SUBCOMMAND",     "Manage the database";  subcommand "db",     DBCommands
+  desc "deploy SUBCOMMAND", "Deploy";               subcommand "deploy", DeployCommands
+end
+```
+
+---
+
+## Subcommands Across Files
+
+Define each subcommand class in its own `.loki` file. Because all files reopen the same Ruby classes, the classes are available when `.loki` registers them:
+
+```
+myproject/
+  .loki                    ← registers all subcommands
+  server_subcommands.loki  ← defines ServerCommands
+  db_subcommands.loki      ← defines DBCommands
+```
+
+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.