kettle-dev 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d64f3a7f29e3470e85bfa3ad0ba278f7f591c618ced02911e6bdf00f804ee128
-  data.tar.gz: 90e9d7630f0115f908efff5e5ad359ff787cb80660a44fd5b6ba63a01839fb6b
+  metadata.gz: 78bcc9bdf8d357f03e49a189ec85cdde3aae0589085735fe90f7e1843d0bf8dc
+  data.tar.gz: e8210c52d958b4e9c6d154cb18c7098a74994c20c9cff74038f52c2df1179b72
 SHA512:
-  metadata.gz: b9323a16c2cc9236888a268907031508b9b74b99feb5d149233604809e855bda0e34a03543d7cd683affe0e9139b993a31f7f746b226a9a9cec06987045d99b3
-  data.tar.gz: 48f6ef3c7424930a5840f71b2f9dcf86df2e6bb1a9b341bc29dfc15941ef6576bc2fad093b34e6d210792b70b6f5f4fbe180d86eaee21e7bd7f82f0e29396b8a
+  metadata.gz: d798f16b37df5bd1e96e94fb45c964e5ee8913724af313c04936689feb9a52b1096aba043edb5a3b1444cfeeb81e96a3e9390ce0d331d1782dd735d11a185ab1
+  data.tar.gz: 35b9bb8a37bdd71891f47c340af180999cc9658924c63c92267a4f6d6581cefbdc8e7b7c173fdc61feddb7dbc2f908f1bc7b106a09ae1470a87fb7629096ca2d

data/CHANGELOG.md

