runsheets 0.0.1 → 0.0.2

data/lib/runsheets/wizard.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Runsheets
+  # `runsheets --new [DIR]`: ask what kind of runbook to make, then write it
+  # from a Template into DIR, asking for DIR too when it was not given.
+  #
+  # Every question has a default, so Enter accepts it. Answers are read
+  # from +input+ and prompts written to +output+, so a test (or a script
+  # piping answers in) drives it like a person would. When input runs out
+  # each remaining question takes its default, and the final "Create?" is
+  # answered yes.
+  class Wizard
+    SHAPES = {
+      "directory" => "runbook.md, steps/, verify.md and rollback.md",
+      "single-file" => "one .md file; each ## heading is a step"
+    }.freeze
+
+    # What Enter gives for the free-text questions.
+    DEFAULTS = {
+      name: "new-runbook",
+      when_to_use: "One or two sentences on the situation this runbook is for.",
+      escalation: "Who to call when a step fails"
+    }.freeze
+
+    # How a runbook sits in its parent directory: a directory runbook, a
+    # single .md file, or a single file in a folder of its own because its
+    # template brings support files (see Template#support_files?). Keyed by
+    # [shape, whether the template has support files].
+    LAYOUTS = {
+      ["directory", false] => :directory, ["directory", true] => :directory,
+      ["single-file", false] => :file, ["single-file", true] => :folder
+    }.freeze
+
+    # Where each layout's runbook itself is, relative to the parent. Its
+    # first part is what the layout creates there.
+    MAINS = { directory: "%<name>s", file: "%<name>s.md", folder: "%<name>s/%<name>s.md" }.freeze
+
+    Answers = Data.define(:template, :name, :title, :when_to_use, :escalation, :layout) do
+      def single_file? = layout != :directory
+      def shape        = single_file? ? "single-file" : "directory"
+      # What is created in the parent directory: a file or a directory.
+      def location     = Wizard.location(name, layout)
+      # The runbook itself, relative to the parent: what --check is given.
+      def main         = format(MAINS.fetch(layout), name:)
+
+      def context
+        Template::Context.new(name:, title:, when_to_use:, escalation:, single_file: single_file?)
+      end
+    end
+
+    # "DB Refresh!" => "db-refresh": the basename a name becomes. A name
+    # with nothing usable in it gives "".
+    def self.slug(text) = Slug.of(text.to_s.strip.downcase.delete_suffix(".md"))
+
+    # The layout for a runbook of +shape+ from a template that has, or has
+    # not, +support_files+.
+    def self.layout(shape, support_files) = LAYOUTS.fetch([shape, support_files])
+
+    # What a runbook called +name+ creates in its parent directory: a
+    # directory or a .md file.
+    def self.location(name, layout) = format(MAINS.fetch(layout), name:).split("/").first
+
+    # "db-refresh" => "Db refresh": the title a name suggests.
+    def self.title_for(name) = Slug.title(name)
+
+    # Why +path+ cannot be created, or nil when it can: an existing file, or
+    # a directory with something in it.
+    def self.conflict(path)
+      return "#{path} already exists" if File.file?(path)
+
+      "#{path} exists and is not empty" if File.directory?(path) && !Dir.empty?(path)
+    end
+
+    # Why +name+ cannot be a new runbook of +layout+ in +parent+, or nil
+    # when it can.
+    def self.name_problem(parent, name, layout)
+      return "a name needs a letter or digit" if name.empty?
+
+      conflict(File.join(parent, location(name, layout)))
+    end
+
+    # Why +dir+ cannot be the directory to write into, or nil when it can.
+    def self.parent_problem(dir)
+      return "a directory is needed" if dir.nil?
+
+      "#{dir} is a file, not a directory" if File.file?(Config.expand_path(dir))
+    rescue ConfigError => e
+      e.message
+    end
+
+    # The one of +names+ that +answer+ picks, by its number in the list or
+    # by name, or nil.
+    def self.pick(names, answer)
+      return names.find { it == answer } unless answer.match?(/\A\d+\z/)
+
+      names[answer.to_i - 1] if answer.to_i.between?(1, names.size)
+    end
+
+    CANCELLED = "Nothing created."
+
+    attr_reader :parent
+
+    # +parent+ is the directory to write into; nil asks for it, offering
+    # +default_parent+ (nil for no default).
+    def initialize(parent, input: $stdin, output: $stdout, templates: Template.all, default_parent: nil)
+      raise RunbookError, "no runbook templates to offer" if templates.empty?
+
+      @parent         = parent
+      @default_parent = default_parent
+      @output         = output
+      @prompt         = Prompt.new(input:, output:)
+      @templates      = templates
+    end
+
+    # Ask, confirm, write. Returns the exit status.
+    def run
+      @parent ||= ask_parent(@default_parent)
+      @output.puts "New runbook in #{parent}", ""
+      answers = ask_all
+      return cancelled unless confirm?(summary(answers))
+
+      write(answers)
+    end
+
+    # Every question, in order, as Answers.
+    def ask_all
+      shape    = choose("Shape", SHAPES)
+      template = choose("Template", @templates.to_h { [it.name, it.description] }, default: Template::DEFAULT)
+      layout   = self.class.layout(shape, template_named(template).support_files?)
+      name     = ask_name(layout)
+      title    = ask("Title", default: self.class.title_for(name))
+      Answers.new(template:, name:, title:, layout:,
+                  when_to_use: ask("When to use, in a sentence", default: DEFAULTS[:when_to_use], shown: "edit later"),
+                  escalation: ask("Who to call when a step fails", default: DEFAULTS[:escalation], shown: "edit later"))
+    end
+
+    # One free-text answer: what was typed, else +default+. +shown+ is what
+    # the prompt displays in the brackets in place of a long default.
+    # +rejected+ says why the last answer was refused: when input runs out
+    # while it is being asked again, the default would quietly replace it,
+    # so that is an error instead.
+    def ask(question, default:, shown: default, rejected: nil)
+      @output.print shown ? "#{question} [#{shown}]: " : "#{question}: "
+      line = @prompt.line
+      raise RunbookError, rejected if line.nil? && rejected
+
+      line.nil? || line.empty? ? default : line
+    end
+
+    # Pick one of +options+ (name => description) by number or name.
+    # Returns the name; +default+ (the first option unless named) is
+    # what Enter picks.
+    def choose(question, options, default: options.keys.first)
+      names = options.keys
+      @output.puts "#{question}:"
+      width = names.map(&:size).max
+      names.each.with_index(1) { |name, i| @output.puts "  #{i}) #{name.ljust(width)}  #{options[name]}" }
+      ask_until do |rejected|
+        answer = ask("Choose", default: ((names.index(default) || 0) + 1).to_s, rejected:)
+        pick   = self.class.pick(names, answer)
+        [pick, ("#{answer.inspect} is not one of 1-#{names.size}" unless pick)]
+      end
+    end
+
+    # The runbook's name, slugged, asked again while it is blank or taken.
+    def ask_name(layout)
+      ask_until do |rejected|
+        name = self.class.slug(ask("Name (the #{layout == :file ? 'file' : 'directory'} name)", default: DEFAULTS[:name], rejected:))
+        [name, self.class.name_problem(parent, name, layout)]
+      end
+    end
+
+    # The directory to write into, expanded so ~ works: what was typed,
+    # else +default+. Asked again while it is blank with no default, names
+    # a file, or cannot be expanded (~nobody).
+    def ask_parent(default)
+      dir = ask_until do |rejected|
+        answer = ask("Directory to create the runbook in", default:, rejected:)
+        [answer, self.class.parent_problem(answer)]
+      end
+      Config.expand_path(dir)
+    end
+
+    # Ask until an answer has no problem. The block is given why the last
+    # answer was refused (nil at first) and returns [answer, problem or
+    # nil]. Returns the answer.
+    def ask_until
+      rejected = nil
+      loop do
+        answer, problem = yield(rejected)
+        return answer unless problem
+
+        rejected = retry_or_give_up(problem)
+      end
+    end
+
+    def summary(answers)
+      "Create #{answers.shape} runbook #{File.join(parent, answers.main)} from the #{answers.template} template?"
+    end
+
+    # A yes/no question; Enter, or input that has run out, is yes.
+    def confirm?(question)
+      @output.puts
+      @prompt.yes_unless_no?(question)
+    end
+
+    # The template called +name+ among those offered.
+    def template_named(name) = @templates.find { it.name == name } || raise(RunbookError, "no template named #{name}")
+
+    # The files for +answers+: relative to the parent directory => text. A
+    # single file takes the runbook's markdown; support files go beside it.
+    def files(answers)
+      rendered = template_named(answers.template).render(answers.context)
+      return rendered.transform_keys { File.join(answers.location, it) } unless answers.single_file?
+
+      support = Template.support_files(rendered).transform_keys { File.join(answers.location, it) }
+      { answers.main => SingleFile.from_directory(rendered), **support }
+    end
+
+    # Write the runbook and say what to do next. Returns the exit status.
+    def write(answers)
+      problem = self.class.conflict(File.join(parent, answers.location))
+      raise RunbookError, problem if problem
+
+      files(answers).each do |rel, text|
+        full = File.join(parent, rel)
+        FileUtils.mkdir_p(File.dirname(full))
+        File.write(full, text)
+        @output.puts "created #{full}"
+      end
+      path = File.join(parent, answers.main)
+      @output.puts <<~NEXT
+
+        Next:
+          #{CLI::PROGRAM} --check #{path}
+          #{CLI::PROGRAM} #{path}
+      NEXT
+      0
+    end
+
+    private
+
+    # Say what was wrong before the question is asked again, and return it
+    # for that ask. When input has already run out, asking again would loop
+    # forever, so stop instead.
+    def retry_or_give_up(problem)
+      raise RunbookError, problem if @prompt.exhausted?
+
+      @output.puts "  #{problem}"
+      problem
+    end
+
+    def cancelled
+      @output.puts CANCELLED
+      1
+    end
+  end
+end

