kettle-dev 2.5.27 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ec35425bc4a7f6e3ee067f5e92c80f9b81559945d464bde2966e5667eb94979
-  data.tar.gz: 1d6c6fc458b3667f2a2d6aff255da8f4cd6ff1503020d36cba21e8a3199a21e6
+  metadata.gz: 335bd9651ff7bbe5381c8e050a26f070c6accd8054ab581226ba3355c8a4aa6e
+  data.tar.gz: 7f59238412adde48ba5f2b524b08e4ce77a5348c81d0984e44013e6ce905b2dc
 SHA512:
-  metadata.gz: 8a6b8bd1a2e8fb4c5a2c73f3791378f793d31ef9eb05643621c720175508147c791660453b1341f62d5fc6aedb4befb37f0caecb0615244a1f3e5ce5af70989e
-  data.tar.gz: 0e1f22f3cd86b4544ff272dc78d3a24f7b6b1edc915be470d8760137cf91227482530899fc399c6398ed2ac44b30b675a1d3d2297fca03486f66f0bed76b5959
+  metadata.gz: 94e3d356b963078c8dd46d50d0f2b7ed92f656327bd3f766618617b56172ae0051dc32f6469cfd5c9faf539e00a4bbdf123947dd8febbd10c34172f51a2efc2d
+  data.tar.gz: d2eee5766a478c4846f05969ac4fcbf4614793740911c029219d85fb446fd308f9c376c5fa8d68edbdc71bd144dba09a1ad927c5915278c7933d0fc50ac74dca

data/CHANGELOG.md

@@ -30,6 +30,49 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.0.1] - 2026-08-10
+
+- TAG: [v3.0.1][3.0.1t]
+- COVERAGE: 91.87% -- 5602/6098 lines in 47 files
+- BRANCH COVERAGE: 76.29% -- 2117/2775 branches in 47 files
+- 50.64% documented
+
+### Fixed
+
+- Run 1Password authorization keepalives through the interactive terminal so release prompts remain visible.
+
+- Re-normalize release lockfiles after release tasks before commit and CI validation.
+
+## [3.0.0] - 2026-08-09
+
+- TAG: [v3.0.0][3.0.0t]
+- COVERAGE: 91.48% -- 5552/6069 lines in 47 files
+- BRANCH COVERAGE: 76.26% -- 2107/2763 branches in 47 files
+- 50.77% documented
+
+### Changed
+
+- Move the kettle-changelog executable to the standalone kettle-changelog gem while retaining kettle-dev support APIs for the transition.
+
+- Resolve standalone kettle-changelog through the generated Ruby-4-only modular release-tool Gemfile, with local path wiring for development.
+
+### Fixed
+
+- Use a dedicated standalone changelog bundle during bootstrap releases when the project bundle does not include kettle-changelog.
+
+- Keep standalone changelog bootstrap paths out of target release tests and documentation.
+
+## [2.5.28] - 2026-08-09
+
+- TAG: [v2.5.28][2.5.28t]
+- COVERAGE: 91.71% -- 5544/6045 lines in 47 files
+- BRANCH COVERAGE: 76.48% -- 2104/2751 branches in 47 files
+- 50.77% documented
+
+### Fixed
+
+- Retry an existing gem publication once with a fresh RubyGems MFA OTP when the release task reports an invalid OTP.
+
 ## [2.5.27] - 2026-08-09
 
 - TAG: [v2.5.27][2.5.27t]
