kettle-dev 1.0.11 → 1.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 913b6449dd3d5d61bc20384f02a12cb6296f9cbc9e6fdc1255c1fabeb9332034
-  data.tar.gz: ccb5f23873871c1e152d6394b4b5b96ea73ecb5306032710c637e948e7012741
+  metadata.gz: 18dc37569a34008ec953339ce7fd69e285bf007f2f1dd035de13856fb2d621ec
+  data.tar.gz: b3afeca255b2fb10fd86c4e48a47679b8652ff7ab9f75c4b8637c7738f83e28b
 SHA512:
-  metadata.gz: a86a6391cdb16fff03bc84ef00a50c62a1d86d775f6527bda5693e5bc395ab45be775480037436c9a3460cc557584fc16ea35e85bdb939ff983b5db10df69fcc
-  data.tar.gz: d492c8141e8a4899a1c742efc3e09afa38c97fdf3c667c92d0357f5ff1e0c460b9164ad1373a03d4696bad6b8406202c247c5d471cafccf5f29ea6ac2bb81912
+  metadata.gz: d12f7394b9aba54d138cbddc74598e03908280f6e4102c0b98a9d326e00909cc5d1cac16f1a5bced75ee694c2606e026bc772088b005abf1a69d9a1d23bf0c93
+  data.tar.gz: 5fc72941ddcc1c21e9e56fd0fffd2eb0b603eff7d1fe60d6cdf55108b8e4c314320be1ed243e5064d89cb604e74e42bdc6756764c42dcf920bc204514fbe539b

data/.junie/guidelines.md

@@ -128,6 +128,7 @@ Notes
 - NEVER run vanilla rubocop, as it won't handle the linting config properly. Always run rubocop_gradual:autocorrect or rubocop_gradual.
 - Running only a subset of specs is supported but in order to bypass the hard failure due to coverage thresholds, you need to run with K_SOUP_COV_MIN_HARD=false.
 - When adding code that writes to STDOUT, remember most specs silence output unless tagged with :check_output or DEBUG=true.
+- Completion criteria after changes: Only consider your change “done” when the relevant examples pass, as verified by .rspec_status. Do not rely on STDOUT impressions; consult .rspec_status (and example IDs) to confirm green results for the affected files/examples. If you ran a subset, re-run the full suite before finalizing to restore coverage thresholds.
 - Coverage reports: NEVER review the HTML report. Use JSON (preferred), XML, LCOV, or RCOV. For this project, always run tests with K_SOUP_COV_FORMATTERS set to "json".
 - Do NOT modify .envrc in tasks; when running tests locally or in scripts, manually prefix each run, e.g.: K_SOUP_COV_FORMATTERS="json" bin/rspec
 - For all the kettle-soup-cover options, see .envrc and find the K_SOUP_COV_* env vars.

data/Appraisals

@@ -26,6 +26,7 @@ appraise "unlocked_deps" do
   eval_gemfile "modular/coverage.gemfile"
   eval_gemfile "modular/documentation.gemfile"
   eval_gemfile "modular/style.gemfile"
+  eval_gemfile "modular/optional.gemfile"
 end
 
 # Used for head (nightly) releases of ruby, truffleruby, and jruby.

data/Appraisals.example

@@ -25,6 +25,7 @@ appraise "unlocked_deps" do
   eval_gemfile "modular/coverage.gemfile"
   eval_gemfile "modular/documentation.gemfile"
   eval_gemfile "modular/style.gemfile"
+  eval_gemfile "modular/optional.gemfile"
 end
 
 # Used for head (nightly) releases of ruby, truffleruby, and jruby.
@@ -92,6 +93,7 @@ appraise "coverage" do
   gem "mutex_m", "~> 0.2"
   gem "stringio", "~> 3.0"
   eval_gemfile "modular/coverage.gemfile"
+  eval_gemfile "modular/optional.gemfile"
 end
 
 # Only run linter on latest Ruby version (but, in support of oldest supported Ruby version)

data/CHANGELOG.md