@@ -12,6 +12,18 @@ and this project adheres to [Semantic Versioning v2](https://semver.org/spec/v2.
 ### Fixed
 ### Security
 
+## [1.0.1] - 2025-08-24
+- TAG: [v1.0.1][1.0.1t]
+- COVERAGE: 100.00% -- 98/98 lines in 7 files
+- BRANCH COVERAGE: 100.00% -- 30/30 branches in 7 files
+- 94.59% documented
+### Added
+- These were documented but not yet released:
+  - `kettle-release` ruby script for safely, securely, releasing a gem.
+      - This may move to its own gem in the future.
+  - `kettle-readme-backers` ruby script for integrating Open Source Collective backers into a README.md file.
+      - This may move to its own gem in the future.
+
 ## [1.0.0] - 2025-08-24
 - TAG: [v1.0.0][1.0.0t]
 - COVERAGE: 100.00% -- 98/98 lines in 7 files
@@ -37,11 +49,9 @@ and this project adheres to [Semantic Versioning v2](https://semver.org/spec/v2.
 - `ci:act` rake task CLI menu / scoreboard for a project's GHA workflows
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
-- `kettle-release` ruby script for safely, securely, releasing a gem.
-  - This may move to its own gem in the future.
-- `kettle-readme-backers` ruby script for integrating Open Source Collective backers into a README.md file.
-  - This may move to its own gem in the future.
 
-[Unreleased]: https://gitlab.com/kettle-rb/kettle-dev/-/compare/v1.0.0...HEAD
+[Unreleased]: https://gitlab.com/kettle-rb/kettle-dev/-/compare/v1.0.1...HEAD
+[1.0.1]: https://gitlab.com/kettle-rb/kettle-dev/-/compare/v1.0.0...v1.0.1
+[1.0.1t]: https://gitlab.com/kettle-rb/kettle-dev/-/tags/v1.0.1
 [1.0.0]: https://gitlab.com/kettle-rb/kettle-dev/-/compare/a427c302df09cfe4253a7c8d400333f9a4c1a208...v1.0.0
 [1.0.0t]: https://gitlab.com/kettle-rb/kettle-dev/-/tags/v1.0.0

data/checksums/kettle-dev-1.0.1.gem.sha256

@@ -0,0 +1 @@
+5b92c8a76f54954791e4154bb22594dbc9dd4f0e06d9d4c5db15a32aa2718ede

data/checksums/kettle-dev-1.0.1.gem.sha512

@@ -0,0 +1 @@
+5cac18505a8f780d3897f1d900a662c896537056441b1a8178531355a4b10198bee0bdc62216ab2036b640adada34911bc30b813f715a14a464d797718d7a065

data/exe/kettle-commit-msg

@@ -0,0 +1,185 @@
+#!/usr/bin/env ruby
+# vim: set syntax=ruby
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "rubygems"
+require "bundler/setup"
+
+# Standard library
+require "erb"
+
+# ENV variable control (set in .envrc, or .env.local)
+# BRANCH_RULE_TYPE = jira, or another type of branch rule validation, or false to disable
+# FOOTER_APPEND = true/false append commit message footer
+BRANCH_RULES = {
+  "jira" => /^(?<story_type>(hotfix)|(bug)|(feature)|(candy))\/(?<story_id>\d{8,})-.+\Z/,
+}
+BRANCH_RULE_TYPE = (validate = ENV.fetch("GIT_HOOK_BRANCH_VALIDATE", "false")) && !validate.casecmp?("false") && validate
+
+# Called the "JIRA pattern", because of traditional use with JIRA.
+if (branch_rule = BRANCH_RULES[BRANCH_RULE_TYPE])
+  # branches should be named like:
+  #	<story_type>/<story_id>-explosion-in-the-fudge-factory-spec-suite-fix
+  #	where story type is one of "hotfix", "bug", "feature", "candy"
+  #
+  branch = %x(git branch 2> /dev/null | grep -e ^* | awk '{print $2}')
+  match_data = branch.match(branch_rule)
+  # NOTE: `match` will return nil if match fails, otherwise an instance of MatchData.
+  # If not nil then we are assured matches for both regex capture groups
+  # match_data_or_nil[:story_type] will be one of "hotfix", "bug", "feature", "candy"
+  # match_data_or_nil[:story_id] will be a numeric string
+
+  if !match_data.nil?
+    commit_msg = File.read(ARGV[0])
+    unless commit_msg.include?(match_data[:story_id])
+      commit_msg = <<~EOS
+        #{commit_msg.strip}
+        [#{match_data[:story_type]}][#{match_data[:story_id]}]
+      EOS
+      File.open(ARGV[0], "w") do |file|
+        file.print(commit_msg)
+      end
+    end
+  end
+else
+  # puts "No branch rule configured (set GIT_HOOK_BRANCH_VALIDATE=jira to enforce rules for jira style branch names)"
+end
+
+class GitCommitFooter
+  # Prefer project-local .git-hooks (repo root), then fallback to global ~/.git-hooks
+  NAME_ASSIGNMENT_REGEX = /\bname\s*=\s*(["'])([^"']+)\1/.freeze
+  FOOTER_APPEND = ENV.fetch("GIT_HOOK_FOOTER_APPEND", "false").casecmp("true").zero?
+  SENTINEL = ENV["GIT_HOOK_FOOTER_SENTINEL"] # No default to avoid accidental duplicate commit of a footer via ammended commits
+  raise "Set GIT_HOOK_FOOTER_SENTINEL=<footer sentinel> in .env.local (e.g., '⚡️ A message from a fellow meat-based-AI ⚡️')" if FOOTER_APPEND && SENTINEL.nil? || SENTINEL.empty?
+
+  class << self
+    def git_toplevel
+      toplevel = nil
+      begin
+        # 'git rev-parse --show-toplevel' returns the repo root when run anywhere inside the repo
+        out = %x(git rev-parse --show-toplevel 2>/dev/null)
+        toplevel = out.strip unless out.nil? || out.empty?
+      rescue StandardError
+        # ignore
+      end
+      toplevel
+    end
+
+    def local_hooks_dir
+      top = git_toplevel
+      return unless top && !top.empty?
+      File.join(top, ".git-hooks")
+    end
+
+    def global_hooks_dir
+      File.join(ENV["HOME"], ".git-hooks")
+    end
+
+    def hooks_path_for(filename)
+      local_dir = local_hooks_dir
+      if local_dir
+        local_path = File.join(local_dir, filename)
+        return local_path if File.file?(local_path)
+      end
+      File.join(global_hooks_dir, filename)
+    end
+
+    def commit_goalie_path
+      hooks_path_for("commit-subjects-goalie.txt")
+    end
+
+    # Determine whether the commit subject allows footer append, based on optional goalie file
+    # ~/.git-hooks/commit-subjects-goalie.txt
+    # - If present, only allow appending when the first line of the commit message starts with one of the non-commented prefixes
+    # - If absent, disallow footer
+    def goalie_allows_footer?(subject_line)
+      goalie_path = commit_goalie_path
+      return false unless File.file?(goalie_path)
+
+      prefixes = File.read(goalie_path).lines.map { |l| l.strip }.reject { |l| l.empty? || l.start_with?("#") }
+      # If the file exists but has no usable lines, treat as deny-all per goalie intent
+      return false if prefixes.empty?
+
+      subj = subject_line.to_s.strip
+      prefixes.any? { |prefix| subj.start_with?(prefix) }
+    end
+
+    def render(*argv)
+      commit_msg = File.read(argv[0])
+      subject_line = commit_msg.lines.first.to_s
+      if GitCommitFooter::FOOTER_APPEND && goalie_allows_footer?(subject_line)
+        if commit_msg.include?(GitCommitFooter::SENTINEL)
+          # This is a commit message that has already been appended
+          # This will happen if the commit message is edited and re-committed
+          # puts "FOOTER_APPEND is true, skipping footer append"
+          exit(0)
+        else
+          footer_binding = GitCommitFooter.new
+          # Append footer to the commit message
+          File.open(argv[0], "w") do |file|
+            file.print(commit_msg)
+            file.print("\n")
+            file.print(footer_binding.render)
+          end
+        end
+      else
+        # Skipping footer append (either FOOTER_APPEND is false, or goalie did not allow it)
+      end
+    end
+  end
+
+  def initialize
+    @pwd = Dir.pwd
+    @gemspecs = Dir["*.gemspec"]
+    @spec = @gemspecs.first
+    @gemspec_path = File.expand_path(@spec, @pwd)
+    @gem_name = parse_gemspec_name || derive_gem_name
+  end
+
+  # Render ERB with binding variables
+  def render
+    ERB.new(template).result(binding)
+  end
+
+  private
+
+  # Lightweight parse for gem name to avoid full Gem::Specification load
+  def parse_gemspec_name
+    begin
+      content = File.read(@gemspec_path)
+      # Look for name assignment patterns like:
+      #   spec.name = "my_gem" OR Gem::Specification.new do |spec|; spec.name = 'my_gem'
+      @name_index = content =~ NAME_ASSIGNMENT_REGEX
+      if @name_index
+        return $2
+      end
+    rescue StandardError
+      # fall through
+    end
+    nil
+  end
+
+  # No-parse derivation of gem name, when parsing gemspec fails
+  def derive_gem_name
+    File.basename(@gemspec_path, ".*") if @gemspec_path
+  end
+
+  # Example
+  #
+  #     ⚡️ A message from a fellow meat-based-AI ⚡️
+  #     I ❤️ working on <%= @gem_name %>.
+  #
+  # The first line is the footer sentinel (which does appear in the commit).
+  # The second line, and any additional, is the main body of the footer.
+  #
+  # The sentinel must be set in an ENV variable (e.g., in your .env.local file):
+  #
+  #   export GIT_HOOK_FOOTER_SENTINEL="⚡️ A message from a fellow meat-based-AI ⚡️"
+  #
+  def template
+    File.read(self.class.hooks_path_for("footer-template.erb.txt"))
+  end
+end
+
+GitCommitFooter.render(*ARGV)

data/exe/kettle-readme-backers

@@ -0,0 +1,355 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Updates README.md backers and sponsors sections using data from Open Collective
+# backers.json and sponsors.json for the configured handle.
+#
+# Backers (individuals) section markers supported (first match wins):
+#   <!-- OPENCOLLECTIVE:START --> ... <!-- OPENCOLLECTIVE:END -->
+#   <!-- OPENCOLLECTIVE-INDIVIDUALS:START --> ... <!-- OPENCOLLECTIVE-INDIVIDUALS:END -->
+# Sponsors (organizations) section markers:
+#   <!-- OPENCOLLECTIVE-ORGANIZATIONS:START --> ... <!-- OPENCOLLECTIVE-ORGANIZATIONS:END -->
+#
+# Handle resolution order:
+#   1. ENV["OPENCOLLECTIVE_HANDLE"] if present
+#   2. .opencollective.yml's `collective:` key in project root if present
+#   3. Abort with error
+#
+# Usage:
+#   OPENCOLLECTIVE_HANDLE=kettle-rb exe/kettle-readme-backers
+#   # or ensure .opencollective.yml exists with collective: "kettle-rb"
+
+require "rubygems"
+require "bundler/setup"
+
+require "yaml"
+require "json"
+require "uri"
+require "net/http"
+require "set"
+
+module Kettle
+  module Dev
+    class ReadmeBackers
+      DEFAULT_AVATAR = "https://opencollective.com/static/images/default-avatar.png"
+      README_PATH = File.expand_path("../README.md", __dir__)
+      OC_YML_PATH = File.expand_path("../.opencollective.yml", __dir__)
+      README_OSC_TAG_DEFAULT = "OPENCOLLECTIVE"
+      COMMIT_SUBJECT_DEFAULT = "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜"
+
+      Backer = Struct.new(:name, :image, :website, :profile, keyword_init: true)
+
+      def initialize(handle: nil, readme_path: README_PATH)
+        @handle = handle || resolve_handle
+        @readme_path = readme_path
+      end
+
+      def run!
+        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)
+        prev_sponsor_identities = extract_section_identities(readme, s_start_prev, s_end_prev)
+
+        # Backers (individuals)
+        backers = fetch_members("backers.json")
+        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)
+        case updated
+        when :not_found
+          # Do not exit yet; we may still update sponsors.
+          updated_readme = readme
+          backers_changed = false
+          new_backers = []
+        when :no_change
+          updated_readme = readme
+          backers_changed = false
+          new_backers = []
+        else
+          updated_readme = updated
+          backers_changed = true
+          new_backers = compute_new_members(prev_backer_identities, backers)
+        end
+
+        # Sponsors (organizations)
+        sponsors = fetch_members("sponsors.json")
+        sponsors_md = generate_markdown(sponsors, empty_message: "No sponsors yet. Be the first!", default_name: "Sponsor")
+        s_start, s_end = detect_sponsor_tags(updated_readme)
+        updated2 = replace_between_tags(updated_readme, s_start, s_end, sponsors_md)
+        case updated2
+        when :not_found
+          sponsors_changed = false
+          final = updated_readme
+          new_sponsors = []
+        when :no_change
+          sponsors_changed = false
+          final = updated_readme
+          new_sponsors = []
+        else
+          sponsors_changed = true
+          final = updated2
+          new_sponsors = compute_new_members(prev_sponsor_identities, sponsors)
+        end
+
+        if !backers_changed && !sponsors_changed
+          if b_start == :not_found && s_start == :not_found
+            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]}.")
+            exit(2)
+          end
+          puts "No changes to backers or sponsors sections in #{@readme_path}."
+          return
+        end
+
+        File.write(@readme_path, final)
+        msgs = []
+        msgs << "backers" if backers_changed
+        msgs << "sponsors" if sponsors_changed
+        puts "Updated #{msgs.join(" and ")} section#{{true => "s", false => ""}[msgs.size > 1]} in #{@readme_path}."
+
+        # Compose and perform commit with mentions if in a git repo
+        perform_git_commit(new_backers, new_sponsors) if git_repo? && (backers_changed || sponsors_changed)
+      end
+
+      private
+
+      def readme_osc_tag
+        env = ENV["KETTLE_DEV_BACKER_README_OSC_TAG"].to_s
+        return env unless env.strip.empty?
+        if File.file?(OC_YML_PATH)
+          begin
+            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
+              return from_yml unless from_yml.nil? || from_yml.strip.empty?
+            end
+          rescue StandardError
+            # ignore yaml errors and fall back
+          end
+        end
+        README_OSC_TAG_DEFAULT
+      end
+
+      def tag_strings
+        base = readme_osc_tag
+        {
+          generic_start: "<!-- #{base}:START -->",
+          generic_end: "<!-- #{base}:END -->",
+          individuals_start: "<!-- #{base}-INDIVIDUALS:START -->",
+          individuals_end: "<!-- #{base}-INDIVIDUALS:END -->",
+          orgs_start: "<!-- #{base}-ORGANIZATIONS:START -->",
+          orgs_end: "<!-- #{base}-ORGANIZATIONS:END -->",
+        }
+      end
+
+      def resolve_handle
+        env = ENV["OPENCOLLECTIVE_HANDLE"]
+        return env unless env.nil? || env.strip.empty?
+        if File.file?(OC_YML_PATH)
+          yml = YAML.safe_load(File.read(OC_YML_PATH))
+          handle = yml.is_a?(Hash) ? yml["collective"] || yml[:collective] : nil
+          return handle.to_s unless handle.nil? || handle.to_s.strip.empty?
+        end
+        abort("ERROR: Open Collective handle not provided. Set OPENCOLLECTIVE_HANDLE or add 'collective: <handle>' to .opencollective.yml.")
+      end
+
+      def fetch_members(path)
+        url = URI("https://opencollective.com/#{@handle}/#{path}")
+        response = Net::HTTP.start(url.host, url.port, use_ssl: url.scheme == "https") do |conn|
+          conn.read_timeout = 10
+          conn.open_timeout = 5
+          req = Net::HTTP::Get.new(url)
+          req["User-Agent"] = "kettle-dev/README-backers"
+          conn.request(req)
+        end
+        return [] unless response.is_a?(Net::HTTPSuccess)
+        parsed = JSON.parse(response.body)
+        Array(parsed).map do |h|
+          Backer.new(
+            name: h["name"],
+            image: (h["image"].to_s.strip.empty? ? nil : h["image"]),
+            website: (h["website"].to_s.strip.empty? ? nil : h["website"]),
+            profile: (h["profile"].to_s.strip.empty? ? nil : h["profile"]),
+          )
+        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})"
+        end.join(" ")
+      end
+
+      def replace_between_tags(content, start_tag, end_tag, new_content)
+        return :not_found if start_tag == :not_found || end_tag == :not_found
+        start_index = content.index(start_tag)
+        end_index = content.index(end_tag)
+        return :not_found if start_index.nil? || end_index.nil? || end_index < start_index
+        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
+        trailing = after[end_tag.length..-1] || ""
+        "#{before}\n#{new_content}\n#{end_tag}#{trailing}"
+      end
+
+      def detect_backer_tags(content)
+        ts = tag_strings
+        if content.include?(ts[:generic_start]) && content.include?(ts[:generic_end])
+          [ts[:generic_start], ts[:generic_end]]
+        elsif content.include?(ts[:individuals_start]) && content.include?(ts[:individuals_end])
+          [ts[:individuals_start], ts[:individuals_end]]
+        else
+          [:not_found, :not_found]
+        end
+      end
+
+      def detect_sponsor_tags(content)
+        ts = tag_strings
+        if content.include?(ts[:orgs_start]) && content.include?(ts[:orgs_end])
+          [ts[:orgs_start], ts[:orgs_end]]
+        else
+          [:not_found, :not_found]
+        end
+      end
+
+      # Extract identity tokens from the current README section between start/end tags
+      # Identity priority used for comparison:
+      #   href (profile/website URL) downcased, else alt text (name) downcased
+      def extract_section_identities(content, start_tag, end_tag)
+        return Set.new unless start_tag && end_tag && start_tag != :not_found && end_tag != :not_found
+        start_index = content.index(start_tag)
+        end_index = content.index(end_tag)
+        return Set.new if start_index.nil? || end_index.nil? || end_index < start_index
+        block = content[(start_index + start_tag.length)...end_index]
+        identities = Set.new
+        # Match patterns like: [![Alt](image_url)](link_url)
+        block.to_s.scan(/\[!\[[^\]]*\]\([^\)]*\)\]\(([^\)]+)\)/) do |m|
+          href = (m[0] || "").strip
+          identities << href.downcase unless href.empty?
+        end
+        # Also capture alt texts in case links are missing
+        block.to_s.scan(/\[!\[([^\]]*)\]\([^\)]*\)\]\([^\)]*\)/) do |m|
+          alt = (m[0] || "").strip
+          identities << alt.downcase unless alt.empty?
+        end
+        identities
+      end
+
+      def compute_new_members(previous_identities, members)
+        prev = previous_identities || Set.new
+        members.select do |m|
+          id = identity_for_member(m)
+          !prev.include?(id)
+        end
+      end
+
+      def identity_for_member(m)
+        if m.profile && !m.profile.strip.empty?
+          m.profile.strip.downcase
+        elsif m.website && !m.website.strip.empty?
+          m.website.strip.downcase
+        elsif m.name && !m.name.strip.empty?
+          m.name.strip.downcase
+        else
+          ""
+        end
+      end
+
+      def mention_for_member(m, default_name: "Member")
+        handle = github_handle_from_urls(m.profile, m.website)
+        return "@#{handle}" if handle
+        name = (m.name && !m.name.strip.empty?) ? m.name.strip : default_name
+        name
+      end
+
+      def github_handle_from_urls(*urls)
+        urls.compact.each do |u|
+          begin
+            uri = URI.parse(u)
+          rescue URI::InvalidURIError
+            next
+          end
+          next unless uri&.host&.downcase&.end_with?("github.com")
+          path = (uri.path || "").sub(%r{^/}, "").sub(%r{/$}, "")
+          next if path.empty?
+          parts = path.split("/")
+          # github.com/sponsors/<handle> or github.com/<handle>/...
+          candidate = if parts[0].downcase == "sponsors" && parts[1]
+            parts[1]
+          else
+            parts[0]
+          end
+          candidate = candidate.gsub(%r{[^a-zA-Z0-9-]}, "")
+          return candidate unless candidate.empty?
+        end
+        nil
+      end
+
+      def perform_git_commit(new_backers, new_sponsors)
+        backer_mentions = new_backers.map { |m| mention_for_member(m, default_name: "Backer") }.uniq
+        sponsor_mentions = new_sponsors.map { |m| mention_for_member(m, default_name: "Subscriber") }.uniq
+        title = commit_subject
+        lines = [title]
+        lines << ""
+        lines << "Backers: #{backer_mentions.join(", ")}" unless backer_mentions.empty?
+        lines << "Subscribers: #{sponsor_mentions.join(", ")}" unless sponsor_mentions.empty?
+        message = lines.join("\n")
+        # Stage and commit README.md
+        system("git", "add", @readme_path)
+        # Only commit if README is staged/changed
+        if system("git", "diff", "--cached", "--quiet")
+          # nothing staged; skip commit
+          return
+        end
+        system("git", "commit", "-m", message)
+      end
+
+      def commit_subject
+        env = ENV["KETTLE_README_BACKERS_COMMIT_SUBJECT"].to_s
+        return env unless env.strip.empty?
+        # Fallback to .opencollective.yml key: readme-backers-commit-subject
+        if File.file?(OC_YML_PATH)
+          begin
+            yml = YAML.safe_load(File.read(OC_YML_PATH))
+            if yml.is_a?(Hash)
+              from_yml = yml["readme-backers-commit-subject"] || yml[:"readme-backers-commit-subject"]
+              from_yml = from_yml.to_s if from_yml
+              return from_yml unless from_yml.nil? || from_yml.strip.empty?
+            end
+          rescue StandardError
+            # ignore yaml read errors and fall back to default
+          end
+        end
+        COMMIT_SUBJECT_DEFAULT
+      end
+
+      def git_repo?
+        system("git", "rev-parse", "--is-inside-work-tree", out: File::NULL, err: File::NULL)
+      end
+
+      def escape_text(text)
+        text.gsub("[", "\\[").gsub("]", "\\]")
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Kettle::Dev::ReadmeBackers.new.run!
+end

