asgard 0.5.1 → 0.6.0

data/examples/kitchen_sink.loki

@@ -1,210 +0,0 @@
-# frozen_string_literal: true
-# kitchen_sink.loki — demonstrates every Thor DSL feature available in Asgard.
-#
-# Task names deliberately avoid the gem's own .loki tasks (test, build, quality,
-# install, release) so this file can be loaded alongside them without conflict.
-
-class Tasks
-  # ── Ruby class variables — shared across all tasks and subcommands ──────────
-  @@app_name  ||= "my_app".freeze
-  @@build_dir ||= "builds/#{@@app_name}".freeze
-
-  # ── Computed values — plain private methods replace the removed var DSL ──────
-  # Declare as private so Thor does not try to register them as commands.
-  # Use @ivar ||= inside the method body to memoize expensive calls.
-  private
-
-  def version = `git describe --tags --always`.strip
-  def sha     = `git rev-parse --short HEAD`.strip
-  def branch  = @branch ||= `git rev-parse --abbrev-ref HEAD`.strip
-
-  public
-
-  # ── Asgard: dotenv — load environment variables ────────────────────────────
-  # Uncomment to activate:
-  # dotenv              # loads .env
-  # dotenv ".env.local" # or a specific file
-
-  # ── Thor: class_option — option present on every task ──────────────────────
-  class_option :dry_run,
-               aliases: "-n",
-               type:    :boolean,
-               default: false,
-               desc:    "Print commands without executing them"
-
-  class_option :env,
-               type:    :string,
-               default: "development",
-               enum:    %w[development staging production],
-               desc:    "Target environment"
-
-  # ── Thor: default_task — runs when no command is given ─────────────────────
-  default_task :greet
-
-  # ── Thor: map — short aliases for tasks ────────────────────────────────────
-  map "g"  => :greet
-  map "ck" => :check
-  map "rp" => :report
-  map "pl" => :pipeline
-
-  # ── Basic task — no parameters ─────────────────────────────────────────────
-  desc "Say hello (default task when no command is given)"
-  def greet
-    puts "Hello from #{@@app_name} #{version} (#{branch}) in #{options[:env]} mode!"
-  end
-
-  # ── Positional parameter with default ──────────────────────────────────────
-  desc "hello NAME", "Greet NAME; omit NAME to greet the world"
-  def hello(name = "World")
-    puts "Hello, #{name}!"
-  end
-
-  # ── Positional parameter with method_option ────────────────────────────────
-  desc "farewell NAME", "Say goodbye to NAME"
-  option :formal, aliases: "-f", type: :boolean, default: false, desc: "Use formal language"
-  def farewell(name = "friend")
-    msg = options[:formal] ? "Goodbye, #{name}." : "See ya, #{name}!"
-    puts msg
-  end
-
-  # ── argument — formal positional with type metadata ────────────────────────
-  # WARNING: argument is a CLASS-LEVEL declaration that pollutes every task's
-  # usage line. Only use it when every task in the class shares the same input,
-  # or in a single-command CLI. Shown here as a commented-out reference only.
-  #
-  # argument :target,
-  #          type:    :string,
-  #          default: "localhost",
-  #          desc:    "Deployment target host"
-
-  desc "notify RECIPIENT", "Send a notification to RECIPIENT"
-  def notify(recipient = "team")
-    puts "Notifying #{recipient}..."
-  end
-
-  # ── method_option — all five option types ──────────────────────────────────
-  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 #{@@app_name} → #{options[:output]}"
-  end
-
-  # ── required option + enum + banner ────────────────────────────────────────
-  desc "deploy ENV", "Deploy to ENV (default: staging)"
-  option :strategy,
-         type:     :string,
-         required: true,
-         enum:     %w[blue-green rolling canary],
-         desc:     "Deployment strategy"
-  option :timeout,
-         type:    :numeric,
-         default: 300,
-         banner:  "SECONDS",
-         desc:    "Abort deployment after SECONDS"
-  option :branch,
-         type:    :string,
-         default: "main",
-         desc:    "Git branch to deploy"
-  def deploy(env = "staging")
-    puts "Deploying #{@@app_name}@#{options[:branch]} to #{env}..."
-  end
-
-  # ── long_desc — extended help shown by `asgard help report` ────────────────
-  long_desc <<~LONGDESC
-    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 rp --format text
-  LONGDESC
-  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"
-  option :output, type: :string,                  banner: "FILE",            desc: "Write output to FILE"
-  def report
-    puts "Generating #{options[:format]} report..."
-  end
-
-  # ── Asgard depends_on: sequential — analyze runs before spec ───────────────
-  desc "Check code style and complexity"
-  def analyze = puts "Analyzing..."
-
-  depends_on :analyze
-  desc "Run the test suite (depends on: analyze)"
-  def spec = puts "Running specs..."
-
-  # ── Asgard depends_on: parallel — analyze and typecheck run concurrently ───
-  desc "Run the type checker"
-  def typecheck = puts "Type checking..."
-
-  depends_on [:analyze, :typecheck]
-  desc "Run analyze and typecheck in parallel"
-  def check = puts "All checks passed."
-
-  # ── Asgard depends_on: mixed sequential + parallel ─────────────────────────
-  desc "Create distribution archive"
-  def pack = puts "Packing..."
-
-  #   check → compile+spec (parallel) → pack → pipeline
-  depends_on :check, [:compile, :spec], :pack
-  desc "Full pipeline: check → compile+spec → pack"
-  def pipeline = puts "Pipeline complete."
-
-  # ── Asgard: debug? / verbose? — Kernel predicates for conditional output ──────
-  # debug?   returns true when --debug is passed  (sets $DEBUG)
-  # verbose? returns true when --verbose is passed (sets $VERBOSE)
-  # Both are set by Asgard before invoke_command runs, so they are safe
-  # to read inside any task body.
-  #
-  # Run with:
-  #   asgard status --verbose
-  #   asgard status --debug
-  #   asgard status --verbose --debug
-  desc "Show application status"
-  def status
-    puts "#{@@app_name} is running in #{options[:env]} mode."
-    puts "  build dir : #{@@build_dir}" if verbose?
-    puts "  sha       : #{current_sha}" if verbose?
-    if debug?
-      puts "  $DEBUG    : #{$DEBUG.inspect}"
-      puts "  $VERBOSE  : #{$VERBOSE.inspect}"
-      puts "  options   : #{options.inspect}"
-    end
-  end
-
-  # ── Asgard: sh — run shell commands, single-line and multi-line heredoc ────
-  desc "Show environment info (single-line sh)"
-  def env_info = sh "echo Running #{@@app_name} on $(uname -s)"
-
-  desc "Bootstrap the local environment (multi-line sh / heredoc)"
-  def bootstrap
-    sh <<~SHELL
-      echo "App:  #{@@app_name}"
-      echo "Ruby: $(ruby -v)"
-      echo "Date: $(date)"
-    SHELL
-  end
-
-  # ── Thor: no_commands — public helper excluded from CLI and --help ──────────
-  no_commands do
-    def current_sha
-      `git rev-parse --short HEAD`.strip
-    end
-  end
-
-  # ── private — also excluded from CLI and --help ────────────────────────────
-  private
-
-  def banner(msg)
-    puts "=== #{msg} ==="
-  end
-end

