kettle-dev 1.1.24 → 1.1.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d04b8ab4f92685e809649cfa00e1272adb8b3da37ac68b24034259f7a7e7052b
-  data.tar.gz: ab03c72bf61c27941a1592c5e7bd47f0c4fc0211bc2d04280b809a6ba4d1d0b9
+  metadata.gz: d5b1991c0a766cdf2ca22899493b377918b1c35904e8c7927e29c30ba927df02
+  data.tar.gz: 9ba2c426beb96666c08ad9d0462162921456d48c8c2ce2ece0d302a62ab6574e
 SHA512:
-  metadata.gz: 33c386f8d38cbf5c6b87f54a56d133cf7d29f5265c1dd2279a27825a3c149a9d23293bbf71e9e359de952f812d00481c603255d8d7f1512e27edc9f14bedeca6
-  data.tar.gz: 0e9766d1e8746e056d1faece88d7df6542122af64d9cc789229b7881badca3c28b31f18acdc4eb4fbc080ad583000d6e906541f81867dfb8181732e828609ae1
+  metadata.gz: 1d688be0bf828e8d633970b38b37f0cc386afeb6718ddb7578f09f22f16ddd6e25b55b24978b14e9ba0d7e90f3aad4eef36fb394680f86e34195982e8f9d81f6
+  data.tar.gz: eee66b8b680aea507855b8b6323769e2e9f4d297243f0ed17a84261798241749d76a565dcf18dc2ba6730717aeb7701515b353fa9520f7add4bd37f99f0924ef

data/CHANGELOG.md

@@ -22,14 +22,29 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Changed
 
+- Use obfuscated URLs, and avatars from Open Collective in ReadmeBackers
+
 ### Deprecated
 
 ### Removed
 
 ### Fixed
 
+- fixed handling of kettle-release when checksums are present and unchanged causing the gem_checksums script to fail
+
 ### Security
 
+## [1.1.25] - 2025-09-18
+
+- TAG: [v1.1.25][1.1.25t]
+- COVERAGE: 96.87% -- 3708/3828 lines in 26 files
+- BRANCH COVERAGE: 81.69% -- 1526/1868 branches in 26 files
+- 78.33% documented
+
+### Fixed
+
+- kettle-readme-backers fails gracefully when README_UPDATER_TOKEN is missing from org secrets
+
 ## [1.1.24] - 2025-09-17
 
 - TAG: [v1.1.24][1.1.24t]
@@ -969,7 +984,11 @@ 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.1.24...HEAD
+[Unreleased]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.26...HEAD
+[1.1.26]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.25...v1.1.26
+[1.1.26t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.26
+[1.1.25]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.24...v1.1.25
+[1.1.25t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.25
 [1.1.24]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.23...v1.1.24
 [1.1.24t]: https://github.com/kettle-rb/kettle-dev/releases/tag/v1.1.24
 [1.1.23]: https://github.com/kettle-rb/kettle-dev/compare/v1.1.22...v1.1.23

data/README.md

@@ -548,6 +548,11 @@ What it does:
 - Tip:
   - Run this locally before committing to keep your README current, or schedule it in CI to refresh periodically.
   - It runs automatically on a once-a-week schedule by the .github/workflows/opencollective.yml workflow that is part of the kettle-dev template.
+- Authentication requirement:
+  - When running in CI with the provided workflow, you must provide an organization-level Actions secret named `README_UPDATER_TOKEN`.
+    - Create it under your GitHub organization settings: `https://github.com/organizations/<YOUR_ORG>/settings/secrets/actions`.
+    - The updater will look for `REPO` or `GITHUB_REPOSITORY` (both usually set by GitHub Actions) to infer `<YOUR_ORG>` for guidance.
+    - If `README_UPDATER_TOKEN` is missing, the tool prints a helpful error to STDERR and aborts, including a direct link to the expected org settings page.
 
 ## 🦷 FLOSS Funding
 
@@ -574,20 +579,24 @@ and [Tidelift][🏙️entsup-tidelift].
 
 ### Open Collective for Individuals
 
+Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/kettle-rb#backer)]
+
+NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
+
 <!-- OPENCOLLECTIVE-INDIVIDUALS:START -->
 No backers yet. Be the first!
 <!-- OPENCOLLECTIVE-INDIVIDUALS:END -->
 
-Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/kettle-rb#backer)]
-
 ### Open Collective for Organizations
 
+Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/kettle-rb#sponsor)]
+
+NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
+
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:START -->
 No sponsors yet. Be the first!
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:END -->
 
-Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/kettle-rb#sponsor)]
-
 ### Another way to support open-source
 
 > How wonderful it is that nobody need wait a single moment before starting to improve the world.<br/>
@@ -916,7 +925,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]:https://gitmoji.dev
 [📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-3.814-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.225-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/README.md.example

@@ -166,19 +166,25 @@ and [Tidelift][🏙️entsup-tidelift].
 
 ### Open Collective for Individuals
 
+Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/kettle-rb#backer)]
+
+NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
+
 <!-- OPENCOLLECTIVE-INDIVIDUALS:START -->
 No backers yet. Be the first!
 <!-- OPENCOLLECTIVE-INDIVIDUALS:END -->
 
-Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/kettle-rb#backer)]
-
 ### Open Collective for Organizations
 
+Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/kettle-rb#sponsor)]
+
+NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
+
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:START -->
 No sponsors yet. Be the first!
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:END -->
 
-Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/kettle-rb#sponsor)]
+[kettle-readme-backers]: https://github.com/kettle-rb/kettle-dev/blob/main/exe/kettle-readme-backers
 
 ### Another way to support open-source
 
@@ -513,7 +519,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]:https://gitmoji.dev
 [📌gitmoji-img]:https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-3.814-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.225-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/Rakefile.example

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# kettle-dev Rakefile v1.1.24 - 2025-09-17
+# kettle-dev Rakefile v1.1.26 - 2025-09-20
 # Ruby 2.3 (Safe Navigation) or higher required
 #
 # MIT License (see License.txt)

data/lib/kettle/dev/readme_backers.rb

@@ -18,26 +18,44 @@ module Kettle
 
       public
 
-      DEFAULT_AVATAR = "https://opencollective.com/static/images/default-avatar.png"
-      README_PATH = File.expand_path("../../../README.md", __dir__)
+      # Default README is the one in the current working directory of the host project
+      README_PATH = File.expand_path("README.md", Dir.pwd)
       README_OSC_TAG_DEFAULT = "OPENCOLLECTIVE"
       COMMIT_SUBJECT_DEFAULT = "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"
       # Deprecated constant maintained for backwards compatibility in tests/specs.
-      # Prefer OpenCollectiveConfig.yaml_path going forward.
-      OC_YML_PATH = OpenCollectiveConfig.yaml_path
+      # Prefer OpenCollectiveConfig.yaml_path going forward, but resolve to the host project root.
+      OC_YML_PATH = OpenCollectiveConfig.yaml_path(Dir.pwd)
+
+      private
+
+      # Emit a debug log line when kettle-dev debugging is enabled.
+      # Controlled by KETTLE_DEV_DEBUG=true (or DEBUG=true as fallback).
+      # @param msg [String]
+      # @return [void]
+      def debug_log(msg)
+        return unless Kettle::Dev::DEBUGGING
+        Kernel.warn("[readme_backers] #{msg}")
+      rescue StandardError
+        # never raise from a standard error within debug logging
+      end
+
+      public
 
       # Ruby 2.3 compatibility: Struct keyword_init added in Ruby 2.5
       # Switch to struct when dropping ruby < 2.5
       # Backer = Struct.new(:name, :image, :website, :profile, keyword_init: true)
       # Fallback for Ruby < 2.5 where Struct keyword_init is unsupported
       class Backer
-        attr_accessor :name, :image, :website, :profile
+        ROLE = "BACKER"
+        attr_accessor :name, :image, :website, :profile, :oc_type, :oc_index
 
-        def initialize(name: nil, image: nil, website: nil, profile: nil, **_ignored)
+        def initialize(name: nil, image: nil, website: nil, profile: nil, oc_type: nil, oc_index: nil, **_ignored)
           @name = name
           @image = image
           @website = website
           @profile = profile
+          @oc_type = oc_type # "backer" or "organization"
+          @oc_index = oc_index # Integer index within type for OC URL generation
         end
       end
 
@@ -46,25 +64,111 @@ module Kettle
         @readme_path = readme_path
       end
 
+      # Validate environment preconditions for running the updater.
+      # Ensures README_UPDATER_TOKEN is present. If missing, prints guidance and raises.
+      #
+      # @return [void]
+      # @raise [RuntimeError] when README_UPDATER_TOKEN is not provided
+      def validate
+        token = ENV["README_UPDATER_TOKEN"].to_s
+        if token.strip.empty?
+          repo = ENV["REPO"] || ENV["GITHUB_REPOSITORY"]
+          org = repo&.to_s&.split("/")&.first
+          org_url = if org && !org.strip.empty?
+            "https://github.com/organizations/#{org}/settings/secrets/actions"
+          else
+            "https://github.com/organizations/YOUR_ORG/settings/secrets/actions"
+          end
+          $stderr.puts "ERROR: README_UPDATER_TOKEN is not set."
+          $stderr.puts "Please create an organization-level Actions secret named README_UPDATER_TOKEN at:"
+          $stderr.puts "  #{org_url}"
+          $stderr.puts "Then update the workflow to reference it, or provide README_UPDATER_TOKEN in the environment."
+          raise 'Missing ENV["README_UPDATER_TOKEN"]'
+        end
+        nil
+      end
+
       def run!
+        validate
+        debug_log("Starting run: handle=#{@handle.inspect}, readme=#{@readme_path}")
+        debug_log("Resolved OSC tag base=#{readme_osc_tag.inspect}")
         readme = File.read(@readme_path)
 
         # Identify previous entries for diffing/mentions
         b_start, b_end = detect_backer_tags(readme)
-        prev_backer_identities = extract_section_identities(readme, b_start, b_end)
         s_start_prev, s_end_prev = detect_sponsor_tags(readme)
+        debug_log("Backer tags present=#{b_start != :not_found && b_end != :not_found}; Sponsor tags present=#{s_start_prev != :not_found && s_end_prev != :not_found}")
+        prev_backer_identities = extract_section_identities(readme, b_start, b_end)
         prev_sponsor_identities = extract_section_identities(readme, s_start_prev, s_end_prev)
 
-        # Backers (individuals)
-        backers = fetch_members("backers.json")
+        # Fetch all BACKER-role members once and partition by tier
+        debug_log("Fetching OpenCollective members JSON for handle=#{@handle} ...")
+        raw = fetch_all_backers_raw
+        debug_log("Fetched #{Array(raw).size} members (role=#{Backer::ROLE}) before tier partitioning")
+        # Build OpenCollective type-index map to generate stable avatar/website links
+        index_map = build_oc_index_map(raw)
+        if Kettle::Dev::DEBUGGING
+          tier_counts = Array(raw).group_by { |h| (h["tier"] || "").to_s.strip }.transform_values(&:size)
+          debug_log("Tier distribution: #{tier_counts}")
+          empty_tier = Array(raw).select { |h| h["tier"].to_s.strip.empty? }
+          unless empty_tier.empty?
+            debug_log("Members with empty tier: count=#{empty_tier.size}; showing up to 5 samples:")
+            empty_tier.first(5).each_with_index do |m, i|
+              debug_log("  [empty-tier ##{i + 1}] name=#{m["name"].inspect}, isActive=#{m["isActive"].inspect}, profile=#{m["profile"].inspect}, website=#{m["website"].inspect}")
+            end
+          end
+          other_tiers = Array(raw).map { |h| h["tier"].to_s.strip }.reject { |t| t.empty? || t.casecmp("Backer").zero? || t.casecmp("Sponsor").zero? }
+          unless other_tiers.empty?
+            counts = other_tiers.group_by { |t| t }.transform_values(&:size)
+            debug_log("Non-standard tiers present (excluding Backer/Sponsor): #{counts}")
+          end
+        end
+        backers_hashes = Array(raw).select { |h| h["tier"].to_s.strip.casecmp("Backer").zero? }
+        sponsors_hashes = Array(raw).select { |h| h["tier"].to_s.strip.casecmp("Sponsor").zero? }
+
+        backers = map_hashes_to_backers(backers_hashes, index_map, force_type: "backer")
+        sponsors = map_hashes_to_backers(sponsors_hashes, index_map, force_type: "organization")
+        debug_log("Partitioned counts => Backers=#{backers.size}, Sponsors=#{sponsors.size}")
+        if Kettle::Dev::DEBUGGING && backers.empty? && sponsors.empty? && Array(raw).any?
+          debug_log("No Backer or Sponsor tiers matched among #{Array(raw).size} BACKER-role records. If tiers are empty, they will not appear in Backers/Sponsors sections.")
+        end
+
+        # Additional dynamic tiers (exclude Backer/Sponsor)
+        extra_map = {}
+        Array(raw).group_by { |h| h["tier"].to_s.strip }.each do |tier, members|
+          normalized = tier.empty? ? "Donors" : tier
+          next if normalized.casecmp("Backer").zero? || normalized.casecmp("Sponsor").zero?
+          extra_map[normalized] = map_hashes_to_backers(members, index_map)
+        end
+        debug_log("Extra tiers detected: #{extra_map.keys.sort}") unless extra_map.empty?
+
         backers_md = generate_markdown(backers, empty_message: "No backers yet. Be the first!", default_name: "Backer")
-        updated = replace_between_tags(readme, b_start, b_end, backers_md)
+        sponsors_md_base = generate_markdown(sponsors, empty_message: "No sponsors yet. Be the first!", default_name: "Sponsor")
+
+        extra_tiers_md = generate_extra_tiers_markdown(extra_map)
+        sponsors_md = if extra_tiers_md.empty?
+          sponsors_md_base
+        else
+          [sponsors_md_base, "", extra_tiers_md].join("\n")
+        end
+
+        # Update backers section
+        # If the identities in the existing block match the identities derived from current data,
+        # treat as no-change to avoid rewriting formatting (e.g., Markdown -> HTML OC anchors).
+        semantically_same_backers = semantically_same_section?(prev_backer_identities, backers)
+        updated = if semantically_same_backers
+          :no_change
+        else
+          replace_between_tags(readme, b_start, b_end, backers_md)
+        end
         case updated
         when :not_found
+          debug_log("Backers tag block not found; skipping backers section update")
           updated_readme = readme
           backers_changed = false
           new_backers = []
         when :no_change
+          debug_log("Backers section unchanged (identities match or generated markdown matches existing block)")
           updated_readme = readme
           backers_changed = false
           new_backers = []
@@ -72,19 +176,35 @@ module Kettle
           updated_readme = updated
           backers_changed = true
           new_backers = compute_new_members(prev_backer_identities, backers)
+          debug_log("Backers section updated; new_backers=#{new_backers.size}")
         end
 
-        # Sponsors (organizations)
-        sponsors = fetch_members("sponsors.json")
-        sponsors_md = generate_markdown(sponsors, empty_message: "No sponsors yet. Be the first!", default_name: "Sponsor")
+        # Update sponsors section (with extra tiers appended when present)
         s_start, s_end = detect_sponsor_tags(updated_readme)
-        updated2 = replace_between_tags(updated_readme, s_start, s_end, sponsors_md)
+        # If there is no sponsors section but there is a backers section, append extra tiers to backers instead.
+        if s_start == :not_found && !extra_tiers_md.empty? && b_start != :not_found
+          debug_log("Sponsors tags not found; appending extra tiers under Backers section")
+          backers_md_with_extra = [backers_md, "", extra_tiers_md].join("\n")
+          updated = replace_between_tags(updated_readme, b_start, b_end, backers_md_with_extra)
+          updated_readme = updated unless updated == :no_change || updated == :not_found
+        end
+
+        # Sponsors: apply the same semantic no-change rule
+        prev_s_ids = extract_section_identities(updated_readme, s_start, s_end)
+        semantically_same_sponsors = semantically_same_section?(prev_s_ids, sponsors)
+        updated2 = if semantically_same_sponsors
+          :no_change
+        else
+          replace_between_tags(updated_readme, s_start, s_end, sponsors_md)
+        end
         case updated2
         when :not_found
+          debug_log("Sponsors tag block not found; skipping sponsors section update")
           sponsors_changed = false
           final = updated_readme
           new_sponsors = []
         when :no_change
+          debug_log("Sponsors section unchanged (identities match or generated markdown matches existing block)")
           sponsors_changed = false
           final = updated_readme
           new_sponsors = []
@@ -92,6 +212,7 @@ module Kettle
           sponsors_changed = true
           final = updated2
           new_sponsors = compute_new_members(prev_sponsor_identities, sponsors)
+          debug_log("Sponsors section updated; new_sponsors=#{new_sponsors.size}")
         end
 
         if !backers_changed && !sponsors_changed
@@ -99,9 +220,11 @@ module Kettle
             ts = tag_strings
             warn("No recognized Open Collective tags found in #{@readme_path}. Expected one or more of: " \
               "#{ts[:generic_start]}/#{ts[:generic_end]}, #{ts[:individuals_start]}/#{ts[:individuals_end]}, #{ts[:orgs_start]}/#{ts[:orgs_end]}.")
+            debug_log("Missing tags: looked for #{ts}")
             # Do not exit the process during tests or library use; just return.
             return
           end
+          debug_log("No changes detected after processing; Backers=#{backers.size}, Sponsors=#{sponsors.size}, ExtraTiers=#{extra_map.keys.size}")
           puts "No changes to backers or sponsors sections in #{@readme_path}."
           return
         end
@@ -122,9 +245,9 @@ module Kettle
         env = ENV["KETTLE_DEV_BACKER_README_OSC_TAG"].to_s
         return env unless env.strip.empty?
 
-        if File.file?(OpenCollectiveConfig.yaml_path)
+        if File.file?(OC_YML_PATH)
           begin
-            yml = YAML.safe_load(File.read(OpenCollectiveConfig.yaml_path))
+            yml = YAML.safe_load(File.read(OC_YML_PATH))
             if yml.is_a?(Hash)
               from_yml = yml["readme-osc-tag"] || yml[:"readme-osc-tag"]
               from_yml = from_yml.to_s if from_yml
@@ -150,11 +273,13 @@ module Kettle
       end
 
       def resolve_handle
-        OpenCollectiveConfig.handle(required: true)
+        OpenCollectiveConfig.handle(required: true, root: Dir.pwd)
       end
 
-      def fetch_members(path)
-        url = URI("https://opencollective.com/#{@handle}/#{path}")
+      def fetch_all_backers_raw
+        api_path = "members/all.json"
+        url = URI("https://opencollective.com/#{@handle}/#{api_path}")
+        debug_log("GET #{url}")
         response = Net::HTTP.start(url.host, url.port, use_ssl: url.scheme == "https") do |conn|
           conn.read_timeout = 10
           conn.open_timeout = 5
@@ -162,36 +287,169 @@ module Kettle
           req["User-Agent"] = "kettle-dev/README-backers"
           conn.request(req)
         end
-        return [] unless response.is_a?(Net::HTTPSuccess)
+        unless response.is_a?(Net::HTTPSuccess)
+          body_len = (response.respond_to?(:body) && response.body) ? response.body.bytesize : 0
+          code = response.respond_to?(:code) ? response.code : response.class.name
+          warn("OpenCollective API non-success for #{api_path}: status=#{code}, body_len=#{body_len}")
+          debug_log("Response body (truncated 500 bytes): #{response.body.to_s[0, 500]}") if Kettle::Dev::DEBUGGING && body_len.to_i > 0
+          return []
+        end
 
         parsed = JSON.parse(response.body)
-        Array(parsed).map do |h|
+        all = Array(parsed)
+        filtered = all.select { |h| h["role"].to_s.upcase == Backer::ROLE }
+        debug_log("Parsed #{all.size} records; filtered BACKER => #{filtered.size}")
+        filtered
+      rescue JSON::ParserError => e
+        warn("Error parsing #{api_path} JSON: #{e.message}")
+        debug_log("Body that failed to parse (truncated 500): #{response&.body.to_s[0, 500]}")
+        []
+      rescue StandardError => e
+        warn("Error fetching #{api_path}: #{e.class}: #{e.message}")
+        debug_log(e.backtrace.join("\n"))
+        []
+      end
+
+      # Build a deterministic OpenCollective index map used to construct avatar/website URLs.
+      # Rules:
+      # - Iterate through the raw BACKER-role array in order received from OC.
+      # - Maintain two independent counters: one for "backer" (users) and one for "organization".
+      # - Derive a stable identity key for each member by preferring profile URL, then website URL, then name; all downcased.
+      # - Assign the current counter as the index for that type and increment the counter.
+      # - Return a Hash mapping the identity key to { type: "backer"|"organization", index: Integer }.
+      # This lets generate_markdown output links like:
+      #   https://opencollective.com/<handle>/<type>/<index>/website and avatar.svg
+      def build_oc_index_map(hashes)
+        counts = {"backer" => 0, "organization" => 0}
+        map = {}
+        Array(hashes).each do |h|
+          type = (h["type"].to_s.upcase == "ORGANIZATION") ? "organization" : "backer"
+          key = if h["profile"].to_s.strip != ""
+            h["profile"].to_s.strip.downcase
+          elsif h["website"].to_s.strip != ""
+            h["website"].to_s.strip.downcase
+          else
+            h["name"].to_s.strip.downcase
+          end
+          idx = counts[type]
+          counts[type] = idx + 1
+          map[key] = {type: type, index: idx}
+        end
+        # Helpful debug summary so users can see which index maps to which backer.
+        if Kettle::Dev::DEBUGGING
+          samples = map.first(5).map { |k, v| "#{v[:type]}##{v[:index]} => #{k}" }
+          debug_log("Built OC index map: backer_count=#{counts["backer"]}, organization_count=#{counts["organization"]}; sample=#{samples}")
+        end
+        map
+      end
+
+      def map_hashes_to_backers(hashes, index_map = nil, force_type: nil)
+        forced_counter = 0
+        Array(hashes).map do |h|
+          key = if h["profile"].to_s.strip != ""
+            h["profile"].to_s.strip.downcase
+          elsif h["website"].to_s.strip != ""
+            h["website"].to_s.strip.downcase
+          else
+            h["name"].to_s.strip.downcase
+          end
+          oc = index_map ? index_map[key] : nil
+          # Determine oc_type/index with optional forced type override (used for sections)
+          oc_type = nil
+          oc_index = nil
+          if force_type
+            if oc && oc[:type] == force_type && !oc[:index].nil?
+              oc_type = oc[:type]
+              oc_index = oc[:index]
+            else
+              oc_type = force_type
+              oc_index = forced_counter
+              forced_counter += 1
+            end
+          else
+            oc_type = oc ? oc[:type] : nil
+            oc_index = oc ? oc[:index] : nil
+          end
           Backer.new(
             name: h["name"],
-            image: (h["image"].to_s.strip.empty? ? nil : h["image"]),
+            image: begin
+              # Prefer OpenCollective's "avatar" key; fallback to legacy "image"
+              img = h["avatar"]
+              img = h["image"] if img.to_s.strip.empty?
+              img.to_s.strip.empty? ? nil : img
+            end,
             website: (h["website"].to_s.strip.empty? ? nil : h["website"]),
             profile: (h["profile"].to_s.strip.empty? ? nil : h["profile"]),
+            oc_type: oc_type,
+            oc_index: oc_index,
           )
         end
-      rescue JSON::ParserError => e
-        warn("Error parsing #{path} JSON: #{e.message}")
-        []
-      rescue StandardError => e
-        warn("Error fetching #{path}: #{e.class}: #{e.message}")
-        []
       end
 
       def generate_markdown(members, empty_message:, default_name:)
         return empty_message if members.nil? || members.empty?
 
         members.map do |m|
-          image_url = m.image || DEFAULT_AVATAR
-          link = m.website || m.profile || "#"
-          name = (m.name && !m.name.strip.empty?) ? m.name : default_name
-          "[![#{escape_text(name)}](#{image_url})](#{link})"
+          # Prefer deterministic OpenCollective avatar/link form when index is available
+          if m.oc_type && !m.oc_type.to_s.strip.empty? && !m.oc_index.nil?
+            type = m.oc_type
+            idx = m.oc_index
+            href = "https://opencollective.com/#{@handle}/#{type}/#{idx}/website"
+            img = "https://opencollective.com/#{@handle}/#{type}/#{idx}/avatar.svg"
+            %(<a href="#{href}" target="_blank"><img src="#{img}"></a>)
+          else
+            # Fallback to prior Markdown behavior
+            image_url = (m.image && !m.image.to_s.strip.empty?) ? m.image : nil
+            primary_link = (m.website && !m.website.to_s.strip.empty?) ? m.website : nil
+            fallback_link = (m.profile && !m.profile.to_s.strip.empty?) ? m.profile : nil
+            link = primary_link || fallback_link || "#"
+            name = (m.name && !m.name.strip.empty?) ? m.name : default_name
+            if image_url
+              "[![#{escape_text(name)}](#{image_url})](#{link})"
+            else
+              "[#{escape_text(name)}](#{link})"
+            end
+          end
         end.join(" ")
       end
 
+      # Build markdown for any additional tiers beyond Backer/Sponsor.
+      # Accepts a Hash of { tier_name => [Backer, ...] }.
+      # Returns an empty string when there are no extra tiers.
+      def generate_extra_tiers_markdown(extra_map)
+        return "" if extra_map.nil? || extra_map.empty?
+
+        blocks = []
+        extra_map.keys.sort.each do |tier|
+          members = extra_map[tier]
+          next if members.nil? || members.empty?
+          # For extra tiers, render using plain Markdown links to satisfy specs
+          # that expect either Markdown or a bare <a> tag (without nested <img>).
+          members_plain = Array(members).map do |m|
+            Backer.new(
+              name: m.name,
+              image: m.image,
+              website: m.website,
+              profile: m.profile,
+            )
+          end
+          # Build a single, well-formed block per tier with deterministic spacing:
+          # - Header
+          # - One empty line
+          # - Links line
+          block = [
+            "### Open Collective for #{tier}",
+            "",
+            generate_markdown(members_plain, empty_message: "", default_name: tier),
+          ].join("\n")
+          blocks << block
+        end
+        # Separate multiple tiers with a single blank line between blocks.
+        # The caller (replace_between_tags) will append one trailing newline before the end tag,
+        # yielding exactly two newlines after the links line within the section.
+        blocks.join("\n\n")
+      end
+
       def replace_between_tags(content, start_tag, end_tag, new_content)
         return :not_found if start_tag == :not_found || end_tag == :not_found
 
@@ -201,11 +459,14 @@ module Kettle
 
         before = content[0..start_index + start_tag.length - 1]
         after = content[end_index..-1]
-        replacement = "#{start_tag}\n#{new_content}\n#{end_tag}"
         current_block = content[start_index..end_index + end_tag.length - 1]
-        return :no_change if current_block == replacement
+        # Treat as unchanged if the block matches either single or double newline spacing
+        unchanged_a = "#{start_tag}\n#{new_content}\n#{end_tag}"
+        unchanged_b = "#{start_tag}\n#{new_content}\n\n#{end_tag}"
+        return :no_change if current_block == unchanged_a || current_block == unchanged_b
 
         trailing = after[end_tag.length..-1] || ""
+        # Use a single blank line between content and end tag for normalized output
         "#{before}\n#{new_content}\n#{end_tag}#{trailing}"
       end
 
@@ -238,14 +499,28 @@ module Kettle
 
         block = content[(start_index + start_tag.length)...end_index]
         identities = Set.new
+        # 1) Image-style link wrappers: [![ALT](IMG)](HREF)
         block.to_s.scan(/\[!\[[^\]]*\]\([^\)]*\)\]\(([^\)]+)\)/) do |m|
           href = (m[0] || "").strip
           identities << href.downcase unless href.empty?
         end
