runsheets 0.0.1

data/lib/runsheets/run_record.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "monitor"
+
+module Runsheets
+  # The runsheet: everything that happened to one runbook during one
+  # session. The run directory is named by the session id, so a runbook's
+  # history stays under its slug and each run points back to its session.
+  #
+  #   <runs_root>/<runbook-slug>/<session-id>/
+  #     run.json        machine-readable record
+  #     run.md          human-readable transcript
+  #     blocks/
+  #       <block-id>.<n>.cmd   the exact code that ran
+  #       <block-id>.<n>.out   its stdout + stderr, secrets redacted
+  #
+  # Runs live outside the runbook so captured output never lands next to the
+  # docs in a repository.
+  class RunRecord
+    TIMESTAMP       = "%Y%m%dT%H%M%S"
+    # How a run ends. A run ends with its session, and its status is worked
+    # out from what was done (see #closing_status); "interrupted" is a run
+    # whose process was killed, found by the next start. Records from before
+    # sessions may say "abandoned".
+    STATUSES        = %w[running completed partial opened interrupted abandoned].freeze
+    FINAL_STATUSES  = (STATUSES - ["running"]).freeze
+    TRANSCRIPT_TAIL = 64 * 1024
+
+    attr_reader :dir, :runbook_slug, :runbook_title, :kind, :session_id, :started_at, :finished_at, :status,
+                :inputs, :events, :executions, :step_status, :acks
+
+    # Create the run directory, named by the session, and write the initial
+    # record. Secret inputs are never stored.
+    def self.start(runs_root, runbook, session_id:, inputs: {}, now: Time.now)
+      dir = create_unique_dir(File.join(runs_root, runbook.slug, session_id))
+      FileUtils.mkdir_p(File.join(dir, "blocks"))
+      new(dir:, runbook_slug: runbook.slug, runbook_title: runbook.title, session_id:, started_at: now,
+          inputs: visible_inputs(inputs, runbook)).write!
+    end
+
+    # The inputs as recorded: secret ones left out.
+    def self.visible_inputs(inputs, runbook) = inputs.reject { |name, _| runbook.input(name)&.secret? }.transform_keys(&:to_s)
+
+    # Read a record back from its run.json.
+    def self.load(dir)
+      data = JSON.parse(File.read(File.join(dir, "run.json")))
+      new(
+        dir:, runbook_slug: data["runbook"], runbook_title: data["title"], kind: data["kind"] || "run", session_id: data["session"],
+        started_at: Time.iso8601(data["started_at"]),
+        finished_at: data["finished_at"] && Time.iso8601(data["finished_at"]),
+        status: data["status"], inputs: data["inputs"] || {},
+        events: (data["events"] || []).map { it.transform_keys(&:to_sym) },
+        executions: (data["executions"] || []).map { it.transform_keys(&:to_sym) },
+        step_status: data["steps"] || {},
+        acks: (data["acks"] || {}).transform_values { it.transform_keys(&:to_sym) }
+      )
+    end
+
+    # Previous runs of a runbook, newest first.
+    def self.list(runs_root, slug)
+      dir = File.join(runs_root, slug)
+      return [] unless File.directory?(dir)
+
+      Dir.children(dir).map { File.join(dir, it, "run.json") }.select { File.file?(it) }.filter_map do |path|
+        load(File.dirname(path))
+      rescue StandardError # a record that is not one: unreadable, or JSON of the wrong shape
+        nil
+      end.sort_by(&:started_at).reverse
+    end
+
+    # Create +dir+, or +dir+-2, -3, ... if it exists, and return the one
+    # created. Creating is the check, so two callers never share one.
+    def self.create_unique_dir(dir)
+      FileUtils.mkdir_p(File.dirname(dir))
+      candidate = dir
+      n = 1
+      begin
+        Dir.mkdir(candidate)
+        candidate
+      rescue Errno::EEXIST
+        n += 1
+        candidate = "#{dir}-#{n}"
+        retry
+      end
+    end
+
+    def self.unique_dir(dir)
+      return dir unless File.exist?(dir)
+
+      n = 2
+      n += 1 while File.exist?("#{dir}-#{n}")
+      "#{dir}-#{n}"
+    end
+
+    # A code fence longer than any run of backticks in +text+, so the text
+    # cannot close it.
+    def self.fence_for(text) = "`" * [3, (text.to_s.scan(/`+/).map(&:size).max || 0) + 1].max
+
+    # +text+ as an inline code span that no backtick inside can close.
+    def self.code_span(text)
+      text  = text.to_s.tr("\n", " ")
+      ticks = "`" * ((text.scan(/`+/).map(&:size).max || 0) + 1)
+      pad   = text.start_with?("`") || text.end_with?("`") ? " " : ""
+      "#{ticks}#{pad}#{text}#{pad}#{ticks}"
+    end
+
+    # +text+ (a note) as markdown that renders as itself: on one line, with
+    # the characters that make HTML or markdown escaped.
+    MARKUP = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;" }.freeze
+
+    def self.plain(text) = text.to_s.gsub(/\s*\n\s*/, " ").gsub(/[&<>`*_\[\]\\]/) { MARKUP[it] || "\\#{it}" }
+
+    # Whether an execution hash (as stored in the record) counts as a
+    # failure. A background process the operator stopped is not one.
+    def self.failure?(hash)
+      case hash[:state]
+      when "timed_out", "failed" then true
+      when "finished"            then hash[:exit_status] != 0
+      else false
+      end
+    end
+
+    def initialize(dir:, runbook_slug:, runbook_title:, started_at:, kind: "run", session_id: nil, inputs: {}, status: "running",
+                   finished_at: nil, events: [], executions: [], step_status: {}, acks: {})
+      @dir           = dir
+      @runbook_slug  = runbook_slug
+      @runbook_title = runbook_title
+      @kind          = kind
+      @session_id    = session_id
+      @started_at    = started_at
+      @finished_at   = finished_at
+      @status        = status
+      @inputs        = inputs
+      @events        = events
+      @executions    = executions
+      @step_status   = step_status
+      @acks          = acks
+      @live          = {}
+      @lock          = Monitor.new
+    end
+
+    def id         = File.basename(dir)
+    def active?    = status == "running"
+    def completed? = status == "completed"
+    # A verification run, from before sessions (they no longer exist).
+    def verify?    = kind == "verify"
+    def blocks_dir = File.join(dir, "blocks")
+    def duration   = (finished_at || Time.now) - started_at
+
+    # [cmd path, log path] for the next execution of a block.
+    def paths_for(block)
+      n    = executions.count { it[:block_id] == block.id } + 1
+      base = File.join(blocks_dir, "#{block.id}.#{n}")
+      ["#{base}.cmd", "#{base}.out"]
+    end
+
+    # +confirmed+ records that the operator typed the destructive
+    # confirmation before this execution.
+    def record_execution(execution, step:, confirmed: false, at: Time.now)
+      event = { type: "execute", at: at.iso8601(3), step: step.slug, block: execution.block_id, execution: execution.id }
+      event[:confirmed] = true if confirmed
+      @lock.synchronize do
+        events << event
+        @live[execution.id] = execution
+        executions << execution.to_h.merge(step: step.slug)
+      end
+      self
+    end
+
+    def mark_step(step, status:, note: nil, at: Time.now)
+      @lock.synchronize do
+        events << { type: "step", at: at.iso8601(3), step: step.slug, status:, note: }.compact
+        step_status[step.slug] = status
+      end
+      self
+    end
+
+    # The operator confirms they ran a terminal block themselves.
+    def acknowledge(block, step:, note: nil, at: Time.now)
+      ack = { at: at.iso8601(3), step: step.slug, note: }.compact
+      @lock.synchronize do
+        events << { type: "ack", block: block.id, **ack }
+        acks[block.id] = ack
+      end
+      self
+    end
+
+    # The inputs changed partway: recorded as an event, secrets left out.
+    def change_inputs(inputs, runbook, at: Time.now)
+      visible = RunRecord.visible_inputs(inputs, runbook)
+      @lock.synchronize do
+        events << { type: "inputs", at: at.iso8601(3), inputs: visible }
+        @inputs = visible
+      end
+      self
+    end
+
+    def finish!(status: "completed", at: Time.now)
+      raise ArgumentError, "unknown status #{status}" unless FINAL_STATUSES.include?(status)
+
+      @lock.synchronize do
+        @status      = status
+        @finished_at = at
+        write!
+      end
+    end
+
+    # How this run ends, given the slugs of the runbook's numbered steps:
+    # completed when every one was marked done or skipped, partial when
+    # anything at all was done, opened when nothing was.
+    def closing_status(step_slugs)
+      return "completed" if step_slugs.any? && (step_slugs - step_status.keys).empty?
+      return "partial" if executions.any? || step_status.any? || acks.any?
+
+      "opened"
+    end
+
+    def failed_executions = executions.select { RunRecord.failure?(it) }
+    def steps_done        = step_status.count { |_, s| s == "done" }
+
+    # The most recent execution of each block, keyed by block id.
+    def latest_executions = executions.to_h { [it[:block_id], it] }
+
+    # Blocks whose most recent execution failed. A failure that was re-run
+    # successfully does not count.
+    def unresolved_failures = latest_executions.values.select { RunRecord.failure?(it) }
+
+    # The step the run was last working on: the step of the latest event.
+    def last_step = events.reverse_each.find { it[:step] }&.[](:step)
+
+    # How the runbook has drifted since this run: for the latest execution
+    # of each block, whether the block's code is still what ran. Returns
+    # entries only for blocks that changed or disappeared.
+    def drift(runbook)
+      latest_executions.filter_map do |block_id, hash|
+        recorded = read_block_file(hash[:cmd])
+        _, block = runbook.find_block(block_id)
+        if block.nil?
+          { block_id:, status: :missing, recorded: }
+        elsif Diff.changed?(recorded, block.code)
+          { block_id:, status: :changed, recorded:, current: block.code, diff: Diff.lines(recorded, block.code) }
+        end
+      end
+    end
+
+    def execution(id) = @live[id] || executions.find { it[:id] == id }
+
+    # Pull the latest state from live executions into their hashes.
+    def refresh!
+      executions.each do |hash|
+        live = @live[hash[:id]]
+        hash.merge!(live.to_h) if live
+      end
+      self
+    end
+
+    def write!
+      @lock.synchronize do
+        refresh!
+        Runsheets.write_atomic(File.join(dir, "run.json"), JSON.pretty_generate(to_h))
+        Runsheets.write_atomic(File.join(dir, "run.md"), transcript)
+      end
+      self
+    end
+
+    def to_h
+      {
+        runbook: runbook_slug, title: runbook_title, id:, session: session_id, kind:, status:,
+        started_at: started_at.iso8601(3), finished_at: finished_at&.iso8601(3),
+        duration: duration.round(3), inputs:, steps: step_status, acks:, events:, executions:
+      }
+    end
+
+    def summary
+      { id:, kind:, started_at:, finished_at:, status:, duration:, executions: executions.size,
+        failures: failed_executions.size, unresolved: unresolved_failures.size, steps_done:,
+        last_step: }
+    end
+
+    # The human-readable run.md.
+    def transcript
+      lines = transcript_header
+      lines << "" << "## Timeline" << ""
+      events.each { lines.concat(event_lines(it)) }
+      "#{lines.join("\n")}\n"
+    end
+
+    private
+
+    def transcript_header
+      lines = ["# #{runbook_title} — #{verify? ? 'verification' : 'run'} #{id}", "",
+               "- Runbook: `#{runbook_slug}`"]
+      lines << "- Session: `#{session_id}`" if session_id
+      lines << "- Kind: verification (verify documents only)" if verify?
+      lines.push("- Started: #{started_at.iso8601}",
+                 "- Finished: #{finished_at&.iso8601 || 'in progress'}",
+                 "- Status: #{status}")
+      return lines if inputs.empty?
+
+      lines << "- Inputs:"
+      inputs.each { |k, v| lines << "  - #{RunRecord.code_span(k)} = #{RunRecord.code_span(v)}" }
+      lines
+    end
+
+    # The transcript lines for one event, ending with a blank line.
+    def event_lines(event)
+      case event[:type]
+      when "execute" then execution_transcript(event)
+      when "step"    then ["- #{event[:at]} step #{RunRecord.code_span(event[:step])} marked #{event[:status]}#{note_suffix(event)}", ""]
+      when "ack"     then ["- #{event[:at]} `#{event[:block]}` (#{event[:step]}) confirmed run in the operator's terminal#{note_suffix(event)}", ""]
+      when "inputs"  then ["- #{event[:at]} inputs changed: #{event[:inputs].map do |k, v|
+        "#{RunRecord.code_span(k)} = #{RunRecord.code_span(v)}"
+      end.join(', ')}", ""]
+      else []
+      end
+    end
+
+    def note_suffix(event) = event[:note] ? " — #{RunRecord.plain(event[:note])}" : ""
+
+    def execution_transcript(event)
+      hash  = executions.find { it[:id] == event[:execution] } || {}
+      lines = [execution_title(event, hash), ""]
+      code = read_block_file(hash[:cmd]).chomp
+      fence = RunRecord.fence_for(code)
+      lines << "#{fence}#{command_lang(hash)}" << code << fence << ""
+      output = read_block_file(hash[:log], tail: TRANSCRIPT_TAIL)
+      fence  = RunRecord.fence_for(output)
+      lines << "Output:" << "" << "#{fence}text" << output.chomp << fence << "" unless output.empty?
+      lines
+    end
+
+    def execution_title(event, hash)
+      title = "### #{event[:at]} `#{event[:block]}` (#{event[:step]}) — #{verdict_for(hash)}"
+      title += " in #{hash[:duration]}s" if hash[:duration]
+      tags = execution_tags(event, hash)
+      tags.empty? ? title : "#{title} [#{tags.join(', ')}]"
+    end
+
+    def verdict_for(hash)
+      case hash[:state]
+      when "finished"  then hash[:exit_status] == 0 ? "ok" : "exit #{hash[:exit_status]}"
+      when "timed_out" then "timed out"
+      when "stopped"   then "stopped"
+      when "failed"    then "failed to start: #{hash[:error]}"
+      else hash[:state].to_s
+      end
+    end
+
+    def execution_tags(event, hash)
+      tags = []
+      tags << "background" if hash[:background]
+      tags << "confirmed" if event[:confirmed]
+      tags
+    end
+
+    def command_lang(hash) = File.basename(Array(hash[:command]).first.to_s)
+
+    def read_block_file(name, tail: nil)
+      return "" unless name
+
+      path = File.join(blocks_dir, name)
+      return "" unless File.file?(path)
+
+      size = File.size(path)
+      return File.binread(path).force_encoding("UTF-8").scrub unless tail && size > tail
+
+      "[… #{size - tail} earlier bytes omitted]\n#{File.binread(path, tail, size - tail).force_encoding('UTF-8').scrub}"
+    end
+  end
+end

data/lib/runsheets/runbook.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # A runbook. Either a directory:
+  #
+  #   runbook.md        front matter + preamble (required)
+  #   steps/*.md        ordered by filename
+  #   verify.md         whole-procedure checks (optional)
+  #   rollback.md       what to do when it fails partway (optional)
+  #   assets/           images referenced by the markdown
+  #
+  # or a single markdown file whose `## Headings` are the steps (see
+  # SingleFile). Everything downstream sees the same object either way.
+  class Runbook
+    Input = Data.define(:name, :prompt, :default, :secret) do
+      def self.from(hash)
+        hash = hash.transform_keys(&:to_s)
+        new(name: hash["name"].to_s, prompt: hash["prompt"] || hash["name"].to_s,
+            default: hash["default"]&.to_s, secret: hash["secret"] == true)
+      end
+
+      def secret? = secret
+      def valid?  = name.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+    end
+
+    MAIN_FILE = "runbook.md"
+    STEPS_DIR = "steps"
+    EXTRAS    = %w[verify rollback].freeze
+
+    attr_reader :dir, :root, :slug, :main_path, :data, :landing, :steps, :extras, :inputs, :warnings, :loaded_at
+
+    # Load a runbook directory or a single-file runbook. The slug names the
+    # runbook in run records and URLs: the directory or file name, unless
+    # +slug:+ says otherwise (a Library passes the path inside it). +root:+
+    # is the directory relative links resolve against and /files/ and /docs/
+    # serve from: the library when the runbook is in one, else the runbook's
+    # own directory.
+    def self.load(path, slug: nil, root: nil)
+      path = File.expand_path(path)
+      if File.directory?(path)
+        new(dir: path, main_path: File.join(path, MAIN_FILE), slug: slug || File.basename(path), single_file: false, **{ root: }.compact)
+      elsif File.file?(path)
+        slug ||= File.basename(path, ".*")
+        slug   = File.basename(File.dirname(path)) if slug == File.basename(MAIN_FILE, ".*")
+        new(dir: File.dirname(path), main_path: path, slug:, single_file: true, **{ root: }.compact)
+      else
+        raise RunbookError, "no such runbook: #{path}"
+      end
+    end
+
+    # Is the markdown file at +path+ a runbook rather than a plain document?
+    # A file that cannot be read is neither, and is left out.
+    def self.runbook_file?(path)
+      runbook_text?(File.read(path, encoding: "BOM|UTF-8"))
+    rescue SystemCallError
+      false
+    end
+
+    # Is +path+ a plain document under +root+: an existing markdown file
+    # that is not a runbook and not one of a runbook directory's files
+    # (no runbook.md in its directory or any directory above it, up to
+    # +root+)?
+    def self.plain_document?(path, root)
+      path = File.expand_path(path)
+      root = File.expand_path(root)
+      return false unless File.file?(path) && path.start_with?("#{root}/") && !runbook_file?(path)
+
+      dirs = Pathname(File.dirname(path)).ascend.take_while { it.to_s.start_with?(root) }
+      dirs.none? { File.file?(it.join(MAIN_FILE)) }
+    end
+
+    # A runbook starts with YAML front matter that has a title; anything
+    # else is a plain document. Front matter that does not parse counts as
+    # a runbook: it was meant to be one, and loading it reports why not.
+    def self.runbook_text?(text)
+      !FrontMatter.parse(text).data["title"].to_s.strip.empty?
+    rescue RunbookError
+      true
+    end
+
+    def initialize(dir:, main_path:, slug:, single_file:, root: dir)
+      @dir         = dir
+      @root        = File.expand_path(root)
+      @main_path   = main_path
+      @slug        = slug
+      @single_file = single_file
+      raise RunbookError, "#{MAIN_FILE} not found in #{dir}" unless File.file?(main_path)
+
+      @loaded_at = Time.now
+      parsed     = FrontMatter.parse(File.read(main_path, encoding: "BOM|UTF-8"))
+      @data      = parsed.data
+      raise RunbookError, "#{File.basename(main_path)} is not a runbook: it needs YAML front matter with a title" if data["title"].to_s.strip.empty?
+
+      Runbook.check_shapes(data, File.basename(main_path))
+      @section_warnings = []
+      if single_file
+        load_single_file(parsed.body)
+      else
+        @landing = Step.new(slug: "runbook", text: parsed.body, path: main_path, root: @root, interpreters:)
+        @steps   = load_steps
+        @extras  = load_extras
+      end
+      @inputs       = Array(data["inputs"]).map { Input.from(it) }.freeze
+      @warnings     = validate.freeze
+      @source_count = source_files.size
+    end
+
+    # Raise RunbookError unless the front matter's structured keys have the
+    # shape the rest of runsheets reads: +inputs+ a list of mappings, and
+    # +interpreters+ a mapping of language to command string. +file+ names
+    # the file in the message.
+    def self.check_shapes(data, file)
+      inputs = data["inputs"]
+      unless inputs.nil? || (inputs.is_a?(Array) && inputs.all?(Hash))
+        raise RunbookError, "#{file}: inputs must be a list of mappings, each with a name (- name: REGION)"
+      end
+
+      interpreters = data["interpreters"]
+      return if interpreters.nil? || (interpreters.is_a?(Hash) && interpreters.each_value.all?(String))
+
+      raise RunbookError, "#{file}: interpreters must map a language to a command (sql: psql -f)"
+    end
+
+    def single_file? = @single_file
+
+    def title         = (data["title"] || slug).to_s
+    def when_to_use   = data["when_to_use"]
+    def prerequisites = Array(data["prerequisites"])
+    def blast_radius  = data["blast_radius"]
+    def escalation    = data["escalation"]
+    def tags          = Array(data["tags"]).map(&:to_s)
+    def preamble_html = landing.html
+
+    def verify   = extras["verify"]
+    def rollback = extras["rollback"]
+
+    def destructive? = !blast_radius.nil? || steps.any?(&:destructive?)
+
+    # The checks the Checks page gathers: verify-kind steps in order, then
+    # verify.md.
+    def verify_documents = [*steps.select(&:verify?), verify].compact
+
+    def verify_document?(step) = verify_documents.include?(step)
+
+    def verify_blocks = verify_documents.flat_map(&:executable_blocks)
+
+    # The checks "Run all" runs: plain run blocks. A destructive check needs
+    # its code typed and a background one never finishes, so both are left
+    # for the operator to run by hand.
+    def runnable_checks = verify_blocks.select { it.kind == :run }
+
+    # The markdown files this runbook was built from (those that exist).
+    def source_files
+      return [main_path].select { File.file?(it) } if single_file?
+
+      [main_path, *Dir.glob(File.join(dir, STEPS_DIR, "*.md")), *EXTRAS.map { File.join(dir, "#{it}.md") }].select { File.file?(it) }
+    end
+
+    # True once any source file has been written, added or removed since
+    # this runbook was loaded.
+    def stale?
+      files = source_files
+      return true if files.size != @source_count
+
+      files.any? { File.mtime(it) > loaded_at }
+    rescue SystemCallError # a file vanished between listing and reading
+      true
+    end
+
+    # A reload was tried and failed: count the files as seen, so the next
+    # attempt waits for another edit rather than retrying on every page.
+    def checked!
+      @loaded_at    = Time.now
+      @source_count = source_files.size rescue @source_count
+      self
+    end
+
+    # Every document that can be shown as a page, keyed by slug.
+    def documents = @documents ||= [landing, *steps, *extras.values].to_h { [it.slug, it] }
+
+    def step(slug) = documents[slug]
+
+    # The document read from the file at +path+, or nil. In a single-file
+    # runbook every document shares the file, so this is the landing page.
+    def document_at(path)
+      real = Runbook.real_path(path)
+      documents.each_value.find { it.path && Runbook.real_path(it.path) == real }
+    end
+
+    def self.real_path(path)
+      File.realpath(path)
+    rescue SystemCallError
+      File.expand_path(path)
+    end
+
+    # [step, block] for a block id, or nil.
+    def find_block(id)
+      documents.each_value do |step|
+        block = step.block(id)
+        return [step, block] if block
+      end
+      nil
+    end
+
+    # Previous and next numbered steps around a document (nil at the ends or
+    # for documents that are not numbered steps).
+    def neighbors(step)
+      index = steps.index(step)
+      return [nil, nil] unless index
+
+      [index.positive? ? steps[index - 1] : nil, steps[index + 1]]
+    end
+
+    # Language => command that runs a file of that language: the defaults
+    # plus whatever the front matter adds or overrides.
+    def interpreters
+      @interpreters ||= Block::INTERPRETERS.merge(
+        (data["interpreters"] || {}).to_h { |lang, command| [lang.to_s, Shellwords.split(command.to_s)] }
+      ).freeze
+    end
+
+    def interpreter_for(lang) = interpreters[lang]
+
+    def input(name) = inputs.find { it.name == name }
+
+    def to_h
+      { slug:, dir:, main_path:, single_file: single_file?, title:, when_to_use:, prerequisites:, blast_radius:, escalation:,
+        tags:, inputs: inputs.map(&:to_h),
+        steps: steps.map(&:to_h), extras: extras.keys, warnings: }
+    end
+
+    private
+
+    def load_steps
+      steps_dir = File.join(dir, STEPS_DIR)
+      return [] unless File.directory?(steps_dir)
+
+      names = Dir.glob("*.md", base: steps_dir).sort_by { [it[/\A\d+/].to_i, it] }
+      names.map.with_index(1) { |name, position| Step.load(File.join(steps_dir, name), root:, position:, interpreters:) }
+    end
+
+    def load_extras
+      EXTRAS.filter_map do |name|
+        path = File.join(dir, "#{name}.md")
+        [name, Step.load(path, root:, interpreters:)] if File.file?(path)
+      end.to_h
+    end
+
+    # Preamble up to the first ## heading; each heading is a step, except
+    # the Verify and Rollback sections which become the extras.
+    def load_single_file(body)
+      preamble, sections = SingleFile.split(body)
+      @landing = Step.new(slug: "runbook", text: preamble, path: main_path, root:, interpreters:)
+      @steps   = []
+      @extras  = {}
+      sections.each { add_section(it) }
+      @extras = EXTRAS.filter_map { [it, @extras[it]] if @extras[it] }.to_h
+    end
+
+    def add_section(section)
+      section.warnings.each { section_warning(section, it) }
+      section.extra? ? add_extra(section) : add_step(section)
+    end
+
+    def add_step(section)
+      position = @steps.size + 1
+      @steps << section_step(section, slug: SingleFile.slug_for(section.title, position), position:)
+    end
+
+    def add_extra(section)
+      role = section.role
+      return section_warning(section, "unknown role '#{role}'; expected verify or rollback") unless EXTRAS.include?(role)
+      return section_warning(section, "a second #{role} section; the first one is used") if @extras.key?(role)
+
+      @extras[role] = section_step(section, slug: role)
+    end
+
+    def section_step(section, slug:, position: nil)
+      data = { "title" => section.title }.merge(section.data)
+      Step.new(slug:, text: section.body, path: main_path, root:, position:, data:, interpreters:)
+    end
+
+    def section_warning(section, message)
+      @section_warnings << "section '#{section.title}' (line #{section.line}): #{message}"
+    end
+
+    def validate
+      warnings = []
+      warnings << (single_file? ? "no steps found: add a ## heading per step" : "no steps found in #{STEPS_DIR}/") if steps.empty?
+      inputs.reject(&:valid?).each { warnings << "input name '#{it.name}' is not a valid environment variable name" }
+      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(@section_warnings)
+      documents.each_value do |step|
+        step.warnings.each { warnings << "#{step.slug}: #{it}" }
+      end
+      warnings
+    end
+  end
+end