asgard 0.5.1 → 0.6.0

data/docs/options.md

@@ -1,224 +0,0 @@
-# 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 four built-in `class_option` declarations on `Tasks`: `--debug`, `--verbose`, `--version`, and `--doctor`.
-
----
-
-## 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`.
-
-### Boolean class options and `no_negate`
-
-Thor automatically generates `[--no-name]` and `[--skip-name]` help entries alongside every boolean `class_option`. When negation is meaningful — `--dry-run` paired with `--no-dry-run` — this is useful. When negation is meaningless, call `no_negate` immediately after the declaration to remove the extra variants from the help output:
-
-```ruby
-class Tasks
-  class_option :color,
-               type:    :boolean,
-               default: true,
-               desc:    "Colorize output"
-  no_negate :color
-end
-```
-
-Help output before `no_negate`:
-
-```
-[--color], [--no-color], [--skip-color]  # Colorize output
-```
-
-Help output after `no_negate`:
-
-```
-[--color]                                # Colorize output
-```
-
-`no_negate` accepts multiple option names in a single call:
-
-```ruby
-no_negate :color, :version, :emoji
-```
-
-It has no effect on runtime behaviour — `--no-color` still works on the CLI; only the help display is affected.
-
----
-
-## Built-in Flags
-
-`Tasks` ships with four built-in `class_option` declarations — `--debug`, `--verbose`, `--version`, and `--doctor` — all visible in the Options section of `asgard help`.
-
-### `--version`
-
-A `class_option :version` of type `:boolean`. Prints `Asgard::VERSION` and exits. Handled by `Asgard.run!` before the `.loki` file is loaded, so it works even in a directory without a `.loki` file. `no_negate :version` suppresses the `[--no-version]` / `[--skip-version]` variants (see [Boolean class options and `no_negate`](#boolean-class-options-and-no_negate) above):
-
-```bash
-asgard --version
-# 0.3.0
-```
-
-### `--doctor`
-
-A `class_option :doctor` of type `:boolean`. Diagnoses `.loki` resolution, import chains, and task definitions for the current directory, then exits. Handled by `Asgard.run!` before the `.loki` file is loaded (same pattern as `--version`) — deliberately so, since it needs to keep working in the exact situations that would otherwise abort `run!`: a broken `.loki` file, a circular or undefined dependency, or a task silently redefined by a later `def`. The report includes a "Tasks by file" listing — every command grouped by the file it's defined in, as `file:line` — with any silently-overridden task called out inline, right where it's defined. `no_negate :doctor` suppresses the `[--no-doctor]` / `[--skip-doctor]` variants:
-
-```bash
-asgard --doctor
-```
-
-See [`Asgard::Doctor` in the API Reference](api.md#asgarddoctor) for the full breakdown of what it checks.
-
-### `--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 _something
-# asgard: unknown command '_something'
-```
-
-If you define your own methods on `Tasks`, avoid the `_` prefix to prevent them from being blocked. Built-in `class_option` declarations (like `--version`, `--debug`, `--verbose`, `--doctor`) do not use the `_` prefix because they are options, not commands.

data/docs/schedule.md

@@ -1,106 +0,0 @@
-# Scheduled Tasks
-
-Asgard can run any task on a schedule. You declare schedules in the project's own `.loki`, and `asgard schedule install` hands them to the platform's own scheduler: **launchd** on macOS, **systemd user timers** on Linux. Both schedulers run a calendar job that was missed while the machine slept as soon as it wakes.
-
-Scheduling is built into the gem, so there is nothing to import or require.
-
----
-
-## Declaring Schedules
-
-Call `schedule` at class level inside `Tasks`:
-
-```ruby
-# .loki
-class Tasks
-  desc "daily_summary", "Summarize the day's work"
-  def daily_summary = sh "bin/summary"
-
-  schedule :daily_summary, at: "17:30", on: :weekdays
-  schedule :weekly_report, at: "16:00", on: :friday
-  schedule :sync,          every: 3600                 # seconds
-  schedule :backup,        at: %w[02:00 14:00]         # on: defaults to :daily
-
-  # The task's own options go in options:, split the way a shell would
-  # (quotes respected).
-  schedule :report, options: "--format md -v",  at: "08:00", on: :weekdays
-  schedule :report, options: "--period week",   at: "16:00", on: :friday
-  schedule :notify, options: "--msg 'backup done'", every: 86_400, as: "notify_daily"
-end
-```
-
-A declaration needs exactly one of `at:` or `every:`.
-
-| Keyword | Meaning |
-|---------|---------|
-| `at:` | `"HH:MM"` (24-hour), or an Array of times |
-| `on:` | `:daily` (default), `:weekdays`, `:weekends`, a day (`:friday`), or an Array of days |
-| `every:` | Interval in seconds, or anything that responds to `in_seconds` (an ActiveSupport `Duration`) |
-| `options:` | The task's own arguments, as a String (split shell-style) or an Array of words |
-| `env:` | `{ "KEY" => "value" }`: literal environment variables added to the job |
-| `as:` | The entry's name (letters, digits, `_ . -`) |
-
-### Entry Names
-
-Every entry has a name, and the subcommands below take it as `NAME`. The name defaults to the task name. When the entry has `options:`, the default is a slug of the task plus its options (`:report, options: "--format md -v"` becomes `report-format-md-v`), so one task can be scheduled several times with different flags. `as:` overrides the default. Declaring two *different* entries with the same name raises an error.
-
-### Durations
-
-Asgard doesn't depend on ActiveSupport. If you want `every: 3.minutes`, require it yourself at the top of your `.loki`:
-
-```ruby
-require "active_support/core_ext/integer/time"
-
-class Tasks
-  schedule :sync, every: 15.minutes
-end
-```
-
----
-
-## Managing Schedules
-
-`schedule` is also a command with subcommands. They work the same way on both platforms:
-
-```bash
-asgard schedule preview        # print the job files install would write
-asgard schedule install        # load declared entries; drop entries no longer declared
-asgard schedule list           # this project's entries, state, last exit (--all: every project's)
-asgard schedule stop NAME      # stop one entry (stays stopped across reboots and installs)
-asgard schedule start NAME     # start a stopped entry, or install just this one
-asgard schedule trigger NAME   # run an installed entry now, under the scheduler
-asgard schedule log NAME [-f]  # print the entry's log (-f keeps following it)
-asgard schedule remove         # unload and delete all of this project's entries
-```
-
-`stop`, `start`, `trigger` and `log` also accept an entry of another project, so
-they work from any directory. Use the name shown by `list --all`; if two projects
-have an entry with the same name, write it as `project/name` (this project's own
-entry wins a bare name).
-
-Re-run `asgard schedule install` after changing declarations or your `PATH`.
-
----
-
-## How Jobs Run
-
-Each entry runs `asgard <task> [options]` from the directory that holds `.loki`, so installing from any subdirectory gives the same result. The job gets the `PATH` that was current when you ran `install`, plus any `env:` variables.
-
-If the project has a `.envrc`, the job runs under `direnv exec`, so API keys and other secrets load from `.envrc` at run time and are never copied into the job files. If `direnv` isn't on your `PATH`, `install` warns that `.envrc` will not be loaded.
-
-Entries are scoped to the project (the name of the directory holding `.loki`), so `list`, `install` and `remove` only touch this project's jobs.
-
-| | macOS (launchd) | Linux (systemd) |
-|---|---|---|
-| Job files | `~/Library/LaunchAgents/com.madbomber.asgard.<project>.<name>.plist` | `~/.config/systemd/user/asgard.<project>.<name>.{service,timer}` |
-| Logs | `~/Library/Logs/asgard/` | `~/.local/state/asgard/` (honors `XDG_STATE_HOME`) |
-| Stop | `launchctl disable` | `systemctl --user disable --now` |
-| Caveats | runs only while you're logged in | runs only while you're logged in unless `loginctl enable-linger`; needs systemd 240+ |
-
-Other platforms aren't supported. The `schedule` subcommands there exit with an error.
-
----
-
-## Name Collisions
-
-The built-in command is registered as `_schedule` and mapped to `schedule`, following Asgard's `_` convention for gem-owned tasks. If your `.loki` defines its own `schedule` task, `asgard schedule` still dispatches to the built-in command.

data/docs/shell.md

@@ -1,237 +0,0 @@
-# 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` also accepts `exec: true` to replace the asgard process outright instead of forking — see [Handing Off with `exec`](#handing-off-with-exec).
-
----
-
-## `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
-```
-
-### Handing Off with `exec`
-
-Pass `exec: true` to hand the command the asgard process itself instead of forking a child. Under the hood this calls `Kernel.exec` rather than `system`, which replaces the running ruby process image with the command — asgard doesn't stick around waiting on it.
-
-Use this for a task's final, long-running command — a dev server, a REPL, anything meant to take over the terminal — so there's no idle ruby process sitting in memory alongside it, and Ctrl-C is handled directly by the command instead of unwinding back through asgard:
-
-```ruby
-class Tasks
-  desc "Documentation server startup"
-  depends_on :doc_builder
-  def doc_server = sh "mkdocs serve", exec: true
-end
-```
-
-Since the process is replaced, nothing after the `sh` call ever runs, and `depends_on` chains upstream of it must already have finished (they have — dependencies run before the task body).
-
-```ruby
-class Tasks
-  desc "Start a REPL — never returns to asgard"
-  def console
-    sh "bundle exec pry", exec: true
-    puts "unreachable"
-  end
-end
-```
-
-!!! note
-    `exec: true` only makes sense for a command meant to run for the lifetime of the process. Don't use it for a step with more work queued after it in the same task.
-
----
-
-## `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
-```