data/examples/server_subcommands.loki

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates Thor subcommands registered on the top-level Tasks class.
-#
-# Port state is persisted to .server.port so stop and restart always
-# operate on the same port the server was started on.
-#
-# Usage:
-#   asgard server                    # shows subcommand help
-#   asgard server start
-#   asgard server start -p 8000
-#   asgard server start -p 4000 --workers 4 --daemon
-#   asgard server stop
-#   asgard server stop --force
-#   asgard server status
-#   asgard server restart            # stops then starts on the persisted port
-
-SERVER_PORT_FILE = "tmp/.server.port".freeze
-
-class ServerCommands < Tasks
-  default_task :help  # This is the default value for the default_task
-
-  helper(:server_port) {
-    File.exist?(SERVER_PORT_FILE) ? File.read(SERVER_PORT_FILE).strip.to_i : 3000
-  }
-
-  desc "Start the server"
-  option :port,    aliases: "-p", type: :numeric, default: 3000,             desc: "Port to listen on"
-  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
-    FileUtils.mkdir_p("tmp")
-    File.write(SERVER_PORT_FILE, options[:port].to_s)
-    puts "Starting server on :#{options[:port]} with #{options[:workers]} workers#{options[:daemon] ? " (daemon)" : ""}..."
-  end
-
-  desc "Stop the running server"
-  option :force, aliases: "-f", type: :boolean, default: false, desc: "Force-kill without draining"
-  option :wait,                  type: :numeric, default: 30,   desc: "Seconds to wait for shutdown"
-  def stop
-    if options[:force]
-      puts "Force-stopping server on :#{server_port}..."
-    else
-      puts "Gracefully stopping server on :#{server_port} (timeout: #{options[:wait] || 30}s)..."
-    end
-  end
-
-  desc "Show server status and process info"
-  def status
-    puts "Server is listening on :#{server_port}"
-  end
-
-  depends_on :stop
-  desc "Restart the server on the same port it was started on"
-  def restart
-    puts "Starting server on :#{server_port}..."
-    puts "Server restarted."
-  end
-end
-
-class Tasks
-  desc "server SUBCOMMAND", "Manage the application server"
-  subcommand "server", ServerCommands
-end

