runsheets 0.0.1

data/lib/runsheets/search.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # Full-text search over runbooks. A query is words and "quoted phrases",
+  # matched case-insensitively; a runbook matches when every one of them
+  # appears somewhere in it: its title, its front matter text, or any of
+  # its documents (the preamble, the steps, verify and rollback), code
+  # included. Plain documents are not searched.
+  #
+  # Every function takes the pieces it needs and returns plain data, so
+  # each can be tested on its own.
+  module Search
+    # One runbook that matched: +hits+ are the documents that hold at least
+    # one term, best first.
+    Result = Data.define(:runbook, :slug, :score, :hits)
+
+    # One document of a runbook (the preamble, a step, verify or rollback)
+    # that holds a term.
+    Hit = Data.define(:step, :title, :snippet, :score)
+
+    # How much a term found in each place counts toward a runbook's rank.
+    WEIGHTS = { title: 10, meta: 5, step_title: 3, body: 1 }.freeze
+
+    # Characters of context kept on each side of a match in a snippet.
+    CONTEXT = 70
+
+    # A parsed query: its terms, and what can be asked of a text about them.
+    Query = Data.define(:words) do
+      def self.parse(query) = new(words: Search.terms(query))
+
+      def empty? = words.empty?
+
+      # Does +text+ (already lowercased) hold every term?
+      def all_in?(text) = words.all? { text.include?(it) }
+
+      # How many times the terms occur in +text+, all together.
+      def count(text)
+        haystack = Search.normalize(text)
+        words.sum { haystack.scan(it).size }
+      end
+
+      # A line of +text+ around the first match, whitespace collapsed and
+      # markdown syntax dropped, with "…" where it was cut. nil when nothing
+      # matches.
+      def snippet(text, context: CONTEXT)
+        flat  = Search.plain(text).gsub(/\s+/, " ").strip
+        first = words.filter_map { flat =~ Regexp.new(Regexp.escape(it), Regexp::IGNORECASE) }.min
+        return nil unless first
+
+        from = [first - context, 0].max
+        to   = [first + context, flat.size].min
+        "#{'…' if from.positive?}#{flat[from...to].strip}#{'…' if to < flat.size}"
+      end
+
+      # +text+ HTML-escaped, with each term wrapped in <mark>. Longer terms
+      # are tried first, so a phrase wins over a word inside it.
+      def highlight(text)
+        return Renderer.h(text) if empty?
+
+        pattern = Regexp.union(words.sort_by { -it.size }.map { Regexp.new(Regexp.escape(it), Regexp::IGNORECASE) })
+        text.to_s.split(/(#{pattern})/).each_slice(2).map do |plain, match|
+          "#{Renderer.h(plain)}#{"<mark>#{Renderer.h(match)}</mark>" if match}"
+        end.join
+      end
+    end
+
+    module_function
+
+    # The terms of a query: "quoted phrases" whole, other words one by one,
+    # lowercased, blanks and duplicates dropped.
+    def terms(query)
+      query.to_s.scan(/"([^"]*)"|(\S+)/).map { |phrase, word| normalize(phrase || word.delete('"')).strip }
+           .reject(&:empty?).uniq
+    end
+
+    # Search +runbooks+ (a list of [slug, Runbook] pairs) for the query
+    # string. Results are best first; ties go by title.
+    def run(runbooks, query)
+      query = Query.parse(query)
+      return [] if query.empty?
+
+      runbooks.filter_map { |slug, runbook| result_for(slug, runbook, query) }
+              .sort_by { [-it.score, it.runbook.title.downcase] }
+    end
+
+    # The Result for one runbook, or nil when some term appears nowhere in it.
+    def result_for(slug, runbook, query)
+      return nil unless query.all_in?(text_of(runbook))
+
+      hits  = hits_for(runbook, query)
+      score = (query.count(runbook.title) * WEIGHTS[:title]) + (query.count(meta_text(runbook)) * WEIGHTS[:meta]) + hits.sum(&:score)
+      Result.new(runbook:, slug:, score:, hits:)
+    end
+
+    # Everything searchable in a runbook, lowercased, as one string.
+    def text_of(runbook)
+      normalize([runbook.title, meta_text(runbook), *runbook.documents.values.flat_map { [it.title, it.body] }].join("\n"))
+    end
+
+    # The runbook's front matter prose: what an engineer reads before the
+    # first step.
+    def meta_text(runbook)
+      [runbook.when_to_use, *runbook.prerequisites, runbook.blast_radius, runbook.escalation, *runbook.tags,
+       *runbook.inputs.flat_map { [it.name, it.prompt] }].compact.join("\n")
+    end
+
+    # The documents that hold a term, best first, each with a snippet.
+    def hits_for(runbook, query)
+      hits = runbook.documents.values.filter_map do |doc|
+        score = (query.count(doc.title) * WEIGHTS[:step_title]) + (query.count(doc.body) * WEIGHTS[:body])
+        next if score.zero?
+
+        Hit.new(step: doc, title: doc.title, snippet: query.snippet(doc.body) || doc.title, score:)
+      end
+      hits.sort_by { -it.score }
+    end
+
+    # Text as search compares it: whitespace runs (line breaks included) as
+    # one space, case folded, so a phrase matches across a wrapped line.
+    def normalize(text) = text.to_s.gsub(/\s+/, " ").downcase(:fold)
+
+    # Markdown reduced to the words a reader sees: link text without its
+    # target, no fence lines, heading marks or HTML comments.
+    def plain(text)
+      text.to_s.gsub(/<!--.*?-->/m, " ").gsub(/^\s*(```|~~~).*$/, " ").gsub(/^\s*\#{1,6}\s+/, "")
+          .gsub(/!?\[([^\]]*)\]\([^)]*\)/, '\1')
+    end
+  end
+end

data/lib/runsheets/session.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "socket"
+
+module Runsheets
+  # The engineering session: everything that happens between `runsheets`
+  # starting and stopping. It belongs to one engineer and opens with a note
+  # saying why. Selecting a runbook establishes that runbook's Run; the
+  # engineer can switch between runbooks freely, and every run stays open
+  # until the session ends.
+  #
+  #   <runs_root>/sessions/<session-id>/
+  #     session.json   engineer, host, times, status, notes, the runs
+  #     session.log    every action and its output, appended as it happens
+  #
+  # The runbook on screen is #runbook; the methods the pages and routes call
+  # for "this runbook" (execute, mark_step, run, ...) go to its run.
+  class Session
+    ConfirmationRequired = Run::ConfirmationRequired
+
+    SESSIONS = "sessions"
+    STATUSES = %w[running ended interrupted].freeze
+
+    attr_reader :engineer, :started_at, :ended_at, :notes, :runs_root, :library, :token, :executor, :log, :dir, :runbook
+
+    # Start a session: create its directory and log, close any earlier
+    # session left running by a killed process, and record +why+ as the
+    # first note. +runbook+ is the one runbook served, when there is no
+    # library. +echo+ is the IO the log is echoed to (nil for none).
+    def initialize(engineer:, why:, runs_root: Runsheets.runs_dir, library: nil, runbook: nil, token: SecureRandom.hex(16),
+                   executor: Executor.new, log_level: "info", echo: nil, now: Time.now)
+      raise RunError, "who is starting the session? An engineer name is needed" if engineer.to_s.strip.empty?
+      raise RunError, "why is the session being started? A note is needed" if why.to_s.strip.empty?
+
+      @engineer   = engineer.to_s.strip
+      @runs_root  = runs_root
+      @library    = library
+      @token      = token
+      @executor   = executor
+      @started_at = now
+      @notes      = []
+      @runs       = {}
+      @mutex      = Mutex.new
+      @ending     = false
+      @dir        = RunRecord.create_unique_dir(File.join(Session.root(runs_root), now.strftime(RunRecord::TIMESTAMP)))
+      @log = SessionLog.new(File.join(@dir, "session.log"), level: log_level, echo:)
+      start(why, Session.close_interrupted(runs_root, except: @dir))
+      show(runbook) if runbook
+    end
+
+    # Where sessions are kept under a runs directory.
+    def self.root(runs_root) = File.join(runs_root, SESSIONS)
+
+    # Close every session (and its runs) still marked running whose process
+    # is gone: it was killed, so nothing closed it. A session whose process
+    # is still alive on this host is another runsheets, and is left alone,
+    # as is the session at +except+ (a directory). Returns the ids closed.
+    def self.close_interrupted(runs_root, except: nil)
+      paths = Dir.glob(File.join(root(runs_root), "*", "session.json")) - [File.join(except.to_s, "session.json")]
+      paths.filter_map do |path|
+        data = JSON.parse(File.read(path))
+        next unless data.is_a?(Hash) && data["status"] == "running" && !running_here?(data)
+
+        interrupt(File.dirname(path), data, runs_root:)
+        data["id"]
+      rescue StandardError # unreadable, or not a session record: leave it
+        nil
+      end
+    end
+
+    # Mark a killed session, and the runs it lists, interrupted. The end
+    # time is the last write to its log.
+    def self.interrupt(dir, data, runs_root:)
+      root    = File.expand_path(runs_root)
+      log     = File.join(dir, "session.log")
+      ended   = File.file?(log) ? File.mtime(log) : Time.now
+      runs    = Array(data["runs"]).grep(Hash)
+      runs.each do |run|
+        next unless File.expand_path(run["dir"].to_s).start_with?("#{root}/")
+
+        record = RunRecord.load(run["dir"])
+        record.finish!(status: "interrupted", at: ended) if record.active?
+        run["status"] = record.status
+      rescue StandardError
+        next
+      end
+      Runsheets.write_atomic(File.join(dir, "session.json"),
+                             JSON.pretty_generate(data.merge("status" => "interrupted", "ended_at" => ended.iso8601(3), "runs" => runs)))
+    end
+
+    # The records of the sessions kept under +runs_root+, newest first,
+    # leaving out the one at +except+; unreadable ones are skipped. The
+    # first note (the why) is copied into each as "why".
+    def self.past(runs_root, except: nil)
+      sessions = Dir.glob(File.join(root(runs_root), "*", "session.json")).filter_map do |path|
+        next if File.dirname(path) == except
+
+        data = JSON.parse(File.read(path))
+        next unless data.is_a?(Hash)
+
+        data.merge("why" => Array(data["notes"]).grep(Hash).first&.fetch("text", nil))
+      rescue StandardError
+        nil
+      end
+      sessions.sort_by { it["started_at"].to_s }.reverse
+    end
+
+    # Is the session in +data+ still being written by a live process on
+    # this host?
+    def self.running_here?(data) = data["host"] == Socket.gethostname && alive?(data["pid"])
+
+    def self.alive?(pid)
+      return false unless pid.is_a?(Integer)
+
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    def id     = File.basename(dir)
+    def host   = Socket.gethostname
+    def status = ended_at ? "ended" : "running"
+    def ended? = !ended_at.nil?
+    def why    = notes.first&.fetch(:text)
+    def elapsed(now = Time.now) = (ended_at || now) - started_at
+
+    # Add a timestamped note to the session.
+    def note!(text, at: Time.now)
+      text = text.to_s.strip
+      raise RunError, "a note needs some text" if text.empty?
+
+      @mutex.synchronize do
+        notes << { at:, text: }
+        write!
+      end
+      log.info("note: #{text}", tags: ["session"])
+      self
+    end
+
+    # --- runbooks and runs ---------------------------------------------
+
+    # The runs of this session, in the order their runbooks were selected.
+    def runs = @runs.values
+
+    def run_for(slug) = @runs[slug]
+
+    # The run of the runbook on screen, if it has one.
+    def current = runbook && @runs[runbook.slug]
+
+    # Put +runbook+ on screen without establishing a run. The run it may
+    # already have takes the fresh copy.
+    def show(runbook)
+      @mutex.synchronize do
+        @runbook = runbook
+        @runs[runbook.slug]&.runbook = runbook
+      end
+      runbook
+    end
+
+    # Select a runbook: put it on screen and establish its run with
+    # +inputs+, or return to the run it already has. Returns the Run.
+    def open(runbook, inputs: {})
+      show(runbook)
+      @mutex.synchronize do
+        raise RunError, "this session is ending" if @ending || ended?
+
+        existing = @runs[runbook.slug]
+        return existing if existing
+
+        run = @runs[runbook.slug] = Run.new(session: self, runbook:, inputs:)
+        write!
+        run
+      end
+    end
+
+    # Non-secret input values given earlier in the session, by name. A run
+    # opened later is offered them as defaults.
+    def carried_inputs = runs.map { it.record.inputs }.reduce({}, :merge)
+
+    # Inputs as the start form shows them for the runbook on screen.
+    def resolve_inputs(given = {}) = Run.resolve_inputs(runbook, given, carried: carried_inputs)
+
+    # Reload the runbook on screen if any of its markdown files changed,
+    # so an edit is reflected on the next page. Block ids stay stable unless
+    # fences are added or removed, so its run carries on. A runbook that no
+    # longer loads is kept as it was.
+    def refresh_runbook!
+      return runbook unless runbook&.stale?
+
+      log.debug("reloaded #{runbook.slug}: its files changed", tags: ["session"])
+      show(Runbook.load(runbook.single_file? ? runbook.main_path : runbook.dir, slug: runbook.slug, root: runbook.root))
+    rescue StandardError => e # whatever the edit broke, the page keeps the last good copy
+      log.error("#{runbook.slug} no longer loads: #{e.message}", tags: ["session"])
+      runbook.checked!
+      runbook
+    end
+
+    # --- the runbook on screen ------------------------------------------
+
+    def active? = !current.nil? && current.open?
+
+    # The record of the runbook on screen's run.
+    def run = current&.record
+
+    def execute(block_id, confirm: nil, digest: nil)  = current!.execute(block_id, confirm:, digest:)
+    def acknowledge(block_id, note: nil, digest: nil) = current!.acknowledge(block_id, note:, digest:)
+    def mark_step(slug, status:, note: nil)    = current!.mark_step(slug, status:, note:)
+    def change_inputs(given)                   = current!.change_inputs(given)
+    def step_status(slug)                      = current&.step_status(slug)
+    def ack(block_id)                          = current&.ack(block_id)
+    def secret_inputs_set                      = current&.secret_inputs_set || []
+    def history                                = RunRecord.list(runs_root, runbook.slug)
+
+    # The run of the runbook on screen, or a RunError saying there is none.
+    def current!
+      current or raise RunError, "start the run for #{runbook&.title || 'a runbook'} before executing blocks"
+    end
+
+    # --- executions across every run ------------------------------------
+
+    def executions         = runs.flat_map(&:executions)
+    def running_executions = executions.select(&:running?)
+
+    # [run, execution] for each execution still running, in any runbook.
+    def running = runs.flat_map { |run| run.running_executions.map { [run, it] } }
+
+    def execution(id) = runs.lazy.filter_map { it.execution(id) }.first
+
+    # The text of the expect block for +execution+'s block, in the runbook
+    # of the run that started it, or nil.
+    def expected_output(execution)
+      run = runs.find { it.execution(execution.id) } or return
+      run.runbook.step(execution.step_slug)&.expected_output(execution.block_id)
+    end
+
+    # Stop an execution, whichever runbook started it.
+    def stop(execution_id)
+      run = runs.find { it.execution(execution_id) } or raise RunError, "no execution #{execution_id}"
+      run.stop(execution_id)
+    end
+
+    # --- ending ----------------------------------------------------------
+
+    # End the session: close every run (stopping what it left running) with
+    # the status its work earns, and write the record. +how+ says what ended
+    # it, for the log. Ending twice does nothing.
+    def end!(how, at: Time.now)
+      return self unless begin_ending
+
+      runs.each(&:stop_running!)
+      closed = runs.map { "#{it.slug} #{close_run(it)}" }
+      @mutex.synchronize do
+        @ended_at = at
+        write!
+      end
+      log.info("ended (#{how}) after #{format('%.0f', elapsed)}s; runs: #{closed.empty? ? 'none' : closed.join(', ')}", tags: ["session"])
+      self
+    end
+
+    def to_h
+      {
+        id:, engineer:, host:, pid: Process.pid, runsheets: VERSION, status:,
+        started_at: started_at.iso8601(3), ended_at: ended_at&.iso8601(3),
+        library: library&.dir, log: log.path,
+        notes: notes.map { { at: it[:at].iso8601(3), text: it[:text] } },
+        runs: runs.map { { runbook: it.slug, title: it.runbook.title, dir: it.record.dir, status: it.record.status } }
+      }
+    end
+
+    def write!
+      Runsheets.write_atomic(File.join(dir, "session.json"), JSON.pretty_generate(to_h))
+      self
+    end
+
+    private
+
+    # Claim the ending: true for the first caller only. From here on no run
+    # is opened.
+    def begin_ending
+      @mutex.synchronize do
+        return false if @ending || ended?
+
+        @ending = true
+      end
+    end
+
+    # Close a run, and say what became of it even when closing fails.
+    def close_run(run)
+      run.close!
+    rescue StandardError => e
+      log.error("could not close #{run.slug}: #{e.class}: #{e.message}", tags: ["session"])
+      "error"
+    end
+
+    def start(why, interrupted)
+      where = library ? "library=#{library.dir}" : nil
+      log.info(["started engineer=#{engineer.inspect} host=#{host} pid=#{Process.pid} runsheets=#{VERSION}", where, "log=#{log.path}"].compact.join(" "),
+               tags: ["session"])
+      interrupted.each { log.warn("earlier session #{it} was left running by a process that is gone; closed it as interrupted", tags: ["session"]) }
+      note!(why, at: started_at)
+    end
+  end
+end

data/lib/runsheets/session_log.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Runsheets
+  # The session's log: a plain text file appended as things happen, and
+  # the same lines echoed to the terminal that started runsheets. Each line
+  # is a timestamp, a Rails log level, the tags saying where it happened,
+  # and the event:
+  #
+  #   2026-10-10 14:02:41.200 INFO  [db-maintenance 010-check #1a2b] execute sql via psql -f …
+  #   2026-10-10 14:02:41.540 INFO  [#1a2b] >  database | role
+  #
+  # Two standard Loggers sit behind it, one per destination, each with its
+  # own level. Multi-line text becomes one line per source line with the
+  # same prefix, so every line stands alone under grep.
+  class SessionLog
+    LEVELS = %w[debug info warn error fatal].freeze
+
+    # Turns a stream of output chunks into log lines, one per complete line
+    # of output, each marked "> ". Whatever is left without a newline is
+    # written when the stream closes. Thread-safe enough for one writer (the
+    # executor's pump) and one closer.
+    class OutputStream
+      def initialize(log, tags)
+        @log     = log
+        @tags    = tags
+        @pending = +"".b
+      end
+
+      # Bytes are kept as bytes until a line is complete, so a character
+      # split across two reads is decoded whole.
+      def write(chunk)
+        @pending << chunk.to_s.b
+        lines    = @pending.split("\n".b, -1)
+        @pending = lines.pop || +"".b
+        lines.each { line(it) }
+        chunk.to_s.bytesize
+      end
+
+      def close
+        line(@pending) unless @pending.empty?
+        @pending = +"".b
+      end
+
+      private
+
+      def line(bytes) = @log.info("> #{bytes.force_encoding('UTF-8').scrub.chomp("\r")}", tags: @tags)
+    end
+
+    attr_reader :path, :level
+
+    # +path+ is the log file, opened for appending (and created). +echo+ is
+    # an IO for the terminal copy, or nil for none. +level+ and
+    # +echo_level+ are the floors for each, as level names.
+    def initialize(path, level: "info", echo: nil, echo_level: "info")
+      @path   = path
+      @level  = SessionLog.level_name(level)
+      @io     = File.open(path, "a")
+      @io.sync = true
+      @file   = Logger.new(@io, level: @level, formatter: method(:format))
+      @echo   = echo && Logger.new(echo, level: SessionLog.level_name(echo_level), formatter: method(:format))
+    end
+
+    # A level name, checked: one of LEVELS. Raises ConfigError otherwise.
+    def self.level_name(value)
+      name = value.to_s.strip.downcase
+      raise ConfigError, "log level must be one of #{LEVELS.join(', ')}, got #{value.inspect}" unless LEVELS.include?(name)
+
+      name
+    end
+
+    # The bracketed prefix for a list of tags: [a b #c], or [] dropped.
+    def self.tag_text(tags)
+      words = Array(tags).compact.map { it.to_s.gsub(/[[:cntrl:]]/, "?") }.reject(&:empty?)
+      words.empty? ? "" : "[#{words.join(' ')}]"
+    end
+
+    # One log line as written: time to the millisecond, level, tags, text.
+    def self.line(time, severity, tags, text)
+      prefix = [time.strftime("%Y-%m-%d %H:%M:%S.%L"), severity.ljust(5), tag_text(tags)].reject(&:empty?).join(" ")
+      "#{prefix} #{text}\n"
+    end
+
+    LEVELS.each do |name|
+      define_method(name) { |text, tags: []| add(name, text, tags:) }
+    end
+
+    # Write +text+ at +severity+, one log line per line of text.
+    def add(severity, text, tags: [])
+      level = Logger::Severity.const_get(severity.to_s.upcase)
+      lines = text.to_s.split("\n")
+      lines = [""] if lines.empty?
+      lines.each do |line|
+        @file.add(level, line, tags)
+        @echo&.add(level, line, tags)
+      end
+      self
+    end
+
+    # A sink for one execution's output (see OutputStream).
+    def output_stream(tags) = OutputStream.new(self, tags)
+
+    def close
+      @io.close unless @io.closed?
+      self
+    end
+
+    private
+
+    # Logger's formatter: the tags travel as the progname.
+    def format(severity, time, tags, text) = SessionLog.line(time, severity, tags, text)
+  end
+end

data/lib/runsheets/single_file.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # Splits a single-file runbook into its preamble and sections.
+  #
+  # One markdown file: front matter, a preamble, then one `## Heading` per
+  # step. A section headed "Verify" or "Rollback" (or carrying
+  # `role: verify` / `role: rollback`) plays the part verify.md and
+  # rollback.md play in a directory runbook. Step attributes that a
+  # directory runbook puts in front matter go in an HTML comment right
+  # after the heading, as a YAML flow mapping:
+  #
+  #   ## Drain the ECS services
+  #   <!-- kind: automated, timeout: 600, destructive: true -->
+  #
+  # The comment is invisible on GitHub and in any other renderer, so the
+  # file stays an ordinary markdown document everywhere else.
+  module SingleFile
+    Section = Data.define(:title, :data, :body, :line, :warnings) do
+      def role = data["role"]&.to_s&.downcase || (ROLES.include?(title.strip.downcase) ? title.strip.downcase : nil)
+      def extra? = !role.nil?
+    end
+
+    ROLES    = %w[verify rollback].freeze
+    HEADING  = /\A##[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*\z/
+    # An attribute comment starts with a key; any other comment is prose.
+    COMMENT  = /\A[ \t]*<!--([ \t]*[\w-]+[ \t]*:.*?)-->[ \t]*\z/
+
+    # Returns [preamble markdown, sections].
+    def self.split(markdown)
+      preamble = []
+      sections = []
+      current  = nil
+      open     = nil
+
+      markdown.each_line(chomp: true).with_index(1) do |line, number|
+        if open
+          open = nil if Fences.closes?(line, open)
+          (current ? current[:body] : preamble) << line
+        elsif (match = line.match(Fences::OPEN))
+          open = { char: match[2][0], len: match[2].size }
+          (current ? current[:body] : preamble) << line
+        elsif (match = line.match(HEADING))
+          current = { title: match[1], body: [], line: number }
+          sections << current
+        else
+          (current ? current[:body] : preamble) << line
+        end
+      end
+
+      current[:unclosed] = true if open && current
+      ["#{preamble.join("\n")}\n", sections.map { build(it) }]
+    end
+
+    # Pull the attribute comment off the front of a section body.
+    def self.build(raw)
+      body     = raw[:body].dup
+      data     = {}
+      warnings = []
+      warnings << "a code fence opened in this section is never closed, so every heading after it is part of it" if raw[:unclosed]
+      body.shift while body.first&.strip&.empty?
+      if body.first && (match = body.first.match(COMMENT))
+        data, warning = parse_attributes(match[1])
+        warnings << warning if warning
+        body.shift
+      end
+      Section.new(title: raw[:title].strip, data:, body: "#{body.join("\n")}\n", line: raw[:line], warnings:)
+    end
+    private_class_method :build
+
+    # "kind: verify, timeout: 300" => { "kind" => "verify", "timeout" => 300 }.
+    # Returns [data, warning or nil].
+    def self.parse_attributes(text)
+      inner = text.strip
+      return [{}, nil] if inner.empty?
+
+      parsed = YAML.safe_load("{#{inner}}", permitted_classes: [Date, Time], aliases: false)
+      return [{}, "attribute comment is not a mapping: <!-- #{inner} -->"] unless parsed.is_a?(Hash)
+
+      [parsed.transform_keys(&:to_s), nil]
+    rescue Psych::Exception => e
+      [{}, "attribute comment could not be parsed (#{e.message.lines.first&.strip}): <!-- #{inner} -->"]
+    end
+
+    # 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 = "step" if words.empty?
+      format("%<number>03d-%<words>s", number: position * 10, words:)
+    end
+  end
+end