kettle-dev 1.0.10 → 1.0.12

data/exe/kettle-changelog

@@ -0,0 +1,404 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vim: set syntax=ruby
+
+# kettle-changelog: Generate a CHANGELOG.md entry for the current VERSION.
+# - Reads VERSION from lib/**/version.rb (must be unique across files)
+# - Moves entries from the "Unreleased" section into a new versioned section
+# - Prepends 4 heading lines:
+#   - TAG
+#   - COVERAGE (line coverage)
+#   - BRANCH COVERAGE (branch coverage)
+#   - percent documented (parsed from `bin/yard` output)
+# - Updates bottom link references to GitHub style, converts any existing
+#   GitLab links to GitHub links, and appends the new [X.Y.Z] and [X.Y.Zt] links.
+#
+# Notes:
+# - Expects a JSON coverage report at coverage/coverage.json. If missing,
+#   it will instruct you to run: K_SOUP_COV_FORMATTERS="json" bin/rspec
+# - Expects bin/yard to be available via Bundler.
+
+$stdout.sync = true
+
+# Depending library or project must be using bundler
+require "bundler/setup"
+
+require "json"
+require "time"
+require "open3"
+require "shellwords"
+
+begin
+  require "kettle/dev"
+rescue LoadError => e
+  warn("kettle/dev: failed to load: #{e.message}")
+  warn("Hint: Ensure the host project includes kettle-dev and run bundle install.")
+  exit(1)
+end
+
+require "kettle/dev/versioning"
+
+puts "== kettle-changelog v#{Kettle::Dev::Version::VERSION} =="
+
+module Kettle
+  module Dev
+    class ChangelogCLI
+      def initialize
+        @root = Kettle::Dev::CIHelpers.project_root
+        @changelog_path = File.join(@root, "CHANGELOG.md")
+        @coverage_path = File.join(@root, "coverage", "coverage.json")
+      end
+
+      def run
+        version = Kettle::Dev::Versioning.detect_version(@root)
+        today = Time.now.strftime("%Y-%m-%d")
+        owner, repo = Kettle::Dev::CIHelpers.repo_info
+        unless owner && repo
+          warn("Could not determine GitHub owner/repo from origin remote.")
+          warn("Make sure 'origin' points to github.com. Alternatively, set origin or update links manually afterward.")
+        end
+
+        line_cov_line, branch_cov_line = coverage_lines
+        yard_line = yard_percent_documented
+
+        changelog = File.read(@changelog_path)
+
+        # If the detected version already exists in the changelog, abort to avoid duplicates
+        if changelog =~ /^## \[#{Regexp.escape(version)}\]/
+          abort("CHANGELOG.md already has a section for version #{version}. Bump version.rb or remove the duplicate.")
+        end
+
+        unreleased_block, before, after = extract_unreleased(changelog)
+        if unreleased_block.nil?
+          abort("Could not find '## [Unreleased]' section in CHANGELOG.md")
+        end
+
+        if unreleased_block.strip.empty?
+          warn("No entries found under Unreleased. Creating an empty version section anyway.")
+        end
+
+        prev_version = detect_previous_version(after)
+
+        new_section = +""
+        new_section << "## [#{version}] - #{today}\n"
+        new_section << "- TAG: [v#{version}][#{version}t]\n"
+        new_section << "- #{line_cov_line}\n" if line_cov_line
+        new_section << "- #{branch_cov_line}\n" if branch_cov_line
+        new_section << "- #{yard_line}\n" if yard_line
+        new_section << filter_unreleased_sections(unreleased_block)
+        # Ensure exactly one blank line separates this new section from the next section
+        new_section.rstrip!
+        new_section << "\n\n"
+
+        # Reset the Unreleased section to empty category headings
+        unreleased_reset = <<~MD
+          ## [Unreleased]
+          ### Added
+          ### Changed
+          ### Deprecated
+          ### Removed
+          ### Fixed
+          ### Security
+        MD
+
+        updated = before + unreleased_reset + "\n" + new_section + after
+
+        updated = update_link_refs(updated, owner, repo, prev_version, version)
+
+        # Ensure exactly one trailing newline at EOF
+        updated = updated.rstrip + "\n"
+
+        File.write(@changelog_path, updated)
+        puts "CHANGELOG.md updated with v#{version} section."
+      end
+
+      private
+
+      def abort(msg)
+        Kettle::Dev::ExitAdapter.abort(msg)
+      rescue NameError
+        Kernel.abort(msg)
+      end
+
+      def detect_version
+        candidates = Dir[File.join(@root, "lib", "**", "version.rb")]
+        abort("Could not find version.rb under lib/**.") if candidates.empty?
+        versions = candidates.map do |path|
+          content = File.read(path)
+          m = content.match(/VERSION\s*=\s*(["'])([^"']+)\1/)
+          next unless m
+          m[2]
+        end.compact
+        abort("VERSION constant not found in #{@root}/lib/**/version.rb") if versions.none?
+        abort("Multiple VERSION constants found to be out of sync (#{versions.inspect}) in #{@root}/lib/**/version.rb") unless versions.uniq.length == 1
+        versions.first
+      end
+
+      def extract_unreleased(content)
+        lines = content.lines
+        start_i = lines.index { |l| l.start_with?("## [Unreleased]") }
+        return [nil, nil, nil] unless start_i
+        # Find the next version heading after Unreleased
+        next_i = (start_i + 1)
+        while next_i < lines.length && !lines[next_i].start_with?("## [")
+          next_i += 1
+        end
+        # Now next_i points to the next section heading or EOF
+        before = lines[0..(start_i - 1)].join
+        unreleased_block = lines[(start_i + 1)..(next_i - 1)].join
+        after = lines[next_i..-1]&.join || ""
+        [unreleased_block, before, after]
+      end
+
+      def detect_previous_version(after_text)
+        # after_text begins with the first released section following Unreleased
+        m = after_text.match(/^## \[(\d+\.\d+\.\d+)\]/)
+        return m[1] if m
+        nil
+      end
+
+      # From the Unreleased block, keep only sections that have content.
+      # We detect sections as lines starting with '### '. A section has content if there is at least
+      # one non-empty, non-heading line under it before the next '###' or '##'. Typically these are list items.
+      # Returns a string that includes only the non-empty sections with their content.
+      def filter_unreleased_sections(unreleased_block)
+        lines = unreleased_block.lines
+        out = []
+        i = 0
+        while i < lines.length
+          line = lines[i]
+          if line.start_with?("### ")
+            header = line
+            i += 1
+            chunk = []
+            while i < lines.length && !lines[i].start_with?("### ") && !lines[i].start_with?("## ")
+              chunk << lines[i]
+              i += 1
+            end
+            # Determine if chunk has any content (non-blank)
+            content_present = chunk.any? { |l| l.strip != "" }
+            if content_present
+              # Trim trailing blank lines
+              while chunk.any? && chunk.last.strip == ""
+                chunk.pop
+              end
+              out << header
+              out.concat(chunk)
+              out << "\n" unless out.last&.end_with?("\n")
+            end
+            next
+          else
+            # Lines outside sections are ignored for released sections
+            i += 1
+          end
+        end
+        out.join
+      end
+
+      def coverage_lines
+        unless File.file?(@coverage_path)
+          warn("Coverage JSON not found at #{@coverage_path}.")
+          warn("Run: K_SOUP_COV_FORMATTERS=\"json\" bin/rspec")
+          return [nil, nil]
+        end
+        data = JSON.parse(File.read(@coverage_path))
+        files = data["coverage"] || {}
+        file_count = 0
+        total_lines = 0
+        covered_lines = 0
+        total_branches = 0
+        covered_branches = 0
+        files.each_value do |h|
+          lines = h["lines"] || []
+          line_relevant = lines.count { |x| x.is_a?(Integer) }
+          line_covered = lines.count { |x| x.is_a?(Integer) && x > 0 }
+          if line_relevant > 0
+            file_count += 1
+            total_lines += line_relevant
+            covered_lines += line_covered
+          end
+          branches = h["branches"] || []
+          branches.each do |b|
+            next unless b.is_a?(Hash)
+            cov = b["coverage"]
+            next unless cov.is_a?(Numeric)
+            total_branches += 1
+            covered_branches += 1 if cov > 0
+          end
+        end
+        line_pct = (total_lines > 0) ? ((covered_lines.to_f / total_lines) * 100.0) : 0.0
+        branch_pct = (total_branches > 0) ? ((covered_branches.to_f / total_branches) * 100.0) : 0.0
+        line_str = format("COVERAGE: %.2f%% -- %d/%d lines in %d files", line_pct, covered_lines, total_lines, file_count)
+        branch_str = format("BRANCH COVERAGE: %.2f%% -- %d/%d branches in %d files", branch_pct, covered_branches, total_branches, file_count)
+        [line_str, branch_str]
+      rescue StandardError => e
+        warn("Failed to parse coverage: #{e.class}: #{e.message}")
+        [nil, nil]
+      end
+
+      def yard_percent_documented
+        cmd = File.join(@root, "bin", "yard")
+        unless File.executable?(cmd)
+          warn("bin/yard not found or not executable; ensure yard is installed via bundler")
+          return
+        end
+        out, _ = Open3.capture2(cmd)
+        # Look for a line containing e.g., "95.35% documented"
+        line = out.lines.find { |l| l =~ /\d+(?:\.\d+)?%\s+documented/ }
+        if line
+          line = line.strip
+          # Return exactly as requested: e.g. "95.35% documented"
+          line
+        else
+          warn("Could not find documented percentage in bin/yard output.")
+          nil
+        end
+      rescue StandardError => e
+        warn("Failed to run bin/yard: #{e.class}: #{e.message}")
+        nil
+      end
+
+      def update_link_refs(content, owner, repo, prev_version, new_version)
+        # Convert any GitLab links to GitHub
+        content = content.gsub(%r{https://gitlab\.com/([^/]+)/([^/]+)/-/compare/([^\.]+)\.\.\.([^\s]+)}) do
+          o = owner || Regexp.last_match(1)
+          r = repo || Regexp.last_match(2)
+          from = Regexp.last_match(3)
+          to = Regexp.last_match(4)
+          "https://github.com/#{o}/#{r}/compare/#{from}...#{to}"
+        end
+        content = content.gsub(%r{https://gitlab\.com/([^/]+)/([^/]+)/-/tags/(v[^\s\]]+)}) do
+          o = owner || Regexp.last_match(1)
+          r = repo || Regexp.last_match(2)
+          tag = Regexp.last_match(3)
+          "https://github.com/#{o}/#{r}/releases/tag/#{tag}"
+        end
+
+        # Append or update the bottom reference links
+        lines = content.lines
+
+        # Find the index of the Unreleased heading; only manipulate refs after this point
+        unreleased_idx = lines.index { |l| l.start_with?("## [Unreleased]") } || -1
+
+        # Find the first link-ref line (e.g., "[Unreleased]: http...") AFTER Unreleased
+        first_ref = nil
+        lines.each_with_index do |l, i|
+          if l =~ /^\[[^\]]+\]:\s+http/ && i > unreleased_idx
+            first_ref = i
+            break
+          end
+        end
+        unless first_ref
+          # Append at end if no ref block after Unreleased
+          first_ref = lines.length
+          lines << "\n"
+        end
+
+        # Ensure Unreleased points to GitHub compare from new tag to HEAD
+        if owner && repo
+          unreleased_ref = "[Unreleased]: https://github.com/#{owner}/#{repo}/compare/v#{new_version}...HEAD\n"
+          # Update an existing Unreleased ref only if it appears after Unreleased heading; otherwise append
+          idx = nil
+          lines.each_with_index do |l, i|
+            if l.start_with?("[Unreleased]:") && i >= first_ref
+              idx = i
+              break
+            end
+          end
+          if idx
+            lines[idx] = unreleased_ref
+          else
+            lines << unreleased_ref
+          end
+        end
+
+        if owner && repo
+          # Add compare link for the new version
+          from = prev_version ? "v#{prev_version}" : detect_initial_compare_base(lines)
+          new_compare = "[#{new_version}]: https://github.com/#{owner}/#{repo}/compare/#{from}...v#{new_version}\n"
+          unless lines.any? { |l| l.start_with?("[#{new_version}]:") }
+            lines << new_compare
+          end
+          # Add tag link for the new version
+          new_tag = "[#{new_version}t]: https://github.com/#{owner}/#{repo}/releases/tag/v#{new_version}\n"
+          unless lines.any? { |l| l.start_with?("[#{new_version}t]:") }
+            lines << new_tag
+          end
+        end
+
+        # Rebuild and sort the reference block so newest is at the bottom, preserving everything above first_ref
+        ref_lines = lines[first_ref..-1].select { |l| l =~ /^\[[^\]]+\]:\s+http/ }
+        # Deduplicate by key (text inside the square brackets)
+        by_key = {}
+        ref_lines.each do |l|
+          if l =~ /^\[([^\]]+)\]:\s+/
+            by_key[$1] = l
+          end
+        end
+        unreleased_line = by_key.delete("Unreleased")
+        # Separate version compare and tag links
+        compares = {}
+        tags = {}
+        by_key.each do |k, v|
+          if k =~ /^(\d+\.\d+\.\d+)$/
+            compares[$1] = v
+          elsif k =~ /^(\d+\.\d+\.\d+)t$/
+            tags[$1] = v
+          end
+        end
+        # Sort versions ascending so newest at bottom
+        sorted_versions = compares.keys.map { |s| Gem::Version.new(s) }.sort.map(&:to_s)
+        # In case some versions only have tags or only compares, include them as well
+        (tags.keys - compares.keys).each { |s| sorted_versions |= [s] }
+        sorted_versions = sorted_versions.map { |s| Gem::Version.new(s) }.sort.map(&:to_s)
+
+        new_ref_block = []
+        new_ref_block << unreleased_line if unreleased_line
+        sorted_versions.each do |v|
+          new_ref_block << compares[v] if compares[v]
+          new_ref_block << tags[v] if tags[v]
+        end
+        # Replace the old block
+        rebuilt = lines[0...first_ref] + new_ref_block + ["\n"]
+        rebuilt.join
+      end
+
+      def detect_initial_compare_base(lines)
+        # Fallback when prev_version is unknown: try to find the first compare base used historically
+        # e.g., for 1.0.0 it may be a commit SHA instead of a tag
+        ref = lines.find { |l| l =~ /^\[1\.0\.0\]:\s+https:\/\/github\.com\// }
+        if ref && (m = ref.match(%r{compare/([^\.]+)\.\.\.v\d+})).is_a?(MatchData)
+          m[1]
+        else
+          # Default to previous tag name if none found (unlikely to be correct, but better than empty)
+          "HEAD^"
+        end
+      end
+    end
+  end
+end
+
+begin
+  if ARGV.include?("-h") || ARGV.include?("--help")
+    puts <<~USAGE
+      Usage: kettle-changelog
+
+      Generates a new CHANGELOG.md entry for the current version detected from lib/**/version.rb.
+      Moves entries from [Unreleased] into the new section, adds coverage and documentation stats,
+      and updates bottom link references to GitHub style, adding new compare/tag links.
+
+      Prerequisites:
+        - coverage/coverage.json present (run: K_SOUP_COV_FORMATTERS="json" bin/rspec)
+        - yard installed and available via bin/yard
+    USAGE
+    exit(0)
+  end
+  Kettle::Dev::ChangelogCLI.new.run
+rescue SystemExit
+  raise
+rescue StandardError => e
+  warn("kettle-changelog: unexpected error: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n")) if ENV["DEBUG"]
+  exit(1)
+end

data/exe/kettle-commit-msg

@@ -13,6 +13,8 @@ require "erb"
 
 require "kettle/dev"
 
+puts "== kettle-commit-msg v#{Kettle::Dev::Version::VERSION} =="
+
 # ENV variable control (set in .envrc, or .env.local)
 # BRANCH_RULE_TYPE = jira, or another type of branch rule validation, or false to disable
 # FOOTER_APPEND = true/false append commit message footer

data/exe/kettle-readme-backers

@@ -10,4 +10,6 @@ require "bundler/setup"
 
 require "kettle/dev"
 
+puts "== kettle-readme-backers v#{Kettle::Dev::Version::VERSION} =="
+
 Kettle::Dev::ReadmeBackers.new.run!

data/exe/kettle-release

@@ -19,21 +19,18 @@ $stdout.sync = true
 # Depending library or project must be using bundler
 require "bundler/setup"
 
-begin
-  require "kettle/dev"
-rescue LoadError => e
-  warn("kettle/dev: failed to load: #{e.message}")
-  warn("Hint: Ensure the host project includes kettle-dev and run bundle install.")
-  exit(1)
-end
+require "kettle/dev"
 
 # Always execute when this file is loaded (e.g., via a Bundler binstub).
 # Do not guard with __FILE__ == $PROGRAM_NAME because binstubs use Kernel.load.
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
-    Usage: kettle-release
+    Usage: kettle-release [start_step=<number>]
 
     Automates the release flow for a Ruby gem in the host project:
+
+    Options:
+      start_step=<number>         # skip directly to the numbered step (e.g., 10 for CI validation)
       - Runs bin/setup and bin/rake sanity checks
       - Prompts to confirm version and changelog updates
       - Commits a release prep change
@@ -51,8 +48,12 @@ if ARGV.include?("-h") || ARGV.include?("--help")
   exit 0
 end
 
+puts "== kettle-release v#{Kettle::Dev::Version::VERSION} =="
+# Parse start_step=<n> from ARGV
+start_step_arg = ARGV.find { |a| a.start_with?("start_step=") }
+start_step = start_step_arg ? start_step_arg.split("=", 2)[1].to_i : 1
 begin
-  Kettle::Dev::ReleaseCLI.new.run
+  Kettle::Dev::ReleaseCLI.new(start_step: start_step).run
 rescue LoadError => e
   warn("kettle-release: could not load dependency: #{e.message}")
   warn(e.backtrace.join("\n")) if ENV["DEBUG"]

data/gemfiles/modular/optional.gemfile

@@ -0,0 +1 @@
+# Optional dependencies are not dependended on directly, but may be used if present.

data/lib/kettle/dev/ci_helpers.rb

@@ -177,10 +177,29 @@ module Kettle
         data = JSON.parse(res.body)
         pipe = data&.first
         return unless pipe
+        # Attempt to enrich with failure_reason by querying the single pipeline endpoint
+        begin
+          if pipe["id"]
+            detail_uri = URI("https://#{host}/api/v4/projects/#{project}/pipelines/#{pipe["id"]}")
+            dreq = Net::HTTP::Get.new(detail_uri)
+            dreq["User-Agent"] = "kettle-dev/ci-helpers"
+            dreq["PRIVATE-TOKEN"] = token if token && !token.empty?
+            dres = Net::HTTP.start(detail_uri.hostname, detail_uri.port, use_ssl: true) { |http| http.request(dreq) }
+            if dres.is_a?(Net::HTTPSuccess)
+              det = JSON.parse(dres.body)
+              pipe["failure_reason"] = det["failure_reason"] if det.is_a?(Hash)
+              pipe["status"] = det["status"] if det["status"]
+              pipe["web_url"] = det["web_url"] if det["web_url"]
+            end
+          end
+        rescue StandardError
+          # ignore enrichment errors; fall back to basic fields
+        end
         {
           "status" => pipe["status"],
           "web_url" => pipe["web_url"],
           "id" => pipe["id"],
+          "failure_reason" => pipe["failure_reason"],
         }
       rescue StandardError
         nil

data/lib/kettle/dev/ci_monitor.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+# External stdlib
+require "uri"
+require "json"
+require "net/http"
+
+# Internal
+require "kettle/dev/ci_helpers"
+require "kettle/dev/exit_adapter"
+require "kettle/dev/git_adapter"
+
+module Kettle
+  module Dev
+    # CIMonitor centralizes CI monitoring logic (GitHub Actions and GitLab pipelines)
+    # so it can be reused by both kettle-release and Rake tasks (e.g., ci:act).
+    #
+    # Public API is intentionally small and based on environment/project introspection
+    # via CIHelpers, matching the behavior historically implemented in ReleaseCLI.
+    module CIMonitor
+      module_function
+
+      # Abort helper (delegates through ExitAdapter so specs can trap exits)
+      def abort(msg)
+        Kettle::Dev::ExitAdapter.abort(msg)
+      end
+      module_function :abort
+
+      # Monitor both GitHub and GitLab CI for the current project/branch.
+      # This mirrors ReleaseCLI behavior.
+      #
+      # @param restart_hint [String] guidance command shown on failure
+      # @return [void]
+      def monitor_all!(restart_hint: "bundle exec kettle-release start_step=10")
+        checks_any = false
+        checks_any |= monitor_github_internal!(restart_hint: restart_hint)
+        checks_any |= monitor_gitlab_internal!(restart_hint: restart_hint)
+        abort("CI configuration not detected (GitHub or GitLab). Ensure CI is configured and remotes point to the correct hosts.") unless checks_any
+      end
+
+      # Monitor only the GitLab pipeline for current project/branch.
+      # Used by ci:act after running 'act'.
+      #
+      # @param restart_hint [String] guidance command shown on failure
+      # @return [Boolean] true if check performed (gitlab configured), false otherwise
+      def monitor_gitlab!(restart_hint: "bundle exec rake ci:act")
+        monitor_gitlab_internal!(restart_hint: restart_hint)
+      end
+
+      # -- internals --
+
+      def monitor_github_internal!(restart_hint:)
+        root = Kettle::Dev::CIHelpers.project_root
+        workflows = Kettle::Dev::CIHelpers.workflows_list(root)
+        gh_remote = preferred_github_remote
+        return false unless gh_remote && !workflows.empty?
+
+        branch = Kettle::Dev::CIHelpers.current_branch
+        abort("Could not determine current branch for CI checks.") unless branch
+
+        url = remote_url(gh_remote)
+        owner, repo = parse_github_owner_repo(url)
+        return false unless owner && repo
+
+        total = workflows.size
+        abort("No GitHub workflows found under .github/workflows; aborting.") if total.zero?
+
+        passed = {}
+        puts "Ensuring GitHub Actions workflows pass on #{branch} (#{owner}/#{repo}) via remote '#{gh_remote}'"
+        pbar = if defined?(ProgressBar)
+          ProgressBar.create(title: "CI", total: total, format: "%t %b %c/%C", length: 30)
+        end
+        idx = 0
+        loop do
+          wf = workflows[idx]
+          run = Kettle::Dev::CIHelpers.latest_run(owner: owner, repo: repo, workflow_file: wf, branch: branch)
+          if run
+            if Kettle::Dev::CIHelpers.success?(run)
+              unless passed[wf]
+                passed[wf] = true
+                pbar&.increment
+              end
+            elsif Kettle::Dev::CIHelpers.failed?(run)
+              puts
+              wf_url = run["html_url"] || "https://github.com/#{owner}/#{repo}/actions/workflows/#{wf}"
+              abort("Workflow failed: #{wf} -> #{wf_url} Fix the workflow, then restart this tool from CI validation with: #{restart_hint}")
+            end
+          end
+          break if passed.size == total
+          idx = (idx + 1) % total
+          sleep(1)
+        end
+        pbar&.finish unless pbar&.finished?
+        puts "\nAll GitHub workflows passing (#{passed.size}/#{total})."
+        true
+      end
+      module_function :monitor_github_internal!
+
+      def monitor_gitlab_internal!(restart_hint:)
+        root = Kettle::Dev::CIHelpers.project_root
+        gitlab_ci = File.exist?(File.join(root, ".gitlab-ci.yml"))
+        gl_remote = gitlab_remote_candidates.first
+        return false unless gitlab_ci && gl_remote
+
+        branch = Kettle::Dev::CIHelpers.current_branch
+        abort("Could not determine current branch for CI checks.") unless branch
+
+        owner, repo = Kettle::Dev::CIHelpers.repo_info_gitlab
+        return false unless owner && repo
+
+        puts "Ensuring GitLab pipeline passes on #{branch} (#{owner}/#{repo}) via remote '#{gl_remote}'"
+        pbar = if defined?(ProgressBar)
+          ProgressBar.create(title: "CI", total: 1, format: "%t %b %c/%C", length: 30)
+        end
+        loop do
+          pipe = Kettle::Dev::CIHelpers.gitlab_latest_pipeline(owner: owner, repo: repo, branch: branch)
+          if pipe
+            if Kettle::Dev::CIHelpers.gitlab_success?(pipe)
+              pbar&.increment unless pbar&.finished?
+              break
+            elsif Kettle::Dev::CIHelpers.gitlab_failed?(pipe)
+              # Special-case: if failure is due to exhausted minutes/insufficient quota, treat as unknown and continue
+              reason = (pipe["failure_reason"] || "").to_s
+              if reason =~ /insufficient|quota|minute/i
+                puts "\nGitLab reports pipeline cannot run due to quota/minutes exhaustion. Result is unknown; continuing."
+                pbar&.finish unless pbar&.finished?
+                break
+              else
+                puts
+                url = pipe["web_url"] || "https://gitlab.com/#{owner}/#{repo}/-/pipelines"
+                abort("Pipeline failed: #{url} Fix the pipeline, then restart this tool from CI validation with: #{restart_hint}")
+              end
+            elsif pipe["status"] == "blocked"
+              # Blocked pipeline (e.g., awaiting approvals) — treat as unknown and continue
+              puts "\nGitLab pipeline is blocked. Result is unknown; continuing."
+              pbar&.finish unless pbar&.finished?
+              break
+            end
+          end
+          sleep(1)
+        end
+        pbar&.finish unless pbar&.finished?
+        puts "\nGitLab pipeline passing."
+        true
+      end
+      module_function :monitor_gitlab_internal!
+
+      # -- tiny wrappers around GitAdapter-like helpers used by ReleaseCLI --
+      def remotes_with_urls
+        Kettle::Dev::GitAdapter.new.remotes_with_urls
+      end
+      module_function :remotes_with_urls
+
+      def remote_url(name)
+        Kettle::Dev::GitAdapter.new.remote_url(name)
+      end
+      module_function :remote_url
+
+      def github_remote_candidates
+        remotes_with_urls.select { |n, u| u.include?("github.com") }.keys
+      end
+      module_function :github_remote_candidates
+
+      def gitlab_remote_candidates
+        remotes_with_urls.select { |n, u| u.include?("gitlab.com") }.keys
+      end
+      module_function :gitlab_remote_candidates
+
+      def preferred_github_remote
+        cands = github_remote_candidates
+        return if cands.empty?
+        explicit = cands.find { |n| n == "github" } || cands.find { |n| n == "gh" }
+        return explicit if explicit
+        return "origin" if cands.include?("origin")
+        cands.first
+      end
+      module_function :preferred_github_remote
+
+      def parse_github_owner_repo(url)
+        return [nil, nil] unless url
+        if url =~ %r{git@github.com:(.+?)/(.+?)(\.git)?$}
+          [Regexp.last_match(1), Regexp.last_match(2).sub(/\.git\z/, "")]
+        elsif url =~ %r{https://github.com/(.+?)/(.+?)(\.git)?$}
+          [Regexp.last_match(1), Regexp.last_match(2).sub(/\.git\z/, "")]
+        else
+          [nil, nil]
+        end
+      end
+      module_function :parse_github_owner_repo
+    end
+  end
+end