hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/dispatching/launcher.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../shell"
+require_relative "../console_capture"
+require_relative "brief_text"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # Starts one chosen row's session by running the launcher's own commands, so each step is the
+      # bluebook's command and nothing is written but through one: start the Work row, compose its
+      # brief, hand the brief to `AgentRun`. Before any of them, pull main (`LinkedTree.PullMain`),
+      # so a session never starts from a stale base. A step that fails yields the row to the plan.
+      class Launcher
+        # The claimant every dispatched row names.
+        CLAIMANT = "dispatch"
+
+        # The JSON object a command prints after any log lines.
+        JSON_OBJECT = /\{.*\}/m
+
+        # @param repo [String] the checkout whose `exe/hecks` runs the commands and where sessions work
+        # @param runner [#call, nil] runs an argument list in `repo` and answers a {Shell::Result}
+        def initialize(repo, runner: nil)
+          @repo = repo
+          @runner = runner || ->(argv) { Shell.new.capture("exe/hecks", *argv, chdir: repo) }
+        end
+
+        # @param row [Plan::Row] the row to start
+        # @param held [Array<String>] a line for each area another started row holds
+        # @param frozen [Array<String>] the frozen areas and aggregates
+        # @param minutes [Integer] the time budget of the row
+        # @param limit [Integer, nil] the most spec files a session runs per call, from the world
+        # @return [String] one line: the session started, or why the row went back to the plan
+        def launch(row, held:, frozen:, minutes:, limit: nil)
+          step(row, "pull main", pull_argv)
+          step(row, "start", start_argv(row, minutes))
+          text = BriefText.new(composed(row)).render(row.key, area: row.area, held: held, frozen: frozen, limit: limit)
+          step(row, "dispatch", dispatch_argv(row, text))
+          "started #{row.key}"
+        rescue ConsoleCapture::Failure => e
+          yield_back(row, e.message)
+        end
+
+        # @param key [String] the run, which is also the Work row's key
+        # @return [void]
+        def check(key) = @runner.call(["AgentRun.check!", "to=#{key}", "--wait"])
+
+        # @param key [String] the Work row to record as done
+        # @return [String] the line that says so
+        def finish(key)
+          @runner.call(["tickets", "Work.finish!", "to=#{key}", "--wait"])
+          "finished #{key}"
+        end
+
+        # @param key [String] the Work row to send back to the plan
+        # @param reason [String] why
+        # @return [String] the line that says so
+        def yield_back(key, reason)
+          key = key.key if key.respond_to?(:key)
+          @runner.call(["tickets", "Work.yield!", "to=#{key}", "reason.value=#{reason}", "--wait"])
+          "yielded #{key}: #{reason}"
+        end
+
+        private
+
+        def step(row, name, argv)
+          result = @runner.call(argv)
+          return result if result.ok? && !result.out.include?('"refusal": "')
+
+          raise ConsoleCapture::Failure, "#{name} of #{row.key} failed: #{said(result)}"
+        end
+
+        def said(result) = (result.err.empty? ? result.out : result.err).strip[0, 300]
+
+        # Local `main` current before the session starts, so no worktree is cut from a stale base.
+        def pull_argv = ["LinkedTree.pull_main!", "checkout.value=#{@repo}", "--wait"]
+
+        def dispatch_argv(row, text)
+          ["AgentRun.dispatch!", "run.value=#{row.key}", "repo.value=#{@repo}", "brief.value=#{text}", "--wait"]
+        end
+
+        def start_argv(row, minutes)
+          ["tickets", "Work.start!", "to=#{row.key}", "claimed_by.value=#{CLAIMANT}", "claimed_at.value=#{Time.now.utc.iso8601}",
+           *row.area.map { |word| "area.value=#{word}" }, "budget_minutes.value=#{minutes}", "--wait"]
+        end
+
+        def composed(row)
+          result = step(row, "compose", ["coder", "Brief.compose!", "work.value=#{row.key}", "outcome.value=#{row.title}",
+                                         "detail.value=#{row.detail}", *row.area.map { |word| "area.value=#{word}" }, "--wait"])
+          JSON.parse(result.out[JSON_OBJECT])["state"]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/plan.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../area_overlap"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # Which planned rows start a session now, and why each of the others waits. It decides from the
+      # rows it is given and starts nothing.
+      #
+      # A planned row waits when it sits in a frozen area, when its area overlaps a started row's or an
+      # earlier chosen row's (by {AreaOverlap}), or when the machine is loaded or the cap is reached,
+      # which also hold back every row after it.
+      class Plan
+        # A row, as {Rows} reads it.
+        Row = Struct.new(:key, :title, :detail, :area, keyword_init: true)
+
+        # What a name is compared without, so `quality_control` and `QualityControl` meet.
+        NOT_ALNUM = /[^a-z0-9]/
+
+        # A row left waiting, and the reason.
+        Skip = Struct.new(:key, :reason)
+
+        # @return [Array<Row>] the rows to start, in plan order
+        attr_reader :chosen
+
+        # @return [Array<Skip>] the rows left waiting, in plan order
+        attr_reader :skipped
+
+        # @param planned [Array<Row>] the planned rows, in plan order
+        # @param started [Array<Row>] the started rows
+        # @param limits [Hash] `cap:` (Integer), `load:` and `max_load:` (Float), `frozen:` (Array)
+        def initialize(planned, started, **limits)
+          @started = started
+          @limits = limits
+          @chosen = []
+          @skipped = []
+          planned.each { |row| consider(row) }
+        end
+
+        # @return [Array<Row>] the started rows and the chosen ones: whose areas are not to be edited
+        def holders = @started + @chosen
+
+        private
+
+        def consider(row)
+          reason = stop_reason || frozen_reason(row) || overlap_reason(row)
+          reason ? @skipped << Skip.new(row.key, reason) : @chosen << row
+        end
+
+        def stop_reason = overloaded || capped
+
+        def overloaded
+          return unless @limits[:load] > @limits[:max_load]
+
+          "skipped: load #{@limits[:load].round(1)} > #{@limits[:max_load].round(1)}"
+        end
+
+        def capped
+          return unless holders.size >= @limits[:cap]
+
+          "skipped: cap #{@limits[:cap]} reached (#{holders.size} started or chosen)"
+        end
+
+        def frozen_reason(row)
+          hit = @limits[:frozen].find { |name| row.area.any? { |word| squash(word).include?(squash(name)) } }
+          "skipped: frozen (#{hit})" if hit
+        end
+
+        def overlap_reason(row)
+          holders.each do |other|
+            pair = AreaOverlap.first_overlap(row.area, other.area)
+            return "skipped: #{pair[0]} overlaps #{other.key} at #{pair[1]}" if pair
+          end
+          nil
+        end
+
+        def squash(text) = text.to_s.downcase.gsub(NOT_ALNUM, "")
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/rows.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../started_work"
+require_relative "plan"
+require_relative "../push_size"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # The Work rows and agent runs of a booted registry, read and never written.
+      class Rows
+        # @param registry [Runtime::Registry, nil]
+        def initialize(registry)
+          @registry = registry
+        end
+
+        # The key prefix of a row that says main is red; such a row is planned first, and so is the
+        # `push-due` row once its title says the push is urgent.
+        RED = "red-"
+
+        # @return [Array<Plan::Row>] the planned rows, red ones first, then in plan order (a row
+        #   with no step last)
+        def planned = rows("planned").sort_by.with_index { |row, index| [red?(row[1]) ? 0 : 1, row[0], index] }.map(&:last)
+
+        # @return [Array<Plan::Row>] the started rows
+        def started = rows("started").map(&:last)
+
+        # @return [Hash{String => Hash}] each agent run's key with its `status:` and `condition:`
+        def runs
+          aggregate = find("Hecks", "AgentRun")
+          return {} unless aggregate
+
+          @registry.repository("Hecks", aggregate).all.to_h { |run| [field(run, :run).to_s, state(run)] }
+        end
+
+        private
+
+        def red?(row) = row.key.start_with?(RED) || (row.key == "push-due" && row.title.start_with?(PushSize::URGENT))
+
+        def rows(status)
+          work = find("Tickets", "Work")
+          return [] unless work
+
+          records = @registry.repository("Tickets", work).all
+          records.select { |record| field(record, :status) == status }.map { |record| [step(record), row(record)] }
+        end
+
+        def row(record)
+          Plan::Row.new(key: field(record, :work).to_s, title: field(record, :title).to_s,
+                        detail: field(record, :detail).to_s, area: StartedWork.words(field(record, :area)))
+        end
+
+        def state(run) = { status: field(run, :status).to_s, condition: field(run, :condition).to_s }
+
+        def step(record) = field(record, :step) || Float::INFINITY
+
+        def find(domain, name)
+          bluebook = @registry&.bluebook(domain)
+          bluebook&.aggregates&.find { |candidate| candidate.hecks_name == name }
+        end
+
+        def field(record, name) = StartedWork.value(record, name)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/settings.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "etc"
+require_relative "../work_limits"
+require_relative "../shell"
+require_relative "../codebase/test_scope"
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # What the Tickets world says about filling the queue, and what the machine says about its
+      # load. The bluebook never reads the OS, so the load and the CPU count come through here.
+      class Settings
+        # The world verb naming the areas and aggregates whose persisted shape may not move.
+        FREEZE = "frozen_shapes"
+
+        # The world verb that carries the highest 1-minute load a session may be started under.
+        MAX_LOAD = "dispatch_max_load"
+
+        # The world verb that carries what every session starts with.
+        SESSION = "session_environment"
+
+        # Minutes a started row may run when the caller names no budget.
+        BUDGET_MINUTES = 90
+
+        # What `uptime` prints before the 1-minute load, on macOS and Linux.
+        UPTIME_LOAD = /load averages?:\s*([0-9]+[.,][0-9]+)/
+
+        # @param registry [Runtime::Registry, nil] the booted registry whose Tickets world is read
+        # @param load [#call, nil] answers the 1-minute load average; the machine's when nil
+        # @param cpus [Integer, nil] the CPU count; the machine's when nil
+        def initialize(registry, load: nil, cpus: nil)
+          @registry = registry
+          @load = load || -> { self.class.uptime_load }
+          @cpus = cpus || Etc.nprocessors
+        end
+
+        # Ruby's `Etc` has no load average, so the 1-minute figure is read from `uptime`.
+        #
+        # @param text [String, nil] what `uptime` printed; the machine's when nil
+        # @return [Float] the 1-minute load, 0.0 when `uptime` says none
+        def self.uptime_load(text = nil)
+          text ||= Shell.new.capture("uptime").out
+          text[UPTIME_LOAD, 1].to_s.tr(",", ".").to_f
+        end
+
+        # @return [Array<String>] the frozen areas and aggregates, empty when none is declared
+        def frozen = Array(declared(FREEZE)[:areas]).map(&:to_s)
+
+        # @return [Float] the 1-minute load average now
+        def load = @load.call.to_f
+
+        # @return [Integer] the CPU count
+        attr_reader :cpus
+
+        # @return [Float] the load above which no session is started: the world's, else the CPU count
+        def max_load = (declared(MAX_LOAD)[:limit] || @cpus).to_f
+
+        # @return [Integer] the cap on started rows
+        def cap = WorkLimits.cap(@registry)
+
+        # @return [Integer, nil] the most spec files a session may run per call, from the Hecks
+        #   world's `test_scope` setting; nil when none is declared
+        def spec_files_limit = Codebase::TestScope.limit(@registry)
+
+        # @return [Hash{String => String}] the environment every dispatched session starts with
+        def session_environment
+          dir = declared(SESSION)[:cargo_target_dir]
+          dir ? { "CARGO_TARGET_DIR" => File.expand_path(dir.to_s) } : {}
+        end
+
+        # @return [Integer, nil] the `nice` increment for a session's processes, nil for none
+        def nice = declared(SESSION)[:nice]
+
+        private
+
+        def declared(verb) = @registry&.world("Tickets")&.for_verb(verb) || {}
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching/settler.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # Settles the started rows whose sessions have ended: asks each running session how it is, then
+      # finishes the row of one that ended `done` and yields the row of one that ended any other way,
+      # with the condition as the reason. A session still working is left alone.
+      class Settler
+        # @param rows [Rows] where the started rows and the runs are read
+        # @param launcher [Launcher] runs the commands that check, finish and yield
+        def initialize(rows, launcher)
+          @rows = rows
+          @launcher = launcher
+        end
+
+        # @return [Array<String>] one line for each row settled, empty when none was
+        def call
+          checkable.each_key { |key| @launcher.check(key) }
+          ended.map { |key, run| settle(key, run[:condition]) }
+        end
+
+        private
+
+        def settle(key, condition)
+          condition == "done" ? @launcher.finish(key) : @launcher.yield_back(key, "its session ended #{condition}")
+        end
+
+        def checkable = mine.select { |_key, run| run[:status] == "started" }
+
+        def ended = mine.select { |_key, run| run[:status] == "finished" }
+
+        def mine
+          started = @rows.started.map(&:key)
+          @rows.runs.slice(*started)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/dispatching.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/dispatching"
+
+Hecks.adapter "Dispatching" do
+  port "Dispatching"
+end