@@ -24,6 +24,30 @@ Please file a bug if you notice a violation of semantic versioning.
 ### Fixed
 ### Security
 
+## [1.0.12] - 2025-08-28
+- TAG: [v1.0.12][1.0.12t]
+- COVERAGE: 97.80% -- 1957/2001 lines in 19 files
+- BRANCH COVERAGE: 79.98% -- 763/954 branches in 19 files
+- 78.70% documented
+### Added
+- CIMonitor to consolidate workflow / pipeline monitoring logic for GH/GL across kettle-release and rake tasks, with handling for:
+  - minutes exhausted
+  - blocked
+  - not configured
+  - normal failures
+  - pending
+  - queued
+  - running
+  - success
+- Ability to restart kettle-release from any failed step, so manual fixed can be applied.
+  - Example (after intermittent failure of CI): `bundle exec kettle-release start_step=10`
+### Fixed
+- added optional.gemfile.example, and handling for it in templating
+- kettle-changelog: ensure a blank line at end of file
+- add sleep(0.2) to ci:act to prevent race condition with stdout flushing
+- kettle-release: ensure SKIP_GEM_SIGNING works as expected with values of "true" or "false"
+  - ensure it doesn't abort the process in CI
+
 ## [1.0.11] - 2025-08-28
 - TAG: [v1.0.11][1.0.11t]
 - COVERAGE: 97.90% -- 1959/2001 lines in 19 files
