runsheets 0.0.1 → 0.0.2

data/lib/runsheets/config.rb

@@ -16,7 +16,7 @@ module Runsheets
   #   5. the overrides hash, which the CLI fills from the command line
   #
   # Every key in defaults.yml is an attribute here (dir, port, bind, runs_dir,
-  # open, check, init, dump, engineer, why, log_level, quiet). Paths are
+  # open, check, dump, engineer, why, log_level, quiet). Paths are
   # expanded; flags accept 1/true/yes/on.
   class Config < MywayConfig::Base
     config_name :runsheets
@@ -28,6 +28,14 @@ module Runsheets
     class << self
       def blank?(value) = value.nil? || value.to_s.strip.empty?
 
+      # File.expand_path, but a ~user that names nobody is a ConfigError
+      # rather than an ArgumentError, so the CLI reports it in one line.
+      def expand_path(path, base = nil)
+        File.expand_path(path, base)
+      rescue ArgumentError => e
+        raise ConfigError, "cannot expand #{path}: #{e.message}"
+      end
+
       # A coercion that hands the stripped text to the block, or gives nil for
       # a blank so the bundled default fills it (see fill_blanks_from_defaults).
       def unless_blank = ->(v) { blank?(v) ? nil : yield(v.to_s.strip) }
@@ -47,9 +55,38 @@ module Runsheets
           File.join(Dir.home, ".config", config_name.to_s, "#{config_name}.yml")
       end
 
+      # The config file named in place of the project config: +given+ (the
+      # --config option), else RUNSHEETS_CONFIG, expanded; nil when neither
+      # names one. Raises ConfigError when the file named does not exist.
+      def explicit_path(given, env: ENV)
+        name = [given, env["RUNSHEETS_CONFIG"]].find { !blank?(it) } or return nil
+        path = expand_path(name)
+        raise ConfigError, "config file not found: #{path}" unless File.file?(path)
+
+        path
+      end
+
       # The project config read when neither --config nor RUNSHEETS_CONFIG names a file.
       def project_path = File.expand_path(Anyway::Settings.default_config_path.call(config_name))
 
+      # The settings one config file holds, as a string-keyed Hash, read as
+      # myway_config reads it: the section for +environment+ when one is
+      # set and the file has it, else the whole file. {} when it is
+      # missing, unreadable or not a mapping.
+      def file_settings(path, environment: current_environment)
+        data = YAML.safe_load_file(path, aliases: false)
+        return {} unless data.is_a?(Hash)
+
+        section = data[environment] if environment
+        section.is_a?(Hash) ? section : data
+      rescue Psych::Exception, SystemCallError
+        {}
+      end
+
+      # The environment whose section a config file is read from, or nil
+      # (the usual case for a command) to read the whole file.
+      def current_environment = Anyway::Settings.current_environment&.to_s
+
       # The bundled defaults, coerced, keyed by attribute. What the help text shows.
       def bundled_defaults = schema.to_h { |key, value| [key, type_caster.coerce(key, value)] }
 
@@ -59,12 +96,12 @@ module Runsheets
 
     # Coercions: the raw YAML/env/CLI value becomes the type the attribute needs.
     TEXT = unless_blank(&:itself)
-    PATH = unless_blank { File.expand_path(it) }
+    PATH = unless_blank { expand_path(it) }
     PORT = unless_blank { whole_number(it) }
     FLAG = ->(v) { v == true || TRUE_WORDS.include?(v.to_s.strip.downcase) }
 
-    attr_config :dir, :port, :bind, :runs_dir, :open, :check, :init, :dump, :engineer, :why, :log_level, :quiet
-    coerce_types dir: PATH, runs_dir: PATH, bind: TEXT, port: PORT, open: FLAG, check: FLAG, init: FLAG, dump: FLAG,
+    attr_config :dir, :port, :bind, :runs_dir, :open, :check, :dump, :engineer, :why, :log_level, :quiet
+    coerce_types dir: PATH, runs_dir: PATH, bind: TEXT, port: PORT, open: FLAG, check: FLAG, dump: FLAG,
                  engineer: TEXT, why: TEXT, log_level: unless_blank { SessionLog.level_name(it) }, quiet: FLAG
 
     on_load :fill_blanks_from_defaults