data/lib/hecks/hecks/adapters/dispatching.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require_relative "dispatching/settings"
+require_relative "dispatching/rows"
+require_relative "dispatching/plan"
+require_relative "dispatching/launcher"
+require_relative "dispatching/settler"
+
+module Hecks
+  module Adapters
+    # The `Dispatching` port's adapter for `Dispatch`: reads the Work queue and the machine, says which
+    # planned rows would start a session and why each other waits, and with `confirm` starts them.
+    #
+    # It decides only what the Plan rules decide; whether a row may start is still the bluebook's
+    # (the `WorkAreas` and `WorkLimits` ports refuse a start that clashes or goes over the cap). The
+    # default is a dry run, which writes nothing.
+    class Dispatching
+      # @param registry [Runtime::Registry, nil] the booted registry whose rows are read
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `load:`, `cpus:` and `runner:` stand in for the machine and the launcher
+      # @param root [String, nil] unused
+      def initialize(registry: nil, aggregate: nil, settings: {}, root: nil)
+        @registry = registry
+        @standins = settings
+      end
+
+      # Says which planned rows start now, and starts them when confirmed.
+      #
+      # @param held [Hash] the `Dispatch` record: `repo`, `budget_minutes`, `confirm`
+      # @return [Hash{Symbol => Hash}] `report:` the load, the rows started or that would be, and the
+      #   rows left waiting with the reason
+      def choose(**held)
+        plan = plan_for
+        lines = [header(plan)] + plan.chosen.map { |row| chosen_line(row) } + plan.skipped.map { |skip| skipped_line(skip) }
+        lines += launch(plan, held) if plain(held[:confirm]) == true
+        { report: { value: lines.join("\n") } }
+      end
+
+      # Checks every started session and settles the row of each that ended: done finishes it.
+      #
+      # @param held [Hash] the `Dispatch` record: `repo`
+      # @return [Hash{Symbol => Hash}] `report:` one line per row settled
+      def conclude(**held)
+        lines = Settler.new(rows, launcher_for(held)).call
+        { report: { value: lines.empty? ? "nothing to settle" : lines.join("\n") } }
+      end
+
+      private
+
+      def rows = @standins[:rows] || Rows.new(@registry)
+
+      def machine = Settings.new(@registry, load: @standins[:load], cpus: @standins[:cpus])
+
+      def launcher_for(held) = Launcher.new(plain(held[:repo]), runner: @standins[:runner])
+
+      def plan_for
+        Plan.new(rows.planned, rows.started, cap: machine.cap, load: machine.load, max_load: machine.max_load,
+                                             frozen: machine.frozen)
+      end
+
+      def header(plan)
+        "#{load_line}; cap #{machine.cap}, #{rows.started.size} started; frozen: #{frozen_line}; #{plan.chosen.size} to start"
+      end
+
+      def load_line = "load #{machine.load.round(1)} (limit #{machine.max_load.round(1)}, #{machine.cpus} cpus)"
+
+      def frozen_line = machine.frozen.empty? ? "none" : machine.frozen.join(", ")
+
+      def chosen_line(row) = "would start #{row.key}: #{BriefText.new("outcome" => row.title).first_line}"
+
+      def skipped_line(skip) = "#{skip.key} #{skip.reason}"
+
+      def launch(plan, held)
+        launcher = launcher_for(held)
+        minutes = plain(held[:budget_minutes]) || Settings::BUDGET_MINUTES
+        plan.chosen.each_with_index.map do |row, index|
+          launcher.launch(row, held: holding(plan, index), frozen: machine.frozen, minutes: minutes,
+                          limit: machine.spec_files_limit)
+        end
+      end
+
+      # A line for each other row, started or chosen before this one, that holds an area.
+      def holding(plan, index)
+        (rows.started + plan.chosen.first(index)).reject { |other| other.area.empty? }.map { |other| held_line(other) }
+      end
+
+      def held_line(row) = "#{row.key}: #{row.title} (#{row.area.join(", ")})"
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/doctor_reading/report.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class DoctorReading
+      # Formats the checks: one line each, the fix beneath any check that is not ok.
+      module Report
+        private
+
+        def render(rows)
+          lines = rows.map { |name, status, detail, fix| line(name, status, detail, fix) }
+          (lines + ["status: #{worst(rows)}"]).join("\n")
+        end
+
+        def worst(rows)
+          statuses = rows.map { |row| row[1] }
+          statuses.max_by { |status| %i[ok warn fail].index(status) }
+        end
+
+        def line(name, status, detail, fix)
+          head = format("%<state>-5s %<name>-16s %<detail>s", state: status.to_s.upcase, name: name, detail: detail)
+          fix ? "#{head}\n      fix: #{fix}" : head
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/doctor_reading.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/doctor_reading"
+
+Hecks.adapter "DoctorReading" do
+  port "Doctor"
+end

data/lib/hecks/hecks/adapters/doctor_reading.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "open3"
+require "uri"
+require_relative "doctor_reading/report"
+
+module Hecks
+  module Adapters
+    # The `Doctor` port's adapter for `Checkout`: one line per check of whether this copy can run
+    # Hecks here, each with the fix when it is not ok. It reads and never writes: it does not boot
+    # a domain (a boot can mint an era), write to a store, or call GitHub.
+    class DoctorReading
+      include Report
+
+      # The channel a rust-toolchain.toml pins.
+      FIRST_LINE = /\A[^\n]*/
+
+      CHANNEL_PIN = /channel\s*=\s*"([^"]+)"/
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # @param held [Hash] `domain`, a checkout directory (the current directory when absent)
+      # @return [Hash{Symbol => String}] `text:` one line per check and the overall status
+      def doctor(**held)
+        directory = plain(held[:domain]) || Dir.pwd
+        rows = [overlays(directory), worktree(directory), toolchain(directory),
+                database(directory), version(directory)]
+        { text: render(rows) }
+      end
+
+      private
+
+      # Each row is [name, status, detail, fix], where status is :ok, :warn or :fail.
+      def overlays(directory)
+        files = overlay_files(directory)
+        bad = files.filter_map { |path| (error = syntax_error(path)) && [File.basename(path), error] }
+        return row("overlay files", :ok, "#{files.size} read") if bad.empty?
+
+        name, error = bad.first
+        row("overlay files", :fail, "#{name} does not parse: #{error}", "fix the syntax in #{name}")
+      end
+
+      def overlay_files(directory)
+        [directory, Dir.pwd].uniq.flat_map { |where| Dir[File.join(where, "*.local.{world,hecksagon}")] }.uniq
+      end
+
+      # The first line of a compile error, or nil when the file is valid Ruby. Compiling never runs it.
+      def syntax_error(path)
+        RubyVM::InstructionSequence.compile(File.read(path), path)
+        nil
+      rescue SyntaxError => e
+        first_line(e)
+      end
+
+      def worktree(directory)
+        out, status = Open3.capture2e("git", "-C", directory, "rev-parse", "--git-dir", "--git-common-dir")
+        return row("worktree", :warn, "not a git checkout", "run from a hecks checkout") unless status.success?
+
+        git_dir, common = out.lines.map(&:strip)
+        return row("worktree", :ok, "main checkout") if git_dir == common
+
+        unseen_overlays(directory, File.dirname(File.expand_path(common, directory)))
+      end
+
+      def unseen_overlays(directory, main)
+        here = Dir[File.join(directory, "lib/hecks/hecks/*.local.*")]
+        there = Dir[File.join(main, "lib/hecks/hecks/*.local.*")]
+        return row("worktree", :ok, "linked worktree sees the main checkout's overlays") if here.any? || there.empty?
+
+        row("worktree", :warn, "linked worktree cannot see #{there.size} overlay file(s) in #{main}",
+            "run from #{main}")
+      end
+
+      def toolchain(directory)
+        pin = File.read(File.join(directory, "rust-toolchain.toml"))[CHANNEL_PIN, 1]
+        installed = rustc_version
+        return row("toolchain", :warn, "rustc not on PATH", "install the pinned toolchain with rustup") unless installed
+        return row("toolchain", :ok, installed) if pin && installed.include?(pin)
+
+        row("toolchain", :warn, "installed #{installed}, pinned #{pin || "none"}", "rustup toolchain install #{pin}")
+      rescue Errno::ENOENT
+        row("toolchain", :warn, "no rust-toolchain.toml here", "run from a hecks checkout")
+      end
+
+      def rustc_version
+        out, status = Open3.capture2e("rustc", "--version")
+        status.success? ? out.strip : nil
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # The default store of the domain at this directory, checked without booting it.
+      def database(directory)
+        registry = Hecks.describe(directory).registry
+        store(registry, registry.first_domain_name)
+      rescue StandardError, ScriptError => e
+        row("store", :warn, "could not be read: #{first_line(e)}", "fix the overlay files first")
+      end
+
+      # The default store of one domain: Memory, a file store, or a Postgres database to reach.
+      def store(registry, name)
+        adapter = registry.default_adapter_for(name)
+        return row("store", :ok, "Memory") if adapter.nil? || adapter.to_s == "Memory"
+
+        url = registry.default_database_for(name)
+        return reach(url) if url.to_s.start_with?("postgres")
+
+        file_store(adapter.to_s, url)
+      end
+
+      # A file store is usable when its directory exists; the file itself is made on first write.
+      def file_store(adapter, path)
+        return row("store", :ok, adapter) if path.nil?
+
+        dir = File.dirname(path.to_s)
+        return row("store", :ok, "#{adapter}, #{path}") if File.directory?(dir)
+
+        row("store", :fail, "#{adapter} directory #{dir} is missing", "mkdir -p #{dir}")
+      end
+
+      # Postgres reachable, and the role the URL names exists; a read of the catalog, nothing written.
+      def reach(url)
+        require "pg"
+        PG.connect(url, connect_timeout: 3) { |conn| role_row(conn, URI.parse(url).user) }
+      rescue LoadError
+        row("store", :warn, "pg gem not loaded, so postgres was not tested", "bundle install")
+      rescue PG::Error => e
+        row("store", :fail, "postgres unreachable: #{first_line(e)}", "start postgres")
+      end
+
+      def role_row(conn, role)
+        exists = conn.exec_params("select 1 from pg_roles where rolname = $1", [role]).ntuples.positive?
+        return row("store", :ok, "postgres answers, role #{role} exists") if exists
+
+        row("store", :fail, "postgres answers, role #{role} is missing", "create the role: createuser #{role}")
+      end
+
+      def version(directory)
+        ahead, status = Open3.capture2e("git", "-C", directory, "rev-list", "--count", "origin/main..main")
+        base = "hecks #{Hecks::VERSION}"
+        return row("version", :ok, base) unless status.success? && ahead.to_i.positive?
+
+        row("version", :warn, "#{base}, local main #{ahead.strip} commit(s) ahead of origin/main", "push when ready")
+      end
+
+      def row(name, status, detail, fix = nil) = [name, status, detail, fix]
+
+      def first_line(error)
+        error.message[FIRST_LINE].to_s.strip
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_checkout.rb

@@ -63,7 +63,7 @@ module Hecks
       # @param held [Hash] `checkout`; `range` (default: the last 20 commits)
       # @return [Hash{Symbol => String}] `text:` the commits
       # @raise [Runtime::NotFound] when the checkout or the range is not found
-      def log(**held)
+      def history(**held)
         answering(held) do
           range = plain(held[:range])
           read("log", "--format=%h %s", *(range ? [checked_range(range)] : ["-n", RECENT.to_s]))