puma-release 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8638586debf06bfeee9e4acaafb5e12eece6a740a10e8e1963101f2cf1fc81d1
+  data.tar.gz: ef35f60ebbec7c25836f71484f97adf16f591a383718a66ce7a33d488ba278e1
+SHA512:
+  metadata.gz: 1821c0185b0aceea981e75a229a3d62f404261de70998474ccca5b4444cd3f7554e68e011d981fece8a39a1f33a17f44c99fa3c22487f6010d3d1953dc9c00b2
+  data.tar.gz: a063a259865d0f5b942522c886bd5fba628039829b7e31305e716691bde1b5bfb97bbd9cdbf18193fe92e223e059accfdad1ec9425db2f36754ba8e9370e733b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Berkopec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,114 @@
+# puma-release
+
+Automate Puma releases from a local Puma checkout.
+
+`puma-release` handles the repeatable parts of the Puma release process: checking repo state, proposing the version bump, updating release files, opening the release PR, building gems, and publishing the GitHub release. It follows the upstream [`Release.md`](https://github.com/puma/puma/blob/main/Release.md) workflow.
+
+## Requirements
+
+- `git`, `gh`, `bundle`
+- GPG signing configured for commits and tags
+- An AI agent set via `AGENT_CMD` (defaults to `claude`) for changelog and version bump generation
+- [communique](https://github.com/basecamp/communique) (optional) — if available with `ANTHROPIC_API_KEY` set, it is used instead of the AI agent for changelog generation
+
+```sh
+printf "source 'https://rubygems.org'\ngem 'puma-release'\n" > Gemfile && bundle install
+```
+
+## Quickstart
+
+```sh
+exe/puma-release --repo-dir /path/to/puma run
+```
+
+`run` detects the current release stage and executes the right step. If nothing needs doing, it says so.
+
+## Common workflows
+
+**Prepare against your fork:**
+
+```sh
+exe/puma-release --repo-dir /path/to/puma --release-repo yourname/puma run
+```
+
+**Real release to `puma/puma`:**
+
+```sh
+exe/puma-release --repo-dir /path/to/puma --live --release-repo puma/puma run
+```
+
+**Stable branch (patch) release:**
+
+Check out the stable branch in your Puma clone first, then:
+
+```sh
+exe/puma-release --repo-dir /path/to/puma --live --release-repo puma/puma run
+```
+
+`puma-release` auto-detects the base branch from your current git branch. Pass `--base-branch` to override:
+
+```sh
+exe/puma-release --repo-dir /path/to/puma --base-branch 6-1-stable --live --release-repo puma/puma run
+```
+
+**Skip CI during prepare:**
+
+```sh
+exe/puma-release --repo-dir /path/to/puma --skip-ci-check prepare
+```
+
+## Commands
+
+```sh
+puma-release [options] [command]
+```
+
+| Command | What it does |
+|---------|-------------|
+| `prepare` | Verifies checkout, recommends version, updates `History.md` and `lib/puma/const.rb`, opens release PR, creates draft GitHub release on a `vX.Y.Z-proposal` tag |
+| `build` | Creates and pushes the final `vX.Y.Z` tag, builds MRI and JRuby gems |
+| `github` | Promotes draft release to final, uploads gem artifacts, publishes |
+| `run` | Detects current stage and runs the right command |
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--repo-dir PATH` | Path to the Puma checkout |
+| `--base-branch BRANCH` | Base branch for the release (default: current git branch) |
+| `--release-repo OWNER/REPO` | Repo for writes (branches, tags, PRs, releases) |
+| `--metadata-repo OWNER/REPO` | Repo for CI and commit metadata. Defaults to `puma/puma` |
+| `--live` | Allow writes to the metadata repo for a real release |
+| `--skip-ci-check` | Skip CI check during `prepare` |
+| `--allow-unknown-ci` | Continue when GitHub can't report CI state for `HEAD` |
+| `--changelog-backend auto\|agent\|communique` | Changelog generation backend |
+| `--codename NAME` | Set the release codename directly |
+| `-y`, `--yes` | Skip interactive confirmations |
+| `--debug` | Enable debug logging |
+
+## Environment
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_CMD` | AI agent command. Defaults to `claude`. Set to `pi` to use pi with `--thinking xhigh` |
+
+## Safety model
+
+Writes are fork-first by default:
+
+- `metadata_repo` is read-only (CI checks, commit links, PR metadata).
+- `release_repo` is where writes go (branches, tags, PRs, releases).
+- Without `--live`, `puma-release` prefers your authenticated fork, then a non-upstream `origin`. If it can't find a plausible fork, it refuses writes unless you pass `--release-repo` or `--live`.
+- Writing to `puma/puma` requires `--live`.
+- In live mode, every mutating git command and GitHub write shows the exact command and asks for confirmation unless you pass `--yes`.
+- `prepare` uses a `vX.Y.Z-proposal` tag for the draft; the real `vX.Y.Z` tag is only created during `build`.
+
+## Development
+
+```sh
+bundle exec rake test
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/puma-release

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "puma_release"
+
+PumaRelease::CLI.new(ARGV, env: ENV).run

data/lib/puma_release/agent_client.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PumaRelease
+  class AgentClient
+    attr_reader :context, :last_model_name
+
+    def initialize(context)
+      @context = context
+    end
+
+    def ask_for_json(prompt, system_prompt:, schema:)
+      @last_model_name = nil
+      payload = if pi?
+        ask_pi_for_json(prompt, system_prompt:, schema:)
+      else
+        ask_claude_for_json(prompt, system_prompt:, schema:)
+      end
+      payload = JSON.parse(payload) if payload.is_a?(String)
+      payload
+    rescue JSON::ParserError => e
+      raise Error, "#{context.agent_cmd} returned invalid JSON: #{e.message}"
+    end
+
+    def ask_for_text(prompt, system_prompt:)
+      return context.shell.stream_output(*pi_command(prompt, system_prompt:)).strip if pi?
+
+      context.shell.stream_output(*claude_command(system_prompt:), stdin_data: prompt).strip
+    end
+
+    private
+
+    def pi?
+      File.basename(context.shell.split(context.agent_cmd).first.to_s) == "pi"
+    end
+
+    def ask_pi_for_json(prompt, system_prompt:, schema:)
+      payload = nil
+      progress = {ticks: 0, shown: false}
+
+      context.shell.stream_json_events(*pi_command(json_prompt(prompt, schema), system_prompt:, mode: "json")) do |event|
+        case event["type"]
+        when "message_update", "tool_execution_update"
+          tick_structured_progress(progress)
+        when "message_end"
+          next unless event.dig("message", "role") == "assistant"
+
+          @last_model_name ||= extract_model_name(event.fetch("message"))
+          payload = extract_text_from_message(event.fetch("message"))
+        end
+      end
+
+      payload || raise(Error, "#{context.agent_cmd} returned no JSON payload")
+    ensure
+      finish_structured_progress(progress)
+    end
+
+    def pi_command(prompt, system_prompt:, mode: nil)
+      command = context.shell.split(context.agent_cmd) + [
+        "-p",
+        "--thinking", "xhigh",
+        "--tools", "read,bash",
+        "--no-extensions",
+        "--extension", pi_guard_extension_path,
+        "--no-skills",
+        "--no-prompt-templates",
+        "--no-themes",
+        "--system-prompt", system_prompt
+      ]
+      command += ["--mode", mode] if mode
+      command + [prompt]
+    end
+
+    def json_prompt(prompt, schema)
+      <<~PROMPT
+        #{prompt}
+
+        Return only valid JSON matching this schema:
+        #{JSON.pretty_generate(schema)}
+      PROMPT
+    end
+
+    def pi_guard_extension_path
+      File.expand_path("../../config/pi-agent-guard.ts", __dir__)
+    end
+
+    def extract_text_from_message(message)
+      text_content = Array(message.fetch("content", [])).select { |content| content["type"] == "text" }
+      final_answer = text_content.select { |content| text_signature_phase(content["textSignature"]) == "final_answer" }
+      payload = if final_answer.empty?
+        text_content.rfind { |content| !content["text"].to_s.strip.empty? }.to_h["text"]
+      else
+        final_answer.map { |content| content["text"] }.join
+      end
+      payload.to_s
+    end
+
+    def text_signature_phase(signature)
+      return nil if signature.to_s.empty?
+
+      JSON.parse(signature).fetch("phase", nil)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def extract_model_name(payload)
+      return context.comment_author_model_name unless payload
+
+      model = payload["model"].to_s.strip
+      provider = payload["provider"].to_s.strip
+      return "#{provider}/#{model}" unless provider.empty? || model.empty?
+      return model unless model.empty?
+
+      context.comment_author_model_name
+    end
+
+    def tick_structured_progress(progress)
+      progress[:ticks] += 1
+      return unless progress[:ticks] == 1 || (progress[:ticks] % 25).zero?
+
+      $stdout.print(".")
+      $stdout.flush
+      progress[:shown] = true
+    end
+
+    def finish_structured_progress(progress)
+      return unless progress[:shown]
+
+      $stdout.puts
+    end
+
+    def ask_claude_for_json(prompt, system_prompt:, schema:)
+      payload = nil
+      context.shell.stream_json_events(*claude_command(system_prompt:, schema:), stdin_data: prompt) do |event|
+        @last_model_name ||= extract_model_name(event["message"] || event)
+        case event["type"]
+        when "assistant"
+          Array(event.dig("message", "content")).each do |content|
+            next unless content["type"] == "text"
+            $stdout.print(content["text"])
+            $stdout.flush
+          end
+        when "result"
+          payload = event["structured_output"] || JSON.parse(event.fetch("result"))
+        end
+      end
+      payload
+    end
+
+    def claude_command(system_prompt:, schema: nil)
+      command = context.shell.split(context.agent_cmd) + [
+        "-p",
+        "--allowedTools", "",
+        "--permission-mode", "bypassPermissions",
+        "--system-prompt", system_prompt
+      ]
+      return command unless schema
+
+      command + ["--output-format", "stream-json", "--json-schema", JSON.generate(schema)]
+    end
+  end
+end

data/lib/puma_release/build_support.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class BuildSupport
+    attr_reader :context
+
+    def initialize(context)
+      @context = context
+    end
+
+    def build_jruby_gem(version)
+      return build_with_mise(version) if context.shell.available?("mise")
+      return build_with_local_jruby(version) if context.shell.available?("jruby")
+
+      false
+    end
+
+    private
+
+    def build_with_mise(version)
+      jruby_version = latest_jruby_version
+      return build_with_local_jruby(version) if jruby_version.nil? && context.shell.available?("jruby")
+      return false if jruby_version.nil?
+
+      context.ui.info("Building JRuby gem with mise and jruby@#{jruby_version}...")
+      context.shell.run("mise", "exec", "jruby@#{jruby_version}", "--", "bundle", "exec", "rake", "java", "gem")
+      context.ui.info("Built: pkg/puma-#{version}-java.gem")
+      true
+    end
+
+    def build_with_local_jruby(version)
+      context.ui.info("Building JRuby gem with local jruby...")
+      context.shell.run("jruby", "-S", "bundle", "exec", "rake", "java", "gem")
+      context.ui.info("Built: pkg/puma-#{version}-java.gem")
+      true
+    end
+
+    def latest_jruby_version
+      result = context.shell.run("mise", "latest", "jruby", allow_failure: true)
+      return result.stdout.strip if result.success? && !result.stdout.strip.empty?
+
+      context.ui.warn("mise could not determine a JRuby version.")
+      nil
+    end
+  end
+end

data/lib/puma_release/changelog_generator.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class ChangelogGenerator
+    SYSTEM_PROMPT = <<~PROMPT.strip
+      Draft a Puma release changelog as structured data.
+      Use only these categories: Features, Bugfixes, Performance, Refactor, Docs, CI,
+      Breaking changes.
+      Rules:
+      - Only include categories that have entries.
+      - Every entry must have at least one PR number.
+      - Keep descriptions concise and user-facing.
+      - Omit purely internal noise unless it represents meaningful test infrastructure work.
+      - Prefer combining closely related PRs into one entry when appropriate.
+    PROMPT
+
+    SCHEMA = {
+      type: "object",
+      required: ["entries"],
+      additionalProperties: false,
+      properties: {
+        entries: {
+          type: "array",
+          minItems: 1,
+          items: {
+            type: "object",
+            required: %w[category description pr_numbers],
+            additionalProperties: false,
+            properties: {
+              category: {
+                type: "string",
+                enum: ["Features", "Bugfixes", "Performance", "Refactor", "Docs", "CI", "Breaking changes"]
+              },
+              description: {type: "string", minLength: 1},
+              pr_numbers: {
+                type: "array",
+                minItems: 1,
+                items: {type: "integer", minimum: 1}
+              }
+            }
+          }
+        }
+      }
+    }.freeze
+
+    attr_reader :context, :release_range, :new_tag, :last_tag
+
+    def initialize(context, release_range, new_tag:, last_tag:)
+      @context = context
+      @release_range = release_range
+      @new_tag = new_tag
+      @last_tag = last_tag
+    end
+
+    def call
+      resolved = backend
+      context.ui.info("Changelog backend: #{resolved.class.name.split("::").last.delete_suffix("Backend").downcase}")
+      5.times do |index|
+        context.ui.info("Generating changelog (attempt #{index + 1}/5)...")
+        changelog = resolved.call.strip
+        errors = validator.validate(changelog)
+        return changelog if errors.empty?
+
+        context.ui.warn("Generated changelog did not match the required format:")
+        errors.each { |message| context.ui.warn(message) }
+      end
+      raise Error, "Could not generate a valid changelog after 5 attempts."
+    end
+
+    private
+
+    def backend
+      preferred = context.changelog_backend
+      return CommuniqueBackend.new(context, new_tag, last_tag) if preferred == "communique"
+      return AgentBackend.new(context, release_range, new_tag, last_tag) if preferred == "agent"
+      return CommuniqueBackend.new(context, new_tag, last_tag) if communique_available?
+
+      AgentBackend.new(context, release_range, new_tag, last_tag)
+    end
+
+    def communique_available?
+      context.shell.available?("communique") && !context.env.fetch("ANTHROPIC_API_KEY", "").empty?
+    end
+
+    def validator = @validator ||= ChangelogValidator.new
+
+    class AgentBackend
+      def initialize(context, release_range, new_tag, last_tag)
+        @context = context
+        @release_range = release_range
+        @new_tag = new_tag
+        @last_tag = last_tag
+      end
+
+      def call
+        context.ui.info("Asking #{context.agent_cmd} to draft changelog entries...")
+        payload = agent.ask_for_json(prompt, system_prompt: SYSTEM_PROMPT, schema: SCHEMA)
+        context.ui.info("Rendering changelog...")
+        render(payload.fetch("entries"))
+      end
+
+      private
+
+      CATEGORY_ORDER = ["Features", "Bugfixes", "Performance", "Refactor", "Docs", "CI", "Breaking changes"].freeze
+
+      attr_reader :context, :release_range, :new_tag, :last_tag
+
+      def prompt
+        <<~PROMPT
+          Draft the changelog entries for #{new_tag} from #{last_tag}..HEAD.
+
+          Return JSON only.
+          Each entry must include:
+          - category: one of the allowed categories
+          - description: concise release-note text with no PR refs in the text
+          - pr_numbers: an array of GitHub PR numbers supporting the entry
+
+          #{release_range.to_prompt_context}
+        PROMPT
+      end
+
+      def render(entries)
+        grouped = entries.group_by { |entry| entry.fetch("category") }
+        CATEGORY_ORDER.filter_map do |category|
+          next if grouped[category].to_a.empty?
+
+          (["* #{category}"] + grouped.fetch(category).map { |entry| render_entry(entry) }).join("\n")
+        end.join("\n\n")
+      end
+
+      def render_entry(entry)
+        pr_refs = entry.fetch("pr_numbers").uniq.map { |number| "[#" + number.to_s + "]" }
+        description = entry.fetch("description").strip.gsub(/\s+/, " ").sub(/[.。]\z/, "")
+        "  * #{description} (#{pr_refs.join(", ")})"
+      end
+
+      def agent = @agent ||= AgentClient.new(context)
+    end
+
+    class CommuniqueBackend
+      CONFIG = File.expand_path("../../config/communique.toml", __dir__)
+
+      def initialize(context, new_tag, last_tag)
+        @context = context
+        @new_tag = new_tag
+        @last_tag = last_tag
+      end
+
+      def call
+        result = context.shell.run(
+          "communique", "generate", new_tag, last_tag,
+          "--concise", "--dry-run", "--config", CONFIG,
+          env_overrides: github_env,
+          allow_failure: true
+        )
+        raise Error, "communique failed. Is ANTHROPIC_API_KEY set?" unless result.success?
+
+        result.stdout
+      end
+
+      private
+
+      attr_reader :context, :new_tag, :last_tag
+
+      def github_env
+        token = context.github_token
+        token.empty? ? {} : {"GITHUB_TOKEN" => token}
+      end
+    end
+  end
+end

data/lib/puma_release/changelog_validator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module PumaRelease
+  class ChangelogValidator
+    CATEGORY_ORDER = {
+      "Features" => 1,
+      "Bugfixes" => 2,
+      "Performance" => 3,
+      "Refactor" => 4,
+      "Docs" => 5,
+      "CI" => 6,
+      "Breaking changes" => 7
+    }.freeze
+
+    CATEGORY_REGEX = /^\* (#{Regexp.union(CATEGORY_ORDER.keys).source})$/
+    ITEM_REGEX = /^  \* .+ \(\[#(\d+)\](, \[#(\d+)\])*\)$/
+    INLINE_LINK_REGEX = /\[[^\]]+\]\(/
+
+    def validate(changelog)
+      state = :category
+      current_category = nil
+      last_order = 0
+      counts = {categories: 0, items: 0}
+      seen = {}
+      errors = []
+
+      changelog.each_line(chomp: true).with_index(1) do |raw_line, line_number|
+        line = raw_line.delete_suffix("\r")
+        handle_line(line, line_number, state, current_category, last_order, counts, seen, errors)
+        state, current_category, last_order = transition(line, state, current_category, last_order, seen)
+      end
+
+      errors << "Line #{changelog.lines.count}: category '* #{current_category}' must contain at least one item." if state == :item
+      errors << "Changelog must contain at least one category." if counts.fetch(:categories).zero?
+      errors << "Changelog must contain at least one changelog item." if counts.fetch(:items).zero?
+      errors
+    end
+
+    private
+
+    def handle_line(line, line_number, state, current_category, last_order, counts, seen, errors)
+      if line.empty?
+        errors << "Line #{line_number}: category '* #{current_category}' must contain at least one item." if state == :item
+        return
+      end
+      return errors << "Line #{line_number}: headings are not allowed in the changelog body." if line.start_with?("#")
+      return handle_category(line, line_number, state, current_category, last_order, counts, seen, errors) if line.match?(CATEGORY_REGEX)
+
+      errors << "Line #{line_number}: inline markdown links are not allowed; use reference-style PR refs like ([#123])." if line.match?(INLINE_LINK_REGEX)
+      return handle_item(line, line_number, state, counts, errors) if line.match?(ITEM_REGEX)
+
+      errors << if line.start_with?("*")
+        "Line #{line_number}: unsupported category. Allowed categories: #{CATEGORY_ORDER.keys.join(", ")}."
+      else
+        "Line #{line_number}: unexpected content. Expected a category heading or an item like '  * Description ([#123])'."
+      end
+    end
+
+    def handle_category(line, line_number, state, current_category, last_order, counts, seen, errors)
+      category = line.match(CATEGORY_REGEX)[1]
+      order = CATEGORY_ORDER.fetch(category)
+      errors << "Line #{line_number}: category '* #{current_category}' must contain at least one item before the next category." if state == :item
+      errors << "Line #{line_number}: blank line required between categories." if state == :item_or_blank
+      errors << "Line #{line_number}: categories must appear in this order: #{CATEGORY_ORDER.keys.join(", ")}." if order < last_order
+      errors << "Line #{line_number}: duplicate category '* #{category}'." if seen[category]
+      counts[:categories] += 1
+    end
+
+    def handle_item(line, line_number, state, counts, errors)
+      errors << "Line #{line_number}: changelog items must appear under a category heading." unless %i[item item_or_blank].include?(state)
+      counts[:items] += 1
+    end
+
+    def transition(line, state, current_category, last_order, seen)
+      return [:category, current_category, last_order] if line.empty? && %i[item item_or_blank].include?(state)
+      return [state, current_category, last_order] if line.empty? || line.start_with?("#")
+      return [:item_or_blank, current_category, last_order] if line.match?(ITEM_REGEX)
+      return [state, current_category, last_order] unless (match = line.match(CATEGORY_REGEX))
+
+      current_category = match[1]
+      seen[current_category] = true
+      [:item, current_category, CATEGORY_ORDER.fetch(current_category)]
+    end
+  end
+end