hecks 3.5.0 → 3.6.0

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

@@ -7,6 +7,9 @@ require_relative "codebase/ruby_child"
 require "hecks/projections/deploy/template_diff"
 require_relative "bluebook_report"
 require_relative "deploy_plans"
+require_relative "deploy_toolchain/statuses"
+require_relative "deploy_toolchain/scripts"
+require_relative "deploy_toolchain/answers"
 
 module Hecks
   module Adapters
@@ -20,68 +23,9 @@ module Hecks
     # the project it is given, wherever that is, so it needs no checkout, and neither does a
     # comparison.
     class DeployToolchain
-      # The `Hecks::Tools` tool an ask runs, by ask.
-      SCRIPTS = { generate: "project_deploy", lint: "lint_deploy_recipes", manifest: "project_oidc" }.freeze
-
-      # `hecks deploy recipe.project`'s flag for each `Recipe` field it takes.
-      GENERATE_FLAGS = { "--tenant" => :tenant, "--schema" => :schema, "--out" => :out,
-                         "--environment" => :environment }.freeze
-
-      # The file name the AwsBox projection gives the post-deploy smoke.
-      SMOKE_SCRIPT = "smoke-after-deploy.sh"
-
-      # What each status of `smoke-after-deploy.sh` means, for the reason a refusal gives.
-      SMOKE_STATUS = { 20 => "the roll did not settle", 21 => "gh missing or no repository, smoke not run",
-                       22 => "the smoke failed", 23 => "the smoke's result is unknown" }.freeze
-
-      # The file names the AwsBox projection gives the two rolls.
-      SERVICE_SCRIPT = "deploy-service.sh"
-      BOX_SCRIPT = "deploy-box.sh"
-
-      # What each status of `deploy-box.sh` means, for the reason a refusal gives.
-      BOX_STATUS = { 40 => "the box stack has no instance", 41 => "the roll did not succeed on the box",
-                     42 => "the box is not healthy after the roll" }.freeze
-
-      # What each status of `deploy-service.sh` means; it ends with the box roll's own statuses.
-      SERVICE_STATUS = { 2 => "unknown service", 30 => "the existing tag is not in ECR",
-                         31 => "the fresh tag is already in ECR", 32 => "the box's Compose file is unreadable",
-                         33 => "the box stack has no instance", 34 => "the stack has no parameter for the container",
-                         35 => "the stack update failed or did not settle",
-                         36 => "a parameter other than the container's changed",
-                         37 => "the task definition lacks the pushed image",
-                         38 => "the task definition has no such container" }.merge(BOX_STATUS).freeze
-
-      # The file names the AwsBox projection gives the data copy and its comparison.
-      RESTORE_SCRIPT = "restore-to-rds.sh"
-      VERIFY_SCRIPT = "verify-copy.sh"
-
-      # The status `verify-copy.sh` ends with when the databases differ: an answer, not a refusal.
-      DRIFT_STATUS = 50
-
-      # What each status of `restore-to-rds.sh` means, for the reason a refusal gives.
-      RESTORE_STATUS = { 60           => "a Postgres client older than 16",
-                         61           => "the target already has a schema; force=true replaces it",
-                         62           => "unexpected errors restoring a schema",
-                         DRIFT_STATUS => "the copy does not match the source" }.freeze
-
-      # The file name of the bluebook report script and of the preview script; a companion roll runs
-      # `deploy-<companion>.sh`.
-      DIFF_SCRIPT = "bluebooks-diff.sh"
-      PREVIEW_SCRIPT = "preview.sh"
-
-      # What `preview.sh` ends with: every refusal and failure is 1, a bad verb 2.
-      PREVIEW_STATUS = { 1 => "the preview script refused or failed", 2 => "usage" }.freeze
-
-      # What a roll script ends with: every refusal and failed check is 1.
-      COMPANION_STATUS = { 1 => "the roll was refused, did not succeed, or the companion is not healthy" }.freeze
-
-      # The outcome each `preview.sh` verb records; the writes among them need `confirm`.
-      PREVIEW_OUTCOMES = { "name" => "named", "url" => "located", "list" => "listed", "deploy" => "deployed",
-                           "destroy" => "destroyed", "login" => "signed_in" }.freeze
-      PREVIEW_WRITES = %w[deploy destroy login].freeze
-
-      # What `bluebooks-diff.sh` prints when it has nothing to compare.
-      DIFF_UNAVAILABLE = /^==> bluebooks: (could not read|the local domain image has no|the running domain image .* predates)/
+      include Statuses
+      include Scripts
+      include Answers
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -172,7 +116,7 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when no script, or more than one, is found, or it ends
       #   non-zero; the message names its status and what it printed
       def smoke(**held)
-        run_script(SMOKE_SCRIPT, held, smoke_env(held), "smoke", SMOKE_STATUS)
+        run_script(Script.new(SMOKE_SCRIPT, "smoke", SMOKE_STATUS), held, smoke_env(held))
       end
 
       # Rolls one service with a project's generated `deploy-service.sh`, through
@@ -190,9 +134,9 @@ module Hecks
       def roll_service(**held)
         env = { "EXISTING_TAG" => plain(held[:existing_tag]), "LOCAL_IMAGE" => plain(held[:local_image]),
                 "SMOKE_BY_COMMAND" => "1" }.compact
-        answer = run_script(SERVICE_SCRIPT, held, env, "service roll", SERVICE_STATUS, args: [plain(held[:service])])
-        match = answer[:report][:value].match(/^==> rolled taskdef=(\S*) tag=(\S+)$/)
-        answer.merge(taskdef: wrapped(match&.[](1)), tag: wrapped(match&.[](2))).merge(carried(held, "service_roll"))
+        script = Script.new(SERVICE_SCRIPT, "service roll", SERVICE_STATUS, [plain(held[:service])])
+        answer = run_script(script, held, env)
+        answer.merge(rolled(answer[:report][:value])).merge(carried(held, "service_roll"))
       end
 
       # Rolls the whole box with a project's generated `deploy-box.sh`, through
@@ -203,7 +147,7 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when no script, or more than one, is found, or it ends
       #   non-zero; the message names its status and what it printed
       def roll_box(**held)
-        answer = run_script(BOX_SCRIPT, held, {}, "box roll", BOX_STATUS, args: box_args(held))
+        answer = run_script(Script.new(BOX_SCRIPT, "box roll", BOX_STATUS, box_args(held)), held, {})
         answer.merge(carried(held, "box_roll")).merge(taskdef: wrapped(plain(held[:taskdef])))
       end
 
@@ -224,13 +168,8 @@ module Hecks
         plan = copy_plan(script, held)
         return copy_answer(held, "#{plan}\ndry run: nothing was run", planned: true) if plain(held[:dry_run]) == true
 
-        unless plain(held[:confirm]) == true
-          raise ConsoleCapture::Failure,
-                "refusing to restore: #{plan}\npass confirm=true to run it (dry_run=true prints this plan)"
-        end
-
-        answer = run_script(RESTORE_SCRIPT, held, copy_env(held), "restore", RESTORE_STATUS, args: copy_args(held))
-        copy_answer(held, answer[:report][:value], planned: false)
+        require_confirm(held, "restore", plan)
+        restore(held)
       end
 
       # Compares two databases with a project's generated `verify-copy.sh`, through
@@ -242,7 +181,8 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when no script is found or it fails for another reason
       def compare_copy(**held)
         env = { "A_DB" => database(held[:source_db]), "B_DB" => database(held[:target_db]) }.compact
-        answer = run_script(VERIFY_SCRIPT, held, env, "verify", {}, args: copy_args(held), answering: [DRIFT_STATUS])
+        script = Script.new(VERIFY_SCRIPT, "verify", {}, copy_args(held), [DRIFT_STATUS])
+        answer = run_script(script, held, env)
         { report: answer[:report], drifted: { value: answer.key?(:status) } }
       end
 
@@ -276,15 +216,11 @@ module Hecks
       #   script ends non-zero
       def run_preview(**held)
         action = plain(held[:action]).to_s
-        script = script_for(PREVIEW_SCRIPT, plain(held[:project]), plain(held[:script]))
-        if PREVIEW_WRITES.include?(action)
-          plan = DeployPlans.preview(File.read(script), action, plain(held[:branch]))
-          return planned_answer("#{action}: #{plan}") if plain(held[:dry_run]) == true
+        planned = gate_preview(held, action)
+        return planned if planned
 
-          require_confirm(held, "#{action} a preview", plan)
-        end
         env = { "BRANCH" => plain(held[:branch]) }.compact
-        answer = run_script(PREVIEW_SCRIPT, held, env, "preview #{action}", PREVIEW_STATUS, args: [action])
+        answer = run_script(Script.new(PREVIEW_SCRIPT, "preview #{action}", PREVIEW_STATUS, [action]), held, env)
         { outcome: { value: PREVIEW_OUTCOMES.fetch(action) }, report: answer[:report], planned: { value: false } }
       end
 
@@ -302,165 +238,16 @@ module Hecks
       def roll_companion(**held)
         companion = plain(held[:companion]).to_s
         name = "deploy-#{companion}.sh"
-        script = script_for(name, plain(held[:project]), plain(held[:script]))
-        plan = DeployPlans.companion(File.read(script), companion, plain(held[:taskdef]))
+        plan = companion_plan(held, name, companion)
         return planned_answer(plan) if plain(held[:dry_run]) == true
 
         require_confirm(held, "roll #{companion}", plan)
-        answer = run_script(name, held, {}, "companion roll", COMPANION_STATUS, args: [plain(held[:taskdef])])
-        answer.merge(planned: { value: false })
+        script = Script.new(name, "companion roll", COMPANION_STATUS, [plain(held[:taskdef])])
+        run_script(script, held, {}).merge(planned: { value: false })
       end
 
       private
 