@@ -83,6 +120,16 @@ module Runsheets
     # The config files that exist and were read, lowest layer first.
     def files = [self.class.xdg_path, path].select { File.file?(it) }
 
+    # The dir a config file sets, whatever RUNSHEETS_DIR or the command line
+    # say: from the highest file that has one, expanded, else nil.
+    def file_dir
+      files.reverse_each do |file|
+        value = self.class.file_settings(file)["dir"]
+        return self.class.expand_path(value.to_s) unless self.class.blank?(value)
+      end
+      nil
+    end
+
     # The bind address in force when it came from the project config found
     # in the current directory, else nil. That file arrives with whatever
     # repository was cloned, so the CLI will not let it alone open the
@@ -92,18 +139,15 @@ module Runsheets
       return nil if @override_keys.include?("bind") || !self.class.blank?(ENV["RUNSHEETS_BIND"])
       return nil unless File.file?(path.to_s)
 
-      data = YAML.safe_load_file(path, aliases: false)
-      data.is_a?(Hash) && data.key?("bind") ? bind : nil
-    rescue Psych::Exception
-      nil
+      self.class.file_settings(path).key?("bind") ? bind : nil
     end
 
     # The settings in force as the flat hash a config file holds. dump is
     # left out: it is an action for this run, and a saved `dump: true` would
-    # make every later run print and exit; check and init likewise. why is
+    # make every later run print and exit; check likewise. why is
     # left out too: it belongs to one session, and a saved one would start
     # every later session with it.
-    def settings = (self.class.config_attributes - %i[dump check init why]).to_h { [it.to_s, public_send(it)] }
+    def settings = (self.class.config_attributes - %i[dump check why]).to_h { [it.to_s, public_send(it)] }
 
     # The settings in force as the text of a config file: a comment header,
     # then one key per setting. `runsheets --dump` prints this.
@@ -120,12 +164,7 @@ module Runsheets
     # Where anyway_config's yml loader reads from. A file named explicitly
     # (option or variable) must exist; the project config may be absent.
     def resolve_config_path(_name, _env_prefix)
-      explicit = @explicit_path
-      explicit = ENV["RUNSHEETS_CONFIG"] if self.class.blank?(explicit)
-      explicit = nil if self.class.blank?(explicit)
-      raise ConfigError, "config file not found: #{explicit}" if explicit && !File.file?(File.expand_path(explicit))
-
-      @path = explicit ? File.expand_path(explicit) : self.class.project_path
+      @path = self.class.explicit_path(@explicit_path) || self.class.project_path
     end
 
     # A blank in any layer (RUNSHEETS_PORT="" say) coerces to nil; put the

data/lib/runsheets/prompt.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Runsheets
+  # Questions at the terminal, for `--new` and `--run`: answers are read
+  # from +input+ and prompts written to +output+, so a test or a script
+  # piping answers in drives it as a person would.
+  #
+  # Once input runs out (Ctrl-D, a pipe that ends, stdin from /dev/null)
+  # every read gives nil and #exhausted? is true, so a caller can stop
+  # asking instead of waiting or looping.
+  class Prompt
+    def initialize(input: $stdin, output: $stdout)
+      @input     = input
+      @output    = output
+      @exhausted = false
+    end
+
+    def exhausted? = @exhausted
+
+    # A line of input, stripped, or nil when input has run out.
+    def line = finish(@input.gets)&.strip
+
+    # A secret: read without echo at a terminal, and only its newline
+    # removed, since spaces can be part of a password. nil when input has
+    # run out.
+    def secret
+      return finish(@input.gets)&.chomp unless @input.tty?
+
+      text = @input.noecho(&:gets)
+      @exhausted = true if text.nil?
+      @output.puts # the Enter that noecho did not show
+      text&.chomp
+    end
+
+    # A yes/no question where no is the default: yes only for an answer
+    # starting with y.
+    def yes?(question) = answered_yes?(question, "y/N", false)
+
+    # A yes/no question where yes is the default: Enter, or no more input,
+    # is yes, and so is an answer starting with y.
+    def yes_unless_no?(question) = answered_yes?(question, "Y/n", true)
+
+    private
+
+    def answered_yes?(question, hint, default)
+      @output.print "#{question} [#{hint}]: "
+      answer = line.to_s.downcase
+      answer.empty? ? default : answer.start_with?("y")
+    end
+
+    # +text+, as read; nil marks input as run out and ends the prompt's line.
+    def finish(text)
+      return text unless text.nil?
+
+      @exhausted = true
+      @output.puts
+      nil
+    end
+  end
+end

data/lib/runsheets/runbook.rb

@@ -291,11 +291,23 @@ module Runsheets
       dupes = steps.map(&:slug).tally.select { |_, n| n > 1 }.keys
       warnings << "duplicate step slugs: #{dupes.join(', ')}" if dupes.any?
       steps.map(&:slug).intersection(%w[runbook verify rollback]).each { warnings << "step #{it} has the name of a special document; give it a number" }
+      warnings.concat(shadow_warnings)
       warnings.concat(@section_warnings)
       documents.each_value do |step|
         step.warnings.each { warnings << "#{step.slug}: #{it}" }
       end
       warnings
     end
+
+    # A warning for each numbered step whose name without the number is the
+    # slug of another document (030-verify beside verify.md), which that
+    # name finds first.
+    def shadow_warnings
+      steps.filter_map do |step|
+        slug = step.slug
+        name = Slug.bare(slug)
+        "step #{slug} is named like #{name}.md, so `--run #{name}` runs that; use `--run #{slug}`" if name != slug && documents.key?(name)
+      end
+    end
   end
 end

data/lib/runsheets/single_file.rb

@@ -85,9 +85,42 @@ module Runsheets
     # A step slug for a section: position-numbered like a directory step,
     # so block ids and record files look the same either way.
     def self.slug_for(title, position)
-      words = title.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+      words = Slug.of(title)
       words = "step" if words.empty?
       format("%<number>03d-%<words>s", number: position * 10, words:)
     end