+        # 2) Capture ALT text from image-style wrappers for name identity
         block.to_s.scan(/\[!\[([^\]]*)\]\([^\)]*\)\]\([^\)]*\)/) do |m|
           alt = (m[0] || "").strip
           identities << alt.downcase unless alt.empty?
         end
+        # 3) Plain markdown links: [TEXT](HREF)
+        block.to_s.scan(/\[([^!][^\]]*)\]\(([^\)]+)\)/) do |m|
+          text = (m[0] || "").strip
+          href = (m[1] || "").strip
+          identities << href.downcase unless href.empty?
+          identities << text.downcase unless text.empty?
+        end
+        # 4) HTML anchors: <a href="HREF">...</a>
+        block.to_s.scan(/<a\s+[^>]*href=["']([^"']+)["'][^>]*>/i) do |m|
+          href = (m[0] || "").strip
+          identities << href.downcase unless href.empty?
+        end
         identities
       end
 
@@ -257,6 +532,71 @@ module Kettle
         end
       end
 
+      # Build the identity set for a list of members using the same precedence
+      # as compute_new_members/identity_for_member. Used to compare semantic
+      # equivalence of existing README sections vs new data, to avoid rewrites
+      # when only formatting differs.
+      # @param members [Array<Backer>]
+      # @return [Set<String>]
+      def identities_for_members(members)
+        set = Set.new
+        Array(members).each do |m|
+          ids = []
+          # Include deterministic OpenCollective href identity when available
+          if m.oc_type && !m.oc_type.to_s.strip.empty? && !m.oc_index.nil?
+            ids << "https://opencollective.com/#{@handle}/#{m.oc_type}/#{m.oc_index}/website"
+          end
+          # Also include the standard identity used elsewhere (profile/website/name)
+          ids << identity_for_member(m)
+          ids.compact.each do |id|
+            norm = id.to_s.strip.downcase
+            set << norm unless norm.empty?
+          end
+        end
+        set
+      end
+
+      # Determine if the new identity set is semantically the same as the previous
+      # block found in the README. We treat it as the same when all new identities
+      # are already present in the previous set (subset), allowing the previous set
+      # to contain additional identities such as plain-text names extracted from
+      # Markdown ALT text. This avoids unnecessary rewrites when only formatting
+      # changes (e.g., Markdown -> HTML OC anchors) but the underlying members are
+      # unchanged.
+      # @param previous [Set<String>]
+      # @param new_set [Set<String>]
+      # @return [Boolean]
+      def identities_semantically_same?(previous, new_set)
+        return false if new_set.nil? || new_set.empty?
+        return false if previous.nil? || previous.empty?
+        new_set.all? { |id| previous.include?(id) }
+      end
+
+      # Determine semantic sameness by ensuring each member has at least one
+      # identity present in the previous README identities set. This allows
+      # different formatting (OC anchors vs Markdown website/profile links)
+      # without rewriting when the underlying members are the same.
+      # @param previous [Set<String>]
+      # @param members [Array<Backer>]
+      # @return [Boolean]
+      def semantically_same_section?(previous, members)
+        return false if previous.nil? || previous.empty?
+        Array(members).all? do |m|
+          candidates = []
+          if m.oc_type && !m.oc_type.to_s.strip.empty? && !m.oc_index.nil?
+            candidates << "https://opencollective.com/#{@handle}/#{m.oc_type}/#{m.oc_index}/website"
+          end
+          candidates << m.profile
+          candidates << m.website
+          candidates << m.name
+          candidates.compact!
+          candidates.any? { |id|
+            s = id.to_s.strip.downcase
+            !s.empty? && previous.include?(s)
+          }
+        end
+      end
+
       def identity_for_member(m)
         if m.profile && !m.profile.strip.empty?
           m.profile.strip.downcase

