hecks 5.0.0 → 6.0.0

data/lib/hecks/hecks/adapters/console_capture.rb

@@ -67,6 +67,33 @@ module Hecks
         e.status
       end
 
+      # Runs the block captured and answers what it printed to stdout alone. What it printed to
+      # stderr (a domain's boot notices) goes on to the real stderr instead of into the answer, and
+      # a run that ended otherwise refuses with both.
+      #
+      # @yield the entry point to run
+      # @return [String] stdout when the entry point ended with status 0
+      # @raise [Failure] when it ended otherwise; the message is what it printed
+      def answer_apart(&)
+        out, err, status = synchronize { apart(&) }
+        raise Failure, (out + err).strip unless status.zero?
+
+        $stderr.write(err)
+        out
+      end
+
+      # Runs the block with each stream pointed at a buffer of its own, putting them back
+      # afterwards.
+      def apart(&)
+        saved = [$stdout, $stderr]
+        out = $stdout = StringIO.new
+        err = $stderr = StringIO.new
+        status = exit_status(&)
+        [out.string, err.string, status]
+      ensure
+        $stdout, $stderr = saved
+      end
+
       # Runs the block captured and answers its text, or refuses with it.
       #
       # @yield the entry point to run

data/lib/hecks/hecks/adapters/deploy_plans.rb

@@ -5,6 +5,15 @@ module Hecks
     # The plan a write to AWS prints when it is refused unconfirmed or run with `dry_run`: what the
     # project's script would do, read from the script's own text, so nothing is run to say it.
     module DeployPlans
+      # The CloudFormation output a companion script reads its box's instance id from.
+      INSTANCE_STACK = /out\s+(\S+)\s+InstanceId/
+
+      # The Compose project a companion script names.
+      COMPOSE_PROJECT = /compose -p (\w+)/
+
+      # The absolute directory a companion script makes on the box.
+      MADE_DIRECTORY = %r{mkdir -p (/\S+)}
+
       module_function
 
       # What `preview.sh <action>` would do for a branch.
@@ -33,9 +42,9 @@ module Hecks
       # @param taskdef [String] the task definition its image and settings are read from
       # @return [String]
       def companion(text, companion, taskdef)
-        stack = text[/out\s+(\S+)\s+InstanceId/, 1]
-        project = text[/compose -p (\w+)/, 1] || companion
-        directory = text[%r{mkdir -p (/\S+)}, 1]
+        stack = text[INSTANCE_STACK, 1]
+        project = text[COMPOSE_PROJECT, 1] || companion
+        directory = text[MADE_DIRECTORY, 1]
         place = directory ? " in #{directory}" : +""
         "roll #{companion} (Compose project #{project}#{place}) from task definition " \
           "#{taskdef} onto the box of stack #{stack || "<box stack>"} over SSM, beside the app's project, " \

data/lib/hecks/hecks/adapters/deploy_toolchain/answers.rb

@@ -10,6 +10,15 @@ module Hecks
       module Answers
         include Statuses
 
+        # The `SCHEMAS=` line of a data-copy script, capturing its default schema list.
+        COPY_SCHEMAS = /^SCHEMAS=(?:\$\{SCHEMAS:-)?"([^"]*)"/
+
+        # The data-copy script's database defaults, capturing the source's and the target's.
+        COPY_DATABASES = /^SRC_DB=\$\{SRC_DB:-([^}]*)\}; DST_DB=\$\{DST_DB:-([^}]*)\}/
+
+        # The last line of a service roll, capturing the taskdef and the tag it rolled.
+        ROLLED_LINE = /^==> rolled taskdef=(\S*) tag=(\S+)$/
+
         private
 
         # Runs the confirmed restore and answers what it printed.
@@ -55,7 +64,7 @@ module Hecks
           report = BluebookReport.new(File.read(File.expand_path(old)), File.read(File.expand_path(new)))
           diff_answer(report.changed? ? "changed" : "unchanged", report.text)
         rescue SystemCallError, JSON::ParserError, TypeError, KeyError => e
