ruby-repo-kit 0.1.0

data/lib/ruby_repo_kit/release/artifact.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "digest"
+require "rubygems/package"
+
+module RubyRepoKit
+  module Release
+    # Records and checks existing bytes; publication never builds another gem.
+    class Artifact
+      def initialize(project:)
+        @project = project
+        @metadata = Metadata.new(project: project)
+      end
+
+      def path = @project.path("pkg/#{@project.name}-#{@metadata.version}.gem")
+
+      def record
+        artifact = path
+        digest = Digest::SHA256.file(artifact).hexdigest
+        text = File.read(@project.path(@project.changelog))
+        section = text.include?("## [#{@metadata.version}]") ? @metadata.version : "Unreleased"
+        File.write(@project.path("pkg/SHA256SUMS"), "#{digest}  #{File.basename(artifact)}\n")
+        File.write(@project.path("pkg/release-notes.md"), "#{@metadata.notes(text, section).strip}\n")
+        artifact
+      end
+
+      def verify(expected: ENV.fetch("RELEASE_SHA256", nil))
+        artifact = path
+        digest = Digest::SHA256.file(artifact).hexdigest
+        manifest = File.read(@project.path("pkg/SHA256SUMS"))
+        unless manifest == "#{digest}  #{File.basename(artifact)}\n" && (expected.nil? || expected == digest)
+          raise Error, "Release artifact checksum mismatch"
+        end
+
+        package = Gem::Package.new(artifact)
+        package.verify
+        unless package.spec.name == @project.name && package.spec.version.to_s == @metadata.version
+          raise Error, "Release artifact name/version does not match the checkout"
+        end
+
+        artifact
+      rescue Gem::Package::Error, SystemCallError => e
+        raise Error, "Cannot verify release artifact: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_repo_kit/release/metadata.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "date"
+require "rubygems/version"
+
+module RubyRepoKit
+  module Release
+    # Parses repository-owned metadata without loading the consumer's Ruby code.
+    class Metadata
+      VERSION_PATTERN = /\A(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\z/
+      VERSION_LINE = /^([ \t]*VERSION[ \t]*=[ \t]*)(["'])([^"'\r\n]+)\2((?:\.freeze)?[ \t]*(?:#.*)?)\r?$/
+      HEADING = /\A## \[([^\]]+)\] - (\d{4}-\d{2}-\d{2})( \[YANKED\])?\z/
+      Heading = Data.define(:version, :date, :yanked)
+
+      def initialize(project:, clock: SystemClock, commands: nil)
+        @project = project
+        @clock = clock
+        @commands = commands || Commands.new(project: project)
+      end
+
+      def version = version_from(File.read(@project.path(@project.version_file)))
+
+      def version_from(source)
+        version_match(source)[3].tap { |value| validate_version(value) }
+      end
+
+      def validate_version(target)
+        raise Error, "Use a stable X.Y.Z version" unless target.is_a?(String) && VERSION_PATTERN.match?(target)
+
+        target
+      end
+
+      def validate_branch(branch, target)
+        validate_version(target)
+        hotfix = "hotfix/#{target.split('.').first(2).join('.')}"
+        raise Error, "Release branch must be main or #{hotfix}" unless ["main", hotfix].include?(branch)
+
+        branch
+      end
+
+      def verify(tag:, version: self.version, changelog: nil)
+        validate_version(version)
+        text = changelog || File.read(@project.path(@project.changelog))
+        history = validate_history(text)
+        # A branch rehearsal checks the release we would prepare, without writing it.
+        if tag.nil? && history.none? { |heading| heading.version == version }
+          changes(version,
+                  source: { @project.version_file => "VERSION = \"#{version}\"\n", @project.changelog => text })
+          return version
+        end
+        raise Error, "Release tag must be v#{version}" unless tag.nil? || tag == "v#{version}"
+        raise Error, "The newest changelog release must be #{version}" unless history.first&.version == version
+        raise Error, "Cannot publish a yanked release" if history.first.yanked
+        raise Error, "Release notes for #{version} are empty" unless notes(text, version).match?(/^[-*] \S/)
+
+        check_reference(text, "Unreleased", "#{@project.url}/compare/v#{version}...HEAD")
+        version
+      end
+
+      def verify_ref(sha: ENV.fetch("GITHUB_SHA"), version: self.version)
+        validate_version(version)
+        raise Error, "Invalid release commit" unless sha.is_a?(String) && sha.match?(/\A[0-9a-f]{40}\z/)
+
+        refs = @commands.call(["git", "for-each-ref", "--contains", sha, "--format=%(refname:short)",
+                               "refs/remotes/origin"])
+        allowed = ["origin/main", "origin/hotfix/#{version.split('.').first(2).join('.')}"]
+        return true if refs.lines.map(&:strip).intersect?(allowed)
+
+        raise Error, "Release commit must belong to main or its matching hotfix branch"
+      end
+
+      def notes(changelog, target)
+        heading = /^## \[#{Regexp.escape(target)}\][^\n]*\n/
+        return "" unless changelog.match?(heading)
+
+        changelog.split(heading, 2).last.to_s.split(/^## |^\[[^\]]+\]:/, 2).first.to_s
+      end
+
+      def changes(target, source: nil, date: nil)
+        validate_version(target)
+        source ||= [@project.version_file, @project.changelog].to_h { |path| [path, File.read(@project.path(path))] }
+        original = source.fetch(@project.version_file)
+        current = version_from(original)
+        raise Error, "Version cannot go backwards" if Gem::Version.new(target) < Gem::Version.new(current)
+
+        text = source.fetch(@project.changelog)
+        history = validate_history(text)
+        raise Error, "Version already appears in the changelog" if history.any? { |heading| heading.version == target }
+        raise Error, "Add release notes under Unreleased first" unless notes(text, "Unreleased").match?(/^[-*] \S/)
+
+        release_date = date || @clock.now.utc.to_date
+        updated = text.sub("## [Unreleased]\n", "## [Unreleased]\n\n## [#{target}] - #{release_date.iso8601}\n")
+        link = "[Unreleased]: #{@project.url}/compare/v#{target}...HEAD"
+        updated = updated.sub(/^\[Unreleased\]:[^\n]*$/, link)
+        updated = "#{updated.rstrip}\n[#{target}]: #{@project.url}/releases/tag/v#{target}\n"
+        verify(tag: "v#{target}", version: target, changelog: updated)
+        match = version_match(original)
+        replacement = "#{match[1]}#{match[2]}#{target}#{match[2]}#{match[4]}"
+        { @project.version_file => original.sub(VERSION_LINE) { replacement }, @project.changelog => updated }
+      end
+
+      private
+
+      def version_match(source)
+        assignments = source.scan(/^[ \t]*VERSION[ \t]*=/)
+        matches = source.to_enum(:scan, VERSION_LINE).map { Regexp.last_match }
+        unless assignments.length == 1 && matches.length == 1
+          raise Error, "#{@project.version_file} must contain exactly one static VERSION string assignment"
+        end
+
+        matches.first
+      end
+
+      def validate_history(text)
+        sections = text.lines.map(&:chomp).grep(/^## /)
+        unless sections.first == "## [Unreleased]" && sections.count("## [Unreleased]") == 1
+          raise Error, "Expected one Unreleased section before the release history"
+        end
+
+        history = sections.drop(1).map { |line| parse_heading(line) }
+        versions = history.map(&:version)
+        raise Error, "Duplicate changelog release" unless versions.uniq == versions
+
+        history.each_cons(2) do |newer, older|
+          unless Gem::Version.new(newer.version) > Gem::Version.new(older.version) && newer.date >= older.date
+            raise Error, "Changelog releases must be newest first by version and date"
+          end
+        end
+        history.each do |heading|
+          check_reference(text, heading.version, "#{@project.url}/releases/tag/v#{heading.version}")
+        end
+        references = text.lines.grep(/^\[Unreleased\]:/)
+        raise Error, "Expected one Unreleased link reference" unless references.length == 1
+
+        history
+      end
+
+      def parse_heading(line)
+        match = HEADING.match(line)
+        raise Error, "Invalid changelog release heading: #{line}" unless match
+
+        validate_version(match[1])
+        date = Date.iso8601(match[2])
+        raise Error, "Release date cannot be in the future" if date > @clock.now.utc.to_date
+
+        Heading.new(match[1], date, !match[3].nil?)
+      rescue Date::Error
+        raise Error, "Invalid changelog release date"
+      end
+
+      def check_reference(text, name, url)
+        lines = text.lines.map(&:chomp).grep(/^\[#{Regexp.escape(name)}\]:/)
+        raise Error, "Missing or incorrect release link for #{name}" unless lines == ["[#{name}]: #{url}"]
+      end
+    end
+  end
+end

data/lib/ruby_repo_kit/release/preparation.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RubyRepoKit
+  module Release
+    # Owns local edits and recovery; the workflow owns remote PR and tag transitions.
+    class Preparation
+      def initialize(project:, commands:, metadata:, clock: SystemClock)
+        @project = project
+        @commands = commands
+        @metadata = metadata
+        @clock = clock
+      end
+
+      def resume(version, dry_run: false)
+        dirty = owned_changes(version)
+        source = [@project.version_file, @project.changelog].to_h do |path|
+          [path, @commands.call(["git", "show", "HEAD:#{path}"])]
+        end
+        if source.fetch(@project.changelog).include?("## [#{version}]")
+          raise Error, "Commit or stash unrelated work before continuing" unless dirty.empty?
+
+          @metadata.verify(tag: "v#{version}", version: @metadata.version_from(source.fetch(@project.version_file)),
+                           changelog: source.fetch(@project.changelog))
+          @commands.call(@project.check_command, stream: true) unless dry_run
+          return
+        end
+
+        pending_changes(version, source)
+      end
+
+      def run(changes, version:)
+        targets = changes.to_h { |path, content| [@project.path(path), content] }
+        targets.each { |path, content| File.write(path, content) }
+        @commands.call(%w[bundle lock --local])
+        @commands.call(@project.generate_command, stream: true)
+        @commands.call(@project.check_command, stream: true)
+        owned_changes(version)
+        @commands.call(["git", "add", "--", *@project.release_files])
+        @commands.call(["git", "commit", "-S", "-m", "chore: release v#{version}"])
+        @commands.call(%w[git log -1 --format=full])
+      end
+
+      private
+
+      def pending_changes(version, source)
+        text = File.read(@project.path(@project.changelog))
+        dated = text[/^## \[#{Regexp.escape(version)}\] - (\d{4}-\d{2}-\d{2})$/, 1]
+        date = dated ? Date.iso8601(dated) : @clock.now.utc.to_date
+        changes = @metadata.changes(version, source: source, date: date)
+        changes.each do |path, content|
+          actual = File.read(@project.path(path))
+          next if [source.fetch(path), content].include?(actual)
+
+          raise Error, "#{path} has edits beyond release preparation; review them before retrying"
+        end
+        changes
+      rescue Date::Error
+        raise Error, "Invalid date in partially prepared release"
+      end
+
+      def owned_changes(version)
+        entries = @commands.call(%w[git status --porcelain -z]).split("\0")
+        paths = []
+        until entries.empty?
+          entry = entries.shift
+          paths << entry[3..]
+          paths << entries.shift if entry[0, 2].match?(/[RC]/)
+        end
+        unless paths.all? { |path| owned_path?(path) }
+          raise Error, "Unrelated changes on release/v#{version}; commit or stash them first"
+        end
+
+        paths.each { |path| @project.path(path) }
+      end
+
+      def owned_path?(path)
+        path && @project.release_files.any? { |owned| path == owned || path.start_with?("#{owned}/") }
+      end
+    end
+  end
+end

data/lib/ruby_repo_kit/release/publication.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RubyRepoKit
+  module Release
+    # Remote tags are observation-only on retries; an accepted gem cannot be republished.
+    class Publication
+      def initialize(version, project:, commands:, clock: SystemClock, out: $stdout, branch: "main")
+        @version = version
+        @project = project
+        @commands = commands
+        @clock = clock
+        @out = out
+        @metadata = Metadata.new(project: project, commands: commands, clock: clock)
+        @base = @metadata.validate_branch(branch, version)
+      end
+
+      def tag = "v#{@version}"
+
+      def remote_tag
+        @commands.call(["git", "ls-remote", "--tags", "origin", "refs/tags/#{tag}",
+                        "refs/tags/#{tag}^{}"]).lines.to_h do |line|
+          sha, ref = line.split
+          [ref, sha]
+        end
+      end
+
+      def run(sha, push:, dry_run: false)
+        verify_commit(sha)
+        remote = remote_tag
+        if remote.any? && remote["refs/tags/#{tag}^{}"] != sha
+          raise Error, "Remote #{tag} targets another commit; it will never be moved"
+        end
+
+        exists = !@commands.call(["git", "tag", "--list", tag]).strip.empty?
+        verify_tag(sha) if exists
+        if dry_run || (!push && remote.empty?)
+          next_step = exists ? "push the signed tag" : "sign and push its tag"
+          @out.puts "Release merge #{sha} is ready. Run #{resume_command} --push to #{next_step}."
+          return
+        end
+        if remote.empty?
+          @commands.call(["git", "tag", "-s", tag, "-m", "Release #{@version}", sha]) unless exists
+          verify_tag(sha)
+          @commands.call(["git", "push", "origin", tag], stream: true)
+        end
+        watch_release(sha)
+      end
+
+      def verify_commit(sha)
+        raise Error, "GitHub did not return a valid release merge commit" unless sha&.match?(/\A[0-9a-f]{40}\z/)
+
+        @commands.call(["git", "merge-base", "--is-ancestor", sha, "origin/#{@base}"])
+        verify_metadata(sha)
+      end
+
+      def verify_metadata(sha)
+        source = @commands.call(["git", "show", "#{sha}:#{@project.version_file}"])
+        version = @metadata.version_from(source)
+        changelog = @commands.call(["git", "show", "#{sha}:#{@project.changelog}"])
+        @metadata.verify(tag: tag, version: version, changelog: changelog)
+      end
+
+      private
+
+      def resume_command
+        "bundle exec ruby-repo-kit release #{@version}#{" --branch #{@base}" unless @base == 'main'}"
+      end
+
+      def verify_tag(sha)
+        unless @commands.call(["git", "cat-file", "-t", "refs/tags/#{tag}"]).strip == "tag" &&
+               @commands.call(["git", "rev-parse", "#{tag}^{commit}"]).strip == sha
+          raise Error, "Local #{tag} is not an annotated tag of the release merge; it will never be replaced"
+        end
+
+        @commands.call(["git", "verify-tag", tag])
+      end
+
+      def watch_release(sha)
+        run = find_run(sha)
+        unless run
+          raise Error, "#{tag} is already on GitHub. No Release run appeared; inspect Actions before dispatching it. " \
+                       "The tag was not changed."
+        end
+
+        id = run.fetch("databaseId").to_s
+        manual = run["event"] == "workflow_dispatch"
+        unless run["status"] == "completed"
+          @commands.call(["gh", "run", "watch", id], stream: true)
+          run = @commands.json(["gh", "run", "view", id, "--json", "status,conclusion"])
+        end
+        raise Error, failed_run_message(id) unless run["conclusion"] == "success"
+
+        if manual && !published_run?(id)
+          raise Error, "Manual run #{id} was successful, but publication was not confirmed. " \
+                       "A dry run is not a release. Inspect gh run view #{id} --repo #{@project.repository}; " \
+                       "no publication was retried."
+        end
+
+        @out.puts "Released #{tag}; the existing successful run is #{id}."
+      end
+
+      def find_run(sha)
+        60.times do
+          runs = @commands.json(["gh", "run", "list", "--workflow", @project.workflow,
+                                 "--branch", tag, "--limit", "20", "--json",
+                                 "databaseId,headSha,status,conclusion,event"])
+          matching = runs.select { |candidate| candidate["headSha"] == sha }
+          manual = matching.select { |candidate| candidate["event"] == "workflow_dispatch" }
+          recovered = manual.find do |candidate|
+            candidate["conclusion"] == "success" && published_run?(candidate.fetch("databaseId").to_s)
+          end
+          run = recovered || matching.find { |candidate| candidate["event"] == "push" } || manual.first
+          return run if run
+
+          @clock.sleep(5)
+        end
+        nil
+      end
+
+      def published_run?(id)
+        jobs = @commands.json(["gh", "run", "view", id, "--json", "jobs"]).fetch("jobs")
+        %w[publish github-release].all? do |name|
+          jobs.any? { |job| job["name"] == name && job["conclusion"] == "success" }
+        end
+      end
+
+      def failed_run_message(id)
+        jobs = @commands.json(["gh", "run", "view", id, "--json", "jobs"]).fetch("jobs")
+        publication = jobs.find { |job| job["name"] == "publish" }
+        github_release = jobs.find { |job| job["name"] == "github-release" }
+        prefix = "#{tag} is already on GitHub. Release run #{id} did not complete publication; " \
+                 "no publication was retried."
+        if publication && publication["conclusion"] == "success" && github_release
+          "#{prefix}\nRubyGems publication succeeded. Retry only GitHub release creation:\n" \
+            "gh run rerun #{id} --job #{github_release.fetch('databaseId')} --repo #{@project.repository}"
+        elsif publication.nil? || publication["conclusion"] == "skipped"
+          "#{prefix}\nPublication did not run. Fix the failed checks, then: " \
+            "gh run rerun #{id} --failed --repo #{@project.repository}"
+        else
+          "#{prefix}\nInspect gh run view #{id} --log-failed --repo #{@project.repository}. " \
+            "Check whether RubyGems accepted #{@version} before retrying any publish job."
+        end
+      end
+    end
+  end
+end

data/lib/ruby_repo_kit/release/publisher.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyRepoKit
+  module Release
+    class Publisher
+      def initialize(project:, commands: nil)
+        @project = project
+        @commands = commands || Commands.new(project: project)
+      end
+
+      def publish(expected: ENV.fetch("RELEASE_SHA256", nil), environment: ENV)
+        metadata = Metadata.new(project: @project)
+        version = metadata.version
+        unless environment["GITHUB_ACTIONS"] == "true" && environment["GITHUB_REPOSITORY"] == @project.repository &&
+               environment["GITHUB_REF"] == "refs/tags/v#{version}"
+          raise Error, "Publication runs only in this project's tagged GitHub Actions release workflow"
+        end
+        raise Error, "Publication requires the verified RELEASE_SHA256" unless expected&.match?(/\A[0-9a-f]{64}\z/)
+
+        metadata.verify(tag: "v#{version}")
+        artifact = Artifact.new(project: @project).verify(expected: expected)
+        @commands.call(["gem", "push", "--host", "https://rubygems.org", artifact], stream: true)
+        artifact
+      end
+    end
+  end
+end

data/lib/ruby_repo_kit/release/workflow.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module RubyRepoKit
+  module Release
+    class Workflow
+      def initialize(version, project:, commands: nil, configuration: nil, clock: SystemClock,
+                     out: $stdout, push: false, dry_run: false, branch: "main")
+        raise Error, "--push and --dry-run cannot be combined" if push && dry_run
+
+        @version = version
+        @project = project
+        @push = push
+        @dry_run = dry_run
+        @out = out
+        @clock = clock
+        @commands = commands || Commands.new(project: project, out: out)
+        @metadata = Metadata.new(project: project, commands: @commands, clock: clock)
+        @base = @metadata.validate_branch(branch, version)
+        @preparation = Preparation.new(project: project, commands: @commands, metadata: @metadata, clock: clock)
+        @configuration = configuration
+        @publication = Publication.new(version, project: project, commands: @commands, out: out, clock: clock,
+                                                branch: @base)
+      end
+
+      def run
+        validate
+        request = find_pull_request
+        if request&.fetch("state") == "MERGED"
+          require_clean
+          @publication.run(request.dig("mergeCommit", "oid"), push: @push, dry_run: @dry_run)
+        elsif @publication.remote_tag.any?
+          raise Error, "#{tag} already exists without a matching merged release PR; inspect it before continuing"
+        elsif request
+          resume_pull_request(request)
+        else
+          prepare_pull_request
+        end
+      rescue Error => e
+        raise Error, "#{e.message}\nAfter resolving the problem, rerun #{resume_command}#{' --push' if @push}. " \
+                     "Existing pull requests and tags are inspected before any new action."
+      end
+
+      private
+
+      def tag = "v#{@version}"
+      def branch = "release/#{tag}"
+
+      def resume_command
+        "bundle exec ruby-repo-kit release #{@version}#{" --branch #{@base}" unless @base == 'main'}"
+      end
+
+      def command(...) = @commands.call(...)
+
+      def configuration
+        return @configuration if @configuration
+
+        require_relative "../github"
+        @configuration = GitHub::Configuration.new(project: @project)
+      end
+
+      def validate
+        origin = command(%w[git remote get-url origin]).strip
+        repository = Regexp.escape(@project.repository)
+        unless origin.match?(%r{\A(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)#{repository}(?:\.git)?\z})
+          raise Error, "The origin repository must be #{@project.repository}"
+        end
+
+        configuration.verify!
+        command(%w[git fetch origin --tags])
+        @current_branch = command(%w[git branch --show-current]).strip
+        raise Error, "Run from #{@base} or #{branch}" unless [@base, branch].include?(@current_branch)
+      end
+
+      def find_pull_request
+        requests = @commands.json(["gh", "pr", "list", "--state", "all", "--base", @base, "--head", branch,
+                                   "--json", "url,state,headRefOid,mergeCommit,isCrossRepository"])
+        if requests.any? { |request| request["isCrossRepository"] != false }
+          raise Error, "Release pull requests must originate in #{@project.repository}, not a fork"
+        end
+        raise Error, "Several pull requests use #{branch}; reconcile them before releasing" if requests.length > 1
+
+        requests.first
+      end
+
+      def require_clean
+        raise Error, "Commit or stash unrelated work before continuing" unless command(%w[git status --porcelain
+                                                                                          -z]).empty?
+      end
+
+      def resume_pull_request(request)
+        require_clean
+        unless request["state"] == "OPEN"
+          raise Error,
+                "The release PR was closed without merging; reopen it before retrying"
+        end
+
+        @commit = request.fetch("headRefOid")
+        raise Error, "GitHub did not return a valid release PR head" unless @commit&.match?(/\A[0-9a-f]{40}\z/)
+        if @current_branch == branch && command(%w[git rev-parse HEAD]).strip != @commit
+          raise Error, "Local #{branch} differs from the PR head. Push its reviewed changes before retrying"
+        end
+
+        if @dry_run
+          verify_pull_request
+          return @out.puts "Existing release PR: #{request.fetch('url')} (dry run)."
+        end
+
+        finish_pull_request(request.fetch("url"))
+      end
+
+      def prepare_pull_request
+        if @current_branch == @base
+          require_clean
+          unless command(%w[git rev-parse HEAD]) == command(["git", "rev-parse", "origin/#{@base}"])
+            raise Error, "Local #{@base} must match origin/#{@base}; pull first"
+          end
+
+          changes = @metadata.changes(@version)
+          if @dry_run
+            return @out.puts changes.fetch(@project.changelog),
+                             "Dry run: no working files or GitHub state changed."
+          end
+
+          command(["git", "switch", "-c", branch])
+        else
+          changes = @preparation.resume(@version, dry_run: @dry_run)
+          if @dry_run
+            return @out.puts "Would resume preparation on #{branch}; no working files or GitHub state changed."
+          end
+        end
+        @preparation.run(changes, version: @version) if changes
+        @commit = command(%w[git rev-parse HEAD]).strip
+        command(%w[git verify-commit HEAD])
+        command(["git", "push", "-u", "origin", branch], stream: true)
+        finish_pull_request(open_pull_request)
+      end
+
+      def open_pull_request
+        Tempfile.create(["#{@project.name}-release", ".md"]) do |body|
+          body.write("Release #{@project.name} #{@version}. The signed tag will target the merge commit.\n\n" \
+                     "Validation: `#{@project.check_command.join(' ')}`. Release notes are in #{@project.changelog}.\n")
+          body.flush
+          command(["gh", "pr", "create", "--base", @base, "--head", branch, "--title", "chore: release #{tag}",
+                   "--body-file", body.path]).strip
+        end
+      end
+
+      def finish_pull_request(url)
+        verify_pull_request
+        return @out.puts "Release PR: #{url}. Run #{resume_command} --push to merge, sign and publish." unless @push
+
+        wait_for_checks(url)
+        command(["gh", "pr", "checks", url, "--watch", "--fail-fast", "--interval", "10"], stream: true)
+        command(["gh", "pr", "merge", url, "--merge", "--delete-branch", "--match-head-commit", @commit])
+        sha = command(["gh", "pr", "view", url, "--json", "mergeCommit", "--jq", ".mergeCommit.oid"]).strip
+        raise Error, "GitHub did not return a valid release merge commit" unless sha.match?(/\A[0-9a-f]{40}\z/)
+
+        command(%w[git fetch origin --tags])
+        command(["git", "merge-base", "--is-ancestor", @commit, sha])
+        @publication.run(sha, push: true)
+      end
+
+      def verify_pull_request
+        @publication.verify_metadata(@commit)
+        command(["git", "verify-commit", @commit])
+      end
+
+      def wait_for_checks(url)
+        60.times do
+          count = command(["gh", "pr", "view", url, "--json", "statusCheckRollup", "--jq",
+                           ".statusCheckRollup | length"])
+          return if count.to_i.positive?
+
+          @clock.sleep(5)
+        end
+        raise Error, "Timed out waiting for checks on #{url}; the existing PR will be reused on retry"
+      end
+    end
+  end
+end

data/lib/ruby_repo_kit/release.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Adapted from Slipway and Rich-RI (MIT, Copyright 2026 Highlander Paiva).
+require_relative "../ruby_repo_kit"
+
+module RubyRepoKit
+  module Release
+    module SystemClock
+      def self.now = Time.now
+      def self.sleep(seconds) = Kernel.sleep(seconds)
+    end
+  end
+end
+
+require_relative "release/metadata"
+require_relative "release/artifact"
+require_relative "release/publication"
+require_relative "release/preparation"
+require_relative "release/workflow"
+require_relative "release/publisher"