asgard 0.5.1 → 0.6.0

data/docs/getting-started.md

@@ -1,181 +0,0 @@
-# Getting Started
-
-This guide walks you through installing Asgard, creating your first `.loki` task file, and running tasks from the command line.
-
----
-
-## Installation
-
-=== "RubyGems"
-
-    ```bash
-    gem install asgard
-    ```
-
-=== "Bundler"
-
-    ```bash
-    bundle add asgard
-    ```
-
-    Or add it manually to your `Gemfile`:
-
-    ```ruby
-    gem "asgard", "~> 0.1"
-    ```
-
-    then run `bundle install`.
-
----
-
-## Verify the Installation
-
-```bash
-asgard --version
-# 0.1.2
-```
-
----
-
-## Create Your First Task File
-
-Every Asgard project needs a `.loki` file at its root. This hidden file is both the project root marker (Asgard searches upward from CWD to find it) and the entry point for your tasks.
-
-```bash
-# Create the root marker in your project directory
-touch .loki
-```
-
-Open `.loki` in your editor and add a task:
-
-```ruby
-class Tasks
-  desc "Say hello to the world"
-  def hello = puts "Hello, World!"
-end
-```
-
-!!! note
-    The `Tasks` class is pre-defined by the gem as `class Tasks < Asgard::Base`. You just reopen it — no `require` or superclass declaration needed.
-
----
-
-## Run Your Task
-
-```bash
-asgard hello
-# Hello, World!
-```
-
-See all available tasks:
-
-```bash
-asgard help
-```
-
-See help for a specific task:
-
-```bash
-asgard help hello
-```
-
----
-
-## Add a Parameter
-
-Positional parameters are declared directly in the method signature. Document them in the `desc` usage string:
-
-```ruby
-class Tasks
-  desc "greet NAME", "Greet someone by name"
-  def greet(name = "World")
-    puts "Hello, #{name}!"
-  end
-end
-```
-
-```bash
-asgard greet
-# Hello, World!
-
-asgard greet Alice
-# Hello, Alice!
-```
-
----
-
-## Add an Option
-
-Use `method_option` (alias: `option`) to declare named flags:
-
-```ruby
-class Tasks
-  desc "greet NAME", "Greet someone by name"
-  option :shout, aliases: "-s", type: :boolean, desc: "Uppercase the greeting"
-  def greet(name = "World")
-    msg = options[:shout] ? "HELLO, #{name.upcase}!" : "Hello, #{name}!"
-    puts msg
-  end
-end
-```
-
-```bash
-asgard greet Alice --shout
-# HELLO, ALICE!
-```
-
----
-
-## Multi-Loki Structure
-
-A large Asgard project might look like this:
-
-```
-myproject/
-  .loki          ← root marker and entry point (may be empty or contain tasks)
-  build.loki     ← build-related and library dependency-related tasks
-  deploy.loki    ← deployment tasks
-  qa.loki        ← test and lint tasks
-```
-
-Each `*.loki` file reopens `class Tasks`. To load them, call `import "*.loki"` at the top of `.loki` — files are loaded in alphabetical order. See [Task Files](task-files.md) for full details.
-
----
-
-## Built-in Flags
-
-Every task automatically has four flags available, defined as `class_option` on `Tasks`:
-
-| Flag | Description |
-|---|---|
-| `--version` | Print the Asgard version and exit |
-| `--debug` | Set `$DEBUG = true` before the task runs |
-| `--verbose` | Set `$VERBOSE = true` before the task runs |
-| `--doctor` | Diagnose `.loki` resolution, imports, and task definitions for the CWD, then exit |
-
-```bash
-asgard --version
-asgard hello --debug
-asgard hello --verbose
-asgard --doctor
-```
-
-Inside a task body, use the `debug?` and `verbose?` predicates:
-
-```ruby
-def hello
-  puts "building..."
-  sh "make --debug" if debug?
-end
-```
-
----
-
-## Next Steps
-
-- [Defining Tasks](tasks.md) — parameters, options, aliases, long_desc
-- [Dependencies](dependencies.md) — sequential, parallel, and mixed dependency graphs
-- [Variables](variables.md) — share values across tasks
-- [Shell Helpers](shell.md) — `sh`, `shebang`, and polyglot scripts
-- [Subcommands](subcommands.md) — group related tasks under a namespace
-- [Examples](examples.md) — working `.loki` files for every feature