-          diff_answer("unavailable", "bluebooks: could not compare #{old} and #{new} (#{e.message.lines.first.strip})")
+          diff_answer("unavailable", "bluebooks: could not compare #{old} and #{new} (#{Text.first_line(e.message)})")
         end
 
         # The script reads the registry and the local image; its report says what it found.
@@ -65,7 +74,7 @@ module Hecks
 
           diff_answer(text.include?("no bluebook changes.") ? "unchanged" : "changed", text)
         rescue ConsoleCapture::Failure => e
-          diff_answer("unavailable", "bluebooks: #{e.message.lines.first.strip}; nothing to compare.")
+          diff_answer("unavailable", "bluebooks: #{Text.first_line(e.message)}; nothing to compare.")
         end
 
         def diff_answer(outcome, text) = { outcome: { value: outcome }, report: { value: text } }
@@ -92,7 +101,7 @@ module Hecks
         # Its schemas are the default of the `SCHEMAS=${SCHEMAS:-"..."}` line (overridable).
         def copy_plan(script, held)
           text = File.read(script)
-          schemas = text[/^SCHEMAS=(?:\$\{SCHEMAS:-)?"([^"]*)"/, 1].to_s.split.join(", ")
+          schemas = text[COPY_SCHEMAS, 1].to_s.split.join(", ")
           source_db, target_db = copy_databases(text, held)
           drop = plain(held[:force]) == true ? "; force=true drops each target schema first" : ""
           "copy schemas #{schemas} from database #{source_db} on #{plain(held[:source])} into database " \
@@ -102,7 +111,7 @@ module Hecks
 
         # The source and target databases: the record's, else the script's defaults.
         def copy_databases(text, held)
-          databases = text.match(/^SRC_DB=\$\{SRC_DB:-([^}]*)\}; DST_DB=\$\{DST_DB:-([^}]*)\}/)
+          databases = text.match(COPY_DATABASES)
           [database(held[:source_db]) || databases&.[](1), database(held[:target_db]) || databases&.[](2)]
         end
 
@@ -133,7 +142,7 @@ module Hecks
 
         # The taskdef and tag a service roll's last line names.
         def rolled(text)
-          match = text.match(/^==> rolled taskdef=(\S*) tag=(\S+)$/)
+          match = text.match(ROLLED_LINE)
           { taskdef: wrapped(match&.[](1)), tag: wrapped(match&.[](2)) }
         end
       end

data/lib/hecks/hecks/adapters/deploy_toolchain/scripts.rb

@@ -16,6 +16,9 @@ module Hecks
           def initialize(name, label, statuses, args = [], answering = []) = super
         end
 
+        # A path inside installed or vendored code, or git's own directory.
+        VENDORED_PATH = %r{/(node_modules|vendor|\.git)/}
+
         private
 
         # Runs one generated script, found for the record's project, from its own directory. Answers
@@ -26,7 +29,7 @@ module Hecks
           report = printed(result)
           return { report: { value: report } } if result.ok?
 
-          answer_or_refuse(script, result.status.exitstatus, report)
+          answer_or_refuse(script, result.exit_code, report)
         end
 
         # What the script printed to either stream, trimmed.
@@ -47,7 +50,7 @@ module Hecks
           beside = File.join(root, name)
           return beside if File.file?(beside)
 
-          found = Dir.glob(File.join(root, "**", name)).grep_v(%r{/(node_modules|vendor|\.git)/})
+          found = Dir.glob(File.join(root, "**", name)).grep_v(VENDORED_PATH)
           return found.first if found.one?
 
           raise ConsoleCapture::Failure, ambiguity(name, root, found.sort)
@@ -87,7 +90,7 @@ module Hecks
 
         def message_of(result)
           text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
-          text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
+          text.empty? ? "the tool ended with status #{result.exit_code}" : text
         end
       end
     end

data/lib/hecks/hecks/adapters/deploy_toolchain.rb

@@ -70,12 +70,12 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when the tree is not a checkout, or the linter found a
       #   violation; the message is its report
       def scan(**held)