+
+    # The reverse of split: one single-file runbook made from a directory
+    # runbook's files (relative path => text), as `runsheets --new` writes
+    # one. runbook.md gives the front matter and preamble, then comes a ##
+    # section per step in order, then Verify and Rollback. Each file's front
+    # matter, less its title, becomes the attribute comment under its heading.
+    def self.from_directory(files)
+      steps    = files.keys.grep(%r{\A#{Runbook::STEPS_DIR}/[^/]+\.md\z}).sort_by { [File.basename(it)[/\A\d+/].to_i, it] }
+      extras   = Runbook::EXTRAS.map { "#{it}.md" }.select { files.key?(it) }
+      sections = (steps + extras).map { section(files[it], fallback: File.basename(it, ".md")) }
+      [files.fetch("runbook.md").rstrip, *sections].join("\n\n") << "\n"
+    end
+
+    # A ## section from one step file's text; +fallback+ is its basename,
+    # whose title stands in when the file has none.
+    def self.section(text, fallback:)
+      parsed  = FrontMatter.parse(text)
+      title   = parsed.data["title"] || Slug.title(Slug.bare(fallback))
+      attrs   = parsed.data.except("title")
+      heading = "## #{title}"
+      heading += "\n<!-- #{format_attributes(attrs)} -->" unless attrs.empty?
+      "#{heading}\n\n#{parsed.body.strip}"
+    end
+
+    # The reverse of parse_attributes:
+    # { "kind" => "automated", "timeout" => 300 } => "kind: automated, timeout: 300".
+    # A string YAML would read as something else (yes, 010, a: b) is quoted.
+    def self.format_attributes(data)
+      data.map do |key, value|
+        plain = value.is_a?(String) && value.match?(%r{\A[A-Za-z][\w./-]*\z}) && YAML.safe_load(value) == value
+        "#{key}: #{plain || !value.is_a?(String) ? value : value.to_json}"
+      end.join(", ")
+    end
   end
 end

data/lib/runsheets/slug.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # The text rules shared by steps, single-file sections and the --new
+  # wizard, so each kind of name is made the same way everywhere.
+  module Slug
+    module_function
+
+    # "DB Refresh!" => "db-refresh": lowercase letters and digits joined by
+    # single hyphens. Text with nothing usable in it gives "".
+    def of(text) = text.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+
+    # "020-take-a-backup" => "take-a-backup": a step slug without its number.
+    def bare(slug) = slug.to_s.sub(/\A\d+[-_]?/, "")
+
+    # "db-refresh" => "Db refresh": the title a slug or name suggests.
+    def title(text) = text.to_s.tr("-_", " ").capitalize
+  end
+end

data/lib/runsheets/step.rb

@@ -36,7 +36,7 @@ module Runsheets
     end
 
     def title
-      data["title"] || Renderer.title_of(body) || slug.sub(/\A\d+[-_]?/, "").tr("-_", " ").capitalize
+      data["title"] || Renderer.title_of(body) || Slug.title(Slug.bare(slug))
     end
 
     def kind = (data["kind"] || (blocks.any?(&:executable?) ? "automated" : "manual")).to_s

data/lib/runsheets/step_runner.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # `runsheets --run STEP RUNBOOK`: run one step of a runbook at the
+  # terminal. It is recorded like a run from the page: a session with an
+  # engineer and a why, a run record, and the session log, whose echo shows
+  # each block's output as it comes.
+  #
+  # Each block does at the terminal what it does on the page:
+  #
+  #   run          runs, and fails the step unless it exits 0
+  #   expect       is compared with the output of the block above it
+  #   destructive  runs only once its confirmation code is typed
+  #   terminal     is shown, and the operator says they ran it
+  #   background   cannot run here: nothing would be left to stop it
+  #
+  # A step with nothing to run or confirm is shown, and the operator says it
+  # is done. Answers are read from +input+, so when input runs out (a cron
+  # job, stdin from /dev/null) anything that needs a person fails the step
+  # rather than waiting.
+  class StepRunner
+    attr_reader :session, :runbook, :step
+
+    # The document of +runbook+ that +name+ names: its slug ("020-greet"),
+    # else its slug without the number ("greet"), which covers verify,
+    # rollback and runbook too. A number names nothing here; numbers are
+    # only places in the list choose_step shows. Raises RunbookError saying
+    # what can be named when nothing, or more than one step, matches.
+    def self.find_step(runbook, name)
+      name = name.to_s.strip
+      if name.match?(/\A\d+\z/)
+        raise RunbookError, "#{name.inspect} is a number; name the step by its slug or name, or leave STEP out to choose from a numbered list"
+      end
+
+      found = runbook.step(name) and return found
+
+      matches = runbook.steps.select { Slug.bare(it.slug) == name }
+      return matches.first if matches.one?
+
+      what = matches.empty? ? "no step #{name.inspect}" : "#{name.inspect} matches #{matches.map(&:slug).join(', ')}"
+      raise RunbookError, "#{what} in #{runbook.title} (#{runbook.main_path}); steps: #{runbook.documents.keys.join(', ')}"
+    end
+
+    # The documents --run offers to choose from: the numbered steps, then
+    # verify and rollback, after the landing page when it has blocks to run
+    # or confirm.
+    def self.choices(runbook)
+      landing = runbook.landing if runbook.landing.blocks.any? { it.executable? || it.terminal? }
+      [landing, *runbook.steps, *runbook.extras.values].compact
+    end
+
+    # Ask which step to run, listing the choices. The answer is a number in
+    # the list or anything find_step takes; a wrong one is asked again.
+    # Raises RunError when input runs out with nothing chosen.
+    def self.choose_step(runbook, input:, output:)
+      choices = choices(runbook)
+      raise RunbookError, "#{runbook.title} has no steps" if choices.empty?
+
+      prompt = Prompt.new(input:, output:)
+      output.puts "Steps in #{runbook.title}:", *choice_lines(choices)
+      loop do
+        output.print "Which step? (its number in the list, or its name): "
+        answer = prompt.line or raise RunError, "no step chosen"
+
+        pick = pick_step(runbook, choices, answer) and return pick
+        output.puts "  #{answer.inspect} is not one of the steps"
+      end
+    end
+
+    # The list choose_step shows: number, slug and title, with the steps
+    # that cannot run at a terminal marked.
+    def self.choice_lines(choices)
+      width = choices.map { it.slug.size }.max
+      choices.map.with_index(1) do |step, i|
+        format("  %<i>2d) %<slug>-#{width}s  %<title>s%<note>s", i:, slug: step.slug, title: step.title, note: refusal(step) ? "  (page only)" : "")
+      end
+    end
+
+    # The choice +answer+ names, or nil. A number is a place in the list,
+    # and only that; anything else is looked up as find_step does.
+    def self.pick_step(runbook, choices, answer)
+      return if answer.empty?
+      return choices[answer.to_i - 1] if answer.match?(/\A\d+\z/) && answer.to_i.between?(1, choices.size)
+
+      find_step(runbook, answer)
+    rescue RunbookError
+      nil
+    end
+
+    # Why +step+ cannot be run at a terminal, or nil.
+    def self.refusal(step)
+      background = step.blocks.select(&:background?)
+      return if background.empty?
+
+      "#{step.slug} has a background block (#{background.map(&:id).join(', ')}), which nothing would be left to stop; " \
+        "start it from the page"
+    end
+
+    # Declared inputs that +step+'s blocks refer to and +values+ leaves blank.
+    def self.blank_inputs(runbook, step, values)
+      referenced = step.blocks.select { it.executable? || it.terminal? }.flat_map(&:referenced_variables)
+      runbook.inputs.select { referenced.include?(it.name) && values[it.name].to_s.empty? }
+    end
+
+    # What a prompt shows of an input's current value: " [value]", " [set]"
+    # for a secret with one, or "" when it has none.
+    def self.shown(input, current)
+      return "" if current.to_s.empty?
+
+      " [#{input.secret? ? 'set' : current}]"
+    end
+
+    # Expected and actual lines that differ, marked - and +, for a failed
+    # Expectation comparison.
+    def self.mismatch_lines(result)
+      result.rows.reject { it.tag == :same }.flat_map do |row|
+        [("- #{row.expected.map(&:first).join}" if row.expected), ("+ #{row.actual.map(&:first).join}" if row.actual)].compact
+      end
+    end
+
+    # "A has no value; the step needs it", or for several names
+    # "A, B have no value; the step needs them".
+    def self.blank_message(names)
+      many = names.size > 1
+      "#{names.join(', ')} #{many ? 'have' : 'has'} no value; the step needs #{many ? 'them' : 'it'}"
+    end
+
+    # Raises RunError when +step+ cannot be run at a terminal, so a step
+    # that would be refused is refused before any session starts.
+    def initialize(runbook:, step:, input: $stdin, output: $stdout)
+      refusal = self.class.refusal(step)
+      raise RunError, refusal if refusal
+
+      @runbook = runbook
+      @step    = step
+      @output  = output
+      @prompt  = Prompt.new(input:, output:)
+      @session = nil
+      @run     = nil
+    end
+
+    # Run the step in +session+. Returns the exit status: 0 when every
+    # block ran, matched and was confirmed, 1 otherwise. A numbered step
+    # that succeeds is marked done.
+    def run(session)
+      @session = session
+      inputs   = ask_inputs
+      @run     = session.open(runbook, inputs:)
+      @output.puts "#{step.title} [#{step.slug}]"
+      return 1 unless performed?
+
+      @run.mark_step(step.slug, status: "done") if step.position
+      0
+    end
+
+    # Do the step: each block in turn, stopping at the first that fails, or
+    # for a step with nothing to run, ask whether it is done.
+    def performed? = needs_person? ? done? : step.blocks.all? { perform(it) }
+
+    # Whether the step has nothing to run or confirm, so a person says when
+    # it is done.
+    def needs_person? = step.blocks.none? { it.executable? || it.terminal? }
+
+    # Every input the runbook declares, asked for in order as the page's
+    # start form does, each offering the value it has now (from the
+    # environment or its default) for Enter to keep. Once input runs out
+    # the rest keep theirs unasked. Raises RunError when an input the step
+    # uses is still blank.
+    def ask_inputs
+      values = Run.resolve_inputs(runbook, {})
+      values = runbook.inputs.to_h { [it.name, ask_input(it, values[it.name])] }
+      blank  = self.class.blank_inputs(runbook, step, values).map(&:name)
+      raise RunError, self.class.blank_message(blank) if blank.any?
+
+      values
+    end
+
+    # One input's value: what was typed, else +current+. A secret is read
+    # without echo, and its value is never shown.
+    def ask_input(input, current)
+      return current if @prompt.exhausted?
+
+      @output.print "#{input.prompt || input.name} (#{input.name})#{self.class.shown(input, current)}: "
+      answer = input.secret? ? @prompt.secret : @prompt.line
+      answer.to_s.empty? ? current : answer
+    end
+
+    # Do what +block+ asks for. Returns whether the step can carry on.
+    def perform(block)
+      case block.kind
+      when :run, :destructive then execute(block)
+      when :terminal then confirm_terminal(block)
+      else true
+      end
+    end
+
+    # Run a block, then check its exit status and its expect block.
+    def execute(block)
+      execution = start(block) or return false
+      execution.wait
+      return failed(block.id, Run.ending(execution).last) unless execution.success?
+
+      expected = step.expected_output(block.id)
+      expected.nil? || matches?(block, expected, execution.output)
+    end
+
+    # Start a block, asking for its confirmation code when it is
+    # destructive. Returns the Execution, or nil when it was not confirmed.
+    def start(block)
+      id = block.id
+      begin
+        @run.execute(id)
+      rescue Run::ConfirmationRequired => e
+        @output.print "#{id} is destructive. Type #{e.challenge} to run it: "
+        start_confirmed(id)
+      end
+    end
+
+    # Run block +id+ with the code that is typed; nil when it is not the code.
+    def start_confirmed(id)
+      @run.execute(id, confirm: @prompt.line.to_s)
+    rescue Run::ConfirmationRequired
+      failed(id, "not confirmed")
+      nil
+    end
+
+    # Whether +output+ is what the expect block says; prints the lines that
+    # differ when it is not.
+    def matches?(block, expected, output)
+      result = Expectation.compare(expected, output)
+      return true if result.match?
+
+      @output.puts "#{block.id}: the output is not what the expect block says:", *self.class.mismatch_lines(result).map { "  #{it}" }
+      failed(block.id, "output did not match")
+    end
+
+    # Show a terminal block and ask whether the operator ran it.
+    def confirm_terminal(block)
+      @output.puts "Run this yourself:", *block.code.lines(chomp: true).map { "  #{it}" }
+      return failed(block.id, "not confirmed") unless @prompt.yes?("Did you run it?")
+
+      @output.print "Note (optional): "
+      @run.acknowledge(block.id, note: @prompt.line)
+      true
+    end
+
+    # Show a step with nothing to run and ask whether it is done.
+    def done?
+      @output.puts "", step.body.strip, ""
+      @prompt.yes?("Done?") || failed(step.slug, "not done")
+    end
+
+    private
+
+    # Say why +label+ (a block id or step slug) failed; false, for the step.
+    def failed(label, why)
+      @output.puts "#{label}: #{why}"
+      false
+    end
+  end
+end

data/lib/runsheets/template.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Runsheets
+  # A starter runbook that `runsheets --new` fills in: a directory under
+  # templates/ at the gem root holding a directory runbook. Files ending in
+  # .erb are rendered (the suffix dropped); any other file is copied as is.
+  #
+  #   templates/asgard/
+  #     template.yml           order: and description: for the --new menu
+  #     runbook.md.erb
+  #     steps/010-preflight.md.erb
+  #     verify.md.erb          (optional)
+  #     rollback.md.erb        (optional)
+  #     .loki                  support files: anything else, copied beside
+  #
+  # Each template is written once, in the directory shape. A single-file
+  # runbook is made from the rendered files (SingleFile.from_directory), so the two
+  # shapes cannot drift apart. Step bodies must therefore use ### and
+  # deeper headings: a ## heading would start a new step in a single file.
+  class Template
+    DIR     = File.expand_path("../../templates", __dir__)
+    DEFAULT = "tasks"
+    META    = "template.yml"
+
+    # What the ERB sees. +yaml+ quotes a value for front matter, so a title
+    # such as "null" or "yes: no" stays a string. +ruby_string+ makes a
+    # value a Ruby string literal for a support file such as asgard's .loki,
+    # so a quote or #{} in a title is text, not code.
+    Context = Data.define(:name, :title, :when_to_use, :escalation, :single_file) do
+      def yaml(value) = value.to_s.to_json
+      def ruby_string(value) = value.to_s.dump
+      def binding_for = binding
+    end
+
+    # A template without an order in template.yml sorts after those with one.
+    UNORDERED = 1_000
+
+    attr_reader :name, :dir, :description, :order
+
+    # Every template under +root+, by the order in its template.yml, then
+    # by name. Raises RunbookError when there are none.
+    def self.all(root: DIR)
+      templates = Dir.glob("*/", base: root).map { new(File.join(root, it.chomp("/"))) }.sort_by { [it.order, it.name] }
+      raise RunbookError, "no runbook templates found in #{root}" if templates.empty?
+
+      templates
+    end
+
+    # Whether +rel+, a rendered path, is part of the runbook itself rather
+    # than a support file: runbook.md, a step, verify.md or rollback.md.
+    def self.runbook_file?(rel)
+      rel == "runbook.md" || rel.match?(%r{\A#{Runbook::STEPS_DIR}/[^/]+\.md\z}) || Runbook::EXTRAS.any? { rel == "#{it}.md" }
+    end
+
+    # The rendered files that are not the runbook's own markdown.
+    def self.support_files(files) = files.reject { |rel, _| runbook_file?(rel) }
+
+    def initialize(dir)
+      @dir  = dir
+      @name = File.basename(dir)
+      meta  = File.file?(meta_path) ? YAML.safe_load_file(meta_path, aliases: false) : {}
+      meta  = {} unless meta.is_a?(Hash)
+      @description = meta["description"].to_s
+      @order       = Integer(meta["order"], exception: false) || UNORDERED
+    end
+
+    # The rendered directory runbook: relative path => text. An .erb file
+    # is rendered with +context+ and loses the suffix; others are copied.
+    def render(context)
+      sources.to_h do |rel|
+        text = File.read(File.join(dir, rel))
+        next [rel, text] unless rel.end_with?(".erb")
+
+        [rel.delete_suffix(".erb"), ERB.new(text, trim_mode: "-").result(context.binding_for)]
+      end
+    end
+
+    # The template's files, relative to its directory, sorted: everything,
+    # dotfiles included, but template.yml.
+    def sources
+      Dir.glob("**/*", File::FNM_DOTMATCH, base: dir).select { File.file?(File.join(dir, it)) }.reject { it == META }.sort
+    end
+
+    # Whether the template brings files besides the runbook's markdown, such
+    # as asgard's .loki files. A single-file runbook from it gets a folder.
+    def support_files? = sources.any? { !self.class.runbook_file?(it.delete_suffix(".erb")) }
+
+    private
+
+    def meta_path = File.join(dir, META)
+  end
+end

data/lib/runsheets/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Runsheets
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end