data/examples/subdir/.loki

@@ -1,12 +0,0 @@
-# examples/subdir/.loki — root task file for this subdirectory.
-#
-# When asgard is run from examples/subdir/, it loads this file.
-# From here, import pulls in sibling task files explicitly.
-#
-# import accepts a direct path or a glob:
-#   import "import_up_demo.loki"       # a single file
-#   import "*.loki"                    # all loki files in this directory
-#   import "tasks/**/*.loki"           # all loki files under a tasks/ tree
-#   import "../shared/*.loki"          # files in a sibling directory
-
-import "import_up_demo.loki"

data/examples/subdir/import_demo.loki

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-# This file lives in a subdirectory and is explicitly imported by the
-# parent examples/.loki via import "subdir/import_demo.loki".
-#
-# In a real project a subdirectory might hold task files scoped to a
-# specific concern (deploy, database, CI) while the root .loki wires
-# them all together with import.
-
-class Tasks
-  desc "Confirm this task was loaded from a subdirectory via import"
-  def subdir_task
-    puts "Loaded from examples/subdir/import_demo.loki"
-  end
-end

data/examples/subdir/import_up_demo.loki

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-# Demonstrates import_up — find a file by walking up the directory tree
-# and load it, without needing to know how deep the current file is.
-#
-# import_up(name) combines loki_up(name) + import(path) in one call.
-# It searches CWD, then each ancestor in turn, and loads the first match.
-#
-# This is useful when a nested task file needs to pull in something from
-# the project root — a shared config, a common helpers file — without
-# hardcoding a relative path that would break if the file moves.
-#
-# import_up also accepts a glob:
-#   import_up "*.loki"                 # first directory (walking up) that contains any .loki file
-#   import_up "config/settings.loki"   # first ancestor with config/settings.loki
-#   import_up ".env"                   # locate a .env file anywhere up the tree
-
-# Load env_usage.loki from the nearest ancestor directory that contains it.
-import_up "env_usage.loki"

data/examples/watcher_examples/.envrc

@@ -1,3 +0,0 @@
-# asgard/examples/watcher_examples/.envrc
-
-source_up

data/examples/watcher_examples/.loki

@@ -1,54 +0,0 @@
-# examples/watcher_examples/.loki
-# A small project whose tasks run when its files change.
-#
-# `watch :task, paths: ...` at class level says which files a task cares
-# about. `asgard watcher start` runs one background process for this
-# project that listens for changes and runs the matching tasks, each as a
-# separate `asgard <task>` process started from this directory. The task
-# reads what changed through `changes`.
-#
-# Run with (from this directory):
-#   asgard watcher start      # background; log and state under ~/.local/state/asgard/watch/
-#   asgard watcher list       # the four entries, daemon state, each entry's last run
-#   # ... edit lib/greeter.rb, docs/index.md, add or remove a data/*.json ...
-#   asgard watcher log        # one line per trigger, spawn and exit, plus each task's output
-#   asgard watcher stop       # a task still running finishes first
-#
-# Each task also runs by hand (`asgard lint`), when `changes` is empty.
-# See README.md here for a walkthrough with expected output.
-
-class Tasks
-  # A glob: watches lib/ and keeps the paths that match, like a shell would.
-  watch :lint, paths: "lib/**/*.rb"
-
-  # A directory with filters. only: narrows to Markdown; ignore: silences
-  # the drafts folder; env: adds a variable the task can read with env().
-  watch :docs, paths: "docs", only: /\.md\z/, ignore: %r{\Adrafts/}, env: { BUILD_ENV: "demo" }
-
-  # events: picks which kinds of change count. Editing a data file does
-  # nothing; creating or deleting one triggers a reindex. debounce: waits
-  # a full second after the last event, so a batch of files lands at once.
-  watch :reindex, paths: "data/**/*.json", events: %i[added removed], debounce: 1
-
-  # The same task watched from a second declaration needs its own entry
-  # name. Both entries share one worker, so lint never overlaps itself.
-  watch :lint, paths: "bin/**/*", as: "lint-bin"
-
-  desc "lint", "Report the Ruby files that changed"
-  def lint
-    files = changes.modified + changes.added
-    return puts "lint: nothing changed (run by hand), so linting everything under lib/" if files.empty?
-
-    files.each { |file| puts "lint: #{file} (#{File.foreach(file).count} lines) triggered by #{env(:asgard_watch, 'nothing')}" }
-  end
-
-  desc "docs", "Rebuild the documentation"
-  def docs
-    puts "docs: building for #{env(:build_env, 'development')}; changed: #{changes.all.join(', ')}"
-  end
-
-  desc "reindex", "Rebuild the data index"
-  def reindex
-    puts "reindex: #{changes.added.size} added, #{changes.removed.size} removed; #{Dir['data/**/*.json'].size} data file(s) now"
-  end
-end

data/examples/watcher_examples/README.md

@@ -1,112 +0,0 @@
-# Watcher example
-
-A small project whose tasks run when its files change. The `.loki` here
-declares four watches; `lib/`, `bin/`, `docs/` and `data/` hold one
-placeholder file each so the watcher has something to watch right away.
-
-## Before you start
-
-The watcher runs its daemon and every triggered task as separate `asgard`
-processes. If you are running asgard from a git checkout of this
-repository rather than an installed gem, install the checkout as the gem
-first, from the repository root:
-
-```bash
-asgard install        # builds pkg/asgard-<version>.gem and gem-installs it
-gem list asgard       # the checkout's version should be listed
-```
-
-Otherwise an older asgard gem already on the machine can be the one the
-spawned processes run, and it will not understand `watch`.
-
-## Walkthrough
-
-From this directory:
-
-```bash
-asgard watcher start
-```
-
-```
-started watcher for watcher_examples (pid 12345); log: ~/.local/state/asgard/watch/watcher-examples/watcher.log
-```
-
-Now make some changes and watch the log fill up:
-
-```bash
-echo '# a change' >> lib/greeter.rb         # lint runs, with the path in changes.modified
-echo 'more' >> docs/index.md               # docs runs; BUILD_ENV=demo comes from env:
-echo 'more' >> docs/drafts/ideas.md        # nothing: drafts/ is ignored
-echo '{}' > data/new.json                  # reindex runs: a file was added
-echo '{"edited": true}' > data/new.json    # nothing: events: is added and removed only
-rm data/new.json                           # reindex runs again: a file was removed
-asgard watcher log
-```
-
-```
-2026-10-18 23:40:01 trigger lint task=lint lib/greeter.rb
-2026-10-18 23:40:01 spawn lint task=lint pid=12351 lib/greeter.rb
-lint: lib/greeter.rb (7 lines) triggered by lint
-2026-10-18 23:40:02 exit lint task=lint pid=12351 status=0 seconds=0.41
-2026-10-18 23:40:05 trigger docs task=docs docs/index.md
-2026-10-18 23:40:05 spawn docs task=docs pid=12360 docs/index.md
-docs: building for demo; changed: docs/index.md
-2026-10-18 23:40:06 exit docs task=docs pid=12360 status=0 seconds=0.40
-2026-10-18 23:40:09 trigger reindex task=reindex data/new.json
-2026-10-18 23:40:09 spawn reindex task=reindex pid=12371 data/new.json
-reindex: 1 added, 0 removed; 2 data file(s) now
-2026-10-18 23:40:10 exit reindex task=reindex pid=12371 status=0 seconds=0.40
-...
-```
-
-Each trigger line names the entry and the changed paths. Each spawn and
-exit line carries the task's pid, so the lines of overlapping tasks can be
-told apart; a task's own output sits between its spawn and its exit. Save
-`lib/greeter.rb` twice in quick succession and the second trigger says
-`(queued behind pid N)`: the same task never overlaps itself, while
-different tasks run at the same time.
-
-```bash
-asgard watcher list
-```
-
-```
-┌──────────┬────────────────┬──────────────────────────────────────┬──────────┬────────────────────────────────┐
-│ NAME     │ TASK           │ WATCHES                              │ DAEMON   │ LAST RUN                       │
-├──────────┼────────────────┼──────────────────────────────────────┼──────────┼────────────────────────────────┤
-│ lint     │ asgard lint    │ lib/**/*.rb                          │ running  │ 0 (0.4s, 2026-10-18 23:40:02)  │
-│ docs     │ asgard docs    │ docs                                 │ running  │ 0 (0.4s, 2026-10-18 23:40:06)  │
-│ reindex  │ asgard reindex │ data/**/*.json [added, removed]      │ running  │ 0 (0.4s, 2026-10-18 23:40:14)  │
-│ lint-bin │ asgard lint    │ bin/**/*                             │ running  │ never                          │
-└──────────┴────────────────┴──────────────────────────────────────┴──────────┴────────────────────────────────┘
-```
-
-```bash
-asgard watcher stop
-```
-
-A task that is still running finishes first; `stop` names it while it
-waits.
-
-## Running the tasks by hand
-
-Every task works without the watcher too. `changes` is then empty, which
-`lint` turns into "lint everything":
-
-```bash
-asgard lint
-asgard docs
-asgard reindex
-```
-
-## What the watcher restricts
-
-A triggered task does not inherit the shell the watcher was started from.
-It sees `PATH`, `HOME`, `USER`, `LANG` and a few other basics, the entry's
-`env:`, a project `.envrc` through `direnv`, and the trigger variables
-`ASGARD_WATCH`, `ASGARD_WATCH_ROOT`, `ASGARD_MODIFIED`, `ASGARD_ADDED` and
-`ASGARD_REMOVED`. `asgard watcher preview` prints the exact command and
-environment each entry would run.
-
-Edit `.loki` while the watcher runs and it restarts itself with the new
-declarations.

data/examples/watcher_examples/bin/hello

@@ -1,3 +0,0 @@
-#!/bin/sh
-# Edit this file while the watcher runs: the lint-bin entry picks it up.
-echo "hello from bin/"

data/examples/watcher_examples/data/records.json

@@ -1 +0,0 @@
-{ "records": ["one", "two"] }

data/examples/watcher_examples/docs/drafts/ideas.md

@@ -1,5 +0,0 @@
-# Drafts are ignored
-
-Editing this file never triggers the docs entry: its declaration has
-`ignore: %r{\Adrafts/}`.
-more

data/examples/watcher_examples/docs/index.md

@@ -1,4 +0,0 @@
-# Watcher example
-
-Edit this file while the watcher runs: the docs entry picks it up.
-more

data/examples/watcher_examples/lib/greeter.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-# Edit this file while the watcher runs: the lint entry picks it up.
-module Greeter
-  def self.greet(name) = "Hello, #{name}!"
-end
-# a change

data/gem_tasks.loki

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-# Gem lifecycle tasks — imported by .loki
-
-class Tasks
-  desc "Open IRB console with the gem loaded"
-  def console
-    if File.exist?("bin/console")
-      sh "bin/console"
-    else
-      sh "bundle exec irb -Ilib -r #{@@project}"
-    end
-  end
-
-  desc "Build the gem package"
-  depends_on :quality
-  def build
-    sh "mkdir -p pkg"
-    sh "gem build asgard.gemspec"
-    sh "mv asgard-#{project_version}.gem pkg/"
-  end
-
-  desc "Build and install gem locally"
-  depends_on :build
-  def install
-    sh "gem install pkg/asgard-#{project_version}.gem"
-  end
-
-  desc "release", "Release gem to RubyGems (runs quality gate first)"
-  option :yes, aliases: "-y", type: :boolean, default: false, desc: "Skip confirmation prompt"
-  depends_on :quality
-  def release
-    tag      = "v#{project_version}"
-    gem_file = "pkg/asgard-#{project_version}.gem"
-
-    unless options[:yes]
-      print "Release #{@@project} v#{project_version} to RubyGems? [y/N] "
-      $stdout.flush
-      return puts "Aborted." unless $stdin.gets.strip.downcase == "y"
-    end
-
-    abort "Working directory is not clean — commit or stash changes first." unless `git status --porcelain`.strip.empty?
-    abort "Tag #{tag} already exists." unless `git tag -l #{tag}`.strip.empty?
-
-    sh "mkdir -p pkg"
-    sh "gem build asgard.gemspec"
-    sh "mv asgard-#{project_version}.gem pkg/"
-    sh "git tag #{tag}"
-    sh "git push origin #{tag}"
-    sh "gem push #{gem_file}"
-  end
-end

data/git.loki

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-# Per-repo git tasks — imported by .loki
-
-class Tasks
-  desc "Push the current branch to its remote"
-  def push = sh "git push"
-
-  desc "Pull (fast-forward only) from the remote"
-  def pull = sh "git pull --ff-only"
-
-  desc "Fetch from the remote"
-  def fetch = sh "git fetch"
-end