data/lib/runsheets.rb

@@ -25,10 +25,14 @@ module Runsheets
   class RunbookError < Error; end
   class RunError < Error; end
 
-  autoload :Assets, File.expand_path("runsheets/assets", __dir__)
-  autoload :CLI,    File.expand_path("runsheets/cli", __dir__)
-  autoload :Pages,  File.expand_path("runsheets/pages", __dir__)
-  autoload :Web,    File.expand_path("runsheets/web", __dir__)
+  autoload :Assets,     File.expand_path("runsheets/assets", __dir__)
+  autoload :CLI,        File.expand_path("runsheets/cli", __dir__)
+  autoload :Pages,      File.expand_path("runsheets/pages", __dir__)
+  autoload :Prompt,     File.expand_path("runsheets/prompt", __dir__)
+  autoload :StepRunner, File.expand_path("runsheets/step_runner", __dir__)
+  autoload :Template,   File.expand_path("runsheets/template", __dir__)
+  autoload :Web,        File.expand_path("runsheets/web", __dir__)
+  autoload :Wizard,     File.expand_path("runsheets/wizard", __dir__)
 
   class << self
     attr_writer :runs_dir
@@ -74,6 +78,7 @@ require_relative "runsheets/front_matter"
 require_relative "runsheets/fences"
 require_relative "runsheets/block"
 require_relative "runsheets/renderer"
+require_relative "runsheets/slug"
 require_relative "runsheets/step"
 require_relative "runsheets/single_file"
 require_relative "runsheets/runbook"

data/templates/asgard/.loki.erb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+# asgard's entry point for the <%= title %> runbook beside it. Blocks in the
+# runbook run in this directory, so `asgard` finds this file first.
+
+import "*.loki"
+
+class Tasks
+  header <%= ruby_string("#{name}: tasks for the #{title} runbook") %>
+end

data/templates/asgard/runbook.md.erb

@@ -0,0 +1,23 @@
+---
+title: <%= yaml title %>
+when_to_use: <%= yaml when_to_use %>
+prerequisites:
+  - The asgard command on the PATH (gem install asgard)
+tags: [asgard]
+inputs:
+  - name: WORK_DIR
+    prompt: Where this runbook writes its files
+    default: /tmp/<%= name %>
+escalation: <%= yaml escalation %>
+---
+
+# <%= title %>
+
+Checks and tasks whose code lives in [asgard](https://github.com/MadBomber/asgard)
+tasks, so each block stays one line. The tasks are in `tasks.loki`; `.loki`
+is asgard's entry point and imports it. Blocks run in this runbook's
+directory, and asgard uses the nearest `.loki`, so these are the tasks they
+get. Inputs reach the tasks as environment variables: `env(:work_dir)`.
+
+Run `asgard --help` in this directory to list the tasks.
+

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

@@ -0,0 +1,13 @@
+---
+title: Preflight
+kind: verify
+timeout: 30
+---
+
+```bash run
+asgard preflight
+```
+
+```text expect
+preflight: WORK_DIR is {{any}}
+```

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

@@ -0,0 +1,16 @@
+---
+title: Do the work
+kind: automated
+timeout: 300
+---
+
+The runbook says when and why; the task says how. Change `work` in
+`tasks.loki`, not this block.
+
+```bash run
+asgard work
+```
+
+```text expect
+work: wrote {{any}}/last-run
+```

data/templates/asgard/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/asgard/tasks.loki

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+# The runbook's work. WORK_DIR is a runbook input; env(:work_dir) reads it.
+class Tasks
+  desc "preflight", "Fail unless WORK_DIR is set"
+  def preflight
+    dir = env(:work_dir, "")
+    abort "preflight: WORK_DIR is empty" if dir.empty?
+    puts "preflight: WORK_DIR is #{dir}"
+  end
+
+  desc "work", "Write the time to WORK_DIR/last-run"
+  def work
+    dir = env(:work_dir, "")
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, "last-run"), "#{Time.now.utc}\n")
+    puts "work: wrote #{dir}/last-run"
+  end
+
+  desc "check", "Fail unless WORK_DIR/last-run has something in it"
+  def check
+    path = File.join(env(:work_dir, ""), "last-run")
+    abort "check: #{path} is missing or empty" unless File.size?(path)
+    puts "check: last run #{File.read(path).strip}"
+  end
+end

data/templates/asgard/template.yml

@@ -0,0 +1,2 @@
+order: 6
+description: "Checks and tasks as asgard tasks in .loki files beside the runbook"

data/templates/asgard/verify.md.erb

@@ -0,0 +1,12 @@
+---
+title: Verify
+kind: verify
+---
+
+```bash run
+asgard check
+```
+
+```text expect
+check: last run {{any}}
+```

data/templates/checks/runbook.md.erb

@@ -0,0 +1,15 @@
+---
+title: <%= yaml title %>
+when_to_use: <%= yaml when_to_use %>
+prerequisites:
+  - Nothing; every step only reads
+tags: [checks]
+escalation: <%= yaml escalation %>
+---
+
+# <%= title %>
+
+A runbook of checks only. Every step is `kind: verify`: it runs commands
+that read, never change, and compares what they print with what is
+expected. Run the steps in order, or all at once from the Checks page.
+

data/templates/checks/steps/010-tools.md.erb

@@ -0,0 +1,17 @@
+---
+title: The tools are installed
+kind: verify
+timeout: 30
+---
+
+Each `bash run` block gets a Run button. The `text expect` block under it
+is compared with its output; `{{any}}` matches whatever changes from
+machine to machine.
+
+```bash run
+git --version
+```
+
+```text expect
+git version {{any}}
+```

data/templates/checks/steps/020-disk-space.md.erb

@@ -0,0 +1,14 @@
+---
+title: There is disk space
+kind: verify
+timeout: 30
+---
+
+A check fails when its block exits non-zero. This one fails when the file
+system holding the runbook is 90% full or more.
+
+```bash run
+used=$(df -P . | awk 'NR == 2 { sub("%", "", $5); print $5 }')
+echo "disk use: ${used}%"
+test "$used" -lt 90
+```

data/templates/checks/steps/030-writable.md.erb

@@ -0,0 +1,13 @@
+---
+title: The directory is writable
+kind: verify
+timeout: 30
+---
+
+```bash run
+test -w . && echo "can write here"
+```
+
+```text expect
+can write here
+```

data/templates/checks/template.yml

@@ -0,0 +1,2 @@
+order: 1
+description: "Checks only: verify steps that read and compare, never change"

data/templates/inputs/runbook.md.erb

@@ -0,0 +1,40 @@
+---
+title: <%= yaml title %>
+when_to_use: <%= yaml when_to_use %>
+prerequisites:
+  - python3 on the PATH, for the step in another language
+tags: []
+inputs:
+  - name: GREETING
+    prompt: A value with a default
+    default: hello
+  - name: TARGET
+    prompt: A value with no default; the operator types it
+  - name: API_TOKEN
+    prompt: A secret, masked in the form and kept out of the record
+    secret: true
+# Map a language to the command that runs its blocks. The block is written
+# to a file and the file's path is appended to the command. For a database:
+#   sql: psql -X -v ON_ERROR_STOP=1 -f
+interpreters:
+  python: python3
+escalation: <%= yaml escalation %>
+---
+
+# <%= title %>
+
+Checks and tasks driven by inputs. The start-run form asks for each
+input; every block gets them as environment variables. A blank field
+falls back to the same variable in the environment runsheets started in,
+then to the default. A `secret` is masked in the form, never written to
+the run record, and redacted wherever a block prints it.
+
+<% 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/inputs/steps/010-preflight.md.erb

@@ -0,0 +1,15 @@
+---
+title: Preflight
+kind: verify
+timeout: 30
+---
+
+An input with no default may arrive empty. Check for it first.
+
+```bash run
+test -n "$TARGET" && echo "TARGET is $TARGET"
+```
+
+```text expect
+TARGET is {{any}}
+```

data/templates/inputs/steps/020-use-the-inputs.md.erb

@@ -0,0 +1,13 @@
+---
+title: Use the inputs
+kind: automated
+timeout: 60
+---
+
+This block prints the secret on purpose: the output and the record show
+it redacted.
+
+```bash run
+echo "$GREETING, $TARGET"
+echo "token: $API_TOKEN"
+```

data/templates/inputs/steps/030-another-language.md.erb

@@ -0,0 +1,13 @@
+---
+title: Another language
+kind: automated
+timeout: 60
+---
+
+`python` blocks run because the front matter maps `python` to `python3`
+under `interpreters`. `bash`, `sh`, `zsh` and `ruby` need no mapping.
+
+```python run
+import os
+print(os.environ["GREETING"], "from python")
+```

data/templates/inputs/template.yml

@@ -0,0 +1,2 @@
+order: 5
+description: "Checks, tasks and inputs: defaults, a secret, another language"

data/templates/inputs/verify.md.erb

@@ -0,0 +1,12 @@
+---
+title: Verify
+kind: verify
+---
+
+```bash run
+test -n "$API_TOKEN" && echo "API_TOKEN is set"
+```
+
+```text expect
+API_TOKEN is set
+```

data/templates/rollback/rollback.md.erb

@@ -0,0 +1,10 @@
+---
+title: Rollback
+---
+
+When a step fails partway, put the copy back, then run Verify.
+
+```bash destructive
+cp "$WORK_DIR/last-run.bak" "$WORK_DIR/last-run"
+echo "restored $WORK_DIR/last-run"
+```

data/templates/rollback/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 and tasks, plus a way back. The step that destroys something is a
+`bash destructive` block: its Run button asks for a typed confirmation.
+The step before it keeps a copy, and Rollback, which sits beside every
+step, puts the copy back.
+
+<% 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/rollback/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/rollback/steps/020-keep-a-copy.md.erb

@@ -0,0 +1,18 @@
+---
+title: Keep a copy
+kind: automated
+timeout: 120
+---
+
+Save what the next step replaces, so Rollback has something to restore.
+
+```bash run
+mkdir -p "$WORK_DIR"
+touch "$WORK_DIR/last-run"
+cp "$WORK_DIR/last-run" "$WORK_DIR/last-run.bak"
+echo "saved $WORK_DIR/last-run.bak"
+```
+
+```text expect
+saved {{any}}/last-run.bak
+```

data/templates/rollback/steps/030-replace.md.erb

@@ -0,0 +1,14 @@
+---
+title: Replace
+kind: automated
+timeout: 300
+---
+
+The change that cannot be taken back without the copy. A `destructive`
+block runs only after the operator types the confirmation code, and the
+step shows a warning banner.
+
+```bash destructive
+date -u > "$WORK_DIR/last-run"
+echo "replaced $WORK_DIR/last-run"
+```