@@ -190,7 +214,7 @@ 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/v1.0.11...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.0.12...HEAD
 [1.0.0]: https://github.com/kettle-rb/kettle-dev/compare/a427c302df09cfe4253a7c8d400333f9a4c1a208...v1.0.0
 [1.0.0t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.0.0
 [1.0.1]: https://gitlab.com/kettle-rb/kettle-dev/-/compare/v1.0.0...v1.0.1
@@ -215,4 +239,5 @@ Please file a bug if you notice a violation of semantic versioning.
 [1.0.10t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.0.10
 [1.0.11]: https://github.com/kettle-rb/kettle-dev/compare/v1.0.10...v1.0.11
 [1.0.11t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.0.11
-
+[1.0.12]: https://github.com/kettle-rb/kettle-dev/compare/v1.0.11...v1.0.12
+[1.0.12t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.0.12

data/Gemfile.example

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+git_source(:gitlab) { |repo_name| "https://gitlab.com/#{repo_name}" }
+
+#### IMPORTANT #######################################################
+# Gemfile is for local development ONLY; Gemfile is NOT loaded in CI #
+####################################################### IMPORTANT ####
+
+# Include dependencies from <gem name>.gemspec
+gemspec
+
+platform :mri do
+  # Debugging - Ensure ENV["DEBUG"] == "true" to use debuggers within spec suite
+  # Use binding.break, binding.b, or debugger in code
+  gem "debug", ">= 1.0.0"                  # ruby >= 2.7
+  gem "gem_bench", "~> 2.0", ">= 2.0.5"
+
+  # Dev Console - Binding.pry - Irb replacement
+  gem "pry", "~> 0.14"                     # ruby >= 2.0
+end
+
+# Code Coverage
+eval_gemfile "gemfiles/modular/coverage.gemfile"
+
+# Linting
+eval_gemfile "gemfiles/modular/style.gemfile"
+
+# Documentation
+eval_gemfile "gemfiles/modular/documentation.gemfile"
+
+# Optional
+eval_gemfile "gemfiles/modular/optional.gemfile"

data/README.md

@@ -697,7 +697,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]:https://gitmoji.dev
 [📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20😜%20😍-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.725-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.001-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: 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

data/exe/kettle-changelog

@@ -106,6 +106,9 @@ module Kettle
 
         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

data/exe/kettle-release

@@ -25,9 +25,12 @@ require "kettle/dev"
 # 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
@@ -46,8 +49,11 @@ if ARGV.include?("-h") || ARGV.include?("--help")
 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

@@ -1,5 +1 @@
-# Optional dependencies are not dependended on directly, but will be used if present.
-# git gem is not a direct dependency for two reasons:
-# 1. it is incompatible with Truffleruby v23
-# 2. it depends on activesupport, which is too heavy
-gem "git", ">= 1.19.1"    # ruby >= 2.3
+# 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

data/lib/kettle/dev/input_adapter.rb

@@ -25,6 +25,10 @@ module Kettle
         $stdin.gets(*args)
       end
 
+      def tty?
+        $stdin.tty?
+      end
+
       # Read one line from standard input, raising EOFError on end-of-file.
       # Provided for convenience symmetry with IO#readline when needed.
       #

data/lib/kettle/dev/release_cli.rb

@@ -30,124 +30,177 @@ module Kettle
 
       public
 
-      def initialize
+      def initialize(start_step: 1)
         @root = Kettle::Dev::CIHelpers.project_root
         @git = Kettle::Dev::GitAdapter.new
+        @start_step = (start_step || 1).to_i
+        @start_step = 1 if @start_step < 1
       end
 
       def run
+        # 1. Ensure Bundler version ✓
         ensure_bundler_2_7_plus!
 
-        version = detect_version
-        puts "Detected version: #{version.inspect}"
-
-        latest_overall = nil
-        latest_for_series = nil
-        begin
-          gem_name = detect_gem_name
-          latest_overall, latest_for_series = latest_released_versions(gem_name, version)
-        rescue StandardError => e
-          warn("Warning: failed to check RubyGems for latest version (#{e.class}: #{e.message}). Proceeding.")
-        end
-
-        if latest_overall
-          msg = "Latest released: #{latest_overall}"
-          if latest_for_series && latest_for_series != latest_overall
-            msg += " | Latest for series #{Gem::Version.new(version).segments[0, 2].join(".")}.x: #{latest_for_series}"
-          elsif latest_for_series
-            msg += " (matches current series)"
-          end
-          puts msg
-
-          cur = Gem::Version.new(version)
-          overall = Gem::Version.new(latest_overall)
-          cur_series = cur.segments[0, 2]
-          overall_series = overall.segments[0, 2]
-          target = if (cur_series <=> overall_series) == -1
-            latest_for_series
-          else
-            latest_overall
+        version = nil
+        committed = nil
+        trunk = nil
+        feature = nil
+
+        # 2. Version detection and sanity checks + prompt
+        if @start_step <= 2
+          version = detect_version
+          puts "Detected version: #{version.inspect}"
+
+          latest_overall = nil
+          latest_for_series = nil
+          begin
+            gem_name = detect_gem_name
+            latest_overall, latest_for_series = latest_released_versions(gem_name, version)
+          rescue StandardError => e
+            warn("Warning: failed to check RubyGems for latest version (#{e.class}: #{e.message}). Proceeding.")
           end
-          if target
-            bump = Kettle::Dev::Versioning.classify_bump(target, version)
-            case bump
-            when :same
-              series = cur_series.join(".")
-              warn("version.rb (#{version}) matches the latest released version for series #{series} (#{target}).")
-              abort("Aborting: version bump required. Bump PATCH/MINOR/MAJOR/EPIC.")
-            when :downgrade
-              series = cur_series.join(".")
-              warn("version.rb (#{version}) is lower than the latest released version for series #{series} (#{target}).")
-              abort("Aborting: version must be bumped above #{target}.")
+
+          if latest_overall
+            msg = "Latest released: #{latest_overall}"
+            if latest_for_series && latest_for_series != latest_overall
+              msg += " | Latest for series #{Gem::Version.new(version).segments[0, 2].join(".")}.x: #{latest_for_series}"
+            elsif latest_for_series
+              msg += " (matches current series)"
+            end
+            puts msg
+
+            cur = Gem::Version.new(version)
+            overall = Gem::Version.new(latest_overall)
+            cur_series = cur.segments[0, 2]
+            overall_series = overall.segments[0, 2]
+            target = if (cur_series <=> overall_series) == -1
+              latest_for_series
             else
-              label = {epic: "EPIC", major: "MAJOR", minor: "MINOR", patch: "PATCH"}[bump] || bump.to_s.upcase
-              puts "Proposed bump type: #{label} (from #{target} -> #{version})"
+              latest_overall
+            end
+            if target
+              bump = Kettle::Dev::Versioning.classify_bump(target, version)
+              case bump
+              when :same
+                series = cur_series.join(".")
+                warn("version.rb (#{version}) matches the latest released version for series #{series} (#{target}).")
+                abort("Aborting: version bump required. Bump PATCH/MINOR/MAJOR/EPIC.")
+              when :downgrade
+                series = cur_series.join(".")
+                warn("version.rb (#{version}) is lower than the latest released version for series #{series} (#{target}).")
+                abort("Aborting: version must be bumped above #{target}.")
+              else
+                label = {epic: "EPIC", major: "MAJOR", minor: "MINOR", patch: "PATCH"}[bump] || bump.to_s.upcase
+                puts "Proposed bump type: #{label} (from #{target} -> #{version})"
+              end
+            else
+              puts "Could not determine latest released version from RubyGems (offline?). Proceeding without sanity check."
             end
           else
             puts "Could not determine latest released version from RubyGems (offline?). Proceeding without sanity check."
           end
-        else
-          puts "Could not determine latest released version from RubyGems (offline?). Proceeding without sanity check."
-        end
 
-        puts "Have you updated lib/**/version.rb and CHANGELOG.md for v#{version}? [y/N]"
-        print("> ")
-        ans = Kettle::Dev::InputAdapter.gets&.strip
-        abort("Aborted: please update version.rb and CHANGELOG.md, then re-run.") unless ans&.downcase&.start_with?("y")
+          puts "Have you updated lib/**/version.rb and CHANGELOG.md for v#{version}? [y/N]"
+          print("> ")
+          ans = Kettle::Dev::InputAdapter.gets&.strip
+          abort("Aborted: please update version.rb and CHANGELOG.md, then re-run.") unless ans&.downcase&.start_with?("y")
+        end
 
-        run_cmd!("bin/setup")
-        run_cmd!("bin/rake")
+        # 3. bin/setup
+        run_cmd!("bin/setup") if @start_step <= 3
+        # 4. bin/rake
+        run_cmd!("bin/rake") if @start_step <= 4
+
+        # 5. appraisal:update (optional)
+        if @start_step <= 5
+          appraisals_path = File.join(@root, "Appraisals")
+          if File.file?(appraisals_path)
+            puts "Appraisals detected at #{appraisals_path}. Running: bin/rake appraisal:update"
+            run_cmd!("bin/rake appraisal:update")
+          else
+            puts "No Appraisals file found; skipping appraisal:update"
+          end
+        end
 
-        appraisals_path = File.join(@root, "Appraisals")
-        if File.file?(appraisals_path)
-          puts "Appraisals detected at #{appraisals_path}. Running: bin/rake appraisal:update"
-          run_cmd!("bin/rake appraisal:update")
-        else
-          puts "No Appraisals file found; skipping appraisal:update"
+        # 6. git user + commit release prep
+        if @start_step <= 6
+          ensure_git_user!
+          version ||= detect_version
+          committed = commit_release_prep!(version)
         end
 
-        ensure_git_user!
-        committed = commit_release_prep!(version)
+        # 7. optional local CI via act
+        maybe_run_local_ci_before_push!(committed) if @start_step <= 7
 
-        maybe_run_local_ci_before_push!(committed)
+        # 8. ensure trunk synced
+        if @start_step <= 8
+          trunk = detect_trunk_branch
+          feature = current_branch
+          puts "Trunk branch detected: #{trunk}"
+          ensure_trunk_synced_before_push!(trunk, feature)
+        end
 
-        trunk = detect_trunk_branch
-        feature = current_branch
-        puts "Trunk branch detected: #{trunk}"
-        ensure_trunk_synced_before_push!(trunk, feature)
+        # 9. push branches
+        push! if @start_step <= 9
 
-        push!
+        # 10. monitor CI after push
+        monitor_workflows_after_push! if @start_step <= 10
 
-        monitor_workflows_after_push!
+        # 11. merge feature into trunk and push
+        if @start_step <= 11
+          trunk ||= detect_trunk_branch
+          feature ||= current_branch
+          merge_feature_into_trunk_and_push!(trunk, feature)
+        end
 
-        merge_feature_into_trunk_and_push!(trunk, feature)
+        # 12. checkout trunk and pull
+        if @start_step <= 12
+          trunk ||= detect_trunk_branch
+          checkout!(trunk)
+          pull!(trunk)
+        end
 
-        checkout!(trunk)
-        pull!(trunk)
-
-        # Strong reminder for local runs: skip signing when testing a release flow
-        if ENV["SKIP_GEM_SIGNING"].to_s.strip == ""
-          puts "TIP: For local dry-runs or testing the release workflow, set SKIP_GEM_SIGNING=true to avoid PEM password prompts."
-          # Prompt on CI to allow an explicit abort when signing would otherwise hang
-          if ENV.fetch("CI", "false").casecmp("true").zero?
-            print("Proceed with signing enabled? This may hang waiting for a PEM password. [y/N]: ")
-            ans = Kettle::Dev::InputAdapter.gets&.strip
-            unless ans&.downcase&.start_with?("y")
-              abort("Aborted. Re-run with SKIP_GEM_SIGNING=true bundle exec kettle-release (or set it in your environment).")
+        # 13. signing guidance and checks
+        if @start_step <= 13
+          if ENV.fetch("SKIP_GEM_SIGNING", "false").casecmp("false").zero?
+            puts "TIP: For local dry-runs or testing the release workflow, set SKIP_GEM_SIGNING=true to avoid PEM password prompts."
+            if Kettle::Dev::InputAdapter.tty?
+              # In CI, avoid interactive prompts when no TTY is present (e.g., act or GitHub Actions "CI validation").
+              # Non-interactive CI runs should not abort here; later signing checks are either stubbed in tests
+              # or will be handled explicitly by ensure_signing_setup_or_skip!.
+              print("Proceed with signing enabled? This may hang waiting for a PEM password. [y/N]: ")
+              ans = Kettle::Dev::InputAdapter.gets&.strip
+              unless ans&.downcase&.start_with?("y")
+                abort("Aborted. Re-run with SKIP_GEM_SIGNING=true bundle exec kettle-release (or set it in your environment).")
+              end
+            else
+              warn("Non-interactive shell detected (non-TTY); skipping interactive signing confirmation.")
             end
           end
+
+          ensure_signing_setup_or_skip!
         end
 
-        ensure_signing_setup_or_skip!
-        puts "Running build (you may be prompted for the signing key password)..."
-        run_cmd!("bundle exec rake build")
+        # 14. build
+        if @start_step <= 14
+          puts "Running build (you may be prompted for the signing key password)..."
+          run_cmd!("bundle exec rake build")
+        end
 
-        run_cmd!("bin/gem_checksums")
-        validate_checksums!(version, stage: "after build + gem_checksums")
+        # 15. checksums validate
+        if @start_step <= 15
+          run_cmd!("bin/gem_checksums")
+          version ||= detect_version
+          validate_checksums!(version, stage: "after build + gem_checksums")
+        end
 
-        puts "Running release (you may be prompted for signing key password and RubyGems MFA OTP)..."
-        run_cmd!("bundle exec rake release")
-        validate_checksums!(version, stage: "after release")
+        # 16. release and validate
+        if @start_step <= 16
+          puts "Running release (you may be prompted for signing key password and RubyGems MFA OTP)..."
+          run_cmd!("bundle exec rake release")
+          version ||= detect_version
+          validate_checksums!(version, stage: "after release")
+        end
 
         puts "\nRelease complete. Don't forget to push the checksums commit if needed."
       end
@@ -155,87 +208,9 @@ module Kettle
       private
 
       def monitor_workflows_after_push!
-        root = Kettle::Dev::CIHelpers.project_root
-        workflows = Kettle::Dev::CIHelpers.workflows_list(root)
-        gitlab_ci = File.exist?(File.join(root, ".gitlab-ci.yml"))
-
-        branch = Kettle::Dev::CIHelpers.current_branch
-        abort("Could not determine current branch for CI checks.") unless branch
-
-        gh_remote = preferred_github_remote
-        gh_owner = nil
-        gh_repo = nil
-        if gh_remote && !workflows.empty?
-          url = remote_url(gh_remote)
-          gh_owner, gh_repo = parse_github_owner_repo(url)
-        end
-
-        checks_any = false
-
-        if gh_owner && gh_repo && !workflows.empty?
-          checks_any = true
-          total = workflows.size
-          abort("No GitHub workflows found under .github/workflows; aborting.") if total.zero?
-
-          passed = {}
-          idx = 0
-          puts "Ensuring GitHub Actions workflows pass on #{branch} (#{gh_owner}/#{gh_repo}) via remote '#{gh_remote}'"
-          pbar = if defined?(ProgressBar)
-            ProgressBar.create(title: "CI", total: total, format: "%t %b %c/%C", length: 30)
-          end
-
-          loop do
-            wf = workflows[idx]
-            run = Kettle::Dev::CIHelpers.latest_run(owner: gh_owner, repo: gh_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
-                url = run["html_url"] || "https://github.com/#{gh_owner}/#{gh_repo}/actions/workflows/#{wf}"
-                abort("Workflow failed: #{wf} -> #{url}")
-              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})."
-        end
-
-        gl_remote = gitlab_remote_candidates.first
-        if gitlab_ci && gl_remote
-          owner, repo = Kettle::Dev::CIHelpers.repo_info_gitlab
-          if owner && repo
-            checks_any = true
-            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)
-                  puts
-                  url = pipe["web_url"] || "https://gitlab.com/#{owner}/#{repo}/-/pipelines"
-                  abort("Pipeline failed: #{url}")
-                end
-              end
-              sleep(1)
-            end
-            pbar&.finish unless pbar&.finished?
-            puts "\nGitLab pipeline passing."
-          end
-        end
-
-        abort("CI configuration not detected (GitHub or GitLab). Ensure CI is configured and remotes point to the correct hosts.") unless checks_any
+        # Delegate to shared CI monitor to keep logic DRY across release flow and rake tasks
+        require "kettle/dev/ci_monitor"
+        Kettle::Dev::CIMonitor.monitor_all!(restart_hint: "bundle exec kettle-release start_step=10")
       end
 
       def run_cmd!(cmd)
@@ -608,8 +583,8 @@ module Kettle
       end
 
       def ensure_signing_setup_or_skip!
-        # Treat any non-empty value as an explicit skip signal (more robust across Ruby versions and ENV adapters)
-        return if ENV["SKIP_GEM_SIGNING"].to_s.strip != ""
+        # Treat any non-/true/i value as an explicit skip signal
+        return if ENV.fetch("SKIP_GEM_SIGNING", "").casecmp("true").zero?
 
         user = ENV.fetch("GEM_CERT_USER", ENV["USER"])
         cert_path = File.join(@root, "certs", "#{user}.pem")

data/lib/kettle/dev/tasks/ci_task.rb

@@ -132,6 +132,13 @@ module Kettle
             end
             fetch_and_print_status.call(file)
             run_act_for.call(file_path)
+            # After running locally, check upstream GitLab pipeline status if configured
+            begin
+              require "kettle/dev/ci_monitor"
+              Kettle::Dev::CIMonitor.monitor_gitlab!(restart_hint: "bundle exec rake ci:act")
+            rescue LoadError
+              # ignore if not available
+            end
             return
           end
 
@@ -186,6 +193,10 @@ module Kettle
           print(prompt)
           $stdout.flush
 
+          # We need to sleep a bit here to ensure the terminal is ready for both
+          #   input and writing status updates to each workflow's line
+          sleep(0.2) unless Kettle::Dev::IS_CI
+
           selected = nil
           input_thread = Thread.new do
             begin
@@ -330,6 +341,13 @@ module Kettle
           abort("ci:act aborted: workflow not found: #{file_path}") unless File.file?(file_path)
           fetch_and_print_status.call(chosen_file)
           run_act_for.call(file_path)
+          # After running locally, check upstream GitLab pipeline status if configured
+          begin
+            require "kettle/dev/ci_monitor"
+            Kettle::Dev::CIMonitor.monitor_gitlab!(restart_hint: "bundle exec rake ci:act")
+          rescue LoadError
+            # ignore if not available
+          end
         end
       end
     end

data/lib/kettle/dev/tasks/template_task.rb

@@ -96,7 +96,7 @@ module Kettle
           )
 
           # 4) gemfiles/modular/*.gemfile (from gem's gemfiles/modular)
-          [%w[coverage.gemfile], %w[documentation.gemfile], %w[style.gemfile]].each do |base|
+          [%w[coverage.gemfile], %w[documentation.gemfile], %w[style.gemfile], %w[optional.gemfile]].each do |base|
             src = helpers.prefer_example(File.join(gem_checkout_root, "gemfiles/modular", base[0]))
             dest = File.join(project_root, "gemfiles/modular", base[0])
             if File.basename(src).sub(/\.example\z/, "") == "style.gemfile"

data/lib/kettle/dev/version.rb

@@ -6,7 +6,7 @@ module Kettle
     module Version
       # The gem version.
       # @return [String]
-      VERSION = "1.0.11"
+      VERSION = "1.0.12"
     end
   end
 end

data/sig/kettle/dev/ci_helpers.rbs

@@ -31,7 +31,7 @@ module Kettle
         ?branch: String?,
         ?host: String,
         ?token: String?
-      ) -> { "status" => String, "web_url" => String, "id" => Integer }?
+      ) -> { "status" => String, "web_url" => String, "id" => Integer, "failure_reason" => String? }?
       def self.gitlab_success?: ({ "status" => String }?) -> bool
       def self.gitlab_failed?: ({ "status" => String }?) -> bool
     end

