kettle-dev 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41074cb0fabc348cfb17e29cfb521661c4492792a7c5e3fab1ff32815f960355
-  data.tar.gz: d65ce417666381f6cf72ac7f6cdcd6bea0be35c996c820d16765789229408bc9
+  metadata.gz: e8a1375214aa3c53580a46da791cc0813ab2303a56bf08d32c3928bb6773425a
+  data.tar.gz: 293ad0c152819ca21f1bf9a63cbf4f21078cff641d680ce7b955608c309d5d24
 SHA512:
-  metadata.gz: 100dc6197c4a9329d3ae4e483feb7e3c643160a9a446939c7a3d6bb789a0ca8ba6c41f8231971548b4ba91916e55481469d17b6623998046a1cc302bf96e7825
-  data.tar.gz: cd82a9b3ad27598611f94798fa1187171092017cbf8d28b44ff5fd3c82ed021251ba35053683276ac8dc49a77c33035ec02f3c379a42d79fbabd749d25221bba
+  metadata.gz: 24dce616ec2536f3f3afd7dc6b16cffe9442aa7d81f86a25dcc2867166a10c55cc6e1285ea1e91261f4f176fc309435cd8240dca7e8eaf94bbff6efdaa0ea4c2
+  data.tar.gz: b4fe9b7736463c18bb8e97f2c91d55257c281502b6ccfb40e51e698b5616141dac2c48d6513262b97ee810fcec1e267c31908a0d02bfbe606d21427a0684cd0e

data/CHANGELOG.md

@@ -30,6 +30,70 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.2.0] - 2026-06-08
+
+- TAG: [v2.2.0][2.2.0t]
+- COVERAGE: 91.51% -- 3710/4054 lines in 28 files
+- BRANCH COVERAGE: 72.90% -- 1458/2000 branches in 28 files
+- 67.51% documented
+
+### Added
+
+- `kettle-pre-release` now runs `kettle-gha-sha-pins --check` before release
+  checks, failing with an outdated-actions summary and recommended
+  `kettle-gha-sha-pins --write --upgrade patch` command when workflow actions
+  need updated SHA pins.
+- `kettle-release` now runs `kettle-pre-release` as a full-release gate before
+  release setup starts.
+- `kettle-bump` now bumps a single gem's version file before `kettle-changelog`
+  release prep.
+- `kettle-gha-sha-pins` now shows discovery, workflow scan, and action-resolution
+  progress on STDERR for human runs while keeping JSON output quiet by default.
+- `kettle-gha-sha-pins` now times action resolution, caches one resolution plan
+  per action repository, and uses GitHub REST tag-ref lookups to avoid resolving
+  every release tag through individual commit requests.
+
+- `kettle-gha-sha-pins` now keeps a 24-hour persistent action release cache at
+  the XDG state location and supports `--refresh-cache` to bypass stale entries
+  while preserving cached discoveries for other projects and actions.
+
+### Fixed
+
+- Minitest-only projects now keep `rake test` on the generated
+  `Rake::TestTask` path instead of synthesizing a `kettle-test` RSpec task when
+  tests live directly under `test/`.
+
+- `kettle-release start_step=10` now waits for GitHub Actions runs for the
+  local HEAD SHA to appear before evaluating results, avoiding stale failures
+  from the previous branch run.
+- Removed the duplicate `cgi` declaration from the `head` appraisal so
+  `kettle-release` can regenerate Appraisal gemfiles on Ruby 4.
+
+- `kettle-gha-sha-pins` now treats version-equivalent but unresolved action
+  refs as invalid and converts them to release SHAs instead of accepting
+  stripped tag names such as `6.0.2` when only `v6.0.2` exists.
+- `kettle-gha-sha-pins --write` now refreshes adjacent release-version comments
+  when the pinned SHA is current but the comment is stale.
+- `kettle-gha-sha-pins` now uses `GH_TOKEN` or `gh auth token` as a fallback
+  when `GITHUB_TOKEN` is not set, avoiding false clean reports after
+  unauthenticated GitHub API rate limits are exhausted.
+- Coverage workflow uploads now pin `codecov/codecov-action` and
+  `coverallsapp/github-action` to resolvable release SHAs.
+
+- Ruby 2.4-2.6 CI appraisals now include `backports`, and Ruby 3.0-3.1
+  appraisals include `prism`, so `kettle-bump` and GitHub Action SHA pin specs
+  run on the supported legacy matrix.
+
+- Legacy CI appraisals now skip `kettle-bump` specs when Prism is unavailable,
+  and the Ruby 3.2 appraisal includes `prism` so the specs run where supported.
+
+### Changed
+
+- Retemplated project metadata with the latest `kettle-jem` stack, refreshing
+  README and security-policy generated details for the current release line.
+
+- Runtime dependency `kettle-test` now requires 2.0.4 or newer.
+
 ## [2.1.1] - 2026-06-06
 
 - TAG: [v2.1.1][2.1.1t]
@@ -1913,7 +1977,9 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v2.1.1...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/kettle-rb/kettle-dev/compare/v2.1.1...v2.2.0
+[2.2.0t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v2.2.0
 [2.1.1]: https://github.com/kettle-rb/kettle-dev/compare/v2.1.0...v2.1.1
 [2.1.1t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v2.1.1
 [2.1.0]: https://github.com/kettle-rb/kettle-dev/compare/v2.0.8...v2.1.0

data/README.md

@@ -303,6 +303,8 @@ Common local workflows:
 - `bundle exec rake appraisal:generate` regenerates Appraisal gemfiles.
 - `bundle exec rake appraisal:update` updates Appraisal locks and applies gradual RuboCop autocorrect.
 - `bundle exec rake appraisal:reset` removes Appraisal lockfiles below `gemfiles/`.
+- `kettle-bump patch` bumps the current gem's patch version before running
+  `kettle-changelog`.
 
 GitHub Actions local runner helper:
 
@@ -373,6 +375,7 @@ What it does:
 
 - Script: `exe/kettle-release` (run as `kettle-release`)
 - Purpose: guided release helper that:
+    - Runs `kettle-pre-release` before the numbered release steps on full releases, aborting before release setup if any pre-release gate fails.
     - Runs sanity checks (`bin/setup`, `bin/rake`), confirms version/changelog, optionally updates Appraisals, regenerates docs via `bin/rake yard`, commits “🔖 Prepare release vX.Y.Z”.
     - Optionally runs your CI locally with `act` before any push:
         - Enable with env: `K_RELEASE_LOCAL_CI="true"` (run automatically) or `K_RELEASE_LOCAL_CI="ask"` (prompt \[Y/n\]).
@@ -403,12 +406,29 @@ What it does:
         19. Push tags to remotes (final)
 - Examples:
     - After intermittent CI failure, restart from monitoring: `bundle exec kettle-release start_step=10`
+    - After fixing a failed pre-release gate, rerun from the top: `bundle exec kettle-release`
 - Tips:
     - The commit message helper `exe/kettle-commit-msg` prefers project-local `.git-hooks` (then falls back to `~/.git-hooks`).
     - The goalie file `commit-subjects-goalie.txt` controls when a footer is appended; customize `footer-template.erb.txt` as you like.
 
 ### Changelog generator
 
+- Script: `exe/kettle-bump` (run as `kettle-bump`)
+- Purpose: Bumps the current single gem's `lib/**/version.rb` before changelog
+  preparation. It accepts an exact version or `major`, `minor`, or `patch`.
+- Usage:
+    - `kettle-bump patch`
+    - `kettle-bump 1.2.4 --from 1.2.3`
+    - `kettle-bump minor --dry-run`
+    - `kettle-bump patch --check`
+- Behavior:
+    - Writes by default; use `--dry-run` to preview or `--check` to fail when a
+      bump would change files.
+    - Updates literal `spec.version = "..."` assignments in the gemspec when
+      they match the current version. Dynamic gemspec versions are left alone.
+    - Uses the same `K_CHANGELOG_VERSION_FILE` override as `kettle-changelog`
+      when a project needs to point at a specific version file.
+
 - Script: `exe/kettle-changelog` (run as `kettle-changelog`)
 - Purpose: Generates a new CHANGELOG.md section for the current version read from `lib/**/version.rb`, moves notes from the Unreleased section, and updates comparison links.
 - Prerequisites:
@@ -424,6 +444,27 @@ What it does:
 
 ### Pre-release checks
 
+- Script: `exe/kettle-gha-sha-pins` (run as `kettle-gha-sha-pins`)
+- Purpose: Validate and optionally update GitHub Actions `uses:` refs to pinned
+  SHAs and current allowed release versions.
+- Usage:
+    - `kettle-gha-sha-pins`
+    - `kettle-gha-sha-pins --check`
+    - `kettle-gha-sha-pins --write --upgrade patch`
+- Behavior:
+    - Human output shows discovery, workflow scan, and action-resolution progress
+      on STDERR, including per-action timing via `ruby-progressbar`, then prints
+      the final report on STDOUT.
+    - Action metadata is resolved with the GitHub REST API and cached per
+      `owner/repo` action so duplicate uses of the same action reuse one
+      resolution plan.
+    - The outdated summary reports newer releases even when `--upgrade patch` or
+      `--upgrade minor` limits the write target to a safer release line.
+    - JSON output keeps progress disabled by default so STDOUT remains parseable.
+      Use `--progress` to force progress or `--no-progress` to suppress it.
+    - `--check` exits non-zero when workflow action pins are stale or mutable and
+      prints a recommended `kettle-gha-sha-pins --write --upgrade patch` command.
+
 - Script: `exe/kettle-pre-release` (run as `kettle-pre-release`)
 - Purpose: Run a suite of pre-release validations to catch avoidable mistakes (resumable by check number).
 - Usage:
@@ -432,7 +473,9 @@ What it does:
 - Options:
     - `--check-num N` Start from check number N (default: 1)
 - Checks:
-    - 1)  Validate that all image URLs referenced by Markdown files resolve (HTTP HEAD)
+    - 1) Validate GitHub Actions workflow action refs with `kettle-gha-sha-pins --check`; if pins are stale, it prints an outdated-actions summary, exits non-zero, and recommends `kettle-gha-sha-pins --write --upgrade patch`.
+    - 2) Normalize Markdown image URLs.
+    - 3) Validate that all image URLs referenced by Markdown files resolve (HTTP HEAD).
 
 ### Commit message helper (git hook)
 
@@ -811,7 +854,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-3.209-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.054-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-rb/kettle-dev/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
@@ -839,7 +882,7 @@ Thanks for RTFM. ☺️
 | Package | kettle-dev |
 | Description | 🍲 Kettle::Dev is a meta tool from kettle-rb to streamline development and testing. Acts as a shim dependency, pulling in many other dependencies, to give you OOTB productivity with a RubyGem, or Ruby app project. Configures a complete set of Rake tasks, for all the libraries is brings in, so they arrive ready to go. Fund overlooked open source projects - bottom of stack, dev/test dependencies: floss-funding.dev |
 | Homepage | https://github.com/kettle-rb/kettle-dev |
-| Source | https://github.com/kettle-rb/kettle-dev/tree/v2.1.0 |
+| Source | https://github.com/kettle-rb/kettle-dev/tree/v2.2.0 |
 | License | `AGPL-3.0-only` |
 | Funding | https://github.com/sponsors/pboling, https://issuehunt.io/u/pboling, https://ko-fi.com/pboling, https://liberapay.com/pboling/donate, https://opencollective.com/kettle-rb, https://patreon.com/galtzo, https://polar.sh/pboling, https://thanks.dev/u/gh/pboling, https://tidelift.com/funding/github/rubygems/kettle-dev, https://www.buymeacoffee.com/pboling |
 <!-- kettle-jem:metadata:end -->

data/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version  | Supported |
 |----------|-----------|
-| 2.1.latest | ✅         |
+| 2.2.latest | ✅         |
 
 ## Security contact information
 

data/exe/kettle-bump

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vim: set syntax=ruby
+
+# kettle-bump: Bump the current gem version before running kettle-changelog.
+
+$stdout.sync = true
+$stderr.sync = true
+
+begin
+  require "rubygems"
+rescue LoadError
+  # Older Rubies always have rubygems; continue anyway
+end
+
+script_basename = File.basename(__FILE__)
+
+begin
+  require "kettle/dev"
+  puts "== #{script_basename} v#{Kettle::Dev::Version::VERSION} =="
+rescue LoadError => e
+  warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+  warn("Hint: Ensure the host project has kettle-dev as a dependency and run bundle install.")
+  exit(1)
+end
+
+begin
+  exit(Kettle::Dev::BumpCLI.new(ARGV).run!)
+rescue LoadError => e
+  warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n")) if ENV["DEBUG"]
+  exit(1)
+rescue SystemExit => e
+  warn("#{script_basename}: exited (status=#{e.status}, msg=#{e.message})") if e.status != 0
+  raise
+rescue => e
+  warn("#{script_basename}: unexpected error: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n")) if ENV["DEBUG"]
+  exit(1)
+end

data/exe/kettle-gha-sha-pins

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# vim: set syntax=ruby
+
+$stdout.sync = true
+$stderr.sync = true
+
+# Do not rely on Bundler; allow running in repos that do not depend on kettle-dev
+begin
+  require "rubygems"
+rescue LoadError
+  # Older Rubies always have rubygems; continue anyway
+end
+
+script_basename = File.basename(__FILE__)
+
+begin
+  require "kettle/dev"
+rescue LoadError
+  repo_lib = File.expand_path("../lib", __dir__)
+  $LOAD_PATH.unshift(repo_lib) unless $LOAD_PATH.include?(repo_lib)
+  begin
+    require "kettle/dev"
+  rescue LoadError => e
+    warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
+    warn("Hint: Install the kettle-dev gem (`gem install kettle-dev`) or add it to your Gemfile. Bundler is not required for this script.")
+    exit(1)
+  end
+end
+
+begin
+  cli = Kettle::Dev::GhaShaPinsCLI.new(ARGV)
+  status = cli.run!
+  Kettle::Dev::ExitAdapter.exit(status)
+rescue => e
+  warn("#{script_basename}: unexpected error: #{e.class}: #{e.message}")
+  warn(e.backtrace.join("\n"))
+  Kettle::Dev::ExitAdapter.exit(1)
+end

data/exe/kettle-pre-release

@@ -5,7 +5,7 @@
 
 # kettle-pre-release: Run pre-release checks to catch avoidable mistakes.
 # - Structured as a sequence of checks that can be resumed via check_num
-# - Initial check: validate all image URLs referenced by Markdown files resolve (HTTP HEAD)
+# - Checks GitHub Actions SHA pins and validates Markdown image links.
 
 require "optparse"
 
@@ -45,7 +45,9 @@ parser = OptionParser.new do |opts|
     puts opts
     puts
     puts "Checks:"
-    puts "  1) Validate Markdown image links (HTTP HEAD)"
+    puts "  1) Validate GitHub Actions SHA pins"
+    puts "  2) Normalize Markdown image URLs"
+    puts "  3) Validate Markdown image links (HTTP HEAD)"
     exit(0)
   end
 end

data/exe/kettle-release

@@ -47,6 +47,10 @@ if ARGV.include?("-h") || ARGV.include?("--help")
 
     Automates the release flow for a Ruby gem in the host project.
 
+    Full releases run `kettle-pre-release` before step 1 and abort if any
+    pre-release gate fails. Resume with start_step > 1 only after the gate has
+    passed or after intentionally handling the failure.
+
     Start steps (use start_step=<n> to begin at that step):
       1. Verify Bundler >= 2.7 (always runs; start at 1 to do everything)
       2. Detect version; RubyGems sanity check; confirm CHANGELOG/version; sync copyright years; update badges/headers

data/lib/kettle/dev/bump_cli.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Kettle
+  module Dev
+    # CLI for bumping the current project's gem version before changelog prep.
+    class BumpCLI
+      BUMP_TYPES = %w[major minor patch].freeze
+
+      def initialize(argv = [], out: $stdout, err: $stderr, root: Kettle::Dev::CIHelpers.project_root)
+        @argv = argv.dup
+        @out = out
+        @err = err
+        @root = root
+      end
+
+      def run!
+        options = parse_options
+        return 0 if options.fetch(:help)
+
+        current_version = Kettle::Dev::Versioning.detect_version(root)
+        target_version = resolve_target_version(options.fetch(:target), current_version)
+        edits = collect_edits(
+          current_version: current_version,
+          target_version: target_version,
+          from_version: options[:from]
+        )
+        write_edits(edits) if options.fetch(:mode) == :execute
+
+        out.puts(summary(edits: edits, current_version: current_version, target_version: target_version, mode: options.fetch(:mode)))
+        (options.fetch(:mode) == :check && edits.any?) ? 1 : 0
+      end
+
+      private
+
+      attr_reader :argv, :out, :err, :root
+
+      def parse_options
+        options = {mode: :execute, help: false}
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: kettle-bump VERSION|major|minor|patch [options]"
+          opts.on("--from VERSION", "Require the current version before bumping") { |value| options[:from] = validate_version(value) }
+          opts.on("--check", "Exit non-zero when the bump would change files") { options[:mode] = :check }
+          opts.on("--dry-run", "Print planned changes without writing files") { options[:mode] = :dry_run }
+          opts.on("--execute", "Write the bump to disk (default)") { options[:mode] = :execute }
+          opts.on("-h", "--help", "Show this help") do
+            out.puts(opts)
+            options[:help] = true
+          end
+        end
+        parser.parse!(argv)
+        options[:target] = argv.shift
+        raise Kettle::Dev::Error, "kettle-bump requires VERSION, major, minor, or patch" unless options[:target] || options[:help]
+        raise Kettle::Dev::Error, "unexpected arguments: #{argv.join(" ")}" unless argv.empty?
+
+        options
+      rescue OptionParser::ParseError => error
+        raise Kettle::Dev::Error, error.message
+      end
+
+      def resolve_target_version(target, current_version)
+        if BUMP_TYPES.include?(target)
+          bumped_version(target, current_version)
+        else
+          validate_version(target)
+        end
+      end
+
+      def bumped_version(type, current_version)
+        version = Gem::Version.new(current_version)
+        segments = version.segments
+        unless segments.all? { |segment| segment.is_a?(Integer) }
+          raise Kettle::Dev::Error, "cannot #{type}-bump non-numeric version #{current_version.inspect}"
+        end
+
+        major, minor, patch = (segments + [0, 0, 0])[0, 3]
+        case type
+        when "major"
+          "#{major + 1}.0.0"
+        when "minor"
+          "#{major}.#{minor + 1}.0"
+        when "patch"
+          "#{major}.#{minor}.#{patch + 1}"
+        end
+      end
+
+      def validate_version(version)
+        Gem::Version.new(version).to_s
+      rescue ArgumentError => error
+        raise Kettle::Dev::Error, "invalid version #{version.inspect}: #{error.message}"
+      end
+
+      def collect_edits(current_version:, target_version:, from_version:)
+        if from_version && current_version != from_version
+          raise Kettle::Dev::Error, "current version is #{current_version}, not --from #{from_version}"
+        end
+
+        version_file_edits(target_version) + gemspec_version_edits(current_version, target_version)
+      end
+
+      def version_file_edits(target_version)
+        Kettle::Dev::Versioning.version_file_candidates(root).filter_map do |path|
+          source = File.read(path)
+          node = version_string_node(source, path)
+          current = node.unescaped
+          next if current == target_version
+
+          replacement = quote_like(node.location.slice, target_version)
+          file_edit(path, source, node.location.start_offset, node.location.end_offset, replacement)
+        end
+      end
+
+      def gemspec_version_edits(current_version, target_version)
+        gemspec_path = gemspec_path_for_bump
+        return [] unless gemspec_path
+
+        source = File.read(gemspec_path)
+        parse_result = parse_source(source, gemspec_path)
+        each_node(parse_result.value).filter_map do |node|
+          next unless node.is_a?(Prism::CallNode) && node.name == :version=
+
+          version_node = node.arguments&.arguments&.first
+          next unless version_node.is_a?(Prism::StringNode)
+          next unless version_node.unescaped == current_version
+          next if version_node.unescaped == target_version
+
+          replacement = quote_like(version_node.location.slice, target_version)
+          file_edit(gemspec_path, source, version_node.location.start_offset, version_node.location.end_offset, replacement)
+        end
+      end
+
+      def gemspec_path_for_bump
+        paths = Dir.glob(File.join(root, "*.gemspec")).sort
+        return nil if paths.empty?
+        raise Kettle::Dev::Error, "multiple gemspecs found; kettle-bump supports single gems only" if paths.length > 1
+
+        paths.first
+      end
+
+      def version_string_node(source, path)
+        parse_result = parse_source(source, path)
+        constant = each_node(parse_result.value).find do |node|
+          node.is_a?(Prism::ConstantWriteNode) && node.name == :VERSION && node.value.is_a?(Prism::StringNode)
+        end
+        raise Kettle::Dev::Error, "could not find string VERSION constant in #{path}" unless constant
+
+        constant.value
+      end
+
+      def parse_source(source, path)
+        require_prism
+        parse_result = Prism.parse(source)
+        raise Kettle::Dev::Error, "could not parse #{path}" unless parse_result.success?
+
+        parse_result
+      end
+
+      def require_prism
+        return if defined?(Prism)
+
+        require "prism"
+      rescue LoadError => error
+        raise Kettle::Dev::Error, "kettle-bump requires Prism; install the prism gem or run on Ruby 3.3+ (#{error.message})"
+      end
+
+      def each_node(root)
+        return enum_for(__method__, root) unless block_given?
+
+        queue = [root]
+        until queue.empty?
+          node = queue.shift
+          yield node
+          queue.concat(node.child_nodes.compact) if node.respond_to?(:child_nodes)
+        end
+      end
+
+      def file_edit(path, source, start_offset, end_offset, replacement)
+        {path: path, source: source, start_offset: start_offset, end_offset: end_offset, replacement: replacement}
+      end
+
+      def quote_like(original, value)
+        quote = original.start_with?("'") ? "'" : '"'
+        "#{quote}#{value}#{quote}"
+      end
+
+      def write_edits(edits)
+        edits.group_by { |edit| edit.fetch(:path) }.each_value do |file_edits|
+          source = file_edits.first.fetch(:source)
+          file_edits.sort_by { |edit| -edit.fetch(:start_offset) }.each do |edit|
+            source[edit.fetch(:start_offset)...edit.fetch(:end_offset)] = edit.fetch(:replacement)
+          end
+          File.write(file_edits.first.fetch(:path), source)
+        end
+      end
+
+      def summary(edits:, current_version:, target_version:, mode:)
+        lines = ["kettle-bump: #{current_version} -> #{target_version}"]
+        if edits.empty?
+          lines << "No version changes needed."
+        else
+          verb = (mode == :execute) ? "updated" : "would update"
+          edits.map { |edit| edit.fetch(:path) }.uniq.each { |path| lines << "#{verb} #{Kettle::Dev.display_path(path)}" }
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/kettle/dev/ci_helpers.rb

@@ -45,6 +45,13 @@ module Kettle
         status.success? ? out.strip : nil
       end
 
+      # Current git commit SHA, or nil when unavailable.
+      # @return [String, nil]
+      def current_head_sha
+        out, status = Open3.capture2("git", "rev-parse", "HEAD")
+        status.success? ? out.strip : nil
+      end
+
       # List workflow YAML basenames under .github/workflows at the given root.
       # Excludes maintenance workflows defined by {#exclusions}.
       # @param root [String] project root (defaults to {#project_root})
@@ -81,15 +88,14 @@ module Kettle
       # @param branch [String, nil] branch to query; defaults to {#current_branch}
       # @param token [String, nil] OAuth token for higher rate limits; defaults to {#default_token}
       # @return [Hash{String=>String,Integer}, nil] minimal run info or nil on error/none
-      def latest_run(owner:, repo:, workflow_file:, branch: nil, token: default_token)
+      def latest_run(owner:, repo:, workflow_file:, branch: nil, token: default_token, require_head: false, head_sha: nil)
         return unless owner && repo
 
         b = branch || current_branch
         return unless b
 
         # Scope to the exact commit SHA when available to avoid picking up a previous run on the same branch.
-        sha_out, status = Open3.capture2("git", "rev-parse", "HEAD")
-        sha = status.success? ? sha_out.strip : nil
+        sha = head_sha || current_head_sha
         base_url = "https://api.github.com/repos/#{owner}/#{repo}/actions/workflows/#{workflow_file}/runs?branch=#{URI.encode_www_form_component(b)}&per_page=5"
         uri = URI(base_url)
         req = Net::HTTP::Get.new(uri)
@@ -102,9 +108,10 @@ module Kettle
         runs = Array(data["workflow_runs"]) || []
         # Try to match by head_sha first; fall back to first run (branch-scoped) if none matches yet.
         run = if sha
-          runs.find { |r| r["head_sha"] == sha } || runs.first
+          match = runs.find { |r| r["head_sha"] == sha }
+          require_head ? match : (match || runs.first)
         else
-          runs.first
+          runs.first unless require_head
         end
         return unless run
 
@@ -112,7 +119,8 @@ module Kettle
           "status" => run["status"],
           "conclusion" => run["conclusion"],
           "html_url" => run["html_url"],
-          "id" => run["id"]
+          "id" => run["id"],
+          "head_sha" => run["head_sha"]
         }
       rescue => e
         Kettle::Dev.debug_error(e, __method__)

data/lib/kettle/dev/ci_monitor.rb

@@ -285,8 +285,13 @@ module Kettle
         total = workflows.size
         abort("No GitHub workflows found under .github/workflows; aborting.") if total.zero?
 
+        head_sha = Kettle::Dev::CIHelpers.current_head_sha
+        abort("Could not determine local HEAD SHA for GitHub Actions checks.") unless head_sha && !head_sha.empty?
+
         passed = {}
+        started = {}
         puts "Ensuring GitHub Actions workflows pass on #{branch} (#{owner}/#{repo}) via remote '#{gh_remote}'"
+        puts "Waiting for GitHub Actions runs to start for HEAD #{head_sha[0, 12]}."
         pbar = if defined?(ProgressBar)
           ProgressBar.create(title: "CI", total: total, format: "%t %b %c/%C", length: 30)
         end
@@ -300,11 +305,15 @@ module Kettle
           end
         end
         sleep((initial_sleep && initial_sleep >= 0) ? initial_sleep : 3)
+        start_timeout = github_start_timeout
+        poll_interval = github_poll_interval
+        start_deadline = monotonic_time + start_timeout
         idx = 0
         loop do
           wf = workflows[idx]
-          run = Kettle::Dev::CIHelpers.latest_run(owner: owner, repo: repo, workflow_file: wf, branch: branch)
+          run = Kettle::Dev::CIHelpers.latest_run(owner: owner, repo: repo, workflow_file: wf, branch: branch, require_head: true, head_sha: head_sha)
           if run
+            started[wf] = true
             if Kettle::Dev::CIHelpers.success?(run)
               unless passed[wf]
                 passed[wf] = true
@@ -317,9 +326,14 @@ module Kettle
             end
           end
           break if passed.size == total
+          if started.size < total && monotonic_time >= start_deadline
+            missing = (workflows - started.keys).join(", ")
+            puts
+            abort("Timed out after #{start_timeout}s waiting for GitHub Actions workflows to start for HEAD #{head_sha[0, 12]}: #{missing}. Confirm GitHub Actions started, then restart this tool from CI validation with: #{restart_hint}")
+          end
 
           idx = (idx + 1) % total
-          sleep(1)
+          sleep(poll_interval)
         end
         pbar&.finish unless pbar&.finished?
         puts "\nAll GitHub workflows passing (#{passed.size}/#{total})."
@@ -327,6 +341,31 @@ module Kettle
       end
       module_function :monitor_github_internal!
 
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+      module_function :monotonic_time
+
+      def github_start_timeout
+        seconds = begin
+          Integer(ENV["K_RELEASE_CI_START_TIMEOUT"])
+        rescue
+          nil
+        end
+        (seconds && seconds >= 0) ? seconds : 120
+      end
+      module_function :github_start_timeout
+
+      def github_poll_interval
+        seconds = begin
+          Float(ENV["K_RELEASE_CI_POLL_INTERVAL"])
+        rescue
+          nil
+        end
+        (seconds && seconds >= 0) ? seconds : 1
+      end
+      module_function :github_poll_interval
+
       def monitor_gitlab_internal!(restart_hint:)
         root = Kettle::Dev::CIHelpers.project_root
         gitlab_ci = File.exist?(File.join(root, ".gitlab-ci.yml"))