runsheets 0.0.1 → 0.0.2

data/templates/rollback/steps/040-tell-people.md.erb

@@ -0,0 +1,7 @@
+---
+title: Tell people
+kind: manual
+---
+
+A `manual` step: something the operator does by hand, then acknowledges.
+Say who needs to know that this ran, and where to tell them.

data/templates/rollback/template.yml

@@ -0,0 +1,2 @@
+order: 3
+description: "Checks, tasks and rollback: a destructive step and the way back"

data/templates/rollback/verify.md.erb

@@ -0,0 +1,15 @@
+---
+title: Verify
+kind: verify
+---
+
+Whole-procedure checks. They should pass after every run, and they run on
+their own from the Checks page.
+
+```bash run
+test -s "$WORK_DIR/last-run" && echo "last run: $(cat "$WORK_DIR/last-run")"
+```
+
+```text expect
+last run: {{any}}
+```

data/templates/tasks/runbook.md.erb

@@ -0,0 +1,29 @@
+---
+title: <%= yaml title %>
+when_to_use: <%= yaml when_to_use %>
+prerequisites:
+  - What must be true or installed before starting
+tags: []
+inputs:
+  - name: WORK_DIR
+    prompt: Where this runbook writes its files
+    default: /tmp/<%= name %>
+escalation: <%= yaml escalation %>
+---
+
+# <%= title %>
+
+Checks, then the work, then proof that it worked. The preflight and
+verify checks read; the steps between them change things. `WORK_DIR` is
+an input: the start-run form asks for it and every block gets it as an
+environment variable.
+
+<% if single_file -%>
+Everything above the first `##` heading is the preamble. Each `##` heading
+below is a step, and its attributes (`kind`, `timeout`, ...) go in the HTML
+comment right after the heading.
+<% else -%>
+Everything above the first step is the preamble. The steps are the files in
+`steps/`, run in the order of their numbers, and each one's attributes
+(`kind`, `timeout`, ...) are in its front matter.
+<% end -%>

data/templates/tasks/steps/010-preflight.md.erb

@@ -0,0 +1,16 @@
+---
+title: Preflight
+kind: verify
+timeout: 30
+---
+
+Check what the later steps rely on before anything changes. A `verify`
+step also runs on its own from the Checks page.
+
+```bash run
+test -n "$WORK_DIR" && echo "WORK_DIR is $WORK_DIR"
+```
+
+```text expect
+WORK_DIR is {{any}}
+```

data/templates/tasks/steps/020-do-the-work.md.erb

@@ -0,0 +1,18 @@
+---
+title: Do the work
+kind: automated
+timeout: 300
+---
+
+The change this runbook exists for. Replace the block with the real
+command; keep the expected output so the operator can see it worked.
+
+```bash run
+mkdir -p "$WORK_DIR"
+date -u > "$WORK_DIR/last-run"
+echo "wrote $WORK_DIR/last-run"
+```
+
+```text expect
+wrote {{any}}/last-run
+```

data/templates/tasks/steps/030-tell-people.md.erb

@@ -0,0 +1,7 @@
+---
+title: Tell people
+kind: manual
+---
+
+A `manual` step: something the operator does by hand, then acknowledges.
+Say who needs to know that this ran, and where to tell them.

data/templates/tasks/template.yml

@@ -0,0 +1,2 @@
+order: 2
+description: "Checks and tasks: preflight, automated and manual steps, verify"

data/templates/tasks/verify.md.erb

@@ -0,0 +1,15 @@
+---
+title: Verify
+kind: verify
+---
+
+Whole-procedure checks. They should pass after every run, and they run on
+their own from the Checks page.
+
+```bash run
+test -s "$WORK_DIR/last-run" && echo "last run: $(cat "$WORK_DIR/last-run")"
+```
+
+```text expect
+last run: {{any}}
+```

data/templates/timeouts/runbook.md.erb

@@ -0,0 +1,30 @@
+---
+title: <%= yaml title %>
+when_to_use: <%= yaml when_to_use %>
+prerequisites:
+  - What must be true or installed before starting
+tags: []
+inputs:
+  - name: WORK_DIR
+    prompt: Where this runbook writes its files
+    default: /tmp/<%= name %>
+escalation: <%= yaml escalation %>
+---
+
+# <%= title %>
+
+Checks and tasks that take time. Each step's `timeout` is how many
+seconds its blocks may run before they are stopped (600 when it is not
+set). A `background` block has no timeout: it runs until it is stopped,
+while later steps run. A `terminal` block is one the operator runs in
+their own shell.
+
+<% if single_file -%>
+Everything above the first `##` heading is the preamble. Each `##` heading
+below is a step, and its attributes (`kind`, `timeout`, ...) go in the HTML
+comment right after the heading.
+<% else -%>
+Everything above the first step is the preamble. The steps are the files in
+`steps/`, run in the order of their numbers, and each one's attributes
+(`kind`, `timeout`, ...) are in its front matter.
+<% end -%>

data/templates/timeouts/steps/010-preflight.md.erb

@@ -0,0 +1,16 @@
+---
+title: Preflight
+kind: verify
+timeout: 15
+---
+
+Check what the later steps rely on before anything changes. A `verify`
+step also runs on its own from the Checks page.
+
+```bash run
+test -n "$WORK_DIR" && echo "WORK_DIR is $WORK_DIR"
+```
+
+```text expect
+WORK_DIR is {{any}}
+```

data/templates/timeouts/steps/020-watch-progress.md.erb

@@ -0,0 +1,13 @@
+---
+title: Watch the progress
+kind: automated
+---
+
+Start this before the long step. It keeps running, listed in the Running
+panel on every page, until you stop it or the session ends.
+
+```bash background
+mkdir -p "$WORK_DIR"
+touch "$WORK_DIR/progress.log"
+tail -n 0 -F "$WORK_DIR/progress.log"
+```

data/templates/timeouts/steps/030-the-long-step.md.erb

@@ -0,0 +1,20 @@
+---
+title: The long step
+kind: automated
+timeout: 120
+---
+
+Give a slow step a timeout that fits it. If the block runs past 120
+seconds, its whole process group is stopped and the step fails.
+
+```bash run
+for chunk in 1 2 3 4 5 6 7 8 9 10; do
+  echo "chunk $chunk" >> "$WORK_DIR/progress.log"
+  sleep 1
+done
+echo "done"
+```
+
+```text expect
+done
+```

data/templates/timeouts/steps/040-look-it-over.md.erb

@@ -0,0 +1,14 @@
+---
+title: Look it over
+kind: manual
+---
+
+Some commands need a real terminal: a pager, a prompt, a login. A
+`terminal` block has no Run button; run it yourself, then press
+**I ran this**, with a note if anything stood out.
+
+```bash terminal
+less "$WORK_DIR/progress.log"
+```
+
+Stop the background tail from the Running panel when you are done.

data/templates/timeouts/template.yml

@@ -0,0 +1,2 @@
+order: 4
+description: "Checks, tasks and time: per-step timeouts, a background process, a terminal step"

data/templates/timeouts/verify.md.erb

@@ -0,0 +1,13 @@
+---
+title: Verify
+kind: verify
+timeout: 15
+---
+
+```bash run
+tail -n 1 "$WORK_DIR/progress.log"
+```
+
+```text expect
+chunk 10
+```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: runsheets
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -135,9 +135,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- Archspec.rb
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- archspec_todo.yml
 - bin/runsheets
 - examples/about-the-examples.md
 - examples/directory_based_runbooks/hello/rollback.md
@@ -184,6 +186,7 @@ files:
 - lib/runsheets/pages/chooser.rb
 - lib/runsheets/pages/search.rb
 - lib/runsheets/pages/tree.rb
+- lib/runsheets/prompt.rb
 - lib/runsheets/redactor.rb
 - lib/runsheets/renderer.rb
 - lib/runsheets/run.rb
@@ -193,10 +196,54 @@ files:
 - lib/runsheets/session.rb
 - lib/runsheets/session_log.rb
 - lib/runsheets/single_file.rb
+- lib/runsheets/slug.rb
 - lib/runsheets/step.rb
+- lib/runsheets/step_runner.rb
+- lib/runsheets/template.rb
 - lib/runsheets/version.rb
 - lib/runsheets/web.rb
+- lib/runsheets/wizard.rb
 - sig/runsheets.rbs
+- templates/asgard/.loki.erb
+- templates/asgard/runbook.md.erb
+- templates/asgard/steps/010-preflight.md.erb
+- templates/asgard/steps/020-do-the-work.md.erb
+- templates/asgard/steps/030-tell-people.md.erb
+- templates/asgard/tasks.loki
+- templates/asgard/template.yml
+- templates/asgard/verify.md.erb
+- templates/checks/runbook.md.erb
+- templates/checks/steps/010-tools.md.erb
+- templates/checks/steps/020-disk-space.md.erb
+- templates/checks/steps/030-writable.md.erb
+- templates/checks/template.yml
+- templates/inputs/runbook.md.erb
+- templates/inputs/steps/010-preflight.md.erb
+- templates/inputs/steps/020-use-the-inputs.md.erb
+- templates/inputs/steps/030-another-language.md.erb
+- templates/inputs/template.yml
+- templates/inputs/verify.md.erb
+- templates/rollback/rollback.md.erb
+- templates/rollback/runbook.md.erb
+- templates/rollback/steps/010-preflight.md.erb
+- templates/rollback/steps/020-keep-a-copy.md.erb
+- templates/rollback/steps/030-replace.md.erb
+- templates/rollback/steps/040-tell-people.md.erb
+- templates/rollback/template.yml
+- templates/rollback/verify.md.erb
+- templates/tasks/runbook.md.erb
+- templates/tasks/steps/010-preflight.md.erb
+- templates/tasks/steps/020-do-the-work.md.erb
+- templates/tasks/steps/030-tell-people.md.erb
+- templates/tasks/template.yml
+- templates/tasks/verify.md.erb
+- templates/timeouts/runbook.md.erb
+- templates/timeouts/steps/010-preflight.md.erb
+- templates/timeouts/steps/020-watch-progress.md.erb
+- templates/timeouts/steps/030-the-long-step.md.erb
+- templates/timeouts/steps/040-look-it-over.md.erb
+- templates/timeouts/template.yml
+- templates/timeouts/verify.md.erb
 homepage: https://github.com/madbomber/runsheets
 licenses:
 - MIT