-        paths = plain(held[:makefiles]).to_s.split(",").map(&:strip).reject(&:empty?)
+        paths = Text.comma_list(plain(held[:makefiles]))
         { report: { value: child(:lint, paths).dig(:output, :value) } }
       end
 
       # Projects each domain's OIDC client and scope manifest into its `oidc.json`, or into one
-      # `<chapter>.oidc.json` for each chapter of a directory that holds several, through
+      # `<bluebook>.oidc.json` for each bluebook of a directory that holds several, through
       # `hecks deploy oidc_manifest.project_oidc`.
       #
       # @param held [Hash] the `OidcManifest` record: `domains` (comma separated directories; every
@@ -83,7 +83,7 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `output:` one line per manifest written or skipped
       # @raise [ConsoleCapture::Failure] when the tree is not a checkout
       def manifest(**held)
-        domains = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
+        domains = Text.comma_list(plain(held[:domains]))
         child(:manifest, domains)
       end
 

data/lib/hecks/hecks/adapters/desktop_alert/alert.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class DesktopAlert
+      # One alert, and the program that shows it on this machine: `terminal-notifier` where it is
+      # installed, since clicking its alert opens the link; else `osascript` on macOS, whose alert
+      # opens Script Editor when clicked; else `notify-send`.
+      #
+      # @!attribute [r] title
+      #   @return [String] the alert's first line
+      # @!attribute [r] subtitle
+      #   @return [String] the line beneath it
+      # @!attribute [r] body
+      #   @return [String] the rest
+      # @!attribute [r] link
+      #   @return [String, nil] what clicking the alert opens
+      Alert = Struct.new(:title, :subtitle, :body, :link, keyword_init: true) do
+        # Shows the alert with the first program this machine has.
+        #
+        # @param shell [Shell] the adapter the program runs through
+        # @return [Shell::Result] how the last program tried ended; 127 when none is installed
+        def show(shell)
+          shown = shell.capture(*notifier)
+          status = shown.status
+          return shown unless status.exitstatus == 127
+
+          shell.capture(*fallback)
+        end
+
+        private
+
+        def notifier
+          ["terminal-notifier", "-title", title, "-subtitle", subtitle, "-message", body.empty? ? subtitle : body,
+           "-group", title, "-sound", "Glass", *(["-open", link] if link)]
+        end
+
+        def fallback
+          return ["notify-send", title, "#{subtitle}\n#{body}"] unless RUBY_PLATFORM.include?("darwin")
+
+          ["osascript", "-e", "display notification #{quoted(body)} with title #{quoted(title)} " \
+                              "subtitle #{quoted(subtitle)} sound name \"Glass\""]
+        end
+
+        # An AppleScript string literal.
+        def quoted(text) = "\"#{text.gsub(/[\\"]/) { |char| "\\#{char}" }}\""
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/desktop_alert.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/desktop_alert"
+
+Hecks.adapter "DesktopAlert" do
+  port "Alerts"
+end

data/lib/hecks/hecks/adapters/desktop_alert.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+require_relative "console_capture"
+require_relative "git"
+require_relative "desktop_alert/alert"
+
+module Hecks
+  module Adapters
+    # The `Alerts` port's adapter: says on the operator's desktop that a pushed branch is ready to
+    # deploy. A machine with neither a notifier nor `osascript` refuses, and the push it announces
+    # stands.
+    #
+    # The alert reads at a glance: the repository and "ready to deploy" as its title, the branch,
+    # commit and how many commits went out beneath it, and the newest commits' subjects as its body.
+    # Clicking it opens the branch's runs on GitHub when the remote is a GitHub repository.
+    class DesktopAlert
+      # How many commit subjects the body lists.
+      SUBJECTS = 3
+
+      # A GitHub remote's owner and repository, over HTTPS or SSH.
+      GITHUB = %r{github\.com[:/]([^/]+)/(.+?)(?:\.git)?/?\z}
+
+      # How many commits a push report says went out, captured.
+      COMMIT_COUNT = /(\d+) commit/
+
+      # 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)
+        @shell = Shell.new
+        @git = Git.new
+      end
+
+      # Shows that a branch was pushed and a deploy is ready.
+      #
+      # @param held [Hash] the `PushTrain` record: `checkout`, `branch`, `remote`, `pushed` and
+      #   `report`
+      # @return [Hash{Symbol => Hash}] `report:` the alert's title and subtitle
+      # @raise [ConsoleCapture::Failure] when no desktop alert could be shown
+      def announce(**held)
+        alert = Alert.new(title: title(held), subtitle: subtitle(held), body: body(held), link: runs(held))
+        shown = alert.show(@shell)
+        raise ConsoleCapture::Failure, "no desktop alert was shown: #{shown.err.strip}" unless shown.ok?
+
+        { report: { value: "#{alert.title}: #{alert.subtitle}" } }
+      end
+
+      private
+
+      # Named by its GitHub repository, else by the main checkout's directory: a boarding is often
+      # made from a worktree, whose directory says nothing about the repository.
+      def title(held)
+        owner_and_name = github(held)
+        "#{owner_and_name ? owner_and_name.last : main_checkout(held)} is ready to deploy"
+      end
+
+      def main_checkout(held)
+        common = git(held, "rev-parse", "--path-format=absolute", "--git-common-dir")
+        File.basename(common.ok? ? File.dirname(common.out.strip) : plain(held[:checkout]))
+      end
+
+      def subtitle(held)
+        went_out = plain(held[:report]).to_s[COMMIT_COUNT, 1]
+        "#{plain(held[:remote])}/#{plain(held[:branch])} at #{plain(held[:pushed])[0, 7]}" \
+          "#{" · #{went_out} new" if went_out}"
+      end
+
+      def body(held)
+        listed = git(held, "log", "-#{SUBJECTS}", "--format=%s", plain(held[:pushed]))
+        listed.ok? ? bullets(listed.out) : ""
+      end
+
+      # Each line of `text` as a bullet.
+      def bullets(text) = text.lines.map { |line| "• #{line.strip}" }.join("\n")
+
+      # The branch's runs on GitHub, newest first, or nil for a remote that is not on GitHub.
+      def runs(held)
+        owner, name = github(held)
+        "https://github.com/#{owner}/#{name}/actions?query=branch%3A#{plain(held[:branch])}" if owner
+      end
+
+      # The remote's GitHub owner and repository, or nil.
+      def github(held)
+        url = git(held, "remote", "get-url", plain(held[:remote]))
+        return unless url.ok?
+
+        remote = url.out.strip
+        remote.match(GITHUB)&.captures
+      end
+
+      def git(held, *) = @git.capture(*, chdir: plain(held[:checkout]))
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/finding_github.rb

@@ -19,6 +19,9 @@ module Hecks
       # The environment variable that names the repository when no setting does.
       REPOSITORY_VARIABLE = "HECKS_FINDINGS_REPO"
 
+      # The end of an issue's URL, capturing its number.
+      ISSUE_NUMBER = %r{/issues/(\d+)\z}
+
       # @param aggregate [Object, nil] unused
       # @param settings [Hash] `repository:` names the `owner/name` to drive
       # @param root [String, nil] unused
@@ -35,7 +38,7 @@ module Hecks
       #   issue URL
       def open_issue(**held)
         out = gh("issue", "create", "--title", plain(held[:title]).to_s, "--body", plain(held[:body]).to_s)
-        number = out.lines.last.to_s.strip[%r{/issues/(\d+)\z}, 1]
+        number = Text.last_lines(out, 1)[ISSUE_NUMBER, 1]
         raise Error, "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
 
         { issue_number: { value: number.to_i } }

data/lib/hecks/hecks/adapters/first_admin.rb

@@ -4,10 +4,10 @@ require_relative "../../adapters/driving/json"
 
 module Hecks
   module Adapters
-    # Gives a booted domain its first administrator through the chapter that provides
+    # Gives a booted domain its first administrator through the bluebook that provides
     # `"membership"`, the way a project's hand-written bootstrap script does.
     #
-    # The chapter names its own verbs (`provides "membership", admit:, grant:, people:`), so no
+    # The bluebook names its own verbs (`provides "membership", admit:, grant:, people:`), so no
     # aggregate is recognised by name. Both dispatches run as a caller that asserts the role the
     # command is gated to and binds no `actor_id`: Governance checks an identified caller against
     # its role assignments, which a domain with no administrator cannot have yet, and checks an
@@ -17,10 +17,16 @@ module Hecks
       # The roles that count as an administrator besides the one the grant command is gated to.
       OWNER_ROLES = %w[Owner].freeze
 
-      # What the refusal says when no chapter provides membership: the line to add to one.
-      NO_MEMBERSHIP = "this domain attaches no chapter that provides \"membership\". Add a line like " \
+      # An email address: one `@` with no whitespace on either side.
+      EMAIL = /\A[^\s@]+@[^\s@]+\z/
+
+      # The part of an email address before its `@`.
+      LOCAL_PART = /\A[^@]+/
+
+      # What the refusal says when no bluebook provides membership: the line to add to one.
+      NO_MEMBERSHIP = "this domain attaches no bluebook that provides \"membership\". Add a line like " \
                       "`provides \"membership\", admit: \"Person.Admit\", grant: \"Person.GrantAccess\", " \
-                      "people: \"Person.All\"` to the chapter that keeps who may sign in: admit and grant " \
+                      "people: \"Person.All\"` to the bluebook that keeps who may sign in: admit and grant " \
                       "name its commands (the grant command is gated to the administrator role), people " \
                       "names the query that lists everyone (docs/running-a-rules-service.md)"
 
@@ -49,7 +55,7 @@ module Hecks
       # @param name [String, nil] their name; the part of the email before the `@` when nil
       # @param role [String, nil] the role to grant; the one the grant command is gated to when nil
       # @return [Result] what was done
-      # @raise [Runtime::NotFound] when the domain has no membership chapter, the email is not an
+      # @raise [Runtime::NotFound] when the domain has no membership bluebook, the email is not an
       #   email, or an administrator already exists
       def call(email:, name: nil, role: nil)
         raise Runtime::NotFound, "#{email.inspect} is not an email address" unless email?(email)
@@ -58,14 +64,14 @@ module Hecks
         verbs, gate, people = check_unadministered(provider)
 
         admitted = people.none? { |person| person[:email] == email }
-        admit(provider, verbs.fetch(:admit), email, name || email[/\A[^@]+/]) if admitted
+        admit(provider, verbs.fetch(:admit), email, name || email[LOCAL_PART]) if admitted
         grant(provider, verbs.fetch(:grant), email, role || gate)
         Result.new(email: email, role: role || gate, admitted: admitted)
       end
 
       private
 
-      def email?(email) = email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+      def email?(email) = email.to_s.match?(EMAIL)
 
       # The membership verbs, the role the grant is gated to and the people held, once no
       # administrator is found among them.
@@ -78,7 +84,8 @@ module Hecks
       end
 
       def membership_provider
-        domain = @registry.bluebooks.values.first&.name
+        bluebook = @registry.first_bluebook
+        domain = bluebook&.name
         @registry.membership_provider_for(domain) or
           raise Runtime::NotFound, NO_MEMBERSHIP
       end

data/lib/hecks/hecks/adapters/git.rb

@@ -39,18 +39,18 @@ module Hecks
       # Vendors one package of the bluebook registry into a project, pinned to a release or a
       # commit, through `Hecks::EmbryonautBluebook::VendorCli`.
       #
-      # The source is `from`, else `EMBRYONAUT_BLUEBOOKS_SRC`; the project is `root`, else the
-      # current directory. `ALLOW_DOWNGRADE=1` lets an older release through, as for the script.
+      # The source is `from`, else `EMBRYONAUT_BLUEBOOKS_SRC`, else the `embryonaut_bluebooks`
+      # checkout beside the project; the project is `root`, else the current directory.
+      # `ALLOW_DOWNGRADE=1` lets an older release through, as for the script.
       #
       # @param held [Hash] the `Package` record: `package` (`name` or `name@version-or-commit`),
       #   `from` and `root`