-      # A dry run's answer: the plan, and nothing run.
-      def planned_answer(plan)
-        { outcome: { value: "planned" }, report: { value: "#{plan}\ndry run: nothing was run" }, planned: { value: true } }
-      end
-
-      def require_confirm(held, what, plan)
-        return if plain(held[:confirm]) == true
-
-        raise ConsoleCapture::Failure,
-              "refusing to #{what}: #{plan}\npass confirm=true to run it (dry_run=true prints this plan)"
-      end
-
-      def diff_files(old, new)
-        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})")
-      end
-
-      # The script reads the registry and the local image; its report says what it found.
-      def diff_script(held)
-        text = run_script(DIFF_SCRIPT, held, {}, "bluebook diff", {}).dig(:report, :value)
-        return diff_answer("unavailable", text) if text.match?(DIFF_UNAVAILABLE)
-
-        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.")
-      end
-
-      def diff_answer(outcome, text) = { outcome: { value: outcome }, report: { value: text } }
-
-      # What a data copy's answer hands on to the policies that follow it.
-      def copy_answer(held, report, planned:)
-        carried = %i[project bastion source source_secret target target_secret source_db target_db]
-                  .to_h { |key| [key, { value: plain(held[key]).to_s }] }
-        verify = !planned && plain(held[:skip_verify]) != true
-        carried.merge(report: { value: report }, planned: { value: planned }, run_verify: { value: verify })
-      end
-
-      # A database name the record gave, or nil when it left the script's default.
-      def database(argument) = plain(argument).to_s.empty? ? nil : plain(argument)
-
-      def copy_args(held) = %i[bastion source source_secret target target_secret].map { |key| plain(held[key]) }
-
-      def copy_env(held)
-        { "FORCE" => flag(held[:force]), "SRC_DB" => database(held[:source_db]), "DST_DB" => database(held[:target_db]),
-          "VERIFY_BY_COMMAND" => "1" }.compact
-      end
-
-      # What the script would overwrite, read from the script itself (its schemas and databases).
-      def copy_plan(script, held)
-        text = File.read(script)
-        schemas = text[/^SCHEMAS="([^"]*)"/, 1].to_s.split.join(", ")
-        databases = text.match(/^SRC_DB=\$\{SRC_DB:-([^}]*)\}; DST_DB=\$\{DST_DB:-([^}]*)\}/)
-        source_db = database(held[:source_db]) || databases&.[](1)
-        target_db = database(held[:target_db]) || databases&.[](2)
-        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 " \
-          "#{target_db} on #{plain(held[:target])} through bastion #{plain(held[:bastion])}, " \
-          "OVERWRITING those schemas there#{drop}"
-      end
-
-      # What a roll's answer hands on to the policies that follow it: the project to find the smoke
-      # in, whether to request the smoke (not when the record opted out or the project has no smoke
-      # script, either of which is noted on the record), and which roll asked.
-      def carried(held, kind)
-        skipped = plain(held[:skip_smoke]) == true
-        script = smoke_script?(plain(held[:project]))
-        note = "smoke skipped: skip_smoke=true" if skipped
-        note ||= "smoke skipped: no smoke script" unless script
-        { project: { value: plain(held[:project]) }, skip_smoke: { value: skipped },
-          run_smoke: { value: note.nil? }, smoke: wrapped(note), kind: { value: kind } }
-      end
-
-      # Whether the project has a generated smoke script the smoke could run.
-      def smoke_script?(project)
-        script_for(SMOKE_SCRIPT, project, nil)
-        true
-      rescue ConsoleCapture::Failure
-        false
-      end
-
-      def wrapped(text) = text.to_s.empty? ? nil : { value: text }
-
-      # What `deploy-box.sh` takes: a task definition, or `name=tag` words.
-      def box_args(held) = [plain(held[:taskdef]), *plain(held[:tags]).to_s.split].compact
-
-      # Runs one generated script, found for the record's project, from its own directory. Answers
-      # what it printed, or refuses with its status, that status's meaning and its output.
-      def run_script(name, held, env, label, statuses, args: [], answering: [])
-        script = script_for(name, plain(held[:project]), plain(held[:script]))
-        result = Shell.new.capture("bash", script, *args, env: env, chdir: File.dirname(script))
-        report = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
-        return { report: { value: report } } if result.ok?
-
-        code = result.status.exitstatus
-        return { report: { value: report }, status: code } if answering.include?(code)
-
-        raise ConsoleCapture::Failure, "#{label} ended #{code} (#{statuses.fetch(code, 'unexpected')})\n#{report}"
-      end
-
-      # The script a project runs: the override, else the named one in the project itself, else the
-      # only one beneath it (not under `node_modules`, `vendor` or `.git`).
-      def script_for(name, project, override)
-        return existing_script(override) if override
-
-        root = File.expand_path(project.to_s)
-        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)/})
-        return found.first if found.one?
-
-        raise ConsoleCapture::Failure, ambiguity(name, root, found.sort)
-      end
-
-      def ambiguity(name, root, found)
-        return "no #{name} under #{root}; generate the AwsBox recipe or pass script=<path>" if found.empty?
-
-        "#{found.size} #{name} files under #{root}; pass script=<path>: #{found.join(', ')}"
-      end
-
-      def existing_script(path)
-        script = File.expand_path(path.to_s)
-        File.file?(script) ? script : raise(ConsoleCapture::Failure, "no such script: #{script}")
-      end
-
-      # The variables the generated script reads, set only when the record asks for them.
-      def smoke_env(held)
-        { "TASKDEF" => plain(held[:taskdef]), "SKIP_POST_DEPLOY_SMOKE" => flag(held[:skip]),
-          "SMOKE_ASYNC" => flag(held[:async]), "DRY_RUN" => flag(held[:dry_run]) }.compact
-      end
-
-      def flag(argument) = plain(argument) == true ? "1" : nil
-
-      def child(ask, argv)
-        tree = Codebase::Tree.new
-        tree.require_checkout!
-        run(tree, ask, argv)
-      end
-
-      def run(tree, ask, argv)
-        result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(ask), *argv)
-        raise ConsoleCapture::Failure, message_of(result) unless result.ok?
-
-        { output: { value: result.out } }
-      end
-
       # A project path the tool can read from `root`: relative to it when it lies beneath it, so a
       # recipe made in a checkout names `examples/pizzas`, else absolute.
       def project_path(path, root)
@@ -468,11 +255,6 @@ module Hecks
         absolute.start_with?("#{root}/") ? absolute.delete_prefix("#{root}/") : absolute
       end
 
-      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
-      end
-
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end

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

@@ -47,7 +47,7 @@ module Hecks
         return said("no kind or severity to label") if labels.empty?
 
         gh("issue", "edit", issue(held), "--add-label", labels.join(","))
-        said("labelled #{labels.join(', ')}")
+        said("labelled #{labels.join(", ")}")
       end
 
       # Comments on the issue with the pull request that fixes the finding.
@@ -82,7 +82,7 @@ module Hecks
 
       def gh(*arguments)
         out, err, status = Open3.capture3("gh", *arguments, "--repo", repository)
-        raise "gh #{arguments.first(2).join(' ')} failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        raise "gh #{arguments.first(2).join(" ")} failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
 
         out
       end

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

@@ -34,7 +34,7 @@ module Hecks
       #   @return [Boolean] whether the person had to be admitted first
       Result = Struct.new(:email, :role, :admitted, keyword_init: true) do
         # @return [String] the sentence the verb answers with
-        def to_s = "Granted #{role} access to #{email}#{' (admitted first)' if admitted}"
+        def to_s = "Granted #{role} access to #{email}#{" (admitted first)" if admitted}"
       end
 
       # @param runtime [Hecks::Runtime] the booted domain
@@ -52,13 +52,10 @@ module Hecks
       # @raise [Runtime::NotFound] when the domain has no membership chapter, 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.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+        raise Runtime::NotFound, "#{email.inspect} is not an email address" unless email?(email)
 
         provider = membership_provider
-        verbs    = verbs_of(provider)
-        gate     = gated_role(provider, verbs.fetch(:grant))
-        people   = rows(verbs.fetch(:people))
-        refuse_if_administered!(people, [gate, *OWNER_ROLES].uniq)
+        verbs, gate, people = check_unadministered(provider)
 
         admitted = people.none? { |person| person.dig(:email, :value) == email }
         admit(provider, verbs.fetch(:admit), email, name || email[/\A[^@]+/]) if admitted
@@ -68,6 +65,18 @@ module Hecks
 
       private
 
+      def email?(email) = email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+
+      # The membership verbs, the role the grant is gated to and the people held, once no
+      # administrator is found among them.
+      def check_unadministered(provider)
+        verbs  = verbs_of(provider)
+        gate   = gated_role(provider, verbs.fetch(:grant))
+        people = rows(verbs.fetch(:people))
+        refuse_if_administered!(people, [gate, *OWNER_ROLES].uniq)
+        [verbs, gate, people]
+      end
+
       def membership_provider
         domain = @registry.bluebooks.values.first&.name
         @registry.membership_provider_for(domain) or
@@ -83,11 +92,16 @@ module Hecks
       # The role a verb's command declares, which the dispatch must assert to be let through.
       def gated_role(provider, verb)
         aggregate, command = verb.split("::").last.split(".")
-        found = provider.aggregates.find { |candidate| candidate.hecks_name == aggregate }
-                        &.commands&.find { |candidate| candidate.hecks_name == command }
+        found = declared_command(provider, aggregate, command)
         found&.role&.to_s or raise Runtime::NotFound, "#{verb} declares no role to bootstrap as"
       end
 
+      # The command the provider's aggregate declares, or nil when either is not declared.
+      def declared_command(provider, aggregate, command)
+        holder = provider.aggregates.find { |candidate| candidate.hecks_name == aggregate }
+        holder&.commands&.find { |candidate| candidate.hecks_name == command }
+      end
+
       def refuse_if_administered!(people, roles)
         held = people.select { |person| roles.map(&:downcase).include?(person.dig(:role, :value).to_s.downcase) }
         return if held.empty?

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

@@ -3,6 +3,7 @@
 require "stringio"
 require_relative "shell"
 require_relative "console_capture"
+require_relative "git_refs"
 require_relative "codebase/publishing"
 require "hecks/vendoring/git_environment"
 require "hecks/embryonaut_bluebook/vendor_cli"
@@ -15,6 +16,8 @@ module Hecks
     # or a parent process cannot redirect it to another repository. Subprocesses start through the
     # `Shell` adapter.
     class Git
+      include GitRefs
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -50,14 +53,24 @@ module Hecks
         root = plain(held[:root]) || Dir.pwd
         require_repository!(from)
 
-        argv = [plain(held[:package])]
-        argv += ["--from", from] if from
+        { report: { value: vendored(held[:package], from, root) } }
+      end
+
+      # What the vendor command printed, once it ended well.
+      def vendored(package, from, root)
         out = StringIO.new
         err = StringIO.new
-        status = EmbryonautBluebook::VendorCli.run(argv + ["--root", root], out: out, err: err, root: root)
+        status = EmbryonautBluebook::VendorCli.run(vendor_argv(package, from, root), out: out, err: err, root: root)
         raise ConsoleCapture::Failure, err.string.strip unless status.zero?
 
-        { report: { value: out.string } }
+        out.string
+      end
+
+      # The words the vendor command takes: the package, where from when named, and the project.
+      def vendor_argv(package, from, root)
+        argv = [plain(package)]
+        argv += ["--from", from] if from
+        argv + ["--root", root]
       end
 
       # Checks a project's vendored packages against their `bluebook.lock` files and describes
@@ -162,7 +175,7 @@ module Hecks
         places = [File.join(name, "bluebook"), File.join("vendor", "embryonaut_bluebooks", name, "bluebook")]
         found = places.map { |place| File.join(root, place) }.find { |dir| File.directory?(dir) }
         found or raise Runtime::NotFound,
-                       "#{name} has no bluebook/ directory in #{root} (looked in #{places.join(' and ')})"
+                       "#{name} has no bluebook/ directory in #{root} (looked in #{places.join(" and ")})"
       end
 
       def registry(held)

