proctolog 0.1.0

data/app/models/proctolog/picture.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "digest"
+require "net/http"
+require "open3"
+
+module Proctolog
+  # A picture of a description, kept on this Mac. The address GitHub keeps for
+  # it answers a request that carries gh's token with a redirect to a signed
+  # file, good for a few minutes, so the file is fetched once and kept under
+  # cache/ by its asset id.
+  class Picture
+    Unavailable = Class.new(StandardError)
+
+    EXTENSIONS = %w[png gif jpg jpeg].freeze
+    # A picture's id, the UUID in its address on GitHub.
+    ASSET = /\h{8}(-\h{4}){3}-\h{12}/
+    WHOLE_ASSET = /\A#{ASSET}\z/
+    # A picture's file as the desk serves it: its id and its kind.
+    FILE = /#{ASSET}\.\w+/
+    ADDRESS = "https://github.com/user-attachments/assets/"
+    REDIRECTIONS = 3
+
+    def self.asset?(id) = id.is_a?(String) && id.match?(WHOLE_ASSET)
+
+    # The file of a picture on this Mac, of whatever kind; nil when it was
+    # never fetched.
+    def self.on_disk(asset) = EXTENSIONS.map { Project.current.pictures.join("#{asset}.#{it}") }.find(&:exist?)
+
+    # Its pixels' signature, by which a choice made on it knows whether it
+    # was retaken, as kept beside the file. Nil, unknown, until the desk has
+    # worked it out: a page only reads it, and says the picture is unverified.
+    def self.signature(asset) = signature_file(asset).then { it.read if it.exist? }
+
+    # Works the signature out and keeps it, as the picture under an asset
+    # never changes. ImageMagick takes a few tenths of a second a picture, so
+    # the desk does it as it fetches one, and behind the owner's back for
+    # those it already holds. Nil when it is not on this Mac or ImageMagick
+    # cannot read it.
+    def self.sign(asset)
+      signature(asset) || on_disk(asset)&.then { Difference.signature(it, cache: Project.current.cache).tap { |worked_out| Difference.write(signature_file(asset), worked_out) } }
+    rescue Difference::Unreadable, Errno::ENOENT
+      nil
+    end
+
+    def self.signature_file(asset) = Project.current.pictures.join("#{asset}.signature")
+
+    # Takes the pictures of a reading ahead of the pages that show them,
+    # behind the owner's back (FetchPicturesAheadJob). Once for each reading
+    # of the same pull requests, named by `of`, however often a burst asks
+    # again or another holds them too; the block answers their pictures as
+    # pairs of id and kind, and is only called the first time, as it reads
+    # every description.
+    def self.fetch_ahead(of:)
+      return unless (@taken_ahead ||= Set.new).add?(of)
+
+      pictures = yield.uniq.select { |_, extension| EXTENSIONS.include?(extension) }
+      FetchPicturesAheadJob.perform_later(pictures) if pictures.any?
+    end
+
+    # The token gh signs in with, which GitHub asks for before it gives out a picture.
+    def self.token
+      answer, status = Open3.capture2("gh", "auth", "token")
+      status.success? ? answer.strip : raise(Unavailable, "gh has no token to fetch pictures with.")
+    rescue Errno::ENOENT
+      raise Unavailable, "gh is not on the PATH."
+    end
+
+    # A picture GitHub never held, an unopened pull request's, kept among the
+    # others under an id made of its bytes: the same picture keeps its id
+    # however often it is read, and one retaken gets another. Signing is
+    # left to fetch_ahead, behind the owner's back. Nil for a kind the desk
+    # does not show.
+    def self.import(file)
+      extension = file.extname.delete_prefix(".").downcase
+      return unless EXTENSIONS.include?(extension)
+
+      bytes = file.binread
+      new(Digest::SHA256.hexdigest(bytes).first(32).unpack("a8a4a4a4a12").join("-"), extension).tap { it.send(:store, bytes) unless it.path.exist? }
+    end
+
+    attr_reader :asset, :extension
+
+    def initialize(asset, extension)
+      @asset, @extension = asset, extension
+    end
+
+    # Fetched with a token already at hand; a failure is left for the page to tell.
+    def fetch(token)
+      @token = token
+      file
+    rescue Unavailable
+      nil
+    end
+
+    def path = directory.join("#{asset}.#{extension}")
+
+    # Where its bytes are on disk, fetching them first when this is the first time.
+    def file
+      path.exist? ? path : keep(download)
+    end
+
+    private
+
+    def directory = Project.current.pictures
+
+    def keep(bytes)
+      store(bytes)
+      self.class.sign(asset)
+      path
+    end
+
+    # Written beside the file and moved over it, so that two requests for the
+    # same picture never leave, or serve, half of one.
+    def store(bytes)
+      directory.mkpath
+      draft = directory.join("#{asset}.#{SecureRandom.hex(4)}.part")
+      draft.binwrite(bytes)
+      draft.rename(path)
+    end
+
+    def download
+      signed = get(URI("#{ADDRESS}#{asset}"), "Authorization" => "token #{token}")
+      signed.is_a?(Net::HTTPRedirection) or raise Unavailable, "GitHub does not give out the picture #{asset} (it answered #{signed.code})."
+      stored = get(URI(signed.fetch("location")))
+      stored.is_a?(Net::HTTPSuccess) or raise Unavailable, "GitHub's storage did not give out the picture #{asset} (it answered #{stored.code})."
+      stored.body
+    rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout => e
+      raise Unavailable, "The picture #{asset} could not be fetched: #{e.message}."
+    end
+
+    def get(uri, headers = {})
+      Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) { it.get(uri.request_uri, headers) }
+    end
+
+    def token = @token ||= self.class.token
+  end
+end

