kettle-dev 2.4.2 → 2.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a251345bb56780a5c5b9efcfb53d394ca469581b5798f10839ac8ed5b4cae682
-  data.tar.gz: 4a81578792afe11fd09299ea7d1836d66f0cd8c76af00235491b8234fcec1553
+  metadata.gz: 0764aba0c8669f0c075868db0109a393fb508835db1540ac2b1f3cdf0c1b4cd0
+  data.tar.gz: a5d418a258af62045142025f314820330eaa18dba697036e2c4861bbb3874fad
 SHA512:
-  metadata.gz: 0cfa39888af23e14856d9874d965248c8d68a83b88c42bd3cc722b1a84fe8564b3c1381aa714aaebe0df531822365b70e4f2e7e2eff913f5e781e201e5f49b13
-  data.tar.gz: aefab75e861bc0c2132385b4e7411904b01cb6562c82d3485cdbdbb27d407004450b8e0a7030f33abf869bc73df4074f2cbdd1c3ef7abcfb21e9222b5c1c7f9e
+  metadata.gz: f4edf261a1f8819f89890b26eb1eb3666e388e771dde67bee0aa70d97d7920a7719493c0786267a6e651744c0a9c62462efa690105d0f7e124b612f386da9d09
+  data.tar.gz: 32423487dc0b9ea6af5d22695785f7d2ba2620b8128d6629f922f93433090d71600c4105ca5a1eecb96640c55699405edb78fea174e8bac46ef3eee1439e36cd

data/CHANGELOG.md

@@ -30,6 +30,38 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.4.3] - 2026-07-25
+
+- TAG: [v2.4.3][2.4.3t]
+- COVERAGE: 92.17% -- 4082/4429 lines in 38 files
+- BRANCH COVERAGE: 76.38% -- 1594/2087 branches in 38 files
+- 59.16% documented
+
+### Added
+
+- `kettle-release` now supports `--events[=TYPES]`, `--json`, and
+  `--report PATH` machine-readable release reporting backed by the shared
+  `kettle-ndjson` event toolkit.
+
+### Changed
+
+- kettle-jem-template-20260725-001 - Generated JRuby and TruffleRuby workflow
+  files now run when pull request head branches start with `feature/release`,
+  so release CI monitoring does not report intentionally skipped engine
+  workflows as failures.
+
+### Fixed
+
+- `kettle-release` now retries transient git remote fetch failures during
+  strict pre-push trunk parity checks, and failures now include an explicit
+  `--skip-remotes` recovery hint for intentionally unavailable remotes.
+- `kettle-release` now waits briefly and retries post-publish gem.coop
+  availability validation before failing, so normal registry mirror lag does
+  not abort immediately after a successful RubyGems push.
+
+- Raised the `kettle-ndjson` runtime dependency floor to v0.1.1 so the
+  dependency remains installable on kettle-dev's Ruby 2.4+ support floor.
+
 ## [2.4.2] - 2026-07-24
 
 - TAG: [v2.4.2][2.4.2t]