data/lib/hecks/hecks/adapters/git_refs.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The ref calls of the `Git` adapter: where a ref stands on the remote, whether one commit
+    # contains another, and moving a branch or a tag forward.
+    #
+    # It is mixed into `Git`, which supplies `capture`. Every name that reaches a command is
+    # checked first, and a push is never forced except for a tag the ancestry test has already
+    # allowed to move.
+    module GitRefs
+      # A branch or tag name, or a commit, as git accepts one in a refspec: no space, no option, no
+      # colon, and no `..`, so a name cannot smuggle a second ref or a flag into a command.
+      REF_PATTERN = %r{\A[0-9A-Za-z_][0-9A-Za-z_./-]*\z}
+
+      # Where a ref points on the remote, after fetching it.
+      #
+      # @param ref [String] a branch name, `refs/heads/<name>` or `refs/tags/<name>`
+      # @param remote [String] the remote to ask
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [String, nil] the commit the ref names, or nil when the remote has no such ref
+      # @raise [ConsoleCapture::Failure] when the ref is malformed or the remote cannot be reached
+      def remote_head(ref, remote: "origin", chdir: nil)
+        name = checked_ref(ref)
+        listed = capture("ls-remote", remote, name, chdir: chdir)
+        refuse("git ls-remote #{remote} #{name} failed", listed) unless listed.ok?
+
+        listed.out.lines.map { |line| line.split.first }.first
+      end
+
+      # Whether one commit is an ancestor of another, so that moving a ref from the first to the
+      # second is a fast-forward. A commit is its own ancestor.
+      #
+      # @param ancestor [String] a commit
+      # @param descendant [String] a commit
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Boolean] whether `descendant` contains `ancestor`
+      # @raise [ConsoleCapture::Failure] when git cannot tell (an unknown commit, a malformed name)
+      def ancestor?(ancestor, descendant, chdir: nil)
+        result = capture("merge-base", "--is-ancestor", checked_ref(ancestor), checked_ref(descendant), chdir: chdir)
+        return true if result.ok?
+        return false if result.status.exitstatus == 1
+
+        refuse("git merge-base failed", result)
+      end
+
+      # When the oldest commit of a range was made: the commits `newer` has that `older` lacks.
+      #
+      # Only the first-parent chain counts, so a branch merged long after it was written is dated by
+      # the merge that brought it in, not by its oldest commit: the age asked about is how long the
+      # lane has been waiting for something to land, not how long ago anyone typed it.
+      #
+      # @param older [String, nil] a commit, branch or ref, or nil for every commit of `newer`
+      # @param newer [String] a commit, branch or ref
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Integer, nil] the oldest such commit's time, in seconds since the epoch, or nil
+      #   when `newer` holds nothing `older` lacks
+      # @raise [ConsoleCapture::Failure] when git cannot read the range
+      def oldest_commit_time(older, newer, chdir: nil)
+        range = older ? "#{checked_ref(older)}..#{checked_ref(newer)}" : checked_ref(newer)
+        listed = capture("log", "--first-parent", "--reverse", "--format=%ct", range, chdir: chdir)
+        refuse("git log #{range} failed", listed) unless listed.ok?
+
+        listed.out.lines.first&.to_i
+      end
+
+      # The commits a lane may be moved onto, newest first: the first-parent chain of `newer` that
+      # `older` does not already contain.
+      #
+      # @param newer [String] the commit or ref the chain starts from
+      # @param older [String, nil] the commit the lane stands on, nil when it does not exist yet
+      # @param limit [Integer] how many commits to name at most
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Array<String>] full commit ids, newest first
+      # @raise [ConsoleCapture::Failure] when git cannot read the range
+      def recent_commits(newer, older: nil, limit: 25, chdir: nil)
+        range = older ? "#{checked_ref(older)}..#{checked_ref(newer)}" : checked_ref(newer)
+        listed = capture("rev-list", "--first-parent", "-n", Integer(limit).to_s, range, chdir: chdir)
+        refuse("git rev-list #{range} failed", listed) unless listed.ok?
+
+        listed.out.split
+      end
+
+      # Moves a remote branch to a commit, and only forward: the push is refused by the remote when
+      # the commit does not contain the branch's head, and is never forced.
+      #
+      # @param commit [String] the commit to push
+      # @param branch [String] the branch to move
+      # @param remote [String] the remote to push to
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [void]
+      # @raise [ConsoleCapture::Failure] when the remote refuses (not a fast-forward, a ruleset)
+      def fast_forward(commit, branch, remote: "origin", chdir: nil)
+        pushed = capture("push", remote, "#{checked_ref(commit)}:refs/heads/#{checked_ref(branch)}", chdir: chdir)
+        refuse("git push #{remote} #{branch} was refused", pushed) unless pushed.ok?
+      end
+
+      # Moves a tag to a commit on the remote, and only forward: a tag that points at a commit the
+      # new one does not contain is left where it is. A tag that does not yet exist is made.
+      #
+      # @param tag [String] the tag to move
+      # @param commit [String] the commit it should name
+      # @param remote [String] the remote to push to
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Symbol] `:created`, `:moved` or `:current`
+      # @raise [ConsoleCapture::Failure] when the tag stands on a commit that is not an ancestor of
+      #   `commit`, or the remote refuses
+      def move_tag(tag, commit, remote: "origin", chdir: nil)
+        name = checked_ref(tag)
+        sha = checked_ref(commit)
+        standing = remote_head("refs/tags/#{name}", remote: remote, chdir: chdir)
+        return :current if standing == sha
+
+        refuse_rewind(name, standing, sha) if standing && !ancestor?(standing, sha, chdir: chdir)
+        force_tag(name, sha, remote, chdir)
+        standing ? :moved : :created
+      end
+
+      private
+
+      def force_tag(name, sha, remote, chdir)
+        pushed = capture("push", "--force", remote, "#{sha}:refs/tags/#{name}", chdir: chdir)
+        refuse("git push #{remote} #{name} was refused", pushed) unless pushed.ok?
+      end
+
+      def refuse_rewind(name, standing, sha)
+        raise ConsoleCapture::Failure, "#{name} stands on #{standing[0, 7]}, which #{sha[0, 7]} does not contain"
+      end
+
+      def refuse(what, result)
+        raise ConsoleCapture::Failure, "#{what}: #{result.err.strip}"
+      end
+
+      def checked_ref(ref)
+        name = ref.to_s
+        return name if name.match?(REF_PATTERN) && !name.include?("..")
+
+        raise ConsoleCapture::Failure, "#{name.inspect} is not a ref name git can be given safely"
+      end
+    end
+  end
+end