-      # @return [Hash{Symbol => Hash}] `report:` what was vendored and whether its storage shape
-      #   changed
+      # @return [Hash{Symbol => Hash}] `report:` what was vendored and whether its shape changed
       # @raise [ConsoleCapture::Failure] when the source is not a git repository, or the vendoring
       #   was refused (no such release, a downgrade, an era-breaking shape change)
       def pin(**held)
-        from = plain(held[:from]) || ENV.fetch("EMBRYONAUT_BLUEBOOKS_SRC", nil)
         root = plain(held[:root]) || Dir.pwd
+        from = plain(held[:from]) || EmbryonautBluebook::VendorCli.default_source(root)
         require_repository!(from)
 
         { report: { value: vendored(held[:package], from, root) } }

data/lib/hecks/hecks/adapters/git_checkout.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/git_checkout"
+
+Hecks.adapter "GitCheckout" do
+  port "Reading"
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "git_worktrees"
+
+module Hecks
+  module Adapters
+    # The `Reading` port's adapter for `Checkout`: answers what state a checkout is in, as text,
+    # so nothing needs a raw `git status`, `git diff` or `git log`. It reads and never writes.
+    #
+    # Every query takes `checkout`, a directory inside the repository (the current directory when
+    # absent), and answers `text:`; a refusal is a `Runtime::NotFound`.
+    class GitCheckout
+      include GitWorktrees
+
+      # How many commits `log` prints when it is given no range.
+      RECENT = 20
+
+      # A commit range as git writes one: names joined by `..` or `...`, never an option.
+      RANGE = %r{\A[0-9A-Za-z_][0-9A-Za-z_./^~@{}-]*\z}
+
+      # 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)
+        @git = Git.new
+      end
+
+      # The branch, whether the checkout is a linked worktree, where it stands against local
+      # `main` and `origin/main`, and each changed or untracked path.
+      #
+      # @param held [Hash] `checkout`
+      # @return [Hash{Symbol => String}] `text:` one `name: value` line each, then the paths
+      # @raise [Runtime::NotFound] when the checkout is not a repository
+      def status(**held)
+        answering(held) do
+          lines = ["branch: #{read("rev-parse", "--abbrev-ref", "HEAD")}", "head: #{short(read("rev-parse", "HEAD"))}",
+                   "worktree: #{linked? ? "linked" : "primary"} (#{@checkout})",
+                   standing("main"), standing("origin/main")].compact
+          changed = dirty
+          lines << (changed.empty? ? "clean" : "changed:") << changed.map { |line| "  #{line}" }
+          lines.flatten.join("\n")
+        end
+      end
+
+      # What a checkout changed since a ref: the diffstat, or the paths alone.
+      #
+      # @param held [Hash] `checkout`; `since` (a ref, default `main`); `names_only` (true for the
+      #   paths alone, not the diffstat)
+      # @return [Hash{Symbol => String}] `text:` the diffstat, or one path per line
+      # @raise [Runtime::NotFound] when the checkout or the ref is not found
+      def changes(**held)
+        answering(held) do
+          since = ref(plain(held[:since]) || "main")
+          flag = plain(held[:names_only]).to_s == "true" ? "--name-only" : "--stat"
+          read("diff", flag, read("merge-base", since, "HEAD"))
+        end
+      end
+
+      # The commits in a range, newest first, one `short-sha subject` line each.
+      #
+      # @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)
+        answering(held) do
+          range = plain(held[:range])
+          read("log", "--format=%h %s", *(range ? [checked_range(range)] : ["-n", RECENT.to_s]))
+        end
+      end
+
+      private
+
+      def answering(held)
+        settle(held)
+        { text: "#{yield}\n" }
+      rescue ConsoleCapture::Failure => e
+        raise Runtime::NotFound, e.message
+      end
+
+      def linked? = primary.path != @checkout
+
+      # How far `HEAD` is ahead of and behind a ref, or nil when the repository has no such ref.
+      def standing(other)
+        return nil unless @git.capture("rev-parse", "--verify", "--quiet", other, chdir: @checkout).ok?
+
+        behind, ahead = read("rev-list", "--left-right", "--count", "#{other}...HEAD").split.map(&:to_i)
+        "#{other}: ahead #{ahead}, behind #{behind}"
+      end
+
+      def checked_range(range)
+        return range if range.match?(RANGE)
+
+        raise ConsoleCapture::Failure, "#{range.inspect} is not a commit range"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_landing/merger.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "../git_worktrees"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # One landing: a branch merged onto another, fast-forward when it can be and as a merge commit
+      # when it cannot, in the worktree that has the target checked out, else in a temporary one.
+      #
+      # It never forces anything, never pushes, and never settles a conflict: a merge that conflicts
+      # is aborted and refused, naming the paths in conflict, with every branch as it was.
+      class Merger
+        include GitWorktrees
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level the branch is in
+        # @param branch [String] the branch to land
+        # @param onto [String] the branch to land it on
+        def initialize(git, checkout, branch:, onto:)
+          @git = git
+          @checkout = checkout
+          @branch = ref(branch)
+          @onto = ref(onto)
+        end
+
+        # @return [Hash{Symbol => Hash}] `outcome:` (`current`, `fast_forwarded` or `merged`),
+        #   `checkout:`, `branch:`, `landed:` (the commit the target names now) and `report:`
+        # @raise [ConsoleCapture::Failure] when the merge conflicts, or a tree holds
+        #   uncommitted work
+        def land
+          tip = branch_tip(@branch)
+          before = branch_tip(@onto)
+          return answer("current", before, "#{@branch} is already on #{@onto}") if ancestor?(tip, before)
+
+          host = worktree_on(@onto)
+          outcome, landed = host ? integrate(host.path, before) : in_temporary_tree(before)
+          answer(outcome, landed, "#{@branch} #{outcome.tr("_", " ")} onto #{@onto} at #{short(landed)}")
+        end
+
+        private
+
+        def in_temporary_tree(before)
+          Dir.mktmpdir("hecks-landing") do |dir|
+            tree = File.join(dir, "tree")
+            read("worktree", "add", "--detach", tree, before)
+            outcome, landed = integrate(tree, before)
+            read("update-ref", "refs/heads/#{@onto}", landed, before)
+            [outcome, landed]
+          ensure
+            @git.capture("worktree", "remove", "--force", tree, chdir: @checkout)
+          end
+        end
+
+        def integrate(dir, before)
+          changed = dirty(dir)
+          raise ConsoleCapture::Failure, "#{dir} holds uncommitted work: #{changed.join(", ")}" unless changed.empty?
+
+          outcome = ancestor?(before, branch_tip(@branch)) ? fast_forward(dir) : merge_commit(dir)
+          [outcome, read("rev-parse", "HEAD", dir: dir)]
+        end
+
+        def fast_forward(dir)
+          read("merge", "--ff-only", @branch, dir: dir)
+          "fast_forwarded"
+        end
+
+        def merge_commit(dir)
+          result = @git.capture("merge", "--no-ff", "--no-edit", @branch, chdir: dir)
+          return "merged" if result.ok?
+
+          conflicts = @git.capture("diff", "--name-only", "--diff-filter=U", chdir: dir).out.split
+          @git.capture("merge", "--abort", chdir: dir)
+          raise ConsoleCapture::Failure, "merging #{@branch} into #{@onto} conflicts in #{conflicts.join(", ")}; nothing changed"
+        end
+
+        def answer(outcome, landed, report)
+          { outcome: { value: outcome }, checkout: { value: @checkout }, branch: { value: @branch },
+            landed: { value: landed }, report: { value: report } }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_landing.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/git_landing"
+
+Hecks.adapter "GitLanding" do
+  port "Worktrees"
+end