data/app/models/proctolog/pieces_rendering.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Pieces of a description's markdown as GitHub would draw them, with the
+  # pictures they show served from this Mac like those of a page of the desk.
+  class PiecesRendering
+    # The extension GitHub's address does not carry: the kind already on this Mac, else the likeliest.
+    GUESS = "png"
+    SHOWN = %r{user-attachments/assets/(#{Picture::ASSET})}o
+
+    # How many pieces are drawn at a time: each is a request to GitHub, and a
+    # page of returned work asks for dozens at once.
+    ABREAST = 6
+
+    def initialize(github) = @github = github
+
+    # One piece of HTML for each piece of markdown, in its order.
+    def call(pieces)
+      pieces.each_slice(ABREAST).flat_map do |slice|
+        slice.map { |piece| Thread.new { Rails.application.executor.wrap { @github.rendered(piece) } } }.map(&:value)
+      end.map { serve_pictures_from_here(it) }
+    end
+
+    private
+
+    def serve_pictures_from_here(html)
+      Nokogiri::HTML5.fragment(html).tap do |fragment|
+        fragment.css("img").each do |img|
+          asset = img["src"].to_s[SHOWN, 1] or next
+          extension = Picture.on_disk(asset)&.extname&.delete(".") || GUESS
+          img["src"] = "/pictures/#{asset}.#{extension}"
+          img["loading"] = "lazy"
+          img.remove_attribute("width")
+          img.remove_attribute("height")
+          img.parent.replace(img) if img.parent.name == "a"
+        end
+      end.to_html
+    end
+  end
+end

data/app/models/proctolog/project.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "digest"
+require "open3"
+
+module Proctolog
+  class Project
+    Missing = Class.new(StandardError)
+
+    CONFIGURATION = ".proctolog"
+
+    class << self
+      attr_writer :current
+
+      def current = @current ||= discover(ENV.fetch("PROCTOLOG_PROJECT", Dir.pwd))
+
+      def discover(directory = Dir.pwd)
+        output, status = Open3.capture2e("git", "-C", Pathname(directory).expand_path.to_s, "rev-parse", "--show-toplevel")
+        raise Missing, "#{directory} is not inside a Git checkout. Pass --project to choose one." unless status.success?
+
+        new(output.strip)
+      end
+    end
+
+    attr_reader :root
+
+    def initialize(root) = @root = Pathname(root).realpath
+
+    def definitions = root.join(CONFIGURATION)
+    def bursts = definitions.join("bursts")
+    def scenarios = definitions.join("scenarios")
+
+    # Settings true of the repository in every checkout, kept in Git, and
+    # those of this machine alone, kept out of it and read over the first.
+    def shared = definitions.join("project.yml")
+    def local = definitions.join("local.yml")
+
+    # Where burst files were kept before bursts had their name, read for a
+    # slug bursts/ does not hold.
+    def reviews = definitions.join("reviews")
+
+    # A reviewer's own bursts and their scenarios, kept beside their marks: in
+    # no repository, and seen from every checkout of this one on this Mac.
+    def own_bursts = data.join("bursts")
+    def own_scenarios = data.join("scenarios")
+
+    # Pull requests nobody has opened yet, each in a folder named by its
+    # branch, beside the bursts that hold them.
+    def unopened = data.join("unopened")
+
+    # The reviewer's own first, then those the repository shares.
+    def burst_folders = [own_bursts, bursts, reviews]
+    def scenario_folders = [own_scenarios, scenarios]
+
+    # A path as the owner names it in a sentence: from the root of the
+    # checkout when it is in it, ".proctolog/bursts/first-run.yml", and from
+    # the home folder otherwise.
+    def from_root(path)
+      return Pathname(path).relative_path_from(root) if path.to_s.start_with?("#{root}/")
+
+      path.to_s.sub(/\A#{Regexp.escape(Dir.home)}(?=\/)/, "~")
+    end
+
+    # The repository's name, as a label says it: "sartoria".
+    def name = github_repository&.split("/")&.last || root.basename.to_s
+
+    def data = data_home.join(repository)
+    def cache = cache_home.join(repository)
+    def marks = data.join("marks")
+    def recordings = data.join("films")
+    def pictures = cache.join("pictures")
+    def browsers = cache.join("browsers")
+
+    def setting(name) = settings[name.to_s]
+
+    def decision_records = Array(setting(:decision_records)).map { root.join(it) }
+
+    # Where an agent records a rule the owner made: the project's CLAUDE.md,
+    # or a decision record in one of its folders, each from the root.
+    def rule_destinations = ["CLAUDE.md", *decision_records.map { from_root(it).to_s }]
+
+    # "owner/name" of the GitHub repository its origin is, when it is one.
+    def github_repository
+      return @github_repository if defined?(@github_repository)
+
+      remote, status = Open3.capture2e("git", "-C", root.to_s, "remote", "get-url", "origin")
+      @github_repository = (remote.strip[%r{(?:github\.com[:/])(?<repository>[\w.-]+/[\w.-]+?)(?:\.git)?\z}, :repository] if status.success?)
+    end
+
+    # The branch a pull request goes into when nobody names one: origin's
+    # own, as this Mac last fetched it.
+    def default_branch
+      @default_branch ||= Open3.capture2e("git", "-C", root.to_s, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
+        .then { |output, status| (output.strip.delete_prefix("origin/") if status.success?).presence || "main" }
+    end
+
+    private
+
+    def data_home = Desk.data
+    def cache_home = Desk.cache
+
+    # Asked of git once: every path of the store and the cache is under it, and
+    # a page reads dozens of them.
+    def repository = @repository ||= github_repository || "checkouts/#{Digest::SHA256.hexdigest(root.to_s)[..11]}"
+
+    # A key local.yml names replaces project.yml's whole: its themes are the
+    # machine's list, not more of the project's.
+    def settings = settings_in(shared).merge(settings_in(local))
+
+    def settings_in(file)
+      return {} unless file.file?
+
+      YAML.safe_load_file(file) || {}
+    rescue Psych::Exception => e
+      raise Missing, "#{file} is not valid YAML (#{e.message.lines.first&.strip})."
+    end
+  end
+end

data/app/models/proctolog/pull_request.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # One open pull request as GitHub describes it at this moment, or one
+  # nobody has opened yet as this Mac keeps it (Unopened).
+  class PullRequest < Data.define(:number, :title, :url, :author, :base, :head, :head_oid, :description, :described_at, :committed_at, :files, :threads, :stack_entry)
+    # GitHub never writes a number with a leading zero, so the desk numbers
+    # the pull requests nobody has opened yet so: 01, 02, and on.
+    UNOPENED = /\A0\d+\z/
+
+    # A number as an address, a file name or a list writes it: GitHub's as
+    # an integer, an unopened one's as written. Nil for anything else.
+    def self.number(text) = text.to_s.match?(UNOPENED) ? text.to_s : Integer(text.to_s, 10, exception: false)
+
+    def self.unopened?(number) = number.to_s.match?(UNOPENED)
+
+    # A review thread on GitHub that nobody resolved yet: where in the code it
+    # is, its address, and what was said, each as [who, what].
+    ReviewThread = Data.define(:path, :line, :url, :comments) do
+      def self.from(node)
+        comments = node.dig("comments", "nodes")
+        new(path: node["path"], line: node["line"], url: comments.first&.fetch("url"),
+          comments: comments.map { [it.dig("author", "login"), it.fetch("body")] })
+      end
+    end
+
+    # A pull request no longer open, as a burst that held it remembers it:
+    # merged, with the moment it went in, or closed without merging.
+    Gone = Data.define(:number, :title, :url, :merged_at, :description) do
+      def self.from(node)
+        new(number: node.fetch("number"), title: node.fetch("title"), url: node.fetch("url"),
+          merged_at: node["mergedAt"]&.then { Time.iso8601(it) }, description: Description.new(node["body"].to_s))
+      end
+
+      def merged? = !merged_at.nil?
+    end
+
+    # Its place in one of GitHub's native stacks: the stack's number, and its
+    # position from the bottom, 1 first. UNKNOWN stands for a reading that
+    # could not ask GitHub where its pull requests stand.
+    StackEntry = Data.define(:stack, :position) do
+      def self.from(node) = node&.then { new(stack: it.dig("stack", "number"), position: it.fetch("position")) }
+
+      def unknown? = stack.nil?
+    end
+    StackEntry::UNKNOWN = StackEntry.new(stack: nil, position: nil)
+
+    def self.from(node, stack_entry: nil)
+      new(
+        number: node.fetch("number"),
+        title: node.fetch("title"),
+        url: node.fetch("url"),
+        author: node.dig("author", "login"),
+        base: node.fetch("baseRefName"),
+        head: node.fetch("headRefName"),
+        head_oid: node.fetch("headRefOid"),
+        description: Description.new(node.fetch("body")),
+        described_at: Time.iso8601(node["lastEditedAt"] || node.fetch("createdAt")),
+        committed_at: Time.iso8601(node.dig("commits", "nodes", 0, "commit", "committedDate")),
+        files: node.dig("files", "nodes").pluck("path"),
+        threads: node.dig("reviewThreads", "nodes").reject { it.fetch("isResolved") }.map { ReviewThread.from(it) },
+        stack_entry:
+      )
+    end
+
+    # A reading kept before authors were read names none.
+    def initialize(author: nil, files: [], threads: [], stack_entry: nil, **) = super
+
+    def open_threads = threads.size
+
+    # The number of the native stack it is in, and its position there; nil
+    # when it is in none, or when where it stands is not known.
+    def stack = stack_entry&.stack
+
+    def position = stack_entry&.position
+
+    def stack_known? = !stack_entry&.unknown?
+
+    def unopened? = self.class.unopened?(number)
+
+    def opened? = !unopened?
+
+    # How a burst file lists it: by its number, or by its branch while
+    # nobody has opened it, so the list still holds once someone does.
+    def listed_as = opened? ? number : head
+
+    def to_param = number.to_s
+  end
+end

data/app/models/proctolog/recording.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Proctolog
+  # A film of a flow as a capture script left it: <name>.mp4 beside <name>.vtt,
+  # under films/<burst>/<pull request number, or "sitting">/. It is found by
+  # looking in that folder; no list of recordings is kept anywhere.
+  class Recording
+    # A frame is asked for a hair before it is shown, so that the frame itself
+    # is the first one at or after the time and never the one that follows.
+    SLACK = 0.001
+    DIRECTORY = -> { Project.current.recordings }
+
+    # What ffprobe says of the file: its size in pixels, its length, and the
+    # time each frame is first shown, which is where "one frame" begins and ends
+    # in a film that keeps every frame for as long as it was on screen.
+    Probe = Data.define(:width, :height, :length, :frames) do
+      def self.from(json)
+        stream = json.fetch("streams").first
+        new(width: stream.fetch("width"), height: stream.fetch("height"), length: Float(json.dig("format", "duration")),
+          frames: json.fetch("packets").map { Float(it.fetch("pts_time")) }.sort)
+      end
+    end
+
+    attr_reader :file
+
+    def self.directory = DIRECTORY.respond_to?(:call) ? DIRECTORY.call : DIRECTORY
+
+    def self.of(burst) = directory.join(burst.slug).glob("*/*.mp4").sort.map { new(it) }
+
+    def self.in(burst, folder) = directory.join(burst.slug, folder.to_s).glob("*.mp4").sort.map { new(it) }
+
+    PARAM = %r{\A(?<folder>sitting|\d+)/(?<name>[\w-][\w.-]*)\z}
+
+    # The recording that "sitting/first-run" names in a burst, when it is there.
+    def self.find(burst, param)
+      match = PARAM.match(param.to_s) or return
+      file = directory.join(burst.slug, match[:folder], "#{match[:name]}.mp4")
+      new(file) if file.file?
+    end
+
+    # The recording a note's path names, when its file is still there.
+    def self.at(path) = Project.current.data.join(path).then { new(it) if it.file? }
+
+    def self.probe_command(file) = ["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height:format=duration:packet=pts_time", "-of", "json", file.to_s]
+
+    def self.still_command(file, time, to) = ["ffmpeg", "-y", "-loglevel", "error", "-ss", format("%.3f", [time - SLACK, 0].max), "-i", file.to_s, "-frames:v", "1", to.to_s]
+
+    def initialize(file) = @file = file
+
+    def name = file.basename(".mp4").to_s
+
+    def burst_slug = file.dirname.dirname.basename.to_s
+
+    # The pull request it is about, or "sitting" for the owner's own pass.
+    def folder = file.dirname.basename.to_s
+
+    def number = PullRequest.number(folder)
+
+    # What the player's address and a moment's form call it.
+    def to_param = "#{folder}/#{name}"
+
+    # What a note keeps of it: the path from the desk's root.
+    def path = file.relative_path_from(Project.current.data).to_s
+
+    def url = "/films/#{file.relative_path_from(self.class.directory)}"
+
+    def captions_url = url.delete_suffix(".mp4") + ".vtt"
+
+    def chapters = @chapters ||= Chapters.read(file.sub_ext(".vtt"))
+
+    delegate :width, :height, :length, :frames, to: :probe
+
+    def megabytes = file.size / 1_000_000.0
+
+    # The notes of a marks file that are pinned to a moment of this film.
+    def noted_in(marks) = marks.notes.select { it.place in Note::Moment[recording: ^(path)] }
+
+    # The film's bytes, by which its stills are kept: a film written again is
+    # a round of its own, whatever its name.
+    def digest = Rails.cache.fetch([:film_digest, file.to_s, file.mtime.to_f]) { Digest::SHA256.file(file).hexdigest }
+
+    # The picture a step opens on: the capture script's own when it kept the
+    # frames the steps opened on, else taken from the film once. Kept in the
+    # cache under the film's digest. Nil when it cannot be had, without ffmpeg.
+    def still(index)
+      chapter = chapters.to_a[index] or return
+      keep_stills
+      kept = stills.join("#{index}.png")
+      return kept if kept.exist?
+
+      part = stills.join("#{index}.#{SecureRandom.hex(4)}.part.png")
+      system(*self.class.still_command(file, chapter.from, part), out: File::NULL, err: File::NULL) or return
+      part.rename(kept)
+      kept
+    end
+
+    def stills = Project.current.cache.join("stills", digest)
+
+    # The frames the capture script kept as each step opened, beside the film.
+    def openings = file.sub_ext(".steps")
+
+    # Kept once, when the desk first shows the film: the names of its steps,
+    # and the capture script's own frames when it kept one for every step.
+    # Only those are compared with another round: frames decoded from a film
+    # differ between two encodes of the same screens.
+    def keep_stills
+      return if stills.join("steps.json").exist?
+
+      stills.mkpath
+      lossless = chapters.any? && chapters.each_with_index.all? { |_, index| openings.join("#{index}.png").file? }
+      chapters.each_with_index { |_, index| FileUtils.cp(openings.join("#{index}.png"), stills.join("#{index}.png")) } if lossless
+      Difference.write(stills.join("steps.json"), {lossless:, names: chapters.map(&:name)}.to_json)
+    end
+
+    # How this round's steps stand against the round before, the film's digest
+    # then, by their names: each changed, new, or as it was, with a line that
+    # says which case holds. An unmarked strip never claims nothing changed.
+    Changes = Data.define(:said, :steps) do
+      def of(name) = steps[name]
+    end
+
+    def changes(earlier)
+      keep_stills
+      return Changes.new(said: "No earlier round to compare", steps: {}) unless earlier
+
+      before, now = [earlier, digest].map { Project.current.cache.join("stills", it) }
+      kept = [before, now].map { JSON.parse(it.join("steps.json").read) if it.join("steps.json").file? }
+      return Changes.new(said: "Not compared: a round without the capture script's own frames", steps: {}) unless kept.all? { it&.fetch("lossless") }
+
+      steps = kept.last.fetch("names").each_with_index.to_h do |name, index|
+        earlier_index = kept.first.fetch("names").index(name) or next [name, :new]
+        result = Difference.between(before.join("#{earlier_index}.png"), now.join("#{index}.png"), cache: Project.current.cache)
+        return Changes.new(said: "Not compared: ImageMagick missing", steps: {}) unless result.compared?
+
+        [name, result.same? ? :same : :changed]
+      end
+      Changes.new(said: changes_in_words(steps.values), steps:)
+    end
+
+    # The rounds a burst's films went through: the digest each film had, in
+    # the order the desk first showed them, kept beside the burst's marks.
+    class Rounds
+      def initialize(burst) = @file = Marks.directory_of(burst).join("films.yml")
+
+      # Notes a film's digest when the desk shows it for the first time, with
+      # its stills kept for a later round, and answers the digest of the
+      # round before it, if there was one.
+      def before(recording)
+        recording.keep_stills
+        seen = all.fetch(recording.to_param, [])
+        unless seen.include?(recording.digest)
+          seen += [recording.digest]
+          @file.dirname.mkpath
+          Difference.write(@file, all.merge(recording.to_param => seen).to_yaml)
+        end
+        seen[seen.index(recording.digest) - 1] if seen.index(recording.digest).positive?
+      end
+
+      private
+
+      def all = @file.file? ? YAML.safe_load_file(@file) || {} : {}
+    end
+
+    # The first moment a frame is on screen at or before `time`: the frame the
+    # owner sees when the film is paused there.
+    def frame_at(time) = frames.take_while { it <= time + SLACK }.last || 0.0
+
+    # The moment of a film that a note is pinned to: that frame saved as a
+    # picture in `folder`, where an agent can look at it.
+    def moment(time, box:, keep_in:)
+      shown = frame_at(time)
+      picture = keep_in.join("#{folder}-#{name}-#{(shown * 1000).round}.png")
+      keep_in.mkpath
+      system(*self.class.still_command(file, shown, picture)) or raise Failure, "ffmpeg could not save the frame at #{format("%.1f", shown)} s of #{name} as a picture, so no note was kept. Is ffmpeg installed, and may it write to #{keep_in}?"
+      Note::Moment.new(recording: path, time: shown.round(3), step: chapters.at(shown)&.name, frame: picture.to_s, box:)
+    end
+
+    private
+
+    def changes_in_words(marks)
+      changed, added = marks.count(:changed), marks.count(:new)
+      [changed.zero? ? "No step changed" : "#{changed} #{"step".pluralize(changed)} changed", ("#{added} new" if added.positive?)].compact.join(", ")
+    end
+
+    def probe = @probe ||= Rails.cache.fetch([file.to_s, file.mtime.to_f]) { Probe.from(JSON.parse(ask)) }
+
+    def ask
+      answer, status = Open3.capture2(*self.class.probe_command(file))
+      status.success? ? answer : raise(ArgumentError, "ffprobe could not read #{file}")
+    end
+  end
+end

data/app/models/proctolog/release.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+
+module Proctolog
+  # A version of PRoctolog: the one running, and the latest RubyGems holds as
+  # the desk last asked, once a day while it serves (Housekeeping). Only the
+  # asking waits on the network: a page, `serve` and doctor read the answer
+  # kept in the cache, and say nothing until there is one.
+  class Release < Data.define(:version)
+    include Comparable
+
+    # Where the gem is published, and asked of. PROCTOLOG_GEM_SERVER names a
+    # mirror, or a server of a trial's own.
+    def self.server = ENV.fetch("PROCTOLOG_GEM_SERVER", "https://rubygems.org").chomp("/")
+
+    # What a RubyGems that cannot be reached raises, which only means: not today.
+    UNANSWERED = [SocketError, SystemCallError, IOError, Timeout::Error, OpenSSL::SSL::SSLError, JSON::ParserError, KeyError].freeze
+
+    def self.running = new(VERSION)
+
+    # The latest as last asked, or nil before the first answer.
+    def self.latest
+      new(JSON.parse(kept.read).fetch("version")) if kept.exist?
+    rescue JSON::ParserError, KeyError
+      nil
+    end
+
+    # The latest, when it is newer than the one running.
+    def self.newer = latest&.then { it if it > running }
+
+    # Asks RubyGems, keeps the answer and returns it; nil when nothing
+    # answered. RubyGems says "unknown" of a gem it has never held.
+    def self.ask(answer: -> { asked(URI("#{server}/api/v1/versions/proctolog/latest.json")) })
+      version = JSON.parse(answer.call).fetch("version")
+      return unless Gem::Version.correct?(version)
+
+      kept.dirname.mkpath
+      kept.write(JSON.generate(version:, asked_at: Time.now.utc.iso8601))
+      new(version)
+    rescue *UNANSWERED
+      nil
+    end
+
+    def self.kept = Desk.cache.join("latest_release.json")
+
+    def self.asked(uri) = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 5) { it.get(uri.path).body }
+    private_class_method :asked
+
+    def <=>(other) = Gem::Version.new(version) <=> Gem::Version.new(other.version)
+
+    def to_s = version
+
+    # What the owner is told of a newer one: what to run, and where. `update`
+    # takes it however this PRoctolog was installed, a checkout too.
+    def news = "PRoctolog #{self} is out; you have #{Release.running}. To update, run `proctolog update` in a terminal, then restart the desk: stop it and run `proctolog serve` again."
+  end
+end