data/docs/helpers.md

@@ -1,262 +0,0 @@
-# Helper Methods
-
-Not every method needs to be a CLI command. Asgard (via Thor) provides two mechanisms to define callable helper methods that are excluded from `asgard help` and cannot be invoked directly from the command line.
-
----
-
-## Private Methods
-
-Methods declared after `private` are callable from any task in the same class but are invisible to Thor's command dispatcher. They will not appear in `--help` output and cannot be called from the CLI:
-
-```ruby
-class Tasks
-  desc "Compile and package"
-  def build
-    compile("src")
-    package(app_version)
-  end
-
-  desc "Build and publish to RubyGems"
-  def release
-    build
-    sh "gem push pkg/myapp-#{app_version}.gem"
-  end
-
-  private
-
-  def compile(dir)
-    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
-  end
-
-  def package(ver)
-    sh "tar czf pkg/myapp-#{ver}.tar.gz bin/"
-  end
-
-  def app_version
-    `git describe --tags`.strip
-  end
-end
-```
-
-!!! note
-    In Ruby, `private` applies to all methods defined after it in the same class body. You can group all helpers at the bottom of the class after a single `private` declaration.
-
----
-
-## The `no_commands` Block
-
-Thor's `no_commands` block marks public methods as excluded from CLI discovery. Unlike `private`, these methods are still publicly accessible from Ruby code (e.g., from a subclass or a module). They are useful for methods that must be public for technical reasons but should not appear as commands:
-
-```ruby
-class Tasks
-  desc "Compile the project"
-  def build
-    puts "Revision: #{current_sha}"
-    sh "rake build"
-  end
-
-  desc "Deploy to production"
-  def deploy
-    puts "Deploying revision #{current_sha}..."
-    sh "cap production deploy"
-  end
-
-  no_commands do
-    def current_sha
-      `git rev-parse --short HEAD`.strip
-    end
-
-    def timestamp
-      Time.now.strftime("%Y%m%d-%H%M%S")
-    end
-  end
-end
-```
-
----
-
-## The `helper` DSL Method
-
-`helper` is an Asgard DSL method that defines a helper available in **both class context and instance context** with a single declaration. It is the right tool when a value needs to be used inside a `header` or `footer` call (which execute at class load time) and also inside task instance methods.
-
-### The problem it solves
-
-Thor task methods run as instance methods. Class-level DSL calls like `header` and `footer` run as class methods. A plain `def` only creates an instance method, so it cannot be called inside `header`. Conversely, `def self.name` only creates a class method, so it cannot be called inside a task body without `self.class.name`.
-
-The manual workaround is verbose:
-
-```ruby
-class Tasks
-  @@project ||= "myapp".freeze
-
-  # class method for header/footer
-  def self.version
-    @@version ||= File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
-  end
-
-  # private instance method delegating to the class method
-  no_commands do
-    private def version = self.class.version
-  end
-
-  header "#{@@project} v#{version}"
-
-  desc "Show version"
-  def show_version = puts version
-end
-```
-
-`helper` replaces those six lines with one:
-
-```ruby
-class Tasks
-  @@project ||= "myapp".freeze
-
-  helper(:version) {
-    @@version ||= File.read("lib/myapp/version.rb").match(/VERSION\s*=\s*"([^"]+)"/)[1].freeze
-  }
-
-  header "#{@@project} v#{version}"
-
-  desc "Show version"
-  def show_version = puts version
-end
-```
-
-### Arguments
-
-`helper` supports any argument signature valid in a Ruby method definition: positional, keyword, default values, and blocks.
-
-```ruby
-# No arguments
-helper(:project_root) { loki_up.parent.to_s }
-
-# Positional arguments
-helper(:gem_path) { |name| "lib/#{name}/version.rb" }
-
-# Positional with default
-helper(:tag_prefix) { |sep = "-"| "#{@@project}#{sep}" }
-
-# Positional and keyword arguments
-helper(:format_version) { |name, version, prefix: "v", separator: "-"|
-  "#{prefix}#{name}#{separator}#{version}"
-}
-```
-
-Wrong argument counts or unknown keyword names raise the same `ArgumentError` Ruby raises for any method call — no special error handling needed.
-
-### Visibility
-
-`helper`-defined methods are:
-
-- **Excluded from `asgard help`** — they never appear as commands
-- **Blocked from CLI invocation** — cannot be called directly from the command line
-- **Private on the instance side** — not accessible from outside the class
-
-### When to use `helper`
-
-Use `helper` when the value or computation must be available in both a class-level DSL call (`header`, `footer`, a `@@var` initializer) and inside task instance methods. For helpers that are only needed inside task bodies, a plain `private` method is simpler.
-
----
-
-## Choosing Between `private` and `no_commands`
-
-| | `private` | `no_commands` |
-|---|---|---|
-| Hidden from `--help` | Yes | Yes |
-| Blocked from CLI | Yes | Yes |
-| Accessible from subclass | No | Yes |
-| Accessible from module include | No | Yes |
-| Ruby idiom | Familiar | Thor-specific |
-
-For most helpers, `private` is the right choice. Use `no_commands` when the helper must remain technically public (e.g., it will be inherited by a subcommand class).
-
----
-
-## Sharing Helpers Across Files
-
-### Within a project
-
-Extract shared helpers into a plain Ruby module and load it from `.loki` using `require_relative`:
-
-```ruby
-# shared/helpers.rb
-module BuildHelpers
-  private
-
-  def compile(dir)
-    sh "gcc -O2 -o bin/myapp #{dir}/*.c"
-  end
-
-  def dist_path(ver)
-    "pkg/myapp-#{ver}.tar.gz"
-  end
-end
-```
-
-```ruby
-# .loki
-require_relative "shared/helpers"
-
-class Tasks
-  include BuildHelpers
-
-  desc "Compile the project"
-  def build = compile("src")
-
-  desc "Create distribution archive"
-  def package = sh "tar czf #{dist_path(app_version)} bin/"
-end
-```
-
-Because `include` in the class body makes the module methods available as instance methods, and they are declared `private` inside the module, they remain invisible to Thor.
-
-!!! tip
-    Helpers in a shared module can call `sh`, `shebang`, and other Asgard DSL methods because those are included in `Tasks` (via `Asgard::Base` and `Asgard::Shell`) and are available in `self` when the module method is invoked.
-
-### Across projects with `import_up`
-
-If helpers are defined as tasks in a shared `.loki` file, use `import_up` to load them from any sub-project without knowing the absolute path:
-
-```
-~/sandbox/
-  shared_helpers.loki   ← defines helper tasks available to all sub-projects
-  projectA/
-    .loki
-  projectB/
-    .loki
-```
-
-```ruby
-# projectA/.loki  (and identically in projectB/.loki)
-import_up "shared_helpers.loki"
-
-class Tasks
-  # shared tasks are already defined in Tasks by here
-end
-```
-
-`import_up` walks up from `Dir.pwd` until it finds `shared_helpers.loki`, then loads it. It returns `false` without raising if the file is not found, making it safe to use in projects where the shared file may not always be present.
-
----
-
-## Helper Methods in Subcommands
-
-Subcommand classes that inherit from `Tasks` also inherit all private helpers and `no_commands` methods defined on `Tasks`. You can also define helpers local to the subcommand class:
-
-```ruby
-class DeployCommands < Tasks
-  desc "Deploy to staging"
-  def staging = deploy_to("staging")
-
-  desc "Deploy to production"
-  def production = deploy_to("production")
-
-  private
-
-  def deploy_to(env)
-    sh "cap #{env} deploy REV=#{current_sha}"
-  end
-  # current_sha is inherited from Tasks if defined there
-end
-```

data/docs/index.md

@@ -1,87 +0,0 @@
-# Asgard
-
-<table>
-<tr>
-<td width="40%" align="center" valign="top">
-<img src="assets/images/asgard.jpg" alt="Asgard" width="300"><br>
-<em>"Loki collects the tricks.<br>Thor of Asgard runs them."</em>
-</td>
-<td width="60%" valign="top">
-<strong>Key Features</strong>
-<ul>
-<li><strong>Thor-Powered CLI</strong> — every Thor DSL feature available inside <code>.loki</code> task files</li>
-<li><strong>Task Dependencies</strong> — sequential, parallel, and mixed dependency graphs via <code>depends_on</code></li>
-<li><strong>Concurrent Execution</strong> — parallel task groups run in native Ruby threads</li>
-<li><strong>Subcommands</strong> — group related tasks under a named namespace</li>
-<li><strong>Variables</strong> — shared configuration via Ruby class variables (<code>@@name</code>), visible across all tasks and subcommands</li>
-<li><strong>Shell Helpers</strong> — <code>sh</code> for any shell command or heredoc; <code>shebang</code> for polyglot scripts</li>
-<li><strong>Dotenv Support</strong> — load <code>.env</code> files into the environment with <code>dotenv</code></li>
-<li><strong>Auto-Discovery</strong> — <code>.loki</code> root marker searched from CWD upward through parent directories</li>
-<li><strong>Multi-File Tasks</strong> — split tasks across <code>*.loki</code> files loaded via <code>import</code></li>
-<li><strong>Scheduled Tasks</strong> — run any task periodically under launchd (macOS) or systemd timers (Linux) with <code>schedule</code> and <code>asgard schedule install</code></li>
-<li><strong>Watched Files</strong> — run any task when files change with <code>watch</code> and <code>asgard watcher start</code>; the task reads what changed through <code>changes</code></li>
-<li><strong>Built-in Flags</strong> — <code>--version</code>, <code>--debug</code>, <code>--verbose</code>, and <code>--doctor</code> available on every task</li>
-</ul>
-</td>
-</tr>
-</table>
-
-Asgard is a [Thor](https://github.com/rails/thor)-based task runner for Ruby projects. Define tasks in `.loki` files, declare dependencies between them, and let Asgard handle ordering and concurrent execution. Anything Thor can do — subcommands, typed options, argument validation — is available inside a `.loki` file.
-
----
-
-## Quick Start
-
-```bash
-# Install
-gem install asgard
-
-# Create your project root marker
-touch .loki
-
-# Add your first task
-cat >> .loki << 'EOF'
-class Tasks
-  desc "Say hello"
-  def hello = puts "Hello from Asgard!"
-end
-EOF
-
-# Run it
-asgard hello
-```
-
----
-
-## How It Works
-
-Asgard searches upward from your current directory for a `.loki` file. That file marks the project root. Additional `*.loki` files in the same directory can be loaded via `import "*.loki"` at the top of `.loki`. All task files reopen `class Tasks`, which is pre-defined by the gem as a subclass of `Asgard::Base` (itself a Thor subclass).
-
-The full Thor DSL is available: `desc`, `method_option`, `class_option`, `long_desc`, `argument`, `default_task`, `map`, and `subcommand` all work exactly as documented in Thor — with Asgard's own `depends_on`, `sh`, `shebang`, and `dotenv` layered on top.
-
----
-
-## Documentation
-
-| Section | Description |
-|---|---|
-| [Getting Started](getting-started.md) | Install, create your first `.loki`, run your first task |
-| [Defining Tasks](tasks.md) | Parameters, options, long_desc, aliases, default_task |
-| [Dependencies](dependencies.md) | Sequential, parallel, and mixed dependency graphs |
-| [Variables](variables.md) | Static and lazy-evaluated task variables |
-| [Helper Methods](helpers.md) | Private helpers and the `no_commands` block |
-| [Options & Flags](options.md) | class_option, built-in flags, debug? and verbose? |
-| [Subcommands](subcommands.md) | Grouping tasks under a namespace |
-| [Shell Helpers](shell.md) | `sh`, `shebang`, and supported interpreters |
-| [Environment](environment.md) | Loading `.env` files with `dotenv` |
-| [Task Files](task-files.md) | `.loki` root marker, `import`, multi-file layout |
-| [API Reference](api.md) | Module methods, DSL methods, error classes |
-| [Examples](examples.md) | Working `.loki` files for every feature |
-| [Changelog](changelog.md) | Release history |
-
----
-
-## Requirements
-
-- Ruby >= 3.2.0
-- Dependencies: [thor](https://github.com/rails/thor) `~> 1.0`, [dotenv](https://github.com/bkeepers/dotenv) `~> 3.0`