openlanes 3.0.0

data/lib/openlanes/presentation/reporter.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Presentation
+    # `/spec-status` — every plan, its state in icon and words, and its pull
+    # requests as clickable links.
+    #
+    # {#render} returns a string and prints nothing. Whoever calls it decides
+    # where it goes, which keeps the table pipeable.
+    class Reporter
+      # Columns, so the header and the rows cannot drift apart.
+      HEADINGS = ["Plan", "⬇", "Status", "Feature", "Pull Requests"].freeze
+
+      # Cells given to the plan number: "018.01" with room to grow.
+      ORDINAL_WIDTH = 7
+
+      # Cells given to a status icon. Emoji vary in both character count and
+      # display width, so the cell is padded to this by {UI.fit} rather than
+      # trusted to be any particular size — see the note there.
+      EMOJI_WIDTH = 2
+
+      # Cells given to a pull request's state, so the URLs line up beneath each
+      # other whichever states the tree happens to contain.
+      STATE_WIDTH = Plans::PullRequests::STATES.map { |_, label| UI.display_width(label) }.max
+
+      # @param tree [OpenLanes::Plans::Tree]
+      def initialize(tree:)
+        @tree = tree
+      end
+
+      # @return [OpenLanes::Plans::Tree]
+      attr_reader :tree
+
+      # @return [String] the whole table, newline-terminated
+      def render
+        return "No plans found in #{tree.dir}\n" if tree.subjects.empty?
+
+        [header, *tree.subjects.flat_map { |s| rows_for(s) }, "", footer].join("\n") + "\n"
+      end
+
+      # @return [Hash{Symbol => Integer}] how many plans sit in each state
+      def totals
+        tree.subjects.each_with_object(Hash.new(0)) { |s, h| h[s.status.key] += 1 }
+      end
+
+      # Plans whose folder name their contents do not justify.
+      #
+      # @return [Array<OpenLanes::Plans::Subject>]
+      def inconsistent = tree.subjects.reject(&:consistent?)
+
+      private
+
+      # @return [Integer] widest status label, so the column lines up
+      def label_width = @label_width ||= tree.subjects.map { |s| UI.display_width(s.status.label) }.max.to_i + 4
+
+      # @return [Integer] widest feature name
+      def title_width = @title_width ||= tree.subjects.map { |s| UI.display_width(s.feature.title) }.max.to_i + 2
+
+      # The one place the table's shape is written down. The heading, the plan
+      # rows, the continuation lines and the violations all come through here, so
+      # a column cannot widen in one of them and stay put in the others.
+      #
+      # Cells arrive already fitted and already painted, in that order, because
+      # the order matters: escape codes count toward a string's length, so
+      # padding a coloured string pads it to a width of which several characters
+      # are invisible, and the column collapses by exactly that much.
+      #
+      # @return [String]
+      def row(flag, ordinal, emoji, label, title, tail)
+        format("%s %s  %s %s  %s %s", flag, ordinal, emoji, label, title, tail)
+      end
+
+      # Cell at which the pull requests start, so a plan's second and third pull
+      # requests sit under its first. Measured by running blanks through {#row}
+      # rather than counted by hand, so the indent cannot drift when the layout
+      # changes.
+      #
+      # @return [Integer]
+      def pr_column
+        @pr_column ||= row(" ",
+          " " * ORDINAL_WIDTH,
+          " " * EMOJI_WIDTH,
+          " " * label_width,
+          " " * title_width,
+          "").length
+      end
+
+      # @return [Integer] cell at which the feature name starts
+      def title_column = pr_column - title_width - 1
+
+      # @return [String]
+      def header
+        text = row(" ",
+          UI.fit(HEADINGS[0], ORDINAL_WIDTH),
+          UI.fit(HEADINGS[1], EMOJI_WIDTH),
+          UI.fit(HEADINGS[2], label_width),
+          UI.fit(HEADINGS[3], title_width),
+          HEADINGS[4])
+
+        rule = "  " + ("─" * (UI.display_width(text) - 2))
+
+        [UI.paint(text, :bold), UI.paint(rule, :bright_yellow)].join("\n")
+      end
+
+      # One line per plan, plus a continuation line for each extra pull request
+      # so that every URL is visible and clickable rather than truncated.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<String>]
+      def rows_for(subject)
+        feature = subject.feature
+        prs = subject.pull_requests
+
+        first = row(
+          subject.consistent? ? " " : UI.paint("!", :red),
+          UI.paint(UI.fit(feature.ordinal.to_s, ORDINAL_WIDTH), :bold),
+          UI.fit(feature.status.emoji, EMOJI_WIDTH),
+          UI.paint(UI.fit(feature.status.label, label_width), :yellow),
+          UI.paint(UI.fit(feature.title, title_width), :blue, :bold),
+          prs.empty? ? UI.paint("[none yet]", :bright_red) : link(prs.first)
+        )
+
+        rest = prs.drop(1).map { |pr| (" " * pr_column) + link(pr) }
+
+        [first, *rest, *violation_line(subject)]
+      end
+
+      # The URL is left bare rather than wrapped in an OSC 8 hyperlink: the table
+      # is as likely to be piped into a file as read in a terminal, and every
+      # terminal worth the name linkifies a bare URL anyway.
+      #
+      # @param pr [OpenLanes::Plans::PullRequest]
+      # @return [String]
+      def link(pr)
+        colour = state_colour(pr)
+
+        format("#%4s %s %s",
+          pr.number,
+          UI.paint(UI.fit(pr.state, STATE_WIDTH), colour),
+          UI.paint(pr.url.to_s, colour))
+      end
+
+      # @param pr [OpenLanes::Plans::PullRequest]
+      # @return [Symbol] a pastel style name
+      def state_colour(pr)
+        if pr.merged?
+          :magenta
+        elsif pr.open?
+          :yellow
+        else
+          :blue
+        end
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<String>]
+      def violation_line(subject)
+        return [] if subject.consistent?
+
+        [(" " * title_column) + UI.paint("↳ #{subject.violation}", :red)]
+      end
+
+      # @return [String]
+      def footer
+        counts = totals.map { |key, n| "#{Plans::STATUS_BY_KEY.fetch(key).emoji} #{n}" }.join("   ")
+        lines = ["  #{tree.subjects.size} #{tree.subjects.size == 1 ? "plan" : "plans"}   #{counts}"]
+
+        unless inconsistent.empty?
+          lines << "  #{UI.paint("#{inconsistent.size} with a status their contents do not justify", :red)}"
+        end
+
+        tree.duplicates.each do |ordinal, dirnames|
+          lines << "  #{UI.paint("#{ordinal} is claimed by #{dirnames.size} folders — a number is an identity:", :red)}"
+          dirnames.each { |d| lines << "    #{UI.paint(d, :bright_black)}" }
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/openlanes/presentation/viewer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Presentation
+    # Hands Markdown files to a renderer outside this process: the system
+    # viewer via `open`, or mdfried in the terminal.
+    #
+    # Both paths shell out, so the class takes its two effects as lambdas and
+    # the specs assert on the commands instead of launching viewers on the box
+    # running the suite.
+    class Viewer
+      # What to run when mdfried is asked for but not installed. Homebrew is the
+      # one package manager the toolchain already assumes (see the Brewfile
+      # convention), so there is no fallback chain to get wrong.
+      INSTALL = "brew install mdfried >/dev/null"
+
+      # How to notice mdfried is missing without depending on `which`, which
+      # differs across shells; `command -v` is POSIX.
+      DETECT = "command -v mdfried >/dev/null"
+
+      # @param launch [#call] runs a command, returns truthy on success
+      # @param pipe [#call] runs a command, yielding its stdin as an IO
+      def initialize(launch: ->(*cmd) { system(*cmd) },
+        pipe: ->(cmd, &block) { IO.popen(cmd, "w", &block) })
+        @launch = launch
+        @pipe = pipe
+      end
+
+      # Opens each file in whatever the system has configured for Markdown.
+      #
+      # @param paths [Array<String>]
+      # @return [void]
+      def open(paths)
+        Array(paths).each { |path| @launch.call("open", path) }
+      end
+
+      # Streams each file's content into mdfried, installing it first when it
+      # is missing.
+      #
+      # @param paths [Array<String>]
+      # @return [void]
+      # @raise [OpenLanes::Error] when mdfried is absent and brew cannot fix that
+      def mdfried(paths)
+        ensure_mdfried!
+        Array(paths).each do |path|
+          @pipe.call("mdfried") { |io| io.write(File.read(path)) }
+        end
+      end
+
+      private
+
+      # @return [void]
+      # @raise [OpenLanes::Error]
+      def ensure_mdfried!
+        return if @launch.call(DETECT)
+
+        @launch.call(INSTALL) or
+          raise Error, "mdfried is not installed, and `brew install mdfried` failed"
+      end
+    end
+  end
+end

data/lib/openlanes/presentation.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # Everything a person reads: the live dashboard, the status table, the
+  # generated conventions and the state diagram. These render strings and
+  # draw on STDERR; none of them changes a plan.
+  module Presentation
+    module_function
+
+    # @return [String] the conventions document, derived
+    def documentation = Documentation.new.render
+
+    # @return [String] the state machine, drawn for a terminal
+    def diagram = Diagram.new.render
+
+    # @param tree [OpenLanes::Plans::Tree]
+    # @return [OpenLanes::Presentation::Reporter]
+    def reporter(tree:) = Reporter.new(tree:)
+
+    # @return [OpenLanes::Presentation::Viewer]
+    def viewer = Viewer.new
+  end
+end

data/lib/openlanes/skills/installer.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenLanes
+  module Skills
+    # Copies the bundled skills into a skill directory.
+    #
+    # Copies, never links: a link into the gem's versioned install path
+    # dangles the moment `gem cleanup` removes that version, and the skill
+    # disappears with no error anywhere. Re-running after an upgrade is the
+    # price, and the report says what that run changed.
+    class Installer
+      # What happened to one skill.
+      #
+      # @!attribute [r] skill
+      #   @return [OpenLanes::Skills::Skill]
+      # @!attribute [r] action
+      #   @return [Symbol] :installed, :kept or :replaced
+      # @!attribute [r] target
+      #   @return [String]
+      Outcome = Data.define(:skill, :action, :target)
+
+      # @param into [String] the destination directory
+      # @param skills [Array<OpenLanes::Skills::Skill>]
+      def initialize(into:, skills:)
+        @into = File.expand_path(into)
+        @skills = skills
+      end
+
+      # @return [String]
+      attr_reader :into
+
+      # @param overwrite [Boolean] replace a skill already there
+      # @param dry_run [Boolean] decide, and change nothing
+      # @return [Array<Outcome>]
+      def call(overwrite: false, dry_run: false)
+        @skills.map do |skill|
+          target = File.join(into, skill.name)
+          action = action_for(skill, overwrite)
+          copy(skill, target, replacing: action == :replaced) unless dry_run || action == :kept
+          Outcome.new(skill:, action:, target:)
+        end
+      end
+
+      private
+
+      # @return [Symbol]
+      def action_for(skill, overwrite)
+        return :installed unless skill.installed?(into)
+
+        overwrite ? :replaced : :kept
+      end
+
+      # A link already standing where the skill goes is removed, not
+      # followed: replacing what it points at would edit somebody's checkout.
+      #
+      # @return [void]
+      def copy(skill, target, replacing:)
+        if replacing
+          File.symlink?(target) ? File.unlink(target) : FileUtils.rm_rf(target)
+        end
+        FileUtils.mkdir_p(into)
+        FileUtils.cp_r(skill.path, target)
+      end
+    end
+  end
+end

data/lib/openlanes/skills/skill.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Skills
+    # One bundled skill: a directory holding a `SKILL.md` whose frontmatter
+    # names and describes it.
+    #
+    # @!attribute [r] name
+    #   @return [String] the frontmatter `name`, else the directory's
+    # @!attribute [r] description
+    #   @return [String] the whole frontmatter `description`
+    # @!attribute [r] path
+    #   @return [String] the skill's directory
+    Skill = Data.define(:name, :description, :path) do
+      # What `skills install -h` prints beside the name: a description is
+      # written for an agent deciding whether to load it, and runs long.
+      #
+      # @return [String]
+      def summary = description.split(/(?<=[.!?])\s+/, 2).first.to_s.strip
+
+      # @param into [String]
+      # @return [Boolean] whether a skill of this name is already there
+      def installed?(into) = File.exist?(File.join(into, name)) || File.symlink?(File.join(into, name))
+    end
+
+    class Skill
+      FILENAME = "SKILL.md"
+
+      # @param dir [String]
+      # @return [Array<OpenLanes::Skills::Skill>] every `<dir>/*/SKILL.md`, by name
+      def self.all(dir)
+        Dir.glob(File.join(dir, "*", FILENAME)).map { load(File.dirname(it)) }.sort_by(&:name)
+      end
+
+      # @param path [String] a skill directory
+      # @return [OpenLanes::Skills::Skill]
+      def self.load(path)
+        meta = frontmatter(File.read(File.join(path, FILENAME), encoding: "UTF-8"))
+        new(name: meta.fetch("name", File.basename(path)).to_s,
+          description: meta.fetch("description", "").to_s.gsub(/\s+/, " ").strip,
+          path:)
+      end
+
+      # Agents read a SKILL.md leniently, and a description with `word: word`
+      # in it is not valid YAML as a plain scalar. Refusing such a skill
+      # here would hide one the agents load fine, so a header YAML rejects
+      # is read a line at a time instead.
+      #
+      # @param text [String]
+      # @return [Hash{String => String}]
+      def self.frontmatter(text)
+        Frontmatter.split(text).first
+      rescue Psych::Exception
+        header = text[/\A---\s*\n(.*?)\n---/m, 1].to_s
+        header.scan(/^([a-z][\w-]*):[ \t]*(.*)$/).to_h.transform_values { it.strip.delete_prefix('"').delete_suffix('"') }
+      end
+      private_class_method :frontmatter
+    end
+  end
+end

data/lib/openlanes/skills.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # The agent skills that ship inside the gem, under `skills/`, and the copy
+  # that puts them where a coding agent looks for them.
+  module Skills
+    # Where the bundled skills live: beside `agents/`, at the gem root.
+    SOURCE_DIR = File.expand_path("../../skills", __dir__)
+
+    # The shared skill store that `~/.claude/skills` and the other agents'
+    # skill directories link into.
+    DESTINATION = File.join(Dir.home, ".agents", "skills")
+
+    module_function
+
+    # @param dir [String] a directory of `<name>/SKILL.md`
+    # @return [Array<OpenLanes::Skills::Skill>] by name
+    def bundled(dir: SOURCE_DIR) = Skill.all(dir)
+
+    # @param into [String]
+    # @param source [String]
+    # @return [OpenLanes::Skills::Installer]
+    def installer(into: DESTINATION, source: SOURCE_DIR) = Installer.new(into:, skills: bundled(dir: source))
+  end
+end

data/lib/openlanes/support/config.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module OpenLanes
+  # A project's `.openlanes.yml`, at its root:
+  #
+  #   project: Equilibris App   # heading for INDEX.md; default: the root's name
+  #   lane: full                # default lane for `openlanes create`
+  #   frontend: false           # a spec's `frontend:` when spec.md omits it
+  #   jobs: 4                   # how many plans `openlanes run` works on at once
+  #   redis_url: redis://10.0.4.2:6379/0  # the Redis the live run shares (W16)
+  #   commands:                 # per-command option defaults
+  #     run:
+  #       timeout: 1800
+  #
+  # Precedence, loudest first: a flag typed on the command line, the plan's
+  # spec.md frontmatter, this file, the built-in default. The file supplies
+  # defaults and nothing else.
+  #
+  # `jobs`, `lane` and `project` are each one command's option said once for
+  # the whole project, so each has a second spelling under `commands:`.
+  # Writing both is an error rather than a tie-break: two answers to one
+  # question is a file somebody will edit in the wrong place.
+  #
+  # Anything unknown is an error naming the file, never a shrug: a config
+  # silently ignored is a timeout somebody set that stops applying with no
+  # signal anywhere.
+  #
+  # @!attribute [r] path
+  #   @return [String, nil] the file, nil when the project has none
+  # @!attribute [r] project
+  #   @return [String, nil]
+  # @!attribute [r] lane
+  #   @return [Symbol, nil] one of {Plans::Spec::LANES}
+  # @!attribute [r] frontend
+  #   @return [Boolean, nil] nil when each plan decides
+  # @!attribute [r] jobs
+  #   @return [Integer, nil]
+  # @!attribute [r] redis_url
+  #   @return [String, nil] where the live run keeps its board, its commands
+  #     and its plan claims; `--redis-url` beats it, and it beats `$REDIS_URL`
+  # @!attribute [r] commands
+  #   @return [Hash{String => Hash{Symbol => Object}}] by command name, as
+  #     typed: "run", "resync dirs"
+  Config = Data.define(:path, :project, :lane, :frontend, :jobs, :redis_url, :commands) do
+    def initialize(path: nil, project: nil, lane: nil, frontend: nil, jobs: nil, redis_url: nil, commands: {})
+      super
+    end
+
+    # One command's option defaults, the top-level spelling folded in.
+    #
+    # @param command [String, Symbol] e.g. :run or "resync dirs"
+    # @return [Hash{Symbol => Object}]
+    def for(command)
+      name = command.to_s
+      folded = Config::SHORTHANDS.filter_map { |key, owner|
+        value = public_send(key)
+        [key, value.is_a?(Symbol) ? value.to_s : value] if owner == name && !value.nil?
+      }.to_h
+      commands.fetch(name, {}).merge(folded)
+    end
+
+    # @return [Boolean] whether the project has a file at all
+    def file? = !path.nil?
+
+    # The file `openlanes init` writes: only what was set, in the order the
+    # keys are documented, so it reads like the example it came from.
+    #
+    # @return [String]
+    def to_yaml
+      settings = { "project" => project, "lane" => lane&.to_s, "frontend" => frontend, "jobs" => jobs,
+                   "redis_url" => redis_url }
+      settings["commands"] = commands.transform_values { it.transform_keys(&:to_s) } unless commands.empty?
+      YAML.dump(settings.compact).delete_prefix("---\n")
+    end
+  end
+
+  class Config
+    # The file, at the project root.
+    FILE = Project::FILE
+
+    # Every key the top level may hold.
+    KEYS = %w[project lane frontend jobs redis_url commands].freeze
+
+    # Schemes a `redis_url:` may use.
+    REDIS_SCHEMES = %w[redis rediss unix].freeze
+
+    # Top-level keys that are one command's option, by the command that takes it.
+    SHORTHANDS = { project: "index", lane: "create", jobs: "run" }.freeze
+
+    class << self
+      # @param root [String] the project root
+      # @return [OpenLanes::Config] empty when the root holds no file
+      # @raise [OpenLanes::Error] when the file exists and cannot be used
+      def load(root)
+        path = File.join(root, FILE)
+        return new unless File.file?(path)
+
+        parse(File.read(path, encoding: "UTF-8"), path:)
+      end
+
+      # The project the process is working in. {CLI::Base} has already moved
+      # to the root, so that is where this looks; the file is reread only
+      # when it changes, because routing asks for it on every tick.
+      #
+      # @return [OpenLanes::Config]
+      def current
+        root = Project.root || Dir.pwd
+        path = File.join(root, FILE)
+        key = [path, File.file?(path) && File.mtime(path)]
+        return @current.last if @current&.first == key
+
+        load(root).tap { |config| @current = [key, config] }
+      end
+
+      # @param text [String] the whole file
+      # @param path [String] for every error message
+      # @return [OpenLanes::Config]
+      def parse(text, path:)
+        data = YAML.safe_load(text) || {}
+        fail_with(path, "expected a mapping of settings at the top") unless data.is_a?(Hash)
+
+        settings = data.transform_keys(&:to_s)
+        unknown = settings.keys - KEYS
+        unless unknown.empty?
+          fail_with(path,
+            "unknown key#{"s" unless unknown.size == 1} #{unknown.join(", ")}; " \
+            "known: #{KEYS.join(", ")}")
+        end
+
+        config = new(path:,
+          project:   project(settings, path),
+          lane:      lane(settings, path),
+          frontend:  frontend(settings, path),
+          jobs:      jobs(settings, path),
+          redis_url: redis_url(settings, path),
+          commands:  commands(settings["commands"], path))
+        conflicts!(config, path)
+        config
+      rescue Psych::Exception => e
+        fail_with(path, "is not valid YAML (#{e.message.lines.first.to_s.strip})")
+      end
+
+      private
+
+      # @return [void] never returns
+      def fail_with(path, message) = raise(Error, "#{path}: #{message}")
+
+      # @return [String, nil]
+      def project(settings, path)
+        value = settings["project"]
+        return nil if value.nil?
+        return value.strip if value.is_a?(String) && !value.strip.empty?
+
+        fail_with(path, "project: must be a non-empty name, not #{value.inspect}")
+      end
+
+      # @return [Symbol, nil]
+      def lane(settings, path)
+        return nil unless settings.key?("lane")
+
+        value = settings["lane"].to_s.strip.downcase.to_sym
+        return value if Plans::Spec::LANES.include?(value)
+
+        fail_with(path, "lane: #{settings["lane"].inspect} is not one of #{Plans::Spec::LANES.join(", ")}")
+      end
+
+      # @return [Boolean, nil]
+      def frontend(settings, path)
+        value = settings["frontend"]
+        return value if [true, false, nil].include?(value)
+
+        fail_with(path, "frontend: #{value.inspect} is not true or false")
+      end
+
+      # @return [Integer, nil]
+      def jobs(settings, path)
+        value = settings["jobs"]
+        return value if value.nil? || (value.is_a?(Integer) && value.positive?)
+
+        fail_with(path, "jobs: #{value.inspect} is not a whole number above zero")
+      end
+
+      # @return [String, nil]
+      def redis_url(settings, path)
+        value = settings["redis_url"]
+        return nil if value.nil?
+        return value.strip if value.is_a?(String) && REDIS_SCHEMES.include?(value.strip[/\A([a-z]+):/, 1])
+
+        fail_with(path, "redis_url: #{value.inspect} is not a #{REDIS_SCHEMES.map { "#{it}://" }.join(", ")} URL")
+      end
+
+      # @return [Hash{String => Hash{Symbol => Object}}]
+      def commands(value, path)
+        return {} if value.nil?
+
+        fail_with(path, "commands: must be a mapping of command name to its options") unless value.is_a?(Hash)
+
+        value.to_h do |name, options|
+          fail_with(path, "commands.#{name}: must be a mapping of option to value") unless options.is_a?(Hash)
+
+          [name.to_s.strip, options.transform_keys { it.to_s.tr("-", "_").to_sym }]
+        end
+      end
+
+      # @return [void]
+      def conflicts!(config, path)
+        SHORTHANDS.each do |key, owner|
+          next if config.public_send(key).nil? || !config.commands.fetch(owner, {}).key?(key)
+
+          fail_with(path, "#{key} and commands.#{owner}.#{key} are the same setting; keep one")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/support/frontmatter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module OpenLanes
+  # Splits a markdown file into its YAML frontmatter and its body.
+  #
+  # The agent definitions and `create --from` both read frontmatter, and both
+  # used to call `YAML.safe_load` on their own. Its defaults refuse to build a
+  # `Date`, so an ordinary `date: 2026-08-31` raised Psych::DisallowedClass and
+  # `create` reported a missing `title:` on a file whose title was right there.
+  # One parser, one list of permitted classes, so that cannot happen twice.
+  module Frontmatter
+    # rubocop: disable Lint/OrAssignmentToConstant
+    # Frontmatter, then body.
+    PATTERN ||= /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
+
+    # Dates and timestamps are ordinary frontmatter, so they load. Nothing else
+    # does: the point of `safe_load` is that a seed file cannot name a class.
+    PERMITTED_CLASSES ||= [Date, Time].freeze
+    # rubocop: enable Lint/OrAssignmentToConstant
+
+    class << self
+      # @param content [String] a whole markdown file
+      # @return [Array(Hash, String)] the frontmatter and the body. A file with
+      #   no frontmatter is all body, and frontmatter that is not a mapping —
+      #   a bare list, a lone string — reads as no keys rather than raising.
+      # @raise [Psych::Exception] when the frontmatter is not valid YAML
+      def split(content)
+        match = PATTERN.match(content) or return [{}, content]
+
+        meta = YAML.safe_load(match[1], permitted_classes: PERMITTED_CLASSES)
+        [meta.is_a?(Hash) ? meta : {}, match[2]]
+      end
+    end
+  end
+end