@@ -3371,7 +3414,13 @@ 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-dev/kettle-dev/compare/v2.5.27...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v3.0.1...HEAD
+[3.0.1]: https://github.com/kettle-dev/kettle-dev/compare/v3.0.0...v3.0.1
+[3.0.1t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v3.0.1
+[3.0.0]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.28...v3.0.0
+[3.0.0t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v3.0.0
+[2.5.28]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.27...v2.5.28
+[2.5.28t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.5.28
 [2.5.27]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.26...v2.5.27
 [2.5.27t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.5.27
 [2.5.26]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.25...v2.5.26

data/README.md

@@ -1007,7 +1007,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-6.026-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-6.098-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/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

data/lib/kettle/dev/interactive_release_command.rb

@@ -1,39 +1,54 @@
 # frozen_string_literal: true
 
 require "open3"
+require "shellwords"
 
 module Kettle
   module Dev
     class InteractiveReleaseCommand
-      def initialize(secrets_provider:, input: $stdin, output: $stdout, error: $stderr, secret_event_handler: nil)
+      def initialize(secrets_provider:, input: $stdin, output: $stdout, error: $stderr, secret_event_handler: nil, forward_stdin: false)
         @secrets_provider = secrets_provider
         @input = input
         @output = output
         @error = error
         @secret_event_handler = secret_event_handler
+        @forward_stdin = forward_stdin
         @gem_signing_passphrase = nil
       end
 
       def call(env, cmd)
-        return call_with_pty(env, cmd) if pty_available?
+        call_argv(env, Shellwords.split(cmd.to_s))
+      end
+
+      def call_argv(env, argv)
+        return call_with_pty(env, argv) if pty_available?
 
-        call_with_open3(env, cmd)
+        call_with_open3(env, argv)
       end
 
       private
 
       attr_reader :secrets_provider, :secret_event_handler
 
-      def call_with_pty(env, cmd)
+      def call_with_pty(env, argv)
         stdout_str = +""
+        prompt_buffer = +""
         status = nil
-        PTY.spawn(env, cmd) do |output, input, pid|
+        PTY.spawn(env, *argv) do |output, input, pid|
           begin
             loop do
-              chunk = output.readpartial(1024)
-              stdout_str << chunk
-              @output.print(chunk)
-              handle_prompt(input, chunk)
+              readers = [output]
+              readers << @input if @forward_stdin && @input.tty?
+              IO.select(readers).first.each do |reader|
+                if reader.equal?(@input)
+                  input.write(@input.readpartial(1024))
+                else
+                  chunk = output.readpartial(1024)
+                  stdout_str << chunk
+                  @output.print(chunk)
+                  prompt_buffer = handle_prompt(input, chunk, prompt_buffer: prompt_buffer)
+                end
+              end
             end
           rescue Errno::EIO
             # PTY raises EIO when the child process exits after closing the slave.
@@ -47,27 +62,33 @@ module Kettle
         [stdout_str, "", status]
       end
 
-      def call_with_open3(env, cmd)
+      def call_with_open3(env, argv)
         stdout_str = +""
         stderr_str = +""
+        prompt_buffer = +""
         status = nil
-        Open3.popen3(env, cmd) do |input, output, error, wait_thread|
+        Open3.popen3(env, *argv) do |input, output, error, wait_thread|
           readers = [output, error]
+          readers << @input if @forward_stdin && @input.tty?
           until readers.empty?
             ready = IO.select(readers)
             ready.first.each do |reader|
-              begin
-                chunk = reader.readpartial(1024)
-                if reader.equal?(output)
-                  stdout_str << chunk
-                  @output.print(chunk)
-                else
-                  stderr_str << chunk
-                  @error.print(chunk)
+              if reader.equal?(@input)
+                input.write(@input.readpartial(1024))
+              else
+                begin
+                  chunk = reader.readpartial(1024)
+                  if reader.equal?(output)
+                    stdout_str << chunk
+                    @output.print(chunk)
+                  else
+                    stderr_str << chunk
+                    @error.print(chunk)
+                  end
+                  prompt_buffer = handle_prompt(input, chunk, prompt_buffer: prompt_buffer)
+                rescue EOFError
+                  readers.delete(reader)
                 end
-                handle_prompt(input, chunk)
-              rescue EOFError
-                readers.delete(reader)
               end
             end
           end
@@ -76,13 +97,21 @@ module Kettle
         [stdout_str, stderr_str, status]
       end
 
-      def handle_prompt(input, chunk)
-        if otp_prompt?(chunk)
-          write_secret(input, label: "RubyGems MFA code", source: "rubygems_otp") { secrets_provider.rubygems_otp } if otp_response_prompt?(chunk)
-          return
+      def handle_prompt(input, chunk, prompt_buffer: nil)
+        prompt_buffer = prompt_buffer.to_s.dup
+        prompt_buffer << chunk.to_s
+        prompt_buffer = prompt_buffer.byteslice([prompt_buffer.bytesize - 4096, 0].max, 4096).to_s
+
+        if otp_prompt?(prompt_buffer)
+          if otp_response_prompt?(prompt_buffer)
+            write_secret(input, label: "RubyGems MFA code", source: "rubygems_otp") { secrets_provider.rubygems_otp }
+            return +""
+          end
+          return prompt_buffer
         end
 
-        write_secret(input, label: "gem signing passphrase", source: "gem_signing_passphrase") { gem_signing_passphrase } if signing_password_prompt?(chunk)
+        write_secret(input, label: "gem signing passphrase", source: "gem_signing_passphrase") { gem_signing_passphrase } if signing_password_prompt?(prompt_buffer)
+        prompt_buffer
       end
 
       def gem_signing_passphrase

data/lib/kettle/dev/release_cli.rb

@@ -25,6 +25,7 @@ require_relative "release_secrets"
 module Kettle
   module Dev
     class ReleaseCLI
+      RUBYGEMS_INVALID_OTP = /Your OTP code is incorrect\. Please check it and retry\./.freeze
       QUIET_ENV = {
         "KETTLE_JEM_QUIET" => "true",
         "KETTLE_JEM_DEBUG" => "false",
@@ -116,7 +117,8 @@ module Kettle
           words = effective_command_words(cmd)
           words == ["bin/setup"] ||
             words.first(1) == ["bin/rake"] ||
-            words.first(3) == ["bundle", "exec", "rake"]
+            words.first(3) == ["bundle", "exec", "rake"] ||
+            words.first(3) == ["bundle", "exec", "kettle-changelog"]
         rescue ArgumentError
           false
         end
@@ -620,7 +622,10 @@ module Kettle
       end
 
       def prepare_release_lockfiles_for_commit!
-        reset_release_lockfiles!(stage: "before release prep commit") unless @release_lockfiles_reset_for_release_tasks
+        # Release setup and documentation tasks can re-materialize local PATH
+        # sources in the parent development bundle after the preflight reset.
+        # Always normalize again at the commit boundary.
+        reset_release_lockfiles!(stage: "before release prep commit")
         validate_release_lockfiles!(stage: "before release prep commit")
       end
 
@@ -827,7 +832,7 @@ module Kettle
       end
 
       def run_changelog!
-        cmd = "bundle exec kettle-changelog"
+        cmd = release_changelog_command
         cmd = "#{cmd} --version #{Shellwords.escape(@version_override)}" if @version_override
         cmd = "#{cmd} --yes" if @yes
         cmd = "#{cmd} --events=changelog" if @event_stream
@@ -835,6 +840,51 @@ module Kettle
         @changelog_generated_coverage = true
       end
 
+      # The changelog executable is owned by kettle-changelog, not kettle-dev.
+      # During the bootstrap release of kettle-dev it is therefore intentionally
+      # absent from kettle-dev's bundle. When a local kettle-dev workspace is
+      # supplied, run the standalone tool through that project's bundle instead
+      # of relying on an ambient installed executable.
+      def release_changelog_command
+        gemfile = release_changelog_gemfile
+        return "bundle exec kettle-changelog" unless gemfile
+
+        escaped_gemfile = Shellwords.escape(gemfile)
+        command = +"env -u BUNDLE_GEMFILE -u BUNDLE_LOCKFILE"
+        if (local_root = release_changelog_local_root)
+          command << " KETTLE_DEV_DEV=false KETTLE_CHANGELOG_DEV_ROOT=#{Shellwords.escape(local_root)}"
+        end
+        command << " BUNDLE_GEMFILE=#{escaped_gemfile} bundle exec kettle-changelog"
+        command
+      end
+
+      def release_changelog_gemfile
+        configured = ENV["K_RELEASE_CHANGELOG_GEMFILE"].to_s.strip
+        unless configured.empty?
+          path = File.expand_path(configured)
+          return path if File.file?(path)
+
+          abort("Configured K_RELEASE_CHANGELOG_GEMFILE does not exist: #{path}")
+        end
+
+        local_root = release_changelog_local_root
+        return nil unless local_root
+
+        changelog_root = File.join(File.expand_path(local_root), "kettle-changelog")
+        candidates = [
+          File.join(changelog_root, "gemfiles", "release.gemfile"),
+          File.join(changelog_root, "Gemfile")
+        ]
+        candidates.find { |path| File.file?(path) }
+      end
+
+      def release_changelog_local_root
+        local_root = ENV["KETTLE_DEV_DEV"].to_s.strip
+        return nil if local_root.empty? || %w[false 0 no off].include?(local_root.downcase)
+
+        File.expand_path(local_root)
+      end
+
       # Monorepo subprojects commonly disable their local hard coverage gate
       # because their narrow test suite cannot satisfy the aggregate root
       # thresholds. Preserve an explicit changelog policy, otherwise derive
@@ -1237,7 +1287,7 @@ module Kettle
 
         keep_release_secrets_alive!("prompt-bearing command")
         puts "$ #{cmd}"
-        _stdout_str, stderr_str, status = Kettle::Dev::InteractiveReleaseCommand.new(
+        stdout_str, stderr_str, status = Kettle::Dev::InteractiveReleaseCommand.new(
           secrets_provider: @secrets_provider,
           secret_event_handler: ->(payload) { emit_secret_event(payload) }
         ).call(
@@ -1246,6 +1296,11 @@ module Kettle
         )
         return if status.success?
 
+        if gem_release_command?(cmd) && rubygems_invalid_otp?(stdout_str, stderr_str)
+          retry_gem_push_after_invalid_otp!
+          return
+        end
+
         exit_code = status.respond_to?(:exitstatus) ? status.exitstatus : 1
         diag = stderr_str.to_s.empty? ? "" : "\n--- STDERR (last 20 lines) ---\n#{stderr_str.lines.last(20).join}".rstrip
         abort("Command failed: #{cmd} (exit #{exit_code})#{diag}")
@@ -1261,6 +1316,45 @@ module Kettle
         release_secrets_configured? ? @secrets_provider.class.name.to_s.split("::").last : "interactive"
       end
 
+      def gem_release_command?(cmd)
+        effective_command_words(cmd).first(4) == ["bundle", "exec", "rake", "release"]
+      end
+
+      def rubygems_invalid_otp?(*output)
+        output.any? { |chunk| chunk.to_s.match?(RUBYGEMS_INVALID_OTP) }
+      end
+
+      def retry_gem_push_after_invalid_otp!
+        version = @release_candidate&.version || detect_version
+        gem_path = gem_file_for_version(version)
+        unless gem_path && File.file?(gem_path)
+          abort("RubyGems rejected the OTP, but the built gem for version #{version} could not be found in pkg/.")
+        end
+
+        puts "RubyGems rejected the OTP after the release task completed; retrying the existing gem publication with a fresh OTP..."
+        emit_secret_event(
+          source: release_secrets_provider_label,
+          action: "otp_retry",
+          status: "started",
+          reason: "RubyGems rejected the first OTP"
+        )
+        run_cmd!("gem push #{Shellwords.escape(gem_path)}")
+        emit_secret_event(
+          source: release_secrets_provider_label,
+          action: "otp_retry",
+          status: "ok",
+          reason: "existing gem artifact published after OTP retry"
+        )
+      rescue SystemExit, Kettle::Dev::Error
+        emit_secret_event(
+          source: release_secrets_provider_label,
+          action: "otp_retry",
+          status: "failed",
+          reason: "fresh OTP retry failed"
+        )
+        raise
+      end
+
       def signing_enabled?
         ENV.fetch("SKIP_GEM_SIGNING", "false").casecmp("false").zero?
       end

data/lib/kettle/dev/release_secrets.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require "kettle/dev/interactive_release_command"
 require "kettle/dev/release_notifier"
 
 module Kettle
@@ -73,7 +74,7 @@ module Kettle
           argv = [op_cli, "account", "get"]
           account = string_config("account")
           argv.concat(["--account", account]) unless account.empty?
-          run_op(argv, purpose: "authorization keepalive", elapsed: elapsed)
+          run_op(argv, purpose: "authorization keepalive", elapsed: elapsed, interactive: true)
           true
         end
 
@@ -112,9 +113,11 @@ module Kettle
           required_config("cli")
         end
 
-        def run_op(argv, purpose:, elapsed: nil)
+        def run_op(argv, purpose:, elapsed: nil, interactive: false)
           elapsed_suffix = elapsed.to_s.empty? ? "" : " (elapsed #{elapsed})"
           Kettle::Dev::ReleaseNotifier.alert("1Password #{purpose} lookup starting#{elapsed_suffix}; watch for authorization prompt.")
+          return run_interactive_op(argv, purpose: purpose) if interactive
+
           stdout, stderr, status = Open3.capture3(*argv)
           return stdout.to_s.strip if status.success? && !stdout.to_s.strip.empty?
 
@@ -125,6 +128,23 @@ module Kettle
           raise Kettle::Dev::Error, "1Password CLI executable #{argv.first.inspect} was not found"
         end
 
+        def run_interactive_op(argv, purpose:)
+          _stdout, stderr, status = Kettle::Dev::InteractiveReleaseCommand.new(
+            secrets_provider: Provider.new,
+            input: $stdin,
+            output: $stdout,
+            error: $stderr,
+            forward_stdin: true
+          ).call_argv({}, argv)
+          return if status.success?
+
+          details = stderr.to_s.strip
+          details = "op exited #{status.exitstatus}" if details.empty?
+          raise Kettle::Dev::Error, "1Password #{purpose} lookup failed: #{details}"
+        rescue Errno::ENOENT
+          raise Kettle::Dev::Error, "1Password CLI executable #{argv.first.inspect} was not found"
+        end
+
         def required_config(key)
           value = string_config(key)
           raise Kettle::Dev::Error, "1Password release secrets require #{key}" if value.empty?

data/lib/kettle/dev/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "2.5.27"
+      VERSION = "3.0.1"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 2.5.27
+  version: 3.0.1
 platform: ruby
 authors:
 - Peter H. Boling
@@ -236,7 +236,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 3.2.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -246,7 +246,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 3.2.2
 - !ruby/object:Gem::Dependency
   name: turbo_tests2
   requirement: !ruby/object:Gem::Requirement
@@ -256,7 +256,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -266,7 +266,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
 - !ruby/object:Gem::Dependency
   name: stone_checksums
   requirement: !ruby/object:Gem::Requirement
@@ -317,7 +317,6 @@ email:
 - floss@galtzo.com
 executables:
 - kettle-bump
-- kettle-changelog
 - kettle-check-eof
 - kettle-commit-msg
 - kettle-dev-setup
@@ -336,7 +335,6 @@ files:
 - LICENSE.md
 - README.md
 - exe/kettle-bump
-- exe/kettle-changelog
 - exe/kettle-check-eof
 - exe/kettle-check-eof.sh
 - exe/kettle-commit-msg
@@ -402,10 +400,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.5.27
-  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.5.27/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v3.0.1
+  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v3.0.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.5.27
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/3.0.1
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev

data/exe/kettle-changelog

@@ -1,244 +0,0 @@
-#!/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)
-# - Set K_CHANGELOG_PATH to read/write a changelog outside the current gem root
-# - Set K_CHANGELOG_COVERAGE_ROOT to collect coverage from another bundle root
-# - Set K_CHANGELOG_VERSION_FILE to use a specific version.rb for monorepo roots
-# - Set K_CHANGELOG_GEM_NAME to use a specific gem name for root changelogs
-# - 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/rake 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:
-# - Strict mode (default) removes stale coverage output, runs `bundle exec
-#   kettle-test` with JSON coverage enabled, and reads the freshly generated
-#   coverage/coverage.json.
-# - Non-strict mode reads existing coverage JSON when present and leaves
-#   unavailable coverage or documentation stats blank with a warning.
-# - Expects `bin/rake yard` or `bin/yard` to be available for documentation stats
-#   when strict mode is enabled.
-
-$stdout.sync = true
-
-# Do not rely on Bundler; allow running in repos that do not depend on kettle-dev
-# Ensure RubyGems is available for 'require' lookups
-begin
-  require "rubygems"
-rescue LoadError
-  # Older Rubies always have rubygems; continue anyway
-end
-
-script_basename = File.basename(__FILE__)
-repo_lib = File.expand_path("../lib", __dir__)
-$LOAD_PATH.unshift(repo_lib) if File.directory?(repo_lib) && !$LOAD_PATH.include?(repo_lib)
-
-begin
-  # Standard library
-  require "json"
-  require "time"
-  require "open3"
-  require "shellwords"
-
-  # This library
-  require "kettle/dev"
-  require "kettle/ndjson"
-  require "kettle/dev/executable_version"
-  Kettle::Dev::ExecutableVersion.print_and_exit!(script_basename, ARGV, value_option: true)
-  machine_output = ARGV.any? { |arg| arg == "--json" || arg.start_with?("--events") }
-  Kettle::Dev::ExecutableVersion.print_header(script_basename) unless machine_output
-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
-
-if ARGV.include?("-h") || ARGV.include?("--help")
-  puts <<~USAGE
-    Usage: kettle-changelog [--version VERSION] [--yes] [--update-prep|--reformat|--backfill-released-version VERSION] [--pending-release] [--release-state] [--refresh-cache] [--add-unreleased-entry --section SECTION --entry TEXT] [--json|--events[=TYPES]] [--no-strict] [--no-coverage-threshold]
-
-    Detects the current version from lib/**/version.rb, the latest live release, and
-    the most recent CHANGELOG.md release section, then prompts to confirm the selected plan:
-    create a new release section, update the prepared release section in place, or reformat only.
-
-    Release plans add coverage and documentation stats, move entries from [Unreleased],
-    and update bottom link references to GitHub style.
-
-    Options:
-      --version VERSION         Use this version instead of detecting VERSION from lib/**/version.rb
-      --yes                     Auto-approve the selected release plan
-      --update-prep             Force updating the most recent prepared release section in place
-      --reformat                Normalize CHANGELOG.md structure without release-state planning
-      --backfill-released-version VERSION
-                                Add a tagged historical section without moving Unreleased entries
-      --pending-release         Query whether the changelog has release work pending; exits 0 for yes, 1 for no
-      --release-state,
-      --release-status          Print changelog release state, including latest published release and pending sources
-      --refresh-cache           Bypass cached gem.coop version data for this invocation
-      --add-unreleased-entry    Add one entry to an existing section under ## [Unreleased]
-      --section SECTION         Unreleased section to receive the entry (Added, Changed, Deprecated, Removed, Fixed, Security)
-      --entry TEXT              Changelog entry text; "- " is added when omitted
-      --json                    Print query output as JSON
-      --events[=TYPES]          Print newline-delimited JSON changelog events
-      --no-strict               Allow missing coverage and yard data (warnings only, no errors)
-      --no-coverage-threshold   Generate coverage without hard-failing below configured thresholds
-
-    Environment:
-      K_CHANGELOG_STRICT=false              Disable strict mode (equivalent to --no-strict flag)
-      K_CHANGELOG_COVERAGE_HARD=false       Disable coverage threshold hard-failure
-      K_CHANGELOG_PATH=path                 Read and write this changelog instead of ./CHANGELOG.md
-      K_CHANGELOG_COVERAGE_ROOT=path        Run/read coverage from this root instead of the gem root
-      K_CHANGELOG_VERSION_FILE=path         Read VERSION from this file instead of lib/**/version.rb
-      K_CHANGELOG_GEM_NAME=name             Read live release data as this gem instead of root .gemspec
-      KETTLE_GEM_COOP_REFRESH=true          Bypass cached gem.coop version data
-
-    Data generation:
-      Strict mode is the default. Release plans remove stale coverage output,
-      run bundle exec kettle-test with JSON coverage enabled, read the resulting
-      coverage/coverage.json, and collect documentation stats from bin/rake yard
-      or bin/yard.
-
-      Strict mode fails if specs fail, coverage JSON is not produced, coverage
-      is below the configured project thresholds, or documentation stats cannot
-      be collected.
-
-      Non-strict mode does not generate missing coverage or documentation data;
-      it warns and leaves unavailable stats blank.
-
-    Runtime requirements:
-      - bundle exec kettle-test available for strict coverage generation
-      - bin/rake yard or bin/yard available for strict documentation stats
-
-    Use --no-strict or K_CHANGELOG_STRICT=false to allow missing data.
-    Use --no-coverage-threshold or K_CHANGELOG_COVERAGE_HARD=false to run fresh
-    coverage without hard-failing below configured thresholds.
-  USAGE
-  exit(0)
-end
-
-begin
-  def extract_version_arg!(argv)
-    version = nil
-    if (idx = argv.index("--version"))
-      version = argv[idx + 1]
-      Kettle::Dev::ExitAdapter.abort("--version requires a VERSION") if version.to_s.empty?
-      argv.slice!(idx, 2)
-    end
-    argv.delete_if do |arg|
-      if arg.start_with?("--version=", "version=")
-        version = arg.split("=", 2)[1]
-        true
-      else
-        false
-      end
-    end
-    Kettle::Dev::Versioning.normalize_explicit_version(version)
-  end
-
-  def extract_events_arg!(argv)
-    events = false
-    event_types = nil
-    argv.delete_if do |arg|
-      if arg == "--events"
-        events = true
-      elsif arg.start_with?("--events=")
-        events = true
-        event_types = arg.split("=", 2)[1]
-      else
-        false
-      end
-    end
-    [events, event_types]
-  end
-
-  # Determine if strict mode is enabled (default: true)
-  strict_mode = !ARGV.include?("--no-strict") && ENV.fetch("K_CHANGELOG_STRICT", "true").downcase != "false"
-  update_prep = ARGV.delete("--update-prep")
-  reformat_only = ARGV.delete("--reformat")
-  yes = !!ARGV.delete("--yes")
-  pending_release_query = ARGV.delete("--pending-release")
-  release_state_query = ARGV.delete("--release-state") || ARGV.delete("--release-status")
-  refresh_cache = ARGV.delete("--refresh-cache")
-  add_unreleased_entry = ARGV.delete("--add-unreleased-entry") || ARGV.delete("--add-changelog-entry")
-  json_output = ARGV.delete("--json")
-  events_output, event_types = extract_events_arg!(ARGV)
-  Kettle::Dev::ExitAdapter.abort("--events cannot be combined with --json") if events_output && json_output
-  coverage_threshold_disabled = ARGV.include?("--no-coverage-threshold") || ARGV.include?("--no-coverage-thresholds")
-  coverage_hard = !coverage_threshold_disabled && ENV.fetch("K_CHANGELOG_COVERAGE_HARD", "true").downcase != "false"
-  version_override = extract_version_arg!(ARGV)
-
-  def extract_option_arg!(argv, name)
-    value = nil
-    if (idx = argv.index(name))
-      value = argv[idx + 1]
-      Kettle::Dev::ExitAdapter.abort("#{name} requires a value") if value.to_s.empty?
-      argv.slice!(idx, 2)
-    end
-    argv.delete_if do |arg|
-      if arg.start_with?("#{name}=")
-        value = arg.split("=", 2)[1]
-        true
-      else
-        false
-      end
-    end
-    value
-  end
-
-  historical_backfill_version = extract_option_arg!(ARGV, "--backfill-released-version")
-
-  if add_unreleased_entry
-    section = extract_option_arg!(ARGV, "--section")
-    entry = extract_option_arg!(ARGV, "--entry")
-    Kettle::Dev::ExitAdapter.abort("--section is required with --add-unreleased-entry") if section.to_s.empty?
-    Kettle::Dev::ExitAdapter.abort("--entry is required with --add-unreleased-entry") if entry.to_s.empty?
-
-    result = Kettle::Dev::ChangelogEntryAdder.new(section: section, entry: entry).run
-    message = (result == :changed) ? "CHANGELOG.md updated under Unreleased #{section}." : "CHANGELOG.md already contains that Unreleased #{section} entry."
-    puts(json_output ? JSON.pretty_generate({changed: result == :changed, section: section, entry: entry}) : message)
-    exit(0)
-  end
-
-  event_stream = events_output ? Kettle::Ndjson.event_stream($stdout, types: event_types) : nil
-  cli = Kettle::Dev::ChangelogCLI.new(strict: strict_mode, enforce_coverage_thresholds: coverage_hard, update_prep: update_prep, reformat_only: reformat_only, historical_backfill_version: historical_backfill_version, version: version_override, refresh_cache: refresh_cache, yes: yes, event_stream: event_stream)
-  if release_state_query
-    state = cli.release_state
-    puts(json_output ? JSON.pretty_generate(state) : cli.release_state_table(state))
-    exit(0)
-  end
-
-  if pending_release_query
-    state = cli.pending_release_status
-    output = if json_output
-      JSON.pretty_generate(state)
-    elsif state.fetch(:pending_release)
-      "true"
-    else
-      "false"
-    end
-    puts(output)
-    exit(state.fetch(:pending_release) ? 0 : 1)
-  end
-
-  cli.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
-  # Preserve exit status, but ensure at least a newline so shells don't show an empty line only.
-  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"))
-  exit(1)
-end