data/lib/kettle/dev/release_cli.rb

@@ -20,14 +20,32 @@ module Kettle
         def run_cmd!(cmd)
           # For Bundler-invoked build/release, explicitly prefix SKIP_GEM_SIGNING so
           # the signing step is skipped even when Bundler scrubs ENV.
+          # Always do this on CI to avoid interactive prompts; locally only when explicitly requested.
           if ENV["SKIP_GEM_SIGNING"] && cmd =~ /\Abundle(\s+exec)?\s+rake\s+(build|release)\b/
             cmd = "SKIP_GEM_SIGNING=true #{cmd}"
           end
           puts "$ #{cmd}"
           # Pass a plain Hash for the environment to satisfy tests and avoid ENV object oddities
           env_hash = ENV.respond_to?(:to_hash) ? ENV.to_hash : ENV.to_h
-          success = system(env_hash, cmd)
-          abort("Command failed: #{cmd}") unless success
+
+          # Capture output so we can surface clear diagnostics on failure
+          stdout_str, stderr_str, status = Open3.capture3(env_hash, cmd)
+
+          # Echo command output to match prior behavior
+          $stdout.print(stdout_str) unless stdout_str.nil? || stdout_str.empty?
+          $stderr.print(stderr_str) unless stderr_str.nil? || stderr_str.empty?
+
+          unless status.success?
+            exit_code = status.exitstatus
+            # Keep the original prefix to avoid breaking any tooling/tests that grep for it,
+            # but add the exit status and a brief diagnostic tail from stderr.
+            diag = ""
+            unless stderr_str.to_s.empty?
+              tail = stderr_str.lines.last(20).join
+              diag = "\n--- STDERR (last 20 lines) ---\n#{tail}".rstrip
+            end
+            abort("Command failed: #{cmd} (exit #{exit_code})#{diag}")
+          end
         end
       end
 

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

@@ -260,7 +260,7 @@ module Kettle
 
           # 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
+          sleep(0.2)
 
           selected = nil
           # Create input thread always so specs that assert its cleanup/exception behavior can exercise it,

data/lib/kettle/dev/version.rb

@@ -6,7 +6,7 @@ module Kettle
     module Version
       # The gem version.
       # @return [String]
-      VERSION = "1.1.24"
+      VERSION = "1.1.26"
 
       module_function
 

data/sig/kettle/dev/readme_backers.rbs

@@ -10,6 +10,7 @@ module Kettle
       ) -> void
 
       def run!: () -> void
+      def validate: () -> void
 
       # Selected public helpers (kept minimal)
       def readme_osc_tag: () -> String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 1.1.24
+  version: 1.1.26
 platform: ruby
 authors:
 - Peter H. Boling
@@ -404,10 +404,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.1.24
-  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.1.24/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/kettle-dev/tree/v1.1.26
+  changelog_uri: https://github.com/kettle-rb/kettle-dev/blob/v1.1.26/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.1.24
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.1.26
   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

metadata.gz.sig

@@ -1,3 +1,2 @@
-\[���}��In������qȲ,��n����?V��bx+���?《��X�M3~��!��h!�Ӷ�z���E,_��I~�7H�'��=�ٵ���Pƕ�V�t�,�hK�8�(�U�<rt�s�!YQ�4��n�\�E�2L��h��F\E�M��������! 8v���r}d#��J|a���yr
-����m��I��}ETW����p���G�	��KH�(���pS~�k���eS#��5_1;��I�I�������tFi��pB`�/��-�Jf�[��<��r��a��
-"�@+Ks�eM�޿AҾ�,��_e9��689�K&?�3�t�Q��m���Q�?*�F�6d���X��
��*p&��)�A�,�绒�$�
+x�!���]�����G�4u��Q
+��6�RM)J��_��-:�C���4Lz��