@@ -2674,7 +2706,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-dev/kettle-dev/compare/v2.4.2...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v2.4.3...HEAD
+[2.4.3]: https://github.com/kettle-dev/kettle-dev/compare/v2.4.2...v2.4.3
+[2.4.3t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.4.3
 [2.4.2]: https://github.com/kettle-dev/kettle-dev/compare/v2.4.1...v2.4.2
 [2.4.2t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.4.2
 [2.4.1]: https://github.com/kettle-dev/kettle-dev/compare/v2.4.0...v2.4.1

data/README.md

@@ -891,7 +891,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-4.321-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-4.429-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/exe/kettle-release

@@ -35,8 +35,10 @@ $LOAD_PATH.unshift(repo_lib) if File.directory?(repo_lib) && !$LOAD_PATH.include
 begin
   require "kettle/dev"
   require "kettle/dev/executable_version"
+  require "kettle/dev/release_cli"
   Kettle::Dev::ExecutableVersion.print_and_exit!(script_basename, ARGV, value_option: true)
-  Kettle::Dev::ExecutableVersion.print_header(script_basename)
+  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.")
@@ -47,7 +49,7 @@ end
 # Do not guard with __FILE__ == $PROGRAM_NAME because binstubs use Kernel.load.
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
-    Usage: kettle-release [--version VERSION] [--local-ci] [--appraisal-update] [--skip-bundle-audit] [--skip-steps STEPS] [--ci-workflows WORKFLOWS] [--skip-remotes REMOTES] [start_step=<0-19>]
+    Usage: kettle-release [--version VERSION] [--local-ci] [--appraisal-update] [--skip-bundle-audit] [--skip-steps STEPS] [--ci-workflows WORKFLOWS] [--skip-remotes REMOTES] [--json|--events[=TYPES]] [--report PATH] [start_step=<0-19>]
 
     Automates the release flow for a Ruby gem in the host project.
 
@@ -87,6 +89,9 @@ if ARGV.include?("-h") || ARGV.include?("--help")
       --skip-bundle-audit         # Skip bundle:audit/update during release rake checks
       --ci-workflows WORKFLOWS    # Comma-separated workflow files or stems to monitor at CI step 10
       --skip-remotes REMOTES      # Comma-separated git remote names to exclude from release fetch/push parity
+      --json                      # Print final machine-readable release report as JSON
+      --events[=TYPES]            # Print newline-delimited JSON release events, optionally filtered by type
+      --report PATH               # Write final machine-readable release report as JSON
       --local-ci                  # Sensitive release mode: run act locally, publish before any git push,
                                   # create the git tag locally, then push commits and tags after publish
 
@@ -195,18 +200,60 @@ def extract_skip_remotes_arg!(argv)
   remotes
 end
 
+def extract_report_arg!(argv)
+  report_path = nil
+  if (idx = argv.index("--report"))
+    report_path = argv[idx + 1]
+    if report_path.to_s.empty? || report_path.to_s.start_with?("-")
+      Kettle::Dev::ExitAdapter.abort("--report requires a path")
+    end
+    argv.slice!(idx, 2)
+  end
+  argv.delete_if do |arg|
+    if arg.start_with?("--report=", "report=")
+      report_path = arg.split("=", 2)[1]
+      Kettle::Dev::ExitAdapter.abort("--report requires a path") if report_path.to_s.empty?
+      true
+    else
+      false
+    end
+  end
+  report_path
+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
+
 local_ci = ARGV.include?("--local-ci")
 appraisal_task = ARGV.delete("--appraisal-update") ? "appraisal:update" : nil
 skip_bundle_audit = !!ARGV.delete("--skip-bundle-audit")
+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
 start_step_arg = ARGV.find { |a| a.start_with?("start_step=") }
 start_step = start_step_arg ? start_step_arg.split("=", 2)[1].to_i : 0
 version_override = extract_version_arg!(ARGV)
 skip_steps = extract_skip_steps_arg!(ARGV)
 ci_workflows = extract_ci_workflows_arg!(ARGV)
 skip_remotes = extract_skip_remotes_arg!(ARGV)
+report_path = extract_report_arg!(ARGV)
 
 begin
-  Kettle::Dev::ReleaseCLI.new(start_step: start_step, local_ci: local_ci, version: version_override, appraisal_task: appraisal_task, skip_steps: skip_steps, skip_bundle_audit: skip_bundle_audit, ci_workflows: ci_workflows, skip_remotes: skip_remotes).run
+  event_stream = events_output ? Kettle::Ndjson.event_stream($stdout, types: event_types) : nil
+  Kettle::Dev::ReleaseCLI.new(start_step: start_step, local_ci: local_ci, version: version_override, appraisal_task: appraisal_task, skip_steps: skip_steps, skip_bundle_audit: skip_bundle_audit, ci_workflows: ci_workflows, skip_remotes: skip_remotes, event_stream: event_stream, json_output: json_output, json_io: $stdout, report_path: report_path).run
 rescue LoadError => e
   warn("#{script_basename}: could not load dependency: #{e.class}: #{e.message}")
   warn(Array(e.backtrace).join("\n")) if ENV["DEBUG"]

data/lib/kettle/dev/release_cli.rb

@@ -13,6 +13,7 @@ require "yaml"
 require "set"
 
 # External gems
+require "kettle/ndjson"
 require "kettle/rb/compat_matrix"
 require "ruby-progressbar"
 
@@ -124,14 +125,43 @@ module Kettle
         @version_override = Kettle::Dev::Versioning.normalize_explicit_version(version)
         @appraisal_task = normalize_appraisal_task(appraisal_task || ENV["KETTLE_RELEASE_APPRAISAL_TASK"])
         @release_candidate = nil
+        @event_stream = options[:event_stream]
+        @event_recorder = Kettle::Ndjson.event_recorder(@event_stream, phase_timings: [])
+        @report_path = options[:report_path]
+        @json_output = !!options[:json_output]
+        @json_io = options[:json_io] || $stdout
+        @command_events = []
+        @diagnostics = []
+        @started_at = nil
+        @finished_report = nil
       end
 
       def run
+        @started_at = monotonic_time
+        emit_run_start
+        status = "ok"
+        error = nil
         with_bundle_audit_skip_env do
-          run_with_release_environment
+          with_machine_stdout_redirect do
+            run_with_release_environment
+          end
         end
+      rescue SystemExit => e
+        status = e.status.to_i.zero? ? "ok" : "failed"
+        error = e
+        record_diagnostic("release_exit", e.message, severity: (status == "ok") ? "info" : "error", blocking: status != "ok")
+        raise
+      rescue => e
+        status = "failed"
+        error = e
+        record_diagnostic("release_error", "#{e.class}: #{e.message}", severity: "error", blocking: true)
+        raise
+      ensure
+        finish_release_report(status: status, error: error)
       end
 
+      attr_reader :finished_report
+
       def run_with_release_environment
         run_pre_release_checks! if run_step?(0)
 
@@ -395,11 +425,11 @@ module Kettle
         begin
           version ||= detect_version
           gem_name = detect_gem_name
-          puts "\n🚀 Release #{gem_name} v#{version} Complete 🚀"
+          human_output.puts "\n🚀 Release #{gem_name} v#{version} Complete 🚀"
         rescue => e
           Kettle::Dev.debug_error(e, __method__)
           # Fallback if detection fails for any reason
-          puts "\n🚀 Release v#{version || "unknown"} Complete 🚀"
+          human_output.puts "\n🚀 Release v#{version || "unknown"} Complete 🚀"
         end
       end
 
@@ -1007,9 +1037,19 @@ module Kettle
 
       def run_cmd!(cmd)
         cmd = bundle_audit_skip_command(cmd)
+        emit_command_event(cmd, "started")
         with_bundle_audit_skip_env do
-          self.class.run_cmd!(cmd)
+          with_machine_stdout_redirect do
+            self.class.run_cmd!(cmd)
+          end
         end
+        emit_command_event(cmd, "ok")
+      rescue SystemExit => e
+        emit_command_event(cmd, "failed", reason: e.message)
+        raise
+      rescue => e
+        emit_command_event(cmd, "failed", reason: "#{e.class}: #{e.message}")
+        raise
       end
 
       def bundle_audit_skip_command(cmd)
@@ -1218,21 +1258,45 @@ module Kettle
 
       def run_release_availability_probe(candidate)
         script_path = write_release_availability_probe(candidate)
-        stdout_str = nil
-        stderr_str = nil
-        status = nil
-        with_unbundled_release_probe_env do
-          stdout_str, stderr_str, status = Open3.capture3(self.class.send(:command_env), Gem.ruby, script_path)
+        attempts = release_availability_probe_attempts
+        last_stderr = nil
+        last_status = nil
+        sleep(release_availability_probe_initial_delay)
+        attempts.times do |index|
+          attempt = index + 1
+          puts("Validating #{candidate.gem_name} #{candidate.version} from #{RELEASE_VALIDATION_SOURCE} (attempt #{attempt}/#{attempts})")
+          stdout_str = nil
+          stderr_str = nil
+          status = nil
+          with_unbundled_release_probe_env do
+            stdout_str, stderr_str, status = Open3.capture3(self.class.send(:command_env), Gem.ruby, script_path)
+          end
+          $stdout.print(stdout_str) unless stdout_str.to_s.empty?
+          return true if status.success?
+
+          last_stderr = stderr_str
+          last_status = status
+          sleep(release_availability_probe_interval) if attempt < attempts
         end
-        $stdout.print(stdout_str) unless stdout_str.to_s.empty?
-        return true if status.success?
 
-        diag = stderr_str.to_s.empty? ? "" : "\n--- STDERR ---\n#{stderr_str}".rstrip
-        abort("Published gem availability probe failed for #{candidate.gem_name} #{candidate.version} (exit #{status.exitstatus})#{diag}")
+        diag = last_stderr.to_s.empty? ? "" : "\n--- STDERR ---\n#{last_stderr}".rstrip
+        abort("Published gem availability probe failed for #{candidate.gem_name} #{candidate.version} after #{attempts} attempt(s) (exit #{last_status.exitstatus})#{diag}")
       ensure
         FileUtils.rm_f(script_path) if script_path
       end
 
+      def release_availability_probe_attempts
+        15
+      end
+
+      def release_availability_probe_initial_delay
+        5
+      end
+
+      def release_availability_probe_interval
+        10
+      end
+
       def with_unbundled_release_probe_env(&block)
         if defined?(Bundler)
           Bundler.with_unbundled_env(&block)
@@ -1369,6 +1433,118 @@ module Kettle
         end
       end
 
+      def emit_run_start
+        Kettle::Ndjson.emit_event(
+          @event_recorder,
+          "run_start",
+          command: "release",
+          root: @root,
+          start_step: @start_step,
+          skipped_steps: @skip_steps,
+          local_ci: @local_ci,
+          ci_workflows: @ci_workflows,
+          skipped_remotes: @skip_remotes
+        )
+      end
+
+      def emit_command_event(command, status, reason: nil)
+        event = {
+          phase: "release",
+          index: @command_events.length + 1,
+          name: command_event_name(command),
+          status: status,
+          reason: reason,
+          command: command,
+          changed_files: []
+        }
+        @command_events << event unless status == "started"
+        Kettle::Ndjson.emit_step_event(@event_recorder, "command_step", event, phase: "release", index: event[:index])
+      end
+
+      def command_event_name(command)
+        command.to_s.split(/\s+/, 3).first(2).join("_").gsub(/[^A-Za-z0-9_]+/, "_").sub(/_+\z/, "")
+      end
+
+      def record_diagnostic(kind, message, severity:, blocking:)
+        diagnostic = {
+          kind: kind,
+          severity: severity,
+          message: message.to_s,
+          blocking: blocking
+        }
+        @diagnostics << diagnostic
+        Kettle::Ndjson.emit_diagnostic_event(@event_recorder, diagnostic, index: @diagnostics.length)
+      end
+
+      def finish_release_report(status:, error:)
+        return if @finished_report
+
+        duration_ms = @started_at ? duration_ms_since(@started_at) : nil
+        @finished_report = {
+          command: "release",
+          root: @root,
+          version: safe_detect_version,
+          gem_name: safe_detect_gem_name,
+          start_step: @start_step,
+          skipped_steps: @skip_steps,
+          local_ci: @local_ci,
+          ci_workflows: @ci_workflows,
+          skipped_remotes: @skip_remotes,
+          status: status,
+          error_class: error&.class&.name,
+          error_message: error&.message,
+          duration_ms: duration_ms,
+          command_events: @command_events,
+          diagnostics: @diagnostics,
+          diagnostics_count: @diagnostics.length,
+          phase_timings: @event_recorder.phase_timings
+        }.compact
+        Kettle::Ndjson.emit_summary_event(@event_recorder, @finished_report)
+        write_release_report(@finished_report)
+        @json_io.puts(JSON.pretty_generate(@finished_report)) if @json_output
+      end
+
+      def write_release_report(report)
+        return unless @report_path
+
+        FileUtils.mkdir_p(File.dirname(@report_path))
+        File.write(@report_path, "#{JSON.pretty_generate(report)}\n")
+      end
+
+      def with_machine_stdout_redirect
+        return yield unless @json_output || @event_stream
+
+        previous_stdout = $stdout
+        $stdout = $stderr
+        yield
+      ensure
+        $stdout = previous_stdout if previous_stdout
+      end
+
+      def human_output
+        (@json_output || @event_stream) ? $stderr : $stdout
+      end
+
+      def safe_detect_version
+        detect_version
+      rescue
+        nil
+      end
+
+      def safe_detect_gem_name
+        detect_gem_name
+      rescue
+        nil
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def duration_ms_since(started_at)
+        ((monotonic_time - started_at) * 1000).round(3)
+      end
+
       def push_tags!
         # After release, push tags to remotes according to policy:
         # 1) If a remote named "all" exists, push tags only to it.
@@ -1506,7 +1682,7 @@ module Kettle
           remotes.each do |remote|
             next if remote == "all"
 
-            run_cmd!("git fetch #{Shellwords.escape(remote)}")
+            fetch_remote_for_parity!(remote)
           end
           missing_from = []
           remotes.each do |r|
@@ -1582,6 +1758,50 @@ module Kettle
         end
       end
 
+      def fetch_remote_for_parity!(remote)
+        command = "git fetch #{Shellwords.escape(remote)}"
+        attempts = remote_fetch_parity_attempts
+        last_error = nil
+        attempts.times do |index|
+          attempt = index + 1
+          puts "Fetching remote '#{remote}' for release parity (attempt #{attempt}/#{attempts})"
+          begin
+            run_cmd!(command)
+            return true
+          rescue SystemExit => error
+            last_error = error
+          rescue => error
+            last_error = error
+          end
+          sleep(remote_fetch_parity_interval) if attempt < attempts
+        end
+
+        abort(remote_fetch_failure_message(remote, last_error&.message.to_s))
+      end
+
+      def remote_fetch_parity_attempts
+        3
+      end
+
+      def remote_fetch_parity_interval
+        5
+      end
+
+      def remote_fetch_failure_message(remote, detail)
+        <<~MSG
+          Unable to fetch git remote '#{remote}' during release parity checks.
+          kettle-release enforces trunk parity across active remotes before publishing.
+
+          If this remote is temporarily unavailable or intentionally not part of this release,
+          rerun with one of:
+            kettle-release --skip-remotes #{remote}
+            K_RELEASE_SKIP_REMOTES=#{remote} kettle-release
+
+          Original failure:
+          #{detail}
+        MSG
+      end
+
       def merge_feature_into_trunk_and_push!(trunk, feature)
         return if feature.nil? || feature == trunk
 

data/lib/kettle/dev/version.rb

@@ -3,7 +3,7 @@
 module Kettle
   module Dev
     module Version
-      VERSION = "2.4.2"
+      VERSION = "2.4.3"
     end
     VERSION = Version::VERSION # Traditional Constant Location
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 2.4.2
+  version: 2.4.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -71,6 +71,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.3.1
+- !ruby/object:Gem::Dependency
+  name: kettle-ndjson
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: kettle-rb
   requirement: !ruby/object:Gem::Requirement
@@ -349,10 +369,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.4.2
-  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.4.2/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.4.3
+  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.4.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.4.2
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.4.3
   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