data/exe/kettle-release

@@ -0,0 +1,327 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# kettle-release: Automate release steps from CONTRIBUTING.md
+# - Runs sanity checks
+# - Ensures version/changelog updated (with confirmation)
+# - Commits and pushes a release prep commit
+# - Ensures on trunk, up-to-date
+# - Exports SOURCE_DATE_EPOCH for reproducible checksums
+# - Runs `bundle exec rake build` (expects PEM password unless SKIP_GEM_SIGNING)
+#   - If signing not skipped and no public cert in certs/<user>.pem, aborts with guidance
+# - Runs bin/gem_checksums
+# - Runs `bundle exec rake release` (expects PEM password and RubyGems MFA OTP)
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "rubygems"
+require "bundler/setup"
+
+require "open3"
+require "shellwords"
+require "time"
+require "fileutils"
+require "net/http"
+require "json"
+require "uri"
+require "kettle/dev/ci_helpers"
+require "ruby-progressbar"
+
+module Kettle
+  module Dev
+    class ReleaseCLI
+      def initialize
+        @root = File.expand_path("..", __dir__)
+      end
+
+      def run
+        puts "== kettle-release =="
+
+        run_cmd!("bin/setup")
+        run_cmd!("bin/rake")
+
+        version = detect_version
+        puts "Detected version: #{version.inspect}"
+        puts "Have you updated lib/**/version.rb and CHANGELOG.md for v#{version}? [y/N]"
+        print("> ")
+        ans = $stdin.gets&.strip
+        abort("Aborted: please update version.rb and CHANGELOG.md, then re-run.") unless ans&.downcase&.start_with?("y")
+
+        # Re-run checks (and refresh Gemfile.lock)
+        run_cmd!("bin/setup")
+        run_cmd!("bin/rake")
+
+        # Update Appraisal gemfiles if Appraisals file is present
+        appraisals_path = File.join(@root, "Appraisals")
+        if File.file?(appraisals_path)
+          puts "Appraisals detected at #{appraisals_path}. Running: bin/rake appraisal:update"
+          run_cmd!("bin/rake appraisal:update")
+        else
+          puts "No Appraisals file found; skipping appraisal:update"
+        end
+
+        ensure_git_user!
+        commit_release_prep!(version)
+
+        trunk = detect_trunk_branch
+        feature = current_branch
+        puts "Trunk branch detected: #{trunk}"
+        ensure_trunk_synced_before_push!(trunk, feature)
+
+        push!
+
+        # After pushing, ensure the CI workflows for this project are passing
+        monitor_workflows_after_push!
+
+        # If all workflows are passing, merge the feature branch into trunk and push trunk
+        merge_feature_into_trunk_and_push!(trunk, feature)
+
+        # Ensure we are on trunk for the remaining steps
+        checkout!(trunk)
+        pull!(trunk)
+
+        export_source_date_epoch!
+
+        ensure_signing_setup_or_skip!
+        # Build: expect PEM password prompt unless SKIP_GEM_SIGNING
+        puts "Running build (you may be prompted for the signing key password)..."
+        run_cmd!("bundle exec rake build")
+
+        # Checksums (commits, but does not push)
+        run_cmd!("bin/gem_checksums")
+
+        # Release: expect PEM password + RubyGems MFA OTP
+        puts "Running release (you may be prompted for signing key password and RubyGems MFA OTP)..."
+        run_cmd!("bundle exec rake release")
+
+        puts "\nRelease complete. Don't forget to push the checksums commit if needed."
+      end
+
+      private
+
+      # Monitor GitHub Actions workflows discovered by ci:act logic.
+      # Checks one workflow per second in a round-robin loop until all pass, or any fails.
+      def monitor_workflows_after_push!
+        root = Kettle::Dev::CIHelpers.project_root
+        workflows = Kettle::Dev::CIHelpers.workflows_list(root)
+        if workflows.empty?
+          puts "No workflows detected under .github/workflows; skipping CI checks."
+          return
+        end
+
+        owner, repo = Kettle::Dev::CIHelpers.repo_info
+        branch = Kettle::Dev::CIHelpers.current_branch
+        unless owner && repo && branch
+          puts "Unable to determine repository or branch; skipping CI checks."
+          return
+        end
+
+        total = workflows.size
+        passed = {}
+        idx = 0
+        puts "Ensuring CI workflows pass on branch #{branch} (#{owner}/#{repo})"
+        pbar = ProgressBar.create(title: "CI", total: total, format: "%t %b %c/%C", length: 30)
+
+        loop do
+          wf = workflows[idx]
+          run = Kettle::Dev::CIHelpers.latest_run(owner: owner, repo: repo, workflow_file: wf, branch: branch)
+          if run
+            if Kettle::Dev::CIHelpers.success?(run)
+              unless passed[wf]
+                passed[wf] = true
+                pbar.increment
+              end
+            elsif Kettle::Dev::CIHelpers.failed?(run)
+              # Fail fast with link to the failed run
+              puts
+              url = run["html_url"] || "https://github.com/#{owner}/#{repo}/actions/workflows/#{wf}"
+              abort("Workflow failed: #{wf} -> #{url}")
+            end
+          end
+
+          break if passed.size == total
+
+          idx = (idx + 1) % total
+          sleep(1)
+        end
+        pbar.finish unless pbar.finished?
+        puts "\nAll workflows passing (#{passed.size}/#{total})."
+      end
+
+      def run_cmd!(cmd)
+        puts "$ #{cmd}"
+        success = system(cmd)
+        abort("Command failed: #{cmd}") unless success
+      end
+
+      def git_output(args)
+        out, status = Open3.capture2("git", *args)
+        [out.strip, status.success?]
+      end
+
+      def check_git_clean!
+        out, ok = git_output(["status", "--porcelain"])
+        abort("Git working tree is not clean. Commit/stash changes before releasing.\n\n#{out}") unless ok && out.empty?
+      end
+
+      def ensure_git_user!
+        name, ok1 = git_output(["config", "user.name"])
+        email, ok2 = git_output(["config", "user.email"])
+        abort("Git user.name or user.email not configured.") unless ok1 && ok2 && !name.empty? && !email.empty?
+      end
+
+      def detect_version
+        # Look for lib/**/version.rb and extract VERSION constant string
+        candidates = Dir[File.join(@root, "lib", "**", "version.rb")]
+        abort("Could not find version.rb under lib/**.") if candidates.empty?
+        path = candidates.min
+        content = File.read(path)
+        m = content.match(/VERSION\s*=\s*(["'])([^"']+)\1/)
+        abort("VERSION constant not found in #{path}.") unless m
+        m[2]
+      end
+
+      def commit_release_prep!(version)
+        msg = "🔖 Prepare release v#{version}"
+        # Only commit if there are changes (version/changelog)
+        out, _ = git_output(["status", "--porcelain"])
+        if out.empty?
+          puts "No changes to commit for release prep (continuing)."
+        else
+          run_cmd!(%(git commit -am #{Shellwords.escape(msg)}))
+        end
+      end
+
+      def push!
+        puts "$ git push"
+        success = system("git push")
+        unless success
+          warn("Normal push failed; retrying with force push...")
+          run_cmd!("git push -f")
+        end
+      end
+
+      def detect_trunk_branch
+        out, ok = git_output(["remote", "show", "origin"])
+        abort("Failed to get origin remote info.") unless ok
+        m = out.lines.find { |l| l.include?("HEAD branch") }
+        abort("Unable to detect trunk branch from origin.") unless m
+        m.split.last
+      end
+
+      def checkout!(branch)
+        run_cmd!("git checkout #{Shellwords.escape(branch)}")
+      end
+
+      def pull!(branch)
+        run_cmd!("git pull origin #{Shellwords.escape(branch)}")
+      end
+
+      def current_branch
+        out, ok = git_output(["rev-parse", "--abbrev-ref", "HEAD"])
+        ok ? out : nil
+      end
+
+      def list_remotes
+        out, ok = git_output(["remote"])
+        ok ? out.split(/\s+/).reject(&:empty?) : []
+      end
+
+      def has_remote?(name)
+        list_remotes.include?(name)
+      end
+
+      def remote_branch_exists?(remote, branch)
+        _out, ok = git_output(["show-ref", "--verify", "--quiet", "refs/remotes/#{remote}/#{branch}"])
+        ok
+      end
+
+      def ahead_behind_counts(local_ref, remote_ref)
+        out, ok = git_output(["rev-list", "--left-right", "--count", "#{local_ref}...#{remote_ref}"])
+        return [0, 0] unless ok && !out.empty?
+        parts = out.split
+        left = parts[0].to_i
+        right = parts[1].to_i
+        [left, right]
+      end
+
+      def trunk_behind_remote?(trunk, remote)
+        # If the remote branch doesn't exist, treat as not behind
+        return false unless remote_branch_exists?(remote, trunk)
+        _ahead, behind = ahead_behind_counts(trunk, "#{remote}/#{trunk}")
+        behind.positive?
+      end
+
+      def ensure_trunk_synced_before_push!(trunk, feature)
+        if has_remote?("all")
+          puts "Remote 'all' detected. Fetching from all remotes and enforcing strict trunk parity..."
+          run_cmd!("git fetch --all")
+          remotes = list_remotes
+          missing_from = []
+          remotes.each do |r|
+            next if r == "all"
+            if remote_branch_exists?(r, trunk)
+              _ahead, behind = ahead_behind_counts(trunk, "#{r}/#{trunk}")
+              missing_from << r if behind.positive?
+            end
+          end
+          unless missing_from.empty?
+            abort("Local #{trunk} is missing commits present on: #{missing_from.join(", ")}. Please sync trunk first.")
+          end
+          puts "Local #{trunk} has all commits from remotes: #{(remotes - ["all"]).join(", ")}"
+          return
+        end
+
+        # Default behavior: ensure local trunk is not behind origin/trunk; if it is, rebase flows
+        run_cmd!("git fetch origin #{Shellwords.escape(trunk)}")
+        if trunk_behind_remote?(trunk, "origin")
+          puts "Local #{trunk} is behind origin/#{trunk}. Rebasing..."
+          cur = current_branch
+          checkout!(trunk) unless cur == trunk
+          run_cmd!("git pull --rebase origin #{Shellwords.escape(trunk)}")
+          checkout!(feature) unless feature.nil? || feature == trunk
+          run_cmd!("git rebase #{Shellwords.escape(trunk)}")
+          puts "Rebase complete. Will push updated branch next."
+        else
+          puts "Local #{trunk} is up to date with origin/#{trunk}."
+        end
+      end
+
+      def merge_feature_into_trunk_and_push!(trunk, feature)
+        return if feature.nil? || feature == trunk
+        puts "Merging #{feature} into #{trunk} (after CI success)..."
+        checkout!(trunk)
+        run_cmd!("git pull --rebase origin #{Shellwords.escape(trunk)}")
+        run_cmd!("git merge #{Shellwords.escape(feature)}")
+        run_cmd!("git push origin #{Shellwords.escape(trunk)}")
+        puts "Merged #{feature} into #{trunk} and pushed. The PR (if any) should auto-close."
+      end
+
+      def export_source_date_epoch!
+        epoch = Time.now.to_i
+        ENV["SOURCE_DATE_EPOCH"] = epoch.to_s
+        puts "Exported SOURCE_DATE_EPOCH=#{epoch}"
+      end
+
+      def ensure_signing_setup_or_skip!
+        return if ENV.key?("SKIP_GEM_SIGNING")
+
+        user = ENV.fetch("GEM_CERT_USER", ENV["USER"])
+        cert_path = File.join(@root, "certs", "#{user}.pem")
+        unless File.exist?(cert_path)
+          abort(<<~MSG)
+            Gem signing appears enabled but no public cert found at:
+              #{cert_path}
+            Add your public key to certs/<USER>.pem (or set GEM_CERT_USER), or set SKIP_GEM_SIGNING to build unsigned.
+          MSG
+        end
+        puts "Found signing cert: #{cert_path}"
+        puts "When prompted during build/release, enter the PEM password for ~/.ssh/gem-private_key.pem"
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Kettle::Dev::ReleaseCLI.new.run
+end

data/lib/kettle/dev/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Peter H. Boling
@@ -188,7 +188,10 @@ description: "\U0001F372 Kettle::Dev is a meta tool from kettle-rb to streamline
   Fund overlooked open source projects - bottom of stack, dev/test dependencies: floss-funding.dev"
 email:
 - floss@galtzo.com
-executables: []
+executables:
+- kettle-commit-msg
+- kettle-readme-backers
+- kettle-release
 extensions: []
 extra_rdoc_files:
 - CHANGELOG.md
@@ -202,6 +205,8 @@ extra_rdoc_files:
 - SECURITY.md
 - checksums/kettle-dev-1.0.0.gem.sha256
 - checksums/kettle-dev-1.0.0.gem.sha512
+- checksums/kettle-dev-1.0.1.gem.sha256
+- checksums/kettle-dev-1.0.1.gem.sha512
 files:
 - CHANGELOG.md
 - CITATION.cff
@@ -214,6 +219,11 @@ files:
 - SECURITY.md
 - checksums/kettle-dev-1.0.0.gem.sha256
 - checksums/kettle-dev-1.0.0.gem.sha512
+- checksums/kettle-dev-1.0.1.gem.sha256
+- checksums/kettle-dev-1.0.1.gem.sha512
+- exe/kettle-commit-msg
+- exe/kettle-readme-backers
+- exe/kettle-release
 - lib/kettle-dev.rb
 - lib/kettle/dev.rb
 - lib/kettle/dev/ci_helpers.rb
@@ -229,10 +239,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com/
-  source_code_uri: https://github.com/galtzo-floss/kettle-dev/tree/v1.0.0
-  changelog_uri: https://github.com/galtzo-floss/kettle-dev/blob/v1.0.0/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/kettle-dev/tree/v1.0.1
+  changelog_uri: https://github.com/galtzo-floss/kettle-dev/blob/v1.0.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.0.0
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/1.0.1
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/galtzo-floss/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev