proctolog 0.1.0

data/app/models/proctolog/decisions.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Every box under "Decisions for the owner" across a burst's pull requests,
+  # for one page. A box is in one state: open, answered otherwise, accepted
+  # from the desk, or ticked elsewhere. It waits for the owner when the owner
+  # starred it or the burst file names it. Nothing is sorted away: every box
+  # is listed under "all", and the counts of the states add up to it.
+  class Decisions
+    Changed = Class.new(StandardError)
+
+    # The ways to look at the boxes, with the words the page uses for them.
+    # The four states are also filters; "waiting" cuts across them.
+    FILTERS = {"waiting" => "Waiting for you", "open" => "Open", "answered" => "Answered otherwise", "accepted" => "Accepted",
+               "elsewhere" => "Ticked elsewhere", "all" => "All"}.freeze
+
+    # What the burst file says waits for the owner: a box, by the first words
+    # of its lead, or a question that has no box; and who said so.
+    Named = Data.define(:pr, :words, :question, :by) do
+      def initialize(words: nil, question: nil, by: nil, **) = super
+
+      def question? = question.present?
+
+      def names?(stop, decision) = pr == stop.number && words.present? && decision.plain_lead.start_with?(words)
+    end
+
+    # One box as GitHub renders it, and where it stands. `quote` is its lead
+    # as a note holds it, `answers` the owner's live changes to it, `asked`
+    # the live questions and remarks on it, which leave it open, `accepted`
+    # whether the owner ticked it from the desk, `named` the entries of the
+    # burst file that name it.
+    Box = Data.define(:stop, :decision, :html, :quote, :answers, :asked, :starred, :accepted, :named) do
+      delegate :position, :lead, :plain_lead, :alternative, to: :decision
+
+      # The owner's live notes on it, the newest last: notes are numbered as they are written.
+      def notes = (answers + asked).sort_by { [it.written_at, it.id[/\d+\z/].to_i] }
+
+      def state
+        if decision.ticked then accepted ? :accepted : :elsewhere
+        elsif answers.any? then :answered
+        else :open
+        end
+      end
+
+      def waiting? = decision.open? && (starred || named.any?)
+
+      # Open and waiting for no one: what one gesture may accept.
+      def routine? = state == :open && !waiting?
+
+      def to_param = "#{stop.number}-#{position}"
+    end
+
+    # What one pull request shows under a filter: its boxes, its questions
+    # that have no box, and the leads accepted from the desk that its
+    # description no longer holds.
+    Part = Data.define(:stop, :boxes, :questions, :rewritten) do
+      # Boxes in runs, each under the line the description leads it in with.
+      def groups(of = boxes) = of.slice_when { |one, other| one.decision.under != other.decision.under }.map { [it.first.decision.under, it] }
+
+      def blocking = boxes.select { it.decision.blocking? }
+
+      def non_blocking = boxes.reject { it.decision.blocking? }
+    end
+
+    # `marks` answers a pull request's number with the owner's marks on it,
+    # `renderings` with GitHub's HTML of its description. `pages` maps the
+    # address of a pull request on GitHub to the desk's page for it.
+    def initialize(route:, marks:, renderings:, named: [], pages: {})
+      @route, @marks, @renderings, @pages = route, marks, renderings, pages
+      @named = named.map { Named.new(**it) }
+    end
+
+    def boxes = @boxes ||= @route.flat_map { boxes_of(it) }
+
+    # The boxes a filter lists, and the one a page was just saved from
+    # (`keeping`, a box's `to_param`) wherever it now falls: it stays where the
+    # owner is, reading its new state, and goes from the list at the next visit.
+    def only(filter, keeping: nil) = boxes.select { shown?(it, filter) || it.to_param == keeping }
+
+    # What a filter lists: boxes, and under "waiting" the questions as well.
+    def count(filter) = only(filter).size + ((filter == "waiting") ? questions.size : 0)
+
+    # A filter the page was asked for, or the one worth opening on.
+    def filter_for(name)
+      return name if FILTERS.key?(name)
+
+      count("waiting").positive? ? "waiting" : "open"
+    end
+
+    # The boxes of one theme across the burst, in the route's order.
+    ThemeGroup = Data.define(:theme, :boxes)
+
+    # The boxes a filter lists, by the theme each names: the project's themes
+    # in its own order, then "other", where a box naming none or one the
+    # project does not list goes.
+    def by_theme(filter, keeping: nil)
+      themes = Theme.all
+      only(filter, keeping:).group_by { Theme.named(it.decision.theme_name, themes) || Theme::OTHER }
+        .sort_by { |theme, _| themes.index(theme) || themes.size }
+        .map { |theme, boxes| ThemeGroup.new(theme:, boxes:) }
+    end
+
+    def parts(filter, keeping: nil)
+      shown = only(filter, keeping:).group_by { it.stop.number }
+      @route.filter_map do |stop|
+        part = Part.new(stop:, boxes: shown.fetch(stop.number, []), questions: questions_of(stop, filter), rewritten: rewritten_of(stop, filter))
+        part if [part.boxes, part.questions, part.rewritten].any?(&:any?)
+      end
+    end
+
+    # Questions the burst file names that belong to no box, for the pull
+    # requests of the route: those are the ones a page lists.
+    def questions = @named.select(&:question?).select { @route.at(it.pr) }
+
+    # Entries of the burst file that name a box, and no box begins with their words.
+    def unmatched = @named.reject(&:question?).reject { |entry| boxes.any? { entry.names?(it.stop, it.decision) } }
+
+    # How many boxes of a pull request are in each state.
+    def tally(stop) = boxes.select { it.stop.number == stop.number }.map(&:state).tally
+
+    # The open boxes of a pull request that wait for no one.
+    def routine(stop) = boxes.select { it.stop.number == stop.number && it.routine? }
+
+    # The box a page named: it must still stand there, with that lead.
+    def box(number, position, lead)
+      boxes.find { it.stop.number == number && it.position == position && it.lead == lead } or raise Changed, gone(number)
+    end
+
+    # The unticked boxes of one pull request at these places, to tick.
+    def to_accept(number, positions)
+      chosen = boxes.select { it.stop.number == number && positions.include?(it.position) && it.decision.open? }
+      chosen.size == positions.uniq.size && chosen.any? or raise Changed, gone(number)
+      chosen
+    end
+
+    # The boxes of one pull request alone, which its own page shows.
+    def boxes_of(stop)
+      decisions = stop.description.decisions
+      marks = @marks.call(stop.number)
+      section = Rendering.new(@renderings.call(stop.number), pages: @pages).sections.find { it.heading == Description::DECISIONS }
+      items = section ? section.boxes : []
+      items = [] unless items.size == decisions.size # shortcut: if GitHub's list and the Markdown's disagree, show the Markdown; upgrade when one does
+      on_boxes = notes_on_boxes(marks.notes, stop.description)
+
+      decisions.zip(items).map do |decision, item|
+        answers, asked = on_boxes.fetch(decision, []).partition(&:change?)
+        Box.new(stop:, decision:, html: html_of(decision, item), quote: quote_of(decision, item, section), answers:, asked:,
+          starred: marks.starred.include?(decision.lead), accepted: marks.accepted.include?(decision.lead),
+          named: @named.select { it.names?(stop, decision) })
+      end
+    end
+
+    private
+
+    def shown?(box, filter)
+      case filter
+      when "all" then true
+      when "waiting" then box.waiting?
+      else box.state.to_s == filter
+      end
+    end
+
+    def gone(number) = "The boxes of ##{number} are not as the page showed them: read it again."
+
+    def questions_of(stop, filter) = (filter == "waiting") ? questions.select { it.pr == stop.number } : []
+
+    # Leads the owner accepted from the desk that no box of the description has now.
+    def rewritten_of(stop, filter)
+      return [] unless %w[accepted all].include?(filter)
+
+      @marks.call(stop.number).accepted - stop.description.decisions.map(&:lead)
+    end
+
+    def html_of(decision, item)
+      return ERB::Util.html_escape(decision.text) unless item
+
+      item.css("input.task-list-item-checkbox").each(&:remove)
+      item.inner_html.strip
+    end
+
+    # The lead as the page has it, with the words around it from the section's
+    # text, so that a note finds this box and not another that repeats the words.
+    def quote_of(decision, item, section)
+      quote = Note::Quote.new(exact: decision.plain_lead, before: nil, after: nil, section: Description::DECISIONS)
+      spot = item && quote.locate(item.text) or return quote
+
+      start = item.xpath("preceding::text()").sum { it.content.length } + spot.begin
+      finish = start + spot.size
+      text = section.text
+      quote.with(exact: item.text[spot], before: text[[start - Note::NEAR, 0].max...start], after: text[finish, Note::NEAR])
+    end
+
+    # The owner's live notes on words of a box, by the decision they fall in.
+    def notes_on_boxes(notes, description)
+      on_boxes = notes.select { it.live? && (it.place in Note::Quote[section: Description::DECISIONS]) }
+      on_boxes.group_by { description.decision_quoted_by(it.place) }.except(nil)
+    end
+  end
+end

data/app/models/proctolog/description.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A pull request's description, read for what the desk shows of it: the task
+  # boxes under "Decisions for the owner", the pictures it shows, its length.
+  class Description
+    DECISIONS = "Decisions for the owner"
+    NON_BLOCKING = /^###\s+Non-blocking\s*$/i
+    BOX = /^- \[([ xX])\] (.+)$/
+    PICTURE = %r{<img\b[^>]*\bsrc="(https://github\.com/user-attachments/assets/[^"]+)"}
+    # A picture shown, as an <img> or as Markdown's ![alt](address), and a
+    # decision's link to one by its alt text.
+    IMAGE = %r{<img\b[^>]*>|!\[[^\]]*\]\(https://github\.com/user-attachments/assets/[^)\s]+\)}
+    LINK = /\(#screenshot-([^)\s]+)\)/
+
+    # A picture the description shows: its alt text, which a decision links
+    # it by, and its asset on GitHub.
+    Shot = Data.define(:name, :asset)
+
+    # One box under "Decisions for the owner": its place among them, its
+    # words, whether it is ticked, the line the description leads its group
+    # in with ("Still open"), when it has one, and its grade: :blocking, or
+    # :non_blocking under a "### Non-blocking" heading. A description that
+    # grades none has every decision blocking. `row` is its line in the
+    # description, which a check names it by; `pictures` the shots it rests on.
+    Decision = Data.define(:position, :text, :ticked, :under, :grade, :row, :pictures) do
+      def initialize(grade: :blocking, row: nil, pictures: [], **) = super
+
+      def open? = !ticked
+
+      def blocking? = grade == :blocking
+
+      # The theme its hidden marker names, as the marker spells it; nil
+      # without one. Theme.named says which theme of the project that is.
+      def theme_name = text[Theme::MARKER, 1]
+
+      # Its words without theme markers: what its key is made from and what a
+      # choice compares, so naming or mending a theme never reopens a choice.
+      def bare_text = Theme.unmarked(text)
+
+      def key = text[/<!-- proctolog:decision ([\w.-]+) -->/, 1] || Digest::SHA256.hexdigest(bare_text)[0, 16]
+
+      # What was built, as the description puts it: the bold sentence, or the
+      # first one. It is how a decision is known again after an edit, so a
+      # colon does not end it: "Still open: after a refused send, ..." opens
+      # five boxes of one description.
+      def lead = bare_text[/\A\*\*(.+?)\*\*/, 1] || bare_text[/\A.+?[.?!](?=\s|\z)/] || bare_text
+
+      # The lead as the page reads it, with no Markdown around the words.
+      def plain_lead = plain(lead)
+
+      # Whether the box holds the words a quote is of.
+      def holds?(quote) = plain(text).include?(plain(quote.exact))
+
+      # Whether a quote could be about this decision: it quotes words of the
+      # box, or it quotes more than the lead and so takes in the whole lead.
+      # Other boxes may hold the same words: Description#decision_quoted_by tells.
+      def quoted_by?(quote) = holds?(quote) || plain(quote.exact).include?(plain_lead)
+
+      # Whether the quote is exactly this decision's lead.
+      def led_by?(quote) = plain_lead == plain(quote.exact)
+
+      # How many characters of the quote's surroundings stand round its words
+      # within this box; 0 when its words are not in the box.
+      def fit(quote)
+        around = Note::Quote.new(exact: plain(quote.exact), before: flat(quote.before), after: flat(quote.after), section: nil)
+        around.fit_in(flat(text)).to_i
+      end
+
+      def alternative = visible(text)[/Alternative: (.+)\z/, 1]
+
+      # The line as it stands in the description.
+      def line = "- [#{ticked ? "x" : " "}] #{text}"
+
+      private
+
+      def visible(words) = words.to_s.gsub(/<!--.*?-->/, "").strip
+      def plain(words) = visible(words).delete("*`").squish
+
+      # Like `plain`, for words with other text beside them: the spaces at the ends are part of what is compared.
+      def flat(words) = words.to_s.gsub(/<!--.*?-->/, "").delete("*`").gsub(/\s+/, " ")
+    end
+
+    def initialize(markdown)
+      @markdown = markdown.to_s.gsub("\r\n", "\n")
+    end
+
+    def to_s = @markdown
+
+    def words = @markdown.split.size
+
+    def pictures = @markdown.scan(PICTURE).flatten
+
+    # The pull requests it names, as "#1234".
+    def mentions = @markdown.scan(/#([1-9]\d{2,4})\b/).flatten.map(&:to_i).uniq
+
+    def digest = "sha256:#{Digest::SHA256.hexdigest(@markdown)}"
+
+    # The boxes after "### Non-blocking" are non-blocking, and the line that
+    # leads a group in starts again under it.
+    def decisions
+      under, grade = nil, :blocking
+      rows(DECISIONS).each_with_object([]) do |(line, row), found|
+        case line
+        when BOX then found << Decision.new(position: found.size, text: $2, ticked: $1 != " ", under:, grade:, row:, pictures: pictures_in($2))
+        when NON_BLOCKING then under, grade = nil, :non_blocking
+        when /^\S/ then under = line.strip.delete_suffix(":").delete("*")
+        end
+      end
+    end
+
+    # Every picture it shows, in its order.
+    def shots
+      @shots ||= @markdown.scan(IMAGE).filter_map do |shown|
+        asset = shown[%r{user-attachments/assets/(#{Picture::ASSET})}, 1] or next
+        Shot.new(name: shown[/\balt="([^"]*)"/, 1] || shown[/\A!\[([^\]]*)\]/, 1], asset:)
+      end
+    end
+
+    # The names of the pictures some line of it links: a decision, or a step
+    # of a scenario.
+    def linked = @markdown.scan(LINK).flatten.to_set
+
+    # The pictures a decision's words rest on: those its links name, a pair
+    # as both its halves, and those shown in its own line, each once.
+    def pictures_in(text) = (text.scan(LINK).flatten.flat_map { named(it) } + Description.new(text).shots).uniq
+
+    # A picture by its alt text, or a pair's halves when no picture has the
+    # name itself, as the desk's page pairs them.
+    def named(name)
+      halves = %w[before after].filter_map { |half| shots.find { it.name == "#{name}-#{half}" } }
+      shots.select { it.name == name }.presence || ((halves.size == 2) ? halves : [])
+    end
+
+    # The lines of a section under its heading, each with its line number in
+    # the description; none when it has no such section.
+    def rows(heading)
+      first = @markdown.lines.index { it[/\A## (.+)$/, 1]&.strip == heading } or return []
+      section(heading).lines.drop(1).each.with_index(first + 2).to_a
+    end
+
+    # The decision a quote is about: the box whose lead it is, else the only
+    # box that holds its words (or, when none does, whose lead it takes in).
+    # Of several, the one whose surroundings are those the quote saw, and none
+    # when they cannot tell the boxes apart, since "Alternative:" is in every box.
+    def decision_quoted_by(quote)
+      holding = decisions.select { it.holds?(quote) }.presence || decisions.select { it.quoted_by?(quote) }
+      candidates = holding.select { it.led_by?(quote) }.presence || holding
+      candidates.one? ? candidates.first : apart(candidates, quote)
+    end
+
+    def section(heading) = sections.fetch(heading, "")
+
+    private
+
+    # The box among several whose surroundings plainly are the quote's own.
+    def apart(candidates, quote)
+      fits = candidates.index_with { it.fit(quote) }
+      best, next_best = fits.values.max(2)
+      fits.key(best) if best.to_i >= Note::CONFIRMING && best > next_best
+    end
+
+    def sections = @sections ||= @markdown.split(/^(?=## )/).index_by { it[/\A## (.+)$/, 1]&.strip }
+  end
+end

data/app/models/proctolog/difference.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "open3"
+
+module Proctolog
+  # Whether two pictures show the same pixels, and where they do not: the
+  # boxes of the changed regions, a mask of every changed pixel, and that
+  # mask's pixel signature, by which the same change is known in two pairs.
+  # Pictures of different sizes are compared from the top left, and say so.
+  # Plain Ruby over ImageMagick, with no Rails in it, because the capture
+  # kit's compare.rb loads it without the desk. Each answer is kept in the
+  # cache root it is given, under the two pictures' pixel signatures.
+  class Difference
+    # A changed region, in pixels from the top left.
+    Box = Data.define(:left, :top, :width, :height) do
+      def right = left + width
+      def bottom = top + height
+
+      def near?(other, gap) = left - gap <= other.right && other.left - gap <= right && top - gap <= other.bottom && other.top - gap <= bottom
+
+      def +(other)
+        left, top = [self.left, other.left].min, [self.top, other.top].min
+        Box.new(left:, top:, width: [right, other.right].max - left, height: [bottom, other.bottom].max - top)
+      end
+    end
+
+    # What a comparison found. One that could not be made, for want of
+    # ImageMagick or of a picture it can read, is not compared.
+    Result = Data.define(:compared, :same, :boxes, :mask, :mask_signature, :sizes) do
+      def self.from(stored) = new(**stored, boxes: stored.fetch(:boxes).map { Box.new(**it) }, mask: stored[:mask]&.then { Pathname(it) })
+
+      def compared? = compared
+      def same? = same
+      def different_sizes? = sizes.uniq.size > 1
+
+      def to_h = super.merge(boxes: boxes.map(&:to_h), mask: mask&.to_s)
+    end
+
+    NOT_COMPARED = Result.new(compared: false, same: nil, boxes: [], mask: nil, mask_signature: nil, sizes: [])
+
+    # Changes nearer than this, in pixels, are one region: the letters of a
+    # changed word are one place to look, not one each.
+    GAP = 12
+
+    def self.between(before, after, cache:) = new(before, after, cache:).result
+
+    # A picture's pixel signature: a re-encoding or a change of metadata
+    # leaves it as it was. Kept by the file's bytes, so it is asked once.
+    def self.signature(file, cache:)
+      kept = Pathname(cache).join("signatures", Digest::SHA256.file(file).hexdigest)
+      return kept.read if kept.exist?
+
+      identify(file, "%#").tap { |signature| write(kept, signature) }
+    end
+
+    def self.identify(file, format)
+      output, status = Open3.capture2("magick", "identify", "-format", format, "#{file}[0]", err: File::NULL)
+      status.success? ? output.strip : raise(Unreadable, file.to_s)
+    end
+
+    # Beside the file and moved over it, so a reader never meets half of one.
+    def self.write(file, text)
+      file.dirname.mkpath
+      file.sub_ext("#{file.extname}.part").tap { it.write(text) }.rename(file)
+    end
+
+    Unreadable = Class.new(StandardError)
+
+    def initialize(before, after, cache:)
+      @before, @after, @cache = Pathname(before), Pathname(after), Pathname(cache).join("differences")
+    end
+
+    def result
+      signatures = [@before, @after].map { self.class.signature(it, cache: @cache.dirname) }
+      kept = @cache.join("#{signatures.join("-")}.json")
+      return Result.from(JSON.parse(kept.read, symbolize_names: true)) if kept.exist?
+
+      compare(signatures, mask: kept.sub_ext(".png")).tap { self.class.write(kept, it.to_h.to_json) }
+    rescue Errno::ENOENT, Unreadable
+      NOT_COMPARED
+    end
+
+    private
+
+    def compare(signatures, mask:)
+      sizes = [@before, @after].map { self.class.identify(it, "%w %h").split.map(&:to_i) }
+      return Result.new(compared: true, same: true, boxes: [], mask: nil, mask_signature: nil, sizes:) if signatures.uniq.size == 1 && sizes.uniq.size == 1
+
+      draw_mask(sizes, mask)
+      boxes = regions(mask)
+      Result.new(compared: true, same: boxes.empty?, boxes:, mask:, mask_signature: self.class.identify(mask, "%#"), sizes:)
+    end
+
+    # White where any channel differs, black elsewhere, on a canvas as large
+    # as the larger picture: what one picture has and the other lacks counts.
+    def draw_mask(sizes, mask)
+      canvas = sizes.transpose.map(&:max).join("x")
+      part = mask.sub_ext(".png.part")
+      mask.dirname.mkpath
+      run("magick", *laid(@before, canvas), *laid(@after, canvas), "-compose", "difference", "-composite",
+        "-separate", "-evaluate-sequence", "max", "-threshold", "0", "-depth", "8", "PNG8:#{part}")
+      part.rename(mask)
+    end
+
+    def laid(file, canvas) = ["(", "#{file}[0]", "-alpha", "off", "-background", "black", "-gravity", "NorthWest", "-extent", canvas, ")"]
+
+    # A run of changed pixels as ImageMagick lists it: its box, and white,
+    # which a palette names in sRGB and a grey mask in grey.
+    CHANGED = /^\s*\d+: (\d+)x(\d+)\+(\d+)\+(\d+) \S+ \d+ (?:gray\(255\)|srgb\(255,255,255\)|white)\s*$/
+
+    # The changed regions, each a run of changed pixels with those near it.
+    # ImageMagick lists the runs on one stream or the other, by its build.
+    def regions(mask)
+      listed, status = Open3.capture2e("magick", mask.to_s, "-define", "connected-components:verbose=true", "-connected-components", "8", "null:")
+      status.success? or raise Unreadable, mask.to_s
+      found = listed.scan(CHANGED)
+        .map { |width, height, left, top| Box.new(left: left.to_i, top: top.to_i, width: width.to_i, height: height.to_i) }
+      merged(found).sort_by { [it.top, it.left] }
+    end
+
+    def merged(boxes)
+      boxes.each_with_object([]) do |box, regions|
+        while (near = regions.find { it.near?(box, GAP) })
+          regions.delete(near)
+          box += near
+        end
+        regions << box
+      end
+    end
+
+    def run(*command)
+      output, status = Open3.capture2(*command, err: File::NULL)
+      status.success? ? output : raise(Unreadable, command.join(" "))
+    end
+  end
+end

data/app/models/proctolog/doctor.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "open3"
+require "socket"
+
+module Proctolog
+  # What this Mac and this checkout give the desk, a line each with the fix.
+  # A need that is missing keeps the desk from working; a nicety that is
+  # missing only turns its feature off. `proctolog doctor` prints it.
+  class Doctor
+    MARKS = {fine: "ok", missing: "!!", off: "--"}.freeze
+
+    Finding = Data.define(:state, :line) do
+      def missing? = state == :missing
+      def to_s = "#{MARKS.fetch(state)}  #{line}"
+    end
+
+    NEEDS = %i[ruby gh launcher checkout repository bursts].freeze
+    NICETIES = %i[release skills chrome diffle imagemagick ffmpeg app port].freeze
+
+    # project is nil when the directory is no Git checkout.
+    def initialize(project, home: Dir.home, path: ENV.fetch("PATH", ""))
+      @project, @home, @path = project, Pathname(home), path.split(File::PATH_SEPARATOR)
+    end
+
+    def findings = @findings ||= (NEEDS + NICETIES).filter_map { send(it) }
+
+    def fine? = findings.none?(&:missing?)
+
+    def to_s = findings.join("\n")
+
+    private
+
+    def ruby = fine("Ruby #{RUBY_VERSION}")
+
+    def gh
+      return missing("gh is not on the PATH: brew install gh, then gh auth login") unless command?("gh")
+
+      succeeds?("gh", "auth", "status") ? fine("gh, signed in") : missing("gh is not signed in: gh auth login")
+    end
+
+    # RubyGems' launcher for a gem, or the one bin/install leaves in ~/.local/bin for a checkout.
+    def launcher
+      if (folder = @path.find { File.executable?(File.join(it, "proctolog")) }) then fine("proctolog in #{folder}")
+      elsif (bin = @home.join(".local/bin")).join("proctolog").exist? then missing("#{bin} is not on the PATH: add it in ~/.zshrc")
+      else missing("PRoctolog is not installed: gem install proctolog, or ruby bin/install in a checkout of it")
+      end
+    end
+
+    def checkout = @project ? fine("Reviewing #{@project.root}") : missing("Not in a Git checkout: cd into the one you review, or pass --project")
+
+    # Asked only of a gh that is there: a missing one has its own line.
+    def repository
+      return unless @project && command?("gh")
+      return missing("#{@project.root}'s origin is not on GitHub") unless (name = @project.github_repository)
+
+      succeeds?("gh", "repo", "view", name, "--json", "name") ? fine("GitHub answers for #{name}") : missing("gh cannot read #{name}: ask for access to it")
+    end
+
+    def bursts
+      return unless @project
+
+      files = Burst.files
+      return missing("No bursts to open: start one with proctolog burst new NAME --pr NUMBER") if files.empty?
+
+      fine("Bursts: #{files.map { it.basename(".yml") }.join(", ")}")
+    end
+
+    # The skills an agent needs, by what the line calls them.
+    SKILLS = {"proctolog-pr-writing" => "PR-writing", "proctolog-handover" => "handover"}.freeze
+
+    def skills
+      folders = %w[.claude/skills .agents/skills].select { |folder| SKILLS.keys.all? { @home.join(folder, it).exist? } }
+      missing = SKILLS.reject { |skill, _| %w[.claude/skills .agents/skills].any? { @home.join(it, skill).exist? } }.values
+      if missing.any? then off("The #{missing.to_sentence} #{"skill".pluralize(missing.size)} #{missing.one? ? "is" : "are"} not linked: proctolog install")
+      else fine("The #{SKILLS.values.to_sentence} skills, in ~/#{folders.join(" and ~/")}")
+      end
+    end
+
+    # As the desk last asked RubyGems: a doctor waits on no network for it.
+    def release = (newer = Release.newer) ? off(newer.news) : fine("PRoctolog #{Release.running}")
+
+    def chrome
+      require "ferrum"
+      Ferrum::Browser::Options::Chrome.options.detect_path ? fine("Chrome, for browser tests and scenarios") : off("No Chrome: browser tests skip and scenarios cannot open")
+    end
+
+    def diffle = command?("diffle") ? fine("Diffle, for d on a pull request") : off("No Diffle, so d opens no code: brew install diffle")
+
+    def imagemagick = command?("magick") ? fine("ImageMagick, for comparing pictures") : off("No ImageMagick, so pictures are not compared: brew install imagemagick")
+
+    def ffmpeg = command?("ffmpeg") ? fine("ffmpeg, for the stills of films") : off("No ffmpeg, so films have no stills: brew install ffmpeg")
+
+    # Each command app.yml names runs from a program the checkout or the PATH holds.
+    def app
+      return unless @project
+
+      app = App.new(@project.definitions.join(App::FILE))
+      return off("No .proctolog/app.yml, so scenario buttons cannot run the app: see docs/manual/app.md") unless app.described?
+
+      lacking = app.programs.reject { runnable?(it) }
+      return missing("app.yml runs #{lacking.to_sentence}, which neither the checkout nor the PATH holds") if lacking.any?
+
+      fine("app.yml names #{app.parts.to_sentence}")
+    end
+
+    def port = answers?(4040) ? off("Port 4040 answers already: a desk may be open there, or serve --port 4041") : fine("Port 4040 is free")
+
+    def fine(line) = Finding.new(:fine, line)
+    def missing(line) = Finding.new(:missing, line)
+    def off(line) = Finding.new(:off, line)
+
+    def command?(name) = @path.any? { File.executable?(File.join(it, name)) }
+
+    # A program app.yml names: a path from the checkout's root, or a command on the PATH.
+    def runnable?(program) = program.include?("/") ? @project.root.join(program).executable? : command?(program)
+
+    def succeeds?(*command) = Open3.capture2e({"PATH" => @path.join(File::PATH_SEPARATOR)}, *command).last.success?
+
+    def answers?(port)
+      Socket.tcp("localhost", port, connect_timeout: 1, &:close)
+      true
+    rescue SystemCallError
+      false
+    end
+  end
+end

data/app/models/proctolog/evidence.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A picture an agent's answer rests on: a file on this Mac that the answer's
+  # evidence names, from the root or from the checkout under review. The desk
+  # gives out a file only when an answer of the burst names it, and only a
+  # picture, so its address reads nothing else the Mac holds.
+  class Evidence
+    KINDS = %w[png jpg jpeg gif webp].freeze
+
+    def self.picture?(path) = KINDS.include?(File.extname(path.to_s).delete(".").downcase)
+
+    def initialize(burst) = @burst = burst
+
+    # The file named, or nil when no answer names it, it is no picture, or it is not on this Mac.
+    def picture(path)
+      return unless self.class.picture?(path) && named.include?(path)
+
+      Project.current.root.join(path).then { it if it.file? }
+    end
+
+    private
+
+    def named = answers.flat_map { it["results"] }.flat_map { Array(it["evidence"]) }.filter_map { it["path"] }.to_set
+
+    # Those the desk keeps with the choices, and those waiting in the folder of responses.
+    def answers = [*Array(@burst.choices.document&.dig("responses")), *ResponseFiles.new(@burst).all]
+  end
+end

data/app/models/proctolog/failure.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Something went wrong that the owner can mend or should know of, with a
+  # sentence for the page it happened on. The application controller says it.
+  Failure = Class.new(StandardError)
+end