data/sig/kettle/dev/ci_monitor.rbs

@@ -0,0 +1,8 @@
+module Kettle
+  module Dev
+    module CIMonitor
+      def self.monitor_all!: (?restart_hint: String) -> void
+      def self.monitor_gitlab!: (?restart_hint: String) -> bool
+    end
+  end
+end

data/sig/kettle/dev/release_cli.rbs

@@ -1,7 +1,7 @@
 module Kettle
   module Dev
     class ReleaseCLI
-      def initialize: () -> void
+      def initialize: (?start_step: Integer) -> void
       def run: () -> void
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.0.12
 platform: ruby
 authors:
 - Peter H. Boling
@@ -270,6 +270,7 @@ files:
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
+- Gemfile.example
 - LICENSE.txt
 - README.md
 - README.md.example
@@ -288,6 +289,7 @@ files:
 - lib/kettle-dev.rb
 - lib/kettle/dev.rb
 - lib/kettle/dev/ci_helpers.rb
+- lib/kettle/dev/ci_monitor.rb
 - lib/kettle/dev/commit_msg.rb
 - lib/kettle/dev/exit_adapter.rb
 - lib/kettle/dev/git_adapter.rb
@@ -317,6 +319,7 @@ files:
 - sig/kettle-dev.rbs
 - sig/kettle/dev.rbs
 - sig/kettle/dev/ci_helpers.rbs
+- sig/kettle/dev/ci_monitor.rbs
 - sig/kettle/dev/commit_msg.rbs
 - sig/kettle/dev/exit_adapter.rbs
 - sig/kettle/dev/git_adapter.rbs
@@ -336,10 +339,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.0.11
-  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.0.11/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.0.12
+  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.0.12/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.0.11
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.0.12
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev