runsheets 0.0.1

data/examples/single_md_file_runbooks/policies/cleanup-policy.md

@@ -0,0 +1,33 @@
+# Cleanup policy
+
+What may be deleted to free space, and what may not. Used by the
+[disk space triage](../disk-space-triage.md) runbook. Terms are explained
+in the [glossary](../disk-usage-glossary.md).
+
+![Triage: measure, find, check the policy, clean, verify](images/triage-flow.svg)
+
+## Safe to delete
+
+- Build caches and intermediate artifacts the next build recreates.
+- Package manager caches (`~/.cache`, `~/.npm/_cacache`, gem and bundler
+  caches).
+- Rotated and compressed logs older than 14 days.
+- Anything under `/tmp` older than a day that no running process holds open.
+
+## Ask first
+
+- Uncompressed logs of a service that is still running. Truncate them
+  instead of deleting, so the service keeps writing to the same file.
+- Container images and volumes. An unused-looking volume may hold the only
+  copy of something.
+
+## Never delete
+
+- Database files, even when the database is stopped.
+- Anything under a backup or snapshot directory.
+- Files you cannot identify. Find their owner first.
+
+## When something was deleted by mistake
+
+Stop, do not write more to that file system, and contact the owner of the
+host. Restore from backup before trying anything clever.

data/examples/single_md_file_runbooks/policies/images/triage-flow.svg

@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 150" width="760" height="150" role="img" aria-labelledby="t d">
+  <title id="t">Disk space triage</title>
+  <desc id="d">Measure with df, find with du, check the cleanup policy, clean by hand, then verify use is under the threshold; loop back to find if it is not.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 10 5 0 10z" fill="#8b95a8"/>
+    </marker>
+  </defs>
+  <g font-family="-apple-system, Segoe UI, Helvetica, Arial, sans-serif" font-size="14" text-anchor="middle">
+    <g>
+      <rect x="10" y="40" width="120" height="56" rx="10" fill="#10263d" stroke="#5ab0ff" stroke-width="1.5"/>
+      <text x="70" y="64" fill="#d9dee8" font-weight="600">Measure</text>
+      <text x="70" y="83" fill="#8b95a8" font-size="12" font-family="ui-monospace, Menlo, monospace">df -h</text>
+    </g>
+    <g>
+      <rect x="160" y="40" width="120" height="56" rx="10" fill="#10263d" stroke="#5ab0ff" stroke-width="1.5"/>
+      <text x="220" y="64" fill="#d9dee8" font-weight="600">Find</text>
+      <text x="220" y="83" fill="#8b95a8" font-size="12" font-family="ui-monospace, Menlo, monospace">du -sh</text>
+    </g>
+    <g>
+      <rect x="310" y="40" width="130" height="56" rx="10" fill="#211a3a" stroke="#a78bfa" stroke-width="1.5"/>
+      <text x="375" y="64" fill="#d9dee8" font-weight="600">Check policy</text>
+      <text x="375" y="83" fill="#8b95a8" font-size="12">plain document</text>
+    </g>
+    <g>
+      <rect x="470" y="40" width="120" height="56" rx="10" fill="#33240f" stroke="#ffb454" stroke-width="1.5"/>
+      <text x="530" y="64" fill="#d9dee8" font-weight="600">Clean</text>
+      <text x="530" y="83" fill="#8b95a8" font-size="12">by hand</text>
+    </g>
+    <g>
+      <rect x="620" y="40" width="130" height="56" rx="10" fill="#0f2e24" stroke="#3ddc97" stroke-width="1.5"/>
+      <text x="685" y="64" fill="#d9dee8" font-weight="600">Verify</text>
+      <text x="685" y="83" fill="#8b95a8" font-size="12">use ≤ threshold</text>
+    </g>
+    <g stroke="#8b95a8" stroke-width="1.5" fill="none" marker-end="url(#arrow)">
+      <path d="M130 68h28"/>
+      <path d="M280 68h28"/>
+      <path d="M440 68h28"/>
+      <path d="M590 68h28"/>
+      <path d="M685 96v28H220v-26" stroke-dasharray="5 4"/>
+    </g>
+    <text x="452" y="140" fill="#8b95a8" font-size="12">still over: find more</text>
+  </g>
+</svg>

data/examples/single_md_file_runbooks/runbooks_with_scripts/.loki

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# Asgard entry point for the asgard-tasks.md example runbook.
+#
+# asgard looks for a .loki file in its working directory, then in each
+# directory above it. runsheets runs a single-file runbook's blocks in the
+# runbook's own directory, so `asgard` in one of its blocks finds this file
+# first, ahead of the repository's own .loki further up.
+#
+# This file loads the task files beside it (the glob skips .loki itself):
+#   greet.loki    greet NAME
+#   checks.loki   ruby_check, disk_check [DIR], and health, which runs both
+
+import "*.loki"
+
+class Tasks
+  header "runbook tasks: defined beside asgard-tasks.md"
+end

data/examples/single_md_file_runbooks/runbooks_with_scripts/asgard-tasks.md

@@ -0,0 +1,135 @@
+---
+title: Runbook tasks from local .loki files
+when_to_use: >
+  An example of a runbook whose blocks call asgard tasks defined in .loki
+  files kept beside it, so a long or reusable script lives in a task file
+  and the runbook block stays one line.
+prerequisites:
+  - The `asgard` command on PATH (`gem install asgard`)
+escalation: Nobody; this runbook only reads.
+tags: [asgard, loki, scripts, safe, example]
+inputs:
+  - name: NAME
+    prompt: Who to greet
+    default: operator
+  - name: TARGET_DIR
+    prompt: Directory whose file system disk_check measures
+    default: /tmp
+  - name: MAX_USE
+    prompt: Highest acceptable disk use, in percent
+    default: "95"
+---
+
+# Runbook tasks from local .loki files
+
+This runbook is one markdown file, and its scripts are
+[asgard](https://github.com/MadBomber/asgard) tasks in `.loki` files in
+the same directory:
+
+```text
+runbooks_with_scripts/
+  asgard-tasks.md   this runbook
+  .loki             asgard's entry point: imports the other .loki files
+  greet.loki        greet NAME
+  checks.loki       ruby_check, disk_check [DIR], and health, which runs both
+```
+
+Two facts make it work:
+
+- runsheets runs a single-file runbook's blocks in the directory holding
+  the runbook (a step's `cwd` can change that).
+- asgard looks for a `.loki` file in its working directory first, then in
+  each directory above. The `.loki` here is found before any other, such as
+  the one at the root of the runsheets repository.
+
+The `.loki` file marks the directory as asgard's project root and loads
+the task files beside it:
+
+```ruby
+import "*.loki"
+```
+
+Each task file reopens `class Tasks`, as in `greet.loki`:
+
+```ruby
+class Tasks
+  desc "greet NAME", "Say hello to NAME"
+  def greet(name = "World") = puts "Hello, #{name}, from a task beside the runbook!"
+end
+```
+
+A block then calls the task by name, with runbook inputs as arguments or
+in the environment. Every block in this runbook only reads.
+
+## Find the local task file
+<!-- kind: verify, timeout: 30 -->
+
+`asgard --doctor` reports which `.loki` file it is using. It should be the
+one beside this runbook. The doctor's full report also lists every
+imported file and the tasks each defines; the block prints only the line
+that names the file in use.
+
+```bash run
+asgard --doctor | grep -o 'using .loki marker: [^[:cntrl:]]*'
+```
+
+```text expect
+using .loki marker: {{any}}/runbooks_with_scripts/.loki
+```
+
+## List the tasks
+
+The task list comes from the local `.loki` files, together with asgard's
+built-in commands (`help`, `schedule`, `tree`).
+
+```bash run
+asgard tree
+```
+
+## Run a task with an argument
+<!-- timeout: 30 -->
+
+`greet` is defined in `greet.loki`. The `NAME` input is passed as its
+argument.
+
+```bash run
+asgard greet "$NAME"
+```
+
+```text expect
+Hello, {{any}}, from a task beside the runbook!
+```
+
+## Run a task with dependencies
+<!-- timeout: 60 -->
+
+`health` in `checks.loki` declares `depends_on [:ruby_check, :disk_check]`,
+so asgard runs both checks in parallel before it. A dependency gets no
+arguments, so `disk_check` reads its directory from `TARGET_DIR` and its
+limit from `MAX_USE`, both runbook inputs in the environment. If either
+check fails, `health` does not run and the block fails.
+
+```bash run
+asgard health
+```
+
+The two checks run in parallel and may print in either order.
+
+```text expect
+{{any}}_check: {{any}}
+{{any}}_check: {{any}}
+health: all checks passed
+```
+
+## Verify
+
+Disk use under `TARGET_DIR` is at or below `MAX_USE`, checked by the same
+task the health check runs, this time called directly with an argument.
+
+```bash run
+asgard disk_check "$TARGET_DIR"
+```
+
+## Rollback
+
+Nothing to undo: no task in this directory changes anything.

data/examples/single_md_file_runbooks/runbooks_with_scripts/checks.loki

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+class Tasks
+  desc "ruby_check", "Report the Ruby that asgard runs on"
+  def ruby_check = puts "ruby_check: ruby #{RUBY_VERSION}"
+
+  # DIR defaults to TARGET_DIR from the environment, which is how a runbook
+  # input reaches a task run as a dependency, with no arguments.
+  desc "disk_check [DIR]", "Fail when the file system holding DIR is more than MAX_USE percent full"
+  def disk_check(dir = env(:target_dir, "."))
+    used  = disk_use(dir)
+    limit = env(:max_use, "95").to_i
+    puts "disk_check: #{dir} is #{used}% used, limit #{limit}%"
+    exit 1 if used > limit
+  end
+
+  depends_on [:ruby_check, :disk_check]
+  desc "Run every check, in parallel"
+  def health = puts "health: all checks passed"
+
+  private
+
+  # Percent used of the file system holding +dir+, from POSIX df output.
+  def disk_use(dir) = `df -P #{Shellwords.escape(dir)}`.lines.last.split[4].to_i
+end

data/examples/single_md_file_runbooks/runbooks_with_scripts/greet.loki

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class Tasks
+  desc "greet NAME", "Say hello to NAME"
+  def greet(name = "World") = puts "Hello, #{name}, from a task beside the runbook!"
+end